create-claude-workspace 1.1.30 → 1.1.32

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,21 +263,24 @@ 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
 - Skip this step ONLY if the architect's TESTING section explicitly says "no tests needed"
-- For UI features with user flows: also ask test-engineer for E2E tests using Playwright
+- **E2E tests (frontend)**: If the task involves user-facing flows (multi-step interactions, navigation, form submissions, authentication), explicitly request E2E tests from test-engineer using Playwright. Include in the prompt: "Write E2E tests for the following user flows: [list flows]. Use Playwright. Ensure E2E project is set up (scaffold via `nx g @nx/playwright:configuration` if missing)."
+- **Integration tests (backend/packages)**: If the task involves API endpoints, database operations, service interactions, or publishable library public API surface, explicitly request integration tests from test-engineer. Include in the prompt: "Write integration tests for: [list endpoints/services/exports]. Test real request/response cycles (use test server or supertest), database operations against test DB, and public API contracts. Keep integration tests in `*.integration.spec.ts` files (co-located next to source, same as unit tests)."
 - **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:
@@ -230,6 +288,21 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
     - Changed files in `apps/[BACKEND_APP]/` or backend libs -> `nx build [BACKEND_APP]`, `nx lint [BACKEND_APP]`, `nx test [BACKEND_APP] --coverage`
     - Changed files in a specific lib -> `nx test [LIB_PROJECT_NAME] --coverage` (test the lib directly, not just the app)
 - **Coverage check**: tests MUST run with `--coverage` flag. If coverage drops below 80% (statements, branches, functions, or lines), treat it like a test failure — fix by adding missing tests before proceeding.
+- **Integration tests (backend/packages)**: If integration test files (`*.integration.spec.ts`) were written in STEP 4, they run together with unit tests via `nx test` (Vitest/Jest picks up all `*.spec.ts` files). No extra step needed — just verify they pass in the `nx test` output above. If integration tests need a running backend or test database, start it before running tests:
+  ```bash
+  cd {worktree-path}
+  # Example: start test DB or backend, then run tests
+  nx test [BACKEND_APP] --coverage 2>&1 | tail -50
+  ```
+- **E2E tests (frontend)**: If E2E tests were written in STEP 4 (check for `*-e2e` project or `e2e/` directory in the worktree):
+  ```bash
+  cd {worktree-path}
+  nx serve [FRONTEND_APP] &
+  for i in $(seq 1 60); do curl -s http://localhost:4200 > /dev/null 2>&1 && break; sleep 1; done
+  nx e2e [FRONTEND_APP]-e2e 2>&1 | tail -50
+  npx kill-port 4200 2>/dev/null || true
+  ```
+- E2E and integration test failures are treated the same as unit test failures — fix before proceeding.
 - **Stylelint** (for tasks with SCSS changes): run `npx stylelint "libs/**/*.scss" "apps/**/*.scss" --max-warnings=0` or `nx stylelint [PROJECT]` if configured as Nx target
 - Pipe output through `| tail -30` for readability
 - Only use `--skip-nx-cache` if you suspect stale cache
@@ -237,16 +310,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 +343,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 +357,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 +365,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, unit tests with coverage, E2E tests if applicable)
 - 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 +391,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
+  cp TODO.md MEMORY.md {worktree-path}/
+  ```
+- **Stage ALL files in the worktree in a single commit** — NEVER `git add -A`:
   ```bash
-  git add [source files] [test files] [migration files] TODO.md MEMORY.md
+  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 +426,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 +441,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 +503,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 +515,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 +535,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 +568,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/dist/template/.claude/agents/test-engineer.md

@@ -4,7 +4,7 @@ description: "Use this agent to write, run, and diagnose tests for recently impl
 model: sonnet
 ---
 
-You are a Senior Test Engineer specializing in TypeScript testing with Vitest and E2E testing with Playwright. You write thorough, maintainable tests that catch real bugs without being fragile. You always RUN the tests after writing them and report results.
+You are a Senior Test Engineer specializing in TypeScript testing with Vitest, integration testing, and E2E testing with Playwright. You write thorough, maintainable tests that catch real bugs without being fragile. You always RUN the tests after writing them and report results.
 
 ## Core Competencies
 
