rafcode 1.2.0 → 2.0.0

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

@@ -0,0 +1,88 @@
+# Project Decisions
+
+## How should the --worktree flag be persisted so `raf do` knows the project uses worktree mode?
+By naming convention - if a worktree directory matching `<repo>-<project id>` exists in `../<repo>-worktrees/`, the project is in worktree mode. No config file needed; existence of the worktree directory is the signal.
+
+## What branch name format should be used for the worktree branch?
+Full project folder name (e.g., `020-worktree-weaver`) - matches the project folder exactly.
+
+## Should planning also happen inside the worktree directory, or only execution?
+Both plan and execute in worktree. Create worktree first, then run planning inside it. Plans, decisions, input all live in the worktree.
+
+## What should happen during auto-merge on project completion if there are merge conflicts?
+~~Fast-forward only, warn on conflict. Only auto-merge if fast-forward is possible. If not, print a warning and leave the branch for manual merge.~~ UPDATED: Merge is controlled by `--merge` flag. Try ff first, fall back to merge-commit. On conflicts, run `git merge --abort` and warn the user to merge manually.
+
+## Should the project folder structure inside the worktree mirror the same relative path?
+Yes, same relative path. The worktree is a full repo clone. Project folder lives at the same `RAF/020-project-name/` path inside the worktree, so Claude works normally.
+
+## Should the worktree directory be cleaned up after a successful merge?
+~~Auto-cleanup after merge. Run `git worktree remove` and delete the worktree directory after successful merge.~~ UPDATED: No cleanup after merge. Worktrees persist indefinitely. No `raf cleanup` command needed.
+
+## For `raf do` without --worktree flag: should it auto-detect worktree mode?
+Require `--worktree` flag explicitly. Since it allows RAF to `cd` into the worktree dir and find project plans there. Both `raf plan` and `raf do` need the flag.
+
+## When should the git worktree be created during `raf plan --worktree`?
+~~Require the project name upfront when `--worktree` flag is present.~~ UPDATED: Project name is NOT required upfront for `--worktree`. The normal name picker/auto-generation flow works. The editor uses a temp file (never touches the main tree), so the worktree is created AFTER the project name is known. Flow: editor (temp file) → name resolution → create worktree → create project folder inside worktree → save input.md inside worktree.
+
+## Should `raf do --worktree` validate the worktree exists before execution?
+Yes, validate and fail with a helpful message. Check that: (1) the worktree directory exists, (2) the project folder and plan files exist inside the worktree. If not, error with guidance like "No worktree found. Did you plan with --worktree?"
+
+## Should `raf status` show worktree information?
+No, keep status output simple. No worktree-specific display.
+
+## Should `raf do --worktree` support multiple projects?
+No, `--worktree` only supports a single project at a time. Multi-project execution is not compatible with worktree mode.
+
+## How should the CLI syntax work for `raf plan --worktree`?
+~~Name is required when `--worktree` is used.~~ UPDATED: Name is optional, same as non-worktree mode. `raf plan --worktree` works without a name — the name picker/auto-generation runs as normal. `raf plan my-feature --worktree` also works (skips name picker). The `--auto` flag works the same (auto-selects first generated name).
+
+## Should planning artifacts be committed in worktree mode?
+Yes, commit in the worktree branch. Same commit behavior as today, but the commit lands in the worktree's branch instead of the main branch.
+
+## Where should worktree directories be stored?
+In `~/.raf/worktrees/<repo-basename>/<project-id>`, where `<repo-basename>` is the basename of the repo root directory (e.g., `myapp` from `/Users/me/projects/myapp`), and `<project-id>` is the full project folder name (e.g., `020-worktree-weaver`). This keeps worktrees outside the repo entirely — no `.gitignore` changes needed.
+
+## Should the parent `<repo>` directory under `~/.raf/worktrees/` be cleaned up when empty?
+No. Leave `~/.raf/worktrees/<repo>/` in place. No separate cleanup command needed.
+
+## How should `raf plan --amend --worktree` resolve the project identifier?
+Resolve from the worktree. Since plans only exist inside the worktree in worktree mode, project identifier resolution should look inside `~/.raf/worktrees/<repo-basename>/` to find the matching project. This is part of task 002 (worktree-plan-command).
+
+## When multiple uncompleted worktree projects are found (for `raf do --worktree` without project identifier), what should happen?
+Show an interactive picker (like the existing non-worktree flow) to let the user choose one project.
+
+## Should `raf do --worktree` without a project identifier be a new task or modify existing task 003?
+Modify task 003 directly to support optional project identifier with auto-discovery. Keeps related logic together.
+
+## What defines "latest completed project in main tree"?
+The project with the highest ID where all tasks are completed (project status = 'completed').
+
+## Should auto-discovery include worktree projects with failed tasks?
+Yes, include both pending and failed worktree projects in the picker - they're all "uncompleted".
+
+## If only one uncompleted worktree project is found, should it auto-select?
+No, still show the picker/confirmation even for a single project, so the user can cancel.
+
+## Should auto-discovery utility functions be added to task 001 (worktree utilities)?
+Yes, add a utility function like `listWorktreeProjects()` to task 001, and have task 003 call it. Keeps worktree scanning logic reusable.
+
+## What should the starting point for worktree scanning be?
+Start from "highest completed project in main tree minus 3" instead of "after the latest completed". This accounts for amended projects — e.g., if the highest completed main-tree project is 008, scan worktrees starting from 006 (006, 007, 008, 009, 010, ...). This catches worktrees for projects that were amended after completion and now have new uncompleted tasks.
+
+## Should worktrees be cleaned up after task completion or merge?
+No. No cleanup, no deletion of worktree, no prune after task completion. No `raf cleanup` command is needed. Worktrees stay in place indefinitely.
+
+## How should merging work after project completion in worktree mode?
+Merge is controlled by a `--merge` flag on `raf do`. When `--merge` is present, attempt merge after all tasks complete. Allow merge-commits (not ff-only). On merge conflicts, notify the user. Without `--merge`, no merge happens.
+
+## Should failed planning still clean up the worktree?
+Yes. If planning fails or is interrupted and no plans were created, clean up the worktree that was just created. This is different from post-completion cleanup — it's cleaning up a half-created state.
+
+## Should the worktree removal utility remain in task 001?
+Yes. It's still needed for the failed-plan cleanup in task 002. Just remove post-completion cleanup references from task 004.
+
+## Should `--merge` only work with `--worktree`?
+Yes. `--merge` is only valid when `--worktree` is also present. Error if used without `--worktree`.
+
+## What should happen on merge conflicts?
+Abort the merge (`git merge --abort`) to leave the repo in a clean state, then tell the user to merge manually.

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

