claude-code-workflow 6.3.53 → 7.0.0

package/.claude/skills/team-executor/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: team-executor
+description: Lightweight session execution skill. Resumes existing team-coordinate sessions for pure execution. No analysis, no role generation -- only loads and executes. Session path required. Triggers on "team executor".
+allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+---
+
+# Team Executor
+
+Lightweight session execution skill: load session -> reconcile state -> spawn workers -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions.
+
+## Architecture
+
+```
++---------------------------------------------------+
+|  Skill(skill="team-executor")                      |
+|  args="--session=<path>" [REQUIRED]                |
+|  args="--role=<name>" (for worker dispatch)        |
++-------------------+-------------------------------+
+                    | Session Validation
+         +---- --session valid? ----+
+         | NO                       | YES
+         v                          v
+    Error immediately         Role Router
+    (no session)                  |
+                          +-------+-------+
+                          | --role present?
+                          |       |
+                     YES  |       | NO
+                     v    |       v
+              Route to    |   Orchestration Mode
+              session     |   -> executor
+              role.md     |
+```
+
+---
+
+## Session Validation (BEFORE routing)
+
+**CRITICAL**: Session validation MUST occur before any role routing.
+
+### Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- `--session=<path>`: Path to team-coordinate session folder (REQUIRED)
+- `--role=<name>`: Role to dispatch (optional, defaults to orchestration mode)
+
+### Validation Steps
+
+1. **Check `--session` provided**:
+   - If missing -> **ERROR**: "Session required. Usage: --session=<path-to-TC-folder>"
+   - Do NOT proceed
+
+2. **Validate session structure** (see specs/session-schema.md):
+   - Directory exists at path
+   - `team-session.json` exists and valid JSON
+   - `task-analysis.json` exists and valid JSON
+   - `roles/` directory has at least one `.md` file
+   - Each role in `team-session.json#roles` has corresponding `.md` file in `roles/`
+
+3. **Validation failure**:
+   - Report specific missing component
+   - Suggest re-running team-coordinate or checking path
+   - Do NOT proceed
+
+### Validation Checklist
+
+```
+Session Validation Checklist:
+[ ] --session argument provided
+[ ] Directory exists at path
+[ ] team-session.json exists and parses
+[ ] task-analysis.json exists and parses
+[ ] roles/ directory has >= 1 .md files
+[ ] All session.roles[] have corresponding roles/<role>.md
+```
+
+---
+
+## Role Router
+
+### Dispatch Logic
+
+| Scenario | Action |
+|----------|--------|
+| No `--session` | **ERROR** immediately |
+| `--session` invalid | **ERROR** with specific reason |
+| No `--role` | Orchestration Mode -> executor |
+| `--role=executor` | Read built-in `roles/executor/role.md` |
+| `--role=<other>` | Read `<session>/roles/<role>.md` |
+
+### Orchestration Mode
+
+When invoked without `--role`, executor auto-starts.
+
+**Invocation**: `Skill(skill="team-executor", args="--session=<session-folder>")`
+
+**Lifecycle**:
+```
+Validate session
+  -> executor Phase 0: Reconcile state (reset interrupted, detect orphans)
+  -> executor Phase 1: Spawn first batch workers (background) -> STOP
+  -> Worker executes -> SendMessage callback -> executor advances next step
+  -> Loop until pipeline complete -> Phase 2 report
+```
+
+**User Commands** (wake paused executor):
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | Output execution status graph, no advancement |
+| `resume` / `continue` | Check worker states, advance next step |
+
+---
+
+## Role Registry
+
+| Role | File | Type |
+|------|------|------|
+| executor | [roles/executor/role.md](roles/executor/role.md) | built-in orchestrator |
+| (dynamic) | `<session>/roles/<role-name>.md` | loaded from session |
+
+> **COMPACT PROTECTION**: Role files are execution documents. After context compression, role instructions become summaries only -- **MUST immediately `Read` the role.md to reload before continuing**. Never execute any Phase based on summaries.
+
+---
+
+## Shared Infrastructure
+
+The following templates apply to all worker roles. Each loaded role.md follows the same structure.
+
+### Worker Phase 1: Task Discovery (all workers shared)
+
+Each worker on startup executes the same task discovery flow:
+
+1. Call `TaskList()` to get all tasks
+2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
+3. No tasks -> idle wait
+4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress
+
+**Resume Artifact Check** (prevent duplicate output after resume):
+- Check if this task's output artifacts already exist
+- Artifacts complete -> skip to Phase 5 report completion
+- Artifacts incomplete or missing -> normal Phase 2-4 execution
+
+### Worker Phase 5: Report + Fast-Advance (all workers shared)
+
+Task completion with optional fast-advance to skip executor round-trip:
+
+1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
+   - Params: operation="log", team=**<session-id>**, from=<role>, to="executor", type=<message-type>, summary="[<role>] <summary>", ref=<artifact-path>
+   - **`team` must be session ID** (e.g., `TC-my-project-2026-02-27`), NOT team name. Extract from task description `Session:` field -> take folder name.
+   - **CLI fallback**: `ccw team log --team <session-id> --from <role> --to executor --type <type> --summary "[<role>] ..." --json`
+2. **TaskUpdate**: Mark task completed
+3. **Fast-Advance Check**:
+   - Call `TaskList()`, find pending tasks whose blockedBy are ALL completed
+   - If exactly 1 ready task AND its owner matches a simple successor pattern -> **spawn it directly** (skip executor)
+   - Otherwise -> **SendMessage** to executor for orchestration
+4. **Loop**: Back to Phase 1 to check for next task
+
+**Fast-Advance Rules**:
+
+| Condition | Action |
+|-----------|--------|
+| Same-prefix successor (Inner Loop role) | Do not spawn, main agent inner loop (Phase 5-L) |
+| 1 ready task, simple linear successor, different prefix | Spawn directly via Task(run_in_background: true) |
+| Multiple ready tasks (parallel window) | SendMessage to executor (needs orchestration) |
+| No ready tasks + others running | SendMessage to executor (status update) |
+| No ready tasks + nothing running | SendMessage to executor (pipeline may be complete) |
+
+**Fast-advance failure recovery**: If a fast-advanced task fails, the executor detects it as an orphaned in_progress task on next `resume`/`check` and resets it to pending for re-spawn. Self-healing. See [monitor.md](roles/executor/commands/monitor.md).
+
+### Worker Inner Loop (roles with multiple same-prefix serial tasks)
+
+When a role has **2+ serial same-prefix tasks**, it loops internally instead of spawning new agents:
+
+**Inner Loop flow**:
+
+```
+Phase 1: Discover task (first time)
+  |
+  +- Found task -> Phase 2-3: Load context + Execute work
+  |                |
+  |                v
+  |          Phase 4: Validation (+ optional Inline Discuss)
+  |                |
+  |                v
+  |          Phase 5-L: Loop Completion
+  |                |
+  |                +- TaskUpdate completed
+  |                +- team_msg log
+  |                +- Accumulate summary to context_accumulator
+  |                |
+  |                +- More same-prefix tasks?
+  |                |   +- YES -> back to Phase 1 (inner loop)
+  |                |   +- NO -> Phase 5-F: Final Report
+  |                |
+  |                +- Interrupt conditions?
+  |                    +- consensus_blocked HIGH -> SendMessage -> STOP
+  |                    +- Errors >= 3 -> SendMessage -> STOP
+  |
+  +- Phase 5-F: Final Report
+       +- SendMessage (all task summaries)
+       +- STOP
+```
+
+**Phase 5-L vs Phase 5-F**:
+
+| Step | Phase 5-L (looping) | Phase 5-F (final) |
+|------|---------------------|-------------------|
+| TaskUpdate completed | YES | YES |
+| team_msg log | YES | YES |
+| Accumulate summary | YES | - |
+| SendMessage to executor | NO | YES (all tasks summary) |
+| Fast-Advance to next prefix | - | YES (check cross-prefix successors) |
+
+### Wisdom Accumulation (all roles)
+
+Cross-task knowledge accumulation. Loaded from session at startup.
+
+**Directory**:
+```
+<session-folder>/wisdom/
++-- learnings.md      # Patterns and insights
++-- decisions.md      # Design and strategy decisions
++-- issues.md         # Known risks and issues
+```
+
+**Worker load** (Phase 2): Extract `Session: <path>` from task description, read wisdom files.
+**Worker contribute** (Phase 4/5): Write discoveries to corresponding wisdom files.
+
+### Role Isolation Rules
+
+| Allowed | Prohibited |
+|---------|-----------|
+| Process own prefix tasks | Process other role's prefix tasks |
+| SendMessage to executor | Directly communicate with other workers |
+| Use tools appropriate to responsibility | Create tasks for other roles |
+| Fast-advance simple successors | Spawn parallel worker batches |
+| Report capability_gap to executor | Attempt work outside scope |
+
+Executor additionally prohibited: directly write/modify deliverable artifacts, call implementation subagents directly, directly execute analysis/test/review, generate new roles.
+
+---
+
+## Cadence Control
+
+**Beat model**: Event-driven, each beat = executor wake -> process -> spawn -> STOP.
+
+```
+Beat Cycle (single beat)
+======================================================================
+  Event                   Executor                 Workers
+----------------------------------------------------------------------
+  callback/resume --> +- handleCallback -+
+                      |  mark completed   |
+                      |  check pipeline   |
+                      +- handleSpawnNext -+
+                      |  find ready tasks |
+                      |  spawn workers ---+--> [Worker A] Phase 1-5
+                      |  (parallel OK)  --+--> [Worker B] Phase 1-5
+                      +- STOP (idle) -----+         |
+                                                     |
+  callback <-----------------------------------------+
+  (next beat)              SendMessage + TaskUpdate(completed)
+======================================================================
+
+  Fast-Advance (skips executor for simple linear successors)
+======================================================================
+  [Worker A] Phase 5 complete
+    +- 1 ready task? simple successor? --> spawn Worker B directly
+    +- complex case? --> SendMessage to executor
+======================================================================
+```
+
+---
+
+## Executor Spawn Template
+
+### Standard Worker (single-task role)
+
+```
+Task({
+  subagent_type: "general-purpose",
+  description: "Spawn <role> worker",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: `You are team "<team-name>" <ROLE>.
+
+## Primary Instruction
+All your work MUST be executed by calling Skill to get role definition:
+Skill(skill="team-executor", args="--role=<role> --session=<session-folder>")
+
+Current requirement: <task-description>
+Session: <session-folder>
+
+## Role Guidelines
+- Only process <PREFIX>-* tasks, do not execute other role work
+- All output prefixed with [<role>] tag
+- Only communicate with executor
+- Do not use TaskCreate to create tasks for other roles
+- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team=<session-id> from Session field, NOT team name)
+- After task completion, check for fast-advance opportunity (see SKILL.md Phase 5)
+
+## Workflow
+1. Call Skill -> get role definition and execution logic
+2. Follow role.md 5-Phase flow
+3. team_msg(team=<session-id>) + SendMessage results to executor
+4. TaskUpdate completed -> check next task or fast-advance`
+})
+```
+
+### Inner Loop Worker (multi-task role)
+
+```
+Task({
+  subagent_type: "general-purpose",
+  description: "Spawn <role> worker (inner loop)",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: `You are team "<team-name>" <ROLE>.
+
+## Primary Instruction
+All your work MUST be executed by calling Skill to get role definition:
+Skill(skill="team-executor", args="--role=<role> --session=<session-folder>")
+
+Current requirement: <task-description>
+Session: <session-folder>
+
+## Inner Loop Mode
+You will handle ALL <PREFIX>-* tasks in this session, not just the first one.
+After completing each task, loop back to find the next <PREFIX>-* task.
+Only SendMessage to executor when:
+- All <PREFIX>-* tasks are done
+- A consensus_blocked HIGH occurs
+- Errors accumulate (>= 3)
+
+## Role Guidelines
+- Only process <PREFIX>-* tasks, do not execute other role work
+- All output prefixed with [<role>] tag
+- Only communicate with executor
+- Do not use TaskCreate to create tasks for other roles
+- Before each SendMessage, call mcp__ccw-tools__team_msg to log (team=<session-id> from Session field, NOT team name)
+- Use subagent calls for heavy work, retain summaries in context`
+})
+```
+
+---
+
+## Integration with team-coordinate
+
+| Scenario | Skill |
+|----------|-------|
+| New task, no session | team-coordinate |
+| Existing session, resume execution | **team-executor** |
+| Session needs new roles | team-coordinate (with --resume) |
+| Pure execution, no analysis | **team-executor** |
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No --session provided | ERROR immediately with usage message |
+| Session directory not found | ERROR with path, suggest checking path |
+| team-session.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| task-analysis.json missing | ERROR, session incomplete, suggest re-run team-coordinate |
+| No roles in session | ERROR, session incomplete, suggest re-run team-coordinate |
+| Role file not found | ERROR with expected path |
+| capability_gap reported | Warn only, cannot generate new roles (see monitor.md handleAdapt) |
+| Fast-advance spawns wrong task | Executor reconciles on next callback |

