claude-code-workflow 7.2.23 → 7.2.25

package/.codex/skills/team-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-issue
 description: Unified team skill for issue resolution. Uses team-worker agent architecture with role directories for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team issue".
-allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*)
+allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), assign_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__team_msg(*)
 ---
 
 # Team Issue Resolution
@@ -54,7 +54,8 @@ Before calling ANY tool, apply this check:
 
 | Tool Call | Verdict | Reason |
 |-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_input` | ALLOWED | Orchestration |
+| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `assign_task` | ALLOWED | Orchestration |
+| `list_agents` | ALLOWED | Agent health check |
 | `request_user_input` | ALLOWED | User interaction |
 | `mcp__ccw-tools__team_msg` | ALLOWED | Message bus |
 | `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
@@ -85,6 +86,8 @@ Coordinator spawns workers using this template:
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -108,13 +111,15 @@ pipeline_phase: <pipeline-phase>` },
 })
 ```
 
-After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
 
 **Parallel spawn** (Batch mode, N explorer or M implementer instances):
 
 ```
 spawn_agent({
   agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
   items: [
     { type: "text", text: `## Role Assignment
 role: <role>
@@ -139,7 +144,30 @@ pipeline_phase: <pipeline-phase>` },
 })
 ```
 
-After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
+After spawning, use `wait_agent({ targets: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ target })` each worker.
+
+
+### Model Selection Guide
+
+| Role | model | reasoning_effort | Rationale |
+|------|-------|-------------------|-----------|
+| Explorer (EXPLORE-*) | (default) | medium | Context gathering, file reading, less reasoning |
+| Planner (SOLVE-*) | (default) | high | Solution design requires deep analysis |
+| Reviewer (AUDIT-*) | (default) | high | Code review and plan validation need full reasoning |
+| Integrator (MARSHAL-*) | (default) | medium | Queue ordering and dependency resolution |
+| Implementer (BUILD-*) | (default) | high | Code generation needs precision |
+
+Override model/reasoning_effort in spawn_agent when cost optimization is needed:
+```
+spawn_agent({
+  agent_type: "team_worker",
+  task_name: "<task-id>",
+  fork_context: false,
+  model: "<model-override>",
+  reasoning_effort: "<effort-level>",
+  items: [...]
+})
+```
 
 ## User Commands
 
@@ -176,6 +204,57 @@ After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect
 
 - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
 
+## v4 Agent Coordination
+
+### Message Semantics
+
+| Intent | API | Example |
+|--------|-----|---------|
+| Send exploration context to running planner | `send_message` | Queue EXPLORE-* findings to SOLVE-* worker |
+| Not used in this skill | `assign_task` | No resident agents -- all workers are one-shot |
+| Check running agents | `list_agents` | Verify parallel explorer/implementer health |
+
+### Pipeline Pattern
+
+Pipeline with context passing: explore -> plan -> review (optional) -> marshal -> implement. In **Batch mode**, N explorers and M implementers run in parallel:
+
+```
+// Batch mode: spawn N explorers in parallel (max 5)
+const explorerNames = ["EXPLORE-001", "EXPLORE-002", ..., "EXPLORE-00N"]
+for (const name of explorerNames) {
+  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
+}
+wait_agent({ targets: explorerNames, timeout_ms: 900000 })
+
+// After MARSHAL completes: spawn M implementers in parallel (max 3)
+const buildNames = ["BUILD-001", "BUILD-002", ..., "BUILD-00M"]
+for (const name of buildNames) {
+  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
+}
+wait_agent({ targets: buildNames, timeout_ms: 900000 })
+```
+
+### Review-Fix Cycle
+
+Reviewer (AUDIT-*) may reject plans, triggering fix cycles (max 2). Dynamic SOLVE-fix and AUDIT re-review tasks are created in tasks.json.
+
+### Agent Health Check
+
+Use `list_agents({})` in handleResume and handleComplete:
+
+```
+// Reconcile session state with actual running agents
+const running = list_agents({})
+// Compare with tasks.json active_agents
+// Reset orphaned tasks (in_progress but agent gone) to pending
+```
+
+### Named Agent Targeting
+
+Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
+- `send_message({ target: "SOLVE-001", items: [...] })` -- queue exploration context to running planner
+- `close_agent({ target: "BUILD-001" })` -- cleanup by name after completion
+
 ## Error Handling
 
 | Scenario | Resolution |

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

