rafcode 1.2.0 → 2.0.0

package/RAF/ahnbcu-letterjam/plans/03-migrate-command.md

@@ -0,0 +1,49 @@
+# Task: Add `raf migrate-project-ids-base26` CLI command
+
+## Objective
+Add a CLI command that renames existing project folders from old ID formats (3-char base36 or 6-char base36) to the new 6-char base26 encoding.
+
+## Context
+After switching to base26 encoding, existing projects on disk still have old-format IDs. The migrate command provides a clean one-time transition. It must handle two legacy formats: the original 3-char base36 sequential IDs (e.g., "007-project") and the intermediate 6-char base36 epoch IDs (e.g., "021h44-project").
+
+## Dependencies
+01
+
+## Requirements
+- New CLI command: `raf migrate-project-ids-base26`
+- Detects two legacy folder patterns:
+  - 3-char base36: `[0-9a-z]{3}-<name>` (e.g., "007-my-project", "01a-feature")
+  - 6-char base36 with digits: `[0-9a-z]{6}-<name>` where the prefix contains at least one digit (to distinguish from already-migrated base26 IDs)
+- For each legacy folder:
+  - Decode the old ID to its numeric value (base36 decode for both 3-char and 6-char formats)
+  - Re-encode as 6-char base26
+  - Rename the folder on disk
+- Handles the RAF directory in the current repo (standard location)
+- Also handles worktree RAF directories if `--worktree` flag is specified or auto-detected
+- Prints a summary of what was renamed (old name → new name)
+- Dry-run mode (`--dry-run`) to preview changes without renaming
+- Skips folders that are already in base26 format
+- Handles collisions (two old IDs mapping to same base26 ID — unlikely but should error gracefully)
+
+## Implementation Steps
+1. Create `src/commands/migrate.ts` with the migrate command handler.
+2. Add detection logic for the two legacy patterns (3-char base36 and 6-char base36-with-digits).
+3. Implement the rename operation: decode old ID → encode as base26 → rename folder.
+4. Add dry-run support.
+5. Register the command in `src/index.ts` (or wherever Commander.js commands are registered).
+6. Handle edge cases: empty RAF dir, no legacy projects, folder rename failures.
+7. Consider worktree directories — if projects live in worktree paths, the migration should find and rename those too.
+
+## Acceptance Criteria
+- [ ] `raf migrate-project-ids-base26` renames 3-char base36 project folders to base26
+- [ ] `raf migrate-project-ids-base26` renames 6-char base36 project folders to base26
+- [ ] Already-base26 folders are skipped
+- [ ] `--dry-run` shows planned renames without executing them
+- [ ] Summary output shows old → new folder names
+- [ ] Command registered and accessible via CLI
+
+## Notes
+- 3-char base36 IDs are small numbers (e.g., 7, 23) — they'll produce base26 IDs like "aaaaah", "aaaaax".
+- Base36 epoch IDs are large (seconds since 2026-01-01) — they'll produce reasonable base26 IDs.
+- Worktree branch names contain the old project ID. Branch renaming is out of scope for this task — just rename the folders.
+- The git.ts module extracts project numbers from paths — after migration, these paths will have new prefixes.

package/RAF/ahnbcu-letterjam/plans/04-update-documentation.md