@@ -0,0 +1,27 @@
+add support for git worktree if you pass --worktree flag to "do" or "plan". plan should be created
+with --worktree for raf do to work in worktree mode. --worktree means worktree folder will be
+created with git. use path "../<current folder name>-worktrees/<current folder name>-<project id
+like 001>". based on thether worktree dir exists in git we can validate if "raf do" can work in
+worktree mode. in worktree mode raf switches to worktree dir (in created branch with project name) and plans, commits and do work there.
+on project completion if it's possible to merge <project name> branch into original branch from with
+raf was called - it does so
+
+---
+
+use .raf/worktrees/<repo> as a place for raf worktrees
+
+---
+
+make it possible to not specify project name in "raf do --worktree" command, for that raf will go to
+worktrees repo and list uncompleted projects AFTER latest completed project in main tree
+
+---
+
+task 004 mentiones this:
+
+When `raf do <project> --worktree` finishes with all tasks completed, the project branch should be merged back into the branch from which `raf` was originally called. This is the final step in the worktree lifecycle: plan in worktree -> execute in worktree -> merge back -> remove worktree. The parent directory (`~/.raf/worktrees/<repo>/`) is NOT cleaned up here — that is handled by `raf cleanup`.
+
+---
+let's clarify cleanup situation (and remove mentionse about clean up from project plans)
+the situation is this: no cleanup, no delition of worktree, prune etc after task completion. AND no
+raf cleanup command need to be implemeted. look through all the plans and update

package/RAF/aaaacu-worktree-weaver/outcomes/01-git-worktree-utilities.md

@@ -0,0 +1,41 @@
+# Outcome: Git Worktree Utility Functions
+
+## Summary
+Created `src/core/worktree.ts` module with all git worktree utility functions needed as the foundation for worktree support in RAF.
+
+## Changes Made
+
+### New Files
+- **`src/core/worktree.ts`** - Core worktree utility module with 11 exported functions:
+  - `getRepoRoot()` - Get the git toplevel directory
+  - `getRepoBasename()` - Get the basename of the repo root (e.g., "myapp")
+  - `getCurrentBranch()` - Get the current branch name
+  - `computeWorktreePath(repoBasename, projectId)` - Compute `~/.raf/worktrees/<repo>/<project>` path
+  - `computeWorktreeBaseDir(repoBasename)` - Compute `~/.raf/worktrees/<repo>/` path
+  - `getWorktreeProjectPath(worktreePath, projectRelativePath)` - Compute project path inside worktree
+  - `createWorktree(repoBasename, projectId)` - Create worktree with auto-created parent dir and new branch
+  - `validateWorktree(worktreePath, projectRelativePath)` - Validate worktree existence, git status, project content
+  - `mergeWorktreeBranch(branch, originalBranch)` - Merge with ff-first, fallback to merge-commit, abort on conflicts
+  - `removeWorktree(worktreePath)` - Remove a single worktree (for failed-plan cleanup)
+  - `listWorktreeProjects(repoBasename)` - List all worktree project directories for a repo
+
+- **`tests/unit/worktree.test.ts`** - 30 unit tests covering all functions, error paths, and edge cases
+
+### Interfaces Exported
+- `WorktreeCreateResult` - Result of worktree creation
+- `WorktreeMergeResult` - Result of branch merge (includes fastForward flag)
+- `WorktreeValidation` - Validation result with exists/isValidWorktree/hasProjectFolder/hasPlans/projectPath
+
+## Acceptance Criteria Verification
+- [x] Worktree path computation returns `~/.raf/worktrees/<repo-basename>/<project-id>`
+- [x] Parent directory `~/.raf/worktrees/<repo-basename>/` is created automatically
+- [x] Worktree creation creates the directory and branch with correct names
+- [x] Validation correctly identifies existing vs missing worktrees and checks for project content
+- [x] Merge function tries fast-forward first, falls back to merge-commit, aborts on conflicts
+- [x] Removal function removes a single worktree (for failed-plan cleanup only)
+- [x] Listing function returns all worktree project directories for the current repo
+- [x] Listing function returns empty array when no worktrees exist
+- [x] All functions handle non-git-repo scenario gracefully
+- [x] All functions handle errors and return meaningful messages
+
+<promise>COMPLETE</promise>

