cc-workspace 4.0.5 → 4.1.1

package/README.md

@@ -1,65 +1,64 @@
-# Claude Code Multi-Workspace Orchestrator v4.0.5
+# cc-workspace
 
-A system to pilot multi-service projects from Claude Code.
-The orchestrator (Opus) never codes in repos. It clarifies, plans,
-delegates to teammates who work in parallel in each repo.
+**Claude Code Multi-Workspace Orchestrator** — turn Claude Code into a team of AI developers that work in parallel across your repos.
 
-> Claude Code v2.1.47+ / Opus 4.6 / Sonnet 4.6 (February 2026).
-> 9 skills, 11 hooks, 3 agents, 3 rules.
+Instead of Claude Code trying to do everything in one session and losing context, `cc-workspace` sets up an orchestrator (Opus) that clarifies requirements, writes a plan, then delegates to teammates (Sonnet) who implement in parallel — each in their own repo, their own worktree, their own context.
+
+> Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.1.47+ with Agent Teams.
+> Works with Opus 4.6, Sonnet 4.6, Haiku 4.5 (February 2026).
 
 ---
 
-## Installation
+## Quick start
 
 ### Prerequisites
 
-- **Claude Code** v2.1.47+
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** v2.1.47+
 - **Node.js** 18+
 - **jq** (`brew install jq` on macOS, `apt install jq` on Linux)
 
-### 1. Workspace setup
+### Setup a workspace
 
 ```bash
+# Navigate to the parent directory containing your repos
 cd ~/projects/my-workspace
+
+# Initialize the orchestrator (no install needed)
 npx cc-workspace init . "My Project"
 ```
 
-The CLI:
-- Installs skills/rules/agents in `~/.claude/` (if newer version)
-- Creates `orchestrator/` with plans/, templates/, hooks
-- Scans sibling repos (directories with `.git/`)
-- Generates `service-profiles.md`
-- workspace.md and constitution.md in `[UNCONFIGURED]` mode
+This creates an `orchestrator/` directory and installs 9 skills, 3 agents, 11 hooks, and 3 rules into `~/.claude/`.
 
-### 2. Initialization (one time only)
+### Configure (one time)
 
 ```bash
 cd orchestrator/
 claude --agent workspace-init
-# type "go" to start the diagnostic
+# type "go" to start the interactive diagnostic
 ```
 
-The `workspace-init` agent:
-1. Diagnoses the structure (hooks, settings, templates)
-2. Scans sibling repos, detects project types, checks Claude Code readiness
-3. Offers to generate missing CLAUDE.md files (optional)
-4. Interactive configuration of workspace.md (section by section)
-5. Interactive configuration of constitution.md (project rules)
-6. Final report with each check's status
+The init agent will:
+1. Scan sibling repos and detect their tech stacks
+2. Offer to generate missing `CLAUDE.md` files for each repo
+3. Walk you through `workspace.md` configuration (section by section)
+4. Walk you through `constitution.md` (your engineering principles)
 
-### 3. Work sessions
+### Start working
 
 ```bash
 cd orchestrator/
 claude --agent team-lead
-
-# The team-lead offers 4 modes:
-# A -- Full (clarify -> plan -> validate -> dispatch -> QA)
-# B -- Quick plan (specs -> plan -> dispatch)
-# C -- Go direct (immediate dispatch)
-# D -- Single-service (1 repo, no waves)
 ```
 
+The team-lead offers 4 modes:
+
+| Mode | When to use |
+|------|-------------|
+| **A -- Full** | Complex feature, multi-service, needs clarification |
+| **B -- Quick plan** | Clear specs, no questions needed |
+| **C -- Go direct** | Hotfix, quick fix, obvious specs |
+| **D -- Single-service** | Bug or isolated feature in a single repo |
+
 ### Update
 
 ```bash
@@ -68,7 +67,7 @@ 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
+- **Local** (if `orchestrator/` found): hooks, settings.json, CLAUDE.md, templates, _TEMPLATE.md
 - **Never overwritten**: workspace.md, constitution.md, plans/
 
 ### Diagnostic
@@ -341,6 +340,31 @@ Both `init` and `update` are safe to re-run:
 
 ---
 
+## 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. |
+
+---
+
+## Changelog v4.0 -> v4.0.5
+
+| # | Fix | Detail |
+|---|-----|--------|
+| 1 | **Agent frontmatter fix** | `allowed-tools` → `tools` on all 3 agents. `allowed-tools` is the skill field — agents use `tools`. Without this fix, tool restrictions were silently ignored. |
+| 2 | **Removed `effort` field** | `effort: high/medium/low` doesn't exist in Claude Code spec. Removed from all agents. |
+| 3 | **Skill `agent` field** | Added `agent: Explore` or `agent: general-purpose` to 6 skills for proper subagent routing. |
+| 4 | **`Task(type)` restrictions** | team-lead restricted to `Task(implementer, Explore)`, workspace-init to `Task(Explore)`. |
+| 5 | **`update` fixes local files** | `npx cc-workspace update` now also updates local orchestrator/ files (hooks, settings.json, CLAUDE.md, templates, _TEMPLATE.md). Previously only updated globals. |
+| 6 | **Failure handling** | Added failure handling section to spawn-templates: max 2 re-dispatches, escalation criteria. |
+
+---
+
 ## Changelog v3.5.0 -> v4.0
 
 | # | Feature | Detail |

package/bin/cli.js

@@ -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

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

@@ -78,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
 
@@ -99,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/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,9 +105,12 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-workspace",
-  "version": "4.0.5",
+  "version": "4.1.1",
   "description": "Claude Code multi-workspace orchestrator — skills, hooks, agents, and templates for multi-service projects",
   "bin": {
     "cc-workspace": "./bin/cli.js"
@@ -20,7 +20,15 @@
     "workspace",
     "monorepo"
   ],
-  "author": "VincVan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VincentVanN/cc-workspace.git"
+  },
+  "homepage": "https://github.com/VincentVanN/cc-workspace#readme",
+  "bugs": {
+    "url": "https://github.com/VincentVanN/cc-workspace/issues"
+  },
+  "author": "VincentVanN",
   "license": "MIT",
   "engines": {
     "node": ">=18"