@@ -0,0 +1,39 @@
+# Task: Update documentation for base26 project IDs
+
+## Objective
+Update CLAUDE.md and README.md to document the new base26 project ID encoding scheme and the migrate command.
+
+## Context
+After tasks 01-03, the codebase uses base26 for project IDs, but documentation still references base36. All developer-facing docs need updating.
+
+## Dependencies
+01, 03
+
+## Requirements
+- Update CLAUDE.md sections that reference base36 project IDs:
+  - "Project Naming Convention" section
+  - "Task ID Format" section (clarify task IDs remain base36)
+  - "Git Commit Schema" section (examples use old IDs)
+  - "RAF Project Structure" section (example folder names)
+  - Any other mentions of "base36" in the context of project IDs
+- Update README.md if it references project ID format
+- Document the `raf migrate-project-ids-base26` command in the appropriate section
+- All example project IDs in docs should use base26 format
+
+## Implementation Steps
+1. Search CLAUDE.md for all occurrences of "base36" related to project IDs and update to "base26".
+2. Update example project folder names throughout (e.g., "00j3k1-project-name" → a valid base26 example).
+3. Add documentation for the `raf migrate-project-ids-base26` command.
+4. Update README.md with any project ID format references.
+5. Ensure task ID documentation still correctly says base36.
+
+## Acceptance Criteria
+- [ ] CLAUDE.md accurately describes base26 project ID encoding
+- [ ] All example IDs in docs are valid base26 (a-z only, 6 chars)
+- [ ] `raf migrate-project-ids-base26` command is documented
+- [ ] Task ID docs correctly unchanged (still base36)
+- [ ] No stale references to base36 for project IDs remain in docs
+
+## Notes
+- Be precise about which IDs changed (project = base26) vs stayed (task = base36).
+- The encoding details matter: a=0, z=25, padded with 'a', 6 chars.

package/RAF/ahnwrk-worktree-weaver/decisions.md

@@ -0,0 +1,19 @@
+# Project Decisions
+
+## Worktree auto-discovery: when a user picks a worktree project from the regular `raf do` picker, should RAF automatically switch to worktree mode?
+Yes — auto-switch to worktree mode. Picking a worktree project automatically behaves as if `--worktree` was passed (runs in worktree path, shows post-action picker after).
+
+## What model should be used to generate PR descriptions?
+Sonnet. Better quality summaries justify the slightly higher cost.
+
+## PR description structure: Summary (from proofread input.md) → Key Decisions (from decisions.md) → What Was Done (from outcomes) → Test Plan?
+Yes, this structure works.
+
+## Should Co-Authored-By removal apply to ALL commits, or be configurable?
+Never include it. Add explicit instruction in execution prompt to not add Co-Authored-By trailers.
+
+## How should worktree projects appear in the regular `raf do` picker?
+Mixed list with label. Show all projects in one sorted list, with worktree projects marked (e.g. `abcdef my-feature (2/5 tasks) [worktree]`).
+
+## For the `\n` issue in PR descriptions: investigate or known cause?
+Investigate and fix. Find the root cause of the `\n` escaping in the PR creation pipeline.

package/RAF/ahnwrk-worktree-weaver/input.md

