claude-code-workflow 7.2.23 → 7.2.24

package/.codex/skills/team-iterdev/roles/coordinator/commands/analyze.md

@@ -1,62 +1,62 @@
-# Analyze Task
-
-Parse iterative development task -> detect capabilities -> assess pipeline complexity -> design roles.
-
-**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
-
-## Signal Detection
-
-| Keywords | Capability | Role |
-|----------|------------|------|
-| design, architect, restructure, refactor plan | architect | architect |
-| implement, build, code, fix, develop | developer | developer |
-| test, verify, validate, coverage | tester | tester |
-| review, audit, quality, check | reviewer | reviewer |
-
-## Pipeline Selection
-
-| Signal | Score |
-|--------|-------|
-| Changed files > 10 | +3 |
-| Changed files 3-10 | +2 |
-| Structural change (refactor, architect, restructure) | +3 |
-| Cross-cutting (multiple, across, cross) | +2 |
-| Simple fix (fix, bug, typo, patch) | -2 |
-
-| Score | Pipeline |
-|-------|----------|
-| >= 5 | multi-sprint |
-| 2-4 | sprint |
-| 0-1 | patch |
-
-## Dependency Graph
-
-Natural ordering tiers:
-- Tier 0: architect (design must come first)
-- Tier 1: developer (implementation requires design)
-- Tier 2: tester, reviewer (validation requires artifacts, can run parallel)
-
-## Complexity Assessment
-
-| Factor | Points |
-|--------|--------|
-| Cross-module changes | +2 |
-| Serial depth > 3 | +1 |
-| Multiple developers needed | +2 |
-| GC loop likely needed | +1 |
-
-## Output
-
-Write <session>/task-analysis.json:
-```json
-{
-  "task_description": "<original>",
-  "pipeline_type": "<patch|sprint|multi-sprint>",
-  "capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
-  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
-  "complexity": { "score": 0, "level": "Low|Medium|High" },
-  "needs_architecture": true,
-  "needs_testing": true,
-  "needs_review": true
-}
-```
+# Analyze Task
+
+Parse iterative development task -> detect capabilities -> assess pipeline complexity -> design roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Role |
+|----------|------------|------|
+| design, architect, restructure, refactor plan | architect | architect |
+| implement, build, code, fix, develop | developer | developer |
+| test, verify, validate, coverage | tester | tester |
+| review, audit, quality, check | reviewer | reviewer |
+
+## Pipeline Selection
+
+| Signal | Score |
+|--------|-------|
+| Changed files > 10 | +3 |
+| Changed files 3-10 | +2 |
+| Structural change (refactor, architect, restructure) | +3 |
+| Cross-cutting (multiple, across, cross) | +2 |
+| Simple fix (fix, bug, typo, patch) | -2 |
+
+| Score | Pipeline |
+|-------|----------|
+| >= 5 | multi-sprint |
+| 2-4 | sprint |
+| 0-1 | patch |
+
+## Dependency Graph
+
+Natural ordering tiers:
+- Tier 0: architect (design must come first)
+- Tier 1: developer (implementation requires design)
+- Tier 2: tester, reviewer (validation requires artifacts, can run parallel)
+
+## Complexity Assessment
+
+| Factor | Points |
+|--------|--------|
+| Cross-module changes | +2 |
+| Serial depth > 3 | +1 |
+| Multiple developers needed | +2 |
+| GC loop likely needed | +1 |
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<patch|sprint|multi-sprint>",
+  "capabilities": [{ "name": "<cap>", "role": "<role>", "keywords": ["..."] }],
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "needs_architecture": true,
+  "needs_testing": true,
+  "needs_review": true
+}
+```

package/.codex/skills/team-iterdev/roles/coordinator/commands/monitor.md

@@ -1,186 +1,227 @@
-# Command: Monitor
-
-Synchronous pipeline coordination using spawn_agent + wait_agent.
-
-## Constants
-
-- WORKER_AGENT: team_worker
-- MAX_GC_ROUNDS: 3
-
-## Handler Router
-
-| Source | Handler |
-|--------|---------|
-| "capability_gap" | handleAdapt |
-| "check" or "status" | handleCheck |
-| "resume" or "continue" | handleResume |
-| All tasks completed | handleComplete |
-| Default | handleSpawnNext |
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Session state | tasks.json | Yes |
-| Trigger event | From Entry Router detection | Yes |
-| Meta state | <session>/.msg/meta.json | Yes |
-
-1. Load tasks.json for current state, pipeline_mode, gc_round, max_gc_rounds
-2. Read tasks from tasks.json to get current task statuses
-3. Identify trigger event type from Entry Router
-
-## Phase 3: Event Handlers
-
-### handleCallback
-
-Triggered when a worker completes (wait_agent returns).
-
-1. Determine role from completed task prefix:
-
-| Task Prefix | Role Detection |
-|-------------|---------------|
-| `DESIGN-*` | architect |
-| `DEV-*` | developer |
-| `VERIFY-*` | tester |
-| `REVIEW-*` | reviewer |
-
-2. Mark task as completed in tasks.json:
-
-```
-state.tasks[taskId].status = 'completed'
-```
-
-3. Record completion in session state and update metrics
-
-4. **Generator-Critic check** (when reviewer completes):
-   - If completed task is REVIEW-* AND pipeline is sprint or multi-sprint:
-   - Read review report for GC signal (critical_count, score)
-   - Read tasks.json for gc_round
-
-   | GC Signal | gc_round < max | Action |
-   |-----------|----------------|--------|
-   | review.critical_count > 0 OR review.score < 7 | Yes | Increment gc_round, create DEV-fix task in tasks.json with deps on this REVIEW, log `gc_loop_trigger` |
-   | review.critical_count > 0 OR review.score < 7 | No (>= max) | Force convergence, accept with warning, log to wisdom/issues.md |
-   | review.critical_count == 0 AND review.score >= 7 | - | Review passed, proceed to handleComplete check |
-
-   - Log team_msg with type "gc_loop_trigger" or "task_unblocked"
-
-5. Proceed to handleSpawnNext
-
-### handleSpawnNext
-
-Find and spawn the next ready tasks.
-
-1. Read tasks.json, find tasks where:
-   - Status is "pending"
-   - All deps tasks have status "completed"
-
-2. For each ready task, determine role from task prefix:
-
-| Task Prefix | Role | Inner Loop |
-|-------------|------|------------|
-| DESIGN-* | architect | false |
-| DEV-* | developer | true |
-| VERIFY-* | tester | false |
-| REVIEW-* | reviewer | false |
-
-3. Spawn team_worker:
-
-```javascript
-// 1) Update status in tasks.json
-state.tasks[taskId].status = 'in_progress'
-
-// 2) Spawn worker
-const agentId = spawn_agent({
-  agent_type: "team_worker",
-  items: [
-    { type: "text", text: `## Role Assignment
-role: ${role}
-role_spec: ${skillRoot}/roles/${role}/role.md
-session: ${sessionFolder}
-session_id: ${sessionId}
-requirement: ${taskDescription}
-inner_loop: ${innerLoop}` },
-
-    { type: "text", text: `Read role_spec file to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` }
-  ]
-})
-
-// 3) Track agent
-state.active_agents[taskId] = { agentId, role, started_at: now }
-
-// 4) Wait for completion
-wait_agent({ ids: [agentId] })
-
-// 5) Collect results and update tasks.json
-state.tasks[taskId].status = 'completed'
-delete state.active_agents[taskId]
-```
-
-4. **Parallel spawn rules**:
-
-| Pipeline | Scenario | Spawn Behavior |
-|----------|----------|---------------|
-| Patch | DEV -> VERIFY | One worker at a time |
-| Sprint | VERIFY + REVIEW both unblocked | Spawn BOTH in parallel, wait_agent for both |
-| Sprint | Other stages | One worker at a time |
-| Multi-Sprint | VERIFY + DEV-fix both unblocked | Spawn BOTH in parallel, wait_agent for both |
-| Multi-Sprint | Other stages | One worker at a time |
-
-5. STOP after processing -- wait for next event
-
-### handleCheck
-
-Output current pipeline status from tasks.json. Do NOT advance pipeline.
-
-```
-Pipeline Status (<pipeline-mode>):
-  [DONE]  DESIGN-001  (architect)   -> design/design-001.md
-  [DONE]  DEV-001     (developer)   -> code/dev-log.md
-  [RUN]   VERIFY-001  (tester)      -> verifying...
-  [RUN]   REVIEW-001  (reviewer)    -> reviewing...
-  [WAIT]  DEV-fix     (developer)   -> blocked by REVIEW-001
-
-GC Rounds: <gc_round>/<max_gc_rounds>
-Sprint: <sprint_id>
-Session: <session-id>
-```
-
-### handleResume
-
-Resume pipeline after user pause or interruption.
-
-1. Audit tasks.json for inconsistencies:
-   - Tasks stuck in "in_progress" -> reset to "pending"
-   - Tasks with completed deps but still "pending" -> include in spawn list
-2. Proceed to handleSpawnNext
-
-### handleComplete
-
-Triggered when all pipeline tasks are completed.
-
-**Completion check by mode**:
-
-| Mode | Completion Condition |
-|------|---------------------|
-| patch | DEV-001 + VERIFY-001 completed |
-| sprint | DESIGN-001 + DEV-001 + VERIFY-001 + REVIEW-001 (+ any GC tasks) completed |
-| multi-sprint | All sprint tasks (+ any GC tasks) completed |
-
-1. Verify all tasks completed in tasks.json
-2. If any tasks not completed, return to handleSpawnNext
-3. **Multi-sprint check**: If multi-sprint AND more sprints planned:
-   - Record sprint metrics to .msg/meta.json sprint_history
-   - Evaluate downgrade eligibility (velocity >= expected, review avg >= 8)
-   - Pause for user confirmation before Sprint N+1
-4. If all completed, transition to coordinator Phase 5 (Report + Completion Action)
-
-## Phase 4: State Persistence
-
-After every handler execution:
-
-1. Update tasks.json with current state (gc_round, last event, active tasks)
-2. Update .msg/meta.json gc_round if changed
-3. Verify task list consistency
-4. STOP and wait for next event
+# Command: Monitor
+
+Synchronous pipeline coordination using spawn_agent + wait_agent.
+
+## Constants
+
+- WORKER_AGENT: team_worker
+- MAX_GC_ROUNDS: 3
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session state | tasks.json | Yes |
+| Trigger event | From Entry Router detection | Yes |
+| Meta state | <session>/.msg/meta.json | Yes |
+
+1. Load tasks.json for current state, pipeline_mode, gc_round, max_gc_rounds
+2. Read tasks from tasks.json to get current task statuses
+3. Identify trigger event type from Entry Router
+
+## Phase 3: Event Handlers
+
+### handleCallback
+
+Triggered when a worker completes (wait_agent returns).
+
+1. Determine role from completed task prefix:
+
+| Task Prefix | Role Detection |
+|-------------|---------------|
+| `DESIGN-*` | architect |
+| `DEV-*` | developer |
+| `VERIFY-*` | tester |
+| `REVIEW-*` | reviewer |
+
+2. Mark task as completed in tasks.json:
+
+```
+state.tasks[taskId].status = 'completed'
+```
+
+3. Record completion in session state and update metrics
+
+4. **Generator-Critic check** (when reviewer completes):
+   - If completed task is REVIEW-* AND pipeline is sprint or multi-sprint:
+   - Read review report for GC signal (critical_count, score)
+   - Read tasks.json for gc_round
+
+   | GC Signal | gc_round < max | Action |
+   |-----------|----------------|--------|
+   | review.critical_count > 0 OR review.score < 7 | Yes | Increment gc_round, create DEV-fix task in tasks.json with deps on this REVIEW, log `gc_loop_trigger` |
+   | review.critical_count > 0 OR review.score < 7 | No (>= max) | Force convergence, accept with warning, log to wisdom/issues.md |
+   | review.critical_count == 0 AND review.score >= 7 | - | Review passed, proceed to handleComplete check |
+
+   - Log team_msg with type "gc_loop_trigger" or "task_unblocked"
+
+5. Proceed to handleSpawnNext
+
+### handleSpawnNext
+
+Find and spawn the next ready tasks.
+
+1. Read tasks.json, find tasks where:
+   - Status is "pending"
+   - All deps tasks have status "completed"
+
+2. For each ready task, determine role from task prefix:
+
+| Task Prefix | Role | Inner Loop |
+|-------------|------|------------|
+| DESIGN-* | architect | false |
+| DEV-* | developer | true |
+| VERIFY-* | tester | false |
+| REVIEW-* | reviewer | false |
+
+3. Spawn team_worker:
+
+```javascript
+// 1) Update status in tasks.json
+state.tasks[taskId].status = 'in_progress'
+
+// 2) Spawn worker
+const agentId = spawn_agent({
+  agent_type: "team_worker",
+  task_name: taskId,  // e.g., "DEV-001" — enables named targeting
+  items: [
+    { type: "text", text: `## Role Assignment
+role: ${role}
+role_spec: ${skillRoot}/roles/${role}/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${taskDescription}
+inner_loop: ${innerLoop}` },
+
+    { type: "text", text: `Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.` }
+  ]
+})
+
+// 3) Track agent
+state.active_agents[taskId] = { agentId, role, started_at: now }
+
+// 4) Wait for completion — use task_name for stable targeting (v4)
+const waitResult = wait_agent({ targets: [taskId], timeout_ms: 900000 })
+if (waitResult.timed_out) {
+  state.tasks[taskId].status = 'timed_out'
+  close_agent({ target: taskId })
+  delete state.active_agents[taskId]
+  // Report timeout, STOP
+} else {
+  // 5) Collect results and update tasks.json
+  state.tasks[taskId].status = 'completed'
+  close_agent({ target: taskId })  // Use task_name, not agentId
+  delete state.active_agents[taskId]
+}
+```
+
+4. **Parallel spawn rules**:
+
+| Pipeline | Scenario | Spawn Behavior |
+|----------|----------|---------------|
+| Patch | DEV -> VERIFY | One worker at a time |
+| Sprint | VERIFY + REVIEW both unblocked | Spawn BOTH in parallel, wait_agent for both |
+| Sprint | Other stages | One worker at a time |
+| Multi-Sprint | VERIFY + DEV-fix both unblocked | Spawn BOTH in parallel, wait_agent for both |
+| Multi-Sprint | Other stages | One worker at a time |
+
+**Cross-Agent Supplementary Context** (v4):
+
+When spawning workers in a later pipeline phase, send upstream results as supplementary context to already-running workers:
+
+```
+// Example: Send design results to running developer
+send_message({
+  target: "<running-agent-task-name>",
+  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+})
+// Note: send_message queues info without interrupting the agent's current work
+```
+
+Use `send_message` (not `assign_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+
+5. STOP after processing -- wait for next event
+
+### handleCheck
+
+Output current pipeline status from tasks.json. Do NOT advance pipeline.
+
+```
+Pipeline Status (<pipeline-mode>):
+  [DONE]  DESIGN-001  (architect)   -> design/design-001.md
+  [DONE]  DEV-001     (developer)   -> code/dev-log.md
+  [RUN]   VERIFY-001  (tester)      -> verifying...
+  [RUN]   REVIEW-001  (reviewer)    -> reviewing...
+  [WAIT]  DEV-fix     (developer)   -> blocked by REVIEW-001
+
+GC Rounds: <gc_round>/<max_gc_rounds>
+Sprint: <sprint_id>
+Session: <session-id>
+```
+
+### handleResume
+
+**Agent Health Check** (v4):
+```
+// Verify actual running agents match session state
+const runningAgents = list_agents({})
+// For each active_agent in tasks.json:
+//   - If agent NOT in runningAgents -> agent crashed
+//   - Reset that task to pending, remove from active_agents
+// This prevents stale agent references from blocking the pipeline
+```
+
+Resume pipeline after user pause or interruption.
+
+1. Audit tasks.json for inconsistencies:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed deps but still "pending" -> include in spawn list
+2. Proceed to handleSpawnNext
+
+### handleComplete
+
+**Cleanup Verification** (v4):
+```
+// Verify all agents are properly closed
+const remaining = list_agents({})
+// If any team agents still running -> close_agent each
+// Ensures clean session shutdown
+```
+
+Triggered when all pipeline tasks are completed.
+
+**Completion check by mode**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| patch | DEV-001 + VERIFY-001 completed |
+| sprint | DESIGN-001 + DEV-001 + VERIFY-001 + REVIEW-001 (+ any GC tasks) completed |
+| multi-sprint | All sprint tasks (+ any GC tasks) completed |
+
+1. Verify all tasks completed in tasks.json
+2. If any tasks not completed, return to handleSpawnNext
+3. **Multi-sprint check**: If multi-sprint AND more sprints planned:
+   - Record sprint metrics to .msg/meta.json sprint_history
+   - Evaluate downgrade eligibility (velocity >= expected, review avg >= 8)
+   - Pause for user confirmation before Sprint N+1
+4. If all completed, transition to coordinator Phase 5 (Report + Completion Action)
+
+## Phase 4: State Persistence
+
+After every handler execution:
+
+1. Update tasks.json with current state (gc_round, last event, active tasks)
+2. Update .msg/meta.json gc_round if changed
+3. Verify task list consistency
+4. STOP and wait for next event