cc-workspace 4.0.4 → 4.1.0

package/README.md

@@ -1,4 +1,4 @@
-# Claude Code Multi-Workspace Orchestrator v4.0
+# Claude Code Multi-Workspace Orchestrator v4.1.0
 
 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/
 
@@ -330,12 +332,24 @@ 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`)
+
+---
+
+## Changelog v4.0.5 -> v4.1.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **Atomic commits** | Plan template splits tasks into commit-sized units (~300 lines max). Teammates commit as they go, not a single giant commit at the end. |
+| 2 | **Progress tracker** | Plan includes a progress tracker table: commits planned vs done per service, visible at a glance. |
+| 3 | **Commit strategy in spawn templates** | All teammate templates (backend, frontend, infra) include a mandatory commit strategy section with layer-by-layer split guidelines. |
+| 4 | **Commit granularity enforcement** | Team-lead checks commit count vs plan, flags giant commits (>400 lines), requires split before accepting a wave. |
+| 5 | **Teammate commit reporting** | Teammates report commits made (hash + message) alongside files and tests. |
 
 ---
 

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.
@@ -399,7 +399,7 @@ function planTemplateContent() {
 ## Impacted services
 | Service | Impacted | Branch | Teammate | Status |
 |---------|----------|--------|----------|--------|
-| | yes/no | | | ⏳ |
+| | yes/no | feature/[name] | | ⏳ |
 
 ## Waves
 - Wave 1: [producers]
@@ -407,12 +407,33 @@ function planTemplateContent() {
 - Wave 3: [infra]
 
 ## API contract
-[Exact shapes]
+[Exact request/response shapes for each endpoint]
 
 ## Tasks
 
 ### [service]
+
+#### Commit 1: [data layer — models, migrations, DTOs]
+- ⏳ [task]
 - ⏳ [task]
+> ~N files, ~N lines
+
+#### Commit 2: [business logic — use cases, services]
+- ⏳ [task]
+> ~N files, ~N lines
+
+#### Commit 3: [API/UI layer — controllers, routes, components]
+- ⏳ [task]
+> ~N files, ~N lines
+
+#### Commit 4: [tests]
+- ⏳ [task]
+> ~N files, ~N lines
+
+## Progress tracker
+| Service | Commits planned | Commits done | Tests | Status |
+|---------|:-:|:-:|:-:|:-:|
+| | N | 0 | ⏳ | ⏳ |
 
 ## QA
 - ⏳ Cross-service check
@@ -424,6 +445,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 +780,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 +821,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:
@@ -79,11 +78,11 @@ The workflow depends on the chosen mode:
 - **Mode D**: phases 1-2 then ONE teammate only, no waves
 
 1. CLARIFY — ask the missing questions (max 5, formulated as choices)
-2. PLAN — write the plan in markdown, wait for approval
+2. PLAN — write the plan in markdown with commit-sized task units, wait for approval
 3. DISPATCH — send teammates in waves (API/data first, frontend next)
-4. COLLECT — update the plan with results
+4. COLLECT — update the plan with results, verify commit granularity
 5. VERIFY — cross-service check then QA ruthless
-6. REPORT — present the summary, propose fixes
+6. REPORT — present the summary with commit inventory, propose fixes
 
 ## Dispatch mechanism — Agent Teams
 
@@ -100,12 +99,22 @@ For lightweight read-only tasks (scans, checks), you can use Task
 with Explore subagents (Haiku) — faster and cheaper.
 Explore subagents are read-only, they do NOT need a worktree.
 
+## Commit granularity enforcement
+
+When collecting teammate reports:
+- **Check commit count vs plan** — the plan defines N commit units, the teammate must have N+ commits
+- **Flag giant commits** — any commit >400 lines gets flagged in the session log
+- **If a teammate made a single commit for all tasks**: ask them to split via SendMessage
+  before accepting the wave as complete
+- **Progress tracker** in the plan must be updated after each teammate report
+
 ## What you NEVER do
 - Write code in sibling repos (that's the teammates' job)
 - Modify a file in a repo (delegate via Agent Teams)
 - Guess when you can ask
 - Forget to include the full constitution in spawn prompts
 - Forget UX standards for frontend teammates
+- Accept a single giant commit covering multiple tasks — enforce atomic commits
 - Let the context grow (compact after each cycle)
 - Launch wave 2 before wave 1 has reported
 

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/SKILL.md

@@ -63,6 +63,23 @@ Create `./plans/{feature-name}.md` using `./plans/_TEMPLATE.md`.
 Include: context, clarification answers, services impacted, dependency waves,
 detailed tasks per service, API contract (exact shapes), and autonomous choices if applicable.
 
+### Commit planning (mandatory)
+
+For EACH service, break tasks into **commit-sized units** (~300 lines max each):
+- **Commit 1**: Data layer — models, migrations, DTOs, repositories
+- **Commit 2**: Business logic — use cases, services, validation
+- **Commit 3**: API/UI layer — controllers, routes, components, pages
+- **Commit 4**: Tests for the above
+
+Each commit unit in the plan must:
+- Have a descriptive title (becomes the commit message)
+- List the specific tasks it covers
+- Estimate ~N files, ~N lines
+- Be independently compilable and testable
+
+The plan also includes a **progress tracker** table summarizing commits planned
+vs done per service, visible at a glance.
+
 ### Dependency waves
 
 - **Wave 1**: Producers — API backend, data/analytics, auth (define contracts)
@@ -127,11 +144,13 @@ Never mix: one teammate per repo per wave. No two teammates editing the same rep
 ## Phase 4: Collect and update
 
 On each teammate report:
-1. Update `./plans/{feature-name}.md` — statuses ✅ or ❌
-2. Note dead code found
-3. If a teammate failed → analyze, correct plan, re-dispatch
-4. **Session log** entry: `[HH:MM] teammate-[service]: [status], [N] files, tests [pass/fail]`
-5. If current wave done → launch next wave
+1. Update `./plans/{feature-name}.md` — statuses ✅ or ❌ per commit unit
+2. Update the **progress tracker** table (commits done / planned)
+3. Note dead code found
+4. Verify commit count and sizes — flag if a teammate made a single giant commit
+5. If a teammate failed → analyze, correct plan, re-dispatch
+6. **Session log** entry: `[HH:MM] teammate-[service]: [status], [N] commits, [N] files, tests [pass/fail]`
+7. If current wave done → launch next wave
 
 ## Phase 5: Post-implementation
 

package/global-skills/dispatch-feature/references/anti-patterns.md

@@ -28,3 +28,6 @@ Reference file for dispatch-feature. Loaded on-demand when Claude needs reminder
 | Plan has vague tasks like "implement feature" | Each task should have a clear input→output | Rewrite plan with specific tasks |
 | API contract has `{}` placeholder | Frontend can't build types | Complete the contract shapes before wave 2 |
 | Two teammates on same repo in same wave | Git conflicts guaranteed | Split into separate waves |
+| Giant commit (500+ lines) | PR unreadable, impossible to review | Split into atomic commits (~300 lines max) per logical unit |
+| Single commit at the end | All-or-nothing, no partial rollback | Commit after each logical unit — data, logic, API, tests |
+| Task without commit boundary | Teammate guesses the split | Plan must define commit units per task |

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

@@ -27,10 +27,23 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 3. Use the LSP tool for code navigation (go-to-definition, find-references)
 4. Run the existing test suite — report pass/fail
 5. List any dead code created or exposed by your changes
-6. Commit on branch feature/[name] with conventional commits
+6. **Atomic commits** — follow the commit plan below
 7. If you hit an architectural decision NOT covered by the plan: STOP and
    report the dilemma instead of guessing
-8. Report back: files created/modified, tests pass/fail, dead code found, blockers
+8. Report back: files created/modified, tests pass/fail, dead code found,
+   commits made (hash + message), blockers
+
+## Commit strategy (mandatory)
+- **One commit per logical unit** — each task in "Your tasks" = one commit minimum
+- **Max ~300 lines per commit** — if a task produces more, split it:
+  1. Data layer first (models, migrations, DTOs, repositories)
+  2. Business logic (use cases, services, validation)
+  3. API layer (controllers, routes, requests)
+  4. Tests for the above
+- **Commit message format**: `feat(domain): description` or `fix(domain): description`
+- **Each commit must compile and pass tests** — no broken intermediate states
+- **Commit as you go** — do NOT accumulate all changes for a single final commit
+- Branch: `feature/[name]` — create it on your first commit
 ```
 
 ## Frontend teammate spawn template
