cc-workspace 4.4.0 → 4.5.1

package/global-skills/dispatch-feature/SKILL.md

@@ -167,34 +167,32 @@ For each service in the current wave:
 **Cross-service parallelism**: Different services within the same wave can
 progress in parallel. Use parallel Task calls when possible.
 
-### Implementer spawn prompt — include for EVERY implementer
+### Implementer spawn prompt — context tiering
 
-1. **Which commit unit** this is: "You are implementing Commit 3 of 4 for service api"
-2. **Tasks for this commit only** (NOT the whole plan)
-3. **Constitution rules** from constitution.md (translated to English)
-4. **API contract** (if this commit involves API endpoints)
-5. **Repo path** and **session branch**: `session/{name}`
-6. **Previous context**: "Commits 1-2 are already on the branch (data layer + business logic).
-   You handle Commit 3: API layer. Do NOT redo earlier work."
-7. Instruction to read repo CLAUDE.md first
-8. Instruction to escalate if hitting an architectural decision not in the plan
+The implementer agent already knows its git workflow, commit protocol, and cleanup
+procedure. Do NOT repeat these in spawn prompts. Only provide specific values and context.
 
-See @references/spawn-templates.md for the full templates per service type.
+**Always include (Tier 1):**
+1. Which commit unit: "Commit N of M for service X"
+2. Tasks for this commit only (NOT the whole plan)
+3. Constitution rules from constitution.md (translated to English)
+4. Repo path + session branch: `session/{name}`
+5. Previous context: "Commits 1..N-1 are on the branch. Do NOT redo."
 
-> **Constitution in spawn prompts**: Implementers do NOT receive the constitution
-> automatically. You MUST include ALL rules from constitution.md in every spawn prompt.
-
-### Frontend implementers — extra context
+**Conditional (Tier 2):**
+- **Frontend commits with UI**: UX standards (from `references/frontend-ux-standards.md`)
+- **API commits**: API contract shapes (exact request/response)
+- **Frontend commits**: API contract as TypeScript interfaces
 
