cc-workspace 4.5.0 → 4.6.0

package/README.md

@@ -74,7 +74,8 @@ Updates all components if the package version is newer:
 ### Diagnostic
 
 ```bash
-npx cc-workspace doctor
+npx cc-workspace doctor     # from terminal
+/doctor                      # from inside a Claude Code session
 ```
 
 Checks: installed version, skills, rules, agents, hooks, jq, orchestrator/ structure.
@@ -157,14 +158,22 @@ In `workspace.md`, add the `Source Branch` column to the service map:
 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)
 
-### Session CLI commands
+### Session commands
 
+From terminal (CLI):
 ```bash
 cc-workspace session list                  # show active sessions + branches
 cc-workspace session status feature-auth   # commits per repo on session branch
 cc-workspace session close feature-auth    # interactive: create PRs, delete branches, clean up
 ```
 
+From inside a Claude Code session (slash commands):
+```
+/session                          # list active sessions
+/session status feature-auth      # commits per repo
+/session close feature-auth       # interactive close
+```
+
 `session close` asks for confirmation before every action (PR creation, branch deletion, JSON cleanup).
 
 ### Parallel workflow
@@ -199,6 +208,36 @@ 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
+
+```mermaid
+graph LR
+    USER([You]) <-->|clarify\nplan\nreview| TL
+
+    subgraph "orchestrator/"
+        TL["Team Lead\n(Opus 4.6)"]
+        PLANS["plans/*.md"]
+        TL -->|writes| PLANS
+    end
+
+    TL -->|spawn| IMP1["Implementer\n(Sonnet)"]
+    TL -->|spawn| IMP2["Implementer\n(Sonnet)"]
+    TL -->|spawn| QA["QA Ruthless\n(Sonnet)"]
+    TL -.->|scan| EXP["Explorer\n(Haiku)"]
+
+    subgraph "/tmp/ worktrees"
+        IMP1 -->|commit| WT1["repo-api\nsession/feat"]
+        IMP2 -->|commit| WT2["repo-front\nsession/feat"]
+    end
+
+    style TL fill:#6c5ce7,color:#fff
+    style IMP1 fill:#0d6efd,color:#fff
+    style IMP2 fill:#0d6efd,color:#fff
+    style QA fill:#e17055,color:#fff
+    style EXP fill:#636e72,color:#fff
+    style USER fill:#1a1a2e,color:#fff
+```
+
 ### Who does what
 
 | Role | Model | What it does |
@@ -221,6 +260,59 @@ parallel in each repo via Agent Teams.
 
 ### The dispatch-feature workflow (Mode A)
 
