cc-workspace 4.7.1 → 5.2.1

package/CHANGELOG.md

@@ -0,0 +1,291 @@
+# Changelog
+
+## [5.2.1] — 2026-03-06
+
+### Prompt quality improvements
+
+- **`dispatch-feature` Phase 0** — added concrete few-shot examples for good vs bad
+  clarification questions. Models produce significantly better clarifications with
+  examples to anchor on.
+
+- **`dispatch-feature` modes B/C/D** — expanded from 1-line descriptions to detailed
+  step-by-step procedures. Mode B specifies exploration-first flow, Mode C specifies
+  retroactive plan creation and scoped post-impl, Mode D defers to its dedicated section.
+  Reduces improvisation risk on non-default modes.
+
+- **`dispatch-feature` Phase 4 micro-QA** — Haiku diff review prompt is now referenced
+  from `@references/spawn-templates.md` instead of being inlined. Prevents prompt
+  corruption when Opus reformulates the template. The canonical template in
+  spawn-templates.md (section "Haiku micro-QA subagent template") is the single
+  source of truth.
+
+### Bug fixes
+
+- **`workspace-init` Phase 2** — fixed stale references to global `~/.claude/skills/`
+  and `~/.claude/rules/` (removed in v5.2.0). Phase 2 now correctly checks local
+  `orchestrator/.claude/skills/` and `.claude/rules/`, and checks global agents
+  separately with the full list of 6 agents.
+
+- **CLI `doctor`** — skill count check is now dynamic (reads from package's
+  `global-skills/` directory) instead of hardcoded `13`. Adding or removing skills
+  no longer requires updating the doctor check.
+
+- **CLI `session close`** — now checks for `gh` CLI availability before offering PR
+  creation. If `gh` is not installed, the PR step is skipped with a helpful message
+  instead of failing silently on user confirmation.
+
+- **CLI cleanup** — removed obsolete tombstone comment about `generateBlockHook()`
+  (removed in v4.1.4).
+
+## [5.2.0] — 2026-03-06
+
+### Breaking changes
+
+- **Skills and rules are now LOCAL** — installed in `orchestrator/.claude/skills/` and
+  `orchestrator/.claude/rules/` instead of `~/.claude/skills/` and `~/.claude/rules/`.
+  Only agents remain global (`~/.claude/agents/`) because `claude --agent` requires it.
+  This means Claude sessions outside orchestrator/ no longer inherit cc-workspace rules
+  and skills — Claude behaves normally when used outside orchestrator context.
+
+- **Automatic legacy cleanup** — `npx cc-workspace update --force` removes old global
+  skills and rules from `~/.claude/` (from versions < 5.2). Only cc-workspace-owned
+  entries are removed; user-created skills/rules are untouched.
+
+### New agents
+
+- **`reviewer`** — Senior code review agent (Opus). Evidence-based: every comment requires
+  file:line + code snippet + justification. Anchored on constitution + CLAUDE.md + plan,
+  NEVER on existing legacy code (safe for projects in active refactoring). Mandatory scope
+  check (plan vs implemented). Standalone via `claude --agent reviewer` or invoked in
+  dispatch-feature Phase 5 after qa-ruthless.
+
+- **`security-auditor`** — Security audit agent (Opus). 7-phase systematic audit:
+  auth flow tracing (endpoint × middleware mapping), tenant isolation (model × scoping check),
+  secrets scan (hardcoded values, committed .env, frontend bundle exposure), dependency CVEs
+  (npm audit / composer audit with grep fallback), input validation & injection vectors
+  (SQL, XSS, command, deserialization), headers & CORS, and session-scoped delta analysis
+  (separates NEW findings from PRE-EXISTING). Conditional in Phase 5 — triggered when plan
+  involves auth changes, tenant-scoped models, file uploads, payment data, or new public
+  endpoints. Standalone via `claude --agent security-auditor`.
+
+### Changes
+
+- **`qa-ruthless`** — added explicit `model: opus` in frontmatter. Previously inherited
+  from caller context; now fixed to Opus regardless of invocation method.
+
+- **`dispatch-feature` Phase 5** — updated order:
+  1. cross-service-check
+  2. qa-ruthless
+  3. reviewer (new — always)
+  4. security-auditor (new — conditional)
+  5. merge-prep
+  6. cycle-retrospective
+
+- **`team-lead`** — workflow table updated for new Phase 5 order with reviewer and
+  conditional security-auditor.
+
+- **`model-routing.md`** — routing table updated: QA orchestration = Opus (explicit),
+  code reviewer = Opus, security auditor = Opus, QA investigators = Sonnet (clarified).
+
+- **`doctor`** — refactored for new layout:
+  - Skills and rules checked locally in `orchestrator/.claude/` (not globally)
+  - Legacy detection: warns if old global skills/rules still exist
+  - Agent count updated to 6 (added reviewer, security-auditor)
+
+- **`bin/cli.js`** — major refactoring:
+  - `installGlobals()`: only installs agents globally; calls `cleanLegacyGlobals()`
+  - `cleanLegacyGlobals()` (new): removes cc-workspace skills and rules from `~/.claude/`
+  - `setupWorkspace()`: copies skills + rules into `orchestrator/.claude/skills/` and
+    `orchestrator/.claude/rules/`
+  - `updateLocal()`: now updates skills + rules locally (in addition to hooks, settings,
+    templates, CLAUDE.md)
+  - `doctor()`: checks skills/rules locally, detects legacy globals
+  - `uninstall`: updated for new layout, cleans agents + legacy globals
+  - CLAUDE.md content: updated config section, skills/agents count, launch commands
+  - Help, post-init summary, and all user-facing messages updated
+
+- **All frontmatter** — `prompt_version` bumped to `5.2.0` across all 19 agents and skills.
+
+### Migration from v5.1.x
+
+1. Run `npx cc-workspace update --force` from your workspace root.
+2. This will:
+   - Install 6 agents globally (`~/.claude/agents/`)
+   - Install skills + rules locally (`orchestrator/.claude/skills/` and `rules/`)
+   - Remove legacy global skills and rules from `~/.claude/`
+   - Update hooks, settings, templates, CLAUDE.md
+3. Run `npx cc-workspace doctor` to verify the new layout.
+4. Claude sessions outside orchestrator/ will no longer see cc-workspace rules/skills.
+
+## [5.1.0] — 2026-03-05
+
+### Fixes from prompt engineering review
+
+- **Version alignment** — `package.json` now matches `prompt_version: 5.1.0` across all agents/skills.
+
+- **`--dry-run` flag** — `init` and `update` commands now support `--dry-run` to preview
+  all file operations without writing anything. All FS helpers (mkdirp, copyFile, copyDir,
+  writeFile, writeVersion, chmod) respect the flag.
+
+- **Secure `permission-auto-approve.sh`** — compound commands (`&&`, `||`, `;`, `|`,
+  backticks, `$()`) are now rejected before any pattern matching. Prevents hypothetical
+  `git branch session/x && malicious-command` bypasses. DRY constant for JSON responses.
+
+- **Robust `detectProjectType`** — replaced naive `string.includes()` check with
+  `JSON.parse` + `dependencies`/`devDependencies` key lookup. Detects `@quasar/app-vite`,
+  `@quasar/app-webpack` explicitly. No more false positives from package names containing
+  "next" or "react" as substrings.
+
+- **Split `session-start-context.sh`** — extracted orphan worktree cleanup into
+  `orphan-cleanup.sh` (new hook). `session-start-context.sh` now handles context injection
+  only. Both registered as separate `SessionStart` hooks in `settings.json`.
+
+- **Stronger `validate-spawn-prompt.sh`** — constitution detection uses 3 heuristics:
+  explicit headers, numbered bold rules (3+ = constitution), and keyword+domain term density.
+  Expanded domain keywords (error handling, security, test coverage, etc.).
+
+- **JSON format for Haiku micro-QA** — micro-QA template now requests structured JSON
+  (`{"status":"OK"}` or `{"status":"BLOCKER","file":"...","line":N,"reason":"..."}`)
+  instead of free-text. Updated in both `spawn-templates.md` and `dispatch-feature/SKILL.md`.
+
+- **Compact Phase 2.5/2.9** — replaced verbose literal bash blocks with concise semantic
+  descriptions + table format. Opus has the concepts; token savings without information loss.
+
+- **Clarified `/compact` instruction** — Rule #10 in team-lead now explicitly references
+  Claude Code's native `/compact` command rather than vague "compact after each cycle".
+
+- **Chrome MCP check in doctor** — new Check 4b verifies Chrome DevTools MCP server
+  configuration in both global and project-level settings. Warns if `e2e-validator --chrome`
+  would fail due to missing MCP.
+
+- **CLI unit tests** — added `test_cli.sh` (comprehensive): version, help, unknown command,
+  `--dry-run` (no files written), full `init` (structure + globals + permissions),
+  idempotency (user files preserved), `update --force`, project type detection,
+  session list. ~50 assertions.
+
+## [5.0.0] — 2026-03-05
+
+### Breaking changes
+
+- **Orchestrator now has Bash access** — `disallowedTools: Bash` removed from `team-lead`.
+  Opus manages git (branch creation, worktrees) and micro-QA directly. No subagent delegation for git.
+
+- **One teammate per repo** — the dispatch model shifts from "one subagent per commit unit"
+  to "one teammate per repo". The teammate handles all commit units for its repo sequentially,
+  signals after each commit, and waits for orchestrator green light.
+
+- **Micro-QA between every commit** — mandatory Bash test run + Haiku diff review after each
+  commit before greenlighting the next. This replaces the single final QA-only model.
+
+- **Worktrees created after plan validation** — branches and worktrees are set up by Opus
+  directly via Bash only after the user validates the plan. No more orphan branches on rejected plans.
+
+- **Worktrees persist until session close** — worktrees in `/tmp/` are never pruned during
+  an active session. Cleanup happens exclusively in `/session close <n>`.
+
+- **cycle-retrospective is mandatory** — now a required Phase 5 step in dispatch-feature,
+  not an optional post-cycle task.
+
+- **plan-review uses Sonnet** — upgraded from Haiku for constitution compliance checking.
+
+### New features
+
+- **Source branch override** — specify a different source branch in the initial prompt
+  ("fix on hotfix/payment", "refacto from develop"). Stored in session JSON, used as PR target.
+
+- **Session JSON commit tracking** — session `.json` files now track per-repo commit status,
+  hash, and QA result for resumability after crashes.
+
+- **Worktree removal in session close** — `session close` (CLI and skill) now includes
+  a step to remove `/tmp/` worktrees before branch deletion.
+
+- **Micro-QA Haiku template** — new spawn template in `spawn-templates.md` for the
+  structured diff-only review subagent used in Phase 4.
+
+### Changes
+
+- `team-lead.md` — removed `disallowedTools: Bash`, added Phase 4 micro-QA flow,
+  updated dispatch model to one teammate per repo, added git setup instructions (Phase 2.5).
+
+- `implementer.md` — removed all git setup responsibility (worktree creation, branch creation).
+  Implementer receives a ready worktree path. Added SendMessage signal + wait protocol.
+  `maxTurns` increased from 60 to 120 for multi-commit sessions.
+
+- `dispatch-feature/SKILL.md` — Phase 1 uses Opus direct exploration (no upfront Haiku scan).
+  Phase 2.5 documents Opus-direct git setup. Phase 3 redesigned for one-teammate-per-repo.
+  Phase 4 (micro-QA) is new. Phase 5 adds mandatory cycle-retrospective.
+
+- `dispatch-feature/references/spawn-templates.md` — full rewrite for one-teammate-per-repo
+  model. New backend, frontend, infra, and Haiku micro-QA templates. Context tiering updated.
+
+- `dispatch-feature/references/anti-patterns.md` — updated for v5 model.
+  Removed "one subagent per commit" anti-pattern (now correct behavior).
+  Added: never two teammates on same repo, never skip micro-QA, never prune active worktrees.
+
+- `hooks/permission-auto-approve.sh` — extended to auto-approve safe Bash git operations
+  (branch creation, worktree add in /tmp/, log/status/diff) and test/typecheck in worktrees.
+
+- `hooks/validate-spawn-prompt.sh` — updated checks for v5 spawn model:
+  worktree_path required, signal protocol required, plan (not just tasks) required.
+
+- `hooks/session-start-context.sh` — session-aware orphan cleanup: active session worktrees
+  are never removed. Only truly orphaned worktrees (no matching active session JSON) are cleaned.
+
+- `hooks/user-prompt-guard.sh` — updated reminder: Bash is allowed for git/test operations,
+  not for writing application code in repos.
+
+- `rules/model-routing.md` — updated routing table (plan-review → Sonnet, micro-QA → Haiku).
+  Documents dispatch-feature Phase 1 exception (Opus explores directly).
+
+- `skills/session/SKILL.md` — added worktree removal step in `/session close`.
+
+- `dispatch-feature/SKILL.md` — added **Phase 2.9: Pre-dispatch check** between
+  git setup and teammate dispatch. Verifies branch exists, worktree exists and is on
+  the right branch, worktree is clean, repo is reachable. Auto-fixes simple cases
+  (missing branch/worktree), escalates to user if unreachable.
+
+- `doctor/SKILL.md` — added **v5 compatibility checks** (Check 3):
+  detects v4 installations (disallowedTools: Bash in team-lead, missing SendMessage
+  in implementer, plan-review on haiku), validates active session worktree_path fields,
+  checks session worktrees exist on disk, detects orphan worktrees not linked to any session.
+
+- `skills/cleanup/SKILL.md` — session-aware: explicitly skips active session worktrees.
+
+- `skills/cycle-retrospective/SKILL.md` — description updated to MANDATORY, references Phase 5.
+
+- `skills/plan-review/SKILL.md` — model changed from haiku to sonnet.
+
+- `templates/workspace.template.md` — version reference updated to v5.0.
+
+- `bin/cli.js` — version bumped to 5.0.0. `session close` command now includes worktree
+  removal step before branch deletion. `claudeMdContent()` updated to reflect v5 rules.
+
+### Migration from v4.x
+
+1. Run `npx cc-workspace update --force` to install v5 global components.
+2. Run `npx cc-workspace update` from your workspace root to update local `orchestrator/`.
+3. The new `team-lead` agent has Bash access — review your workspace security posture.
+4. Existing sessions (`session.json` files) are compatible but lack the new `worktree_path`
+   and `commits` fields. Add them manually or re-init sessions.
+5. `cycle-retrospective` will now be called automatically at the end of every dispatch cycle.
+
+
+### E2E Validator updates (v5.0.0 continued)
+
+- `agents/e2e-validator.md` — model upgraded Sonnet → Opus. maxTurns 100 → 150.
+  No worktrees: agent works directly on repos at correct branch (merged or session).
+  Added port conflict check (Step 1) before starting containers.
+  Added global 10-minute timeout on container health checks.
+  Added test data seeding step (Step 2).
+  Teardown simplified — no worktree removal, only branch restore + docker down.
+  `--fix` mode updated to use Teammate(implementer) instead of Task(implementer).
+
+- `e2e-validator/references/container-strategies.md` — build contexts changed from
+  `/tmp/e2e-{repo}` to `../{repo}` (direct repo path at checked-out branch).
+  Added non-standard port defaults to reduce conflicts with local dev servers.
+  Added port assignment table in e2e-config.md guidance.
+  Removed all /tmp/ worktree references.
+
+## [4.7.1] — previous
+
+See git history for earlier versions.

