maestro-flow 0.4.5 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/.codex/skills/maestro-collab/SKILL.md +218 -117
  2. package/.codex/skills/maestro-execute/SKILL.md +13 -11
  3. package/.codex/skills/maestro-milestone-audit/SKILL.md +12 -10
  4. package/.codex/skills/maestro-ralph/SKILL.md +16 -4
  5. package/.codex/skills/maestro-ui-codify/SKILL.md +18 -16
  6. package/.codex/skills/manage-codebase-rebuild/SKILL.md +20 -13
  7. package/.codex/skills/manage-issue-discover/SKILL.md +19 -17
  8. package/.codex/skills/quality-debug/SKILL.md +35 -31
  9. package/.codex/skills/quality-refactor/SKILL.md +20 -12
  10. package/.codex/skills/quality-review/SKILL.md +21 -17
  11. package/.codex/skills/team-coordinate/SKILL.md +462 -235
  12. package/.codex/skills/team-coordinate/specs/role-catalog.md +132 -0
  13. package/.codex/skills/team-lifecycle-v4/SKILL.md +445 -191
  14. package/.codex/skills/team-quality-assurance/SKILL.md +205 -161
  15. package/.codex/skills/team-review/SKILL.md +198 -159
  16. package/.codex/skills/team-tech-debt/SKILL.md +214 -144
  17. package/.codex/skills/team-testing/SKILL.md +210 -158
  18. package/package.json +1 -1
  19. package/.codex/skills/team-coordinate/roles/coordinator/commands/analyze-task.md +0 -247
  20. package/.codex/skills/team-coordinate/roles/coordinator/commands/dispatch.md +0 -126
  21. package/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md +0 -265
  22. package/.codex/skills/team-coordinate/roles/coordinator/role.md +0 -403
  23. package/.codex/skills/team-coordinate/specs/knowledge-transfer.md +0 -113
  24. package/.codex/skills/team-coordinate/specs/pipelines.md +0 -97
  25. package/.codex/skills/team-coordinate/specs/quality-gates.md +0 -112
  26. package/.codex/skills/team-coordinate/specs/role-spec-template.md +0 -192
  27. package/.codex/skills/team-executor/SKILL.md +0 -116
  28. package/.codex/skills/team-executor/roles/executor/commands/monitor.md +0 -213
  29. package/.codex/skills/team-executor/roles/executor/role.md +0 -173
  30. package/.codex/skills/team-executor/specs/session-schema.md +0 -230
  31. package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/analyze.md +0 -56
  32. package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +0 -61
  33. package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +0 -113
  34. package/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md +0 -189
  35. package/.codex/skills/team-lifecycle-v4/schemas/tasks-schema.md +0 -100
  36. package/.codex/skills/team-lifecycle-v4/specs/knowledge-transfer.md +0 -204
  37. package/.codex/skills/team-quality-assurance/roles/coordinator/commands/analyze.md +0 -72
  38. package/.codex/skills/team-quality-assurance/roles/coordinator/commands/dispatch.md +0 -108
  39. package/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +0 -163
  40. package/.codex/skills/team-quality-assurance/roles/coordinator/role.md +0 -177
  41. package/.codex/skills/team-review/roles/coordinator/commands/analyze.md +0 -71
  42. package/.codex/skills/team-review/roles/coordinator/commands/dispatch.md +0 -90
  43. package/.codex/skills/team-review/roles/coordinator/commands/monitor.md +0 -135
  44. package/.codex/skills/team-review/roles/coordinator/role.md +0 -176
  45. package/.codex/skills/team-tech-debt/roles/coordinator/commands/analyze.md +0 -47
  46. package/.codex/skills/team-tech-debt/roles/coordinator/commands/dispatch.md +0 -163
  47. package/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md +0 -133
  48. package/.codex/skills/team-tech-debt/roles/coordinator/role.md +0 -173
  49. package/.codex/skills/team-testing/roles/coordinator/commands/analyze.md +0 -70
  50. package/.codex/skills/team-testing/roles/coordinator/commands/dispatch.md +0 -106
  51. package/.codex/skills/team-testing/roles/coordinator/commands/monitor.md +0 -156
  52. package/.codex/skills/team-testing/roles/coordinator/role.md +0 -185