+```mermaid
+flowchart TD
+    START([User describes feature]) --> CLARIFY
+
+    subgraph "Phase 0 — Clarify"
+        CLARIFY[Ask max 5 questions\nif ambiguity]
+    end
+
+    CLARIFY --> PLAN
+
+    subgraph "Phase 1-2 — Plan"
+        PLAN[Load context\nworkspace.md + constitution.md]
+        PLAN --> WRITE[Write plan in ./plans/\ncommit units + API contract]
+        WRITE --> APPROVE{User approves?}
+        APPROVE -- No --> WRITE
+    end
+
+    APPROVE -- Yes --> SESSION
+
+    subgraph "Phase 2.5 — Session"
+        SESSION[Create session branches\ngit branch session/name source]
+    end
+
+    SESSION --> W1
+
+    subgraph "Phase 3 — Dispatch"
+        W1["Wave 1: Producers\n(API, data, auth)"]
+        W1 -->|"contracts validated"| W2["Wave 2: Consumers\n(frontend, integrations)"]
+        W2 --> W3["Wave 3: Infra\n(gateway, config)"]
+
+        W1 -.- IMP1["Implementer\nCommit 1/3"]
+        W1 -.- IMP2["Implementer\nCommit 2/3"]
+        W1 -.- IMP3["Implementer\nCommit 3/3"]
+    end
+
+    W3 --> VERIFY
+
+    subgraph "Phase 4-5 — Verify"
+        VERIFY[cross-service-check\n+ qa-ruthless]
+    end
+
+    VERIFY --> REPORT([Final summary\n+ propose fixes])
+
+    style START fill:#1a1a2e,color:#fff
+    style REPORT fill:#1a1a2e,color:#fff
+    style APPROVE fill:#2d3436,color:#fff
+    style IMP1 fill:#0d6efd,color:#fff
+    style IMP2 fill:#0d6efd,color:#fff
+    style IMP3 fill:#0d6efd,color:#fff
+```
+
+**Text version:**
+
 ```
 CLARIFY  -> ask max 5 questions if ambiguity
 PLAN     -> write the plan in ./plans/, wait for approval
@@ -299,6 +391,23 @@ All hooks in settings.json are **non-blocking** (exit 0 + warning). No hook bloc
 
 ---
 
+## Slash commands (in-session)
+
+These skills can be invoked directly from a Claude Code session, replacing the CLI for common operations.
+
+| Command | CLI equivalent | What it does |
+|---------|---------------|--------------|
+| `/session` | `cc-workspace session list` | List active sessions with branches and commit counts |
+| `/session status X` | `cc-workspace session status X` | Detailed session view: commits, files changed |
+| `/session close X` | `cc-workspace session close X` | Interactive: create PRs, delete branches, cleanup |
+| `/doctor` | `cc-workspace doctor` | Full diagnostic of workspace installation |
+| `/cleanup` | _(no CLI equivalent)_ | Remove orphan worktrees, stale sessions, dangling containers |
+
+> These slash commands use `context: fork` — they don't pollute the orchestrator's context.
+> The CLI commands (`npx cc-workspace ...`) remain available for terminal use outside sessions.
+
+---
+
 ## The 3 templates
 
 | Template | Usage |
@@ -345,6 +454,8 @@ in every teammate spawn prompt (teammates don't receive it automatically).
 
 - `claude --resume` resumes the session with the team-lead agent
 - The SessionStart hook automatically injects active plans
+- Orphan worktrees in `/tmp/` are cleaned up automatically at session start
+- Run `/cleanup` to manually purge stale worktrees, sessions, and containers
 - The markdown plan on disk is the source of truth
 
 | Emoji | Status |
@@ -353,6 +464,7 @@ in every teammate spawn prompt (teammates don't receive it automatically).
 | 🔄 | IN PROGRESS |
 | ✅ | DONE |
 | ❌ | BLOCKED/FAILED |
+| ❌ ESCALATED | Failed 2+ times, wave stopped, waiting for user |
 
 ---
 
@@ -363,7 +475,7 @@ The package uses semver. The installed version is tracked in `~/.claude/.orchest
 ```bash
 npx cc-workspace version    # shows package and installed versions
 npx cc-workspace update     # updates if newer version
-npx cc-workspace doctor     # full diagnostic
+npx cc-workspace doctor     # full diagnostic (or /doctor in-session)
 ```
 
 On each `init` or `update`, the CLI compares versions:
@@ -406,8 +518,11 @@ cc-workspace/
     │       ├── container-strategies.md
     │       ├── test-frameworks.md
     │       └── scenario-extraction.md
-    ├── hooks/                         <- 11 scripts (warning-only)
-    ├── rules/                         <- 3 rules
+    ├── 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)
 ```
 
@@ -417,7 +532,7 @@ 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`, `block-orchestrator-writes.sh` (security), `CLAUDE.md`, `_TEMPLATE.md`
+- **Always regenerated**: `settings.json`, `CLAUDE.md`, `_TEMPLATE.md`
 - **Always copied**: hooks, templates
 - **Always regenerated on init**: `service-profiles.md` (fresh scan)
 - **Global components**: only updated if the version is newer (or `--force`)
@@ -486,6 +601,19 @@ With `--chrome`, the agent:
 
 ---
 
