rafcode 1.3.2 → 2.0.0

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

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

@@ -0,0 +1,51 @@
+# Task: Auto-merge on Project Completion
+
+## Objective
+When `--merge` flag is present on `raf do --worktree`, automatically merge the project branch into the original branch after all tasks complete successfully.
+
+## Context
+After worktree execution completes, the user may want to merge the project branch back into the branch from which `raf` was originally called. This is controlled by the `--merge` flag (only valid with `--worktree`). The worktree itself is NOT cleaned up or removed after merge — it stays in place.
+
+## Dependencies
+003
+
+## Requirements
+- Add `--merge` boolean flag to the do command in Commander.js
+- `--merge` is only valid when `--worktree` is also present — error if `--merge` is used without `--worktree`
+- After all tasks complete (project state is "completed") and `--merge` is set, attempt auto-merge:
+  1. Switch back to the original branch (the branch that was active when `raf do --worktree` was invoked)
+  2. Attempt merge using the merge utility from task 001 (tries ff first, falls back to merge-commit)
+  3. On success: log success message with merge details
+  4. On conflict: `git merge --abort` is called by the utility, log a warning with the branch name so the user can merge manually
+- Record the original branch name at the start of `raf do --worktree` execution (before switching to worktree)
+- The merge must happen from the ORIGINAL repo's working directory, not from inside the worktree
+- If the project is NOT fully completed (has failures), skip the merge entirely — just show a message about the worktree branch
+- The merge should also work for partially completed projects that were continued with `--force` and are now fully complete
+- Do NOT remove or clean up the worktree after merge — the worktree stays in place
+
+## Implementation Steps
+1. Add `--merge` option to the Commander command definition in `src/commands/do.ts`
+2. Validate that `--merge` is only used with `--worktree`, error otherwise
+3. In the `do` command's worktree flow, record the current branch name before execution starts
+4. After the task execution loop completes, check if `--merge` is set and the project is fully completed
+5. If completed with `--merge`: call the merge utility from task 001 (passing original branch, project branch, and paths)
+6. Handle merge result: success -> log success, conflict -> log warning with manual merge instructions
+7. If project has failures: just note that the worktree branch is available for inspection
+8. No worktree cleanup or removal after merge
+
+## Acceptance Criteria
+- [ ] `--merge` flag is added to the do command
+- [ ] `--merge` without `--worktree` shows an error
+- [ ] On full project completion with `--merge`, merge is attempted
+- [ ] Successful merge logs a clear success message
+- [ ] Merge conflicts trigger `git merge --abort` and show warning with branch name and manual merge instructions
+- [ ] Incomplete projects (failures) skip merge and mention the branch
+- [ ] Original branch is correctly recorded and restored
+- [ ] Worktree is NOT removed or cleaned up after merge
+- [ ] Without `--merge`, no merge is attempted even if project completes
+
+## Notes
+- The merge happens in the original repo directory, not the worktree — this is important because `git merge` needs to be on the target branch
+- The current branch at invocation time should be captured early (before any worktree operations change context)
+- Consider the case where the user's original branch has moved forward (other commits) while the worktree was being worked on — if ff fails, a merge-commit is created; only conflicts cause failure
+- Reference the worktree utility functions from task 001 for merge operations

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