@@ -1,64 +1,64 @@
-# Analyze Task
-
-Parse user issue description -> detect required capabilities -> assess complexity -> select pipeline mode.
-
-**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
-
-## Signal Detection
-
-| Keywords | Capability | Prefix |
-|----------|------------|--------|
-| explore, analyze, context, impact, understand | explorer | EXPLORE |
-| plan, solve, design, solution, approach | planner | SOLVE |
-| review, audit, validate, feasibility | reviewer | AUDIT |
-| marshal, integrate, queue, conflict, order | integrator | MARSHAL |
-| build, implement, execute, code, develop | implementer | BUILD |
-
-## Dependency Graph
-
-Natural ordering tiers:
-- Tier 0: explorer (context analysis -- no dependencies)
-- Tier 1: planner (requires explorer output)
-- Tier 2: reviewer (requires planner output, full/batch modes only)
-- Tier 3: integrator (requires reviewer or planner output)
-- Tier 4: implementer (requires integrator output)
-
-## Complexity Scoring
-
-| Factor | Points |
-|--------|--------|
-| Issue count > 2 | +3 |
-| Issue count > 4 | +2 more |
-| Any high-priority issue (priority >= 4) | +2 |
-| Multiple issue types / cross-cutting | +2 |
-| Simple / single issue | -2 |
-
-Results:
-- 0-2: Low -> quick (4 tasks: EXPLORE -> SOLVE -> MARSHAL -> BUILD)
-- 3-4: Medium -> full (5 tasks: EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD)
-- 5+: High -> batch (N+N+1+1+M tasks, parallel exploration and implementation)
-
-## Pipeline Selection
-
-| Complexity | Pipeline | Tasks |
-|------------|----------|-------|
-| Low | quick | EXPLORE -> SOLVE -> MARSHAL -> BUILD |
-| Medium | full | EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD |
-| High | batch | EXPLORE-001..N (parallel) -> SOLVE-001..N -> AUDIT -> MARSHAL -> BUILD-001..M (parallel) |
-
-## Output
-
-Write <session>/task-analysis.json:
-```json
-{
-  "task_description": "<original>",
-  "pipeline_type": "<quick|full|batch>",
-  "issue_ids": ["<id1>", "<id2>"],
-  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
-  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
-  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
-  "complexity": { "score": 0, "level": "Low|Medium|High" },
-  "parallel_explorers": 1,
-  "parallel_builders": 1
-}
-```
+# Analyze Task
+
+Parse user issue description -> detect required capabilities -> assess complexity -> select pipeline mode.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Prefix |
+|----------|------------|--------|
+| explore, analyze, context, impact, understand | explorer | EXPLORE |
+| plan, solve, design, solution, approach | planner | SOLVE |
+| review, audit, validate, feasibility | reviewer | AUDIT |
+| marshal, integrate, queue, conflict, order | integrator | MARSHAL |
+| build, implement, execute, code, develop | implementer | BUILD |
+
+## Dependency Graph
+
+Natural ordering tiers:
+- Tier 0: explorer (context analysis -- no dependencies)
+- Tier 1: planner (requires explorer output)
+- Tier 2: reviewer (requires planner output, full/batch modes only)
+- Tier 3: integrator (requires reviewer or planner output)
+- Tier 4: implementer (requires integrator output)
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Issue count > 2 | +3 |
+| Issue count > 4 | +2 more |
+| Any high-priority issue (priority >= 4) | +2 |
+| Multiple issue types / cross-cutting | +2 |
+| Simple / single issue | -2 |
+
+Results:
+- 0-2: Low -> quick (4 tasks: EXPLORE -> SOLVE -> MARSHAL -> BUILD)
+- 3-4: Medium -> full (5 tasks: EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD)
+- 5+: High -> batch (N+N+1+1+M tasks, parallel exploration and implementation)
+
+## Pipeline Selection
+
+| Complexity | Pipeline | Tasks |
+|------------|----------|-------|
+| Low | quick | EXPLORE -> SOLVE -> MARSHAL -> BUILD |
+| Medium | full | EXPLORE -> SOLVE -> AUDIT -> MARSHAL -> BUILD |
+| High | batch | EXPLORE-001..N (parallel) -> SOLVE-001..N -> AUDIT -> MARSHAL -> BUILD-001..M (parallel) |
+
+## Output
+
+Write <session>/task-analysis.json:
+```json
+{
+  "task_description": "<original>",
+  "pipeline_type": "<quick|full|batch>",
+  "issue_ids": ["<id1>", "<id2>"],
+  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
+  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
+  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
+  "complexity": { "score": 0, "level": "Low|Medium|High" },
+  "parallel_explorers": 1,
+  "parallel_builders": 1
+}
+```