package/RAF/aaaacu-worktree-weaver/outcomes/02-worktree-plan-command.md

@@ -0,0 +1,44 @@
+# Outcome: Add --worktree Flag to Plan Command
+
+## Summary
+Added `--worktree` (`-w`) flag to `raf plan` that creates a git worktree for isolated planning. Supports both new project creation and amendment of existing worktree projects.
+
+## Changes Made
+
+### Modified Files
+- **`src/commands/plan.ts`** - Added `--worktree` flag to the plan command with full support in both new project and amend flows:
+  - Added `-w, --worktree` option to Commander command definition
+  - Updated `PlanCommandOptions` interface with `worktree?: boolean`
+  - `runPlanCommand`: When `--worktree` is set, creates a worktree AFTER name resolution, creates project folder inside worktree at the correct relative path, saves input.md only in the worktree, runs Claude with `cwd` set to the worktree root, commits artifacts in the worktree branch, and shows success message with worktree path and `--worktree` suggestion for `raf do`
+  - `runAmendCommand`: When `--worktree` is set, resolves project from `~/.raf/worktrees/<repo>/` instead of main repo, validates worktree exists and is valid, runs amend flow with paths pointing into the worktree, commits amendment artifacts in the worktree branch
+  - Cleanup: failed planning with no plan files cleans up the worktree (new project only), amend does not create or clean up worktrees
+  - Added imports for worktree utilities, path utilities, and validation
+
+- **`src/core/git.ts`** - Updated `commitPlanningArtifacts` to accept optional `{ cwd }` parameter so git commands can run from the worktree directory instead of the main repo
+
+## Acceptance Criteria Verification
+- [x] `raf plan --worktree` without project name works (name picker/auto-generation runs)
+- [x] `raf plan my-feature --worktree` works with explicit name (skips name picker)
+- [x] `raf plan --worktree --auto` works (auto-selects generated name)
+- [x] Worktree is created AFTER name is resolved, not before
+- [x] input.md is only saved inside the worktree, never in the main tree
+- [x] Project folder is created at correct relative path inside worktree
+- [x] Planning session runs with cwd set to worktree root
+- [x] Planning artifacts are committed in the worktree branch
+- [x] Success message mentions the worktree path and suggests `--worktree` flag for `raf do`
+- [x] Without `--worktree`, behavior is unchanged
+- [x] Failed planning cleans up the worktree (new project only)
+- [x] Compatible with `--auto` and `--model` flags
+- [x] `raf plan --amend <project> --worktree` resolves project from worktree directory
+- [x] `raf plan --amend <project> --worktree` with no worktree shows helpful error
+- [x] Amend flow reads existing plans/state from inside the worktree
+- [x] New plan files from amend are committed in the worktree branch
+- [x] Amend does NOT attempt to create or clean up the worktree
+
+## Test Results
+- Build: passes cleanly (no TypeScript errors)
+- All 835 tests pass (834 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated to this change)
+- All 64 plan command tests pass
+- All 8 commit-planning-artifacts tests pass
+
+<promise>COMPLETE</promise>

package/RAF/aaaacu-worktree-weaver/outcomes/03-worktree-do-command.md

