cc-workspace 4.5.1 → 4.6.1

package/README.md

@@ -208,6 +208,28 @@ 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 |
@@ -231,15 +253,49 @@ parallel in each repo via Agent Teams.
 ### The dispatch-feature workflow (Mode A)
 
 ```
-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
+  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
 ```
 
 ### Security — path-aware writes
@@ -518,6 +574,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 | **ASCII diagrams in README** | Architecture overview and dispatch workflow now have visual diagrams (ASCII art, compatible with GitHub and npm). |
+
+---
+
 ## 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.1",
+  "version": "4.6.1",
   "description": "Claude Code multi-workspace orchestrator — skills, hooks, agents, and templates for multi-service projects",
   "bin": {
     "cc-workspace": "./bin/cli.js"