cc-workspace 4.0.3 → 4.0.5

package/README.md

@@ -1,4 +1,4 @@
-# Claude Code Multi-Workspace Orchestrator v4.0
+# Claude Code Multi-Workspace Orchestrator v4.0.5
 
 A system to pilot multi-service projects from Claude Code.
 The orchestrator (Opus) never codes in repos. It clarifies, plans,
@@ -66,8 +66,10 @@ claude --agent team-lead
 npx cc-workspace update
 ```
 
-Updates global components (~/.claude/) if the package version is newer.
-Workspace files (workspace.md, constitution.md, plans/) are never overwritten.
+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
+- **Never overwritten**: workspace.md, constitution.md, plans/
 
 ### Diagnostic
 
@@ -164,7 +166,7 @@ detects if the target path is in a repo (presence of `.git/`).
 
 Protection layers:
 1. `disallowedTools: Bash` in agent frontmatter
-2. `allowed-tools` whitelist in agent frontmatter
+2. `tools` whitelist in agent frontmatter (note: `allowed-tools` is the skill equivalent)
 3. `PreToolUse` path-aware hook in agent frontmatter
 4. `block-orchestrator-writes.sh` hook in .claude/hooks/
 
@@ -224,7 +226,7 @@ All hooks are **non-blocking** (exit 0 + warning). No hook blocks the session.
 | Template | Usage |
 |----------|-------|
 | `workspace.template.md` | Structure for workspace.md (project, service map, relationships, rules, onboarding) |
-| `constitution.template.md` | Structure for constitution.md (project rules 13+) |
+| `constitution.template.md` | Structure for constitution.md (your engineering principles) |
 | `claude-md.template.md` | Standardized structure for repo CLAUDE.md files (stack, arch, rules, tests, anti-patterns) |
 
 ---
@@ -251,17 +253,13 @@ The `orchestrator/` directory is portable:
 
 ## The constitution
 
-### Global (scoped to workspace)
+`constitution.md` in orchestrator/. You define **all** your engineering
+principles here — security, UX, code quality, process, project-specific rules.
+The `workspace-init` agent helps you write it interactively.
 
-12 universal principles in `~/.claude/rules/constitution-en.md`.
-Scoped to orchestrator files (`workspace.md`, `plans/**`, etc.).
-**v4.0**: teammates no longer receive it automatically.
-The orchestrator includes it in every spawn prompt.
-
-### Project (to customize)
-
-`constitution.md` in orchestrator/. Contains **only** project-specific
-rules (numbered 13+).
+There is no global constitution imposed by the package. Each workspace
+defines its own rules. The orchestrator includes the full constitution
+in every teammate spawn prompt (teammates don't receive it automatically).
 
 ---
 
@@ -307,7 +305,6 @@ cc-workspace/
 ├── LICENSE
 │
 └── global-skills/                     <- components installed in ~/.claude/
-    ├── constitution.md                <- 12 principles (EN)
     ├── templates/
     │   ├── workspace.template.md
     │   ├── constitution.template.md
@@ -335,12 +332,12 @@ cc-workspace/
 
 ## Idempotence
 
-The setup is safe to re-run:
-- Does not overwrite `workspace.md` or `constitution.md` if already present
-- Always regenerates `service-profiles.md` (fresh scan)
-- Always regenerates `settings.json` and `block-orchestrator-writes.sh` (security)
-- Templates are always copied
-- Global components are only updated if the version is newer
+Both `init` and `update` are safe to re-run:
+- **Never overwritten**: `workspace.md`, `constitution.md`, `plans/*.md` (user content)
+- **Always regenerated**: `settings.json`, `block-orchestrator-writes.sh` (security), `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`)
 
 ---
 
@@ -357,7 +354,7 @@ The setup is safe to re-run:
 | 7 | **Warning-only hooks** | No more blocking hooks (exit 2 -> exit 0). |
 | 8 | **verify-cycle-complete removed** | No more exit blocking. |
 | 9 | **Orchestrator can write** | In orchestrator/ only. Dynamic path-aware hook. |
-| 10 | **Scoped constitution** | `globs: ["*"]` -> orchestrator files only. |
+| 10 | **Per-workspace constitution** | No global constitution — each workspace defines its own rules. |
 | 11 | **30-line limit removed** | The orchestrator adapts verbosity to context. |
 | 12 | **Structured templates** | workspace.template.md + constitution.template.md + claude-md.template.md. |
 

package/bin/cli.js

@@ -324,7 +324,7 @@ You clarify, plan, delegate, track.
 
 ## Security
 - \`disallowedTools: Bash\` — no direct shell
-- \`allowed-tools\` : Read, Write, Edit, Glob, Grep, Task, Teammate, SendMessage
+- \`tools\` : Read, Write, Edit, Glob, Grep, Task(implementer, Explore), Teammate, SendMessage
 - Hook \`PreToolUse\` path-aware: allows orchestrator/, blocks sibling repos
 
 > settings.json contains env vars + hooks registration.
@@ -424,6 +424,80 @@ function planTemplateContent() {
 `;
 }
 
+// ─── Update local orchestrator/ components ──────────────────
+// Called by `update` when run from a workspace that contains orchestrator/
+// or from inside orchestrator/ itself.
+function updateLocal() {
+  const cwd = process.cwd();
+  // Detect if we're inside orchestrator/ or in the parent workspace
+  let orchDir;
+  if (fs.existsSync(path.join(cwd, "workspace.md"))) {
+    orchDir = cwd; // inside orchestrator/
+  } else if (fs.existsSync(path.join(cwd, "orchestrator", "workspace.md"))) {
+    orchDir = path.join(cwd, "orchestrator");
+  } else {
+    return false; // no local orchestrator found
+  }
+
+  step(`Updating local: ${c.dim}${orchDir}${c.reset}`);
+  let count = 0;
+
+  // ── Hooks (always overwrite — security critical) ──
+  const hooksDir = path.join(orchDir, ".claude", "hooks");
+  if (fs.existsSync(hooksDir)) {
+    generateBlockHook(hooksDir);
+    count++;
+    const hooksSrc = path.join(SKILLS_DIR, "hooks");
+    if (fs.existsSync(hooksSrc)) {
+      for (const f of fs.readdirSync(hooksSrc)) {
+        if (!f.endsWith(".sh") || f === "verify-cycle-complete.sh") continue;
+        copyFile(path.join(hooksSrc, f), path.join(hooksDir, f));
+        fs.chmodSync(path.join(hooksDir, f), 0o755);
+        count++;
+      }
+    }
+    ok(`${count} hooks updated`);
+  }
+
+  // ── settings.json (always regenerate — hook registration) ──
+  const settingsPath = path.join(orchDir, ".claude", "settings.json");
+  if (fs.existsSync(path.join(orchDir, ".claude"))) {
+    generateSettings(orchDir);
+    ok("settings.json regenerated");
+  }
+
+  // ── Templates (always overwrite — reference docs) ──
+  const templatesDir = path.join(SKILLS_DIR, "templates");
+  const localTemplates = path.join(orchDir, "templates");
+  if (fs.existsSync(templatesDir) && fs.existsSync(localTemplates)) {
+    let tplCount = 0;
+    for (const f of fs.readdirSync(templatesDir)) {
+      if (f.endsWith(".md")) {
+        copyFile(path.join(templatesDir, f), path.join(localTemplates, f));
+        tplCount++;
+      }
+    }
+    ok(`${tplCount} templates updated`);
+  }
+
+  // ── CLAUDE.md (always overwrite — generated file, not user content) ──
+  const claudeMd = path.join(orchDir, "CLAUDE.md");
+  fs.writeFileSync(claudeMd, claudeMdContent());
+  ok("CLAUDE.md updated");
+
+  // ── Plan template (always overwrite — structure only) ──
+  const planTpl = path.join(orchDir, "plans", "_TEMPLATE.md");
+  if (fs.existsSync(path.join(orchDir, "plans"))) {
+    fs.writeFileSync(planTpl, planTemplateContent());
+    ok("_TEMPLATE.md updated");
+  }
+
+  // ── NEVER touch: workspace.md, constitution.md, plans/*.md, service-profiles.md ──
+  info(`${c.dim}workspace.md, constitution.md, plans/ — preserved${c.reset}`);
+
+  return true;
+}
+
 // ─── Setup workspace ────────────────────────────────────────
 function setupWorkspace(workspacePath, projectName) {
   const wsAbs = path.resolve(workspacePath);
@@ -685,10 +759,15 @@ switch (command) {
     const force = args.includes("--force");
     log(BANNER);
     const updated = installGlobals(force);
-    if (!updated) {
+    const localUpdated = (updated || force) ? updateLocal() : false;
+    if (!updated && !force) {
       log(`\n  ${c.dim}Already up to date. Use --force to reinstall.${c.reset}\n`);
     } else {
-      log(`\n  ${c.green}${c.bold}Update complete.${c.reset}\n`);
+      if (localUpdated) {
+        log(`\n  ${c.green}${c.bold}Update complete (globals + local orchestrator/).${c.reset}\n`);
+      } else {
+        log(`\n  ${c.green}${c.bold}Update complete (globals only — no local orchestrator/ found).${c.reset}\n`);
+      }
     }
     break;
   }
@@ -721,7 +800,9 @@ switch (command) {
     log(`      Installs global skills/rules/agents if version is newer.`);
     log("");
     log(`    ${c.cyan}npx cc-workspace update${c.reset} ${c.dim}[--force]${c.reset}`);
-    log(`      Update global components to this package version.`);
+    log(`      Update global components (skills, rules, agents).`);
+    log(`      Also updates local orchestrator/ if found (hooks, settings, CLAUDE.md, templates).`);
+    log(`      Never overwrites: workspace.md, constitution.md, plans/.`);
     log("");
     log(`    ${c.cyan}npx cc-workspace doctor${c.reset}`);
     log(`      Check all components are installed and consistent.`);

package/global-skills/agents/implementer.md

@@ -7,9 +7,8 @@ description: >
   (Agent Teams teammates get automatic isolation).
 isolation: worktree
 model: sonnet
-allowed-tools: Read, Write, Edit, MultiEdit, Bash, Glob, Grep
+tools: Read, Write, Edit, MultiEdit, Bash, Glob, Grep
 memory: project
-effort: medium
 maxTurns: 50
 ---
 

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

@@ -6,10 +6,9 @@ description: >
   quality. Never codes in repos — can write in orchestrator/.
   Triggered via claude --agent team-lead.
 model: opus
-allowed-tools: Read, Write, Edit, Glob, Grep, Task, Teammate, SendMessage
+tools: Read, Write, Edit, Glob, Grep, Task(implementer, Explore), Teammate, SendMessage
 disallowedTools: Bash
 memory: project
-effort: high
 maxTurns: 200
 hooks:
   PreToolUse:

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

@@ -6,9 +6,8 @@ description: >
   Interactively configures workspace.md and constitution.md if [UNCONFIGURED].
   Run once via: claude --agent workspace-init
 model: sonnet
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Task
+tools: Read, Write, Edit, Bash, Glob, Grep, Task(Explore)
 memory: project
-effort: medium
 maxTurns: 80
 ---
 

package/global-skills/bootstrap-repo/SKILL.md

@@ -7,6 +7,7 @@ description: >
   or when a repo is detected without CLAUDE.md during setup.
 argument-hint: "[repo-path]"
 context: fork
+agent: general-purpose
 disable-model-invocation: true
 model: haiku
 allowed-tools: Read, Write, Glob, Grep, Bash

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

@@ -8,6 +8,7 @@ description: >
   "cross-service", "aligned", "pre-merge".
 argument-hint: "[feature-name]"
 context: fork
+agent: general-purpose
 disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep, Task
 ---

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

@@ -8,6 +8,7 @@ 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

package/global-skills/dispatch-feature/references/spawn-templates.md

@@ -85,6 +85,8 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 
 ## Explore/Haiku subagent template (read-only)
 
+Use `Task` with `subagent_type: Explore` and `model: haiku` for lightweight scans.
+
 ```
 You are an explorer scanning [target]. Read-only — do NOT modify any files.
 
@@ -94,3 +96,11 @@ You are an explorer scanning [target]. Read-only — do NOT modify any files.
 ## Report format
 [what to extract and how to format the findings]
 ```
+
+## Failure handling
+
+When a teammate reports back:
+- **Test regression or missing file** (recoverable): fix plan, re-dispatch ONCE
+- **Architectural decision not in plan** (blocking): STOP the wave, escalate to user
+- **No report after extended time**: send a status request via SendMessage
+- **Max re-dispatches per teammate per wave**: 2. After that, escalate to user.

package/global-skills/merge-prep/SKILL.md

@@ -7,6 +7,7 @@ description: >
   "prepare merge", "merge-prep", "ready to merge".
 argument-hint: "[feature-name]"
 context: fork
+agent: general-purpose
 disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep, Bash, Task
 ---

package/global-skills/plan-review/SKILL.md

@@ -7,6 +7,7 @@ description: >
   Use when a plan was just written or user says "review plan", "vérifie le plan".
 argument-hint: "[plan-name.md]"
 context: fork
+agent: Explore
 disable-model-invocation: true
 model: haiku
 allowed-tools: Read, Glob, Grep

package/global-skills/refresh-profiles/SKILL.md

@@ -5,6 +5,7 @@ description: >
   listed in workspace.md. Use when conventions changed, or user says
   "refresh profiles", "update profiles", "re-read CLAUDE.md files".
 context: fork
+agent: Explore
 disable-model-invocation: true
 model: haiku
 allowed-tools: Read, Write, Glob, Grep

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

@@ -12,7 +12,7 @@ If you write code for a repo (not a markdown plan), you have failed — delegate
 
 ## Security layers (3 layers in agent frontmatter — no settings.json pollution)
 1. **Agent frontmatter**: `disallowedTools` — refused at model level
-2. **Agent frontmatter**: `allowed-tools` — whitelist of permitted tools
+2. **Agent frontmatter**: `tools` — whitelist of permitted tools (note: `allowed-tools` is for skills only)
 3. **Agent hook**: `PreToolUse` in frontmatter — structured deny response
 
 ## Routing table
@@ -24,18 +24,6 @@ If you write code for a repo (not a markdown plan), you have failed — delegate
 | Explorers / cross-checks | **Haiku** | `model: haiku` in skill/agent frontmatter |
 | Plan review | **Haiku** | `model: haiku` in skill frontmatter |
 
-## Effort levels
-| Role | Effort | Rationale |
-|------|--------|-----------|
-| Orchestrator (team-lead) | **high** | Complex planning, multi-step reasoning |
-| Implementation teammates | **medium** | Focused implementation, clear scope |
-| QA investigators | **medium** | Thorough but bounded analysis |
-| Explorers / cross-checks (Haiku) | **low** | Fast scans, read-only |
-| Plan review (Haiku) | **low** | Structural checks, no deep reasoning |
-
-Effort levels are set in agent frontmatter (`effort: high|medium|low|max`).
-Use `max` only for critical debugging or complex architectural decisions.
-
 ## Custom agent `implementer`
 For Task subagents that need to write code in an isolated worktree,
 use `@implementer` (frontmatter with `isolation: worktree`).

package/package.json

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