rafcode 1.3.2 → 2.1.0

package/RAF/ahrren-turbo-finder/outcomes/02-medium-effort-do.md

@@ -0,0 +1,34 @@
+# Outcome: Set medium reasoning effort for `raf do` execution
+
+## Summary
+
+Configured `raf do` to spawn Claude CLI processes with `CLAUDE_CODE_EFFORT_LEVEL=medium` environment variable, reducing reasoning overhead during automated task execution while preserving default (high) effort for interactive planning sessions.
+
+## Key Changes
+
+### `src/core/claude-runner.ts`
+- Added optional `effortLevel` field (`'low' | 'medium' | 'high'`) to `ClaudeRunnerOptions` interface
+- In `run()`: when `effortLevel` is set, spreads `process.env` with `CLAUDE_CODE_EFFORT_LEVEL` override; otherwise passes `process.env` directly
+- In `runVerbose()`: same env injection logic as `run()`
+- `runInteractive()` is unchanged — uses `process.env` as-is (no effort override for planning sessions)
+
+### `src/commands/do.ts`
+- Passes `effortLevel: 'medium'` in both `claudeRunner.run()` and `claudeRunner.runVerbose()` calls during task execution
+
+### `tests/unit/claude-runner.test.ts`
+- Added 6 tests in new `effort level` describe block:
+  - Verifies `CLAUDE_CODE_EFFORT_LEVEL` is set in env for `run()` when effortLevel provided
+  - Verifies `CLAUDE_CODE_EFFORT_LEVEL` is set in env for `runVerbose()` when effortLevel provided
+  - Verifies env is `process.env` directly (no override) when effortLevel not provided in `run()`
+  - Verifies env is `process.env` directly (no override) when effortLevel not provided in `runVerbose()`
+  - Verifies all three levels (low, medium, high) work correctly
+  - Verifies other env vars (e.g., PATH) are preserved when effortLevel is set
+
+### `tests/unit/claude-runner-interactive.test.ts`
+- Added 1 test verifying `runInteractive()` does NOT set `CLAUDE_CODE_EFFORT_LEVEL` in its env
+
+## Test Results
+
+All 45 test suites pass (978 tests total, 0 failures).
+
+<promise>COMPLETE</promise>

package/RAF/ahrren-turbo-finder/plans/01-worktree-auto-detect.md