@@ -0,0 +1,58 @@
+# Outcome: Add --worktree Flag to Do Command
+
+## Summary
+Added `--worktree` (`-w`) flag to `raf do` that validates worktree existence and executes all tasks inside the worktree directory. Supports both explicit project identifier and auto-discovery of uncompleted worktree projects when no identifier is given.
+
+## Changes Made
+
+### Modified Files
+- **`src/commands/do.ts`** - Added `--worktree` flag with full worktree support:
+  - Added `-w, --worktree` option to Commander command definition
+  - When `--worktree` with no identifier: auto-discovery flow via `discoverAndPickWorktreeProject()`:
+    - Lists worktree projects using `listWorktreeProjects()`
+    - Finds highest-numbered completed project in main tree
+    - Filters worktrees by threshold (highest completed - 3)
+    - Derives state for remaining worktrees, keeps uncompleted ones
+    - Shows interactive picker (even for single project)
+    - Shows appropriate messages for no projects / all completed
+  - When `--worktree` with explicit identifier:
+    - Validates single project only (errors if multiple)
+    - Resolves project from main repo or searches worktrees directly
+    - Validates worktree existence, git worktree status, project content, and plans
+    - Shows helpful error messages on validation failure
+  - When `--worktree` with identifier: validates worktree, resolves project path inside it
+  - Passes `worktreeCwd` to `executeSingleProject` which flows to `ClaudeRunner.run()`/`runVerbose()`
+  - Git operations (commit verification, stash) use worktree cwd
+  - Added imports for worktree utilities, path utilities, inquirer select, and discoverProjects
+
+- **`src/core/git.ts`** - Added optional `cwd` parameter to git utility functions:
+  - `isGitRepo(cwd?)` - accepts optional cwd for worktree context
+  - `hasUncommittedChanges(cwd?)` - accepts optional cwd
+  - `getHeadCommitHash(cwd?)` - accepts optional cwd
+  - `stashChanges(name, cwd?)` - accepts optional cwd, propagates to internal calls
+
+- **`src/types/config.ts`** - Added `worktree?: boolean` to `DoCommandOptions` interface
+
+## Acceptance Criteria Verification
+- [x] `raf do --worktree` without project identifier triggers auto-discovery flow
+- [x] Auto-discovery lists worktree projects, finds latest completed main-tree project, filters correctly
+- [x] Auto-discovery shows picker even when only one uncompleted project is found
+- [x] Auto-discovery shows "No worktree projects found" when none exist
+- [x] Auto-discovery shows "All worktree projects are completed" when all are done
+- [x] `raf do proj1 proj2 --worktree` shows error about single project only
+- [x] `raf do my-feature --worktree` with no worktree shows helpful error
+- [x] `raf do my-feature --worktree` with valid worktree executes tasks in worktree
+- [x] Claude runs with cwd set to worktree root
+- [x] State derivation reads from worktree project path
+- [x] Outcome files are written to worktree project path
+- [x] Git commits land in the worktree branch
+- [x] Compatible with `--verbose`, `--timeout`, `--force`, `--debug`, `--model`
+- [x] Without `--worktree`, behavior is unchanged
+
+## Test Results
+- Build: passes cleanly (no TypeScript errors)
+- All 835 tests pass (834 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated to this change)
+- All 67 do command tests pass (do-command, do-multiproject, do-rerun, do-blocked-tasks)
+- All 29 git tests pass (git, git-stash, git-commit-helpers)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacu-worktree-weaver/outcomes/04-auto-merge-and-cleanup.md

@@ -0,0 +1,40 @@
+# Outcome: Auto-merge on Project Completion
+
+## Summary
+Added `--merge` flag to `raf do` that automatically merges the worktree branch back into the original branch after all tasks complete successfully. The merge uses fast-forward first, falls back to merge-commit, and aborts on conflicts with helpful manual merge instructions.
+
+## Changes Made
+
+### Modified Files
+- **`src/commands/do.ts`** - Added `--merge` flag with full merge-on-completion support:
+  - Added `--merge` option to Commander command definition
+  - Added validation that `--merge` requires `--worktree` (errors otherwise)
+  - Records the original branch name (`getCurrentBranch()`) at the start of worktree execution, before any worktree operations
+  - After task execution loop completes, checks if `--merge` is set:
+    - If all results succeeded: attempts merge via `mergeWorktreeBranch()` from the original repo directory
+    - On successful merge: logs success message with merge type (fast-forward or merge commit)
+    - On merge conflict: `mergeWorktreeBranch` aborts the merge, logs warning with branch name and manual merge instructions
+    - If project has failures: skips merge entirely, logs message about worktree branch being available for inspection
+  - Worktree is NOT removed or cleaned up after merge
+  - Added imports for `getCurrentBranch` and `mergeWorktreeBranch` from worktree module
+
+- **`src/types/config.ts`** - Added `merge?: boolean` to `DoCommandOptions` interface
+
+## Acceptance Criteria Verification
+- [x] `--merge` flag is added to the do command
+- [x] `--merge` without `--worktree` shows an error
+- [x] On full project completion with `--merge`, merge is attempted
+- [x] Successful merge logs a clear success message
+- [x] Merge conflicts trigger `git merge --abort` and show warning with branch name and manual merge instructions
+- [x] Incomplete projects (failures) skip merge and mention the branch
+- [x] Original branch is correctly recorded and restored
+- [x] Worktree is NOT removed or cleaned up after merge
+- [x] Without `--merge`, no merge is attempted even if project completes
+
+## Test Results
+- Build: passes cleanly (no TypeScript errors)
+- All 835 tests pass (834 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated to this change)
+- All 50 do-command and worktree tests pass
+- All 30 worktree utility tests pass
+
+<promise>COMPLETE</promise>

package/RAF/aaaacu-worktree-weaver/outcomes/05-worktree-tests.md