package/.claude/skills/team-executor/roles/executor/commands/monitor.md

@@ -0,0 +1,277 @@
+# Command: monitor
+
+## Purpose
+
+Event-driven pipeline coordination with Spawn-and-Stop pattern for team-executor. Adapted from team-coordinate monitor.md -- role names are read from `team-session.json#roles` instead of hardcoded. **handleAdapt is LIMITED**: only warns, cannot generate new roles.
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
+| ONE_STEP_PER_INVOCATION | true | Executor does one operation then STOPS |
+| FAST_ADVANCE_AWARE | true | Workers may skip executor for simple linear successors |
+| ROLE_GENERATION | disabled | handleAdapt cannot generate new roles |
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session file | `<session-folder>/team-session.json` | Yes |
+| Task list | `TaskList()` | Yes |
+| Active workers | session.active_workers[] | Yes |
+| Role registry | session.roles[] | Yes |
+
+**Dynamic role resolution**: Known worker roles are loaded from `session.roles[].name`. This is the same pattern as team-coordinate.
+
+## Phase 3: Handler Routing
+
+### Wake-up Source Detection
+
+Parse `$ARGUMENTS` to determine handler:
+
+| Priority | Condition | Handler |
+|----------|-----------|---------|
+| 1 | Message contains `[<role-name>]` from session roles | handleCallback |
+| 2 | Contains "capability_gap" | handleAdapt |
+| 3 | Contains "check" or "status" | handleCheck |
+| 4 | Contains "resume", "continue", or "next" | handleResume |
+| 5 | None of the above (initial spawn after dispatch) | handleSpawnNext |
+
+---
+
+### Handler: handleCallback
+
+Worker completed a task. Verify completion, update state, auto-advance.
+
+```
+Receive callback from [<role>]
+  +- Find matching active worker by role (from session.roles)
+  +- Is this a progress update (not final)? (Inner Loop intermediate task completion)
+  |   +- YES -> Update session state, do NOT remove from active_workers -> STOP
+  +- Task status = completed?
+  |   +- YES -> remove from active_workers -> update session
+  |   |   +- -> handleSpawnNext
+  |   +- NO -> progress message, do not advance -> STOP
+  +- No matching worker found
+      +- Scan all active workers for completed tasks
+      +- Found completed -> process each -> handleSpawnNext
+      +- None completed -> STOP
+```
+
+**Fast-advance note**: A worker may have already spawned its successor via fast-advance. When processing a callback:
+1. Check if the expected next task is already `in_progress` (fast-advanced)
+2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker
+3. If no -> normal handleSpawnNext
+
+---
+
+### Handler: handleCheck
+
+Read-only status report. No pipeline advancement.
+
+**Output format**:
+
+```
+[executor] Pipeline Status
+[executor] Progress: <completed>/<total> (<percent>%)
+
+[executor] Execution Graph:
+  <visual representation of dependency graph with status icons>
+
+  done=completed  >>>=running  o=pending  .=not created
+
+[executor] Active Workers:
+  > <subject> (<role>) - running <elapsed> [inner-loop: N/M tasks done]
+
+[executor] Ready to spawn: <subjects>
+[executor] Commands: 'resume' to advance | 'check' to refresh
+```
+
+**Icon mapping**: completed=done, in_progress=>>>, pending=o, not created=.
+
+**Graph rendering**: Read dependency_graph from task-analysis.json, render each node with status icon. Show parallel branches side-by-side.
+
+Then STOP.
+
+---
+
+### Handler: handleResume
+
+Check active worker completion, process results, advance pipeline.
+
+```
+Load active_workers from session
+  +- No active workers -> handleSpawnNext
+  +- Has active workers -> check each:
+      +- status = completed -> mark done, log
+      +- status = in_progress -> still running, log
+      +- other status -> worker failure -> reset to pending
+      After processing:
+        +- Some completed -> handleSpawnNext
+        +- All still running -> report status -> STOP
+        +- All failed -> handleSpawnNext (retry)
+```
+
+---
+
+### Handler: handleSpawnNext
+
+Find all ready tasks, spawn workers in background, update session, STOP.
+
+```
+Collect task states from TaskList()
+  +- completedSubjects: status = completed
+  +- inProgressSubjects: status = in_progress
+  +- readySubjects: pending + all blockedBy in completedSubjects
+
+Ready tasks found?
+  +- NONE + work in progress -> report waiting -> STOP
+  +- NONE + nothing in progress -> PIPELINE_COMPLETE -> Phase 2
+  +- HAS ready tasks -> for each:
+      +- Is task owner an Inner Loop role AND that role already has an active_worker?
+      |   +- YES -> SKIP spawn (existing worker will pick it up via inner loop)
+      |   +- NO -> normal spawn below
+      +- TaskUpdate -> in_progress
+      +- team_msg log -> task_unblocked (team=<session-id>, NOT team name)
+      +- Spawn worker (see spawn tool call below)
+      +- Add to session.active_workers
+      Update session file -> output summary -> STOP
+```
+
+**Spawn worker tool call** (one per ready task):
+
+```
+Task({
+  subagent_type: "general-purpose",
+  description: "Spawn <role> worker for <subject>",
+  team_name: <team-name>,
+  name: "<role>",
+  run_in_background: true,
+  prompt: "<worker prompt from SKILL.md Executor Spawn Template>"
+})
+```
+
+---
+
+### Handler: handleAdapt (LIMITED)
+
+Handle mid-pipeline capability gap discovery. **UNLIKE team-coordinate, executor CANNOT generate new roles.**
+
+```
+Receive capability_gap from [<role>]
+  +- Log via team_msg (type: warning)
+  +- Report to user:
+     "Capability gap detected: <gap_description>
+
+      team-executor cannot generate new roles.
+      Options:
+        1. Continue with existing roles (worker will skip gap work)
+        2. Re-run team-coordinate with --resume=<session> to extend session
+        3. Manually add role to <session>/roles/ and retry"
+  +- Extract: gap_description, requesting_role, suggested_capability
+  +- Validate gap is genuine:
+      +- Check existing roles in session.roles -> does any role cover this?
+      |   +- YES -> redirect: SendMessage to that role's owner -> STOP
+      |   +- NO -> genuine gap, report to user (cannot fix)
+  +- Do NOT generate new role
+  +- Continue execution with existing roles
+```
+
+**Key difference from team-coordinate**:
+| Aspect | team-coordinate | team-executor |
+|--------|-----------------|---------------|
+| handleAdapt | Generates new role, creates tasks, spawns worker | Only warns, cannot fix |
+| Recovery | Automatic | Manual (re-run team-coordinate) |
+
+---
+
+### Worker Failure Handling
+
+When a worker has unexpected status (not completed, not in_progress):
+
+1. Reset task -> pending via TaskUpdate
+2. Log via team_msg (type: error)
+3. Report to user: task reset, will retry on next resume
+
+### Fast-Advance Failure Recovery
+
+When executor detects a fast-advanced task has failed (task in_progress but no callback and worker gone):
+
+```
+handleCallback / handleResume detects:
+  +- Task is in_progress (was fast-advanced by predecessor)
+  +- No active_worker entry for this task
+  +- Original fast-advancing worker has already completed and exited
+  +- Resolution:
+      1. TaskUpdate -> reset task to pending
+      2. Remove stale active_worker entry (if any)
+      3. Log via team_msg (type: error, summary: "Fast-advanced task <ID> failed, resetting for retry")
+      4. -> handleSpawnNext (will re-spawn the task normally)
+```
+
+**Detection in handleResume**:
+
+```
+For each in_progress task in TaskList():
+  +- Has matching active_worker? -> normal, skip
+  +- No matching active_worker? -> orphaned (likely fast-advance failure)
+      +- Check creation time: if > 5 minutes with no progress callback
+      +- Reset to pending -> handleSpawnNext
+```
+
+**Prevention**: Fast-advance failures are self-healing. The executor reconciles orphaned tasks on every `resume`/`check` cycle.
+
+### Consensus-Blocked Handling
+
+When a worker reports `consensus_blocked` in its callback:
+
+```
+handleCallback receives message with consensus_blocked flag
+  +- Extract: divergence_severity, blocked_round, action_recommendation
+  +- Route by severity:
+      |
+      +- severity = HIGH
+      |   +- Create REVISION task:
+      |       +- Same role, same doc type, incremented suffix (e.g., DRAFT-001-R1)
+      |       +- Description includes: divergence details + action items from discuss
+      |       +- blockedBy: none (immediate execution)
+      |       +- Max 1 revision per task (DRAFT-001 -> DRAFT-001-R1, no R2)
+      |       +- If already revised once -> PAUSE, escalate to user
+      |   +- Update session: mark task as "revised", log revision chain
+      |
+      +- severity = MEDIUM
+      |   +- Proceed with warning: include divergence in next task's context
+      |   +- Log action items to wisdom/issues.md
+      |   +- Normal handleSpawnNext
+      |
+      +- severity = LOW
+          +- Proceed normally: treat as consensus_reached with notes
+          +- Normal handleSpawnNext
+```
+
+## Phase 4: Validation
+
+| Check | Criteria |
+|-------|----------|
+| Session state consistent | active_workers matches TaskList in_progress tasks |
+| No orphaned tasks | Every in_progress task has an active_worker entry |
+| Dynamic roles valid | All task owners exist in session.roles |
+| Completion detection | readySubjects=0 + inProgressSubjects=0 -> PIPELINE_COMPLETE |
+| Fast-advance tracking | Detect tasks already in_progress via fast-advance, sync to active_workers |
+| Fast-advance orphan check | in_progress tasks without active_worker entry -> reset to pending |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Session file not found | Error, suggest re-run team-coordinate |
+| Worker callback from unknown role | Log info, scan for other completions |
+| All workers still running on resume | Report status, suggest check later |
+| Pipeline stall (no ready, no running) | Check for missing tasks, report to user |
+| Fast-advance conflict | Executor reconciles, no duplicate spawns |
+| Fast-advance task orphaned | Reset to pending, re-spawn via handleSpawnNext |
+| Dynamic role file not found | Error, cannot proceed without role definition |
+| capability_gap from role | WARN only, cannot generate new roles |
+| consensus_blocked HIGH | Create revision task (max 1) or pause for user |
+| consensus_blocked MEDIUM | Proceed with warning, log to wisdom/issues.md |