claude-code-workflow 7.2.23 → 7.2.25

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

@@ -1,159 +1,171 @@
-# Coordinator Role
-
-Orchestrate team-planex: 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: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor results -> Spawn executors -> Report
-
-## Boundaries
-
-### MUST
-- Parse user input (Issue IDs / --text / --plan) and determine execution method
-- Create session and initialize tasks.json
-- Dispatch tasks via `commands/dispatch.md`
-- Monitor progress via `commands/monitor.md` with Spawn-and-Stop pattern
-- Maintain session state (.msg/meta.json)
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-
-### MUST NOT
-- Execute planning or implementation work directly (delegate to workers)
-- Modify solution artifacts or code (workers own their deliverables)
-- Call implementation CLI tools (code-developer, etc.) directly
-- Skip dependency validation when creating task chains
-
-## 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 |
-|-----------|-----------|---------|
-| Worker result | Result from wait_agent contains [planner] or [executor] tag | -> handleCallback (monitor.md) |
-| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Add tasks | Args contain "add" | -> handleAdd |
-| Interrupted session | Active/paused session exists in `.workflow/.team/PEX-*` | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For callback/check/resume: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
-
-### handleAdd
-
-1. Parse new input (Issue IDs / `--text` / `--plan`)
-2. Get current max PLAN-* sequence from tasks.json
-3. Add new PLAN-00N task entry to tasks.json with role: "planner"
-4. If planner already sent `all_planned` (check team_msg) -> signal planner to re-enter loop
-5. STOP
-
-## Phase 0: Session Resume Check
-
-1. Scan `.workflow/.team/PEX-*/.msg/meta.json` for sessions with status "active" or "paused"
-2. No sessions -> Phase 1
-3. Single session -> resume (Session Reconciliation)
-4. Multiple sessions -> request_user_input for selection
-
-**Session Reconciliation**:
-1. Read tasks.json -> reconcile session state vs task status
-2. Reset in_progress tasks -> pending (they were interrupted)
-3. Rebuild team if needed (create session + spawn needed workers)
-4. Kick first executable task -> Phase 4
-
-## Phase 1: Input Parsing + Execution Method
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Delegate to @commands/analyze.md -> produces task-analysis.json
-2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
-3. Determine execution method (see specs/pipelines.md Selection Decision Table):
-   - Explicit `--exec` flag -> use specified method
-   - `-y` / `--yes` flag -> Auto mode
-   - No flags -> request_user_input for method choice
-4. Store requirements: input_type, raw_input, execution_method
-5. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Create Team + Initialize Session
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash("pwd")`
-   - `skill_root` = `<project_root>/.codex/skills/team-planex`
-2. Generate session ID: `PEX-<slug>-<date>`
-3. Create session folder: `.workflow/.team/<session-id>/`
-4. Create subdirectories: `artifacts/solutions/`, `wisdom/`
-5. Create session folder + initialize `tasks.json` (empty array)
-6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
-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: "plan-execute",
-    pipeline_stages: ["planner", "executor"],
-    roles: ["coordinator", "planner", "executor"],
-    team_name: "planex",
-    input_type: "<issues|text|plan>",
-    execution_method: "<codex|gemini>"
-  }
-})
-```
-
-## Phase 3: Create Task Chain
-
-Delegate to `@commands/dispatch.md`:
-1. Read `roles/coordinator/commands/dispatch.md`
-2. Execute its workflow to create PLAN-001 task in tasks.json
-3. PLAN-001 contains input info + execution method in description
-
-## Phase 4: Spawn-and-Stop
-
-1. Load `@commands/monitor.md`
-2. Execute `handleSpawnNext` to find ready tasks and spawn planner worker
-3. Output status summary
-4. STOP (idle, wait for worker result)
-
-**ONE_STEP_PER_INVOCATION**: true -- coordinator does one operation per wake-up, then STOPS.
-
-## Phase 5: Report + Completion Action
-
-1. Load session state -> count completed tasks, duration
-2. List deliverables with output paths
-3. Update session status -> "completed"
-4. Execute Completion Action per session.completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean (status=completed, clean up session)
-   - auto_keep -> Keep Active (status=paused)
-   - auto_yes -> Archive & Clean without prompting
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Session file not found | Error, suggest re-initialization |
-| Unknown worker callback | Log, scan for other completions |
-| Pipeline stall | Check missing tasks, report to user |
-| Worker crash | Reset task to pending, re-spawn on next beat |
-| All workers running on resume | Report status, suggest check later |
+# Coordinator Role
+
+Orchestrate team-planex: 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: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor results -> Spawn executors -> Report
+
+## Boundaries
+
+### MUST
+- Parse user input (Issue IDs / --text / --plan) and determine execution method
+- Create session and initialize tasks.json
+- Dispatch tasks via `commands/dispatch.md`
+- Monitor progress via `commands/monitor.md` with Spawn-and-Stop pattern
+- Maintain session state (.msg/meta.json)
+- **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
+- Execute planning or implementation work directly (delegate to workers)
+- Modify solution artifacts or code (workers own their deliverables)
+- Call implementation CLI tools (code-developer, etc.) directly
+- Skip dependency validation when creating task chains
+
+## 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 |
+|-----------|-----------|---------|
+| Worker result | Result from wait_agent contains [planner] or [executor] tag | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Add tasks | Args contain "add" | -> handleAdd |
+| Interrupted session | Active/paused session exists in `.workflow/.team/PEX-*` | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
+
+### handleAdd
+
+1. Parse new input (Issue IDs / `--text` / `--plan`)
+2. Get current max PLAN-* sequence from tasks.json
+3. Add new PLAN-00N task entry to tasks.json with role: "planner"
+4. If planner already sent `all_planned` (check team_msg) -> signal planner to re-enter loop
+5. STOP
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/PEX-*/.msg/meta.json` for sessions with status "active" or "paused"
+2. No sessions -> Phase 1
+3. Single session -> resume (Session Reconciliation)
+4. Multiple sessions -> request_user_input for selection
+
+**Session Reconciliation**:
+1. Read tasks.json -> reconcile session state vs task status
+2. Reset in_progress tasks -> pending (they were interrupted)
+3. Rebuild team if needed (create session + spawn needed workers)
+4. Kick first executable task -> Phase 4
+
+## Phase 1: Input Parsing + Execution Method
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Delegate to @commands/analyze.md -> produces task-analysis.json
+2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y)
+3. Determine execution method (see specs/pipelines.md Selection Decision Table):
+   - Explicit `--exec` flag -> use specified method
+   - `-y` / `--yes` flag -> Auto mode
+   - No flags -> request_user_input for method choice
+4. Store requirements: input_type, raw_input, execution_method
+5. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## Phase 2: Create Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash("pwd")`
+   - `skill_root` = `<project_root>/.codex/skills/team-planex`
+2. Generate session ID: `PEX-<slug>-<date>`
+3. Create session folder: `.workflow/.team/<session-id>/`
+4. Create subdirectories: `artifacts/solutions/`, `wisdom/`
+5. Create session folder + initialize `tasks.json` (empty array)
+6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md)
+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: "plan-execute",
+    pipeline_stages: ["planner", "executor"],
+    roles: ["coordinator", "planner", "executor"],
+    team_name: "planex",
+    input_type: "<issues|text|plan>",
+    execution_method: "<codex|gemini>"
+  }
+})
+```
+
+## Phase 3: Create Task Chain
+
+Delegate to `@commands/dispatch.md`:
+1. Read `roles/coordinator/commands/dispatch.md`
+2. Execute its workflow to create PLAN-001 task in tasks.json
+3. PLAN-001 contains input info + execution method in description
+
+## Phase 4: Spawn-and-Stop
+
+1. Load `@commands/monitor.md`
+2. Execute `handleSpawnNext` to find ready tasks and spawn planner worker
+3. Output status summary
+4. STOP (idle, wait for worker result)
+
+**ONE_STEP_PER_INVOCATION**: true -- coordinator does one operation per wake-up, then STOPS.
+
+## Phase 5: Report + Completion Action
+
+1. Load session state -> count completed tasks, duration
+2. List deliverables with output paths
+3. Update session status -> "completed"
+4. Execute Completion Action per session.completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, clean up session)
+   - auto_keep -> Keep Active (status=paused)
+   - auto_yes -> Archive & Clean without prompting
+
+## 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 |
+|-------|------------|
+| Session file not found | Error, suggest re-initialization |
+| Unknown worker callback | Log, scan for other completions |
+| Pipeline stall | Check missing tasks, report to user |
+| Worker crash | Reset task to pending, re-spawn on next beat |
+| All workers running on resume | Report status, suggest check later |

package/.codex/skills/team-planex/roles/executor/role.md

@@ -1,91 +1,91 @@
----
-role: executor
-prefix: EXEC
-inner_loop: true
-message_types:
-  success: impl_complete
-  error: impl_failed
----
-
-# Executor
-
-Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Codex/Gemini), verifies with tests, commits, and reports completion.
-
-## Phase 2: Task & Solution Loading
-
-| Input | Source | Required |
-|-------|--------|----------|
-| Issue ID | Task description `Issue ID:` field | Yes |
-| Solution file | Task description `Solution file:` field | Yes |
-| Session folder | Task description `Session:` field | Yes |
-| Execution method | Task description `Execution method:` field | Yes |
-| Wisdom | `<session>/wisdom/` | No |
-
-1. Extract issue ID, solution file path, session folder, execution method
-2. Load solution JSON from file (file-first)
-3. If file not found -> fallback: `ccw issue solution <issueId> --json`
-4. Load wisdom files for conventions and patterns
-5. Verify solution has required fields: title, tasks
-
-## Phase 3: Implementation
-
-### Backend Selection
-
-| Method | Backend | CLI Tool |
-|--------|---------|----------|
-| `codex` | `ccw cli --tool codex --mode write` | CLI |
-| `gemini` | `ccw cli --tool gemini --mode write` | CLI |
-
-### CLI Backend (Codex/Gemini)
-
-```bash
-ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
-TASK: <solution.tasks as bullet points>
-MODE: write
-CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
-EXPECTED: Working implementation with: code changes, test updates, no syntax errors
-CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
-Issue: <issueId>
-Title: <solution.title>
-Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature
-```
-
-Wait for CLI completion before proceeding to verification.
-
-## Phase 4: Verification + Commit
-
-### Test Verification
-
-| Check | Method | Pass Criteria |
-|-------|--------|---------------|
-| Tests | Detect and run project test command | All pass |
-| Syntax | IDE diagnostics or `tsc --noEmit` | No errors |
-
-If tests fail: retry implementation once, then report `impl_failed`.
-
-### Commit
-
-```bash
-git add -A
-git commit -m "feat(<issueId>): <solution.title>"
-```
-
-### Update Issue Status
-
-```bash
-ccw issue update <issueId> --status completed
-```
-
-### Report
-
-Write results to discoveries file for coordinator to read.
-
-## Boundaries
-
-| Allowed | Prohibited |
-|---------|-----------|
-| Load solution from file | Create or modify issues |
-| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts |
-| Run tests | Spawn additional agents (use CLI tools instead) |
-| git commit | Direct user interaction |
-| Update issue status | Create tasks for other roles |
+---
+role: executor
+prefix: EXEC
+inner_loop: true
+message_types:
+  success: impl_complete
+  error: impl_failed
+---
+
+# Executor
+
+Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Codex/Gemini), verifies with tests, commits, and reports completion.
+
+## Phase 2: Task & Solution Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Issue ID | Task description `Issue ID:` field | Yes |
+| Solution file | Task description `Solution file:` field | Yes |
+| Session folder | Task description `Session:` field | Yes |
+| Execution method | Task description `Execution method:` field | Yes |
+| Wisdom | `<session>/wisdom/` | No |
+
+1. Extract issue ID, solution file path, session folder, execution method
+2. Load solution JSON from file (file-first)
+3. If file not found -> fallback: `ccw issue solution <issueId> --json`
+4. Load wisdom files for conventions and patterns
+5. Verify solution has required fields: title, tasks
+
+## Phase 3: Implementation
+
+### Backend Selection
+
+| Method | Backend | CLI Tool |
+|--------|---------|----------|
+| `codex` | `ccw cli --tool codex --mode write` | CLI |
+| `gemini` | `ccw cli --tool gemini --mode write` | CLI |
+
+### CLI Backend (Codex/Gemini)
+
+```bash
+ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
+TASK: <solution.tasks as bullet points>
+MODE: write
+CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
+EXPECTED: Working implementation with: code changes, test updates, no syntax errors
+CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
+Issue: <issueId>
+Title: <solution.title>
+Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature
+```
+
+Wait for CLI completion before proceeding to verification.
+
+## Phase 4: Verification + Commit
+
+### Test Verification
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Tests | Detect and run project test command | All pass |
+| Syntax | IDE diagnostics or `tsc --noEmit` | No errors |
+
+If tests fail: retry implementation once, then report `impl_failed`.
+
+### Commit
+
+```bash
+git add -A
+git commit -m "feat(<issueId>): <solution.title>"
+```
+
+### Update Issue Status
+
+```bash
+ccw issue update <issueId> --status completed
+```
+
+### Report
+
+Write results to discoveries file for coordinator to read.
+
+## Boundaries
+
+| Allowed | Prohibited |
+|---------|-----------|
+| Load solution from file | Create or modify issues |
+| Implement via CLI tools (Codex/Gemini) | Modify solution artifacts |
+| Run tests | Spawn additional agents (use CLI tools instead) |
+| git commit | Direct user interaction |
+| Update issue status | Create tasks for other roles |