cc-workspace 4.6.2 → 4.7.1

package/README.md

@@ -215,7 +215,7 @@ parallel in each repo via Agent Teams.
 | **Orchestrator** | Opus 4.6 | Clarifies, plans, delegates, verifies. Writes in orchestrator/ only. |
 | **Init** | Sonnet 4.6 | Diagnostic + interactive workspace configuration. Run once. |
 | **Teammates** | Sonnet 4.6 | Implement in an isolated worktree, test, commit. |
-| **Explorers** | Haiku | Read-only. Scan, verify consistency. |
+| **Data extractors** | Haiku | Read-only. Collect raw data (types, configs, logs). Never judge or conclude. |
 | **QA** | Sonnet 4.6 | Hostile mode. Min 3 problems found per service. |
 | **E2E Validator** | Sonnet 4.6 | Containers + Chrome browser testing (beta). |
 
@@ -265,7 +265,7 @@ Protection layers:
 | **incident-debug** | Multi-layer diagnostic | "Bug", "500", "not working" |
 | **plan-review** | Plan sanity check (Haiku) | "Review plan" |
 | **merge-prep** | Conflicts, PRs, merge order | "Merge", "PR" |
-| **cycle-retrospective** | Post-cycle learning (Haiku) | "Retro", "retrospective" |
+| **cycle-retrospective** | Post-cycle learning (Opus + Haiku gatherers) | "Retro", "retrospective" |
 | **refresh-profiles** | Re-scan repo CLAUDE.md files (Haiku) | "Refresh profiles" |
 | **bootstrap-repo** | Generate a CLAUDE.md (Haiku) | "Bootstrap", "init CLAUDE.md" |
 | **e2e-validator** | E2E validation: containers + Chrome (beta) | `claude --agent e2e-validator` |
@@ -518,6 +518,17 @@ With `--chrome`, the agent:
 
 ---
 
+## Changelog v4.6.2 -> v4.7.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Gather → Reason pattern** | `cross-service-check`, `incident-debug`, and `cycle-retrospective` now use a two-phase approach: Haiku subagents extract raw data (types, configs, logs, code snippets), then Opus performs all reasoning, comparison, and judgment. Previously Haiku did both, producing shallow analysis. |
+| 2 | **cycle-retrospective upgraded to Opus** | Was `model: haiku` (entire skill ran on Haiku). Now inherits session model (Opus). Haiku still gathers data, but pattern analysis and improvement suggestions are Opus-quality. |
+| 3 | **Data extractors replace investigators** | `incident-debug` no longer uses a full Sonnet teammate for API investigation. All layers use Haiku data collectors, and Opus correlates the evidence — better reasoning at lower cost. |
+| 4 | **Model routing docs updated** | `rules/model-routing.md` now documents the Gather → Reason pattern and when to apply it. |
+
+---
+
 ## Changelog v4.5.1 -> v4.6.0
 
 | # | Feature | Detail |

package/global-skills/agents/implementer.md

@@ -20,8 +20,8 @@ hooks:
             [ -z "$CMD" ] && exit 0
             # Block git checkout/switch in sibling repos (would disrupt main working tree)
             if echo "$CMD" | grep -qE 'git\s+(-C\s+\.\./\S+\s+)?(checkout|switch)\s'; then
-              # Allow checkout inside /tmp/ worktrees (that's the intended workflow)
-              if echo "$CMD" | grep -qE '^\s*cd\s+/tmp/' || echo "$CMD" | grep -qE 'git\s+-C\s+/tmp/'; then
+              # Allow checkout inside /tmp/ worktrees (macOS: /tmp -> /private/tmp)
+              if echo "$CMD" | grep -qE '^\s*cd\s+(/private)?/tmp/' || echo "$CMD" | grep -qE 'git\s+-C\s+(/private)?/tmp/'; then
                 exit 0
               fi
               printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"BLOCKED: git checkout/switch targets a main repo. Use your /tmp/ worktree instead. See Git workflow instructions."}}'
@@ -51,23 +51,32 @@ Previous commits are already on the session branch — you'll see them in your w
 
 ## Git workflow (do this FIRST)
 
-You work in a **temporary worktree**. If you don't commit, YOUR WORK IS LOST.
+You work in a **worktree**. If you don't commit, YOUR WORK IS LOST.
 