@@ -0,0 +1,44 @@
+# Task: Auto-detect worktree projects in `raf do`
+
+## Objective
+Make `raf do <name>` and `raf do <id>` automatically find and run worktree projects without requiring the `--worktree` flag.
+
+## Context
+Currently, `raf do <identifier>` without `--worktree` only searches the main repo's RAF directory. If a project lives exclusively in a worktree (or the user simply omits the flag), the command fails with "project not found". The worktree folder name matches the project folder name (e.g., `~/.raf/worktrees/<repo>/ahrren-turbo-finder/`), so resolution can leverage this naming convention.
+
+When a worktree project is auto-detected, the full worktree flow should activate — including the post-execution action picker (merge/PR/leave), worktree cwd, and cleanup behavior — exactly as if `--worktree` had been passed.
+
+## Requirements
+- When `raf do <name>` (e.g., `turbo-finder`) doesn't find the project in the main repo, fall back to searching worktree directories
+- When `raf do <id>` (e.g., `ahrren`) doesn't find the project in the main repo, fall back to searching worktree directories
+- When `raf do <full-folder>` (e.g., `ahrren-turbo-finder`) doesn't find the project in the main repo, fall back to searching worktree directories
+- Use the worktree folder naming convention: worktree folders at `~/.raf/worktrees/<repo-basename>/<project-folder>/` where `<project-folder>` matches the project folder name format (`XXXXXX-name`)
+- Match identifiers against worktree folder names using the same resolution logic as `resolveProjectIdentifierWithDetails` (full name, base26 ID, or project name)
+- When a worktree project is auto-detected, enable the full worktree mode: set `worktreeMode = true`, `worktreeRoot`, `originalBranch`, and trigger the post-execution action picker
+- If project exists in both main repo and worktree, prefer the worktree version (consistent with existing picker deduplication behavior)
+
+## Implementation Steps
+1. In `runDoCommand()` in `src/commands/do.ts`, modify the non-worktree resolution path (currently around line 305) to add a worktree fallback
+2. After `resolveProjectIdentifierWithDetails(rafDir, projectIdentifier)` fails (returns no path), check if the current directory is a git repo
+3. If in a git repo, use `listWorktreeProjects(repoBasename)` to get worktree project folders
+4. For each worktree folder, attempt to match the identifier using the same resolution strategy: full folder name match, base26 prefix match, or name-portion match
+5. If a match is found, set `worktreeMode = true`, compute `worktreeRoot`, record `originalBranch`, and proceed through the existing worktree validation and execution flow
+6. Consider also checking worktrees FIRST (before main repo) or in parallel, to match the picker behavior where worktree versions take priority over main repo versions
+7. Add unit tests for the new auto-detection logic
+8. Add integration-level tests verifying the full flow (identifier → worktree detection → worktree mode enabled)
+
+## Acceptance Criteria
+- [ ] `raf do turbo-finder` finds and runs a worktree project named `ahrren-turbo-finder`
+- [ ] `raf do ahrren` finds and runs a worktree project with ID `ahrren`
+- [ ] `raf do ahrren-turbo-finder` finds and runs the worktree project by full folder name
+- [ ] Auto-detected worktree projects trigger the post-execution action picker (merge/PR/leave)
+- [ ] Auto-detected worktree projects execute with the worktree as cwd
+- [ ] If project exists in both main and worktree, worktree version is preferred
+- [ ] Existing `--worktree` flag behavior is unchanged
+- [ ] All existing tests pass
+- [ ] New tests cover the auto-detection scenarios
+
+## Notes
+- The existing worktree resolution code (lines 240-304 in `do.ts`) already handles the case where `--worktree` is passed. The new code should reuse as much of that logic as possible rather than duplicating it.
+- `listWorktreeProjects()` from `src/core/worktree.ts` returns sorted folder names. Resolution against these can use string matching without needing filesystem reads into each worktree's RAF dir.
+- Be careful with the `projectFolderName` variable scoping — it's currently declared inside the worktree block and needs to be accessible when auto-detection sets worktree mode.

package/RAF/ahrren-turbo-finder/plans/02-medium-effort-do.md

