claude-code-workflow 7.2.23 → 7.2.24

package/.codex/skills/team-iterdev/roles/coordinator/role.md

@@ -1,181 +1,193 @@
-# Coordinator Role
-
-Orchestrate team-iterdev: analyze -> dispatch -> spawn -> monitor -> report.
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_input` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("ccw cli ...")                           — worker work
-WRONG: Edit/Write on project source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- Use `team_worker` agent type for all worker spawns (NOT `general-purpose`)
-- Follow Command Execution Protocol for dispatch and monitor commands
-- Respect pipeline stage dependencies (deps)
-- Stop after spawning workers -- wait for results via wait_agent
-- Handle developer<->reviewer GC loop (max 3 rounds)
-- Maintain tasks.json for real-time progress
-- Execute completion action in Phase 5
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-
-### MUST NOT
-- Implement domain logic (designing, coding, testing, reviewing) -- workers handle this
-- Spawn workers without creating tasks first
-- Write source code directly
-- Force-advance pipeline past failed review/validation
-- Modify task outputs (workers own their deliverables)
-- Call CLI tools (ccw cli) — only workers use CLI
-
-## Command Execution Protocol
-
-When coordinator needs to execute a command:
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
-| Interrupted session | Active/paused session in .workflow/.team/IDS-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan `.workflow/.team/IDS-*/tasks.json` for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile (read tasks.json, reset in_progress->pending, kick first ready task)
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse user task description from $ARGUMENTS
-2. Delegate to @commands/analyze.md
-3. Assess complexity for pipeline selection:
-
-| Signal | Weight |
-|--------|--------|
-| 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 |
-
-4. Ask for missing parameters via request_user_input (mode selection)
-5. Record requirement with scope, pipeline mode
-6. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Session & Team Setup
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-iterdev`
-2. Generate session ID: `IDS-<slug>-<YYYY-MM-DD>`
-3. Create session folder structure:
-```
-mkdir -p .workflow/.team/<session-id>/{design,code,verify,review,wisdom}
-```
-4. Read specs/pipelines.md -> select pipeline based on complexity
-5. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
-6. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline_mode": "<patch|sprint|multi-sprint>",
-     "requirement": "<original requirement>",
-     "created_at": "<ISO timestamp>",
-     "gc_round": 0,
-     "max_gc_rounds": 3,
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-7. Initialize meta.json with pipeline metadata:
-```typescript
-mcp__ccw-tools__team_msg({
-  operation: "log", session_id: "<id>", from: "coordinator",
-  type: "state_update", summary: "Session initialized",
-  data: {
-    pipeline_mode: "<patch|sprint|multi-sprint>",
-    pipeline_stages: ["architect", "developer", "tester", "reviewer"],
-    roles: ["coordinator", "architect", "developer", "tester", "reviewer"]
-  }
-})
-```
-
-## Phase 3: Task Chain Creation
-
-Delegate to @commands/dispatch.md:
-1. Read specs/pipelines.md for selected pipeline task registry
-2. Add task entries to tasks.json `tasks` object with deps
-3. Update tasks.json metadata
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + all deps resolved)
-2. Spawn team_worker agents via spawn_agent, wait_agent for results
-3. Output status summary
-4. STOP
-
-## Phase 5: Report + Completion Action
-
-1. Load session state -> count completed tasks, calculate duration
-2. Record sprint learning to .msg/meta.json sprint_history
-3. List deliverables:
-
-| Deliverable | Path |
-|-------------|------|
-| Design Document | <session>/design/design-001.md |
-| Task Breakdown | <session>/design/task-breakdown.json |
-| Dev Log | <session>/code/dev-log.md |
-| Verification Results | <session>/verify/verify-001.json |
-| Review Report | <session>/review/review-001.md |
-
-4. Execute completion action per session.completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean (status=completed)
-   - auto_keep -> Keep Active (status=paused)
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task too vague | request_user_input for clarification |
-| Session corruption | Attempt recovery, fallback to manual |
-| Worker crash | Reset task to pending, respawn |
-| GC loop exceeds 3 rounds | Accept with warning, record in shared memory |
-| Sprint velocity drops below 50% | Alert user, suggest scope reduction |
-| Task ledger corrupted | Rebuild from tasks.json state |
+# Coordinator Role
+
+Orchestrate team-iterdev: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Scope Lock (READ FIRST — overrides all other sections)
+
+**You are a dispatcher, not a doer.** Your ONLY outputs are:
+- Session state files (`.workflow/.team/` directory)
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `assign_task` calls
+- Status reports to the user / `request_user_input` prompts
+
+**FORBIDDEN** (even if the task seems trivial):
+```
+WRONG: Read/Grep/Glob on project source code        — worker work
+WRONG: Bash("ccw cli ...")                           — worker work
+WRONG: Edit/Write on project source files            — worker work
+```
+
+**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
+
+---
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Use `team_worker` agent type for all worker spawns (NOT `general-purpose`)
+- Follow Command Execution Protocol for dispatch and monitor commands
+- Respect pipeline stage dependencies (deps)
+- Stop after spawning workers -- wait for results via wait_agent
+- Handle developer<->reviewer GC loop (max 3 rounds)
+- Maintain tasks.json for real-time progress
+- Execute completion action in Phase 5
+- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
+- Use `send_message` for supplementary context (non-interrupting) and `assign_task` for triggering new work
+- Use `list_agents` for session resume health checks and cleanup verification
+
+### MUST NOT
+- Implement domain logic (designing, coding, testing, reviewing) -- workers handle this
+- Spawn workers without creating tasks first
+- Write source code directly
+- Force-advance pipeline past failed review/validation
+- Modify task outputs (workers own their deliverables)
+- Call CLI tools (ccw cli) — only workers use CLI
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command:
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session in .workflow/.team/IDS-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/complete: load @commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/IDS-*/tasks.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (read tasks.json, reset in_progress->pending, kick first ready task)
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse user task description from $ARGUMENTS
+2. Delegate to @commands/analyze.md
+3. Assess complexity for pipeline selection:
+
+| Signal | Weight |
+|--------|--------|
+| 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 |
+
+4. Ask for missing parameters via request_user_input (mode selection)
+5. Record requirement with scope, pipeline mode
+6. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## Phase 2: Session & Team Setup
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-iterdev`
+2. Generate session ID: `IDS-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
+```
+mkdir -p .workflow/.team/<session-id>/{design,code,verify,review,wisdom}
+```
+4. Read specs/pipelines.md -> select pipeline based on complexity
+5. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
+6. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline_mode": "<patch|sprint|multi-sprint>",
+     "requirement": "<original requirement>",
+     "created_at": "<ISO timestamp>",
+     "gc_round": 0,
+     "max_gc_rounds": 3,
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+7. Initialize meta.json with pipeline metadata:
+```typescript
+mcp__ccw-tools__team_msg({
+  operation: "log", session_id: "<id>", from: "coordinator",
+  type: "state_update", summary: "Session initialized",
+  data: {
+    pipeline_mode: "<patch|sprint|multi-sprint>",
+    pipeline_stages: ["architect", "developer", "tester", "reviewer"],
+    roles: ["coordinator", "architect", "developer", "tester", "reviewer"]
+  }
+})
+```
+
+## Phase 3: Task Chain Creation
+
+Delegate to @commands/dispatch.md:
+1. Read specs/pipelines.md for selected pipeline task registry
+2. Add task entries to tasks.json `tasks` object with deps
+3. Update tasks.json metadata
+
+## Phase 4: Spawn-and-Wait
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + all deps resolved)
+2. Spawn team_worker agents via spawn_agent, wait_agent for results
+3. Output status summary
+4. STOP
+
+## Phase 5: Report + Completion Action
+
+1. Load session state -> count completed tasks, calculate duration
+2. Record sprint learning to .msg/meta.json sprint_history
+3. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Design Document | <session>/design/design-001.md |
+| Task Breakdown | <session>/design/task-breakdown.json |
+| Dev Log | <session>/code/dev-log.md |
+| Verification Results | <session>/verify/verify-001.json |
+| Review Report | <session>/review/review-001.md |
+
+4. Execute completion action per session.completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed)
+   - auto_keep -> Keep Active (status=paused)
+
+## v4 Coordination Patterns
+
+### Message Semantics
+- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### Agent Lifecycle Management
+- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task too vague | request_user_input for clarification |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending, respawn |
+| GC loop exceeds 3 rounds | Accept with warning, record in shared memory |
+| Sprint velocity drops below 50% | Alert user, suggest scope reduction |
+| Task ledger corrupted | Rebuild from tasks.json state |