-### Setup
+### Setup — ALWAYS check for existing worktree first
 ```bash
-# 1. Create worktree (or reuse if previous attempt left one)
-git -C ../[repo] worktree add /tmp/[repo]-[session] session/[branch]
-# If fails with "already checked out": previous crash left a worktree
-#   → cd /tmp/[repo]-[session] && git status to assess state
-
-# 2. Move into worktree — ALL work happens here
-cd /tmp/[repo]-[session]
-
-# 3. Verify branch
+# 1. FIRST: check if a worktree already exists for the session branch
+WORKTREE_PATH=$(git -C ../[repo] worktree list --porcelain | grep -B1 'branch.*session/[branch]' | head -1 | sed 's/worktree //')
+
+if [ -n "$WORKTREE_PATH" ] && [ -d "$WORKTREE_PATH" ]; then
+  # Worktree exists — REUSE IT (do NOT create a new one)
+  cd "$WORKTREE_PATH"
+  echo "Reusing existing worktree at $WORKTREE_PATH"
+else
+  # No worktree — create one
+  git -C ../[repo] worktree add /tmp/[repo]-[session] session/[branch]
+  cd /tmp/[repo]-[session]
+fi
+
+# 2. Verify branch
 git branch --show-current  # must show session/[branch]
 
-# 4. Check existing commits from previous implementers
+# 3. Check existing commits from previous implementers
 git log --oneline -5
+
+# 4. Check for leftover uncommitted changes from a crashed previous implementer
+git status --short
+# If dirty: assess changes — commit useful ones, discard junk with git checkout -- .
 ```
 
 If session branch doesn't exist:
@@ -76,13 +85,8 @@ git -C ../[repo] branch session/[branch] [source-branch]
 git -C ../[repo] worktree add /tmp/[repo]-[session] session/[branch]
 ```
 
-### Recovering from a previous failed attempt
-If `git worktree add` fails because the worktree already exists:
-1. `cd /tmp/[repo]-[session]` — enter the existing worktree
-2. `git status` — check for uncommitted changes from the previous implementer
-3. `git log --oneline -3` — check if the previous attempt committed anything
-4. If changes exist but aren't committed: assess if they're useful, commit or discard
-5. If clean: proceed normally with your commit unit
+**IMPORTANT — macOS paths**: `/tmp` is a symlink to `/private/tmp`.
+Git worktree list shows `/private/tmp/...`. Both paths are valid. Use whichever `worktree list` reports.
 
 ## Workflow
 
@@ -116,9 +120,11 @@ Report:
 - Dead code found
 - Blockers or escalations
 
-Cleanup:
+Cleanup — **do NOT remove the worktree** (next implementer will reuse it):
 ```bash
