create-claude-workspace 1.1.30 → 1.1.31

package/dist/index.js

@@ -128,7 +128,7 @@ function listFiles(dir, base = dir) {
 }
 function ensureGitignore(targetDir) {
     const gitignorePath = join(targetDir, '.gitignore');
-    const entries = ['.npmrc', '.docker-compose.auth.yml', '.claude/autonomous.log', '.claude/autonomous.lock', '.claude/autonomous-state.json'];
+    const entries = ['.npmrc', '.docker-compose.auth.yml', '.claude/autonomous.log', '.claude/autonomous.lock', '.claude/autonomous-state.json', '.worktrees/'];
     if (existsSync(gitignorePath)) {
         let content = readFileSync(gitignorePath, 'utf-8');
         const added = [];

package/dist/template/.claude/agents/devops-integrator.md

@@ -185,8 +185,8 @@ When the orchestrator picks a task from TODO.md:
 
 ```bash
 # Extract issue number from TODO.md comment <!-- #42 -->
-# Create feature branch
-git checkout -b feat/42-task-title-slug
+# Create git worktree with feature branch (project root stays on main)
+git worktree add .worktrees/feat/42-task-title-slug -b feat/42-task-title-slug
 
 # Update issue label
 # GitHub
@@ -196,18 +196,22 @@ gh issue edit 42 --remove-label "status::todo" --add-label "status::in-progress"
 glab issue update 42 --unlabel "status::todo" --label "status::in-progress"
 ```
 
+**Return the absolute path of the worktree** to the orchestrator (it needs it for all subsequent file operations).
+
 Branch naming: `{type}/{issue-number}-{slug}`
 - `feat/42-card-domain-types`
 - `fix/43-camera-permission-error`
 - `refactor/44-extract-shared-utils`
 
+Worktree path: `.worktrees/{type}/{issue-number}-{slug}/`
+
 ### 3. Task Complete (called at STEP 11 of development cycle, after commit)
 
-After the commit is made:
+After the commit is made in the worktree:
 
 ```bash
-# Push branch
-git push -u origin HEAD
+# Push branch from worktree (orchestrator provides the worktree path)
+git -C {worktree-path} push -u origin HEAD
 
 # Create MR/PR
 # GitHub
@@ -322,12 +326,16 @@ glab issue update {issue-number} --unlabel "status::in-review" --label "status::
 **When called directly** (outside the development cycle, e.g., manual cleanup):
 
 ```bash
-# Switch back to main branch
+# Clean up worktree (if it exists)
+git worktree remove .worktrees/feat/{issue-number}-{slug} 2>/dev/null || true
+git worktree remove .worktrees/fix/{issue-number}-{slug} 2>/dev/null || true
+
+# Ensure on main
 git checkout main 2>/dev/null || git checkout master
 git pull --rebase origin HEAD
 
 # Delete the merged feature branch locally
-git branch -d feat/{issue-number}-{slug}
+git branch -d feat/{issue-number}-{slug} 2>/dev/null || git branch -d fix/{issue-number}-{slug} 2>/dev/null || true
 
 # Delete remote branch (if not auto-deleted by platform)
 git push origin --delete feat/{issue-number}-{slug} 2>/dev/null || true

package/dist/template/.claude/agents/orchestrator.md

@@ -21,6 +21,50 @@ You are an ORCHESTRATOR, not an implementer. You MUST delegate specialized work
 - NEVER do planning, architecture, or review "inline" — these MUST go through specialist agents
 - If you catch yourself writing code directly after STEP 1, STOP — you skipped STEP 2
 
+## Git Worktree Workflow
+
+The project root directory ALWAYS stays on `main`. Each task gets its own **git worktree** — a separate working directory with the feature branch checked out. This keeps the main checkout stable and avoids disruptive branch switching.
+
+**Worktree path**: `.worktrees/{branch-name}/` (e.g., `.worktrees/feat/42-user-auth/`)
+**Track in MEMORY.md**: `Current Worktree: .worktrees/feat/42-user-auth`
+
+### Creating a worktree (STEP 1)
+```bash
+git worktree add .worktrees/feat/{slug} -b feat/{slug}
+```
+
+### Working in the worktree (STEP 2-10)
+ALL file reads, edits, and commands target the worktree path:
+- **Read/Edit/Write**: use absolute paths under the worktree (e.g., `{worktree-abs-path}/src/app/...`)
+- **Bash**: always `cd` into the worktree first: `cd {worktree-path} && nx build ...`
+- **Sub-agent prompts**: include `"Working directory: {worktree-abs-path}"` so they operate on the correct files
+
+### Tracking files (MEMORY.md, TODO.md)
+- **Step-by-step updates** (e.g., `Current Step: 3 — IMPLEMENT`): edit MEMORY.md in the **project root** (on main). These are uncommitted crash-recovery state — always readable at session start.
+- **STEP 11** (commit): copy final MEMORY.md + TODO.md into the worktree, commit everything together. Then discard the uncommitted tracking changes on main: `git checkout -- MEMORY.md TODO.md` (they come back via merge).
+- **After merge** (STEP 12): main receives the committed MEMORY.md and TODO.md from the feature branch.
+
+### Merging (STEP 12)
+From the project root (on main):
+```bash
+git merge feat/{slug} --no-ff    # or platform merge via devops-integrator
+git worktree remove .worktrees/feat/{slug}
+git branch -d feat/{slug}
+```
+
+### Reverting / skipping a task
+```bash
+git worktree remove --force .worktrees/feat/{slug}
+git branch -D feat/{slug}
+```
+Then commit tracking changes (TODO.md `[~]`, MEMORY.md blocker) directly on main.
+
+### Crash recovery
+- Worktree exists at session start → check MEMORY.md `Current Step` and `Current Worktree` to resume
+- Worktree has uncommitted changes → continue from the recorded step
+- Worktree has commits ahead of main → proceed to STEP 12 (merge)
+- Orphaned worktree (no `Current Worktree` in MEMORY.md) → `git worktree remove --force` + `git branch -D`
+
 ## Session Start — Health Check
 
 At the beginning of EVERY session (including every Ralph Loop iteration):
@@ -43,19 +87,26 @@ At the beginning of EVERY session (including every Ralph Loop iteration):
 
 ### 4. Reconcile working state
 Before doing anything, check for unexpected state from user intervention or previous session:
-- `git status` — if there are uncommitted changes:
-  - Read MEMORY.md `Current Task` and `Current Step` for context
-  - **Crash recovery for STEP 11-12**: If `Current Step` contains `12` (e.g., `12 — POST-MERGE (pending)`):
-    - Check `git status` for uncommitted changes. If present, the STEP 11 commit was incomplete — re-stage all task files + TODO.md + MEMORY.md and commit before proceeding.
-    - If working tree is clean, the commit succeeded. Proceed to STEP 12 to complete the merge.
+- **Worktree recovery**: Read MEMORY.md `Current Worktree`. If set, check if the worktree directory exists:
+  - Worktree exists + `Current Step` is set → resume from that step (continue working in the worktree)
+  - **Crash recovery for STEP 11**: If `Current Step` contains `11`:
+    - Check `git -C {worktree} status` for uncommitted changes. If present, the STEP 11 commit was incomplete — re-stage all task files + TODO.md + MEMORY.md in the worktree and commit.
+    - If worktree is clean, the commit succeeded. Proceed to STEP 12 (merge).
+  - **Crash recovery for STEP 12**: If `Current Step` contains `12`:
+    - Check if the feature branch has commits ahead of main. If yes, proceed to STEP 12 (merge from main).
+    - If already merged: clean up worktree and branch, clear `Current Worktree` from MEMORY.md.
   - **Crash recovery for hotfix**: If `Current Step` starts with `hotfix`, resume in hotfix workflow mode (shortened cycle). Use the STEP number after `hotfix —` to determine where to continue.
-  - If changes match current task and an earlier step -> continue from that step
-  - If changes are unknown -> `git stash --include-untracked -m "stash: unknown changes found at session start"`, log in MEMORY.md Notes: "Stashed unknown changes — user should review with `git stash list` and `git stash pop` or `git stash drop`"
-- `git branch --show-current` — if on a feature branch:
-  - Check if there's an open MR/PR for it -> if merged, delete branch and switch to main
-  - If not merged and work is incomplete -> continue from where you left off (use `Current Step` from MEMORY.md)
-  - If `Current Step` is empty but the branch has commits ahead of main -> previous iteration completed but merge was interrupted. Proceed to STEP 12.
-- Check if TODO.md or MEMORY.md were manually edited (compare git diff) -> accept changes, adjust plan
+  - Worktree has uncommitted changes matching current task → continue from recorded step
+  - `Current Worktree` is set but directory doesn't exist → orphaned reference. Check if the branch was merged (in `git log main`). If merged: clear `Current Worktree` and `Current Task` from MEMORY.md. If not merged but branch exists: recreate worktree `git worktree add {path} {branch}` and resume. If branch is gone: clear tracking, move to next task.
+- **Orphaned worktrees**: `git worktree list` — if there are worktrees not referenced by MEMORY.md `Current Worktree`:
+  - `git worktree remove --force {path}` + `git branch -D {branch}` if the branch is not merged
+  - Skip if the branch is merged (just remove worktree, keep branch deletion for normal cleanup)
+- **Uncommitted tracking changes on main**: `git status` on the project root — if MEMORY.md or TODO.md have uncommitted changes on main:
+  - These are step-tracking updates from a previous crashed session. Accept them (they reflect the last known state).
+- `git branch --show-current` — confirm you are on `main`/`master`. If on a feature branch (legacy pre-worktree state):
+  - Check if there's an open MR/PR for it → if merged, delete branch and switch to main
+  - If not merged: create a worktree from this branch (`git worktree add .worktrees/{branch} {branch}`), switch project root back to main (`git checkout main 2>/dev/null || git checkout master`), and resume from the worktree
+- Check if TODO.md or MEMORY.md were manually edited (compare git diff) → accept changes, adjust plan
 
 ### 5. Check required files exist
 Resolve in THIS order (each depends on the previous):
@@ -65,16 +116,11 @@ Resolve in THIS order (each depends on the previous):
 4. `MEMORY.md` missing -> Create it (see MEMORY.md template below).
 
 ### 6. Sync with main branch
-If currently on main/master AND remote exists (`git remote -v | grep origin`):
+Project root should be on `main`/`master`. If remote exists (`git remote -v | grep origin`):
 ```bash
 git pull --rebase origin HEAD
 ```
-If on a **detached HEAD** (worktree mode after previous merge) AND remote exists:
-```bash
-git fetch origin main:main 2>/dev/null || git fetch origin master:master
-```
-This updates the local main ref without checkout — needed when main is checked out in another worktree.
-If no remote or on a feature branch (continuing work), skip this step.
+If no remote, skip this step.
 
 ### 7. Check git log and structure
 - `git log --oneline -10`
@@ -154,13 +200,20 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
     5. Publish: `npm publish dist/libs/[LIB] --access [public/restricted]`
     6. If this is the **first publish** (npm returns 404/not-found before publish): log in MEMORY.md Notes: "First npm publish done locally for [LIB]. User should configure Trusted Publishing on npmjs.com for future CI publishes."
     7. **NEVER** echo, log, or write the npm token value — it is read from `~/.npmrc` automatically
-- Update MEMORY.md: set `Current Task: [task title]`
-- If git integration is active (TODO.md has `<!-- #N -->` markers):
-  - Delegate to `devops-integrator` agent: "Start task #N — create feature branch and update issue status to in-progress"
-- If no git integration: `git checkout -b feat/{slug} 2>/dev/null || git checkout feat/{slug}` (handles existing branch from previous aborted attempt)
+- Update MEMORY.md (on main): set `Current Task: [task title]`
+- **Create worktree** (see §Git Worktree Workflow):
+  - If git integration is active (TODO.md has `<!-- #N -->` markers):
+    - Delegate to `devops-integrator` agent: "Start task #N — create a git worktree at `.worktrees/feat/{issue-number}-{slug}` with a new branch `feat/{issue-number}-{slug}`, and update issue status to in-progress. Return the worktree absolute path."
+  - If no git integration:
+    ```bash
+    git worktree add .worktrees/feat/{slug} -b feat/{slug} 2>/dev/null || true
+    ```
+    If the branch already exists (aborted previous attempt): `git worktree add .worktrees/feat/{slug} feat/{slug}`
+- Store the worktree path: update MEMORY.md (on main) `Current Worktree: .worktrees/feat/{slug}`
+- **All subsequent steps (2-11) operate in the worktree directory.** Use absolute paths for file operations and `cd {worktree}` for bash commands.
 
 **STEP 2: PLAN — DELEGATE to architect agent (MANDATORY)**
-- Update MEMORY.md: set `Current Step: 2 — PLAN`
+- Update MEMORY.md (on main): set `Current Step: 2 — PLAN`
 - Determine task type using the Task Type Detection heuristic above
 - **Frontend items** -> Agent tool with `ui-engineer`
 - **Backend items** -> Agent tool with `backend-ts-architect`
@@ -170,6 +223,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   3. **If `ui-engineer` returns an API CONTRACT FEEDBACK section**: the API contract needs revision. Re-delegate to `backend-ts-architect` with the feedback: "Frontend architect identified issues with your API contract: [feedback]. Revise the affected endpoints." Then re-run `ui-engineer` with the revised contract. Max 1 revision round.
   - This prevents API contract mismatches between frontend and backend
 - In your Agent tool prompt, include:
+  - **Working directory: {worktree-abs-path}** — all file reads/edits must use this path
   - The task description from MEMORY.md / TODO.md
   - Relevant file paths and existing code references
   - Ask for the structured plan: EXISTING CODE, SCOPE, FILES, IMPLEMENTATION ORDER, INTERFACES, REUSE OPPORTUNITIES, PATTERNS, PITFALLS, TESTING, VERIFICATION
@@ -179,7 +233,8 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - DO NOT write your own plan instead of delegating
 
 **STEP 3: IMPLEMENT (following the agent's plan)**
-- Update MEMORY.md: set `Current Step: 3 — IMPLEMENT`
+- Update MEMORY.md (on main): set `Current Step: 3 — IMPLEMENT`
+- **All file operations in the worktree** (`Current Worktree` from MEMORY.md). Use absolute paths for Read/Edit/Write and `cd {worktree}` for Bash commands.
 - **CLI commands and Nx Generators FIRST**: Always prioritize using CLI commands and `nx generate` over manual file creation. NEVER manually create `project.json`, `tsconfig.*`, or configure build/test/lint targets — generators and CLI tools handle this correctly. NEVER manually install or configure build tools (tsup, esbuild, rollup, webpack) — Nx generators handle build configuration. Internal libs don't need a build step; publishable libs get `--bundler` from the generator. This includes:
   - **Workspace scaffolding** (Phase 0): `npx create-nx-workspace` — architect decides preset and flags
   - **Libraries/components/apps**: `nx generate` — see CLAUDE.md "Nx Generators" section
@@ -208,12 +263,13 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
     - Used within ONE library -> keep it local
 
 **STEP 4: WRITE TESTS — DELEGATE to `test-engineer` (when applicable)**
-- Update MEMORY.md: set `Current Step: 4 — TESTS`
+- Update MEMORY.md (on main): set `Current Step: 4 — TESTS`
 - Check the architect's **TESTING** section from STEP 2 — it lists which files need tests and what to test
 - If TESTING section lists files that need tests -> delegate to `test-engineer` agent
 - **Include the architect's TESTING section in the prompt** so test-engineer knows what was already decided
 - **Fallback**: If the architect's plan has no TESTING section, assume tests are needed for all new `business/` and `domain/` files
 - In your Agent tool prompt, include:
+  - **Working directory: {worktree-abs-path}** — all file reads/edits/test runs must use this path
   - The TESTING section from the architect's plan (file paths + test cases)
   - List of new/changed files
   - Ask for: TEST PLAN, then full .spec.ts implementation, then RUN all tests and report results
@@ -222,7 +278,8 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - **Error recovery**: If test-engineer agent fails, write basic smoke tests yourself and note in MEMORY.md
 
 **STEP 5: BUILD, LINT & TEST (with coverage)**
-- Update MEMORY.md: set `Current Step: 5 — BUILD`
+- Update MEMORY.md (on main): set `Current Step: 5 — BUILD`
+- **Run all commands in the worktree**: `cd {worktree-path} && ...`
 - Determine which projects to verify:
   - Use `nx affected --target=build --base=main --head=HEAD` to find affected projects
   - If `nx affected` is not available or unreliable, explicitly run for each project containing changed files:
@@ -237,16 +294,16 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - **SAFETY LIMIT: Max 3 fix attempts.** If still failing after 3:
   1. Delegate to the original architect agent: "Build/lint/test is failing after 3 fix attempts. Errors: [paste errors]. Suggest a fix or a different approach."
   2. If architect provides fix -> apply it, 1 more attempt
-  3. If still failing -> revert changes (`git stash --include-untracked -m "REVERTED: [task title] — build failure"`), return to main (`git checkout main 2>/dev/null || git checkout master`), delete orphaned branch (`git branch -D feat/{slug}`), mark task as `[~]` SKIPPED in TODO.md, log as BLOCKER in MEMORY.md with full error details, commit tracking on main (`git add TODO.md MEMORY.md && git commit -m "chore: skip [task title] — [brief reason]"`, push only if remote exists), move to next task
+  3. If still failing -> remove the worktree and branch (`git worktree remove --force .worktrees/feat/{slug} && git branch -D feat/{slug}`), clear `Current Worktree` from MEMORY.md, mark task as `[~]` SKIPPED in TODO.md, log as BLOCKER in MEMORY.md with full error details, commit tracking on main (`git add TODO.md MEMORY.md && git commit -m "chore: skip [task title] — [brief reason]"`, push only if remote exists), move to next task
 - DO NOT proceed to review with broken build or failing tests
 
 **STEP 6: VISUAL VERIFICATION (UI tasks only)**
-- Update MEMORY.md: set `Current Step: 6 — VISUAL VERIFY`
+- Update MEMORY.md (on main): set `Current Step: 6 — VISUAL VERIFY`
 - Skip this step for backend-only tasks
 - For frontend tasks, use Playwright MCP to verify visual output:
-  1. Start dev server if not running. **Important**: each Bash tool call runs in a separate shell, so PID variables don't persist. Start the server in one Bash call and leave it running:
+  1. Start dev server **from the worktree**. **Important**: each Bash tool call runs in a separate shell, so PID variables don't persist. Start the server in one Bash call and leave it running:
      ```bash
-     nx serve [FRONTEND_APP] &
+     cd {worktree-path} && nx serve [FRONTEND_APP] &
      # Wait for server readiness (max 60 seconds)
      for i in $(seq 1 60); do curl -s http://localhost:4200 > /dev/null 2>&1 && break; sleep 1; done
      ```
@@ -270,10 +327,11 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   ```
 
 **STEP 7: CODE REVIEW — DELEGATE to reviewer agent (MANDATORY)**
-- Update MEMORY.md: set `Current Step: 7 — REVIEW`
-- First, prepare the list of ALL changed/new files: `git diff --name-only` / `git status`
+- Update MEMORY.md (on main): set `Current Step: 7 — REVIEW`
+- First, prepare the list of ALL changed/new files in the worktree: `git -C {worktree-path} diff --name-only main` / `git -C {worktree-path} status`
 - Call the Agent tool with `senior-code-reviewer`
 - In your prompt, include:
+  - **Working directory: {worktree-abs-path}** — all file reads must use this path
   - The full list of changed files (including new .spec.ts files)
   - Brief description of what was implemented and why
   - **Include the architect's TESTING section** so reviewer knows which files were intentionally excluded from testing
@@ -283,7 +341,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - DO NOT skip this step even if you think the code is perfect
 
 **STEP 8: REWORK (based on reviewer's findings)**
-- Update MEMORY.md: set `Current Step: 8 — REWORK`
+- Update MEMORY.md (on main): set `Current Step: 8 — REWORK`
 - CRITICAL: Fix ALL. No exceptions.
 - WARN: Fix ALL. No exceptions.
 - NICE-TO-HAVE: Implement ALL that make sense.
@@ -291,23 +349,23 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - GREEN: No action, confirms correct direction.
 
 **STEP 9: RE-REVIEW — DELEGATE again (max 4 re-reviews here, 5 total with STEP 7)**
-- Update MEMORY.md: set `Current Step: 9 — RE-REVIEW`
+- Update MEMORY.md (on main): set `Current Step: 9 — RE-REVIEW`
 - After rework, call Agent tool with `senior-code-reviewer` AGAIN on changed files
 - If issues remain after re-review, return to STEP 8 for rework. Continue this STEP 8→9 loop until clean or safety limit reached.
 - **SAFETY LIMIT: Max 5 review cycles total (STEP 7 counts as cycle 1).** If still failing after 5:
   1. Delegate to the original architect agent: "Review cycle exceeded 5 iterations. Here are the remaining issues: [list]. Suggest a fundamentally different approach."
   2. If architect provides new approach -> restart from STEP 3 with new plan (counts as 1 additional attempt)
   3. If architect says issues are cosmetic/acceptable -> proceed with current code
-  4. If still stuck -> **SKIP this task**: revert with `git stash --include-untracked -m "REVERTED: [task title] — review cycle exceeded"`, return to main (`git checkout main 2>/dev/null || git checkout master`), delete orphaned branch (`git branch -D feat/{slug}`), mark as `- [~] ~~**Task**~~ — SKIPPED: review cycle exceeded, see MEMORY.md blocker` in TODO.md, log as BLOCKER in MEMORY.md with full details, commit tracking on main (`git add TODO.md MEMORY.md && git commit -m "chore: skip [task title] — [brief reason]"`, push only if remote exists), move to next task
+  4. If still stuck -> **SKIP this task**: remove worktree and branch (`git worktree remove --force .worktrees/feat/{slug} && git branch -D feat/{slug}`), clear `Current Worktree` from MEMORY.md, mark as `- [~] ~~**Task**~~ — SKIPPED: review cycle exceeded, see MEMORY.md blocker` in TODO.md, log as BLOCKER in MEMORY.md with full details, commit tracking on main (`git add TODO.md MEMORY.md && git commit -m "chore: skip [task title] — [brief reason]"`, push only if remote exists), move to next task
 
 **STEP 10: FINAL VERIFICATION**
-- Update MEMORY.md: set `Current Step: 10 — FINAL VERIFY`
-- Run the same affected project commands as STEP 5 (build, lint, test)
+- Update MEMORY.md (on main): set `Current Step: 10 — FINAL VERIFY`
+- Run the same affected project commands as STEP 5 in the worktree (build, lint, test)
 - If any fail after review rework: fix and re-verify (do NOT go back to review for build fixes)
 
 **STEP 11: COMMIT & PUSH**
-- Update MEMORY.md: set `Current Step: 11 — COMMIT`
-- **First, update tracking files** (so they are included in the same commit):
+- Update MEMORY.md (on main): set `Current Step: 11 — COMMIT`
+- **First, update tracking files on main** (project root):
   - **TODO.md**: Check off the completed task: `- [x] **Task** — description ([date])`
     - For skipped tasks: `- [~] ~~**Task**~~ — SKIPPED: [brief reason]`
   - **MEMORY.md** — set the FINAL state here (no further commits after merge):
@@ -317,22 +375,34 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
     - Update `Complexity This Session` (add S=1, M=2, L=4 for completed task)
     - Set `Current Task` to `(none)`
     - Set `Current Step` to `(none)`
+    - Set `Current Worktree` to `(none)`
     - Decisions, Blockers, Notes sections
-- **Stage ALL files in a single commit** — NEVER `git add -A`:
+- **Copy tracking files into the worktree** (so they are part of the same commit):
   ```bash
-  git add [source files] [test files] [migration files] TODO.md MEMORY.md
+  cp TODO.md MEMORY.md {worktree-path}/
+  ```
+- **Stage ALL files in the worktree in a single commit** — NEVER `git add -A`:
+  ```bash
+  cd {worktree-path} && git add [source files] [test files] [migration files] TODO.md MEMORY.md
   ```
   - Include ALL files that are part of this task: source, tests, migrations, config changes, PLUS tracking files (TODO.md, MEMORY.md)
-  - If unsure about a file, check `git diff [file]` — if it's related to this task, include it
+  - If unsure about a file, check `git -C {worktree-path} diff [file]` — if it's related to this task, include it
 - Descriptive message, English, focus on "why" not "what"
 - Conventional commits: feat/fix/refactor/chore/docs
 - **Single commit** (implementation + tracking together — no separate "chore: update progress tracking"):
+  ```bash
+  cd {worktree-path} && git commit -m "[type]: [message]"
+  ```
   - If git integration is active (TODO.md has `<!-- #N -->` markers): `git commit -m "[type]: [message] (#N)"` — always include the task ID reference. Example: `git commit -m "feat: add user authentication flow (#42)"`
   - If no git integration: `git commit -m "[type]: [message]"`
+- **Discard uncommitted tracking changes on main** (they will come back via merge):
+  ```bash
+  git checkout -- MEMORY.md TODO.md
+  ```
 - If git integration is active (TODO.md has `<!-- #N -->` markers):
-  - Delegate to `devops-integrator` agent: "Task #N is committed. Push branch, create MR/PR with 'Closes #N'. Update issue status to in-review."
+  - Delegate to `devops-integrator` agent: "Task #N is committed in worktree at `{worktree-path}`. Push branch from the worktree (`git -C {worktree-path} push -u origin HEAD`), create MR/PR with 'Closes #N'. Update issue status to in-review."
 - If no git integration:
-  - `git remote -v | grep origin` — if remote exists: `git push -u origin HEAD`. If no remote: skip push (local-only mode).
+  - `git remote -v | grep origin` — if remote exists: `cd {worktree-path} && git push -u origin HEAD`. If no remote: skip push (local-only mode).
 - **Rollback plan**: If push fails or MR/PR creation fails:
   1. Check error message — auth issue? network? conflict?
   2. If merge conflict -> go to "Merge Conflicts" section
@@ -340,19 +410,13 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   4. Commit is still local and safe — do NOT reset or amend without reason
 
 **STEP 12: POST-MERGE & NEXT ITEM**
-- Working tree is now **clean** (everything committed in STEP 11, including final MEMORY.md state).
-- **ZERO commits in this step** — all tracking was already committed in STEP 11. This step only performs git operations (merge, checkout, push, branch delete) and delegates issue status updates. Do NOT create any "chore: update progress tracking" commits.
-- **Worktree handling**: If any `git checkout main` below fails with "already checked out at" error (you're in a git worktree while main is checked out elsewhere):
-  1. Merge without checkout: `git fetch . feat/{branch-name}:main` (fast-forwards local main). If not a fast-forward (main diverged), rebase first: `git rebase main && git fetch . HEAD:main`.
-  2. Detach HEAD: `git checkout --detach`
-  3. Delete feature branch: `git branch -d feat/{branch-name}`
-  4. Skip `git pull --rebase origin HEAD` here — health check syncs at next iteration start.
-  5. Continue to next task from the detached state (STEP 1 will create a new feature branch).
+- Everything was committed in STEP 11 inside the worktree. The project root (on main) has a clean working tree (tracking changes were discarded in STEP 11).
+- **ZERO commits in this step** — all tracking was already committed in STEP 11. This step only performs git operations (merge, worktree cleanup, push) and delegates issue status updates.
 - **Solo workflow** (CLAUDE.md `Workflow: solo` or default):
   - **If git integration active** (MR/PR was created in STEP 11):
-    - Ensure latest commit is pushed:
+    - Ensure latest commit is pushed from worktree:
       ```bash
-      git push origin HEAD
+      git -C {worktree-path} push origin HEAD
       ```
     - Merge via platform to properly close the MR/PR (if CI status checks are required, this will fail — use local merge fallback below):
       ```bash
@@ -361,43 +425,46 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
       # GitLab
       glab mr merge --remove-source-branch
       ```
-    - Then sync local:
+    - Then sync local main:
       ```bash
-      git checkout main 2>/dev/null || git checkout master
       git pull --rebase origin HEAD
-      git branch -d feat/{branch-name} 2>/dev/null || true
+      ```
+    - Clean up worktree and branch:
+      ```bash
+      git worktree remove .worktrees/feat/{slug}
+      git branch -d feat/{slug} 2>/dev/null || true
       ```
     - Delegate to `devops-integrator`: "Update issue #N status to done. Do NOT perform any git operations or file edits — already handled."
   - **If no git integration** (no MR/PR):
-    - Merge locally:
+    - If remote exists: `git pull --rebase origin HEAD` before merge
+    - Merge locally (from project root, which is on main):
       ```bash
-      git checkout main 2>/dev/null || git checkout master
-      git merge feat/{branch-name} --no-ff
+      git merge feat/{slug} --no-ff
       ```
     - If merge fails due to conflicts: follow the "Merge Conflicts" section below, then retry
-    - If remote exists (`git remote -v | grep origin`): `git pull --rebase origin HEAD` before merge, `git push origin HEAD` after merge. If push fails (branch protection, auth): log blocker, leave commit local.
+    - If remote exists: `git push origin HEAD` after merge. If push fails (branch protection, auth): log blocker, leave commit local.
     - If no remote: skip pull/push (local-only mode)
-    - Delete merged branch: `git branch -d feat/{branch-name}`
+    - Clean up worktree and branch:
+      ```bash
+      git worktree remove .worktrees/feat/{slug}
+      git branch -d feat/{slug}
+      ```
   - If platform merge fails (auth, permissions):
     - Fall back to local merge (same as no-git-integration path above)
     - Delegate to `devops-integrator`: "Update issue #N status to done. Do NOT perform any git operations or file edits — already handled."
 - **Team workflow** (CLAUDE.md `Workflow: team`):
-  - If remote exists: push the branch:
+  - If remote exists: push from worktree: `git -C {worktree-path} push origin HEAD`
+  - Clean up worktree (branch stays for MR/PR review):
     ```bash
-    git push origin HEAD
+    git worktree remove .worktrees/feat/{slug}
     ```
-  - Switch to main for the next task:
+  - If remote exists: sync main: `git pull --rebase origin HEAD`
+  - If git integration active: delegate to `devops-integrator`: "Update issue #N status to in-review. Do NOT perform any git operations."
+  - Next task: if the next task depends on the previous (unmerged) MR/PR, create worktree from previous branch:
     ```bash
-    git checkout main 2>/dev/null || git checkout master
+    git worktree add .worktrees/feat/{next} -b feat/{next} feat/{previous}
     ```
-  - If remote exists: `git pull --rebase origin HEAD`
-  - If git integration active: delegate to `devops-integrator`: "Update issue #N status to in-review. Do NOT perform any git operations."
-  - Start next task:
-    - If the next task depends on the previous (unmerged) MR/PR:
-      - Stack branches: `git checkout -b feat/{next} feat/{previous}` (branch from previous feature branch)
-      - Note the stacking in MEMORY.md
-      - When the previous MR/PR is merged, rebase: `git rebase --onto main feat/{previous} feat/{next}`
-    - Otherwise: `git checkout -b feat/{next-task-slug}`
+    Note the stacking in MEMORY.md. When the previous MR/PR is merged: `git -C .worktrees/feat/{next} rebase --onto main feat/{previous}`
 - **If no `[ ]` tasks remain in current phase AND at least one `[~]` exists** (all remaining were skipped): do NOT auto-advance. Delegate to `product-owner`: "All tasks in Phase [N] are blocked/skipped. The autonomous loop cannot proceed. Options: (1) ADD replacement tasks that unblock progress, (2) REPRIORITIZE to skip this phase entirely and move to next, (3) declare a BLOCKER requiring human intervention." If product-owner returns only CONFIRM with no actionable changes, STOP the autonomous loop and log: "Phase [N] fully blocked — requires human intervention. Run orchestrator manually after resolving blockers."
 - One task per invocation — after post-merge, end session. The external loop will start the next invocation. Do NOT update MEMORY.md here (already done in STEP 11).
 - **If no `[ ]` tasks remain in current phase AND zero `[~]` exist** (all completed) -> phase transition (handled at start of STEP 1)
@@ -420,7 +487,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 
 When creating MEMORY.md (health check step 5.4), use the same template as `project-initializer` agent (Step 8). The required sections are:
 
-- `Current Phase`, `Current Task`, `Current Step` — workflow state tracking
+- `Current Phase`, `Current Task`, `Current Step`, `Current Worktree` — workflow state tracking
 - `Complexity This Session` — informational tracking (S=1, M=2, L=4)
 - `Session Config` — app names + workflow mode from CLAUDE.md
 - `Done`, `Next` — task progress
@@ -432,16 +499,16 @@ When creating MEMORY.md (health check step 5.4), use the same template as `proje
 
 For critical production bugs (outside normal TODO.md flow):
 
-1. Create branch: `git checkout -b fix/{description}`
-2. Delegate to architect agent for minimal fix plan (STEP 2 — cannot be skipped)
+1. Create worktree: `git worktree add .worktrees/fix/{description} -b fix/{description}` — store in MEMORY.md `Current Worktree`
+2. Delegate to architect agent for minimal fix plan (STEP 2 — cannot be skipped). Include `Working directory: {worktree-abs-path}` in prompt.
 3. Implement fix (STEP 3)
 4. Build, lint & test (STEP 5)
 5. Code review (STEP 7 — cannot be skipped). **Include in reviewer prompt**: "NOTE: This is a hotfix. Test writing was intentionally deferred — do not flag missing test coverage for this change."
 6. If reviewer finds CRITICAL or WARN issues: set `Current Step: 7 — REVIEW (hotfix rework)`, fix them and re-review (max 2 cycles for hotfixes). If still failing, commit anyway with a note in MEMORY.md — hotfix urgency takes priority.
-7. Commit & push (STEP 11) — include in the SAME commit:
-   - MEMORY.md: add note under "Notes": `Hotfix: [description] ([date])`, set `Current Task` to `(none)`, `Current Step` to `(none)`
+7. Commit & push from worktree (STEP 11) — include in the SAME commit:
+   - Copy MEMORY.md into worktree. MEMORY.md: add note under "Notes": `Hotfix: [description] ([date])`, set `Current Task` to `(none)`, `Current Step` to `(none)`, `Current Worktree` to `(none)`
    - Do NOT update TODO.md checkboxes unless the fix corresponds to an existing task
-8. Post-merge: follow STEP 12 logic (solo: merge to main, team: MR/PR). No additional commits.
+8. Post-merge: follow STEP 12 logic (merge to main from project root, clean up worktree + branch). No additional commits.
 9. **Patch release**: if git integration active, delegate to `devops-integrator`: "Hotfix merged. Create a patch release with changelog."
 
 **Skipped steps:** STEP 4 (tests — unless the bug reveals missing test coverage), STEP 6 (visual verification).
@@ -452,19 +519,20 @@ For critical production bugs (outside normal TODO.md flow):
 
 If a merge conflict occurs:
 
-**During feature branch development** (STEP 3-10):
-1. `git fetch origin main && git rebase origin/main`
+**During feature branch development** (STEP 3-10, in worktree):
+1. `cd {worktree-path} && git fetch origin main && git rebase origin/main`
 2. Resolve conflicts manually — prefer keeping both changes when possible
-3. Re-run STEP 5 (build, lint & test) after resolution
+3. Re-run STEP 5 (build, lint & test) in the worktree after resolution
 4. If conflict changes are significant (not just trivial merge): re-run STEP 7 (code review) on affected files
-5. If rebase is too complex: `git merge origin/main` instead (creates merge commit but is safer)
+5. If rebase is too complex: `cd {worktree-path} && git merge origin/main` instead (creates merge commit but is safer)
 6. Log the conflict resolution in MEMORY.md Notes
 
-**During `git merge feat/branch` on main** (STEP 12 solo/no-git path):
+**During `git merge feat/branch` on main** (STEP 12, from project root):
 1. Resolve the conflict in the merge commit (do NOT rebase here — you are on main)
 2. `git add [resolved files]` (only resolved files — do NOT use `git add .`), then `git merge --continue`
-3. Re-run STEP 5 to verify the merged result
+3. Verify the merged result: build, lint, test from project root
 4. Push: `git push origin HEAD`
+5. Then clean up: `git worktree remove .worktrees/feat/{slug} && git branch -d feat/{slug}`
 
 ## Tech Debt & Refactoring
 
@@ -484,7 +552,7 @@ NEVER stay stuck. Escalation order:
 **A: RESEARCH** — Explore codebase, WebSearch for docs
 **B: ARCHITECT** — Delegate to `backend-ts-architect` or `ui-engineer` with problem description
 **C: DECIDE** — Pick best approach, log to MEMORY.md
-**D: SKIP (last resort)** — Only if blocker is objectively unresolvable. Revert changes (`git stash --include-untracked -m "REVERTED: [task title]"`), return to main (`git checkout main 2>/dev/null || git checkout master`), delete orphaned branch (`git branch -D feat/{slug}`). Then log everything in MEMORY.md Blockers section, mark task as `[~]` SKIPPED in TODO.md with reason, commit tracking on main (`git add TODO.md MEMORY.md && git commit -m "chore: skip [task title] — [brief reason]"`, push only if remote exists), move to next task.
+**D: SKIP (last resort)** — Only if blocker is objectively unresolvable. Remove worktree and branch (`git worktree remove --force .worktrees/feat/{slug} && git branch -D feat/{slug}`). Clear `Current Worktree` from MEMORY.md. Log everything in MEMORY.md Blockers section, mark task as `[~]` SKIPPED in TODO.md with reason, commit tracking on main (`git add TODO.md MEMORY.md && git commit -m "chore: skip [task title] — [brief reason]"`, push only if remote exists), move to next task.
 
 ## End-of-Iteration Output
 

package/dist/template/.claude/agents/project-initializer.md

@@ -253,6 +253,9 @@ Phase 0: Foundation
 ## Current Step
 (none)
 
+## Current Worktree
+(none)
+
 ## Iterations This Session
 0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-workspace",
-  "version": "1.1.30",
+  "version": "1.1.31",
   "description": "Scaffold a project with Claude Code agents for autonomous AI-driven development",
   "type": "module",
   "bin": {