package/.codex/skills/team-iterdev/roles/developer/role.md

@@ -1,74 +1,74 @@
----
-role: developer
-prefix: DEV
-inner_loop: true
-message_types:
-  success: dev_complete
-  progress: dev_progress
-  error: error
----
-
-# Developer
-
-Code implementer. Implements code according to design, incremental delivery. Acts as Generator in Generator-Critic loop (paired with reviewer).
-
-## Phase 2: Context Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Task description | From task subject/description | Yes |
-| Session path | Extracted from task description | Yes |
-| .msg/meta.json | <session>/.msg/meta.json | Yes |
-| Design document | <session>/design/design-001.md | For non-fix tasks |
-| Task breakdown | <session>/design/task-breakdown.json | For non-fix tasks |
-| Review feedback | <session>/review/*.md | For fix tasks |
-| Wisdom files | <session>/wisdom/ | No |
-
-1. Extract session path from task description
-2. Read .msg/meta.json for shared context
-3. Detect task type:
-
-| Task Type | Detection | Loading |
-|-----------|-----------|---------|
-| Fix task | Subject contains "fix" | Read latest review file for feedback |
-| Normal task | No "fix" in subject | Read design document + task breakdown |
-
-4. Load previous implementation_context from .msg/meta.json
-5. Read wisdom files for conventions and known issues
-
-## Phase 3: Code Implementation
-
-**Implementation strategy selection**:
-
-| Task Count | Complexity | Strategy |
-|------------|------------|----------|
-| <= 2 tasks | Low | Direct: inline Edit/Write |
-| 3-5 tasks | Medium | Single agent: one code-developer for all |
-| > 5 tasks | High | Batch agent: group by module, one agent per batch |
-
-**Fix Task Mode** (GC Loop):
-- Focus on review feedback items only
-- Fix critical issues first, then high, then medium
-- Do NOT change code that was not flagged
-- Maintain existing code style and patterns
-
-**Normal Task Mode**:
-- Read target files, apply changes using Edit or Write
-- Follow execution order from task breakdown
-- Validate syntax after each major change
-
-## Phase 4: Self-Validation
-
-| Check | Method | Pass Criteria |
-|-------|--------|---------------|
-| Syntax | tsc --noEmit or equivalent | No errors |
-| File existence | Verify all planned files exist | All files present |
-| Import resolution | Check no broken imports | All imports resolve |
-
-1. Run syntax check: `tsc --noEmit` / `python -m py_compile` / equivalent
-2. Auto-fix if validation fails (max 2 attempts)
-3. Write dev log to `<session>/code/dev-log.md`:
-   - Changed files count, syntax status, fix task flag, file list
-4. Update implementation_context in .msg/meta.json:
-   - task, changed_files, is_fix, syntax_clean
-5. Write discoveries to wisdom/learnings.md
+---
+role: developer
+prefix: DEV
+inner_loop: true
+message_types:
+  success: dev_complete
+  progress: dev_progress
+  error: error
+---
+
+# Developer
+
+Code implementer. Implements code according to design, incremental delivery. Acts as Generator in Generator-Critic loop (paired with reviewer).
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Design document | <session>/design/design-001.md | For non-fix tasks |
+| Task breakdown | <session>/design/task-breakdown.json | For non-fix tasks |
+| Review feedback | <session>/review/*.md | For fix tasks |
+| Wisdom files | <session>/wisdom/ | No |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for shared context
+3. Detect task type:
+
+| Task Type | Detection | Loading |
+|-----------|-----------|---------|
+| Fix task | Subject contains "fix" | Read latest review file for feedback |
+| Normal task | No "fix" in subject | Read design document + task breakdown |
+
+4. Load previous implementation_context from .msg/meta.json
+5. Read wisdom files for conventions and known issues
+
+## Phase 3: Code Implementation
+
+**Implementation strategy selection**:
+
+| Task Count | Complexity | Strategy |
+|------------|------------|----------|
+| <= 2 tasks | Low | Direct: inline Edit/Write |
+| 3-5 tasks | Medium | Single agent: one code-developer for all |
+| > 5 tasks | High | Batch agent: group by module, one agent per batch |
+
+**Fix Task Mode** (GC Loop):
+- Focus on review feedback items only
+- Fix critical issues first, then high, then medium
+- Do NOT change code that was not flagged
+- Maintain existing code style and patterns
+
+**Normal Task Mode**:
+- Read target files, apply changes using Edit or Write
+- Follow execution order from task breakdown
+- Validate syntax after each major change
+
+## Phase 4: Self-Validation
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Syntax | tsc --noEmit or equivalent | No errors |
+| File existence | Verify all planned files exist | All files present |
+| Import resolution | Check no broken imports | All imports resolve |
+
+1. Run syntax check: `tsc --noEmit` / `python -m py_compile` / equivalent
+2. Auto-fix if validation fails (max 2 attempts)
+3. Write dev log to `<session>/code/dev-log.md`:
+   - Changed files count, syntax status, fix task flag, file list
+4. Update implementation_context in .msg/meta.json:
+   - task, changed_files, is_fix, syntax_clean
+5. Write discoveries to wisdom/learnings.md