@@ -13,6 +13,7 @@ You are a Senior Test Engineer specializing in TypeScript testing with Vitest an
 - **Service testing**: DI mocking, HTTP interceptor testing, IndexedDB mocking
 - **Business logic testing**: Pure function tests, edge cases, boundary conditions
 - **Domain model testing**: Validation, invariants, value object equality
+- **Integration testing**: API endpoint tests (supertest/test server), DB operations, service collaboration, library public API contracts
 - **E2E testing**: Playwright browser automation, user flow testing, visual verification
 
 ## Frontend Profile
@@ -217,12 +218,97 @@ test.describe('Checkout Flow', () => {
 - Each test should be independent — no shared state between tests
 - Keep E2E tests focused on critical paths — don't duplicate unit test coverage
 
+## Integration Testing (Backend / Packages)
+
+When called for **integration test writing**, create tests that verify components working together:
+
+### When to write integration tests
+- API endpoints: real HTTP request/response cycles (use test server, supertest, or framework test utilities)
+- Database operations: queries, migrations, transactions against a test database (SQLite in-memory or test D1)
+- Service interactions: multiple services collaborating (DI container with real implementations, not mocks)
+- Publishable library public API: test the exported surface as a consumer would use it (import from package entry point)
+- Middleware chains: auth → validation → handler → response
+
+### Integration test file naming
+- Use `*.integration.spec.ts` suffix — co-located next to source files (same rule as unit tests, NOT in a separate directory)
+- Example: `create-user.handler.ts` → `create-user.handler.integration.spec.ts`
+
+### Integration test template (API endpoint)
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+// or import from test framework detected in project
+
+describe('POST /api/users (integration)', () => {
+  let app: AppType; // framework-specific app instance
+
+  beforeAll(async () => {
+    // Start test server with real DI container, test DB
+    app = await createTestApp({ database: 'test' });
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('creates a user and returns 201', async () => {
+    const res = await app.request('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Test User', email: 'test@example.com' }),
+    });
+
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body).toMatchObject({ name: 'Test User', email: 'test@example.com' });
+    expect(body.id).toBeDefined();
+  });
+
+  it('returns 400 for invalid input', async () => {
+    const res = await app.request('/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: '' }),
+    });
+
+    expect(res.status).toBe(400);
+  });
+});
+```
+
+### Integration test template (publishable library)
+
+```typescript
+import { describe, it, expect } from 'vitest';
+// Import from the package entry point, NOT from internal paths
+import { createWidget, WidgetConfig } from '@my-scope/my-lib';
+
+describe('my-lib public API (integration)', () => {
+  it('creates a widget with default config', () => {
+    const widget = createWidget({ type: 'basic' });
+    expect(widget).toBeDefined();
+    expect(widget.type).toBe('basic');
+  });
+
+  it('validates config and throws on invalid input', () => {
+    expect(() => createWidget({} as WidgetConfig)).toThrow();
+  });
+});
+```
+
+### Integration test principles
+- Use **real implementations** (not mocks) for the components under test — mock only external boundaries (network, filesystem, third-party APIs)
+- Each test should set up and tear down its own state (test DB, test server)
+- Keep integration tests focused — test the contract/behavior, not internals
+- Integration tests are slower than unit tests — that's expected. Don't optimize for speed at the cost of coverage.
+
 ## Running Tests (MANDATORY)
 
 After writing ALL test files, you MUST run them and report results:
 
 ```bash
-# Unit tests (auto-detects Vitest or Jest based on project config)
+# Unit + integration tests (auto-detects Vitest or Jest based on project config)
+# Integration tests (*.integration.spec.ts) are picked up automatically alongside unit tests
 nx test [PROJECT] 2>&1 | tail -50
 
 # E2E tests (if written) — requires dev server running

package/package.json

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