-When the commit unit involves UI components, also include:
-- The UX standards (content of `references/frontend-ux-standards.md`)
-- The exact API contract shapes for TypeScript interfaces
+**Never inject (Tier 3 — already in repo CLAUDE.md or agent instructions):**
+- Anti-patterns list (implementer reads CLAUDE.md)
+- Git workflow procedure (implementer agent already knows)
+- Full workspace context (implementer doesn't need it)
 
-### API implementers — extra context
+See @references/spawn-templates.md for templates per service type.
 
-When the commit unit involves API endpoints:
-- The API contract they must implement (exact shapes)
-- Note that frontend will build types from these shapes
+> **Constitution in spawn prompts**: Implementers do NOT receive the constitution
+> automatically. You MUST include ALL rules from constitution.md in every spawn prompt.
 
 ### Isolation
 

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

@@ -8,35 +8,36 @@ Reference file for dispatch-feature. Loaded on-demand, not at skill activation.
 > template below includes a "Constitution" section that you MUST fill with
 > all rules from your workspace's `constitution.md`.
 
+## Context tiering — what to inject per commit type
+
+| Context | Backend commits | Frontend commits | Infra commits |
+|---------|:-:|:-:|:-:|
+| Constitution rules | ALWAYS | ALWAYS | ALWAYS |
+| Commit unit tasks | ALWAYS | ALWAYS | ALWAYS |
+| Repo path + session branch | ALWAYS | ALWAYS | ALWAYS |
+| Previous commits summary | ALWAYS | ALWAYS | ALWAYS |
+| API contract shapes | If API commit | ALWAYS (TypeScript) | Never |
+| UX standards | Never | If UI commit | Never |
+| Anti-patterns | Never (read CLAUDE.md) | Never (read CLAUDE.md) | Never |
+
+> **Deduplication note**: The implementer agent already knows its git workflow
+> (worktree creation, commit protocol, cleanup). Do NOT repeat the full git
+> procedure in spawn prompts. Only provide the SPECIFIC values: repo path,
+> session branch name, and source branch (if branch may not exist yet).
+
 ## Backend/API implementer spawn template
 
 ```
 You are implementer for [service], handling Commit [N] of [total]: [commit title].
 Commits 1 to [N-1] are already on the session branch. Do NOT redo earlier work.
 
-Read the CLAUDE.md in your repo first.
-
-## Git workflow (CRITICAL — read first)
-You are working in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST
-when the worktree is cleaned up.
-
-CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
-You are already in an isolated worktree — all git commands run HERE, not in the main repo.
-
-1. FIRST THING: Switch to the session branch inside your worktree:
-   git checkout session/{session-name}
-   (This is safe — you are in a worktree, not the main repo)
-2. Verify you are on the right branch:
-   git branch --show-current  (must show: session/{session-name})
-3. If checkout fails with "did not match any file(s)":
-   git fetch origin session/{session-name}
-   git checkout session/{session-name}
-4. Check existing commits: git log --oneline -5
-
-Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
+## Repo & branch
+- Repo: ../[service]
+- Session branch: session/[session-name]
+- Source branch: [source-branch] (only if branch may need creation)
 
 ## Constitution (non-negotiable)
-[paste all rules from your workspace's constitution.md]
+[paste all rules from your workspace's constitution.md, translated to English]
 
 ## API contract
 [paste the exact request/response shapes relevant to THIS commit]
@@ -51,16 +52,13 @@ Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
 ## Instructions
 1. Read the repo CLAUDE.md first — follow its conventions
 2. Implement ONLY the tasks above — do not touch code from earlier commits
-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. If your changes exceed ~300 lines, split into multiple commits
+3. Run the existing test suite — report pass/fail
+4. List any dead code created or exposed by your changes
+5. If your changes exceed ~300 lines, split into multiple commits
    (data → logic → API layer), each compilable
-7. If you hit an architectural decision NOT covered by the plan: STOP and
+6. If you hit an architectural decision NOT covered by the plan: STOP and
    report the dilemma instead of guessing
-8. COMMIT before reporting. Run: git status (must be clean), git log --oneline -3
-   (your commit must appear)
-9. Report back: commit hash + message, files created/modified, tests pass/fail,
+7. Report back: commit hash + message, files created/modified, tests pass/fail,
    dead code found, blockers
 ```
 
@@ -70,32 +68,15 @@ Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
 You are implementer for [service], handling Commit [N] of [total]: [commit title].
 Commits 1 to [N-1] are already on the session branch. Do NOT redo earlier work.
 
-Read the CLAUDE.md in your repo first.
-
-## Git workflow (CRITICAL — read first)
-You are working in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST
-when the worktree is cleaned up.
-
-CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
-You are already in an isolated worktree — all git commands run HERE, not in the main repo.
-
-1. FIRST THING: Switch to the session branch inside your worktree:
-   git checkout session/{session-name}
-   (This is safe — you are in a worktree, not the main repo)
-2. Verify you are on the right branch:
-   git branch --show-current  (must show: session/{session-name})
-3. If checkout fails with "did not match any file(s)":
-   git fetch origin session/{session-name}
-   git checkout session/{session-name}
-4. Check existing commits: git log --oneline -5
-
-Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
+## Repo & branch
+- Repo: ../[service]
+- Session branch: session/[session-name]
 
 ## Constitution (non-negotiable)
-[paste all rules from your workspace's constitution.md]
+[paste all rules from your workspace's constitution.md, translated to English]
 
-## UX Standards (non-negotiable)
-[paste full content of frontend-ux-standards.md — only if this commit involves UI components]
+## UX Standards (non-negotiable — only if this commit involves UI components)
+[paste full content of frontend-ux-standards.md]
 
 ## API contract (TypeScript interfaces)
 [paste exact response shapes relevant to THIS commit]
@@ -109,17 +90,14 @@ Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
 ## Instructions
 1. Read the repo CLAUDE.md first — follow its conventions
 2. Implement ONLY the tasks above — do not touch code from earlier commits
-3. Use the LSP tool for code navigation
-4. If this commit adds components: MUST handle 4 states (skeleton, 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. If your changes exceed ~300 lines, split into multiple commits
+3. If this commit adds components: MUST handle 4 states (skeleton, empty+CTA, error+retry, success)
+4. Run the existing test suite — report pass/fail
+5. List any dead code (unused components, composables, store actions, CSS)
+6. If your changes exceed ~300 lines, split into multiple commits
    (types → store → components → pages), each compilable
-8. If you hit an architectural decision NOT covered by the plan: STOP and escalate
-9. COMMIT before reporting. Run: git status (must be clean), git log --oneline -3
-   (your commit must appear)
-10. Report back: commit hash + message, files created/modified, tests pass/fail,
-    dead code found, UX compliance, blockers
+7. If you hit an architectural decision NOT covered by the plan: STOP and escalate
+8. Report back: commit hash + message, files created/modified, tests pass/fail,
+   dead code found, UX compliance, blockers
 ```
 
 ## Infra/Config implementer spawn template
@@ -128,29 +106,12 @@ Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
 You are implementer for [service], handling Commit [N] of [total]: [commit title].
 Commits 1 to [N-1] are already on the session branch. Do NOT redo earlier work.
 
-Read the CLAUDE.md in your repo first.
-
-## Git workflow (CRITICAL — read first)
-You are working in a temporary worktree. If you don't commit, YOUR WORK WILL BE LOST
-when the worktree is cleaned up.
-
-CRITICAL: Do NOT run `git checkout` in the main repo. Do NOT use `git -C ../repo checkout`.
-You are already in an isolated worktree — all git commands run HERE, not in the main repo.
-
-1. FIRST THING: Switch to the session branch inside your worktree:
-   git checkout session/{session-name}
-   (This is safe — you are in a worktree, not the main repo)
-2. Verify you are on the right branch:
-   git branch --show-current  (must show: session/{session-name})
-3. If checkout fails with "did not match any file(s)":
-   git fetch origin session/{session-name}
-   git checkout session/{session-name}
-4. Check existing commits: git log --oneline -5
-
-Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
+## Repo & branch
+- Repo: ../[service]
+- Session branch: session/[session-name]
 
 ## Constitution (non-negotiable)
-[paste all rules from your workspace's constitution.md]
+[paste all rules from your workspace's constitution.md, translated to English]
 
 ## Your single commit unit
 [paste ONLY the tasks for this commit — typically gateway routes, configs, env vars]
@@ -165,9 +126,7 @@ Branch `session/{session-name}` ALREADY EXISTS. Do NOT create other branches.
 4. No application code changes — only configuration
 5. Commit message format: `chore(service): description`
 6. If you hit an architectural decision NOT covered by the plan: STOP and escalate
-7. COMMIT before reporting. Run: git status (must be clean), git log --oneline -3
-   (your commit must appear)
-8. Report back: commit hash + message, files modified, consistency check results, blockers
+7. Report back: commit hash + message, files modified, consistency check results, blockers
 ```
 
 ## Explore/Haiku subagent template (read-only)
@@ -189,7 +148,8 @@ You are an explorer scanning [target]. Read-only — do NOT modify any files.
 When an implementer reports back:
 - **Test regression or missing file** (recoverable): fix commit unit description, re-dispatch ONCE
 - **Architectural decision not in plan** (blocking): STOP the wave, escalate to user
-- **No commit in report**: the implementer forgot to commit. Verify on session branch
-  with a Task subagent. If no commit exists, re-dispatch with emphasis on committing.
-- **Max re-dispatches per commit unit**: 2. After that, escalate to user.
+- **No commit in report**: verify on session branch with a Task subagent.
+  If no commit exists, re-dispatch with emphasis on committing.
+- **Max re-dispatches per commit unit**: 2. After that → mark ❌ ESCALATED, stop the wave.
 - **Giant commit (>400 lines)**: note in session log, consider splitting in future plans
+- **Corrupted branch**: use rollback protocol (see team-lead agent instructions)

package/global-skills/doctor/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: doctor
+description: >
+  Full diagnostic of the orchestrator workspace installation. Checks global
+  components (skills, rules, agents), local structure (hooks, settings,
+  workspace.md), and repo health (CLAUDE.md, test frameworks).
+  Use: /doctor
+argument-hint: ""
+context: fork
+model: haiku
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# Doctor — Workspace Diagnostic
+
+Run a comprehensive health check of the orchestrator installation.
+
+## Checks to perform
+
+### 1. Global components (~/.claude/)
+```bash
+# Version
+cat ~/.claude/.orchestrator-version 2>/dev/null || echo "NOT INSTALLED"
+```
+
+Check existence of:
+- `~/.claude/skills/` — count skill directories (expect 10+)
+- `~/.claude/rules/context-hygiene.md`
+- `~/.claude/rules/model-routing.md`
+- `~/.claude/agents/team-lead.md`
+- `~/.claude/agents/implementer.md`
+- `~/.claude/agents/workspace-init.md`
+- `~/.claude/agents/e2e-validator.md`
+
+### 2. Local orchestrator structure
+Find orchestrator dir (./workspace.md or ./orchestrator/workspace.md).
+
+Check:
+- `workspace.md` exists and is configured (no `[UNCONFIGURED]`)
+- `constitution.md` exists and has rules
+- `plans/` directory exists
+- `plans/_TEMPLATE.md` exists
+- `templates/` directory exists
+- `.claude/settings.json` exists and has hooks config
+- `.claude/hooks/` — count .sh files, verify executable permissions
+- `.sessions/` directory exists
+- `e2e/` directory exists
+
+### 3. Dependencies
+```bash
+jq --version 2>/dev/null || echo "MISSING"
+git --version 2>/dev/null || echo "MISSING"
+docker compose version 2>/dev/null || echo "MISSING (optional, for E2E)"
+gh --version 2>/dev/null || echo "MISSING (optional, for PRs)"
+```
+
+### 4. Sibling repos health
+For each directory in `../` with `.git/`:
+- Has CLAUDE.md? (yes/no)
+- Has `.claude/settings.json`? (yes/no)
+- Detected type (package.json → Vue/React/Node, composer.json → PHP, etc.)
+- Has test config? (vitest.config.*, phpunit.xml, pytest.ini, etc.)
+- Stale worktrees? `git worktree list` — flag any in /tmp/
+
+### 5. Orphan worktrees
+```bash
+# Check for stale /tmp/ worktrees
+ls -d /tmp/*-session-* /tmp/e2e-* 2>/dev/null
+```
+
+## Output format
+
+Present results as a markdown table:
+
+```
+| Check | Status | Detail |
+|-------|--------|--------|
+| Installed version | ✅ | v4.5.0 |
+| Skills (12/10) | ✅ | |
+| workspace.md | ✅ | Configured |
+| jq | ✅ | jq-1.7 |
+| docker | ⚠️ | Not installed (optional) |
+| repo: api | ✅ | PHP/Laravel, CLAUDE.md ✓ |
+| repo: front | ⚠️ | Vue/Quasar, CLAUDE.md ✗ |
+| Orphan worktrees | ✅ | None |
+```
+
+End with:
+- If all OK: "All checks passed."
+- If issues: list recommended fixes.

package/global-skills/hooks/session-start-context.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # session-start-context.sh
-# SessionStart hook: injects active plan context and repo status.
+# SessionStart hook: injects active plan context, repo status, and cleans orphan worktrees.
 # Stdout on exit 0 is added as context visible to Claude.
 set -euo pipefail
 
@@ -8,7 +8,39 @@ cat > /dev/null
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 OUTPUT=""
 
-# Find active plans (plans with pending ⏳ or in-progress 🔄 tasks)
+# ── Orphan worktree cleanup ──────────────────────────────────
+# Clean /tmp/ worktrees that were left behind by crashed implementers.
+# These are safe to remove: they're temporary by design.
+ORPHAN_COUNT=0
+for wt in /tmp/*-session-* /tmp/e2e-* 2>/dev/null; do
+    [ -d "$wt" ] || continue
+    # Check if the worktree is registered with any repo
+    REPO_FOUND=0
+    PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)" || continue
+    for repo_dir in "$PARENT_DIR"/*/; do
+        [ -d "$repo_dir/.git" ] || continue
+        if git -C "$repo_dir" worktree list 2>/dev/null | grep -q "$wt"; then
+            # Worktree is registered — check if it's stale (no git lock, no recent activity)
+            if [ ! -f "$wt/.git" ]; then
+                # Not a valid worktree anymore — remove registration
+                git -C "$repo_dir" worktree remove "$wt" --force 2>/dev/null && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+                REPO_FOUND=1
+                break
+            fi
+            REPO_FOUND=1
+            break
+        fi
+    done
+    if [ "$REPO_FOUND" -eq 0 ] && [ -d "$wt/.git" ] || [ -f "$wt/.git" ]; then
+        # Unregistered worktree directory — likely a crash remnant. Remove it.
+        rm -rf "$wt" 2>/dev/null && ORPHAN_COUNT=$((ORPHAN_COUNT + 1))
+    fi
+done
+if [ "$ORPHAN_COUNT" -gt 0 ]; then
+    OUTPUT+="[Cleanup] Removed $ORPHAN_COUNT orphan worktree(s) from /tmp/.\n"
+fi
+
+# ── Active plans ─────────────────────────────────────────────
 if [ -d "$PROJECT_DIR/plans" ]; then
     ACTIVE_PLANS=$(find "$PROJECT_DIR/plans" -name '*.md' \
         ! -name '_TEMPLATE.md' \
@@ -29,14 +61,13 @@ if [ -d "$PROJECT_DIR/plans" ]; then
         done <<< "$ACTIVE_PLANS"
         OUTPUT+="\nRead these plans to resume where you left off.\n"
 
-        # Export active plan name to Claude's environment if supported
         if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "$FIRST_PLAN" ]; then
             echo "ACTIVE_PLAN=$FIRST_PLAN" >> "$CLAUDE_ENV_FILE"
         fi
     fi
 fi
 
-# Detect active sessions
+# ── Active sessions ──────────────────────────────────────────
 SESSIONS_DIR="$PROJECT_DIR/.sessions"
 if [ -d "$SESSIONS_DIR" ]; then
     ACTIVE_SESSIONS=""
@@ -54,12 +85,12 @@ if [ -d "$SESSIONS_DIR" ]; then
     fi
 fi
 
-# Check workspace.md exists
+# ── Workspace check ──────────────────────────────────────────
 if [ ! -f "$PROJECT_DIR/workspace.md" ]; then
     OUTPUT+="[WARNING] No workspace.md found. Run setup-workspace.sh first.\n"
 fi
 
-# First-session detection
+# ── First-session detection ──────────────────────────────────
 if [ -f "$PROJECT_DIR/workspace.md" ]; then
     if grep -q '\[UNCONFIGURED\]' "$PROJECT_DIR/workspace.md" 2>/dev/null; then
         OUTPUT+="[FIRST SESSION] workspace.md is not yet configured. Run: claude --agent workspace-init\n"
@@ -77,7 +108,7 @@ if [ -f "$PROJECT_DIR/workspace.md" ]; then
     fi
 fi
 
-# Auto-discovery: detect new repos not in workspace.md
+# ── Auto-discovery: new repos ────────────────────────────────
 if [ -f "$PROJECT_DIR/workspace.md" ] && ! grep -q '\[UNCONFIGURED\]' "$PROJECT_DIR/workspace.md" 2>/dev/null; then
     PARENT_DIR="$(cd "$PROJECT_DIR/.." 2>/dev/null && pwd)"
     NEW_REPOS=""

package/global-skills/session/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: session
+description: >
+  Manage parallel feature sessions. List active sessions, show detailed status
+  with commits per repo, or close a session (PRs + branch cleanup).
+  Use: /session, /session status <name>, /session close <name>.
+argument-hint: "[list | status <name> | close <name>]"
+context: fork
+allowed-tools: Bash, Read, Glob, Grep
+---
+
+# Session Manager
+
+You manage parallel feature sessions from the orchestrator.
+
+## Detect context
+
+1. Find the orchestrator directory:
+   - If `./workspace.md` exists → you're in orchestrator/
+   - If `../orchestrator/workspace.md` exists → orchestrator is at `../orchestrator/`
+   - Otherwise → error: "No orchestrator found. Run from orchestrator/ or its parent."
+
+2. Read `.sessions/*.json` files to list sessions.
+
+## Commands
+
+### /session (no args) or /session list
+List all sessions with their status:
+```
+For each .sessions/*.json:
+  - Name, status (active/closed), created date
+  - For each repo: session branch, branch_created status
+  - Commit count on session branch vs source branch
+```
+
+Run for each active session repo:
+```bash
+git -C ../[repo] log session/[name] --oneline --not [source_branch] 2>/dev/null | wc -l
+```
+
+Present as a clean table.
+
+### /session status <name>
+Detailed view of one session:
+```bash
+# For each repo in the session JSON:
+git -C ../[repo] log session/[name] --oneline --not [source_branch] 2>/dev/null
+git -C ../[repo] diff --stat [source_branch]..session/[name] 2>/dev/null
+```
+
+Show: commits list, files changed, lines added/removed.
+
+### /session close <name>
+Interactive close — ask before EACH action:
+
+1. **For each repo**: offer to create PR
+   ```bash
+   gh pr create --repo [remote] --base [source_branch] --head session/[name] \
+     --title "[session-name]: [repo]" --body "Session: [session-name]"
+   ```
+   Ask: "Create PR session/X → source in [repo]? [y/N]"
+
+2. **For each repo**: offer to delete session branch
+   First check for unpushed commits:
+   ```bash
+   git -C ../[repo] log session/[name] --oneline --not --remotes 2>/dev/null
+   ```
+   If unpushed: warn before deletion.
+   Ask: "Delete branch session/X in [repo]? [y/N]"
+   ```bash
+   git -C ../[repo] branch -D session/[name]
+   ```
+
+3. **Session file**: offer to delete or mark closed
+   Ask: "Delete .sessions/[name].json? [y/N]"
+   If no → mark status as "closed" in the JSON.
+
+## Output format
+Use clean markdown tables. Keep it concise.

package/package.json

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