@@ -0,0 +1,4 @@
+- [ ] make 'raf do' to automatically check existing worktrees in ~/.raf for the repo and if there task to do - offer to do the project in the project picker that we have
+- [ ] update status of tasks in 'raf do' to from "[01] base26-encoding" to "01-base26-encoding"
+- [ ] use sonnet to summarize PR and investigate why formatting is wrong on github (no newlines displayed) /Users/eremeev/Desktop/Screenshot\ 2026-02-09\ at\ 21.10.53.png (may /n escaped and everything goes under md header). also some log got into pr description /Users/eremeev/Desktop/Screenshot\ 2026-02-09\ at\ 21.31.26.png (don't put them). make nice and clear PR discription. input.md in proof read form nicely formatted, key decision made extracted from decisions.md (not all, mort important / big). then clear outline of that was done
+- [ ] don't add "Co-Authored-By: claude code" in commit messages

package/RAF/ahnwrk-worktree-weaver/outcomes/01-remove-co-authored-by.md

@@ -0,0 +1,20 @@
+# Outcome: Remove Co-Authored-By from Commit Messages
+
+## Summary
+
+Added explicit instructions to the execution prompt telling Claude not to add Co-Authored-By or any other trailers to commit messages, ensuring commits use only the single-line `RAF[project:task] description` format.
+
+## Key Changes
+
+- **`src/prompts/execution.ts`** (lines 100-101): Added two bullet points to the commit instruction section:
+  - "The commit message must be a SINGLE LINE -- no body, no trailers"
+  - "Do NOT add Co-Authored-By or any other trailers to the commit message"
+- **`tests/unit/execution-prompt.test.ts`**: Added 2 new test cases:
+  - Verifies the prompt contains the no-trailers instruction
+  - Verifies the prompt specifies single-line commit format
+
+## Test Results
+
+All 45 tests pass (43 existing + 2 new).
+
+<promise>COMPLETE</promise>

package/RAF/ahnwrk-worktree-weaver/outcomes/02-update-task-status-format.md

@@ -0,0 +1,21 @@
+# Outcome: Update Task Status Display Format
+
+## Summary
+
+Changed the task status display format from `[ID] name` to `ID-name` to match the file naming convention used in plan/outcome files.
+
+## Key Changes
+
+- **`src/utils/terminal-symbols.ts`** (line 52): Changed `idPrefix` from `` `[${taskId}] ` `` to `` `${taskId}-` ``
+- **`src/utils/terminal-symbols.ts`** (lines 39-40): Updated JSDoc `@param` and `@returns` to reflect the new format
+- **`tests/unit/terminal-symbols.test.ts`**: Updated 4 test expectations to match the new format:
+  - `● 001-auth-login 1/5` (was `● [001] auth-login 1/5`)
+  - `✓ 001-auth-login 1m 23s` (was `✓ [001] auth-login 1m 23s`)
+  - `⊘ 002-depends-on-failed 2/5` (was `⊘ [002] depends-on-failed 2/5`)
+  - `✗ 003-deploy 45s` (was `✗ [003] deploy 45s`)
+
+## Test Results
+
+All 933 tests pass (45 suites).
+
+<promise>COMPLETE</promise>

package/RAF/ahnwrk-worktree-weaver/outcomes/03-worktree-auto-discovery.md

@@ -0,0 +1,34 @@
+# Outcome: Auto-Discover Worktree Projects in raf do
+
+## Summary
+
+Made `raf do` (without `--worktree` flag) automatically discover pending worktree projects from `~/.raf/worktrees/<repo-basename>/` and merge them into the interactive project picker. Selecting a worktree project auto-switches to worktree mode with post-action picker.
+
+## Key Changes
+
+- **`src/ui/project-picker.ts`**:
+  - Added `ProjectSource` type (`'local' | 'worktree'`) and `source`/`worktreeRoot` fields to `PendingProjectInfo`
+  - Added `PickerResult` interface for typed picker return values (folder, source, worktreeRoot)
+  - Added `getPendingWorktreeProjects()` function that scans worktree directories and returns pending projects
+  - Updated `formatProjectChoice()` to append `[worktree]` suffix for worktree-sourced projects
+  - Updated `pickPendingProject()` to accept optional worktree projects, deduplicate by folder (preferring worktree), sort chronologically, and return `PickerResult`
+
+- **`src/commands/do.ts`**:
+  - When no project identifier is provided (and `--worktree` not set), discovers worktree projects via `getPendingWorktreeProjects()` and passes them to the picker
+  - When a worktree project is selected, auto-switches: sets `worktreeMode = true`, `worktreeRoot`, and `originalBranch`
+  - This enables the full worktree execution flow (worktree cwd, post-action picker, post-action execution)
+
+- **`CLAUDE.md`**: Updated worktree documentation to reflect auto-discovery behavior
+
+- **`tests/unit/project-picker.test.ts`**: Updated and expanded from 20 to 26 tests:
+  - Updated 4 existing `pickPendingProject` tests for new `PickerResult` return type
+  - Added 1 test for `source: 'local'` on `getPendingProjects`
+  - Added 2 tests for `formatProjectChoice` worktree labeling
+  - Added 5 tests for `getPendingWorktreeProjects` (empty, metadata, completed skip, invalid folder, missing path)
+  - Added 4 tests for picker merging, deduplication, chronological sorting, and backwards compatibility
+
+## Test Results
+
+All 945 tests pass (45 suites).
+
+<promise>COMPLETE</promise>

package/RAF/ahnwrk-worktree-weaver/outcomes/04-fix-pr-description.md

@@ -0,0 +1,30 @@
+# Outcome: Fix and Improve PR Description Generation
+
+## Summary
+
+Fixed the `\n` escaping bug in PR descriptions, added output filtering, switched to Sonnet model, and restructured the PR body to a 4-section format.
+
+## Key Changes
+
+- **`src/core/pull-request.ts`**:
+  - Added `import * as os from 'node:os'` for temp file path generation
+  - **`createPullRequest()`**: Replaced inline `--body` with `--body-file` using a temp file written via `fs.writeFileSync()`, with cleanup in a `finally` block (even on error)
+  - **`callClaudeForPrBody()`**: Changed `--model haiku` to `--model sonnet`; applied `filterClaudeOutput()` to strip log noise from Claude's stdout
+  - **`generatePrBody()`**: Increased default timeout from 60s to 120s; rewrote prompt template to produce 4-section structure: Summary, Key Decisions, What Was Done, Test Plan
+  - **`generateFallbackBody()`**: Updated to produce the same 4-section structure with placeholder content
+  - **`filterClaudeOutput()`** (new, exported): Strips non-markdown lines from Claude output (warning emojis, `[warn]`/`[info]` prefixes, `console.warn`, `Note:`, `Loading`/`Connecting`/`Processing` lines, progress indicators)
+  - Updated JSDoc comments to reflect Sonnet usage
+
+- **`tests/unit/pull-request.test.ts`**:
+  - Added mocks for `node:os` (`tmpdir`), `fs.writeFileSync`, `fs.unlinkSync`
+  - Added `filterClaudeOutput` to imports
+  - Added 10 new tests for `filterClaudeOutput` (clean markdown passthrough, warning emoji removal, `[warn]` prefix, `console.warn`, `Note:` lines, Loading/Connecting/Processing, progress indicators, empty input, all-log input, blank line preservation)
+  - Added 3 new tests for `createPullRequest` (verifying `--body-file` usage, temp file cleanup on success, cleanup on failure)
+  - Added 2 new tests for `generatePrBody` (4-section prompt structure verification, sonnet model verification)
+  - Updated 2 existing `generatePrBody` tests to check for all 4 sections
+
+## Test Results
+
+All 960 tests pass (45 suites).
+
+<promise>COMPLETE</promise>

package/RAF/ahnwrk-worktree-weaver/plans/01-remove-co-authored-by.md

@@ -0,0 +1,26 @@
+# Task: Remove Co-Authored-By from Commit Messages
+
+## Objective
+Prevent Claude from adding "Co-Authored-By" trailers to commit messages during task execution.
+
+## Context
+Claude Code's default behavior adds a "Co-Authored-By: Claude..." trailer to git commits. Since RAF instructs Claude to make commits via the execution prompt, an explicit instruction must be added to suppress this. The execution prompt is in `src/prompts/execution.ts`.
+
+## Requirements
+- Add an explicit instruction in the Git Instructions section of the execution prompt telling Claude NOT to add Co-Authored-By or any other trailers to commit messages
+- The commit message should contain ONLY the `RAF[project:task] description` format, nothing else
+- Update the existing tests for the execution prompt to verify the new instruction is present
+
+## Implementation Steps
+1. In `src/prompts/execution.ts`, add to the commit instruction section (within the `commitInstructions` template) a clear instruction that the commit message must not include any trailers like Co-Authored-By
+2. Update tests in the execution prompt test file to check for the new instruction
+
+## Acceptance Criteria
+- [ ] Execution prompt includes explicit instruction to not add Co-Authored-By trailers
+- [ ] Commit format instructions specify that ONLY the RAF format should be used with no additional lines
+- [ ] Existing tests updated and passing
+
+## Notes
+- The current execution prompt is at `src/prompts/execution.ts` lines 89-103
+- The commit format is: `RAF[<projectNumber>:<paddedTaskNumber>] <description>`
+- This is a single-line commit message — no body, no trailers

package/RAF/ahnwrk-worktree-weaver/plans/02-update-task-status-format.md

@@ -0,0 +1,27 @@
+# Task: Update Task Status Display Format
+
+## Objective
+Change the task status display from `[01] base26-encoding` to `01-base26-encoding` to match the file naming convention.
+
+## Context
+The current terminal output shows task status as `● [01] base26-encoding 1:23` with brackets around the task ID. The user wants it to match the file naming pattern: `● 01-base26-encoding 1:23` — no brackets, dash separator between ID and name.
+
+## Requirements
+- Change the format from `[<taskId>] <name>` to `<taskId>-<name>` in the `formatTaskProgress()` function
+- Update all related tests to expect the new format
+- Ensure all terminal output that uses this function reflects the change
+
+## Implementation Steps
+1. In `src/utils/terminal-symbols.ts`, modify the `formatTaskProgress()` function to use `${taskId}-` instead of `[${taskId}] ` for the idPrefix
+2. Update the function's JSDoc comment/return example to reflect the new format
+3. Update all tests in the terminal-symbols test file to expect the new format string
+
+## Acceptance Criteria
+- [ ] Task progress lines display as `● 01-task-name` instead of `● [01] task-name`
+- [ ] All tests pass with the new format
+- [ ] JSDoc examples updated
+
+## Notes
+- The change is in `src/utils/terminal-symbols.ts` line 52: `const idPrefix = taskId ? `[${taskId}] ` : '';`
+- Change to: `const idPrefix = taskId ? `${taskId}-` : '';`
+- This affects running, completed, failed, pending, and blocked task displays

package/RAF/ahnwrk-worktree-weaver/plans/03-worktree-auto-discovery.md

@@ -0,0 +1,37 @@
+# Task: Auto-Discover Worktree Projects in raf do
+
+## Objective
+Make `raf do` (without `--worktree` flag) automatically discover pending worktree projects and include them in the project picker, auto-switching to worktree mode when one is selected.
+
+## Context
+Currently, worktree project discovery only happens when `--worktree` is explicitly passed. Users have to remember which worktree projects exist. The regular `raf do` picker should also show pending worktree projects from `~/.raf/worktrees/<repo-basename>/` so users can pick and execute them seamlessly.
+
+## Requirements
+- When `raf do` is run without arguments (triggering the project picker), also scan `~/.raf/worktrees/<repo-basename>/` for projects with pending tasks
+- Merge worktree projects into the same picker list alongside regular projects, sorted chronologically
+- Worktree projects should be labeled with `[worktree]` suffix, e.g. `abcdef my-feature (2/5 tasks) [worktree]`
+- When a worktree project is selected, automatically behave as if `--worktree` was passed: execute tasks in the worktree path and show the post-action picker after completion
+- The picker selection must carry metadata about whether the selected project is a worktree project
+
+## Implementation Steps
+1. Extend `src/ui/project-picker.ts` to accept worktree projects in addition to local ones. Add a `source` field to `PendingProjectInfo` (or similar) to distinguish worktree vs local projects
+2. Create a helper function that discovers pending worktree projects for the current repo by scanning `~/.raf/worktrees/<repo-basename>/` using existing `listWorktreeProjects()` from `src/core/worktree.ts`, then deriving state for each
+3. In `formatProjectChoice()`, append `[worktree]` label for worktree-sourced projects
+4. In `src/commands/do.ts`, when no identifier is provided and `--worktree` is not set, call the extended picker that includes both local and worktree projects
+5. When the user selects a worktree project, set the execution context to worktree mode: use the worktree path as cwd, enable the post-execution action picker, and follow the worktree execution flow
+6. Add tests for the new discovery logic, picker formatting, and worktree auto-switch behavior
+
+## Acceptance Criteria
+- [ ] `raf do` without arguments shows both local and worktree pending projects
+- [ ] Worktree projects are labeled with `[worktree]` in the picker
+- [ ] Selecting a worktree project automatically executes in worktree mode with post-action picker
+- [ ] Projects are sorted chronologically (mixed local and worktree)
+- [ ] When no worktree projects exist, picker behaves exactly as before
+- [ ] Tests cover the new functionality
+
+## Notes
+- Key files: `src/ui/project-picker.ts`, `src/commands/do.ts`, `src/core/worktree.ts`
+- The existing `discoverAndPickWorktreeProject()` in `do.ts` (around line 491) has similar logic for `--worktree` mode — reuse patterns from there
+- `listWorktreeProjects()` from `src/core/worktree.ts` returns project folder names for a given repo basename
+- `getRepoBasename()` from worktree.ts gets the current repo's basename
+- The picker return value needs to carry whether it's a worktree project so `do.ts` can handle it appropriately

package/RAF/ahnwrk-worktree-weaver/plans/04-fix-pr-description.md

@@ -0,0 +1,50 @@
+# Task: Fix and Improve PR Description Generation
+
+## Objective
+Fix the `\n` escaping bug in PR descriptions, filter out log noise, switch to Sonnet model, and restructure the PR body for clarity.
+
+## Context
+PR descriptions currently have multiple issues:
+1. **Newlines rendered as literal `\n`** — Root cause: `pull-request.ts` line 421 uses `.replace(/\n/g, '\\n')` when building the `gh pr create --body` shell command, which turns real newlines into literal `\n` strings
+2. **Log output leaking into PR body** — Claude CLI stdout may include warning/log lines mixed with the actual response
+3. **Haiku produces low-quality summaries** — Should use Sonnet for better PR descriptions
+4. **PR body structure needs improvement** — Should have: proofread summary from input.md, key decisions from decisions.md, clear outline of what was done
+
+## Requirements
+- Fix the `\n` escaping bug by writing the PR body to a temp file and using `gh pr create --body-file` instead of inline `--body`
+- Filter Claude CLI output to remove any non-markdown log lines (console warnings, progress indicators, etc.)
+- Change the model from `haiku` to `sonnet` in `callClaudeForPrBody()`
+- Restructure the prompt to produce this format:
+  - **Summary**: Proofread, clean version of the project requirements from input.md
+  - **Key Decisions**: Most important design choices extracted from decisions.md (not all, just significant ones)
+  - **What Was Done**: Clear outline of completed work from outcomes
+  - **Test Plan**: How to verify the changes
+- Clean up the temp file after PR creation
+
+## Dependencies
+01
+
+## Implementation Steps
+1. In `createPullRequest()`, write the generated PR body to a temp file and use `--body-file <path>` flag instead of `--body "<escaped>"`. Clean up the temp file after the `gh` command completes
+2. In `callClaudeForPrBody()`, change `--model haiku` to `--model sonnet`
+3. In `callClaudeForPrBody()`, add output filtering to strip non-markdown lines from Claude's stdout (lines that look like log output, warnings, or progress indicators)
+4. In `generatePrBody()`, rewrite the prompt template to instruct Claude to produce the new structured format: Summary (from input.md), Key Decisions (from decisions.md), What Was Done (from outcomes), Test Plan
+5. Update the fallback body in `generateFallbackBody()` to match the new structure
+6. Update tests for PR body generation, temp file handling, and the new prompt structure
+
+## Acceptance Criteria
+- [ ] PR body contains proper newlines (not literal `\n`) when viewed on GitHub
+- [ ] No log/warning output appears in PR descriptions
+- [ ] Sonnet model is used for body generation
+- [ ] PR body follows the new 4-section structure: Summary, Key Decisions, What Was Done, Test Plan
+- [ ] Temp file is cleaned up after PR creation (even on error)
+- [ ] Fallback body matches new structure
+- [ ] All tests pass
+
+## Notes
+- The `gh pr create --body-file` flag reads the body from a file, completely avoiding shell escaping issues
+- Use `os.tmpdir()` and a unique filename for the temp file
+- For output filtering: Claude CLI sometimes outputs lines starting with warning symbols or `console.warn` markers — strip anything that doesn't look like markdown content
+- The prompt should emphasize that only the MOST important decisions should be included, not every Q&A pair
+- `src/core/pull-request.ts` is the main file to modify
+- Increase the timeout from 60s since Sonnet is slower than Haiku

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;AAgDpC;;;;;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,CAiBzC;AA0QD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuBhG"}