cc-workspace 4.7.1 → 5.2.1

package/global-skills/cleanup/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: cleanup
+prompt_version: 5.2.1
 description: >
   Clean orphan worktrees, stale sessions, and temporary files left by
-  crashed implementers. Safe to run anytime — only removes /tmp/ worktrees
-  and closed/stale sessions.
+  crashed implementers. Session-aware: never removes worktrees belonging
+  to active sessions. Safe to run anytime.
   Use: /cleanup
 argument-hint: ""
 context: fork
@@ -12,35 +13,48 @@ allowed-tools: Bash, Read, Glob, Grep
 
 # Cleanup — Orphan Worktree & Session Cleaner
 
-## Step 1: Find orphan worktrees in /tmp/
+## CRITICAL: Session-aware worktree cleanup
+
+**NEVER remove worktrees that belong to active sessions.**
+Active session worktrees persist until `session close` — this is by design.
+Only remove worktrees that have NO corresponding active session JSON entry.
+
+## Step 1: Identify session worktrees (do NOT touch these)
+
+```bash
+# List all worktree paths referenced by active sessions
+find ./.sessions -name "*.json" -exec jq -r 'select(.status=="active") | .repos[].worktree_path' {} \; 2>/dev/null
+```
+
+Note these paths. Skip them in all subsequent cleanup steps.
+
+## Step 2: Find truly orphaned worktrees in /tmp/
 
 ```bash
-# List all potential orchestrator worktrees
 ls -d /tmp/*-session-* /tmp/e2e-* 2>/dev/null || echo "No worktrees found in /tmp/"
 ```
 
-For each found worktree:
+For each found worktree that is NOT in the active session list:
 1. Check if it's still registered with a repo:
    ```bash
-   # Find the parent repo by checking all sibling repos
    for repo in ../*/; do
      [ -d "$repo/.git" ] || continue
      git -C "$repo" worktree list 2>/dev/null | grep "/tmp/worktree-path"
    done
    ```
-2. If registered but the directory is invalid → prune:
+2. If registered but invalid → prune:
    ```bash
-   git -C ../[repo] worktree prune
+   git -C ../{repo} worktree prune
    ```
 3. If not registered → safe to remove:
    ```bash
-   rm -rf /tmp/[worktree-path]
+   rm -rf /tmp/{worktree-path}
    ```
 
 Present what was found and ask the user before deleting:
-> "Found N orphan worktrees. Remove them? [y/N]"
+> "Found N orphan worktrees (not linked to any active session). Remove them? [y/N]"
 
-## Step 2: Find stale sessions
+## Step 3: Find stale sessions
 
 Read `.sessions/*.json`. A session is stale if:
 - Status is "closed"
@@ -48,29 +62,24 @@ Read `.sessions/*.json`. A session is stale if:
 
 For stale sessions, show:
 ```
-| Session | Status | Created | Repos | Action |
-|---------|--------|---------|-------|--------|
-| feature-old | closed | 2026-01-15 | api, front | Delete JSON? |
-| feature-stuck | active | 2026-01-20 | api | Stale (37 days) |
+| Session | Status | Created | Repos | Worktrees | Action |
+|---------|--------|---------|-------|-----------|--------|
+| feature-old | closed | 2026-01-15 | api, front | /tmp/api-feature-old (missing) | Delete JSON? |
+| feature-stuck | active | 2026-01-20 | api | /tmp/api-feature-stuck (exists!) | Stale (37d) |
 ```
 
-Ask before each deletion.
-
-For active stale sessions, also check if session branches exist:
-```bash
-git -C ../[repo] branch --list session/[name] 2>/dev/null
-```
+For stale ACTIVE sessions with existing worktrees: warn strongly before suggesting removal.
+These might be legitimate long-running sessions.
 
-## Step 3: Clean modified-files.log
+## Step 4: Clean modified-files.log
 
 ```bash
-# Truncate if larger than 1000 lines
 wc -l .claude/modified-files.log 2>/dev/null
 ```
 
 If >1000 lines, ask to truncate to last 200 lines.
 