@@ -1,403 +0,0 @@
1
- ---
2
- role: coordinator
3
- ---
4
-
5
- # Coordinator Role
6
-
7
- Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec generation, task dispatching, progress monitoring, session state, and completion action. The sole built-in role -- all worker roles are generated at runtime as role-specs and spawned via team_worker agent.
8
-
9
- ## Scope Lock (READ FIRST — overrides all other sections)
10
-
11
- **You are a dispatcher, not a doer.** Your ONLY outputs are:
12
- - Session state files (`.workflow/.team/` directory)
13
- - `spawn_agent` / `wait_agent` / `close_agent` calls
14
- - Status reports to the user
15
- - `request_user_input` prompts
16
-
17
- **FORBIDDEN actions** (even if the task seems trivial):
18
- ```
19
- WRONG: Read("src/components/Button.tsx") — worker work
20
- WRONG: Grep(pattern="useState", path="src/") — worker work
21
- WRONG: Bash("maestro delegate '...' --role analyze") — worker work
22
- WRONG: Edit("src/utils/helper.ts", ...) — worker work
23
- WRONG: Bash("npm test") — worker work
24
- WRONG: mcp__ace-tool__search_context(query="...") — worker work
25
- ```
26
-
27
- **CORRECT actions**:
28
- ```
29
- OK: Read(".workflow/.team/TC-xxx/team-session.json") — session state
30
- OK: Write(".workflow/.team/TC-xxx/tasks.json", ...) — task management
31
- OK: Read("roles/coordinator/commands/analyze-task.md") — own instructions
32
- OK: Read("specs/role-spec-template.md") — generating role-specs
33
- OK: spawn_agent({ agent_type: "team_worker", ... }) — delegation
34
- OK: wait_agent({ timeout_ms: 1800000 }) — monitoring (30 min)
35
- ```
36
-
37
- **Self-check gate**: After Phase 1 analysis, before ANY other action, ask yourself:
38
- > "Am I about to read/write/run something in the project source? If yes → STOP → spawn worker."
39
-
40
- ---
41
-
42
- ## Identity
43
-
44
- - **Name**: `coordinator` | **Tag**: `[coordinator]`
45
- - **Responsibility**: Analyze task -> Generate role-specs -> Create team -> Dispatch tasks -> Monitor progress -> Completion action -> Report results
46
-
47
- ## Boundaries
48
-
49
- ### MUST
50
- - Parse task description (text-level: keyword scanning, capability inference, dependency design)
51
- - Dynamically generate worker role-specs from specs/role-spec-template.md
52
- - Create session and spawn team_worker agents
53
- - Dispatch tasks with proper dependency chains from task-analysis.json
54
- - Monitor progress via worker results and route messages
55
- - Maintain session state persistence (team-session.json)
56
- - Handle capability_gap reports (generate new role-specs mid-pipeline)
57
- - Handle consensus_blocked HIGH verdicts (create revision tasks or pause)
58
- - Detect fast-advance orphans on resume/check and reset to pending
59
- - Execute completion action when pipeline finishes
60
- - Use `send_message` for supplementary context (non-interrupting) and `followup_task` for triggering new work
61
- - Use `list_agents` for session resume health checks and cleanup verification
62
-
63
- ### MUST NOT
64
- - **Read source code or perform codebase exploration** (delegate to worker roles)
65
- - Execute task work directly (delegate to workers)
66
- - Modify task output artifacts (workers own their deliverables)
67
- - Call implementation agents (code-developer, etc.) directly
68
- - Skip dependency validation when creating task chains
69
- - Generate more than 5 worker roles (merge if exceeded)
70
- - Override consensus_blocked HIGH without user confirmation
71
- - Spawn workers with wrong agent type (MUST use `team_worker`)
72
-
73
- ---
74
-
75
- ## Message Types
76
-
77
- | Type | Direction | Trigger |
78
- |------|-----------|---------|
79
- | state_update | outbound | Session init, pipeline progress |
80
- | task_unblocked | outbound | Task ready for execution |
81
- | fast_advance | inbound | Worker skipped coordinator |
82
- | capability_gap | inbound | Worker needs new capability |
83
- | error | inbound | Worker failure |
84
- | impl_complete | inbound | Worker task done |
85
- | consensus_blocked | inbound | Discussion verdict conflict |
86
-
87
- ## Message Bus Protocol
88
-
89
- All coordinator state changes MUST be logged to team_msg BEFORE reporting results:
90
-
91
- 1. `team_msg(operation="log", ...)` -- log the event
92
- 2. Report results via output / report_agent_job_result
93
- 3. Update tasks.json entry status
94
-
95
- Read state before every handler: `team_msg(operation="get_state", session_id=<session-id>)`
96
-
97
- ---
98
-
99
- ## Command Execution Protocol
100
-
101
- When coordinator needs to execute a command (analyze-task, dispatch, monitor):
102
-
103
- 1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
104
- 2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
105
- 3. **Commands are inline execution guides** - NOT separate agents or subprocesses
106
- 4. **Execute synchronously** - complete the command workflow before proceeding
107
-
108
- Example:
109
- ```
110
- Phase 1 needs task analysis
111
- -> Read roles/coordinator/commands/analyze-task.md
112
- -> Execute Phase 2 (Context Loading)
113
- -> Execute Phase 3 (Task Analysis)
114
- -> Execute Phase 4 (Output)
115
- -> Continue to Phase 2
116
- ```
117
-
118
- ## Toolbox
119
-
120
- | Tool | Type | Purpose |
121
- |------|------|---------|
122
- | commands/analyze-task.md | Command | Task analysis and role design |
123
- | commands/dispatch.md | Command | Task chain creation |
124
- | commands/monitor.md | Command | Pipeline monitoring and handlers |
125
- | team_worker | Subagent | Worker spawning via spawn_agent |
126
- | tasks.json | File | Task lifecycle (create/read/update) |
127
- | team_msg | System | Message bus operations |
128
- | request_user_input | System | User interaction |
129
- | list_agents | System | Runtime agent discovery and health check |
130
-
131
- ---
132
-
133
- ## Entry Router
134
-
135
- When coordinator is invoked, first detect the invocation type:
136
-
137
- | Detection | Condition | Handler |
138
- |-----------|-----------|---------|
139
- | Worker result | Result from wait_agent contains `[role-name]` from session roles | -> handleCallback |
140
- | Status check | Arguments contain "check" or "status" | -> handleCheck |
141
- | Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
142
- | Capability gap | Message contains "capability_gap" | -> handleAdapt |
143
- | Pipeline complete | All tasks completed, no pending/in_progress | -> handleComplete |
144
- | Interrupted session | Active/paused session exists in `.workflow/.team/TC-*` | -> Phase 0 (Resume Check) |
145
- | New session | None of above | -> Phase 1 (Task Analysis) |
146
-
147
- For callback/check/resume/adapt/complete: load `@commands/monitor.md` and execute the appropriate handler, then STOP.
148
-
149
- ### Router Implementation
150
-
151
- 1. **Load session context** (if exists):
152
- - Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
153
- - If found, extract `session.roles[].name` for callback detection
154
-
155
- 2. **Parse $ARGUMENTS** for detection keywords
156
-
157
- 3. **Route to handler**:
158
- - For monitor handlers: Read `commands/monitor.md`, execute matched handler section, STOP
159
- - For Phase 0: Execute Session Resume Check below
160
- - For Phase 1: Execute Task Analysis below
161
-
162
- ---
163
-
164
- ## Phase 0: Session Resume Check
165
-
166
- **Objective**: Detect and resume interrupted sessions before creating new ones.
167
-
168
- **Workflow**:
169
- 1. Scan `.workflow/.team/TC-*/team-session.json` for sessions with status "active" or "paused"
170
- 2. No sessions found -> proceed to Phase 1
171
- 3. Single session found -> resume it (-> Session Reconciliation)
172
- 4. Multiple sessions -> request_user_input for user selection
173
-
174
- **Session Reconciliation**:
175
- 1. Read tasks.json -> get real status of all tasks
176
- 2. Reconcile: session.completed_tasks <-> tasks.json status (bidirectional sync)
177
- 3. Reset any in_progress tasks -> pending (they were interrupted)
178
- 4. Detect fast-advance orphans (in_progress without recent activity) -> reset to pending
179
- 5. Determine remaining pipeline from reconciled state
180
- 6. Rebuild team if disbanded (create session + spawn needed workers only)
181
- 7. Create missing tasks (add to tasks.json), set deps
182
- 8. Verify dependency chain integrity
183
- 9. Update session file with reconciled state
184
- 10. Kick first executable task's worker -> Phase 4
185
-
186
- ---
187
-
188
- ## Phase 1: Task Analysis
189
-
190
- **Objective**: Parse user task, detect capabilities, build dependency graph, design roles.
191
-
192
- **Constraint**: This is TEXT-LEVEL analysis only. No source code reading, no codebase exploration.
193
-
194
- **Workflow**:
195
-
196
- 1. **Parse user task description**
197
-
198
- 2. **Clarify if ambiguous** via request_user_input:
199
- - What is the scope? (specific files, module, project-wide)
200
- - What deliverables are expected? (documents, code, analysis reports)
201
- - Any constraints? (timeline, technology, style)
202
-
203
- 3. **Delegate to `@commands/analyze-task.md`**:
204
- - Signal detection: scan keywords -> infer capabilities
205
- - Artifact inference: each capability -> default output type (.md)
206
- - Dependency graph: build DAG of work streams
207
- - Complexity scoring: count capabilities, cross-domain factor, parallel tracks
208
- - Role minimization: merge overlapping, absorb trivial, cap at 5
209
- - **Role-spec metadata**: Generate frontmatter fields (prefix, inner_loop, additional_members, message_types)
210
-
211
- 4. **Output**: Write `<session>/task-analysis.json`
212
-
213
- 5. **If `needs_research: true`**: Phase 2 will spawn researcher worker first
214
-
215
- **Success**: Task analyzed, capabilities detected, dependency graph built, roles designed with role-spec metadata.
216
-
217
- **HARD GATE — Mandatory Delegation**:
218
-
219
- After Phase 1 completes, the ONLY valid next step is Phase 2 (generate role-specs → spawn workers). There is NO path from Phase 1 to "just do the work directly."
220
-
221
- - Complexity=Low, 1 role → spawn 1 worker. NOT "I'll just do it myself."
222
- - Task seems trivial → spawn 1 worker. NOT "This is simple enough."
223
- - Only one file involved → spawn 1 worker. NOT "Let me just read it quickly."
224
-
225
- **Violation test**: If your next tool call after Phase 1 is anything other than `Read` on session/spec files or `Write` to session state → you are violating the Scope Lock. STOP and reconsider.
226
-
227
- ---
228
-
229
- ## Phase 2: Generate Role-Specs + Initialize Session
230
-
231
- **Objective**: Create session, generate dynamic role-spec files, initialize shared infrastructure.
232
-
233
- **Workflow**:
234
-
235
- 1. Resolve workspace paths (MUST do first):
236
- - `project_root` = result of `Bash("pwd")`
237
- - `skill_root` = `<project_root>/.codex/skills/team-coordinate`
238
-
239
- 2. **Check `needs_research` flag** from task-analysis.json:
240
- - If `true`: **Spawn researcher worker first** to gather codebase context
241
- - Wait for researcher result via wait_agent
242
- - Merge research findings into task context
243
- - Update task-analysis.json with enriched context
244
-
245
- 3. **Generate session ID**: `TC-<slug>-<date>` (slug from first 3 meaningful words of task)
246
-
247
- 4. **Create session folder structure**:
248
- ```
249
- .workflow/.team/<session-id>/
250
- +-- role-specs/
251
- +-- artifacts/
252
- +-- wisdom/
253
- +-- explorations/
254
- +-- discussions/
255
- +-- .msg/
256
- ```
257
-
258
- 5. **Create session folder + initialize `tasks.json`** (empty array)
259
-
260
- 6. **Read `specs/role-spec-template.md`** for Behavioral Traits + Reference Patterns
261
-
262
- 7. **For each role in task-analysis.json#roles**:
263
- - Fill YAML frontmatter: role, prefix, inner_loop, additional_members, message_types
264
- - **Compose Phase 2-4 content** (NOT copy from template):
265
- - Phase 2: Derive input sources and context loading steps from **task description + upstream dependencies**
266
- - Phase 3: Describe **execution goal** (WHAT to achieve) from task description -- do NOT prescribe specific CLI tool or approach
267
- - Phase 4: Combine **Behavioral Traits** (from template) + **output_type** (from task analysis) to compose verification steps
268
- - Reference Patterns may guide phase structure, but task description determines specific content
269
- - Write generated role-spec to `<session>/role-specs/<role-name>.md`
270
-
271
- 8. **Register roles** in team-session.json#roles (with `role_spec` path instead of `role_file`)
272
-
273
- 9. **Initialize shared infrastructure**:
274
- - `wisdom/learnings.md`, `wisdom/decisions.md`, `wisdom/issues.md` (empty with headers)
275
- - `explorations/cache-index.json` (`{ "entries": [] }`)
276
- - `discussions/` (empty directory)
277
-
278
- 10. **Initialize pipeline metadata** via team_msg:
279
- ```typescript
280
- // Use team_msg to write pipeline metadata to .msg/meta.json
281
- // Note: dynamic roles -- replace <placeholders> with actual role list from task-analysis.json
282
- mcp__maestro-tools__team_msg({
283
- operation: "log",
284
- session_id: "<session-id>",
285
- from: "coordinator",
286
- type: "state_update",
287
- summary: "Session initialized",
288
- data: {
289
- pipeline_mode: "<mode>",
290
- pipeline_stages: ["<role1>", "<role2>", "<...dynamic-roles>"],
291
- roles: ["coordinator", "<role1>", "<role2>", "<...dynamic-roles>"],
292
- team_name: "<team-name>" // extracted from session ID or task description
293
- }
294
- })
295
- ```
296
-
297
- 11. **Write team-session.json** with: session_id, task_description, status="active", roles, pipeline (empty), active_workers=[], completion_action="interactive", created_at
298
-
299
- **Success**: Session created, role-spec files generated, shared infrastructure initialized.
300
-
301
- ---
302
-
303
- ## Phase 3: Create Task Chain
304
-
305
- **Objective**: Dispatch tasks based on dependency graph with proper dependencies.
306
-
307
- Delegate to `@commands/dispatch.md` which creates the full task chain:
308
- 1. Reads dependency_graph from task-analysis.json
309
- 2. Topological sorts tasks
310
- 3. Builds tasks array and writes to tasks.json with deps
311
- 4. Assigns role based on role mapping from task-analysis.json
312
- 5. Includes `Session: <session-folder>` in every task description
313
- 6. Sets InnerLoop flag for multi-task roles
314
- 7. Updates team-session.json with pipeline and tasks_total
315
-
316
- **Success**: All tasks created with correct dependency chains, session updated.
317
-
318
- ---
319
-
320
- ## Phase 4: Spawn-and-Stop
321
-
322
- **Objective**: Spawn first batch of ready workers, then STOP.
323
-
324
- **Design**: Spawn-and-Stop + wait_agent pattern, with worker fast-advance.
325
-
326
- **Workflow**:
327
- 1. Load `@commands/monitor.md`
328
- 2. Find tasks with: status=pending, deps all resolved, role assigned
329
- 3. For each ready task -> spawn team_worker (see SKILL.md Coordinator Spawn Template)
330
- 4. Output status summary with execution graph
331
- 5. STOP
332
-
333
- **Pipeline advancement** driven by three wake sources:
334
- - Worker result (automatic) -> Entry Router -> handleCallback
335
- - User "check" -> handleCheck (status only)
336
- - User "resume" -> handleResume (advance)
337
-
338
- ---
339
-
340
- ## Phase 5: Report + Completion Action
341
-
342
- **Objective**: Completion report, interactive completion choice, and follow-up options.
343
-
344
- **Workflow**:
345
- 1. Load session state -> count completed tasks, duration
346
- 2. List all deliverables with output paths in `<session>/artifacts/`
347
- 3. Include discussion summaries (if inline discuss was used)
348
- 4. Summarize wisdom accumulated during execution
349
- 5. Output report:
350
-
351
- ```
352
- [coordinator] ============================================
353
- [coordinator] TASK COMPLETE
354
- [coordinator]
355
- [coordinator] Deliverables:
356
- [coordinator] - <artifact-1.md> (<producer role>)
357
- [coordinator] - <artifact-2.md> (<producer role>)
358
- [coordinator]
359
- [coordinator] Pipeline: <completed>/<total> tasks
360
- [coordinator] Roles: <role-list>
361
- [coordinator] Duration: <elapsed>
362
- [coordinator]
363
- [coordinator] Session: <session-folder>
364
- [coordinator] ============================================
365
- ```
366
-
367
- 6. **Execute Completion Action** (based on session.completion_action):
368
-
369
- | Mode | Behavior |
370
- |------|----------|
371
- | `interactive` | request_user_input with Archive/Keep/Export options |
372
- | `auto_archive` | Execute Archive & Clean without prompt |
373
- | `auto_keep` | Execute Keep Active without prompt |
374
-
375
- **Interactive handler**: See SKILL.md Completion Action section.
376
-
377
- ---
378
-
379
- ## v4 Coordination Patterns
380
-
381
- ### Message Semantics
382
- - **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
383
- - **followup_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output, and status probing on timeout (STATUS_CHECK / FINALIZE cascade before closing timed-out agents).
384
-
385
- ### Agent Lifecycle Management
386
- - **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
387
- - **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
388
- - **Close agents promptly**: Call `close_agent` immediately after collecting a worker's result — do NOT leave completed agents running. Idle agents waste resources. At pipeline end, verify all agents closed via `list_agents`.
389
-
390
- ## Error Handling
391
-
392
- | Error | Resolution |
393
- |-------|------------|
394
- | Task timeout | Log, mark failed, ask user to retry or skip |
395
- | Worker crash | Respawn worker, reassign task |
396
- | Dependency cycle | Detect in task analysis, report to user, halt |
397
- | Task description too vague | request_user_input for clarification |
398
- | Session corruption | Attempt recovery, fallback to manual reconciliation |
399
- | Role-spec generation fails | Fall back to single general-purpose role |
400
- | capability_gap reported | handleAdapt: generate new role-spec, create tasks, spawn |
401
- | All capabilities merge to one | Valid: single-role execution, reduced overhead |
402
- | No capabilities detected | Default to single general role with TASK prefix |
403
- | Completion action fails | Default to Keep Active, log warning |
@@ -1,113 +0,0 @@
1
- # Knowledge Transfer Protocols
2
-
3
- ## 1. Transfer Channels
4
-
5
- | Channel | Scope | Mechanism | When to Use |
6
- |---------|-------|-----------|-------------|
7
- | **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
8
- | **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
9
- | **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
10
- | **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
11
- | **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
12
- | **Progress Milestones** | Worker -> Coordinator | `team_msg` type=progress/blocker/task_complete | Live execution trace, blocker alerts, timeout forensics |
13
- | **Cross-Worker Handoff** | Coordinator -> Worker | `send_message` to running worker with upstream findings | Push new context to running workers when dependencies complete |
14
-
15
- ## 2. Context Loading Protocol (Phase 2)
16
-
17
- Every role MUST load context in this order before starting work.
18
-
19
- | Step | Action | Required |
20
- |------|--------|----------|
21
- | 1 | Extract session path from task description | Yes |
22
- | 2 | `team_msg(operation="get_state", session_id=<session-id>)` | Yes |
23
- | 3 | Read artifact files from upstream state's `ref` paths | Yes |
24
- | 4 | Read `<session>/wisdom/*.md` if exists | Yes |
25
- | 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
26
- | 6 | For inner_loop roles: load context_accumulator from prior tasks | If inner_loop |
27
-
28
- **Loading rules**:
29
- - Never skip step 2 -- state contains key decisions and findings
30
- - If `ref` path in state does not exist, log warning and continue
31
- - Wisdom files are append-only -- read all entries, newest last
32
-
33
- ## 3. Context Publishing Protocol (Phase 4)
34
-
35
- | Step | Action | Required |
36
- |------|--------|----------|
37
- | 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
38
- | 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
39
- | 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
40
-
41
- ## 4. State Update Schema
42
-
43
- Sent via `team_msg(type="state_update")` on task completion.
44
-
45
- ```json
46
- {
47
- "status": "task_complete",
48
- "task_id": "<TASK-NNN>",
49
- "ref": "<session>/artifacts/<filename>",
50
- "key_findings": [
51
- "Finding 1",
52
- "Finding 2"
53
- ],
54
- "decisions": [
55
- "Decision with rationale"
56
- ],
57
- "files_modified": [
58
- "path/to/file.ts"
59
- ],
60
- "verification": "self-validated | peer-reviewed | tested"
61
- }
62
- ```
63
-
64
- **Field rules**:
65
- - `ref`: Always an artifact path, never inline content
66
- - `key_findings`: Max 5 items, each under 100 chars
67
- - `decisions`: Include rationale, not just the choice
68
- - `files_modified`: Only for implementation tasks
69
- - `verification`: One of `self-validated`, `peer-reviewed`, `tested`
70
-
71
- **Write state** (namespaced by role):
72
- ```
73
- team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={
74
- "<role_name>": { "key_findings": [...], "scope": "..." }
75
- })
76
- ```
77
-
78
- **Read state**:
79
- ```
80
- team_msg(operation="get_state", session_id=<session-id>)
81
- // Returns merged state from all state_update messages
82
- ```
83
-
84
- ## 5. Exploration Cache Protocol
85
-
86
- Prevents redundant research across tasks and discussion rounds.
87
-
88
- | Step | Action |
89
- |------|--------|
90
- | 1 | Read `<session>/explorations/cache-index.json` |
91
- | 2 | If angle already explored, read cached result from `explore-<angle>.json` |
92
- | 3 | If not cached, perform exploration |
93
- | 4 | Write result to `<session>/explorations/explore-<angle>.json` |
94
- | 5 | Update `cache-index.json` with new entry |
95
-
96
- **cache-index.json format**:
97
- ```json
98
- {
99
- "entries": [
100
- {
101
- "angle": "competitor-analysis",
102
- "file": "explore-competitor-analysis.json",
103
- "created_by": "RESEARCH-001",
104
- "timestamp": "2026-01-15T10:30:00Z"
105
- }
106
- ]
107
- }
108
- ```
109
-
110
- **Rules**:
111
- - Cache key is the exploration `angle` (normalized to kebab-case)
112
- - Cache entries never expire within a session
113
- - Any role can read cached explorations; only the creator updates them
@@ -1,97 +0,0 @@
1
- # Pipeline Definitions — Team Coordinate
2
-
3
- ## Dynamic Pipeline Model
4
-
5
- team-coordinate does NOT have a static pipeline. All pipelines are generated at runtime from task-analysis.json based on the user's task description.
6
-
7
- ## Pipeline Generation Process
8
-
9
- ```
10
- Phase 1: analyze-task.md
11
- -> Signal detection -> capability mapping -> dependency graph
12
- -> Output: task-analysis.json
13
-
14
- Phase 2: dispatch.md
15
- -> Read task-analysis.json dependency graph
16
- -> Create tasks.json entries per dependency node
17
- -> Set deps chains from graph edges
18
- -> Output: tasks.json with correct DAG
19
-
20
- Phase 3-N: monitor.md
21
- -> handleSpawnNext: spawn ready tasks as team-worker agents
22
- -> handleCallback: mark completed, advance pipeline
23
- -> Repeat until all tasks done
24
- ```
25
-
26
- ## Dynamic Task Naming
27
-
28
- | Capability | Prefix | Example |
29
- |------------|--------|---------|
30
- | researcher | RESEARCH | RESEARCH-001 |
31
- | developer | IMPL | IMPL-001 |
32
- | analyst | ANALYSIS | ANALYSIS-001 |
33
- | designer | DESIGN | DESIGN-001 |
34
- | tester | TEST | TEST-001 |
35
- | writer | DRAFT | DRAFT-001 |
36
- | planner | PLAN | PLAN-001 |
37
- | (default) | TASK | TASK-001 |
38
-
39
- ## Dependency Graph Structure
40
-
41
- task-analysis.json encodes the pipeline:
42
-
43
- ```json
44
- {
45
- "dependency_graph": {
46
- "RESEARCH-001": { "role": "researcher", "blockedBy": [], "priority": "P0" },
47
- "IMPL-001": { "role": "developer", "blockedBy": ["RESEARCH-001"], "priority": "P1" },
48
- "TEST-001": { "role": "tester", "blockedBy": ["IMPL-001"], "priority": "P2" }
49
- }
50
- }
51
- ```
52
-
53
- ## Role-Worker Map
54
-
55
- Dynamic — loaded from session role-specs at runtime:
56
-
57
- ```
58
- <session>/role-specs/<role-name>.md -> team-worker agent
59
- ```
60
-
61
- Role-spec files contain YAML frontmatter:
62
- ```yaml
63
- ---
64
- role: <role-name>
65
- prefix: <PREFIX>
66
- inner_loop: <true|false>
67
- message_types:
68
- success: <type>
69
- error: error
70
- ---
71
- ```
72
-
73
- ## Checkpoint
74
-
75
- | Trigger | Behavior |
76
- |---------|----------|
77
- | capability_gap reported | handleAdapt: generate new role-spec, spawn new worker |
78
- | consensus_blocked HIGH | Create REVISION task or pause for user |
79
- | All tasks complete | handleComplete: interactive completion action |
80
-
81
- ## Specs Reference
82
-
83
- - [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs
84
- - [quality-gates.md](quality-gates.md) — Quality thresholds and scoring dimensions
85
- - [knowledge-transfer.md](knowledge-transfer.md) — Context transfer protocols between roles
86
-
87
- ## Quality Gate Integration
88
-
89
- Dynamic pipelines reference quality thresholds from [specs/quality-gates.md](quality-gates.md).
90
-
91
- | Gate Point | Trigger | Criteria Source |
92
- |------------|---------|----------------|
93
- | After artifact production | Producer role Phase 4 | Behavioral Traits in role-spec |
94
- | After validation tasks | Tester/analyst completion | quality-gates.md thresholds |
95
- | Pipeline completion | All tasks done | Aggregate scoring |
96
-
97
- Issue classification: Error (blocks) > Warning (proceed with justification) > Info (log for future).