+## Changelog v4.5.1 -> v4.6.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Framework-agnostic UX standards** | `frontend-ux-standards.md` no longer hardcodes Quasar. Breakpoints, dialogs, and design system sections now reference the project's chosen library. Constitution overrides are documented. |
+| 2 | **Rollback protocol externalized** | Rollback and failed dispatch procedures moved from team-lead agent prompt (203→~170 lines) to `references/rollback-protocol.md`. Reduces base context load. |
+| 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 | **Mermaid diagrams in README** | Architecture overview and dispatch workflow now have visual flowcharts. Text fallback preserved. |
+
+---
+
 ## Changelog v4.4.0 -> v4.5.0
 
 | # | Feature | Detail |

package/bin/cli.js

@@ -825,6 +825,65 @@ switch (command) {
     break;
   }
 
+  case "uninstall": {
+    log(BANNER_SMALL);
+    step("Uninstalling global components");
+
+    const readline = require("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+
+    (async () => {
+      const answer = await ask(
+        `  Remove all cc-workspace components from ${c.dim}~/.claude/${c.reset}? [y/N] `
+      );
+      if (answer.toLowerCase() !== "y") {
+        log(`  ${c.dim}Cancelled.${c.reset}\n`);
+        rl.close();
+        return;
+      }
+
+      // Skills
+      if (fs.existsSync(GLOBAL_SKILLS)) {
+        const skipDirs = new Set(["rules", "agents", "hooks", "templates"]);
+        const skillDirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+          .filter(e => e.isDirectory() && !skipDirs.has(e.name))
+          .map(e => e.name);
+        let n = 0;
+        for (const name of skillDirs) {
+          const target = path.join(GLOBAL_SKILLS, name);
+          if (fs.existsSync(target)) { fs.rmSync(target, { recursive: true }); n++; }
+        }
+        ok(`${n} skills removed`);
+      }
+
+      // Rules
+      for (const f of ["context-hygiene.md", "model-routing.md"]) {
+        const fp = path.join(GLOBAL_RULES, f);
+        if (fs.existsSync(fp)) fs.unlinkSync(fp);
+      }
+      ok("Rules removed");
+
+      // Agents
+      for (const f of ["team-lead.md", "implementer.md", "workspace-init.md", "e2e-validator.md"]) {
+        const fp = path.join(GLOBAL_AGENTS, f);
+        if (fs.existsSync(fp)) fs.unlinkSync(fp);
+      }
+      ok("Agents removed");
+
+      // Version file
+      if (fs.existsSync(VERSION_FILE)) fs.unlinkSync(VERSION_FILE);
+      ok("Version tracking removed");
+
+      log("");
+      log(`  ${c.green}${c.bold}Uninstall complete.${c.reset}`);
+      log(`  ${c.dim}Local orchestrator/ directories are preserved — remove them manually if needed.${c.reset}`);
+      log("");
+      rl.close();
+    })();
+    break;
+  }
+
   case "version":
   case "--version":
   case "-v": {
@@ -864,6 +923,10 @@ switch (command) {
     log(`    ${c.cyan}npx cc-workspace session close${c.reset} ${c.dim}<name>${c.reset}`);
     log(`      Interactive close: create PRs, delete branches, clean up.`);
     log("");
+    log(`    ${c.cyan}npx cc-workspace uninstall${c.reset}`);
+    log(`      Remove all global components from ~/.claude/ (interactive).`);
+    log(`      Local orchestrator/ directories are preserved.`);
+    log("");
     log(`    ${c.cyan}npx cc-workspace version${c.reset}`);
     log(`      Show package and installed versions.`);
     log("");

package/global-skills/agents/team-lead.md

@@ -150,37 +150,10 @@ See @dispatch-feature/references/spawn-templates.md for full templates.
 ### Wave completion
 All commit units of all services in a wave must be ✅ before launching next wave.
 
-## Rollback protocol
-
-If an implementer corrupts the session branch (bad merge, broken state):
-
-1. Identify the last known good commit hash (from plan's session log)
-2. Spawn a Task subagent (Bash):
-   ```
-   git -C ../[repo] update-ref refs/heads/session/{name} [good-commit-hash]
-   ```
-3. Mark the commit unit ❌ in the plan with reason
-4. Re-dispatch with corrected instructions
-
-If the branch is unrecoverable:
-1. Delete the branch: `git -C ../[repo] branch -D session/{name}`
-2. Recreate from source: `git -C ../[repo] branch session/{name} {source_branch}`
-3. Re-dispatch ALL commit units for this service from scratch
-4. Warn the user — this resets all progress on this service
-
-## Failed dispatch tracking
-
-After 2 failed re-dispatches of a commit unit:
-
-1. Mark as `❌ ESCALATED` in the plan
-2. Record in the plan's **Failed dispatches** section:
-   - Commit unit title
-   - Failure reason (from implementer report)
-   - Attempted fixes
-   - Suggested resolution
-3. **STOP the wave** — do NOT continue to the next commit unit
-4. Present the failure to the user, ask for direction
-5. Resume only after user provides corrective action
+## Rollback & failure handling
+
+See @dispatch-feature/references/rollback-protocol.md for the full rollback and
+failed dispatch escalation procedures.
 
 ## What you CAN write
 - Plans in `./plans/`

package/global-skills/agents/workspace-init.md

@@ -13,7 +13,7 @@ maxTurns: 80
 
 # Workspace Init — Diagnostic & Configuration
 
-You are the initialization agent for the orchestrator workspace v4.0.
+You are the initialization agent for the orchestrator workspace.
 Your job: verify everything is in place, fix what can be fixed,
 and guide the user to configure what needs their input.
 
@@ -50,7 +50,7 @@ Check global components (read-only, no auto-fix):
 
 | # | Check | If missing |
 |---|-------|-----------|
-| 10 | `~/.claude/skills/` contains all 9 skills | List the missing ones |
+| 10 | `~/.claude/skills/` contains all 13 skills | List the missing ones |
 | 11 | `~/.claude/rules/` contains context-hygiene.md, model-routing.md | List the missing ones |
 | 12 | `~/.claude/agents/` contains team-lead.md, implementer.md, workspace-init.md | List the missing ones |
 

package/global-skills/dispatch-feature/references/frontend-ux-standards.md

@@ -3,6 +3,11 @@
 This document is injected into every frontend teammate's prompt.
 It defines the minimum expected UX quality level.
 
+> **Project-specific overrides**: If `constitution.md` defines a design system
+> (e.g., MUI, Ant Design, Vuetify, Shadcn), those rules take precedence over
+> the framework-specific examples below. The principles (4 states, responsive,
+> a11y, forms) are universal — only the component names and breakpoints change.
+
 ## The 4 mandatory states
 
 Every component that displays data MUST implement:
@@ -33,8 +38,9 @@ Every component that displays data MUST implement:
 ## Responsive
 
 - **Mobile first**: build the mobile version first
-- Quasar breakpoints: `$breakpoint-xs` (0-599), `$breakpoint-sm` (600-1023),
-  `$breakpoint-md` (1024-1439), `$breakpoint-lg` (1440+)
+- Use the project's breakpoint system. Common defaults:
+  - xs (0-599), sm (600-1023), md (1024-1439), lg (1440+)
+  - Adapt to the actual framework (Quasar `$breakpoint-*`, Tailwind `sm:/md:/lg:`, MUI `useMediaQuery`, etc.)
 - Data tables on mobile: switch to card/list view, no horizontal scroll
 - Forms on mobile: stacked fields, appropriate native keyboard (inputmode)
 - Primary actions: accessible with the thumb (bottom zone of the screen)
@@ -45,7 +51,7 @@ Every component that displays data MUST implement:
 - **Optimistic updates** for quick actions (toggle, delete)
   with rollback on API error
 - **Confirmation** for destructive actions (delete, reset)
-  via Quasar dialog, not window.confirm()
+  via the project's dialog/modal component, never window.confirm()
 - **Transitions** between states: fade 150ms by default
 - **Disabled state** clear on buttons during processing (no double submit)
 
@@ -67,7 +73,7 @@ Every component that displays data MUST implement:
 
 ## Design system
 
-- Use native Quasar components first (QTable, QForm, QDialog...)
-- Do not reinvent a component that exists in Quasar
-- Colors, spacing, and typography follow the project's Quasar theme
-- Icons come from a single set (Material Icons or the configured one)
+- Use the project's component library first (e.g., Quasar, MUI, Ant Design, Vuetify, Shadcn)
+- Do not reinvent a component that exists in the chosen library
+- Colors, spacing, and typography follow the project's theme/design tokens
+- Icons come from a single set (the one configured in the project)

package/global-skills/dispatch-feature/references/rollback-protocol.md

@@ -0,0 +1,35 @@
+# Rollback & Failed Dispatch Protocol
+
+Reference file for team-lead and dispatch-feature. Loaded on-demand.
+
+## Rollback protocol
+
+If an implementer corrupts the session branch (bad merge, broken state):
+
+1. Identify the last known good commit hash (from plan's session log)
+2. Spawn a Task subagent (Bash):
+   ```
+   git -C ../[repo] update-ref refs/heads/session/{name} [good-commit-hash]
+   ```
+3. Mark the commit unit ❌ in the plan with reason
+4. Re-dispatch with corrected instructions
+
+If the branch is unrecoverable:
+1. Delete the branch: `git -C ../[repo] branch -D session/{name}`
+2. Recreate from source: `git -C ../[repo] branch session/{name} {source_branch}`
+3. Re-dispatch ALL commit units for this service from scratch
+4. Warn the user — this resets all progress on this service
+
+## Failed dispatch tracking
+
+After 2 failed re-dispatches of a commit unit:
+
+1. Mark as `❌ ESCALATED` in the plan
+2. Record in the plan's **Failed dispatches** section:
+   - Commit unit title
+   - Failure reason (from implementer report)
+   - Attempted fixes
+   - Suggested resolution
+3. **STOP the wave** — do NOT continue to the next commit unit
+4. Present the failure to the user, ask for direction
+5. Resume only after user provides corrective action

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

@@ -33,8 +33,8 @@ If unclear, investigate all layers.
 ## Phase 2: Investigate (parallel)
 
 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
-- **Frontend, Gateway, Infra, Auth**: lightweight Explore subagents (Task, Haiku) for read-only scan. Use LSP tool where available for tracing
+- **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.
 
 Multiple teammates can share findings and challenge each other's hypotheses.
 This adversarial pattern finds root causes faster than sequential investigation.

package/global-skills/qa-ruthless/SKILL.md

@@ -42,7 +42,8 @@ Spawn one teammate per service impacted. All run in parallel via Agent Teams.
 
 Include in spawn prompt: **full constitution (all rules from constitution.md)**, plan context, then these steps:
 1. Run test suite — report pass/fail with details
-2. Use the **LSP tool** (go-to-definition, find-references) to trace call chains
+2. Use the **LSP tool** (go-to-definition, find-references) to trace call chains.
+   If LSP is unavailable, fall back to Grep + Glob for tracing references manually.
 3. **Constitution check**: multi-tenant scoping, secrets, rollback, test coverage
 4. **Code quality**: missing validation, missing auth checks, N+1, error handling, race conditions
 5. **Dead code hunt**: unused imports, unreachable methods, abandoned feature flags
@@ -54,7 +55,8 @@ Include in spawn prompt: **full constitution (all rules from constitution.md)**,
 
 Include in spawn prompt: **full constitution (all rules from constitution.md)**, plan context, UX standards, then these steps:
 1. Run tests — report pass/fail
-2. Use the **LSP tool** for tracing component dependencies and store usage
+2. Use the **LSP tool** for tracing component dependencies and store usage.
+   If LSP is unavailable, fall back to Grep + Glob for tracing references manually.
 3. **UX audit** on every new/modified component: 4 states (skeleton not spinner, empty+CTA, error+retry, smooth success), responsive, a11y, interactions (debounce, optimistic, confirmation), forms (inline validation, error messages, preserve data)
 4. **Constitution check**: data precision, feedback <200ms
 5. **Code quality**: TypeScript `any`, unsafe `as`, infinite loops, XSS via v-html

package/package.json

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