@@ -0,0 +1,43 @@
+# Outcome: Add Tests for Worktree Functionality
+
+## Summary
+Added comprehensive tests covering worktree utilities and CLI validation for `--worktree` and `--merge` flags. Tests include both unit tests with mocked dependencies and integration tests using real temporary git repos.
+
+## Changes Made
+
+### Modified Files
+- **`tests/unit/worktree.test.ts`** - Added 6 new unit tests for path computation with various repo/project names:
+  - `computeWorktreePath`: repo names with dots, underscores, hyphens; base36 project IDs
+  - `computeWorktreeBaseDir`: repo names with special characters
+  - `getWorktreeProjectPath`: nested relative paths
+
+### New Files
+- **`tests/unit/worktree-integration.test.ts`** - 22 integration tests in two sections:
+
+  **Real git repo tests** (12 tests):
+  - `createWorktree`: worktree creation with real git, branch conflict detection
+  - `validateWorktree`: valid worktree with project/plans, nonexistent path, non-worktree directory, missing project folder
+  - `mergeWorktreeBranch`: fast-forward merge, merge-commit fallback on divergence, conflict detection with abort, checkout failure
+  - `removeWorktree`: successful removal for failed-plan cleanup, nonexistent worktree failure
+
+  **CLI validation tests** (10 tests):
+  - `--merge requires --worktree`: validates the constraint, allows valid combos
+  - `--worktree supports only single project`: rejects multiple projects, allows single/none
+  - `--worktree validation for missing worktree`: missing path, non-worktree dir, missing content, valid worktree
+
+## Test Results
+- All 58 worktree tests pass (36 unit + 22 integration)
+- All 862 project tests pass (1 pre-existing failure in planning-prompt.test.ts unrelated to this change)
+- Temp directories and worktrees are properly cleaned up after each test
+
+## Acceptance Criteria Verification
+- [x] All worktree utility functions have unit tests
+- [x] Path computation tested with various repo and project names
+- [x] Worktree creation tested with real temporary git repo
+- [x] Merge tested for ff success, merge-commit fallback, and conflict/abort
+- [x] Removal tested for failed-plan cleanup scenario
+- [x] CLI validation tests for error cases (--merge without --worktree, etc.)
+- [x] All tests pass with `npm test`
+- [x] Tests clean up temporary files/directories
+
+<promise>COMPLETE</promise>

package/RAF/aaaacu-worktree-weaver/outcomes/06-update-documentation.md

@@ -0,0 +1,33 @@
+# Outcome: Update Documentation for Worktree Support
+
+## Summary
+Updated both README.md (user-facing) and CLAUDE.md (internal developer docs) with comprehensive documentation for the `--worktree` and `--merge` flags.
+
+## Changes Made
+
+### Modified Files
+- **`README.md`** - Added worktree documentation in four places:
+  - **Features section**: Added "Worktree Mode" bullet describing isolated branch execution
+  - **Commands section**: Added `raf plan --worktree` and `raf do --worktree --merge` examples to both plan and do command blocks
+  - **Worktree Mode section** (new, after Project Structure): Explains the workflow, worktree path convention, merge behavior, conflict handling, persistence, and single-project limitation
+  - **Command Reference tables**: Added `-w, --worktree` row to plan table; added `-w, --worktree` and `--merge` rows to do table
+
+- **`CLAUDE.md`** - Added "Worktree Mode" subsection under "Architectural Decisions" covering:
+  - Worktree path convention (`~/.raf/worktrees/<repo-basename>/<project-id>`)
+  - Branch naming (matches project folder name)
+  - Flag requirement (explicit `--worktree` on both plan and do)
+  - Full lifecycle: create -> plan -> execute -> merge
+  - Merge strategy details
+  - Cleanup behavior (no auto-cleanup except on plan failure)
+  - Constraints (`--worktree` single project only, `--merge` requires `--worktree`)
+  - Core module reference (`src/core/worktree.ts`)
+
+## Acceptance Criteria Verification
+- [x] README.md has `--worktree` and `--merge` in Features, Commands, and Command Reference
+- [x] README.md has a "Worktree Mode" section with workflow explanation
+- [x] CLAUDE.md has a "Worktree Mode" architectural decision section
+- [x] Documentation mentions that worktrees persist (no auto-cleanup)
+- [x] Documentation matches the implemented behavior (verified against source code)
+- [x] No existing documentation is broken or contradicted
+
+<promise>COMPLETE</promise>

package/RAF/aaaacu-worktree-weaver/plans/01-git-worktree-utilities.md

