diff --git a/README.md b/README.md
index 9405342..117349f 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,19 @@ Ralph is a minimal, file-based agent loop for autonomous coding. Each iteration
 - Git
 - An AI agent: [Claude Code](https://claude.ai/download), [Codex](https://github.com/openai/codex), or [Droid](https://factory.ai)
 
+#### Windows Users
+
+Ralph requires a bash shell. Choose one:
+
+| Option | Best For | Install |
+|--------|----------|---------|
+| **WSL 2** (Recommended) | Full compatibility | `wsl --install` in PowerShell (Admin) |
+| **Git Bash** | Lightweight | [git-scm.com/download/win](https://git-scm.com/download/win) |
+
+Run Ralph commands from Git Bash or WSL terminal, not CMD.exe or PowerShell.
+
+See **[Windows Setup Guide](documentation/WINDOWS_SETUP.md)** for detailed instructions.
+
 ### Install Ralph
 
 ```bash
diff --git a/documentation/WINDOWS_IMPROVEMENTS.md b/documentation/WINDOWS_IMPROVEMENTS.md
new file mode 100644
index 0000000..6e8f948
--- /dev/null
+++ b/documentation/WINDOWS_IMPROVEMENTS.md
@@ -0,0 +1,384 @@
+# Windows Installation Improvements Proposal
+
+This document outlines proposed improvements to make Ralph CLI installation and usage easier for Windows users.
+
+## Current State Analysis
+
+### What Works
+- `npm install && npm link` - Works natively on Windows
+- `ralph install` - Node.js file operations work correctly
+- Path handling in JavaScript uses `path.join()` - Cross-platform compatible
+- Entry point (`bin/ralph`) already detects Windows at line 15
+
+### Critical Issues
+
+| Issue | Impact | Severity |
+|-------|--------|----------|
+| All execution logic is in bash scripts | Commands like `build`, `plan`, `prd`, `stream` fail without bash | **Critical** |
+| No Windows setup documentation | Users don't know prerequisites | **High** |
+| Unix-specific commands in scripts | `ps`, `pkill`, `sed`, `grep`, `flock` unavailable | **High** |
+| No Windows CI testing | Bugs won't be caught | **Medium** |
+| Hardcoded `/tmp/` paths | Temp file operations fail | **Medium** |
+| ANSI color codes | Display issues in CMD.exe | **Low** |
+
+---
+
+## Proposed Improvements
+
+### Phase 1: Documentation & Prerequisites (Quick Wins)
+
+**1.1 Add Windows Prerequisites Section to README.md**
+
+```markdown
+### Windows Prerequisites
+
+Ralph CLI requires a bash shell on Windows. Choose one option:
+
+**Option A: WSL 2 (Recommended)**
+- Best compatibility with Unix tools
+- Install: `wsl --install` in PowerShell (Admin)
+- Run Ralph commands inside WSL terminal
+
+**Option B: Git Bash**
+- Lighter weight, comes with Git for Windows
+- Install: https://git-scm.com/download/win
+- Run Ralph commands from Git Bash terminal
+
+**Option C: Windows Terminal + Git Bash**
+- Modern terminal experience
+- Install Windows Terminal from Microsoft Store
+- Add Git Bash as a profile
+```
+
+**1.2 Create `documentation/WINDOWS_SETUP.md`**
+
+Detailed setup guide covering:
+- WSL 2 installation and configuration
+- Git Bash setup and PATH configuration
+- Claude Code / Codex / Droid installation on Windows
+- Common issues and solutions
+- Environment variable setup
+
+**1.3 Add Windows Troubleshooting Section**
+
+```markdown
+### Windows Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `'bash' is not recognized` | Bash not in PATH | Install Git Bash or WSL |
+| `ENOENT: no such file or directory` | Path separator issues | Use Git Bash, not CMD |
+| Colors not displaying | ANSI not supported | Use Windows Terminal or Git Bash |
+| `flock: command not found` | Missing util-linux | Use WSL or skip concurrent builds |
+```
+
+---
+
+### Phase 2: Graceful Fallbacks (Medium Effort)
+
+**2.1 Add Bash Availability Check**
+
+Update `bin/ralph` to check for bash before running scripts:
+
+```javascript
+// Add to bin/ralph after line 19
+function checkBashAvailable() {
+  if (process.platform !== "win32") return true;
+
+  try {
+    const result = spawnSync("bash", ["--version"], { encoding: "utf-8" });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// Before spawning bash scripts
+if (!checkBashAvailable()) {
+  error("Bash shell not found. Ralph requires bash to run.");
+  console.log("");
+  info("Windows setup options:");
+  console.log("  1. Install Git for Windows: https://git-scm.com/download/win");
+  console.log("  2. Install WSL 2: wsl --install (in PowerShell Admin)");
+  console.log("");
+  info(`See: ${pc.cyan("https://github.com/AskTinNguyen/ralph-cli/blob/main/documentation/WINDOWS_SETUP.md")}`);
+  process.exit(1);
+}
+```
+
+**2.2 Add `ralph doctor` Windows Checks**
+
+Extend the doctor command to verify Windows requirements:
+
+```javascript
+// In lib/commands/doctor.js
+if (process.platform === "win32") {
+  checks.push({
+    name: "Bash shell",
+    check: () => {
+      const result = spawnSync("bash", ["--version"]);
+      return result.status === 0;
+    },
+    fix: "Install Git for Windows or WSL 2",
+  });
+
+  checks.push({
+    name: "Git Bash PATH",
+    check: () => process.env.PATH?.includes("Git\\bin"),
+    fix: "Add Git Bash to PATH: C:\\Program Files\\Git\\bin",
+  });
+}
+```
+
+**2.3 Fix Temp Directory Paths**
+
+Replace hardcoded `/tmp/` with cross-platform equivalent:
+
+```bash
+# In shell scripts, replace:
+# TEMP_FILE="/tmp/ralph-$$"
+# With:
+TEMP_FILE="${TMPDIR:-${TMP:-/tmp}}/ralph-$$"
+```
+
+Or better, use Node.js for temp file creation and pass paths to scripts.
+
+---
+
+### Phase 3: Windows CI Testing (Medium Effort)
+
+**3.1 Add Windows to GitHub Actions**
+
+Update `.github/workflows/ci.yml`:
+
+```yaml
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node-version: [18, 20, 22]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      # Windows-specific: Install Git Bash
+      - name: Setup Git Bash (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          # Git Bash comes with GitHub Actions Windows runners
+          echo "C:\Program Files\Git\bin" >> $GITHUB_PATH
+        shell: bash
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+        shell: bash
+```
+
+**3.2 Create Windows-Specific Test Suite**
+
+```javascript
+// tests/windows-compat.mjs
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { spawnSync } from "child_process";
+import path from "path";
+import os from "os";
+
+describe("Windows Compatibility", { skip: process.platform !== "win32" }, () => {
+  it("should detect bash availability", () => {
+    const result = spawnSync("bash", ["--version"]);
+    assert.strictEqual(result.status, 0, "Bash should be available");
+  });
+
+  it("should handle Windows paths correctly", () => {
+    const testPath = path.join(os.tmpdir(), "ralph-test");
+    assert.ok(!testPath.includes("/") || testPath.includes("\\"));
+  });
+
+  it("should run ralph help without bash", () => {
+    const result = spawnSync("node", ["bin/ralph", "help"]);
+    assert.strictEqual(result.status, 0);
+  });
+});
+```
+
+---
+
+### Phase 4: PowerShell Alternative (Higher Effort)
+
+**4.1 Create PowerShell Wrapper for Core Functions**
+
+For users who can't install bash, provide PowerShell alternatives for basic operations:
+
+```powershell
+# .agents/ralph/loop.ps1
+param(
+    [string]$Command = "build",
+    [int]$Iterations = 1
+)
+
+$ErrorActionPreference = "Stop"
+$RalphDir = Join-Path $PWD ".ralph"
+
+function Get-NextStory {
+    # Read plan.md and find next unchecked story
+    $plan = Get-Content (Join-Path $RalphDir "plan.md") -Raw
+    if ($plan -match '\[ \] (US-\d+)') {
+        return $matches[1]
+    }
+    return $null
+}
+
+# ... rest of loop implementation
+```
+
+**4.2 Hybrid Approach: Node.js Core with Optional Bash**
+
+Rewrite critical functions in Node.js that can fall back:
+
+```javascript
+// lib/loop-core.js
+class RalphLoop {
+  constructor(options) {
+    this.cwd = options.cwd;
+    this.ralphDir = path.join(this.cwd, ".ralph");
+    this.hasBash = this.checkBash();
+  }
+
+  async runIteration() {
+    if (this.hasBash) {
+      return this.runBashLoop();
+    }
+    return this.runNodeLoop();
+  }
+
+  async runNodeLoop() {
+    // Pure Node.js implementation
+    const story = await this.getNextStory();
+    if (!story) return { done: true };
+
+    await this.executeStory(story);
+    await this.markComplete(story);
+    await this.commitChanges(story);
+
+    return { done: false, story };
+  }
+}
+```
+
+---
+
+### Phase 5: Native Windows Support (Long-term)
+
+**5.1 Rewrite Shell Scripts in Node.js**
+
+The ultimate solution is rewriting bash scripts as Node.js modules:
+
+| Current File | Node.js Equivalent | Priority |
+|--------------|-------------------|----------|
+| `loop.sh` | `lib/loop.js` | High |
+| `stream.sh` | `lib/stream.js` | High |
+| `atomic-write.sh` | `lib/atomic.js` | Medium |
+| `output.sh` | Already uses `picocolors` | Done |
+| `test-ui.sh` | `lib/test-ui.js` | Low |
+
+**5.2 Use Cross-Platform Alternatives**
+
+| Unix Command | Cross-Platform Alternative |
+|--------------|---------------------------|
+| `grep` | Node.js `fs.readFileSync` + regex |
+| `sed` | Node.js string replace |
+| `ps aux` | `ps-list` npm package |
+| `pkill` | `tree-kill` npm package |
+| `flock` | `proper-lockfile` npm package |
+| `mktemp` | `os.tmpdir()` + `crypto.randomUUID()` |
+| `date +%s` | `Date.now() / 1000` |
+
+**5.3 Suggested Package Additions**
+
+```json
+{
+  "dependencies": {
+    "proper-lockfile": "^4.1.2",
+    "ps-list": "^8.1.0",
+    "tree-kill": "^1.2.2",
+    "cross-spawn": "^7.0.3"
+  }
+}
+```
+
+---
+
+## Implementation Priority
+
+| Phase | Effort | Impact | Priority |
+|-------|--------|--------|----------|
+| Phase 1: Documentation | Low | High | **P0 - Do First** |
+| Phase 2: Graceful Fallbacks | Medium | High | **P1 - Soon** |
+| Phase 3: Windows CI | Medium | Medium | **P1 - Soon** |
+| Phase 4: PowerShell Alternative | High | Medium | P2 - Nice to Have |
+| Phase 5: Native Node.js | Very High | Very High | P3 - Long-term |
+
+---
+
+## Quick Start: Minimum Viable Windows Support
+
+To get Windows users running quickly, implement these changes:
+
+1. **README.md** - Add Windows prerequisites section (30 min)
+2. **bin/ralph** - Add bash check with helpful error (1 hour)
+3. **lib/commands/doctor.js** - Add Windows checks (1 hour)
+4. **CI workflow** - Add Windows runner (30 min)
+
+Total estimated effort: ~3 hours for basic Windows support with clear error messages and documentation.
+
+---
+
+## Appendix: Windows User Journey (Current vs Improved)
+
+### Current Experience
+```
+User: npm install && npm link
+→ Success
+
+User: ralph install
+→ Success
+
+User: ralph build 5
+→ Error: 'bash' is not recognized as an internal or external command
+→ User confused, no guidance
+```
+
+### Improved Experience
+```
+User: npm install && npm link
+→ Success
+
+User: ralph doctor
+→ ✓ Node.js 20.x
+→ ✓ Git installed
+→ ✗ Bash not found
+→   Fix: Install Git for Windows or WSL 2
+→   See: documentation/WINDOWS_SETUP.md
+
+User: ralph build 5 (without bash)
+→ Error: Bash shell required
+→
+→ Windows setup options:
+→   1. Install Git for Windows: https://git-scm.com/download/win
+→   2. Install WSL 2: wsl --install (in PowerShell Admin)
+→
+→ After installing, run from Git Bash or WSL terminal.
+→ See: https://github.com/AskTinNguyen/ralph-cli/blob/main/documentation/WINDOWS_SETUP.md
+```
diff --git a/documentation/WINDOWS_SETUP.md b/documentation/WINDOWS_SETUP.md
new file mode 100644
index 0000000..f55e15d
--- /dev/null
+++ b/documentation/WINDOWS_SETUP.md
@@ -0,0 +1,246 @@
+# Windows Setup Guide
+
+This guide covers installing and running Ralph CLI on Windows.
+
+## Prerequisites
+
+Ralph CLI requires:
+- **Node.js 18+** - [Download](https://nodejs.org/)
+- **Git** - [Download](https://git-scm.com/download/win)
+- **Bash shell** - Required for script execution (see options below)
+- **An AI agent** - Claude Code, Codex, or Droid
+
+## Bash Shell Options
+
+Ralph's execution engine uses bash scripts. Choose one of these options:
+
+### Option A: WSL 2 (Recommended)
+
+Windows Subsystem for Linux provides the best compatibility.
+
+**Install WSL 2:**
+```powershell
+# Run in PowerShell as Administrator
+wsl --install
+```
+
+**After installation:**
+1. Restart your computer
+2. Ubuntu will install automatically on first boot
+3. Create a username and password when prompted
+4. Run Ralph commands inside the WSL terminal
+
+**Using Ralph with WSL:**
+```bash
+# Open WSL terminal, then:
+cd /mnt/c/Users/YourName/Projects/your-project
+ralph build 5
+```
+
+### Option B: Git Bash
+
+Git for Windows includes Git Bash, a lighter-weight option.
+
+**Install Git for Windows:**
+1. Download from https://git-scm.com/download/win
+2. During installation, select:
+   - "Use Git and optional Unix tools from the Command Prompt"
+   - "Use Windows' default console window" or "Use MinTTY"
+3. Complete installation
+
+**Using Ralph with Git Bash:**
+1. Open Git Bash from Start Menu
+2. Navigate to your project: `cd /c/Users/YourName/Projects/your-project`
+3. Run Ralph commands: `ralph build 5`
+
+### Option C: Windows Terminal + Git Bash
+
+For the best terminal experience on Windows:
+
+1. Install Windows Terminal from Microsoft Store
+2. Install Git for Windows (Option B above)
+3. Open Windows Terminal Settings
+4. Add a new profile for Git Bash:
+   ```json
+   {
+     "name": "Git Bash",
+     "commandline": "C:\\Program Files\\Git\\bin\\bash.exe --login -i",
+     "icon": "C:\\Program Files\\Git\\mingw64\\share\\git\\git-for-windows.ico",
+     "startingDirectory": "%USERPROFILE%"
+   }
+   ```
+
+## Installation
+
+### Step 1: Install Ralph CLI
+
+```bash
+# In Git Bash or WSL terminal
+git clone https://github.com/AskTinNguyen/ralph-cli.git
+cd ralph-cli
+npm install && npm link
+```
+
+### Step 2: Verify Installation
+
+```bash
+ralph --help
+ralph doctor
+```
+
+### Step 3: Install to Your Project
+
+```bash
+cd /path/to/your-project
+ralph install
+```
+
+## Installing AI Agents on Windows
+
+### Claude Code
+
+```bash
+# In Git Bash or WSL
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+Or download the installer from https://claude.ai/download
+
+### Codex
+
+```bash
+npm install -g @openai/codex
+```
+
+### Droid
+
+```bash
+curl -fsSL https://app.factory.ai/cli | sh
+```
+
+## Common Issues
+
+### "bash is not recognized"
+
+**Cause:** Running from CMD.exe or PowerShell without bash in PATH.
+
+**Solutions:**
+1. Run commands from Git Bash terminal instead
+2. Or add Git Bash to PATH: `C:\Program Files\Git\bin`
+3. Or use WSL terminal
+
+### "ENOENT: no such file or directory"
+
+**Cause:** Path separator issues or file not found.
+
+**Solutions:**
+1. Use forward slashes in paths: `/c/Users/...` not `C:\Users\...`
+2. Ensure you're in the correct directory
+3. Run `ralph doctor` to check setup
+
+### Colors Not Displaying
+
+**Cause:** ANSI escape codes not supported in CMD.exe.
+
+**Solutions:**
+1. Use Git Bash or Windows Terminal
+2. Or set environment variable: `FORCE_COLOR=1`
+
+### "flock: command not found"
+
+**Cause:** `flock` is Linux-specific, not available in Git Bash.
+
+**Impact:** Concurrent stream builds may have race conditions.
+
+**Solutions:**
+1. Use WSL for full compatibility
+2. Or run one build at a time (avoid `ralph stream build 1 & ralph stream build 2 &`)
+
+### "sed: invalid option"
+
+**Cause:** Git Bash uses MinGW sed which has different options than GNU sed.
+
+**Solutions:**
+1. Use WSL for full GNU tool compatibility
+2. Most Ralph operations work fine, but some edge cases may fail
+
+### Permission Denied Errors
+
+**Cause:** Windows file locking or antivirus interference.
+
+**Solutions:**
+1. Run terminal as Administrator
+2. Add project folder to antivirus exclusions
+3. Close other programs that might lock files
+
+## Environment Variables
+
+Set these in your shell profile (`~/.bashrc` for Git Bash or `~/.bashrc` for WSL):
+
+```bash
+# Optional: Set default agent
+export DEFAULT_AGENT=claude
+
+# Optional: GitHub token for MCP integrations
+export GITHUB_TOKEN=your_token_here
+
+# Optional: Notion integration
+export NOTION_API_KEY=your_key_here
+```
+
+## Path Considerations
+
+| Terminal | Project Path Format |
+|----------|-------------------|
+| Git Bash | `/c/Users/Name/Projects/myapp` |
+| WSL | `/mnt/c/Users/Name/Projects/myapp` |
+| CMD/PowerShell | `C:\Users\Name\Projects\myapp` |
+
+**Tip:** Keep your projects in a path without spaces to avoid issues.
+
+## Performance Tips
+
+1. **Use WSL 2** for best performance with file-heavy operations
+2. **Store projects in WSL filesystem** (`~/projects/`) rather than `/mnt/c/` for faster I/O
+3. **Exclude node_modules** from Windows Defender real-time scanning
+4. **Use SSD storage** for project directories
+
+## Verifying Your Setup
+
+Run these commands to verify everything is working:
+
+```bash
+# Check Ralph installation
+ralph --version
+
+# Run diagnostics
+ralph doctor
+
+# Test basic functionality
+cd your-project
+ralph install
+ralph help
+```
+
+Expected output from `ralph doctor`:
+```
+Ralph Doctor
+============
+✓ Node.js 20.x
+✓ Git 2.x
+✓ Bash available
+✓ AI agent (claude) found
+✓ Templates installed
+```
+
+## Getting Help
+
+- **GitHub Issues:** https://github.com/AskTinNguyen/ralph-cli/issues
+- **Documentation:** https://asktinnguyen.github.io/ralph-cli/
+- **Discord:** (if available)
+
+When reporting Windows-specific issues, please include:
+- Windows version (`winver`)
+- Terminal used (Git Bash, WSL, etc.)
+- Output of `ralph doctor`
+- Full error message