package/README.md

@@ -27,7 +27,7 @@ cd ~/projects/my-workspace
 npx cc-workspace init . "My Project"
 ```
 
-This creates an `orchestrator/` directory and installs 13 skills, 4 agents, 9 hooks, and 2 rules into `~/.claude/`.
+This creates an `orchestrator/` directory with 13 skills, 2 rules, and 9 hooks locally in `orchestrator/.claude/`, and installs 6 agents globally in `~/.claude/agents/`.
 
 ### Configure (one time)
 
@@ -48,6 +48,8 @@ The init agent will:
 ```bash
 cd orchestrator/
 claude --agent team-lead          # orchestration sessions
+claude --agent reviewer           # evidence-based code review
+claude --agent security-auditor   # security audit
 claude --agent e2e-validator      # E2E validation (beta)
 ```
 
@@ -67,8 +69,8 @@ npx cc-workspace update
 ```
 
 Updates all components if the package version is newer:
-- **Global**: skills, rules, agents in `~/.claude/`
-- **Local** (if `orchestrator/` found): hooks, settings.json, CLAUDE.md, templates, _TEMPLATE.md
+- **Global**: agents in `~/.claude/agents/` + cleanup of legacy global skills/rules
+- **Local** (if `orchestrator/` found): skills, rules, hooks, settings.json, CLAUDE.md, templates, _TEMPLATE.md
 - **Never overwritten**: workspace.md, constitution.md, plans/, e2e/
 
 ### Diagnostic