@@ -57,9 +70,23 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 4. Every new component MUST handle 4 states: skeleton loader, empty+CTA, error+retry, success
 5. Run the existing test suite — report pass/fail
 6. List any dead code (unused components, composables, store actions, CSS)
-7. Commit on branch feature/[name] with conventional commits
+7. **Atomic commits** — follow the commit plan below
 8. If you hit an architectural decision NOT covered by the plan: STOP and escalate
-9. Report back: files created/modified, tests pass/fail, dead code found, UX compliance, blockers
+9. Report back: files created/modified, tests pass/fail, dead code found,
+   UX compliance, commits made (hash + message), blockers
+
+## Commit strategy (mandatory)
+- **One commit per logical unit** — each task = one commit minimum
+- **Max ~300 lines per commit** — if a task produces more, split it:
+  1. Types/interfaces and API service layer
+  2. Store/composables (state management)
+  3. Components (one commit per complex component)
+  4. Page integration + routing
+  5. Tests for the above
+- **Commit message format**: `feat(domain): description` or `fix(domain): description`
+- **Each commit must compile and pass tests** — no broken intermediate states
+- **Commit as you go** — do NOT accumulate all changes for a single final commit
+- Branch: `feature/[name]` — create it on your first commit
 ```
 
 ## Infra/Config teammate spawn template
@@ -78,13 +105,18 @@ You are teammate-[service]. Read the CLAUDE.md in your repo first.
 2. Implement the configuration changes following the full constitution
 3. Verify consistency with other services (env vars, routes, schemas)
 4. No code changes — only configuration
-5. Commit on branch feature/[name]
-6. If you hit an architectural decision NOT covered by the plan: STOP and escalate
-7. Report back: files modified, consistency check results, blockers
+5. **Atomic commits** — one commit per logical config change
+6. Commit message format: `chore(service): description`
+7. If you hit an architectural decision NOT covered by the plan: STOP and escalate
+8. Report back: files modified, consistency check results,
+   commits made (hash + message), blockers
+- Branch: `feature/[name]`
 ```
 
 ## 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 +126,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.4",
+  "version": "4.1.0",
   "description": "Claude Code multi-workspace orchestrator — skills, hooks, agents, and templates for multi-service projects",
   "bin": {
     "cc-workspace": "./bin/cli.js"