team-lifecycle-v4

# Team Lifecycle v4 Orchestrate multi-agent software development: specification -> planning -> implementation -> testing -> review. ## Architecture ``` Skill(skill="team-lifecycle-v4", args="task description") | SKILL.md (this file) = Router | +--------------+--------------+ | | no --role flag --role <name> | | Coordinator Worker roles/coordinator/role.md roles/<name>/role.md | +-- analyze -> dispatch -> spawn -> wait -> collect | +--------+---+--------+ v v v spawn_agent ... spawn_agent (team_worker) (team_supervisor) per-task resident agent lifecycle followup_task-driven | | +-- wait_agent --------+ | collect results ``` ## Role Registry | Role | Path | Prefix | Inner Loop | |------|------|--------|------------| | coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- | | analyst | [roles/analyst/role.md](roles/analyst/role.md) | RESEARCH-* | false | | writer | [roles/writer/role.md](roles/writer/role.md) | DRAFT-* | true | | planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | true | | executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | true | | tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | false | | reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-*, IMPROVE-* | false | | supervisor | [roles/supervisor/role.md](roles/supervisor/role.md) | CHECKPOINT-* | false | ## Role Router Parse `$ARGUMENTS`: - Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4 - No `--role` -> `roles/coordinator/role.md`, execute entry router ## Delegation Lock **Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.** Before calling ANY tool, apply this check: | Tool Call | Verdict | Reason | |-----------|---------|--------| | `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_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 | | `Read` on `roles/`, `commands/`, `specs/`, `templates/` | ALLOWED | Loading own instructions | | `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker | | `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker | | `Bash("ccw cli ...")` | BLOCKED | Only workers call CLI | | `Bash` running build/test/lint commands | BLOCKED | Delegate to worker | **If a tool call is BLOCKED**: STOP. Create a task, spawn a worker. **No exceptions for "simple" tasks.** Even a single-file read-and-report MUST go through spawn_agent. --- ## Shared Constants - **Session prefix**: `TLV4` - **Session path**: `.workflow/.team/TLV4-<date>-<slug>/` - **State file**: `<session>/tasks.json` - **Discovery files**: `<session>/discoveries/{task_id}.json` - **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications) ## Worker Spawn Template Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", task_name: "<task-id>", fork_turns: "none", message: `## Role Assignment role: <role> role_spec: <skill_root>/roles/<role>/role.md session: <session-folder> session_id: <session-id> requirement: <task-description> inner_loop: <true|false> Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions. Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report). ## Task Context task_id: <task-id> title: <task-title> description: <task-description> pipeline_phase: <pipeline-phase> ## Upstream Context <prev_context>` }) ``` ## Supervisor Spawn Template Supervisor is a **resident agent** (independent from team_worker). Spawned once during session init, woken via followup_task for each CHECKPOINT task. ### Spawn (Phase 2 -- once per session) ``` supervisorId = spawn_agent({ agent_type: "team_supervisor", task_name: "supervisor", fork_turns: "none", message: `## Role Assignment role: supervisor role_spec: <skill_root>/roles/supervisor/role.md session: <session-folder> session_id: <session-id> requirement: <task-description> Read role_spec file (<skill_root>/roles/supervisor/role.md) to load checkpoint definitions. Init: load baseline context, report ready, go idle. Wake cycle: orchestrator sends checkpoint requests via followup_task.` }) ``` ### Wake (per CHECKPOINT task) ``` followup_task({ target: "supervisor", message: `## Checkpoint Request task_id: <CHECKPOINT-NNN> scope: [<upstream-task-ids>] pipeline_progress: <done>/<total> tasks completed` }) wait_agent({ timeout_ms: 1800000 }) // 30 min — apply timeout cascade if timed_out ``` ### Shutdown (pipeline complete) ``` close_agent({ target: "supervisor" }) ``` ### Model Selection Guide | Role | model | reasoning_effort | Rationale | |------|-------|-------------------|-----------| | Analyst (RESEARCH-*) | (default) | medium | Read-heavy exploration, less reasoning needed | | Writer (DRAFT-*) | (default) | high | Spec writing requires precision and completeness | | Planner (PLAN-*) | (default) | high | Architecture decisions need full reasoning | | Executor (IMPL-*) | (default) | high | Code generation needs precision | | Tester (TEST-*) | (default) | high | Test generation requires deep code understanding | | Reviewer (REVIEW-*, QUALITY-*, IMPROVE-*) | (default) | high | Deep analysis for quality assessment | | Supervisor (CHECKPOINT-*) | (default) | medium | Gate checking, report aggregation | Override model/reasoning_effort in spawn_agent when cost optimization is needed: ``` spawn_agent({ agent_type: "team_worker", task_name: "<task-id>", fork_turns: "none", model: "<model-override>", reasoning_effort: "<effort-level>", message: "..." }) ``` ## Wave Execution Engine For each wave in the pipeline: 1. **Load state** -- Read `<session>/tasks.json`, filter tasks for current wave 2. **Skip failed deps** -- Mark tasks whose dependencies failed/skipped as `skipped` 3. **Build upstream context** -- For each task, gather findings from `context_from` tasks via tasks.json and `discoveries/{id}.json` 4. **Separate task types** -- Split into regular tasks and CHECKPOINT tasks 5. **Spawn regular tasks** -- For each regular task, call `spawn_agent({ agent_type: "team_worker", message: "..." })`, collect agent IDs 6. **Wait** -- `wait_agent({ timeout_ms: 1800000 })` — apply timeout cascade if timed_out 7. **Collect results** -- Read `discoveries/{task_id}.json` for each agent, update tasks.json status/findings/error, then `close_agent({ target })` each worker 8. **Execute checkpoints** -- For each CHECKPOINT task, `followup_task` to supervisor, `wait_agent`, read checkpoint report from `artifacts/`, parse verdict 9. **Handle block** -- If verdict is `block`, prompt user via `request_user_input` with options: Override / Revise upstream / Abort 10. **Persist** -- Write updated state to `<session>/tasks.json` ## User Commands | Command | Action | |---------|--------| | `check` / `status` | View execution status graph | | `resume` / `continue` | Advance to next step | | `revise <TASK-ID> [feedback]` | Revise specific task | | `feedback <text>` | Inject feedback for revision | | `recheck` | Re-run quality check | | `improve [dimension]` | Auto-improve weakest dimension | ## v4 Agent Coordination ### Message Semantics | Intent | API | Example | |--------|-----|---------| | Queue supplementary info (don't interrupt) | `send_message` | Send planning results to running implementers | | Wake resident supervisor for checkpoint | `followup_task` | Trigger CHECKPOINT-* evaluation on supervisor | | Supervisor reports back to coordinator | `send_message` | Supervisor sends checkpoint verdict as supplementary info | | Check running agents | `list_agents` | Verify agent + supervisor health during resume | **CRITICAL**: The supervisor is a **resident agent** woken via `followup_task`, NOT `send_message`. Regular workers complete and are closed; the supervisor persists across checkpoints. See "Supervisor Spawn Template" above. ### 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 // ALSO check supervisor: if supervisor missing but CHECKPOINT tasks pending -> respawn ``` ### Named Agent Targeting Workers are spawned with `task_name: "<task-id>"` enabling direct addressing: - `send_message({ target: "IMPL-001", message: "..." })` -- queue planning context to running implementer - `followup_task({ target: "supervisor", message: "..." })` -- wake supervisor for checkpoint - `close_agent({ target: "IMPL-001" })` -- cleanup regular worker by name - `close_agent({ target: "supervisor" })` -- shutdown supervisor at pipeline end ## Completion Action When pipeline completes, coordinator presents: ``` functions.request_user_input({ questions: [{ question: "Pipeline complete. What would you like to do?", header: "Completion", multiSelect: false, options: [ { label: "Archive & Clean (Recommended)", description: "Archive session, clean up resources" }, { label: "Keep Active", description: "Keep session for follow-up work" }, { label: "Export Results", description: "Export deliverables to target directory" } ] }] }) ``` ## Specs Reference - [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry - [specs/quality-gates.md](specs/quality-gates.md) -- Quality gate criteria and scoring - [specs/knowledge-transfer.md](specs/knowledge-transfer.md) -- Artifact and state transfer protocols ## Session Directory ``` .workflow/.team/TLV4-<date>-<slug>/ ├── tasks.json # Task state (JSON)