@@ -78,7 +80,7 @@ npx cc-workspace doctor     # from terminal
 /doctor                      # from inside a Claude Code session
 ```
 
-Checks: installed version, skills, rules, agents, hooks, jq, orchestrator/ structure.
+Checks: installed version, agents (global), skills + rules (local), hooks, jq, orchestrator/ structure, legacy globals detection.
 
 ---
 
@@ -89,10 +91,17 @@ my-workspace/
 ├── orchestrator/                    <- you cd here
 │   ├── .claude/
 │   │   ├── settings.json           <- env vars + hooks
-│   │   └── hooks/
-│   │       ├── session-start-context.sh
-│   │       ├── validate-spawn-prompt.sh
-│   │       └── ...                  <- 9 scripts (all warning-only)
+│   │   ├── hooks/
+│   │   │   ├── session-start-context.sh
+│   │   │   ├── validate-spawn-prompt.sh
+│   │   │   └── ...                  <- 9+ scripts (all warning-only)
+│   │   ├── skills/                  <- LOCAL (13 skills — only active in orchestrator/)
+│   │   │   ├── dispatch-feature/
+│   │   │   ├── qa-ruthless/
+│   │   │   └── ...
+│   │   └── rules/                   <- LOCAL (2 rules — only active in orchestrator/)
+│   │       ├── context-hygiene.md
+│   │       └── model-routing.md
 │   ├── CLAUDE.md                    <- orchestrator profile
 │   ├── workspace.md                 <- filled by workspace-init
 │   ├── constitution.md              <- filled by workspace-init
@@ -117,6 +126,15 @@ my-workspace/
 ├── repo-a/          (.git)          <- teammate worktree
 ├── repo-b/          (.git)          <- teammate worktree
 └── repo-c/          (.git)          <- teammate worktree
+
+~/.claude/
+└── agents/                          <- GLOBAL (6 agents — needed for claude --agent)
+    ├── team-lead.md
+    ├── implementer.md
+    ├── workspace-init.md
+    ├── reviewer.md
+    ├── security-auditor.md
+    └── e2e-validator.md
 ```
 
 ---