@@ -0,0 +1,52 @@
+# Task: Add Tests for Worktree Functionality
+
+## Objective
+Add comprehensive tests covering the worktree utilities and the integration of `--worktree` and `--merge` flags into plan and do commands.
+
+## Context
+RAF uses Jest with ts-jest ESM preset. Existing tests are in `__tests__/` directories. The worktree functionality involves git operations that need careful testing with real temporary git repos.
+
+## Dependencies
+001, 002, 003, 004
+
+## Requirements
+- Unit tests for all worktree utility functions in `src/core/worktree.ts`:
+  - Path computation (given repo name and project folder, verify correct worktree path)
+  - Worktree creation (use a temporary git repo)
+  - Worktree validation (existing vs non-existing)
+  - Merge (fast-forward success, merge-commit fallback, and conflict/abort cases)
+  - Removal (for failed-plan cleanup scenario only)
+- Integration-level tests for command behavior:
+  - `raf do --worktree` with multiple projects should error
+  - `raf do --worktree` with no worktree should error with helpful message
+  - `raf do --merge` without `--worktree` should error
+- Test edge cases:
+  - Worktree path computation when repo has special characters in name
+  - Merge when original branch has diverged (merge-commit should be created)
+  - Merge with conflicts (should abort and return failure)
+- Use temporary directories and real git repos for git operation tests (create temp dir, `git init`, add commits, etc.)
+- Follow existing test patterns in the project
+
+## Implementation Steps
+1. Create `src/core/__tests__/worktree.test.ts` for unit tests of utility functions
+2. Write tests for path computation (pure function, no git needed)
+3. Write tests for worktree creation/validation/merge/removal using temporary git repos
+4. Create test helpers for setting up temporary git repos with commits
+5. Write tests for CLI validation (--worktree and --merge flag behavior)
+6. Ensure all tests clean up their temporary directories
+
+## Acceptance Criteria
+- [ ] All worktree utility functions have unit tests
+- [ ] Path computation tested with various repo and project names
+- [ ] Worktree creation tested with real temporary git repo
+- [ ] Merge tested for ff success, merge-commit fallback, and conflict/abort
+- [ ] Removal tested for failed-plan cleanup scenario
+- [ ] CLI validation tests for error cases (--merge without --worktree, etc.)
+- [ ] All tests pass with `npm test`
+- [ ] Tests clean up temporary files/directories
+
+## Notes
+- Creating temporary git repos for testing: use `fs.mkdtempSync` + `execSync('git init')` + add a commit
+- For worktree tests, the base repo needs at least one commit before `git worktree add` will work
+- Be careful with `process.cwd()` in tests - some utilities may depend on it. Consider mocking or using `chdir` carefully
+- Reference existing test files in the project for patterns and conventions

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

@@ -0,0 +1,55 @@
+# Task: Update Documentation for Worktree Support
+
+## Objective
+Document the `--worktree` and `--merge` flags and worktree workflow in both CLAUDE.md (internal developer docs) and README.md (user-facing docs).
+
+## Context
+The worktree feature adds a new workflow to RAF. Users need to know how to use it, and developers maintaining RAF need to understand the architecture. Both docs files need updates.
+
+## Dependencies
+002, 003, 004
+
+## Requirements
+
+### README.md updates:
+- Add `--worktree` to the Features section (brief mention of isolated branch execution)
+- Add worktree usage examples to the Commands section for both `raf plan` and `raf do`
+- Add `--worktree` and `--merge` rows to the Command Reference tables for both plan and do
+- Add a new "Worktree Mode" section (after the existing "Project Structure" section) explaining:
+  - What worktree mode does and why you'd use it (isolated branch for parallel work)
+  - The basic workflow: `raf plan my-feature --worktree` -> `raf do my-feature --worktree --merge`
+  - Where worktree directories are created (`~/.raf/worktrees/<repo>/<project>`)
+  - Merge behavior with `--merge` flag (ff preferred, merge-commit fallback, conflict abort)
+  - What happens on failure (branch preserved, user can merge manually)
+  - Worktrees persist after completion — no automatic cleanup
+
+### CLAUDE.md updates:
+- Add a new "Worktree Mode" subsection under "Architectural Decisions" explaining:
+  - Worktree path convention: `~/.raf/worktrees/<repo-basename>/<project-id>`
+  - Branch naming: full project folder name (e.g., `020-my-feature`)
+  - How worktree mode detection works (--worktree flag required on both plan and do)
+  - The lifecycle: create worktree -> plan in worktree -> execute in worktree -> optionally merge with `--merge`
+  - Merge strategy: ff preferred, merge-commit fallback, abort on conflicts
+  - Worktrees are NOT cleaned up after completion or merge
+  - Single project limitation (no multi-project with --worktree)
+  - `--merge` only valid with `--worktree`
+- Add `--worktree` and `--merge` to the plan and do command descriptions if they exist in CLAUDE.md
+
+## Implementation Steps
+1. Read both README.md and CLAUDE.md to understand current structure
+2. Add worktree content to README.md in the appropriate sections
+3. Add worktree architectural decision to CLAUDE.md
+4. Ensure the documentation is consistent with the actual implementation
+
+## Acceptance Criteria
+- [ ] README.md has `--worktree` and `--merge` in Features, Commands, and Command Reference
+- [ ] README.md has a "Worktree Mode" section with workflow explanation
+- [ ] CLAUDE.md has a "Worktree Mode" architectural decision section
+- [ ] Documentation mentions that worktrees persist (no auto-cleanup)
+- [ ] Documentation matches the implemented behavior
+- [ ] No existing documentation is broken or contradicted
+
+## Notes
+- Keep documentation concise - match the existing style of both files
+- Focus on the user workflow in README.md and the technical architecture in CLAUDE.md
+- The worktree path example should use concrete values so it's easy to understand

