cc-workspace 4.6.1 → 4.7.0

package/README.md

@@ -208,28 +208,6 @@ The orchestrator (Opus) never touches repo code. It clarifies the need,
 writes a plan in markdown, then sends teammates (Sonnet) to work in
 parallel in each repo via Agent Teams.
 
-### Architecture
-
-```
-                          orchestrator/
-                    ┌─────────────────────┐
-  You ◄──────────►  │  Team Lead (Opus)    │
-   clarify, plan,   │  writes plans/*.md   │
-   review            └────────┬────────────┘
-                              │ spawn
-              ┌───────────────┼───────────────┐
-              │               │               │
-              ▼               ▼               ▼
-     ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-     │ Implementer  │ │ Implementer  │ │  QA Ruthless  │
-     │  (Sonnet)    │ │  (Sonnet)    │ │  (Sonnet)     │
-     └──────┬───────┘ └──────┬───────┘ └──────────────┘
-            │ commit         │ commit
-            ▼                ▼               Explorer
-    /tmp/repo-api     /tmp/repo-front        (Haiku)
-    session/feat      session/feat          read-only
-```
-
 ### Who does what
 
 | Role | Model | What it does |
@@ -237,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). |
 
@@ -253,49 +231,15 @@ parallel in each repo via Agent Teams.
 ### The dispatch-feature workflow (Mode A)
 
 ```
-  User describes feature
-           │
-           ▼
-  ┌─── Phase 0: CLARIFY ───┐
-  │ Ask max 5 questions     │
-  │ if ambiguity            │
-  └────────┬────────────────┘
-           ▼
-  ┌─── Phase 1-2: PLAN ────┐
-  │ Load context            │
-  │ Write plan in ./plans/  │
-  │ Commit units + contract │
-  │ Wait for approval ◄─┐  │
-  │    │            No ──┘  │
-  └────┼────────────────────┘
-       │ Yes
-       ▼
-  ┌─── Phase 2.5: SESSION ─┐
-  │ git branch session/name │
-  │ in each impacted repo   │
-  └────────┬────────────────┘
-           ▼
-  ┌─── Phase 3: DISPATCH ──────────────────────────┐
-  │                                                 │
-  │  Wave 1: Producers (API, data, auth)            │
-  │    ├── Implementer → Commit 1/3                 │
-  │    ├── Implementer → Commit 2/3                 │
-  │    └── Implementer → Commit 3/3                 │
-  │           │ contracts validated                  │
-  │           ▼                                     │
-  │  Wave 2: Consumers (frontend, integrations)     │
-  │           │                                     │
-  │           ▼                                     │
-  │  Wave 3: Infra (gateway, config)                │
-  │                                                 │
-  └────────┬────────────────────────────────────────┘
-           ▼
-  ┌─── Phase 4-5: VERIFY ──┐
-  │ cross-service-check     │
-  │ + qa-ruthless            │
-  └────────┬────────────────┘
-           ▼
-  Final summary + propose fixes
+CLARIFY  -> ask max 5 questions if ambiguity
+PLAN     -> write the plan in ./plans/, wait for approval
+SESSION  -> create session branches in impacted repos (Phase 2.5)
+SPAWN    -> Wave 1: API/data in parallel
+           Wave 2: frontend with validated API contract
+           Wave 3: infra/config if applicable
+COLLECT  -> update the plan with results
+VERIFY   -> cross-service-check + qa-ruthless
+REPORT   -> final summary
 ```
 
 ### Security — path-aware writes
@@ -321,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` |
@@ -574,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 |
@@ -583,7 +538,6 @@ With `--chrome`, the agent:
 | 3 | **LSP fallback documented** | `qa-ruthless` and `incident-debug` now include explicit Grep+Glob fallback when LSP tool is unavailable. |
 | 4 | **`cc-workspace uninstall`** | New CLI command to cleanly remove all global components from `~/.claude/`. Interactive confirmation. Local orchestrator/ preserved. |
 | 5 | **workspace-init fixes** | Removed hardcoded version ("v4.0" → dynamic). Fixed skills count in diagnostic (9 → 13). |
-| 6 | **ASCII diagrams in README** | Architecture overview and dispatch workflow now have visual diagrams (ASCII art, compatible with GitHub and npm). |
 
 ---
 

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.1",
+  "version": "4.7.0",
   "description": "Claude Code multi-workspace orchestrator — skills, hooks, agents, and templates for multi-service projects",
   "bin": {
     "cc-workspace": "./bin/cli.js"