@@ -153,7 +171,7 @@ In `workspace.md`, add the `Source Branch` column to the service map:
 1. The team-lead identifies impacted repos during planning (Phase 2)
 2. After plan approval, **Phase 2.5** creates a session:
    - Writes `.sessions/{name}.json` with impacted repos only
-   - Spawns a Task subagent to run `git branch session/{name} {source}` in each repo
+   - Opus runs `git branch session/{name} {source}` + `git worktree add /tmp/...` directly via Bash
    - Uses `git branch` (NOT `git checkout -b`) to avoid disrupting other sessions
 3. Teammates receive the session branch in their spawn prompt — they do NOT create their own branches
 4. PRs go from `session/{name}` → `source_branch` (never to main directly)
@@ -212,12 +230,14 @@ parallel in each repo via Agent Teams.
 
 | Role | Model | What it does |
 |------|-------|-------------|
-| **Orchestrator** | Opus 4.6 | Clarifies, plans, delegates, verifies. Writes in orchestrator/ only. |
+| **Orchestrator** | Opus 4.6 | Clarifies, plans, manages git, delegates, micro-QA between commits. 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. |
+| **Teammates** | Sonnet 4.6 | Implement in an isolated worktree. One per repo, handles all commits sequentially, signals after each. |
 | **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). |