package/RAF/aaaacv-trim-the-fat/decisions.md

@@ -0,0 +1,34 @@
+# Project Decisions
+
+## Should we remove raf status or modify it?
+Don't remove status. Add automatic worktree discovery — no flag needed.
+
+## Should raf status need a --worktree flag?
+No. Always look for worktree projects automatically (if in a git repo).
+
+## Should raf status show only worktree projects or both main and worktree?
+Both combined. If a project exists in both main repo and worktree, don't duplicate in list mode — only show additional worktree projects and mark them.
+
+## How should worktree-only projects be marked in the status list?
+Indented under a "Worktrees:" header at the bottom of the list.
+
+## How should single-project view work when project exists in both main and worktree?
+Show both states separately ONLY if they differ. For example, after an amend, the main repo might show 5/5 tasks done while the worktree shows 5/7 (not fully completed). List both with clear labels (Main: / Worktree:). If states are identical, show just the normal view with no worktree label.
+
+## Should worktree projects always appear in status output?
+Only if they differ from their main repo counterpart (more tasks, different statuses). If identical, skip them. Worktree-only projects (no main counterpart) are always shown.
+
+## For raf plan --amend syntax change — keep -a alias?
+Keep -a alias. However, this task was SKIPPED — Commander.js treats both orderings identically so no code change needed.
+
+## For removing multi-project support from raf do — what should the arg look like?
+Single project argument only: `raf do <project>` with exactly one identifier.
+
+## For amend commit — should plan files be included?
+Yes. Commit input.md, decisions.md, AND any new/modified plan files.
+
+## Should amend commit message be distinct from new plan commit?
+Yes. Use `RAF[NNN] Amend: project-name` for amendments (vs `RAF[NNN] Plan: project-name` for new plans).
+
+## Should planning/amend exit messages be worktree-aware?
+Yes. When running in worktree mode, the exit message should show `raf do <project> --worktree` instead of `raf do <project>`. Both planning and amend prompts need this.

package/RAF/aaaacv-trim-the-fat/input.md