-git -C ../[repo] worktree remove /tmp/[repo]-[session]
+# Only verify the tree is clean after commit
+git status  # must show "nothing to commit, working tree clean"
+# The orchestrator or session close skill handles worktree cleanup
 ```
 
 ## Memory

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

@@ -26,29 +26,47 @@ Scope: ONLY inter-service alignment. Not code quality, not bugs.
    - Use `git -C ../[repo] show session/{name}:[file]` to read files from the
      session branch without checking it out
 
-## Checks (parallel Explore subagents via Task, Haiku)
+## Phase 1 — Gather (Haiku data extractors)
 
-Only run checks for services that exist in the workspace.
-Spawn lightweight Explore subagents (Task tool, model: haiku) in parallel.
-Use `background: true` so the orchestrator can continue interacting while scans run.
+Only run extractors for services that exist in the workspace.
+Spawn parallel Explore subagents (Task tool, model: haiku) using `background: true`.
+Each extractor returns RAW DATA ONLY — no judgment, no ✅/❌, no comparisons.
 
-### API ↔ Frontend contract
-Compare API Resource response shapes with TypeScript interfaces.
-Report ONLY mismatches: field names, types, missing fields, route names.
+Include this instruction in every extractor prompt: "Return RAW DATA ONLY. Do NOT judge, compare, or produce conclusions. No ✅/❌. Just structured lists of what you found." Format: structured markdown with clear headings and tables.
 
-### Environment variables
-Cross-check env vars between all repos. Grep for env access patterns.
-Compare with .env.example files. Report: used but not declared, declared but never used.
+### API extractor
+Extract all API endpoint response shapes from backend code.
+Return: route, method, response fields and types. One row per field.
 
-### Gateway ↔ API (if gateway exists)
-Compare gateway config routes with actual API routes.
-Report: dead gateway routes, missing routes for new endpoints.
+### Frontend extractor
+Extract all TypeScript interfaces/types that represent API responses.
+Return: interface name, fields and types, which endpoint they map to (if determinable).
 
-### Data layer (if data service exists)
-Compare data schemas with application code. Report: column/type mismatches, missing schema updates.
+### Env extractor
+Extract env var declarations (.env.example) and usages (grep for process.env / import.meta.env / getenv / os.Getenv / etc.) from ALL repos.
+Return: declared vars per repo (from .env.example), used vars per repo (from code grep).
 
-### Auth (if auth service was changed)
-Compare auth config (client IDs, redirect URIs, scopes) between services. Report inconsistencies.
+### Gateway extractor (if gateway exists)
+Extract all gateway route configs.
+Return: path, upstream, method for each route.
+
+### Data extractor (if data service exists)
+Extract schema definitions (table name, columns, types) and application model definitions.
+Return: raw schema table and raw model fields side by side.
+
+### Auth extractor (if auth service was changed)
+Extract auth configs (client IDs, redirect URIs, scopes) from each service.
+Return: raw config values per service.
+
+## Phase 2 — Reason (this skill, running as Opus)
+
+After all extractors return, YOU compare the datasets side-by-side and produce final judgments:
+
+- **API shapes vs Frontend interfaces**: field mismatches, type mismatches, missing fields
+- **Env declarations vs env usages**: used-but-undeclared, declared-but-unused (per repo)
+- **Gateway routes vs API routes**: dead routes, missing routes for new endpoints
+- **Data schemas vs application models**: column/type drift
+- **Auth configs across services**: inconsistencies between client configs
 
 ## Output
 

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

@@ -8,9 +8,6 @@ description: >
   "capitalize", "lessons learned", "what did we learn", "improve docs".
 argument-hint: "[feature-name]"
 context: fork
-agent: general-purpose
-disable-model-invocation: true
-model: haiku
 allowed-tools: Read, Write, Glob, Grep, Task
 ---
 
@@ -28,25 +25,29 @@ and propagate improvements to project documentation.
    - Cross-service check results
    - Session log (blockers, escalations, re-dispatches)
 
-## Phase 2: Analyze patterns
+## Phase 2: Extract data (Haiku collectors)
 
-Spawn parallel Explore subagents (Task, Haiku) to categorize findings:
+Spawn parallel Explore subagents (Task, model: haiku) to extract and structure raw data from the plan. Each collector: "Extract and structure the data. Do NOT analyze patterns or suggest improvements."
 
-### Recurring QA findings
-- Group QA findings by category (🔴 bugs, 🟡 smells, 🟠 dead code, 🔵 missing tests, 🟣 UX violations)
-- Identify patterns: same type of issue across multiple cycles?
-- Flag findings that could have been prevented by a rule or convention
+### QA data extractor
+Parse the QA report section from the plan.
+Return: raw list of findings with category (🔴/🟡/🟠/🔵/🟣), file reference, and description. No analysis.
 
-### Teammate friction
-- Parse session log for escalations — what decisions weren't covered by the plan?
-- Parse for re-dispatches — what went wrong on first attempt?
-- Parse for idle time — were tasks too large or poorly scoped?
+### Session log extractor
+Parse the session log section from the plan.
+Return: raw list of escalations, re-dispatches, and blockers with timestamps or phase references. No analysis.
 
-### Cross-service gaps
-- Were there contract mismatches? Missing env vars? Schema drift?
-- Could these have been caught earlier by a convention?
+### Cross-service data extractor
+Parse the cross-service check results section from the plan.
+Return: raw list of checks with status and details. No analysis.
 
-## Phase 3: Generate improvements
+## Phase 3: Analyze patterns (Opus reasoning)
+
+After all collectors return, YOU (the skill) analyze the raw data. This is where the reasoning model (Opus) works:
+- Group findings by category and identify recurring patterns across cycles
+- Correlate escalations with plan quality — what was missing from the plan?
+- Identify what could have been prevented by a rule or convention
+- Generate concrete improvement suggestions for each finding category
 
 For each finding category, generate concrete improvement suggestions:
 

package/global-skills/incident-debug/SKILL.md

@@ -30,32 +30,38 @@ Parse the user's report for signals:
 
 If unclear, investigate all layers.
 
-## Phase 2: Investigate (parallel)
+## Phase 2: Collect evidence (parallel Haiku extractors)
 
-Spawn investigators via Agent Teams (Teammate tool):
-- **API/Backend**: full Sonnet teammate with write-capable investigation. Use the **LSP tool** (go-to-definition, find-references) to trace error call chains. If LSP is unavailable, fall back to Grep + Glob for tracing references manually.
-- **Frontend, Gateway, Infra, Auth**: lightweight Explore subagents (Task, Haiku) for read-only scan. Use LSP tool where available for tracing, or Grep + Glob as fallback.
+Spawn parallel Explore subagents (Task, model: haiku) per layer. Each one collects raw evidence — code snippets, log entries, config values, error messages — and returns them WITHOUT diagnosis.
 
-Multiple teammates can share findings and challenge each other's hypotheses.
-This adversarial pattern finds root causes faster than sequential investigation.
+Include this instruction in every collector prompt: "Collect RAW EVIDENCE only. Code snippets with file:line references. Do NOT diagnose or hypothesize. Do NOT say 'the problem is X'. Just return what you found."
 
-### LSP investigation patterns
+Use these patterns to guide collectors on WHERE to look (not to diagnose):
 
-Instruct investigators to use these specific LSP workflows:
+| Signal | Where to collect |
+|--------|-----------------|
+| HTTP 500 in controller | Use `go-to-definition` (or Grep+Glob fallback) to find controller method → service layer → repository/query. Return code snippets with file:line. |
+| Type mismatch frontend | Use `find-references` on the TypeScript interface → collect all usage sites. Return raw code. |
+| Auth loop / 401 | Find auth middleware and token validation logic. Return raw config and code snippets. |
+| N+1 query suspicion | Find the relationship method and all callers. Return raw code at each call site. |
+| Dead import / unused function | Use `find-references` → return reference count and locations. |
+| Unknown error class | Find the exception class definition and all catch blocks. Return raw code. |
 
-| Signal | LSP action |
-|--------|-----------|
-| HTTP 500 in controller | `go-to-definition` on the controller method → trace into service layer → trace into repository/query |
-| Type mismatch frontend | `find-references` on the TypeScript interface → verify all usages match the API shape |
-| Auth loop / 401 | `hover` on auth middleware → verify configuration → `find-references` on token validation |
-| N+1 query suspicion | `find-references` on the relationship method → check all callers for eager loading |
-| Dead import / unused function | `find-references` → if 0 references outside tests, flag as dead code |
-| Unknown error class | `go-to-definition` on the exception class → check parent hierarchy and catch blocks |
+### Per-layer collector prompts
+
+- **API/Backend collector**: Find error handlers, relevant controller/service code, recent log patterns, middleware chain. Use Grep+Glob to trace the call chain from the entry point. Return: relevant code snippets with file:line, error handling logic, middleware order.
+- **Frontend collector**: Find component rendering logic, API call code, error boundaries, console error patterns. Return: component tree around the error, API call implementations, error handling code.
+- **Gateway collector** (if applicable): Extract route config, upstream definitions, timeout settings. Return raw config.
+- **Auth collector** (if applicable): Extract token validation logic, middleware config, redirect URIs. Return raw code snippets.
+- **Infra collector** (if applicable): Extract container configs, health checks, resource limits, recent deployment changes. Return raw config.
 
-## Phase 3: Correlate
+## Phase 3: Diagnose (Opus reasoning)
 
-Build request flow timeline with ✅/❌ markers.
-Cross-reference findings between layers.
+After all collectors return, YOU (the skill) correlate the evidence:
+- Build the request flow timeline from the collected code and config
+- Cross-reference findings between layers to identify where the chain breaks
+- Identify the root cause based on the evidence — this is deep reasoning, not pattern matching
+- The model running this skill (Opus) is the one that diagnoses; collectors never diagnose
 
 ## Phase 4: Write diagnosis
 

package/global-skills/rules/model-routing.md

@@ -21,8 +21,24 @@ If you write code for a repo (not a markdown plan), you have failed — delegate
 | Orchestrator | **Opus 4.6** | `claude --agent team-lead` (frontmatter `model: opus`) |
 | Implementation teammates | **Sonnet 4.6** | `CLAUDE_CODE_SUBAGENT_MODEL=sonnet` |
 | QA investigators | **Sonnet 4.6** | Same |
-| Explorers / cross-checks | **Haiku** | `model: haiku` in skill/agent frontmatter |
-| Plan review | **Haiku** | `model: haiku` in skill frontmatter |
+| Data extractors / explorers | **Haiku** | Task subagents with `model: haiku` — raw data only, no reasoning |
+| Gatherers (cross-check, debug, retro) | **Haiku** | Task subagents — raw data extraction only |
+
+## Gather → Reason pattern
+
+Skills that need both data collection and analysis use a two-phase approach:
+
+1. **Gather (Haiku)** — Spawn parallel Explore subagents (Task, model: haiku) that extract
+   raw data: code snippets, type definitions, config values, log entries. They return
+   structured facts. They do NOT judge, compare, or conclude.
+
+2. **Reason (Opus)** — The skill itself (running as Opus via `context: fork`) receives
+   the raw data and performs all analysis: comparison, correlation, judgment, diagnosis,
+   and report writing.
+
+This pattern applies to: `cross-service-check`, `incident-debug`, `cycle-retrospective`.
+It does NOT apply to: `qa-ruthless` (QA investigators are Sonnet — they need to run tests
+and reason about code quality), `plan-review` (structural checklist, Haiku is sufficient).
 
 ## Custom agent `implementer`
 For Task subagents that need to write code in an isolated worktree,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-workspace",
-  "version": "4.6.2",
+  "version": "4.7.1",
   "description": "Claude Code multi-workspace orchestrator — skills, hooks, agents, and templates for multi-service projects",
   "bin": {
     "cc-workspace": "./bin/cli.js"