+| **QA** | Opus 4.6 | Hostile mode. Spawns Sonnet investigators. Min 3 problems found per service. |
+| **Reviewer** | Opus 4.6 | Evidence-based code review. Scope check + architecture + constitution compliance. |
+| **Security Auditor** | Opus 4.6 | Auth flow tracing, tenant isolation, secrets scan, CVEs, input validation. |
+| **E2E Validator** | Opus 4.6 | Containers + Chrome browser testing (beta). |
 
 ### The 4 session modes
 
@@ -233,13 +253,14 @@ parallel in each repo via Agent Teams.
 ```
 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
+SESSION  -> create session branches + worktrees in impacted repos (Phase 2.5)
+SPAWN    -> Wave 1: API/data (one teammate per repo, sequential commits)
            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
+MICRO-QA -> Bash tests + Haiku diff after EVERY commit before green light
+VERIFY   -> cross-service-check + qa-ruthless + reviewer + (security-auditor)
+MERGE    -> merge-prep (PRs, conflict detection)
+RETRO    -> cycle-retrospective (mandatory)
 ```
 
 ### Security — path-aware writes
@@ -249,9 +270,9 @@ but never in sibling repos. A `PreToolUse` hook in the team-lead agent frontmatt
 dynamically checks if the target path is inside orchestrator/ before allowing writes.
 
 Protection layers:
-1. `disallowedTools: Bash` in agent frontmatter
-2. `tools` whitelist in agent frontmatter (note: `allowed-tools` is the skill equivalent)
-3. `PreToolUse` path-aware hook in agent frontmatter (team-lead only — teammates write freely in their worktrees)
+1. `tools` whitelist in agent frontmatter
+2. `PreToolUse` path-aware hook in agent frontmatter (team-lead only — teammates write freely in their worktrees)
+3. `PreToolUse` Bash guard in implementer frontmatter (blocks git checkout on main working trees)
 
 ---
 
@@ -259,16 +280,16 @@ Protection layers:
 
 | Skill | Role | Trigger |
 |-------|------|---------|
-| **dispatch-feature** | 4 modes: Clarify -> Plan -> Delegate -> Track | "Implement X", "new feature" |
-| **qa-ruthless** | Hostile QA + UX audit | "QA", "review", "test" |
+| **dispatch-feature** | 4 modes: Clarify -> Plan -> Git -> Delegate -> Micro-QA -> Track | "Implement X", "new feature" |
+| **qa-ruthless** | Hostile QA + UX audit (Opus) | "QA", "review", "test" |
 | **cross-service-check** | Inter-repo consistency | "cross-service", "pre-merge" |
 | **incident-debug** | Multi-layer diagnostic | "Bug", "500", "not working" |
-| **plan-review** | Plan sanity check (Haiku) | "Review plan" |
+| **plan-review** | Plan sanity check (Sonnet) | "Review plan" |
 | **merge-prep** | Conflicts, PRs, merge order | "Merge", "PR" |
 | **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` |
+| **metrics** | Quantitative KPIs from session data | "/metrics", "/metrics last-5" |
 | **session** | List, status, close parallel sessions | `/session`, `/session status X` |
 | **doctor** | Full workspace diagnostic (Haiku) | `/doctor` |
 | **cleanup** | Remove orphan worktrees + stale sessions | `/cleanup` |
@@ -278,18 +299,23 @@ next one starts. The plan on disk is the source of truth.
 
 ---
 
-## The 4 agents
+## The 6 agents
 
 | Agent | Model | Usage |
 |-------|-------|-------|
 | **team-lead** | Opus 4.6 | `claude --agent team-lead` — multi-service orchestration |
 | **workspace-init** | Sonnet 4.6 | `claude --agent workspace-init` — diagnostic + initial config |
-| **implementer** | Sonnet 4.6 | Task subagent with `isolation: worktree` — isolated implementation |
-| **e2e-validator** | Sonnet 4.6 | `claude --agent e2e-validator` — E2E validation with containers + Chrome (beta) |
+| **implementer** | Sonnet 4.6 | Teammate spawned by team-lead — isolated implementation in worktrees |
+| **reviewer** | Opus 4.6 | `claude --agent reviewer` — evidence-based code review (scope check, architecture, constitution) |
+| **security-auditor** | Opus 4.6 | `claude --agent security-auditor` — auth flows, tenant isolation, secrets, CVEs, input validation |
+| **e2e-validator** | Opus 4.6 | `claude --agent e2e-validator` — E2E validation with containers + Chrome (beta) |
+
+Agents are installed globally in `~/.claude/agents/` (required for `claude --agent`).
+Skills and rules are local to `orchestrator/.claude/` — they don't affect Claude sessions outside orchestrator/.
 
 ---
 
-## The 9 hooks (settings.json) + 1 agent-level hook (team-lead frontmatter)
+## The 9 hooks (settings.json) + 2 agent-level hooks (frontmatter)
 
 All hooks in settings.json are **non-blocking** (exit 0 + warning). No hook blocks the session.
 
@@ -396,9 +422,10 @@ npx cc-workspace doctor     # full diagnostic (or /doctor in-session)
 ```
 
 On each `init` or `update`, the CLI compares versions:
-- **Newer version** → overrides skills, rules, agents, hooks
+- **Newer version** → overrides agents (global), skills + rules + hooks (local)
 - **Same version** → skip (unless `--force`)
 - **Workspace files** (workspace.md, constitution.md, plans/) → never overwritten
+- **Legacy cleanup** → removes old global skills/rules from `~/.claude/` (versions < 5.2)
 
 ---
 
@@ -411,7 +438,7 @@ cc-workspace/
 ├── README.md
 ├── LICENSE
 │
-└── global-skills/                     <- components installed in ~/.claude/
+└── global-skills/                     <- source of truth for all components
     ├── templates/
     │   ├── workspace.template.md
     │   ├── constitution.template.md
@@ -421,7 +448,8 @@ cc-workspace/
     │   └── references/
     │       ├── frontend-ux-standards.md
     │       ├── spawn-templates.md
-    │       └── anti-patterns.md
+    │       ├── anti-patterns.md
+    │       └── rollback-protocol.md
     ├── qa-ruthless/SKILL.md
     ├── cross-service-check/SKILL.md
     ├── incident-debug/SKILL.md
@@ -430,6 +458,7 @@ cc-workspace/
     ├── cycle-retrospective/SKILL.md
     ├── refresh-profiles/SKILL.md
     ├── bootstrap-repo/SKILL.md
+    ├── metrics/SKILL.md
     ├── e2e-validator/
     │   └── references/
     │       ├── container-strategies.md
@@ -438,11 +467,21 @@ cc-workspace/
     ├── session/SKILL.md               <- /session slash command
     ├── doctor/SKILL.md                <- /doctor slash command
     ├── cleanup/SKILL.md               <- /cleanup slash command