@@ -0,0 +1,51 @@
+# Task: Git Worktree Utility Functions
+
+## Objective
+Create a new module with git worktree utility functions that handle path computation, worktree creation, validation, merge, and removal.
+
+## Context
+This is the foundation task for worktree support. All other worktree tasks depend on these utilities. The module follows the pattern of the existing `src/core/git.ts` module - standalone functions using `execSync` for git operations.
+
+## Requirements
+- Compute worktree path: `~/.raf/worktrees/<repo-basename>/<project-id>` where `<repo-basename>` is the basename of `process.cwd()` (the repo root, e.g., `myapp`) and `<project-id>` is the full project folder name (e.g., `020-worktree-weaver`)
+- Create the `~/.raf/worktrees/<repo-basename>/` directory automatically if it doesn't exist
+- Create a git worktree at the computed path with a new branch named after the full project folder (e.g., `020-worktree-weaver`)
+- Validate that a worktree directory exists and is a valid git worktree (check `git worktree list`)
+- Validate that the project folder and plan files exist inside the worktree
+- Compute the project path inside the worktree (same relative path from repo root as in the main repo)
+- Merge: merge the worktree branch into the original branch. Attempt fast-forward first; if not possible, allow a merge-commit. On merge conflicts, run `git merge --abort` and return failure with a message for the user to merge manually
+- Remove a worktree: run `git worktree remove` to remove a single worktree directory (used only for failed-plan cleanup, NOT for post-completion cleanup)
+- Get current branch name (for recording which branch the worktree was created from)
+- List all worktree project directories for a given repo: scan `~/.raf/worktrees/<repo-basename>/` and return the list of project folder names (e.g., `['020-worktree-weaver', '021-another-feature']`). Return an empty array if the directory doesn't exist or is empty
+- All functions should handle errors gracefully and return meaningful error messages
+- Follow the same patterns as `src/core/git.ts` - use `execSync` with `stdio: 'pipe'`, wrap in try/catch
+
+## Implementation Steps
+1. Create `src/core/worktree.ts` module
+2. Implement path computation function that derives `~/.raf/worktrees/<repo-basename>/<project-id>` using `os.homedir()`, the basename of the git toplevel, and the project folder name
+3. Implement worktree creation function that ensures the parent directory exists and runs `git worktree add <path> -b <branch-name>`
+4. Implement validation function that checks worktree existence in `git worktree list` output AND checks for project folder + plans inside
+5. Implement merge function that: switches to the original branch, runs `git merge --ff-only <project-branch>`, if ff fails tries `git merge <project-branch>`, if conflicts arise runs `git merge --abort` and returns failure with manual-merge instructions
+6. Implement removal function that runs `git worktree remove <path>` for a single worktree (used only for failed-plan cleanup)
+7. Implement helper to get the repo root directory name (basename of git toplevel)
+8. Implement function to list all worktree project directories under `~/.raf/worktrees/<repo-basename>/` - read the directory, filter to valid project folder names, return sorted list
+9. Export all functions as named exports
+
+## Acceptance Criteria
+- [ ] Worktree path computation returns `~/.raf/worktrees/<repo-basename>/<project-id>`
+- [ ] Parent directory `~/.raf/worktrees/<repo-basename>/` is created automatically
+- [ ] Worktree creation creates the directory and branch with correct names
+- [ ] Validation correctly identifies existing vs missing worktrees and checks for project content
+- [ ] Merge function tries fast-forward first, falls back to merge-commit, aborts on conflicts
+- [ ] Removal function removes a single worktree (for failed-plan cleanup only)
+- [ ] Listing function returns all worktree project directories for the current repo
+- [ ] Listing function returns empty array when no worktrees exist
+- [ ] All functions handle non-git-repo scenario gracefully
+- [ ] All functions handle errors and return meaningful messages
+
+## Notes
+- The worktree path is now under the user's home directory (`~/.raf/worktrees/`), not relative to the repo. For example, if the repo is at `/Users/me/projects/myapp`, the worktree would be at `~/.raf/worktrees/myapp/020-worktree-weaver`
+- The merge function needs to be called from the ORIGINAL repo (not the worktree) because it needs to switch to the original branch
+- The branch name is the full project folder name (e.g., `020-worktree-weaver`), not just the project name
+- Use `os.homedir()` to resolve `~` to the actual home directory path
+- The removal function is only used for cleaning up failed/cancelled planning — NOT for post-completion cleanup. Worktrees persist after task completion and merge

package/RAF/aaaacu-worktree-weaver/plans/02-worktree-plan-command.md