-## Step 4: Docker cleanup (optional)
+## Step 5: Docker cleanup (optional)
 
 Check for dangling E2E containers:
 ```bash
@@ -87,7 +96,8 @@ docker compose -f ./e2e/docker-compose.e2e.yml down -v 2>/dev/null
 Summary of actions taken:
 ```
 Cleanup complete:
-- Removed N orphan worktrees
+- Active session worktrees preserved: N (not touched)
+- Removed N orphan worktrees (no active session)
 - Deleted N stale session files
 - Pruned modified-files.log (was X lines → 200)
 - Removed N dangling containers

package/global-skills/cross-service-check/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: cross-service-check
+prompt_version: 5.2.1
 description: >
   Validate technical consistency BETWEEN services. Does not review code
   quality (that's qa-ruthless). Checks: API contracts match frontend types,

package/global-skills/cycle-retrospective/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: cycle-retrospective
+prompt_version: 5.2.1
 description: >
-  Post-cycle learning and knowledge capture. Analyzes QA findings, teammate
-  reports, and implementation patterns to improve repo CLAUDE.md files,
-  service profiles, and project constitution. Run after a successful cycle
-  (dispatch → QA → merge). Use when user says "retro", "rétrospective",
+  MANDATORY post-cycle learning and knowledge capture. Always runs as Phase 5
+  of dispatch-feature after qa-ruthless and merge-prep. Analyzes QA findings, teammate
+  session logs, and implementation patterns to improve repo CLAUDE.md files,
+  service profiles, and project constitution.
+  Also triggered manually when user says "retro", "rétrospective",
   "capitalize", "lessons learned", "what did we learn", "improve docs".
 argument-hint: "[feature-name]"
 context: fork

package/global-skills/dispatch-feature/SKILL.md

@@ -1,20 +1,24 @@
 ---
 name: dispatch-feature
+prompt_version: 5.2.1
 description: >
-  Orchestrate multi-service feature implementation. Clarifies ambiguities
-  before planning, writes a persistent markdown plan, spawns teammates
-  in dependency waves with full context including constitution and UX standards.
+  Orchestrate multi-service feature implementation. Clarifies ambiguities,
+  explores repos directly (no upfront Haiku scan), writes a persistent
+  markdown plan, sets up git branches and worktrees after plan validation,
+  spawns one teammate per repo with full context, runs micro-QA between
+  each commit, then runs cross-service-check, qa-ruthless, reviewer,
+  security-auditor (when needed), merge-prep, and cycle-retrospective.
   Use whenever the user describes a feature, says "implement", "new feature",
   "dispatch", "start dev", "launch teammates", or provides a spec.
 argument-hint: "[feature description]"
 context: fork
-allowed-tools: Read, Write, Glob, Grep, Task, Teammate, SendMessage
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, Teammate, SendMessage
 ---
 
-# Dispatch Feature — Clarify, Plan, Delegate, Track
+# Dispatch Feature — Clarify, Plan, Git, Delegate, Track
 
-You produce ZERO code in repos. You clarify, plan, delegate, track.
-You CAN write in orchestrator/ (plans, workspace.md, constitution.md).
+You produce ZERO code in repos. You clarify, plan, manage git, delegate, track.
+You CAN write in orchestrator/ and run git/bash commands directly.
 
 ## Mode detection
 
@@ -22,13 +26,36 @@ Before any phase, check which mode was selected:
 
 | Mode | Behavior |
 |------|----------|
-| **A — Complet** | Run all phases 0-5 (default) |
-| **B — Plan rapide** | Skip Phase 0 (Clarify). Start at Phase 2 with specs as-is. |
+| **A — Full** | All phases 0-5 (default) |
+| **B — Quick plan** | Skip Phase 0 (Clarify). Start at Phase 1 exploration with specs as-is. |
 | **C — Go direct** | Skip Phases 0-2. Dispatch immediately from user specs. |
 | **D — Single-service** | Phases 0-2, then spawn ONE teammate. No waves. |
 
 If no mode specified, use Mode A.
 
+### Mode B — Quick plan details
+
+User provides clear specs upfront (e.g. a Jira ticket, a detailed description).
+1. Skip Phase 0 entirely — do NOT ask clarification questions
+2. Run Phase 1 (targeted exploration) scoped to the user's specs
+3. Run Phase 2 (plan) — write the plan from specs + exploration
+4. Phases 2.5–5 proceed normally (git setup, dispatch, micro-QA, post-impl)
+5. If ambiguities emerge during exploration, ask then (max 3 focused questions)
+
+### Mode C — Go direct details
+
+For hotfixes, quick patches, or when the user provides exact instructions.
+1. Skip Phases 0–2 — no clarification, no exploration, no written plan
+2. Run Phase 2.5 (git setup) — still create session branch + worktree
+3. Spawn ONE teammate per impacted repo with the user's specs as-is
+4. Micro-QA still runs after each commit (Phase 4 is NOT skipped)
+5. Post-impl: skip cross-service-check, run qa-ruthless (scoped), merge-prep, retro
+6. Write a minimal plan retroactively after dispatch for traceability
+
+### Mode D — Single-service details
+
+See dedicated section below (## Mode D: Single-service).
+
 ## Phase 0: Clarify
 
 Run through this checklist SILENTLY. Only ask for items you cannot deduce:
@@ -42,42 +69,59 @@ Run through this checklist SILENTLY. Only ask for items you cannot deduce:
 **Should-know** (ask if ambiguous):
 - Error handling? Permissions? Trigger mechanism? Dependencies?
 
+**Source branch override** — detect in the user's prompt:
+- "fix on hotfix/payment" → source = hotfix/payment
+- "refacto from develop" → source = develop
+- (no mention) → use source_branch from workspace.md per repo
+
 **Rules**: max 5 questions at once, formulated as concrete choices.
 Skip clarify if: bug with log provided, or user says "go"/"autonome".
 
-## Phase 1: Load context
+**Example — good vs bad clarification questions:**
 
-1. Read `./workspace.md`
-2. Read `./plans/service-profiles.md`
-3. Read `./constitution.md` (project-specific rules)
-4. Auto-discover repos: scan `../` for directories with `.git/` not in workspace.md
-   → If new repos found: mention them, ask if relevant to this feature
+Bad (vague, open-ended):
+> "How should the feature handle errors?"
+> "What permissions do you want?"
 
-> The constitution is defined in your workspace's constitution.md.
-> Teammates do NOT receive it automatically. You MUST include all rules
-> from constitution.md in every spawn prompt.
+Good (concrete choices, actionable):
+> "When invoice PDF generation fails: (a) retry 3× then notify user, (b) queue for manual retry, or (c) fail silently with error log?"
+> "Access control for this endpoint: (a) any authenticated user, (b) company admin only, or (c) role-based with a new permission?"
 
-## Phase 2: Write the plan
+## Phase 1: Targeted exploration (Opus direct — no Haiku upfront)
 
-Create `./plans/{feature-name}.md` using `./plans/_TEMPLATE.md`.
-Include: context, clarification answers, services impacted, dependency waves,
-detailed tasks per service, API contract (exact shapes), and autonomous choices if applicable.
+Read directly using available tools. Do NOT spawn a Haiku explorer at this phase.
 
-### Commit planning (mandatory — each commit unit = one implementer spawn)
+**Constraint**: only read files directly related to the feature.
 
-**CRITICAL**: Each commit unit in the plan becomes a separate `Task(implementer)` spawn.
-The team-lead dispatches them sequentially per service. Size them accordingly:
-- **Too granular** (10+ per service) = excessive spawns, slow, expensive
-- **Too coarse** (1 giant unit) = defeats atomic commit purpose
-- **Sweet spot**: 2-5 units per service, ~100-300 lines each
+```bash
+# Step 1: orientation
+cat ./workspace.md
+cat ./plans/service-profiles.md
+cat ./constitution.md
 
-Typical split for a standard feature:
-- **Commit 1**: Data layer — models, migrations, DTOs, repositories
-- **Commit 2**: Business logic — use cases, services, validation
-- **Commit 3**: API/UI layer — controllers, routes, components, pages
-- **Commit 4**: Tests for the above
+# Step 2: read CLAUDE.md of potentially impacted repos
+cat ../{repo}/CLAUDE.md
+
+# Step 3: targeted grep/glob on the feature scope only
+grep -r "EntityName\|routeName" ../{repo}/src/ --include="*.php" -l
+find ../{repo}/src -name "*.ts" | xargs grep "InterfaceName" -l 2>/dev/null
+```
+
+Auto-discover repos: scan ../ for directories with .git/ not in workspace.md.
+If new repos found: mention them, ask if relevant to this feature.
+
+Do NOT scan entire repos. Do NOT read files unrelated to the feature scope.
 
-For a small fix: **1 single commit unit** (no unnecessary splitting).
+## Phase 2: Write the plan
+
+Create ./plans/{feature-name}.md using ./plans/_TEMPLATE.md.
+
+Include: context, clarification answers, effective source branch per repo, dependency waves,
+commit units per repo, API contract (exact shapes), progress tracker.
+
+### Commit unit sizing (CRITICAL — each unit = one teammate commit)
+
+The teammate handles ALL commits sequentially. Size them for clarity, not spawning overhead:
 
 | Service complexity | Recommended commit units |
 |--------------------|--------------------------|
@@ -86,177 +130,185 @@ For a small fix: **1 single commit unit** (no unnecessary splitting).
 | Standard feature | 3-5 |
 | Complex feature | 4-6 (max) |
 
-Each commit unit in the plan must:
-- Have a descriptive title (becomes the commit message)
-- List the specific tasks it covers
-- Estimate ~N files, ~N lines
-- Be independently compilable and testable
-- Be **self-contained enough for a fresh implementer** — an implementer that only sees
-  the previous commits and this unit's description must be able to deliver it
+Sweet spot: 100-300 lines per unit. Each unit must be self-contained and independently compilable.
 
-The plan also includes a **progress tracker** table summarizing commits planned
-vs done per service, visible at a glance.
+Typical split for a standard feature:
+- **Commit 1**: Data layer — models, migrations, DTOs
+- **Commit 2**: Business logic — services, use cases, validation
+- **Commit 3**: API/UI layer — controllers, routes, components, pages
+- **Commit 4**: Tests
 
 ### Dependency waves
 
-- **Wave 1**: Producers — API backend, data/analytics, auth (define contracts)
+- **Wave 1**: Producers — API backend, data, auth (define contracts)
 - **Wave 2**: Consumers — Frontend, integrations (depend on wave 1 contracts)
 - **Wave 3**: Infra/config — Gateway routes, deployment (after code exists)
 
-Independent services go in the same wave. Save. **Present plan, wait for approval.**
-
-## Phase 2.5: Session setup (branch isolation)
-
-After plan approval and before dispatch:
-
-1. Derive session name from feature name (slug: lowercase, hyphens, no spaces)
-2. Read `./workspace.md` — extract the `Source Branch` column for each service
-3. Identify repos impacted by the plan
-4. Write `./.sessions/{session-name}.json`:
-   ```json
-   {
-     "name": "{session-name}",
-     "created": "{date}",
-     "status": "active",
-     "repos": {
-       "{service}": {
-         "path": "../{service}",
-         "source_branch": "{from workspace.md}",
-         "session_branch": "session/{session-name}",
-         "branch_created": false
-       }
-     }
-   }
-   ```
-5. Spawn a **Task subagent with Bash** to create branches in each impacted repo:
-   ```
-   git -C ../[repo] branch session/{name} {source_branch}
-   ```
-   - Use `git branch` — NOT `git checkout -b` (checkout disrupts other sessions)
-   - If the branch already exists, verify it points to the right source and skip
-   - The Task subagent reports success/failure per repo
-6. Update the session JSON: set `branch_created: true` for each successful branch
-
-> **Why a Task subagent?** The team-lead has `disallowedTools: Bash`.
-> Branch creation requires shell access, so it must be delegated.
-
-## Phase 3: Dispatch — one implementer per commit unit
-
-**CRITICAL**: You do NOT spawn one teammate per service. You spawn one
-`Task(implementer)` per **commit unit** in the plan. Each implementer handles
-exactly one commit, then dies. This guarantees every commit is made.
-
-### Dispatch flow per service (sequential)
+Save plan. **Present plan, wait for approval.**
+Loop on Phases 1-2 if user requests changes.
 
-```
-For each service in the current wave:
-  For each commit unit (in order):
-    1. Spawn Task(implementer) with:
-       - This commit unit's tasks ONLY
-       - Constitution rules
-       - API contract (if relevant)
-       - Repo path + session branch
-       - Context: "Commits 1..N-1 are already on the branch"
-    2. Wait for implementer to return
-    3. Verify commit on session branch (Task subagent with Bash)
-    4. Update plan: mark commit unit ✅ or ❌
-    5. If ❌: re-dispatch (max 2 retries), then escalate
-    6. If ✅: proceed to next commit unit
-```
+## Phase 2.5: Git setup (after plan validation ONLY)
 
-**Cross-service parallelism**: Different services within the same wave can
-progress in parallel. Use parallel Task calls when possible.
+Opus runs git directly via Bash. No subagents for git setup.
 
-### Implementer spawn prompt — context tiering
+For each impacted repo:
+1. `git -C ../{repo} branch session/{name} {source_branch}` — **git branch**, never checkout -b
+2. `git worktree add /tmp/{repo}-{session-name} session/{name}` — persists until session close
+3. Verify worktree appears in `git worktree list`
 
-The implementer agent already knows its git workflow, commit protocol, and cleanup
-procedure. Do NOT repeat these in spawn prompts. Only provide specific values and context.
+Write `.sessions/{name}.json` with session metadata (name, created, status, per-repo: path, worktree_path, source_branch, session_branch, commits map).
 
-**Always include (Tier 1):**
-1. Which commit unit: "Commit N of M for service X"
-2. Tasks for this commit only (NOT the whole plan)
-3. Constitution rules from constitution.md (translated to English)
-4. Repo path + session branch: `session/{name}`
-5. Previous context: "Commits 1..N-1 are on the branch. Do NOT redo."
+PR target at session close = effective source branch.
 
-**Conditional (Tier 2):**
-- **Frontend commits with UI**: UX standards (from `references/frontend-ux-standards.md`)
-- **API commits**: API contract shapes (exact request/response)
-- **Frontend commits**: API contract as TypeScript interfaces
 
-**Never inject (Tier 3 — already in repo CLAUDE.md or agent instructions):**
-- Anti-patterns list (implementer reads CLAUDE.md)
-- Git workflow procedure (implementer agent already knows)
-- Full workspace context (implementer doesn't need it)
+## Phase 2.9: Pre-dispatch check (before spawning any teammate)
+
+Verify via Bash for each repo. Abort and fix before proceeding:
+
+| Check | Fix if failed |
+|-------|---------------|
+| Session branch exists | `git -C ../{repo} branch session/{name} {source_branch}` |
+| Worktree exists at /tmp/ path | `git worktree add /tmp/{repo}-{session-name} session/{name}` |
+| Worktree on correct branch | Inspect — may need worktree remove + re-add |
+| Worktree is clean (no uncommitted leftovers) | Inspect, commit useful changes or `git checkout -- .` |
+| Repo is reachable | Escalate to user |
+
+Only proceed to Phase 3 once all checks pass.
+
+## Phase 3: Dispatch — one teammate per repo
 
-See @references/spawn-templates.md for templates per service type.
+**ONE teammate per repo.** Each teammate receives the complete repo plan and handles
+all its commit units sequentially. It signals after each commit and waits for green light.
 
-> **Constitution in spawn prompts**: Implementers do NOT receive the constitution
-> automatically. You MUST include ALL rules from constitution.md in every spawn prompt.
+This is fundamentally different from the old model (one subagent per commit unit).
+The teammate has the full picture of its repo and can escalate intelligently at any point.
 
-### Isolation
+### Teammate spawn prompt — context tiering
 
-Each `Task(implementer)` creates its own worktree in `/tmp/`. The worktree is
-removed after the commit. The next implementer creates a fresh worktree and sees
-all previous commits on the session branch.
+See @references/spawn-templates.md for full templates.
 
-Never run two implementers on the same repo simultaneously — sequential only.
-Cross-service parallelism is fine.
+**Always inject (Tier 1):**
+1. `worktree_path`: /tmp/{repo}-{session-name}/ — ready, no git setup needed
+2. `session_branch`: session/{name}
+3. Complete repo plan (all commit units in order)
+4. Constitution rules (all from constitution.md, translated to English)
+5. SignalInstruction: "After each commit, SendMessage: 'commit N done — {hash} — {files} — tests: {pass/fail}'. Then WAIT for my green light."
+6. ScopeInstruction: "For each commit, read only files in scope for that commit unit."
+
+**Conditional (Tier 2):**
+- Frontend repo with UI → inject full frontend-ux-standards.md
+- API commits → inject API contract (exact request/response shapes)
+- Frontend commits → inject API contract as TypeScript interfaces
+
+**Never inject (Tier 3 — already in CLAUDE.md or agent):**
+- Git workflow (teammate has no git responsibility)
+- Generic anti-patterns
+- Full workspace context
+
+> The constitution is in constitution.md. Teammates do NOT receive it automatically.
+> Include ALL rules in every spawn prompt, translated to English.
+
+### Parallelism
+
+- Different repos in same wave → spawn teammates in parallel ✅
+- Same repo → ONE teammate handles everything sequentially ❌
 
 ### Wave execution
 
-1. For each service in wave 1: dispatch commit units sequentially (parallel across services)
-2. Wait for ALL services in wave 1 to complete ALL their commit units
-3. Collect wave 1 results, update the API contract if needed
-4. Dispatch wave 2 commit units with validated contracts from wave 1
-5. Repeat for wave 3 if applicable
-
-## Phase 4: Collect and update
-
-After EACH implementer returns:
-1. **Verify the commit** — spawn a Task subagent (Bash):
-   `git -C ../[repo] log session/{name} --oneline -3`
-   → The new commit must appear. If not: re-dispatch this commit unit.
-2. Update `./plans/{feature-name}.md` — mark this commit unit ✅ or ❌
-3. Update the **progress tracker** table (commits done / planned)
-4. Note dead code found
-5. **Flag giant commits** — if >400 lines, note in session log
-6. **Session log** entry: `[HH:MM] impl-[service]-commit-[N]: [status], [hash], [N] files, tests [pass/fail]`
-7. If ❌ → analyze failure, correct the commit unit description, re-dispatch (max 2 retries)
-8. If all commit units for a service are ✅ → service complete
-9. If all services in current wave are complete → launch next wave
-
-## Phase 5: Post-implementation
-
-1. Run `cross-service-check`
-2. Run `qa-ruthless`
-3. Update plan with all results
-4. Present final status to user
+1. Spawn all wave 1 repo teammates (parallel)
+2. Wait for ALL wave 1 teammates to complete ALL commits (all micro-QA validated)
+3. Collect validated API contracts from wave 1 results
+4. Spawn wave 2 teammates with validated contracts
+5. Repeat for wave 3
+
+## Phase 4: Micro-QA between commits
+
+After each teammate SendMessage "commit N done — {hash}":
+
+### Step 1 — Bash verification (Opus direct)
+
+```bash
+# 1. Verify commit exists on session branch
+git -C /tmp/{repo}-{session-name} log session/{name} --oneline -3
+
+# 2. Run scoped tests — adapt command to repo stack:
+#    PHP/Laravel:
+cd /tmp/{repo}-{session-name} && php artisan test --filter={CommitScope} 2>&1 | tail -30
+#    Vue/Node:
+cd /tmp/{repo}-{session-name} && npm run typecheck 2>&1 | tail -20
+#    Go:
+cd /tmp/{repo}-{session-name} && go test ./... 2>&1 | tail -20
+#    Python:
+cd /tmp/{repo}-{session-name} && pytest {scope_path} -v 2>&1 | tail -30
+
+# 3. Check for debug artifacts
+git -C /tmp/{repo}-{session-name} diff HEAD~1 HEAD \
+  | grep -E "(console\.log|dd\(|var_dump|\.only\(|TODO|FIXME|debugger|dump\()" \
+  | head -20
+```
+
+### Step 2 — Haiku diff review (Task subagent, read-only)
+
+Use the Haiku micro-QA template from @references/spawn-templates.md (section "Haiku micro-QA subagent template").
+
+Spawn Task(Explore, model: haiku) with that template, injecting the diff output from Step 1.
+
+**Do NOT rephrase or shorten the template** — copy it verbatim from the reference file.
+Haiku needs the exact structured prompt to return clean JSON.
+
+### Decision
+
+| Bash | Haiku | Action |
+|------|-------|--------|
+| OK | OK | SendMessage to teammate: "green light, proceed to commit N+1" |
+| FAIL | any | Opus analyzes failure, sends fix instruction to teammate OR escalates |
+| OK | BLOCKER | Opus evaluates blocker severity, sends fix instruction or escalates |
+
+Retry limit: max 2 per commit unit → escalate to user, stop the wave.
+
+### Update after each commit
+
+```bash
+# Update plan progress tracker
+# Mark commit N ✅ or ❌
+
+# Update session.json commits tracking
+# Add session log entry:
+# [HH:MM] {repo}-commit-{N}: {status}, {hash}, {N} files, tests {pass/fail}
+```
+
+## Phase 5: Post-implementation (all mandatory)
+
+1. **cross-service-check** — inter-repo consistency (API shapes, env vars, gateway routes)
+2. **qa-ruthless** — adversarial QA, min 3 findings per service
+3. **reviewer** — evidence-based code review (scope check + architecture + constitution compliance). Run via `claude --agent reviewer` or inline.
+4. **security-auditor** (conditional) — run via `claude --agent security-auditor` when the plan involves: auth changes, new tenant-scoped models, file uploads, payment/sensitive data, new public endpoints, or dependency additions. Skip for pure UI or config-only changes.
+5. **merge-prep** — PR summaries, merge order, conflict detection, target = source branch
+6. **cycle-retrospective** — MANDATORY, not optional
+   - Analyzes QA findings + review comments + session log
+   - Suggests CLAUDE.md updates per repo
+   - Suggests constitution additions if gaps found
+   - Asks confirmation before applying any changes
 
 ## Mode D: Single-service
 
 For targeted fixes or single-repo work:
 1. Identify the ONE service to touch
-2. Skip waves — dispatch commit units sequentially (often just 1)
+2. Skip waves — spawn ONE teammate (often 1-2 commit units)
 3. No cross-service-check (unless user requests it)
 4. QA scoped to that service only
 5. Merge prep for that service only
 
-For simple fixes with 1 commit unit: one Task(implementer) — no overhead.
-
-> **Context note**: This skill runs with `context: fork`. After it completes,
-> its internal context is discarded. The plan file on disk is the source of truth.
-> QA and cross-service-check will reload the plan from disk.
-
-## Session recovery
+## Session recovery (after crash)
 
-If resuming after crash:
-1. Read `./workspace.md` for project context
-2. List `./plans/` for active plans
-3. Read active plan — statuses and session log tell you where you are
-4. Resume at last incomplete step
-5. If no mode was selected before crash, default to Mode A
+1. Read ./workspace.md for project context
+2. List ./plans/ for active plans
+3. Check ./.sessions/ for active session JSON — worktrees should still exist in /tmp/
+4. Read active plan — statuses and session log tell you where you are
+5. Verify worktrees still exist: git worktree list for each repo
+6. Re-spawn missing teammates from their last incomplete commit unit
+7. Resume micro-QA loop
 
 ## Anti-patterns
 
-See @references/anti-patterns.md for the full list of anti-patterns and common mistakes.
+See @references/anti-patterns.md for the full list.