-    ├── hooks/                         <- 9 scripts (warning-only)
-    ├── rules/                         <- 2 rules
-    └── agents/                        <- 4 agents (team-lead, implementer, workspace-init, e2e-validator)
+    ├── hooks/                         <- 9+ scripts (warning-only)
+    ├── rules/                         <- 2 rules → installed LOCAL in orchestrator/.claude/rules/
+    └── agents/                        <- 6 agents → installed GLOBAL in ~/.claude/agents/
+        ├── team-lead.md
+        ├── implementer.md
+        ├── workspace-init.md
+        ├── reviewer.md
+        ├── security-auditor.md
+        └── e2e-validator.md
 ```
 
+**Installation layout:**
+- `agents/` → `~/.claude/agents/` (global — `claude --agent` requires it)
+- Everything else → `orchestrator/.claude/` (local — no side effects outside orchestrator)
+
 ---
 
 ## Idempotence
@@ -450,9 +489,10 @@ cc-workspace/
 Both `init` and `update` are safe to re-run:
 - **Never overwritten**: `workspace.md`, `constitution.md`, `plans/*.md`, `e2e/` (user content)
 - **Always regenerated**: `settings.json`, `CLAUDE.md`, `_TEMPLATE.md`
-- **Always copied**: hooks, templates
+- **Always copied**: hooks, skills, rules, templates
 - **Always regenerated on init**: `service-profiles.md` (fresh scan)
-- **Global components**: only updated if the version is newer (or `--force`)
+- **Agents** (global): only updated if the version is newer (or `--force`)
+- **Legacy cleanup**: old global skills/rules in `~/.claude/` are removed automatically
 
 ---
 
@@ -489,14 +529,14 @@ Add `--fix` to any mode to dispatch teammates for fixing failures.
 
 ### How it works
 
-1. Creates `/tmp/` worktrees on session branches (from the plan)
-2. Starts services via `docker compose up`
-3. Waits for health checks
+1. Checks out repos to the correct branch (merged source or session branch)
+2. Starts services via `docker compose up` with build context pointing to repos
+3. Waits for health checks (10-minute global timeout)
 4. Runs existing test suites + generates API scenario tests from the plan
 5. With `--chrome`: drives Chrome via chrome-devtools MCP (navigate, fill forms,
    click, take screenshots, record GIFs, check network requests and console)
 6. Generates report with evidence (screenshots, GIFs, network traces)
-7. Tears down containers and worktrees
+7. Tears down containers and restores repos to their original branch
 
 ### Chrome testing
 
@@ -518,6 +558,48 @@ With `--chrome`, the agent:
 
 ---
 
+## Changelog v5.1.0 -> v5.2.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Skills & rules now LOCAL** | Installed in `orchestrator/.claude/skills/` and `rules/` instead of `~/.claude/`. Only agents remain global. Claude behaves normally outside orchestrator/. |
+| 2 | **Automatic legacy cleanup** | `update --force` removes old global skills/rules from `~/.claude/` (from versions < 5.2). |
+| 3 | **Reviewer agent (Opus)** | Evidence-based code review: scope check (plan vs implemented), architecture assessment, constitution compliance. Anchored on constitution + CLAUDE.md + plan, never on legacy code. |
+| 4 | **Security auditor agent (Opus)** | 7-phase audit: auth flow tracing, tenant isolation, secrets scan, dependency CVEs, input validation, headers/CORS, session-scoped delta analysis. Conditional in Phase 5. |
+| 5 | **qa-ruthless explicit Opus** | Added `model: opus` in frontmatter. Previously inherited from caller context. |
+| 6 | **Phase 5 expanded** | Now: cross-service → qa-ruthless → reviewer → (security-auditor) → merge-prep → cycle-retrospective. |
+
+---
+
+## Changelog v5.0.0 -> v5.1.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **`--dry-run` flag** | `init` and `update` support preview without writing files. |
+| 2 | **Secure `permission-auto-approve.sh`** | Compound commands rejected before pattern matching. |
+| 3 | **Robust `detectProjectType`** | JSON.parse + dependency lookup instead of string.includes(). |
+| 4 | **Split orphan cleanup** | Extracted into separate `orphan-cleanup.sh` hook. |
+| 5 | **JSON format for micro-QA** | Haiku returns structured `{"status":"OK"}` instead of free text. |
+| 6 | **Chrome MCP check in doctor** | Verifies Chrome DevTools MCP configuration. |
+| 7 | **Hook unit tests** | `test_hooks.sh` with ~30 assertions. CLI unit tests with ~50 assertions. |
+
+---
+
+## Changelog v4.7.0 -> v5.0.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Opus has Bash** | `disallowedTools: Bash` removed from team-lead. Opus manages git (branches, worktrees) and micro-QA directly. |
+| 2 | **One teammate per repo** | Shift from one subagent per commit unit to one teammate per repo. Sequential commits with signal+wait protocol. |
+| 3 | **Micro-QA between every commit** | Bash tests + Haiku diff review after each commit before green light. |
+| 4 | **Worktrees after plan validation** | Branches and worktrees created by Opus only after user approves the plan. |
+| 5 | **Worktrees persist** | `/tmp/` worktrees live until `session close`. No pruning during active sessions. |
+| 6 | **cycle-retrospective mandatory** | Required Phase 5 step, not optional. |
+| 7 | **Source branch override** | Specify source branch in initial prompt. Stored in session JSON. |
+| 8 | **E2E validator upgraded** | Opus model, no worktrees (direct checkout), port conflict check, global timeout, test data seeding. |
+
+---
+
 ## Changelog v4.6.2 -> v4.7.0
 
 | # | Feature | Detail |