@@ -0,0 +1,93 @@
+# Task: Add --worktree Flag to Plan Command
+
+## Objective
+Add `--worktree` flag to `raf plan` that creates a git worktree and runs the entire planning session inside it, including support for `--amend` to add tasks to existing worktree projects.
+
+## Context
+When a user runs `raf plan --worktree` (with or without a project name), RAF should create a git worktree under `~/.raf/worktrees/<repo-basename>/`, then create the project folder inside the worktree and run the interactive planning session there. The project name is optional — the normal name picker/auto-generation works since the editor uses a temp file and the worktree is only created after the name is known. When combined with `--amend`, RAF should find the existing worktree, switch into it, and run the amendment flow there.
+
+## Dependencies
+001
+
+## Requirements
+
+### New project flow (`raf plan [name] --worktree`)
+- Add `--worktree` boolean flag to the plan command in Commander.js (both in `src/commands/plan.ts` and `src/index.ts` if needed)
+- Project name is OPTIONAL with `--worktree` — same behavior as non-worktree mode:
+  - If name is provided: use it directly (skip name picker)
+  - If name is NOT provided: generate suggestions from input content, then picker or auto-select (same as today)
+- The worktree is created AFTER the project name is determined (not before), because the worktree path includes the project ID
+- Flow with `--worktree`:
+  1. Validate environment
+  2. Open editor for input (writes to temp file — nothing touches the main tree)
+  3. Resolve project name: use provided name, or generate/pick from input content (same as today)
+  4. Compute project number from the main repo's RAF directory (to get the sequential ID)
+  5. Create git worktree at `~/.raf/worktrees/<repo-basename>/<project-id>` using utilities from task 001
+  6. Create the project folder structure inside the worktree (at the same relative path as it would be in the main repo)
+  7. Save input.md inside the worktree project folder (never in the main tree)
+  8. Run interactive Claude planning session with `cwd` set to the worktree directory
+  9. Commit planning artifacts (input.md, decisions.md, plan files) inside the worktree branch
+  10. Show success message including the worktree path and branch name
+- When `--worktree` is NOT used, behavior is exactly the same as today (no changes)
+- The `--worktree` flag should be compatible with `--auto` and `--model` flags
+- If worktree creation fails, error out with a clear message
+- Cleanup: if planning fails or is interrupted and no plans were created, clean up the worktree
+
+### Amend flow (`raf plan --amend <project> --worktree`)
+- When `--amend` and `--worktree` are both used, the project identifier must be resolved from the worktree directory (`~/.raf/worktrees/<repo-basename>/`), NOT from the main repo — because plans only exist inside the worktree
+- The worktree must already exist (it was created during initial `raf plan --worktree`) — error if not found
+- Flow with `--amend --worktree`:
+  1. Resolve project identifier against the worktree's project directories
+  2. Validate the worktree exists and contains the project with existing plans
+  3. Switch working context to the worktree directory
+  4. Run the standard amend flow (derive project state, show existing tasks, open editor, run Claude amendment interview) with all paths pointing into the worktree
+  5. Commit amendment artifacts (updated input.md, decisions.md, new plan files) in the worktree branch
+- The project state derivation (`deriveProjectState`) should read from the worktree project path
+- The amend system prompt should receive task information from the worktree project
+- No worktree creation or cleanup needed for amend — the worktree already exists
+
+## Implementation Steps
+1. Add `--worktree` option to the Commander command definition in `src/commands/plan.ts`
+2. Update `PlanCommandOptions` interface to include `worktree?: boolean`
+3. **New project path**: When `--worktree` is set (without `--amend`):
+   - Run editor (temp file) and name resolution exactly as today
+   - After name is finalized, compute project number from main repo
+   - Create worktree, then create project folder inside worktree
+   - Save input.md inside worktree project folder
+   - Run planning with cwd set to worktree root
+4. **Amend path**: When `--worktree` and `--amend` are both set:
+   - Resolve project identifier from `~/.raf/worktrees/<repo-basename>/` instead of main repo
+   - Validate the worktree exists
+   - Set all paths to worktree project path and run standard amend flow
+5. For both paths, set the working directory for Claude's interactive session to the worktree root
+6. After planning/amending, commit artifacts in the worktree branch
+7. Add cleanup logic for worktree on failure/interruption for new projects (not for amend — worktree already existed)
+8. Update the success message to mention worktree path and suggest `raf do <name> --worktree`
+
+## Acceptance Criteria
+- [ ] `raf plan --worktree` without project name works (name picker/auto-generation runs)
+- [ ] `raf plan my-feature --worktree` works with explicit name (skips name picker)
+- [ ] `raf plan --worktree --auto` works (auto-selects generated name)
+- [ ] Worktree is created AFTER name is resolved, not before
+- [ ] input.md is only saved inside the worktree, never in the main tree
+- [ ] Project folder is created at correct relative path inside worktree
+- [ ] Planning session runs with cwd set to worktree root
+- [ ] Planning artifacts are committed in the worktree branch
+- [ ] Success message mentions the worktree path and suggests `--worktree` flag for `raf do`
+- [ ] Without `--worktree`, behavior is unchanged
+- [ ] Failed planning cleans up the worktree (new project only)
+- [ ] Compatible with `--auto` and `--model` flags
+- [ ] `raf plan --amend <project> --worktree` resolves project from worktree directory
+- [ ] `raf plan --amend <project> --worktree` with no worktree shows helpful error
+- [ ] Amend flow reads existing plans/state from inside the worktree
+- [ ] New plan files from amend are committed in the worktree branch
+- [ ] Amend does NOT attempt to create or clean up the worktree
+
+## Notes
+- The project folder path inside the worktree should be identical to what it would be in the main repo (e.g., `<worktree>/RAF/020-my-feature/plans/`)
+- The interactive Claude session needs to run with its working directory set to the worktree root so Claude sees the correct file paths
+- The `commitPlanningArtifacts` function from `src/core/git.ts` should work inside the worktree since git operations are branch-aware
+- For amend, `resolveProjectIdentifierWithDetails()` from `src/utils/paths.ts` likely needs a way to point at the worktree's RAF directory instead of the main repo's. This could be an optional parameter or a wrapper that computes the worktree RAF path
+- The project number still comes from the main repo's RAF directory (to maintain sequential numbering), but the project folder itself only exists in the worktree
+- The editor already uses a temp file (`os.tmpdir()`), so nothing touches the main tree before the worktree is created
+- Reference existing plan command at `src/commands/plan.ts` for the current flow

package/RAF/aaaacu-worktree-weaver/plans/03-worktree-do-command.md