@@ -0,0 +1,39 @@
+# Task: Set medium reasoning effort for `raf do` execution
+
+## Objective
+Configure `raf do` to spawn Claude CLI processes with `CLAUDE_CODE_EFFORT_LEVEL=medium` to reduce reasoning overhead during task execution.
+
+## Dependencies
+01
+
+## Context
+By default, Claude Opus uses "high" effort level which allocates more thinking tokens. For automated task execution via `raf do`, medium effort provides a good balance of speed, cost, and capability. The `CLAUDE_CODE_EFFORT_LEVEL` environment variable is the supported mechanism for controlling this in the Claude Code CLI.
+
+RAF's `ClaudeRunner` already passes `process.env` to spawned processes (lines 296, 400, 512 in `claude-runner.ts`). The change needs to inject `CLAUDE_CODE_EFFORT_LEVEL=medium` into the environment for non-interactive (task execution) runs, while leaving interactive planning sessions (`raf plan`) at default effort.
+
+## Requirements
+- Set `CLAUDE_CODE_EFFORT_LEVEL=medium` in the environment when spawning Claude processes for `raf do` task execution
+- Do NOT affect `raf plan` (interactive planning sessions should keep default/high effort)
+- Do NOT affect failure analysis (which uses Haiku via `ClaudeRunner`)
+- The effort level should be configurable through `ClaudeRunnerOptions` or `ClaudeRunnerConfig` so it's not hardcoded deep in the runner
+- Pass the env var by spreading it into the `env` object passed to `spawn()` and `pty.spawn()`
+
+## Implementation Steps
+1. Add an optional `effortLevel` field to `ClaudeRunnerOptions` or `ClaudeRunnerConfig` in `src/core/claude-runner.ts`
+2. In the `run()` and `runVerbose()` methods, merge `CLAUDE_CODE_EFFORT_LEVEL` into the environment when `effortLevel` is set
+3. In `src/commands/do.ts`, pass `effortLevel: 'medium'` when constructing or calling `ClaudeRunner` for task execution
+4. Ensure the interactive `runInteractive()` method does NOT apply the effort override (planning should stay at default)
+5. Add tests verifying the env var is passed correctly
+6. Add tests verifying that planning mode does not get the env var
+
+## Acceptance Criteria
+- [ ] `raf do` spawns Claude with `CLAUDE_CODE_EFFORT_LEVEL=medium` in the environment
+- [ ] `raf plan` does NOT set `CLAUDE_CODE_EFFORT_LEVEL` (uses default behavior)
+- [ ] The effort level is configurable (not hardcoded in the spawn call)
+- [ ] Existing tests pass
+- [ ] New tests verify the env var injection
+
+## Notes
+- The three spawn points in `claude-runner.ts` are: `pty.spawn()` at line 291 (interactive), `spawn()` at line 390 (non-interactive), and `spawn()` at line 499 (verbose). Only the non-interactive and verbose spawns should get the effort override.
+- The env var `CLAUDE_CODE_EFFORT_LEVEL` is confirmed as the correct name per official docs at code.claude.com/docs/en/model-config. Note: there is a known UI bug (GitHub issue #23604) where the `/model` UI always shows "High effort" regardless of the env var, but the env var is believed to still affect actual API requests.
+- An alternative approach (if the env var turns out to be truly broken) would be to write `"effortLevel": "medium"` to a `.claude/settings.json` in the working directory before spawning Claude. This is a fallback, not the primary approach.

package/RAF/ahrtxf-session-sentinel/decisions.md

@@ -0,0 +1,19 @@
+# Project Decisions
+
+## What's the main use case for logging the session ID?
+Resume interrupted sessions. Capture session ID so RAF can attempt to resume interrupted Claude sessions using `claude --resume <id>`, and also allow manual inspection. Add `raf do <project> --resume <session-id>` flag for resuming after Ctrl+C interruption.
+
+## Should the session ID be captured in all execution modes?
+Verbose + non-interactive. Both modes that run tasks should capture session ID. Interactive planning mode can be skipped.
+
+## When a session is interrupted, should the session ID be displayed to the user?
+Print to terminal. Display session ID in terminal output on interruption so user can copy it for `--resume`.
+
+## For `raf do --resume`, should it resume the exact interrupted task or restart from scratch?
+Resume exact task. Pass `--resume` to Claude CLI for the specific interrupted task, continuing from where Claude left off mid-task. Add metadata (task ID) to support this. Format could be `--resume <task-id>:<session-id>` or assume it's the last unfinished task.
+
+## How should non-interactive mode get access to the session ID?
+Always use `--output-format stream-json` for both verbose and non-interactive modes. Parse the init event to capture session_id. Only render/display the stream output when `--verbose` flag is passed. This gives us session IDs universally without changing user-visible behavior.
+
+## When resuming, should RAF pass the original task's system prompt again?
+Rely on session state. Trust that Claude's `--resume` restores the full context including the original prompt. Don't re-send system prompt or task context.

package/RAF/ahrtxf-session-sentinel/input.md

@@ -0,0 +1 @@
+check if it's possible to log claude session id if session got interrupted

package/RAF/ahrtxf-session-sentinel/outcomes/01-capture-session-id.md

@@ -0,0 +1,37 @@
+# Outcome: Capture Session ID from Claude CLI Output
+
+## Summary
+
+Implemented session ID extraction from Claude CLI's `system.init` NDJSON event in both `run()` and `runVerbose()` methods. The session ID is now captured, returned in `RunResult`, and printed to the terminal on interruption.
+
+## Key Changes
+
+### `src/parsers/stream-renderer.ts`
+- Added `session_id` field to `StreamEvent` interface
+- Added `sessionId` field to `RenderResult` interface
+- Modified `renderStreamEvent()` to extract and return `session_id` from system init events
+
+### `src/core/claude-runner.ts`
+- Added `sessionId?: string` field to `RunResult` interface
+- Added `_sessionId` private field and public `sessionId` getter to `ClaudeRunner` class
+- Refactored `run()` to use `--output-format stream-json --verbose` with silent NDJSON parsing (no stdout display), enabling session ID extraction
+- Updated `runVerbose()` to capture `sessionId` from stream events
+- Both methods return `sessionId` in `RunResult`
+- Session ID is printed via `logger.info()` on timeout and context overflow in both methods
+
+### `src/core/shutdown-handler.ts`
+- Added session ID logging in `handleShutdown()` — prints `Session ID: <id>` when a Claude session is interrupted via Ctrl+C/SIGTERM
+
+### `tests/unit/stream-renderer.test.ts`
+- Added 3 new tests: session_id extraction, undefined for missing session_id, undefined for non-system events
+
+### `tests/unit/claude-runner.test.ts`
+- Updated existing `run()` tests to emit NDJSON events (since `run()` now uses stream-json format)
+- Updated flag assertion: `run()` now includes `--output-format stream-json --verbose`
+- Added 5 new tests: sessionId extraction in run(), runVerbose(), undefined when missing, getter exposure, deduplication
+
+## Test Results
+
+All 986 tests pass (45 test suites). No regressions introduced.
+
+<promise>COMPLETE</promise>

package/RAF/ahrtxf-session-sentinel/outcomes/02-resume-flag.md

@@ -0,0 +1,45 @@
+# Outcome: Add --resume Flag to raf do Command
+
+## Summary
+
+Added `--resume <session-id>` option to `raf do` that resumes an interrupted Claude session for a specific task. When used, Claude is spawned with `--resume` flag only (no prompt/model/system-prompt flags), and completion monitoring works identically to normal execution.
+
+## Key Changes
+
+### `src/types/config.ts`
+- Added `resume?: string` field to `DoCommandOptions` interface
+
+### `src/commands/do.ts`
+- Added `-r, --resume <session-id>` option to the `do` command definition
+- Added `resumeSessionId` to `SingleProjectOptions` interface
+- In the task execution loop: when `activeResumeSessionId` is set, calls `runResume()` instead of `run()`/`runVerbose()` for the first attempt
+- Clears `activeResumeSessionId` after the first task completes, so subsequent tasks use normal execution
+- Prints clear user-facing message: `Resuming task <id> with session <session-id>` in both verbose and minimal modes
+
+### `src/core/claude-runner.ts`
+- Added `runResume(sessionId, options)` method that spawns Claude with:
+  - `--resume <session-id>` — restores the interrupted session
+  - `--dangerously-skip-permissions` — required for non-interactive operation
+  - `--output-format stream-json --verbose` — enables NDJSON event parsing
+  - Does NOT pass `--model`, `--append-system-prompt`, or `-p` (Claude restores these from session state)
+- Same completion detection, timeout handling, context overflow detection, and session ID extraction as existing methods
+
+### `tests/unit/claude-runner.test.ts`
+- Added 11 new tests in `runResume()` describe block:
+  - Spawns with `--resume` flag and session ID
+  - Does NOT include `--model`, `--append-system-prompt`, or `-p` flags
+  - Includes `--dangerously-skip-permissions` flag
+  - Includes `--output-format stream-json` and `--verbose` flags
+  - Collects output from NDJSON events
+  - Handles timeout correctly
+  - Detects completion markers
+  - Extracts session ID from resumed session
+  - Passes cwd to spawn (worktree support)
+  - Detects context overflow
+  - Sets CLAUDE_CODE_EFFORT_LEVEL env var when provided
+
+## Test Results
+
+All 997 tests pass (45 test suites). No regressions introduced.
+
+<promise>COMPLETE</promise>

package/RAF/ahrtxf-session-sentinel/plans/01-capture-session-id.md

@@ -0,0 +1,41 @@
+# Task: Capture Session ID from Claude CLI Output
+
+## Objective
+Extract and store the Claude session ID from stream-json output in both verbose and non-interactive execution modes.
+
+## Context
+Claude CLI emits a `session_id` in its `system.init` NDJSON event when using `--output-format stream-json`. RAF currently discards this event entirely. We need to capture and surface this ID so it can be used for session resumption and debugging.
+
+## Requirements
+- Unify both `run()` (non-interactive) and `runVerbose()` methods to use `--output-format stream-json` so that the system init event is always available
+- In non-verbose mode, parse NDJSON events silently (extract textContent for output accumulation and detect completion markers) without rendering anything to stdout
+- In verbose mode, continue rendering stream events to stdout as before
+- Extract `session_id` from the `system.init` event (first event in the stream)
+- Add `sessionId?: string` field to the `RunResult` type returned by both `run()` and `runVerbose()`
+- Modify `renderStreamEvent()` in `stream-renderer.ts` to return the session_id when it encounters a system init event, rather than discarding it
+- When a session is interrupted (Ctrl+C, timeout, context overflow), print the session ID to terminal: `Session ID: <id>` so the user can copy it
+- Add tests for the session ID extraction from system init events
+- Add tests verifying session ID is included in RunResult
+
+## Implementation Steps
+1. Update the `RunResult` type to include an optional `sessionId` field
+2. Modify `renderStreamEvent()` to extract and return `session_id` from system init events (add a new field to the return type, e.g. `sessionId?: string`)
+3. Refactor `run()` to use `--output-format stream-json` internally, parsing NDJSON lines the same way `runVerbose()` does, but without writing display output to stdout
+4. In both `run()` and `runVerbose()`, capture the session_id from the first system init event and include it in the returned `RunResult`
+5. In the shutdown handler and timeout/overflow paths, print the captured session ID to the terminal before exiting
+6. Write unit tests for session ID extraction from stream events
+7. Write integration-style tests verifying RunResult includes sessionId
+
+## Acceptance Criteria
+- [ ] `run()` uses stream-json format internally and parses events silently
+- [ ] `runVerbose()` continues to display stream events as before
+- [ ] Both methods return `sessionId` in `RunResult` when available
+- [ ] On interruption (Ctrl+C, timeout, overflow), session ID is printed to terminal
+- [ ] Existing tests continue to pass
+- [ ] New tests cover session ID extraction
+
+## Notes
+- The system init event format is: `{ type: 'system', subtype: 'init', session_id: string, tools: string[], model: string }`
+- Currently `stream-renderer.ts` line 96 returns `{ display: '', textContent: '' }` for all system events — this is where extraction should happen
+- The `run()` method currently uses plain text output with `child_process.spawn` — it needs to switch to stream-json parsing similar to `runVerbose()`. Consider extracting shared NDJSON parsing logic to avoid duplication.
+- Be careful: `run()` has its own completion marker detection and timeout logic that must continue to work with the new stream-json parsing

package/RAF/ahrtxf-session-sentinel/plans/02-resume-flag.md

@@ -0,0 +1,51 @@
+# Task: Add --resume Flag to raf do Command
+
+## Objective
+Add a `--resume` option to `raf do` that resumes an interrupted Claude session for a specific task.
+
+## Context
+After task 01 captures the session ID and displays it on interruption, users need a way to actually resume the interrupted session. This task adds `raf do <project> --resume <session-id>` which passes Claude CLI's `--resume` flag to continue a session from where it left off.
+
+## Dependencies
+01
+
+## Requirements
+- Add `--resume <session-id>` option to the `raf do` command in Commander.js
+- When `--resume` is provided, RAF should:
+  1. Identify the task to resume — find the first task that is in-progress (has no outcome file, or has a partial/missing completion marker)
+  2. Skip the normal task execution flow and instead spawn Claude with `--resume <session-id>` flag
+  3. Do NOT pass `-p` (prompt), `--append-system-prompt`, or `--model` flags — rely on Claude's session state to restore these
+  4. DO pass `--dangerously-skip-permissions` as it's required for non-interactive operation
+  5. Still use `--output-format stream-json` so we can capture the new session's events and detect completion
+  6. Continue monitoring for completion markers and outcome file as usual
+- After the resumed session completes, normal post-task flow should apply (outcome validation, commit verification, next task, etc.)
+- If `--resume` is used with `--worktree`, ensure the CWD is set to the worktree path
+- Print a clear message indicating which task is being resumed: `Resuming task <id> with session <session-id>`
+- Add a new method to `ClaudeRunner` (e.g. `runResume(sessionId, options)`) that spawns Claude with the `--resume` flag
+- Cover the new flag and resume method with tests
+
+## Implementation Steps
+1. Add `--resume <session-id>` option to the `do` command definition in `src/commands/do.ts`
+2. Add a `runResume()` method to `ClaudeRunner` that spawns Claude with `--resume <session-id> --dangerously-skip-permissions --output-format stream-json` and the same completion monitoring as existing methods
+3. In the task execution loop, when `--resume` is provided:
+   - Determine the current task (first task without a valid outcome)
+   - Call `runResume()` instead of the normal `run()`/`runVerbose()` method
+   - After the resumed task completes, clear the `--resume` flag so subsequent tasks use normal execution
+4. Handle edge cases: invalid session ID format, all tasks already complete, resumed session fails
+5. Write tests for the new `runResume()` method
+6. Write tests for the `--resume` flag integration in the do command
+
+## Acceptance Criteria
+- [ ] `raf do <project> --resume <session-id>` resumes the interrupted session
+- [ ] Claude is spawned with `--resume` flag and without prompt/model/system-prompt flags
+- [ ] Completion monitoring works the same as normal execution
+- [ ] After resumed task completes, subsequent tasks run normally
+- [ ] Works with `--worktree` mode
+- [ ] Clear user-facing message on resume start
+- [ ] Tests cover resume path
+
+## Notes
+- Claude CLI's `--resume` flag restores the full session context including the system prompt, so we must NOT pass those flags again (they may conflict or be rejected)
+- The `--resume` flag only applies to a single task — after it completes (or fails), remaining tasks use normal execution
+- Consider what happens if the user provides a session ID for a task that already completed — should gracefully handle this
+- Check Claude CLI docs/help to verify exact `--resume` flag syntax: `claude --resume <session-id>`

package/README.md

@@ -51,6 +51,7 @@ That's it! RAF will guide you through breaking down your task and then execute i
 - **Resume Support**: Continue from where you left off after interruption
 - **Git Integration**: Automatic commits after each completed task
 - **Task Dependencies**: Tasks can depend on other tasks, with automatic blocking on failure
+- **Worktree Mode**: Isolate planning and execution in a git worktree branch with `--worktree`
 
 ## Commands
 
@@ -61,7 +62,8 @@ Opens your `$EDITOR` to write a project description, then Claude will interview
 ```bash
 raf plan              # Create a new project
 raf plan my-feature   # Create with a specific name
-raf plan --amend 3    # Add tasks to existing project #3
+raf plan --amend abcdef  # Add tasks to existing project
+raf plan --worktree   # Plan in an isolated git worktree
 ```
 
 ### `raf do`
@@ -70,20 +72,31 @@ Execute project tasks. Without arguments, shows a picker to select a pending pro
 
 ```bash
 raf do                # Interactive picker
-raf do 3              # Execute project #3
+raf do abcdef         # Execute by project ID
 raf do my-project     # Execute by name
-raf do 3 4 5          # Execute multiple projects
+raf do --worktree     # Pick and execute a worktree project
+raf do my-feature -w --merge  # Execute in worktree, merge on success
 ```
 
 Note: In non-verbose mode, the completion summary reflects the tasks executed in that run (the remaining tasks at start), so the elapsed time maps to those tasks.
 
 ### `raf status`
 
-Check project status.
+Check project status. Worktree projects are discovered automatically when inside a git repo — no flag needed.
 
 ```bash
-raf status            # List all projects
-raf status 3          # Show details for project #3
+raf status            # List all projects (includes worktree projects that differ)
+raf status abcdef     # Show details for a project (shows both main and worktree if they differ)
+```
+
+### `raf migrate-project-ids-base26`
+
+Rename legacy project folders (3-char base36 or 6-char base36 with digits) to the current 6-char base26 format.
+
+```bash
+raf migrate-project-ids-base26             # Migrate project folders in ./RAF/
+raf migrate-project-ids-base26 --dry-run   # Preview renames without executing
+raf migrate-project-ids-base26 --worktree  # Migrate worktree project folders
 ```
 
 ## Status Symbols
@@ -98,20 +111,43 @@ raf status 3          # Show details for project #3
 
 ## Project Structure
 
-RAF creates a `./RAF/` folder with numbered project directories:
+RAF creates a `./RAF/` folder with project directories identified by epoch-based base26 IDs (a-z only):
 
 ```
 ./RAF/
-├── 001-auth-system/
+├── abcdef-auth-system/
 │   ├── input.md           # Your original intent (raw prompt)
 │   ├── decisions.md       # Design decisions from planning
 │   ├── plans/             # Generated task plans
 │   ├── outcomes/          # Execution results
 │   └── logs/              # Debug logs (on failure)
-└── 002-dashboard/
+└── abaaba-dashboard/
     └── ...
 ```
 
+## Worktree Mode
+
+Worktree mode runs planning and execution in an isolated git worktree, keeping your main branch clean while RAF works on a separate branch.
+
+### Basic workflow
+
+```bash
+# Plan in a worktree (creates branch and worktree directory)
+raf plan my-feature --worktree
+
+# Execute tasks in the worktree, merge back on success
+raf do my-feature --worktree --merge
+```
+
+### How it works
+
+- `--worktree` creates a git worktree at `~/.raf/worktrees/<repo>/<project>/` with a new branch named after the project folder (e.g., `abcdef-my-feature`)
+- All planning artifacts, code changes, and commits happen in the worktree branch
+- `--merge` on `raf do` merges the branch back after all tasks succeed (fast-forward preferred, merge commit as fallback)
+- On merge conflicts, the merge is aborted and you get instructions for manual resolution
+- If tasks fail, the worktree branch is preserved for inspection
+- Worktrees persist after completion — clean them up manually with `git worktree remove` when done
+
 ## Command Reference
 
 ### `raf plan [projectName]`
@@ -120,8 +156,9 @@ RAF creates a `./RAF/` folder with numbered project directories:
 |--------|-------------|
 | `--amend <id>` | Add tasks to existing project |
 | `-y, --auto` | Skip permission prompts (runs in dangerous mode) |
+| `-w, --worktree` | Create a git worktree for isolated planning |
 
-### `raf do [projects...]`
+### `raf do [project]`
 
 | Option | Description |
 |--------|-------------|
@@ -130,9 +167,18 @@ RAF creates a `./RAF/` folder with numbered project directories:
 | `-d, --debug` | Save all logs and show debug output |
 | `-m, --model <name>` | Claude model (sonnet, haiku, opus) |
 | `--sonnet` | Shorthand for `--model sonnet` |
+| `-w, --worktree` | Execute tasks in a git worktree |
+| `--merge` | Merge worktree branch after successful completion (requires `--worktree`) |
 
 Alias: `raf act`
 
+### `raf migrate-project-ids-base26`
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview renames without executing |
+| `-w, --worktree` | Migrate worktree project folders |
+
 > **Note:** `raf do` and `raf plan -y` run Claude with `--dangerously-skip-permissions` for fully automated execution without interactive prompts.
 
 ### `raf status [identifier]`

package/dist/commands/do.d.ts

@@ -1,4 +1,11 @@
 import { Command } from 'commander';
+/**
+ * Post-execution action chosen by the user before task execution begins.
+ * - 'merge': merge the worktree branch into the original branch
+ * - 'pr': push the branch and create a GitHub PR
+ * - 'leave': do nothing, keep the branch as-is
+ */
+export type PostExecutionAction = 'merge' | 'pr' | 'leave';
 /**
  * Format failure history for console output.
  * Shows attempts that failed before eventual success or final failure.
@@ -9,4 +16,12 @@ export declare function formatRetryHistoryForConsole(taskId: string, taskName: s
     reason: string;
 }>, finalAttempt: number, success: boolean): string;
 export declare function createDoCommand(): Command;
+/**
+ * Show an interactive picker for the post-execution action in worktree mode.
+ * Presented before task execution so the user declares intent upfront.
+ *
+ * If "Create PR" is chosen, runs preflight checks immediately. If preflight fails,
+ * warns the user and falls back to re-prompting.
+ */
+export declare function pickPostExecutionAction(worktreeRoot: string): Promise<PostExecutionAction>;
 //# sourceMappingURL=do.d.ts.map

package/dist/commands/do.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"do.d.ts","sourceRoot":"","sources":["../../src/commands/do.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkCpC;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,MAAM,CAkBR;AA0BD,wBAAgB,eAAe,IAAI,OAAO,CAgBzC"}
+{"version":3,"file":"do.d.ts","sourceRoot":"","sources":["../../src/commands/do.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiDpC;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,MAAM,CAkBR;AA0BD,wBAAgB,eAAe,IAAI,OAAO,CAkBzC;AAsSD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuBhG"}