mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-07 16:41:06 +08:00
feat: Add templates for epics, product brief, and requirements documentation
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
@@ -1,415 +1,61 @@
|
||||
---
|
||||
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".
|
||||
description: Unified team skill for iterative development team. Pure router — all roles read this file. Beat model is coordinator-only in monitor.md. Generator-Critic loops (developer<->reviewer, max 3 rounds). Triggers on "team iterdev".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), 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`.
|
||||
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.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
+---------------------------------------------------+
|
||||
| Skill(skill="team-iterdev") |
|
||||
| args="<task-description>" |
|
||||
+-------------------+-------------------------------+
|
||||
Skill(skill="team-iterdev", args="task description")
|
||||
|
|
||||
Orchestration Mode (auto -> coordinator)
|
||||
SKILL.md (this file) = Router
|
||||
|
|
||||
Coordinator (inline)
|
||||
Phase 0-5 orchestration
|
||||
|
|
||||
+-------+-------+-------+-------+
|
||||
v v v v
|
||||
[tw] [tw] [tw] [tw]
|
||||
archi- devel- tester review-
|
||||
tect oper er
|
||||
|
||||
(tw) = team-worker agent
|
||||
+--------------+--------------+
|
||||
| |
|
||||
no --role flag --role <name>
|
||||
| |
|
||||
Coordinator Worker
|
||||
roles/coordinator/role.md roles/<name>/role.md
|
||||
|
|
||||
+-- analyze -> dispatch -> spawn workers -> STOP
|
||||
|
|
||||
+-------+-------+-------+
|
||||
v v v v
|
||||
[architect] [developer] [tester] [reviewer]
|
||||
(team-worker agents, each loads roles/<role>/role.md)
|
||||
```
|
||||
|
||||
## Role Registry
|
||||
|
||||
| Role | Path | Prefix | Inner Loop |
|
||||
|------|------|--------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
|
||||
| architect | [roles/architect/role.md](roles/architect/role.md) | DESIGN-* | false |
|
||||
| developer | [roles/developer/role.md](roles/developer/role.md) | DEV-* | true |
|
||||
| tester | [roles/tester/role.md](roles/tester/role.md) | VERIFY-* | false |
|
||||
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-* | false |
|
||||
|
||||
## Role Router
|
||||
|
||||
### Input Parsing
|
||||
Parse `$ARGUMENTS`:
|
||||
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
|
||||
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
|
||||
|
||||
Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto route to coordinator).
|
||||
## Shared Constants
|
||||
|
||||
### Role Registry
|
||||
- **Session prefix**: `IDS`
|
||||
- **Session path**: `.workflow/.team/IDS-<slug>-<date>/`
|
||||
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
|
||||
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
|
||||
|
||||
| Role | Spec | Task Prefix | Inner Loop |
|
||||
|------|------|-------------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
|
||||
| architect | [role-specs/architect.md](role-specs/architect.md) | DESIGN-* | false |
|
||||
| developer | [role-specs/developer.md](role-specs/developer.md) | DEV-* | true |
|
||||
| tester | [role-specs/tester.md](role-specs/tester.md) | VERIFY-* | false |
|
||||
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REVIEW-* | false |
|
||||
## Worker Spawn Template
|
||||
|
||||
> **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", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
|
||||
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
|
||||
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
|
||||
2. **SendMessage**: Send result to coordinator
|
||||
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 |
|
||||
| Share state via team_msg(type='state_update') | Create tasks for other roles |
|
||||
| SendMessage to coordinator | Communicate directly with other workers |
|
||||
|
||||
**Coordinator additional restrictions**: No direct code writing, no directly executing analysis/testing/review.
|
||||
|
||||
### Message Bus
|
||||
|
||||
Call `mcp__ccw-tools__team_msg` with: operation="log", session_id=<session-id>, from=<role>, type=<type>, data={ref: "<file_path>"}
|
||||
`to` and `summary` auto-defaulted -- do NOT specify explicitly.
|
||||
|
||||
**CLI Fallback**: `ccw team log --session-id "<session-id>" --from "<role>" --type "<type>" --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}/` |
|
||||
| State sharing | team_msg(type='state_update') + .msg/meta.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` via team_msg(type='state_update'). 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` via team_msg(type='state_update') 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` via team_msg(type='state_update') (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` via team_msg(type='state_update'). 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**:
|
||||
```
|
||||
<session-folder>/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: <path>` 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
|
||||
|
||||
### v5 Worker Spawn (all roles)
|
||||
|
||||
When coordinator spawns workers, use `team-worker` agent with role-spec path:
|
||||
Coordinator spawns workers using this template:
|
||||
|
||||
```
|
||||
Agent({
|
||||
@@ -420,7 +66,7 @@ Agent({
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-iterdev/role-specs/<role>.md
|
||||
role_spec: .claude/skills/team-iterdev/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: iterdev
|
||||
@@ -428,92 +74,54 @@ requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
|
||||
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
**Inner Loop roles** (developer): Set `inner_loop: true`. The team-worker agent handles the loop internally.
|
||||
## User Commands
|
||||
|
||||
**Single-task roles** (architect, tester, reviewer): Set `inner_loop: false`.
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | View execution status graph |
|
||||
| `resume` / `continue` | Advance to next step |
|
||||
|
||||
---
|
||||
|
||||
## Completion Action
|
||||
|
||||
When the pipeline completes (all tasks done, coordinator Phase 5):
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "IterDev pipeline complete. What would you like to do?",
|
||||
header: "Completion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
|
||||
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
|
||||
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
.workflow/.team/IDS-<slug>-<YYYY-MM-DD>/
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl # Team message bus
|
||||
│ └── meta.json # Session state
|
||||
├── task-analysis.json # Coordinator analyze output
|
||||
├── 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
|
||||
```
|
||||
|
||||
| Choice | Action |
|
||||
|--------|--------|
|
||||
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-iterdev", args="resume")` |
|
||||
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
|
||||
## Specs Reference
|
||||
|
||||
---
|
||||
|
||||
## Unified Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/IDS-{slug}-{YYYY-MM-DD}/
|
||||
+-- .msg/meta.json
|
||||
+-- .msg/messages.jsonl # Team message bus
|
||||
+-- .msg/meta.json # Session metadata
|
||||
+-- 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-*/.msg/meta.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
|
||||
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
|
||||
|
||||
## 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 |
|
||||
| Unknown command | Error with available command list |
|
||||
| Role not found | Error with role registry |
|
||||
| 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 |
|
||||
| Pipeline deadlock | Check blockedBy chain, report blocking point |
|
||||
|
||||
Reference in New Issue
Block a user