@@ -0,0 +1,81 @@
+# Task: Add --worktree Flag to Do Command
+
+## Objective
+Add `--worktree` flag to `raf do` that validates the worktree exists and executes all tasks inside the worktree directory, with optional auto-discovery of worktree projects when no project identifier is given.
+
+## Context
+After planning with `--worktree`, the user runs `raf do <project> --worktree` to execute tasks. RAF needs to validate the worktree exists at `~/.raf/worktrees/<repo-basename>/<project-id>`, find the project inside it, and run all Claude execution sessions with cwd set to the worktree root.
+
+Additionally, `raf do --worktree` (without a project identifier) should auto-discover uncompleted worktree projects by scanning the worktrees directory and filtering to projects that come after the latest completed project in the main tree.
+
+## Dependencies
+001
+
+## Requirements
+- Add `--worktree` boolean flag to the do command in Commander.js
+- When `--worktree` is used with a project identifier, only a SINGLE project is supported - error if multiple projects are specified
+- When `--worktree` is used WITHOUT a project identifier, perform auto-discovery:
+  1. Use the listing utility from task 001 to get all worktree project directories for this repo
+  2. If no worktree projects exist, show error: "No worktree projects found. Did you plan with --worktree?"
+  3. Find the highest-numbered completed project in the MAIN tree (using `deriveProjectState`)
+  4. Filter worktree projects to those with a project number >= (highest completed - 3). For example, if the highest completed main-tree project is 008, include worktree projects 006 and above. This accounts for amended projects that may have new uncompleted tasks added via `--amend`
+  5. For each remaining worktree project, derive its state and keep only uncompleted ones (pending, failed, or in-progress — anything that is NOT fully completed)
+  6. If no uncompleted worktree projects remain after filtering, show message: "All worktree projects are completed"
+  7. Show an interactive picker with the uncompleted worktree projects (even if there's only one), allowing the user to cancel with Ctrl+C
+  8. Execute the selected project
+- When `--worktree` is used with an explicit project identifier, validate:
+  1. The worktree directory exists at `~/.raf/worktrees/<repo-basename>/<project-id>`
+  2. The worktree is a valid git worktree (listed in `git worktree list`)
+  3. The project folder exists inside the worktree with plan files
+  4. If any validation fails, show a helpful error message (e.g., "No worktree found for project X. Did you plan with --worktree?")
+- Execution flow with `--worktree` (after project is selected/resolved):
+  1. Resolve project identifier to get project folder name
+  2. Compute worktree path using utilities from task 001
+  3. Validate worktree and project content
+  4. Derive project state from the worktree project path (not the main repo)
+  5. Execute each task with Claude's cwd set to the worktree root
+  6. All commits, stashes, and git operations happen in the worktree branch
+  7. State derivation, outcome files, logs - all use the worktree project path
+- When `--worktree` is NOT used, behavior is exactly the same as today
+- The `--worktree` flag should be compatible with all existing flags (`--timeout`, `--verbose`, `--debug`, `--force`, `--model`, `--sonnet`)
+- Update `DoCommandOptions` type in `src/types/config.ts` to include `worktree?: boolean`
+
+## Implementation Steps
+1. Add `--worktree` option to the Commander command definition in `src/commands/do.ts`
+2. Update `DoCommandOptions` interface in `src/types/config.ts`
+3. In `runDoCommand`, branch on whether a project identifier was provided:
+   - **With identifier**: validate single project only, compute worktree path, validate it exists
+   - **Without identifier**: run auto-discovery flow (list worktrees, find latest completed main-tree project, filter, derive states, show picker)
+4. For auto-discovery: scan main tree projects to find the highest-numbered fully-completed project using `deriveProjectState`
+5. For auto-discovery: filter worktree projects to those with IDs >= (highest completed - 3), then derive each project's state to find uncompleted ones
+6. For auto-discovery: show interactive picker using the existing `pickPendingProject` pattern (or similar UI) for the user to select one
+7. After project selection/resolution, replace the `projectPath` with the worktree project path for all operations
+8. Pass the worktree root as the working directory to `ClaudeRunner.run` and `ClaudeRunner.runVerbose`
+9. Ensure `executeSingleProject` uses the worktree project path for state derivation, outcome files, and all file operations
+10. The `ClaudeRunner` likely needs a `cwd` option - check if it already supports it, add if not
+11. All git operations (commit verification, stash, etc.) should naturally work in the worktree since cwd is set there
+
+## Acceptance Criteria
+- [ ] `raf do --worktree` without project identifier triggers auto-discovery flow
+- [ ] Auto-discovery lists worktree projects, finds latest completed main-tree project, filters correctly
+- [ ] Auto-discovery shows picker even when only one uncompleted project is found
+- [ ] Auto-discovery shows "No worktree projects found" when none exist
+- [ ] Auto-discovery shows "All worktree projects are completed" when all are done
+- [ ] `raf do proj1 proj2 --worktree` shows error about single project only
+- [ ] `raf do my-feature --worktree` with no worktree shows helpful error
+- [ ] `raf do my-feature --worktree` with valid worktree executes tasks in worktree
+- [ ] Claude runs with cwd set to worktree root
+- [ ] State derivation reads from worktree project path
+- [ ] Outcome files are written to worktree project path
+- [ ] Git commits land in the worktree branch
+- [ ] Compatible with `--verbose`, `--timeout`, `--force`, `--debug`, `--model`
+- [ ] Without `--worktree`, behavior is unchanged
+
+## Notes
+- The key change is that all paths point to the worktree version of the project, and Claude's working directory is the worktree root
+- The `ClaudeRunner` class in `src/core/claude-runner.ts` likely needs a `cwd` option passed to `spawn` / `node-pty` - check if this already exists
+- When a project identifier IS given, resolution still works against the MAIN repo's RAF directory to get the folder name, but then the actual project path used for execution is inside the worktree
+- For auto-discovery, project identifier resolution works against the worktree directory listing — these projects only exist in worktrees, not the main tree
+- The scanning threshold is: highest completed main-tree project number minus 3. E.g., if project 008 is the highest completed, scan worktrees from 006 onward. This catches amended projects that had new tasks added after completion. If no main-tree projects are completed, scan all worktrees (threshold = 0)
+- Reference existing do command at `src/commands/do.ts` and `ClaudeRunner` at `src/core/claude-runner.ts`
+- Reference `getPendingProjects` and `pickPendingProject` from `src/ui/project-picker.js` for the picker pattern