@@ -0,0 +1,5 @@
+- [ ] remove "raf status"
+- [ ] support only "raf plan project --amend" syntax (remove support for "raf plan --amend project syntax). update docs (readme and claude.md)
+- [ ] remove multi project support for raf do
+- [ ] even if plan was not created in amend (but updated) RAF should still commit input and decisions and updated plan files
+

package/RAF/aaaacv-trim-the-fat/outcomes/01-add-worktree-support-to-status.md

@@ -0,0 +1,43 @@
+# Outcome: Add Automatic Worktree Discovery to raf status
+
+## Summary
+
+Added automatic worktree project discovery to `raf status`. When inside a git repo, the status command now discovers and displays worktree projects from `~/.raf/worktrees/<repo>/` alongside main repo projects, with no flag required.
+
+## Key Changes
+
+### `src/commands/status.ts`
+- Added `getWorktreeContext()` to resolve repo basename and RAF relative path
+- Added `discoverWorktreeProjectStates()` to scan worktree directories and derive project state
+- Added `projectStatesDiffer()` to compare main vs worktree project states (by task count and statuses)
+- **List mode** (`raf status`): Shows main repo projects normally, then appends a `Worktrees:` section listing worktree projects that differ from their main repo counterpart. Identical projects are hidden. Worktree-only projects always shown.
+- **Single project mode** (`raf status <project>`): Shows both "Main:" and "Worktree:" progress bars when states differ. Shows only one view when identical or when project exists in only one location.
+- **JSON output**: List mode wraps in `{ projects: [...], worktrees: [...] }`. Single project mode adds `worktree` field when worktree data exists.
+- Gracefully handles non-git-repo case (skips worktree discovery silently)
+
+### `tests/unit/status-command.test.ts`
+- Added 10 new tests covering:
+  - Project state comparison (identical states, differing task counts, differing statuses)
+  - Worktree project discovery patterns
+  - Filtering worktree-only vs counterpart projects
+  - Stats computation for worktree projects
+
+### `README.md`
+- Updated `raf status` section to mention automatic worktree discovery
+
+### `CLAUDE.md`
+- Added worktree discovery details to the Worktree Mode section
+
+## Acceptance Criteria Verification
+
+- [x] `raf status` lists main repo projects normally, then worktree projects that differ under a `Worktrees:` header
+- [x] Worktree projects identical to their main repo counterpart are not shown
+- [x] `raf status <project>` shows both main repo and worktree state only when they differ
+- [x] `raf status <project>` shows just worktree state when project only exists in worktree
+- [x] `--json` includes worktree project data
+- [x] Non-git-repo environments work fine (worktree section just doesn't appear)
+- [x] README.md and CLAUDE.md updated
+- [x] Tests cover the new functionality (10 new tests, all passing)
+- [x] All existing tests pass (1 pre-existing failure in planning-prompt.test.ts unrelated to changes)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/outcomes/02-remove-multi-project-from-do.md

@@ -0,0 +1,50 @@
+# Outcome: Remove Multi-Project Support from raf do
+
+## Summary
+
+Simplified `raf do` to accept only a single project identifier, removing the multi-project execution feature. The command argument changed from `[projects...]` (variadic) to `[project]` (single optional). All multi-project logic was removed.
+
+## Key Changes
+
+### `src/commands/do.ts`
+- Changed `.argument('[projects...]', ...)` to `.argument('[project]', ...)`
+- Changed action handler signature from `(projects: string[], ...)` to `(project: string | undefined, ...)`
+- Rewrote `runDoCommand()` to work with a single optional identifier:
+  - No array iteration, deduplication (`seenPaths`), or error accumulation
+  - Direct project resolution instead of loop
+  - Simplified merge check: `result.success` instead of `results.every(r => r.success)`
+- Removed `printMultiProjectSummary()` function entirely
+- Removed `isMultiProject` flag and multi-project verbose logging
+- Removed verbose model logging for multi-project (`if (verbose && model && resolvedProjects.length > 1)`)
+- Removed worktree guard for multiple projects (no longer needed)
+- Removed unused `SYMBOLS` import
+
+### `tests/unit/do-multiproject.test.ts`
+- Deleted entirely
+
+### `tests/unit/do-command.test.ts`
+- Removed "Multiple Projects with Full Folder Names" describe block
+- Removed "Mixed Formats" describe block (tested multi-identifier resolution)
+- Kept all single-project, backward compatibility, and error handling tests
+
+### `README.md`
+- Removed `raf do 3 4 5` example from usage
+- Changed command reference from `raf do [projects...]` to `raf do [project]`
+- Removed `--worktree supports a single project at a time (no multi-project)` line
+
+### `CLAUDE.md`
+- Removed `### Multi-Project Execution` section from architectural decisions
+- Removed `--worktree supports single project only (no multi-project)` line from worktree section
+
+## Acceptance Criteria Verification
+
+- [x] `raf do 3` works for a single project
+- [x] `raf do` (no args) still shows interactive picker
+- [x] `raf do --worktree` still shows worktree picker
+- [x] `raf do 3 4` — Commander.js with `[project]` ignores extra args
+- [x] `printMultiProjectSummary` and multi-project loop removed
+- [x] `do-multiproject.test.ts` removed
+- [x] README.md and CLAUDE.md updated (no multi-project references)
+- [x] All remaining tests pass (843 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/outcomes/03-commit-artifacts-on-amend.md

@@ -0,0 +1,35 @@
+# Outcome: Commit Planning Artifacts (Including Plan Files) on Amend
+
+## Summary
+
+Extended `commitPlanningArtifacts()` to support amending by accepting additional file paths and an `isAmend` flag. The amend flow in `plan.ts` now passes new plan file paths to the commit function, and uses a distinct `Amend:` commit message prefix. Also fixed a bug where `isGitRepo()` was not receiving the `cwd` option for worktree support.
+
+## Key Changes
+
+### `src/core/git.ts`
+- Extended `commitPlanningArtifacts()` options to include `additionalFiles?: string[]` and `isAmend?: boolean`
+- When `isAmend` is true, commit message uses `RAF[NNN] Amend: project-name` instead of `RAF[NNN] Plan: project-name`
+- Additional files are staged alongside `input.md` and `decisions.md`
+- Fixed bug: `isGitRepo()` now receives `execCwd` parameter for correct worktree support (was called without `cwd` previously)
+
+### `src/commands/plan.ts`
+- Updated `runAmendCommand()` to build full paths for new plan files (`newPlanPaths = newPlanFiles.map(f => path.join(plansDir, f))`)
+- Passes `additionalFiles` and `isAmend: true` to `commitPlanningArtifacts()`
+- Normal `raf plan` flow unchanged — still only commits input + decisions with "Plan:" prefix
+
+### `tests/unit/commit-planning-artifacts.test.ts`
+- Added test: "should use 'Amend:' prefix when isAmend is true"
+- Added test: "should stage additional files when provided"
+- Added test: "should pass cwd to isGitRepo for worktree support"
+- All 11 tests pass (8 existing + 3 new)
+
+## Acceptance Criteria Verification
+
+- [x] `raf plan --amend` commits input.md, decisions.md, and new plan files together
+- [x] Amend commits use message format `RAF[NNN] Amend: project-name`
+- [x] Normal `raf plan` still uses `RAF[NNN] Plan: project-name` and only commits input + decisions
+- [x] Worktree mode works correctly (cwd passed through)
+- [x] Tests cover the amend commit scenario (3 new tests)
+- [x] All existing tests pass (846 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/outcomes/04-worktree-aware-exit-messages.md

@@ -0,0 +1,36 @@
+# Outcome: Make Planning and Amend Exit Messages Worktree-Aware
+
+## Summary
+
+Made the exit messages in both planning and amend prompts worktree-aware. When planning or amending in worktree mode, the exit message now shows `raf do <project> --worktree` instead of `raf do <project>`. Also improved the amend prompt's exit message to include the `raf do` command (previously it only said "Press Ctrl-C twice to exit").
+
+## Key Changes
+
+### `src/prompts/planning.ts`
+- Added `worktreeMode?: boolean` to `PlanningPromptParams` interface
+- Updated `getPlanningPrompt()` to conditionally append ` --worktree` to the `raf do <project>` exit message
+
+### `src/prompts/amend.ts`
+- Added `worktreeMode?: boolean` to `AmendPromptParams` interface
+- Updated `getAmendPrompt()` exit message from "Press Ctrl-C twice to exit" to include `raf do <project>` command with conditional `--worktree` flag
+
+### `src/commands/plan.ts`
+- Passed `worktreeMode` to `getPlanningPrompt()` in `runPlanCommand()`
+- Passed `worktreeMode` to `getAmendPrompt()` in `runAmendCommand()`
+
+### `tests/unit/planning-prompt.test.ts`
+- Added 3 new tests: worktreeMode false, undefined, and true variations
+
+### `tests/unit/amend-prompt.test.ts` (new file)
+- Added 7 tests covering basic prompt functionality and worktree mode variations
+
+## Acceptance Criteria Verification
+
+- [x] Planning in worktree mode shows `raf do <project> --worktree` in exit message
+- [x] Planning in normal mode still shows `raf do <project>` in exit message
+- [x] Amend in worktree mode shows `raf do <project> --worktree` in exit message
+- [x] Amend in normal mode shows exit message without `--worktree`
+- [x] Tests cover both worktree and non-worktree variations (6 new tests)
+- [x] All existing tests pass (856 pass, 1 pre-existing failure in planning-prompt.test.ts unrelated)
+
+<promise>COMPLETE</promise>

package/RAF/aaaacv-trim-the-fat/plans/01-add-worktree-support-to-status.md

@@ -0,0 +1,43 @@
+# Task: Add Automatic Worktree Discovery to raf status
+
+## Objective
+Make `raf status` always discover and display worktree projects alongside main repo projects — no flag required.
+
+## Context
+Currently `raf status` only discovers and displays projects from the main RAF directory. Projects that exist only in worktrees (`~/.raf/worktrees/<repo>/<project>/`) are invisible to the status command. This makes it hard to track worktree project progress without running `raf do --worktree`. Worktree discovery should be automatic — if a git repo is detected and worktree projects exist, they should appear.
+
+## Requirements
+- **No new flag** — worktree discovery happens automatically when the current directory is inside a git repo
+- **List mode** (`raf status`): Show main repo projects as normal, then append a `Worktrees:` section at the bottom listing worktree projects that DIFFER from their main repo counterpart (indented). A worktree project "differs" if it has more tasks (amend added new ones) or different task statuses. If the worktree state is identical to main repo, skip it. Worktree-only projects (no main repo counterpart) are always shown.
+- **Single project mode** (`raf status <project>`): Show the project from BOTH main repo and worktree only when they differ. This is common after `--amend` — e.g., main repo shows 5/5 tasks completed (original plan), while worktree shows 5/7 (amended with 2 new tasks not yet executed). Display both states, clearly labeled (e.g., "Main:" and "Worktree:"). If the states are identical, show just the main view without any worktree label. If the project only exists in worktree, show just that one.
+- Both modes should support the existing `--json` flag (include worktree data in JSON output)
+- Gracefully handle non-git-repo case: if `getRepoBasename()` returns null, skip worktree discovery silently
+- Use existing worktree utilities: `getRepoBasename()`, `listWorktreeProjects()`, `computeWorktreePath()`, `computeWorktreeBaseDir()` from `src/core/worktree.ts`
+- Use existing state derivation: `deriveProjectState()`, `getDerivedStats()` from `src/core/state-derivation.ts`
+- Follow existing patterns in `src/commands/do.ts` for worktree project resolution (searching worktree directories, resolving identifiers within them)
+
+## Implementation Steps
+1. In `runStatusCommand()` in `src/commands/status.ts`, after the main repo logic, attempt worktree discovery using `getRepoBasename()` and `listWorktreeProjects()`. If not in a git repo, skip silently.
+2. For list mode: discover worktree projects, filter out any that already appear in main repo projects (match by folder name), then display remaining under a `Worktrees:` header with indentation. Derive state for each worktree project to show progress bars.
+3. For single-project mode: resolve the project identifier in both main repo and worktrees. If found in both, show two progress displays labeled "Main:" and "Worktree:". If found in only one, show just that.
+4. Update the `--json` output to include worktree project data when worktree projects are discovered
+5. Update tests in `tests/unit/status-command.test.ts` to cover worktree discovery for both list and single-project modes
+6. Update README.md `raf status` section to mention that worktree projects are shown automatically
+7. Update CLAUDE.md to mention automatic worktree discovery in the status command
+
+## Acceptance Criteria
+- [ ] `raf status` lists main repo projects normally, then worktree projects that differ under a `Worktrees:` header
+- [ ] Worktree projects identical to their main repo counterpart are not shown
+- [ ] `raf status <project>` shows both main repo and worktree state only when they differ
+- [ ] `raf status <project>` shows just worktree state when project only exists in worktree
+- [ ] `--json` includes worktree project data
+- [ ] Non-git-repo environments work fine (worktree section just doesn't appear)
+- [ ] README.md and CLAUDE.md updated
+- [ ] Tests cover the new functionality
+- [ ] All existing tests pass
+
+## Notes
+- The worktree project resolution pattern already exists in `do.ts` — reuse that logic (or extract shared utility if the duplication is significant)
+- `listWorktreeProjects()` returns folder names like `['020-my-feature', '021-another']` — use `extractProjectNumber()` and `extractProjectName()` to display them consistently with main repo projects
+- Worktree projects need their RAF relative path computed (from repo root to RAF dir) to find the project folder inside the worktree, same as `do.ts` does
+- No changes needed to `StatusCommandOptions` type or command definition — this is automatic behavior, not a flag