--- name: team-iterdev description: Unified team skill for iterative development team. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team iterdev". allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) --- # Team IterDev Iterative development team skill. Generator-Critic loops (developer<->reviewer, max 3 rounds), task ledger (task-ledger.json) for real-time progress, shared memory (cross-sprint learning), and dynamic pipeline selection for incremental delivery. All team members route via `--role=xxx`. ## Architecture ``` +-------------------------------------------------+ | Skill(skill="team-iterdev") | | args="task description" or args="--role=xxx" | +-------------------+-----------------------------+ | Role Router +---- --role present? ----+ | NO | YES v v Orchestration Mode Role Dispatch (auto -> coordinator) (route to role.md) | +----+----+----------+---------+---------+ v v v v v coordinator architect developer tester reviewer ``` ## Role Router ### Input Parsing Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto route to coordinator). ### Role Registry | Role | File | Task Prefix | Type | Compact | |------|------|-------------|------|---------| | coordinator | [roles/coordinator.md](roles/coordinator.md) | (none) | orchestrator | **MUST re-read after compression** | | architect | [roles/architect.md](roles/architect.md) | DESIGN-* | pipeline | MUST re-read after compression | | developer | [roles/developer.md](roles/developer.md) | DEV-* | pipeline | MUST re-read after compression | | tester | [roles/tester.md](roles/tester.md) | VERIFY-* | pipeline | MUST re-read after compression | | reviewer | [roles/reviewer.md](roles/reviewer.md) | REVIEW-* | pipeline | MUST re-read after compression | > **COMPACT PROTECTION**: Role files are execution documents, not reference material. When context compression occurs and role instructions are reduced to summaries, you **MUST immediately `Read` the corresponding role.md to reload before continuing execution**. Never execute any Phase based on summaries alone. ### Dispatch 1. Extract `--role` from arguments 2. If no `--role` -> route to coordinator (Orchestration Mode) 3. Look up role in registry -> Read the role file -> Execute its phases ### Orchestration Mode When invoked without `--role`, coordinator auto-starts. User just provides task description. **Invocation**: `Skill(skill="team-iterdev", args="task description")` **Lifecycle**: ``` User provides task description -> coordinator Phase 1-3: requirement clarification -> TeamCreate -> create task chain -> coordinator Phase 4: spawn first batch of workers (background) -> STOP -> Worker executes -> SendMessage callback -> coordinator advances next step -> Loop until pipeline complete -> Phase 5 report ``` **User Commands** (wake suspended coordinator): | Command | Action | |---------|--------| | `check` / `status` | Output execution status diagram, do not advance | | `resume` / `continue` | Check worker status, advance next step | --- ## Shared Infrastructure The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic. ### Worker Phase 1: Task Discovery (shared by all workers) Each worker executes the same task discovery flow on startup: 1. Call `TaskList()` to get all tasks 2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty 3. No tasks -> idle wait 4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress **Resume Artifact Check** (prevent duplicate output after recovery): - Check if this task's output artifact already exists - Artifact complete -> skip to Phase 5 report completion - Artifact incomplete or missing -> normal Phase 2-4 execution ### Worker Phase 5: Report (shared by all workers) Standard report flow after task completion: 1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message - Parameters: operation="log", team=, from=, to="coordinator", type=, summary="[] ", ref= - **CLI fallback**: When MCP unavailable -> `ccw team log --team --from --to coordinator --type --summary "[] ..." --json` 2. **SendMessage**: Send result to coordinator (content and summary both with `[]` prefix) 3. **TaskUpdate**: Mark task completed 4. **Loop**: Return to Phase 1 to check next task ### Role Isolation Rules | Allowed | Prohibited | |---------|------------| | Process tasks with own prefix | Process other roles' prefix tasks | | Read/write shared-memory.json (own fields) | Create tasks for other roles | | SendMessage to coordinator | Communicate directly with other workers | **Coordinator additional restrictions**: No direct code writing, no calling implementation-type subagents, no directly executing analysis/testing/review. ### Message Bus Call `mcp__ccw-tools__team_msg` with: operation="log", team=, from=, to="coordinator", type=, summary="[] ", ref="" **CLI Fallback**: `ccw team log --team "" --from "" --to "coordinator" --type "" --summary "" --json` | Role | Message Types | |------|---------------| | coordinator | `sprint_started`, `gc_loop_trigger`, `sprint_complete`, `task_unblocked`, `error`, `shutdown`, `conflict_detected`, `conflict_resolved`, `resource_locked`, `resource_unlocked`, `resource_contention`, `rollback_initiated`, `rollback_completed`, `rollback_failed`, `dependency_mismatch`, `dependency_update_needed`, `context_checkpoint_saved`, `context_restored`, `user_feedback_received`, `tech_debt_identified` | | architect | `design_ready`, `design_revision`, `error` | | developer | `dev_complete`, `dev_progress`, `error` | | tester | `verify_passed`, `verify_failed`, `fix_required`, `error` | | reviewer | `review_passed`, `review_revision`, `review_critical`, `error` | ### Team Configuration | Setting | Value | |---------|-------| | Team name | iterdev | | Session directory | `.workflow/.team/IDS-{slug}-{date}/` | | Shared memory file | shared-memory.json | | Task ledger file | task-ledger.json | --- ## Coordinator Protocol Summary The coordinator manages several operational protocols. Full implementations reside in [roles/coordinator.md](roles/coordinator.md). The tables below describe the behavioral contracts for each protocol. > **NOTE**: These are behavioral specifications only. Full procedural logic, data format details, and edge case handling are defined in the coordinator role file. ### Resource Lock Protocol Concurrency control for shared resources. Prevents multiple workers from modifying the same files simultaneously. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Acquire lock | Worker requests exclusive access to a resource | Check `resource_locks` in shared-memory.json. If unlocked, record lock with task ID, timestamp, and holder role. Log `resource_locked` message. Return success. | | Deny lock | Resource already locked by another task | Return failure with current holder's task ID. Log `resource_contention` message. Worker must wait or request alternative resource. | | Release lock | Worker completes task or explicitly releases | Remove lock entry from `resource_locks`. Log `resource_unlocked` message to all workers. | | Force release | Lock held beyond timeout (5 min) | Force-remove lock entry. Notify original holder and coordinator. Log warning. | | Deadlock detection | Multiple tasks waiting on each other's locks | Abort youngest task, release its locks, notify coordinator. | ### Conflict Detection Protocol Detects and resolves file-level conflicts between concurrent development tasks. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Detect conflict | DEV task completes with changed files | Compare changed files against other in_progress/completed tasks in ledger. If overlap found, update task's `conflict_info` to status "detected" with conflicting file list. Log `conflict_detected` message. | | Resolve conflict | Conflict detected requiring resolution | Set `conflict_info.resolution_strategy` (manual/auto_merge/abort). Create `{taskId}-fix-conflict` task assigned to developer. Log `conflict_resolved` message. | | Skip (no conflict) | No file overlap with other tasks | No action needed, task proceeds normally. | ### Rollback Point Protocol Manages state snapshots for safe recovery when tasks fail or produce undesirable results. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Create rollback point | Task successfully completes a phase | Generate snapshot ID, record rollback procedure (default: `git revert HEAD`) and state reference in task's `rollback_info` in the ledger. | | Execute rollback | Task failure or user-requested revert | Log `rollback_initiated`. Execute stored rollback procedure. On success, log `rollback_completed`. On failure, log `rollback_failed` with error details. | | Validate snapshot | Before executing rollback | Verify snapshot ID exists and rollback procedure is valid. Abort with error if invalid. | ### Dependency Validation Protocol Validates external dependencies (npm, pip, etc.) before task execution begins. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Validate dependencies | Task startup with declared dependencies | For each dependency: check installed version against expected version range. Record results in task's `external_dependencies` array in ledger (status: ok/mismatch/missing). | | Report mismatch | Any dependency has status mismatch or missing | Log `dependency_mismatch` message listing affected packages. Block task until resolved or user overrides. | | Update notification | External dependency has important update available | Log `dependency_update_needed` message. Add to sprint backlog for consideration. | ### Checkpoint Management Protocol Saves and restores task execution state for interruption recovery. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Save checkpoint | Task reaches significant progress milestone | Store checkpoint in `task_checkpoints` in shared-memory.json with timestamp and state data pointer. Retain last 5 checkpoints per task. Log `context_checkpoint_saved`. | | Restore checkpoint | Task resumes after interruption | Load latest checkpoint for task. Read state data from pointer path. Log `context_restored`. Return state data to worker. | | Checkpoint not found | Resume requested but no checkpoints exist | Return failure with reason. Worker starts fresh from Phase 1. | ### User Feedback Protocol Collects, categorizes, and tracks user feedback throughout the sprint. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Receive feedback | User provides feedback (via AskUserQuestion or direct) | Create feedback item with ID (FB-xxx), severity, category, timestamp. Store in `user_feedback_items` in shared-memory.json (max 50 items). Log `user_feedback_received`. | | Link to task | Feedback relates to specific task | Update feedback item's `source_task_id` and set status to "reviewed". | | Triage feedback | New feedback with high/critical severity | Prioritize in next sprint planning. Create task if actionable. | ### Tech Debt Management Protocol Identifies, tracks, and prioritizes technical debt discovered during development. | Action | Trigger Condition | Coordinator Behavior | |--------|-------------------|----------------------| | Identify debt | Worker reports tech debt during development or review | Create debt item with ID (TD-xxx), category (code/design/test/documentation), severity, estimated effort. Store in `tech_debt_items` in shared-memory.json. Log `tech_debt_identified`. | | Generate report | Sprint retrospective or user request | Aggregate debt items by severity and category. Report totals, open items, and in-progress items. | | Prioritize debt | Sprint planning phase | Rank debt items by severity and priority. Recommend items for current sprint based on estimated effort and available capacity. | | Resolve debt | Developer completes debt resolution task | Update debt item status to "resolved". Record resolution in sprint history. | --- ## Three-Pipeline Architecture ``` Patch (simple fix): DEV-001 -> VERIFY-001 Sprint (standard feature): DESIGN-001 -> DEV-001 -> [VERIFY-001 + REVIEW-001](parallel) Multi-Sprint (large feature): Sprint 1: DESIGN-001 -> DEV-001 -> DEV-002(incremental) -> VERIFY-001 -> DEV-fix -> REVIEW-001 Sprint 2: DESIGN-002(refined) -> DEV-003 -> VERIFY-002 -> REVIEW-002 ... ``` ### Generator-Critic Loop developer <-> reviewer loop, max 3 rounds: ``` DEV -> REVIEW -> (if review.critical_count > 0 || review.score < 7) -> DEV-fix -> REVIEW-2 -> (if still issues) -> DEV-fix-2 -> REVIEW-3 -> (max 3 rounds, then accept with warning) ``` ### Multi-Sprint Dynamic Downgrade If Sprint N metrics are strong (velocity >= expected, review avg >= 8), coordinator may downgrade Sprint N+1 from multi-sprint to sprint pipeline for efficiency. ### Cadence Control **Beat Model**: Event-driven. Each beat = coordinator wakes -> processes -> spawns -> STOP. ``` Beat Cycle (single beat) =========================================================== Event Coordinator Workers ----------------------------------------------------------- callback/resume --> +- handleCallback -+ | mark completed | | check pipeline | +- handleSpawnNext -+ | find ready tasks | | spawn workers ---+--> [Worker A] Phase 1-5 | (parallel OK) --+--> [Worker B] Phase 1-5 +- STOP (idle) -----+ | | callback <----------------------------------------+ (next beat) SendMessage + TaskUpdate(completed) =========================================================== ``` **Pipeline Beat Views**: ``` Patch (2 beats, strict serial) ---------------------------------------------------------- Beat 1 2 | | DEV -> VERIFY ^ ^ pipeline pipeline start done Sprint (3 beats, with parallel window) ---------------------------------------------------------- Beat 1 2 3 | | +----+----+ DESIGN -> DEV --> VERIFY // REVIEW <- parallel window +----+----+ pipeline done Multi-Sprint (N beats, iterative) ---------------------------------------------------------- Sprint 1: Beat 1 2 3 4 5 6 | | | | +----+----+ | DESIGN -> DEV -> DEV -> VERIFY // DEV-fix -> REVIEW (incr) (GC loop) Sprint 2: (refined pipeline based on Sprint 1 metrics) Beat 7 8 9 10 | | | | DESIGN -> DEV -> VERIFY -> REVIEW ``` **Checkpoints**: | Trigger Condition | Location | Behavior | |-------------------|----------|----------| | GC loop exceeds max rounds | After REVIEW-3 | Stop iteration, accept with warning, record in shared memory | | Sprint transition | End of Sprint N | Pause, retrospective, user confirms `resume` for Sprint N+1 | | Pipeline stall | No ready + no running tasks | Check missing tasks, report blockedBy chain to user | **Stall Detection** (coordinator `handleCheck`): | Check | Condition | Resolution | |-------|-----------|------------| | Worker unresponsive | in_progress task with no callback | Report waiting task list, suggest user `resume` | | Pipeline deadlock | No ready + no running + has pending | Inspect blockedBy dependency chain, report blockage | | GC loop exceeded | DEV/REVIEW iteration > max_rounds (3) | Terminate loop, output latest review report | --- ## Task Metadata Registry | Task ID | Role | Pipeline | Dependencies | Description | |---------|------|----------|-------------|-------------| | DESIGN-001 | architect | sprint/multi | (none) | Technical design and task breakdown | | DEV-001 | developer | all | DESIGN-001 (sprint/multi) or (none for patch) | Code implementation | | DEV-002 | developer | multi | DEV-001 | Incremental implementation | | DEV-fix | developer | sprint/multi | REVIEW-* (GC loop trigger) | Fix issues from review | | VERIFY-001 | tester | all | DEV-001 (or last DEV) | Test execution and fix cycles | | REVIEW-001 | reviewer | sprint/multi | DEV-001 (or last DEV) | Code review and quality scoring | --- ## Wisdom Accumulation Cross-sprint knowledge accumulation. Coordinator initializes `wisdom/` directory at session start. Equivalent to shared-memory sprint_history but structured for long-term learning. **Directory**: ``` /wisdom/ +-- learnings.md # Patterns and insights +-- decisions.md # Architecture and design decisions +-- conventions.md # Codebase conventions +-- issues.md # Known risks and issues ``` **Worker Loading** (Phase 2): Extract `Session: ` from task description, read wisdom directory files. **Worker Contributing** (Phase 4/5): Write discoveries from current task into corresponding wisdom files. **Shared Memory** (sprint-level learning, accumulated across sprints): | Field | Purpose | |-------|---------| | `sprint_history[]` | Per-sprint: what_worked, what_failed, patterns_learned | | `architecture_decisions[]` | Cross-sprint architecture decisions | | `implementation_context[]` | Implementation patterns and context | | `review_feedback_trends[]` | Review quality trends across sprints | | `resource_locks{}` | Current resource lock state (see Resource Lock Protocol) | | `task_checkpoints{}` | Task checkpoint data (see Checkpoint Management Protocol) | | `user_feedback_items[]` | User feedback items (see User Feedback Protocol) | | `tech_debt_items[]` | Tech debt tracking (see Tech Debt Management Protocol) | --- ## Task Ledger Real-time tracking of all sprint task progress. Coordinator updates at each task state transition. **Structure**: | Field | Description | |-------|-------------| | `sprint_id` | Current sprint identifier | | `sprint_goal` | Sprint objective | | `tasks[]` | Array of task entries (see below) | | `metrics` | Aggregated metrics: total, completed, in_progress, blocked, velocity | **Task Entry Fields**: | Field | Description | |-------|-------------| | `id` | Task identifier (e.g., DEV-001) | | `title` | Task title | | `owner` | Assigned role | | `status` | pending / in_progress / completed / blocked | | `started_at` / `completed_at` | Timestamps | | `gc_rounds` | Generator-Critic iteration count | | `review_score` | Reviewer score (null until reviewed) | | `test_pass_rate` | Tester pass rate (null until tested) | | `conflict_info` | Conflict state: status (none/detected/resolved), conflicting_files, resolution_strategy, resolved_by_task_id | | `rollback_info` | Rollback state: snapshot_id, rollback_procedure, last_successful_state_id | | `external_dependencies[]` | Dependency entries: name, version_range, actual_version, source, status (ok/mismatch/missing) | --- ## Coordinator Spawn Template When coordinator spawns workers, use background mode (Spawn-and-Stop): ``` Task({ subagent_type: "general-purpose", description: "Spawn worker", team_name: , name: "", run_in_background: true, prompt: `You are team "" . ## Primary Instruction All your work must be executed by calling Skill to load role definition: Skill(skill="team-iterdev", args="--role=") Current requirement: Session: ## Role Guidelines - Only process -* tasks, do not execute other roles' work - All output must have [] identifier prefix - Communicate only with coordinator - Do not use TaskCreate to create tasks for other roles - Before each SendMessage, call mcp__ccw-tools__team_msg to log ## Workflow 1. Call Skill -> load role definition and execution logic 2. Follow role.md 5-Phase flow 3. team_msg + SendMessage result to coordinator 4. TaskUpdate completed -> check next task` }) ``` --- ## Unified Session Directory ``` .workflow/.team/IDS-{slug}-{YYYY-MM-DD}/ +-- team-session.json +-- shared-memory.json # Cross-sprint learning +-- task-ledger.json # Real-time task progress ledger +-- wisdom/ # Cross-task knowledge accumulation | +-- learnings.md | +-- decisions.md | +-- conventions.md | +-- issues.md +-- design/ # Architect output | +-- design-001.md | +-- task-breakdown.json +-- code/ # Developer tracking | +-- dev-log.md +-- verify/ # Tester output | +-- verify-001.json +-- review/ # Reviewer output +-- review-001.md ``` ## Session Resume Coordinator supports `--resume` / `--continue` for interrupted sessions: 1. Scan `.workflow/.team/IDS-*/team-session.json` for active/paused sessions 2. Multiple matches -> AskUserQuestion for selection 3. Audit TaskList -> reconcile session state with task status 4. Reset in_progress -> pending (interrupted tasks) 5. Rebuild team and spawn needed workers only 6. Create missing tasks with correct blockedBy 7. Kick first executable task -> Phase 4 coordination loop ## Error Handling | Scenario | Resolution | |----------|------------| | Unknown --role value | Error with available role list | | Missing --role arg | Orchestration Mode -> coordinator | | Role file not found | Error with expected path | | GC loop exceeds 3 rounds | Accept with warning, record in shared memory | | Sprint velocity drops below 50% | Coordinator alerts user, suggests scope reduction | | Task ledger corrupted | Rebuild from TaskList state | | Conflict detected | Update conflict_info, notify coordinator, create DEV-fix task | | Resource lock timeout | Force release after 5 min, notify holder and coordinator | | Rollback requested | Validate snapshot_id, execute rollback procedure, notify all | | Deadlock detected | Abort youngest task, release its locks, notify coordinator | | Dependency mismatch | Log mismatch, block task until resolved or user override | | Checkpoint restore failure | Log error, worker restarts from Phase 1 |