maestro-flow 0.2.1 → 0.2.2

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 (141) hide show
  1. package/.claude/agents/team-supervisor.md +18 -8
  2. package/.claude/agents/team-worker.md +78 -0
  3. package/.claude/skills/team-coordinate/SKILL.md +266 -0
  4. package/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md +247 -0
  5. package/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md +131 -0
  6. package/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md +358 -0
  7. package/.claude/skills/team-coordinate/roles/coordinator/role.md +363 -0
  8. package/.claude/skills/team-coordinate/specs/knowledge-transfer.md +111 -0
  9. package/.claude/skills/team-coordinate/specs/pipelines.md +97 -0
  10. package/.claude/skills/team-coordinate/specs/quality-gates.md +112 -0
  11. package/.claude/skills/team-coordinate/specs/role-spec-template.md +192 -0
  12. package/.claude/skills/team-executor/SKILL.md +189 -0
  13. package/.claude/skills/team-executor/roles/executor/commands/monitor.md +239 -0
  14. package/.claude/skills/team-executor/roles/executor/role.md +171 -0
  15. package/.claude/skills/team-executor/specs/session-schema.md +264 -0
  16. package/.claude/skills/team-lifecycle-v4/SKILL.md +209 -0
  17. package/.claude/skills/team-lifecycle-v4/roles/analyst/role.md +78 -0
  18. package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/analyze.md +56 -0
  19. package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +56 -0
  20. package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +157 -0
  21. package/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md +130 -0
  22. package/.claude/skills/team-lifecycle-v4/roles/executor/commands/fix.md +35 -0
  23. package/.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md +62 -0
  24. package/.claude/skills/team-lifecycle-v4/roles/executor/role.md +67 -0
  25. package/.claude/skills/team-lifecycle-v4/roles/planner/role.md +76 -0
  26. package/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/review-code.md +34 -0
  27. package/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md +44 -0
  28. package/.claude/skills/team-lifecycle-v4/roles/reviewer/role.md +69 -0
  29. package/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md +192 -0
  30. package/.claude/skills/team-lifecycle-v4/roles/tester/role.md +87 -0
  31. package/.claude/skills/team-lifecycle-v4/roles/writer/role.md +95 -0
  32. package/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md +112 -0
  33. package/.claude/skills/team-lifecycle-v4/specs/pipelines.md +125 -0
  34. package/.claude/skills/team-lifecycle-v4/specs/quality-gates.md +130 -0
  35. package/.claude/skills/team-lifecycle-v4/templates/architecture.md +254 -0
  36. package/.claude/skills/team-lifecycle-v4/templates/epics.md +196 -0
  37. package/.claude/skills/team-lifecycle-v4/templates/product-brief.md +133 -0
  38. package/.claude/skills/team-lifecycle-v4/templates/requirements.md +224 -0
  39. package/.claude/skills/team-quality-assurance/SKILL.md +147 -0
  40. package/.claude/skills/team-quality-assurance/roles/analyst/role.md +80 -0
  41. package/.claude/skills/team-quality-assurance/roles/coordinator/commands/analyze.md +72 -0
  42. package/.claude/skills/team-quality-assurance/roles/coordinator/commands/dispatch.md +111 -0
  43. package/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +250 -0
  44. package/.claude/skills/team-quality-assurance/roles/coordinator/role.md +143 -0
  45. package/.claude/skills/team-quality-assurance/roles/executor/role.md +66 -0
  46. package/.claude/skills/team-quality-assurance/roles/generator/role.md +68 -0
  47. package/.claude/skills/team-quality-assurance/roles/scout/role.md +67 -0
  48. package/.claude/skills/team-quality-assurance/roles/strategist/role.md +71 -0
  49. package/.claude/skills/team-quality-assurance/specs/pipelines.md +115 -0
  50. package/.claude/skills/team-quality-assurance/specs/team-config.json +131 -0
  51. package/.claude/skills/team-review/SKILL.md +147 -0
  52. package/.claude/skills/team-review/roles/coordinator/commands/analyze.md +71 -0
  53. package/.claude/skills/team-review/roles/coordinator/commands/dispatch.md +91 -0
  54. package/.claude/skills/team-review/roles/coordinator/commands/monitor.md +224 -0
  55. package/.claude/skills/team-review/roles/coordinator/role.md +132 -0
  56. package/.claude/skills/team-review/roles/fixer/role.md +76 -0
  57. package/.claude/skills/team-review/roles/reviewer/role.md +68 -0
  58. package/.claude/skills/team-review/roles/scanner/role.md +71 -0
  59. package/.claude/skills/team-review/specs/dimensions.md +82 -0
  60. package/.claude/skills/team-review/specs/finding-schema.json +82 -0
  61. package/.claude/skills/team-review/specs/pipelines.md +102 -0
  62. package/.claude/skills/team-review/specs/team-config.json +27 -0
  63. package/.claude/skills/team-tech-debt/SKILL.md +128 -0
  64. package/.claude/skills/team-tech-debt/roles/assessor/role.md +69 -0
  65. package/.claude/skills/team-tech-debt/roles/coordinator/commands/analyze.md +47 -0
  66. package/.claude/skills/team-tech-debt/roles/coordinator/commands/dispatch.md +156 -0
  67. package/.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md +209 -0
  68. package/.claude/skills/team-tech-debt/roles/coordinator/role.md +123 -0
  69. package/.claude/skills/team-tech-debt/roles/executor/role.md +76 -0
  70. package/.claude/skills/team-tech-debt/roles/planner/role.md +69 -0
  71. package/.claude/skills/team-tech-debt/roles/scanner/role.md +82 -0
  72. package/.claude/skills/team-tech-debt/roles/validator/role.md +78 -0
  73. package/.claude/skills/team-tech-debt/specs/pipelines.md +47 -0
  74. package/.claude/skills/team-tech-debt/specs/team-config.json +129 -0
  75. package/.claude/skills/team-testing/SKILL.md +143 -0
  76. package/.claude/skills/team-testing/roles/analyst/role.md +95 -0
  77. package/.claude/skills/team-testing/roles/coordinator/commands/analyze.md +70 -0
  78. package/.claude/skills/team-testing/roles/coordinator/commands/dispatch.md +108 -0
  79. package/.claude/skills/team-testing/roles/coordinator/commands/monitor.md +257 -0
  80. package/.claude/skills/team-testing/roles/coordinator/role.md +134 -0
  81. package/.claude/skills/team-testing/roles/executor/role.md +99 -0
  82. package/.claude/skills/team-testing/roles/generator/role.md +98 -0
  83. package/.claude/skills/team-testing/roles/strategist/role.md +83 -0
  84. package/.claude/skills/team-testing/specs/pipelines.md +101 -0
  85. package/.claude/skills/team-testing/specs/team-config.json +93 -0
  86. package/.codex/skills/maestro-coordinate/SKILL.md +6 -6
  87. package/.codex/skills/maestro-overlay/SKILL.md +1 -3
  88. package/.codex/skills/manage-issue-analyze/SKILL.md +2 -2
  89. package/.codex/skills/quality-retrospective/SKILL.md +30 -31
  90. package/.codex/skills/team-coordinate/SKILL.md +16 -18
  91. package/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md +50 -7
  92. package/.codex/skills/team-coordinate/roles/coordinator/role.md +4 -4
  93. package/.codex/skills/team-coordinate/specs/knowledge-transfer.md +2 -0
  94. package/.codex/skills/team-executor/SKILL.md +11 -13
  95. package/.codex/skills/team-executor/roles/executor/commands/monitor.md +47 -11
  96. package/.codex/skills/team-lifecycle-v4/SKILL.md +27 -33
  97. package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md +94 -0
  98. package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +1 -1
  99. package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +94 -27
  100. package/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md +12 -14
  101. package/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md +1 -1
  102. package/.codex/skills/team-lifecycle-v4/specs/knowledge-transfer.md +69 -1
  103. package/.codex/skills/team-quality-assurance/SKILL.md +14 -16
  104. package/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +60 -11
  105. package/.codex/skills/team-quality-assurance/roles/coordinator/role.md +4 -4
  106. package/.codex/skills/team-review/SKILL.md +14 -16
  107. package/.codex/skills/team-review/roles/coordinator/commands/monitor.md +47 -10
  108. package/.codex/skills/team-review/roles/coordinator/role.md +4 -4
  109. package/.codex/skills/team-tech-debt/SKILL.md +13 -15
  110. package/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md +51 -12
  111. package/.codex/skills/team-tech-debt/roles/coordinator/role.md +4 -4
  112. package/.codex/skills/team-testing/SKILL.md +15 -17
  113. package/.codex/skills/team-testing/roles/coordinator/commands/monitor.md +51 -13
  114. package/.codex/skills/team-testing/roles/coordinator/role.md +4 -4
  115. package/dashboard/dist-server/dashboard/src/server/agents/stream-json-adapter.js +4 -0
  116. package/dashboard/dist-server/dashboard/src/server/agents/stream-json-adapter.js.map +1 -1
  117. package/dashboard/dist-server/dashboard/src/server/routes/cli-history.js +8 -1
  118. package/dashboard/dist-server/dashboard/src/server/routes/cli-history.js.map +1 -1
  119. package/dashboard/dist-server/dashboard/src/server/routes/mcp.js +20 -0
  120. package/dashboard/dist-server/dashboard/src/server/routes/mcp.js.map +1 -1
  121. package/dashboard/dist-server/dashboard/src/shared/constants.d.ts +1 -0
  122. package/dashboard/dist-server/dashboard/src/shared/constants.js +1 -0
  123. package/dashboard/dist-server/dashboard/src/shared/constants.js.map +1 -1
  124. package/dashboard/dist-server/src/agents/cli-history-store.js +21 -3
  125. package/dashboard/dist-server/src/agents/cli-history-store.js.map +1 -1
  126. package/dist/src/agents/cli-history-store.d.ts.map +1 -1
  127. package/dist/src/agents/cli-history-store.js +21 -3
  128. package/dist/src/agents/cli-history-store.js.map +1 -1
  129. package/dist/src/commands/cli.d.ts.map +1 -1
  130. package/dist/src/commands/cli.js +20 -8
  131. package/dist/src/commands/cli.js.map +1 -1
  132. package/dist/src/commands/uninstall-ui/UninstallFlow.d.ts.map +1 -1
  133. package/dist/src/commands/uninstall-ui/UninstallFlow.js +5 -4
  134. package/dist/src/commands/uninstall-ui/UninstallFlow.js.map +1 -1
  135. package/dist/src/commands/uninstall.js +1 -1
  136. package/dist/src/commands/uninstall.js.map +1 -1
  137. package/dist/src/core/manifest.d.ts.map +1 -1
  138. package/dist/src/core/manifest.js +9 -1
  139. package/dist/src/core/manifest.js.map +1 -1
  140. package/package.json +1 -1
  141. package/workflows/cli-tools-usage.md +6 -2
@@ -48,18 +48,28 @@ Triggered when coordinator sends a checkpoint request message:
48
48
 
49
49
  1. **Parse request**: Extract `task_id` and `scope` from coordinator message
50
50
  2. **Claim task**: `TaskUpdate({ taskId: "<task_id>", status: "in_progress" })`
51
- 3. **Incremental context load**: Only load data new since last wake:
51
+ 3. **Read worker progress** (optional): Check progress milestones for risk assessment:
52
+ ```javascript
53
+ const progressMsgs = mcp__maestro__team_msg({
54
+ operation: "list", session_id: "<session_id>", type: "progress", last: 50
55
+ })
56
+ const blockerMsgs = mcp__maestro__team_msg({
57
+ operation: "list", session_id: "<session_id>", type: "blocker", last: 10
58
+ })
59
+ // Use progress data to assess worker health and identify stalled tasks
60
+ ```
61
+ 4. **Incremental context load**: Only load data new since last wake:
52
62
  - Role states: `team_msg(operation="get_state")` for newly completed roles
53
63
  - Message bus: `team_msg(operation="list", session_id, last=30)` for recent messages
54
64
  - Artifacts: Read files in scope not already in context_accumulator
55
65
  - Wisdom: Read `<session>/wisdom/*.md` for new entries
56
- 4. **Execute checks**: Follow checkpoint-specific instructions from role_spec body
57
- 5. **Write report**: Output to `<session>/artifacts/CHECKPOINT-NNN-report.md`
58
- 6. **Complete task**: `TaskUpdate({ taskId: "<task_id>", status: "completed" })`
59
- 7. **Publish state**: Log `state_update` via `team_msg` with verdict, score, findings
60
- 8. **Accumulate context**: Append checkpoint results to `context_accumulator`
61
- 9. **Report to coordinator**: SendMessage with verdict summary, findings, quality trend
62
- 10. **Go idle**: Wait for next checkpoint request or shutdown
66
+ 5. **Execute checks**: Follow checkpoint-specific instructions from role_spec body
67
+ 6. **Write report**: Output to `<session>/artifacts/CHECKPOINT-NNN-report.md`
68
+ 7. **Complete task**: `TaskUpdate({ taskId: "<task_id>", status: "completed" })`
69
+ 8. **Publish state**: Log `state_update` via `team_msg` with verdict, score, findings
70
+ 9. **Accumulate context**: Append checkpoint results to `context_accumulator`
71
+ 10. **Report to coordinator**: SendMessage with verdict summary, findings, quality trend
72
+ 11. **Go idle**: Wait for next checkpoint request or shutdown
63
73
 
64
74
  ### 4. Crash Recovery
65
75
 
@@ -88,6 +88,84 @@ After execution, publish contributions:
88
88
  2. Prepare state data for the reporting phase
89
89
  3. Append discoveries to wisdom files (`learnings.md`, `decisions.md`, `issues.md`)
90
90
 
91
+ ### Progress Milestone Protocol
92
+
93
+ Report progress via `mcp__maestro__team_msg` at natural phase boundaries. This enables coordinator status dashboards and timeout forensics.
94
+
95
+ **Milestone Reporting** — at each phase boundary:
96
+
97
+ ```javascript
98
+ mcp__maestro__team_msg({
99
+ operation: "log",
100
+ session_id: "<session_id>",
101
+ from: "<task_id>",
102
+ to: "coordinator",
103
+ type: "progress",
104
+ summary: "[<task_id>] <brief phase description> (<pct>%)",
105
+ data: {
106
+ task_id: "<task_id>",
107
+ role: "<role>",
108
+ status: "in_progress",
109
+ progress_pct: <0-100>,
110
+ phase: "<what just completed>",
111
+ key_info: "<most important finding or decision>"
112
+ }
113
+ })
114
+ ```
115
+
116
+ **Role-Specific Milestones**:
117
+
118
+ | Role | ~30% | ~60% | ~90% |
119
+ |------|------|------|------|
120
+ | analyst/researcher | Context loaded | Core analysis done | Verification complete |
121
+ | writer/drafter | Sources gathered | Draft written | Self-review done |
122
+ | planner | Requirements parsed | Plan structured | Dependencies validated |
123
+ | executor/implementer | Context loaded | Core changes done | Tests passing |
124
+ | reviewer/tester | Scope mapped | Reviews/tests done | Report compiled |
125
+
126
+ **Blocker Reporting** — immediately on errors (don't wait for next milestone):
127
+
128
+ ```javascript
129
+ mcp__maestro__team_msg({
130
+ operation: "log",
131
+ session_id: "<session_id>",
132
+ from: "<task_id>",
133
+ to: "coordinator",
134
+ type: "blocker",
135
+ summary: "[<task_id>] BLOCKED: <brief description>",
136
+ data: {
137
+ task_id: "<task_id>",
138
+ role: "<role>",
139
+ blocker_detail: "<what is blocking>",
140
+ severity: "high|medium",
141
+ attempted: "<what was tried>"
142
+ }
143
+ })
144
+ ```
145
+
146
+ **Completion Report** — after final report SendMessage:
147
+
148
+ ```javascript
149
+ mcp__maestro__team_msg({
150
+ operation: "log",
151
+ session_id: "<session_id>",
152
+ from: "<task_id>",
153
+ to: "coordinator",
154
+ type: "task_complete",
155
+ summary: "[<task_id>] Complete: <one-line result>",
156
+ data: {
157
+ task_id: "<task_id>",
158
+ role: "<role>",
159
+ status: "completed",
160
+ progress_pct: 100,
161
+ artifact: "<artifact_path>",
162
+ files_modified: []
163
+ }
164
+ })
165
+ ```
166
+
167
+ **Overhead Rule**: Max 3-4 milestone messages per task. Each summary < 200 chars. Only report at natural phase boundaries, not every minor step.
168
+
91
169
  ### 7. Report and Advance
92
170
 
93
171
  Determine report variant based on loop state:
@@ -0,0 +1,266 @@
1
+ ---
2
+ name: team-coordinate
3
+ description: Universal team coordination skill with dynamic role generation. Uses team-worker agent architecture with role-spec files. Only coordinator is built-in -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent. Beat/cadence model for orchestration. Triggers on "Team Coordinate ".
4
+ allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__team_msg(*)
5
+ ---
6
+
7
+ # Team Coordinate
8
+
9
+ Universal team coordination skill: analyze task -> generate role-specs -> dispatch -> execute -> deliver. Only the **coordinator** is built-in. All worker roles are **dynamically generated** as lightweight role-spec files and spawned via the `team-worker` agent.
10
+
11
+
12
+ ## Architecture
13
+
14
+ ```
15
+ +---------------------------------------------------+
16
+ | Skill(skill="team-coordinate") |
17
+ | args="task description" |
18
+ +-------------------+-------------------------------+
19
+ |
20
+ Orchestration Mode (auto -> coordinator)
21
+ |
22
+ Coordinator (built-in)
23
+ Phase 0-5 orchestration
24
+ |
25
+ +-------+-------+-------+-------+
26
+ v v v v v
27
+ [team-worker agents, each loaded with a dynamic role-spec]
28
+ (roles generated at runtime from task analysis)
29
+
30
+ CLI Tools (callable by any worker):
31
+ maestro cli --mode analysis - analysis and exploration
32
+ maestro cli --mode write - code generation and modification
33
+ ```
34
+
35
+ ## Shared Constants
36
+
37
+ | Constant | Value |
38
+ |----------|-------|
39
+ | Session prefix | `TC` |
40
+ | Session path | `.workflow/.team/TC-<slug>-<date>/` |
41
+ | Worker agent | `team-worker` |
42
+ | Message bus | `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` |
43
+ | CLI analysis | `maestro cli --mode analysis` |
44
+ | CLI write | `maestro cli --mode write` |
45
+ | Max roles | 5 |
46
+
47
+ ## Role Router
48
+
49
+ This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
50
+
51
+ ### Input Parsing
52
+
53
+ Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
54
+
55
+ ### Role Registry
56
+
57
+ Only coordinator is statically registered. All other roles are dynamic, stored as role-specs in session.
58
+
59
+ | Role | File | Type |
60
+ |------|------|------|
61
+ | coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator |
62
+ | (dynamic) | `<session>/role-specs/<role-name>.md` | runtime-generated role-spec |
63
+
64
+ ### CLI Tool Usage
65
+
66
+ Workers can use CLI tools for analysis and code operations:
67
+
68
+ | Tool | Purpose |
69
+ |------|---------|
70
+ | maestro cli --mode analysis | Analysis, exploration, pattern discovery |
71
+ | maestro cli --mode write | Code generation, modification, refactoring |
72
+
73
+ ### Dispatch
74
+
75
+ Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
76
+
77
+ ### Orchestration Mode
78
+
79
+ User just provides task description.
80
+
81
+ **Invocation**: `Skill(skill="team-coordinate", args="task description")`
82
+
83
+ **Lifecycle**:
84
+ ```
85
+ User provides task description
86
+ -> coordinator Phase 1: task analysis (detect capabilities, build dependency graph)
87
+ -> coordinator Phase 2: generate role-specs + initialize session
88
+ -> coordinator Phase 3: create task chain from dependency graph
89
+ -> coordinator Phase 4: spawn first batch workers (background) -> STOP
90
+ -> Worker executes -> SendMessage callback -> coordinator advances next step
91
+ -> Loop until pipeline complete -> Phase 5 report + completion action
92
+ ```
93
+
94
+ **User Commands** (wake paused coordinator):
95
+
96
+ | Command | Action |
97
+ |---------|--------|
98
+ | `check` / `status` | Output execution status graph, no advancement |
99
+ | `resume` / `continue` | Check worker states, advance next step |
100
+ | `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
101
+ | `feedback <text>` | Inject feedback into active pipeline |
102
+ | `improve [dimension]` | Auto-improve weakest quality dimension |
103
+
104
+ ---
105
+
106
+ ## Coordinator Spawn Template
107
+
108
+ ### v2 Worker Spawn (all roles)
109
+
110
+ When coordinator spawns workers, use `team-worker` agent with role-spec path:
111
+
112
+ ```
113
+ Agent({
114
+ subagent_type: "team-worker",
115
+ description: "Spawn <role> worker",
116
+ team_name: <team-name>,
117
+ name: "<role>",
118
+ run_in_background: true,
119
+ prompt: `## Role Assignment
120
+ role: <role>
121
+ role_spec: <session-folder>/role-specs/<role>.md
122
+ session: <session-folder>
123
+ session_id: <session-id>
124
+ team_name: <team-name>
125
+ requirement: <task-description>
126
+ inner_loop: <true|false>
127
+
128
+ ## Progress Milestones
129
+ session_id: <session-id>
130
+ Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
131
+ Report blockers immediately via team_msg type="blocker".
132
+ Report completion via team_msg type="task_complete" after final SendMessage.
133
+
134
+ Read role_spec file to load Phase 2-4 domain instructions.
135
+ Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
136
+ })
137
+ ```
138
+
139
+ **Inner Loop roles** (role has 2+ serial same-prefix tasks): Set `inner_loop: true`. The team-worker agent handles the loop internally.
140
+
141
+ **Single-task roles**: Set `inner_loop: false`.
142
+
143
+ ---
144
+
145
+ ## Completion Action
146
+
147
+ When pipeline completes (all tasks done), coordinator presents an interactive choice:
148
+
149
+ ```
150
+ AskUserQuestion({
151
+ questions: [{
152
+ question: "Team pipeline complete. What would you like to do?",
153
+ header: "Completion",
154
+ multiSelect: false,
155
+ options: [
156
+ { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
157
+ { label: "Keep Active", description: "Keep session for follow-up work" },
158
+ { label: "Export Results", description: "Export deliverables to target directory, then clean" }
159
+ ]
160
+ }]
161
+ })
162
+ ```
163
+
164
+ ### Action Handlers
165
+
166
+ | Choice | Steps |
167
+ |--------|-------|
168
+ | Archive & Clean | Update session status="completed" -> TeamDelete -> output final summary with artifact paths |
169
+ | Keep Active | Update session status="paused" -> output: "Resume with: Skill(skill='team-coordinate', args='resume')" |
170
+ | Export Results | AskUserQuestion(target path) -> copy artifacts to target -> Archive & Clean |
171
+
172
+ ---
173
+
174
+ ## Specs Reference
175
+
176
+ | Spec | Purpose |
177
+ |------|---------|
178
+ | [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
179
+ | [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
180
+ | [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
181
+ | [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
182
+
183
+ ---
184
+
185
+ ## Session Directory
186
+
187
+ ```
188
+ .workflow/.team/TC-<slug>-<date>/
189
+ +-- team-session.json # Session state + dynamic role registry
190
+ +-- task-analysis.json # Phase 1 output: capabilities, dependency graph
191
+ +-- role-specs/ # Dynamic role-spec definitions (generated Phase 2)
192
+ | +-- <role-1>.md # Lightweight: frontmatter + Phase 2-4 only
193
+ | +-- <role-2>.md
194
+ +-- artifacts/ # All MD deliverables from workers
195
+ | +-- <artifact>.md
196
+ +-- .msg/ # Team message bus + state
197
+ | +-- messages.jsonl # Message log
198
+ | +-- meta.json # Session metadata + cross-role state
199
+ +-- wisdom/ # Cross-task knowledge
200
+ | +-- learnings.md
201
+ | +-- decisions.md
202
+ | +-- issues.md
203
+ +-- explorations/ # Shared explore cache
204
+ | +-- cache-index.json
205
+ | +-- explore-<angle>.json
206
+ +-- discussions/ # Inline discuss records
207
+ | +-- <round>.md
208
+ ```
209
+
210
+ ### team-session.json Schema
211
+
212
+ ```json
213
+ {
214
+ "session_id": "TC-<slug>-<date>",
215
+ "task_description": "<original user input>",
216
+ "status": "active | paused | completed",
217
+ "team_name": "<team-name>",
218
+ "roles": [
219
+ {
220
+ "name": "<role-name>",
221
+ "prefix": "<PREFIX>",
222
+ "responsibility_type": "<type>",
223
+ "inner_loop": false,
224
+ "role_spec": "role-specs/<role-name>.md"
225
+ }
226
+ ],
227
+ "pipeline": {
228
+ "dependency_graph": {},
229
+ "tasks_total": 0,
230
+ "tasks_completed": 0
231
+ },
232
+ "active_workers": [],
233
+ "completed_tasks": [],
234
+ "completion_action": "interactive",
235
+ "created_at": "<timestamp>"
236
+ }
237
+ ```
238
+
239
+ ---
240
+
241
+ ## Session Resume
242
+
243
+ Coordinator supports `resume` / `continue` for interrupted sessions:
244
+
245
+ 1. Scan `.workflow/.team/TC-*/team-session.json` for active/paused sessions
246
+ 2. Multiple matches -> AskUserQuestion for selection
247
+ 3. Audit TaskList -> reconcile session state <-> task status
248
+ 4. Reset in_progress -> pending (interrupted tasks)
249
+ 5. Rebuild team and spawn needed workers only
250
+ 6. Create missing tasks, set dependencies via TaskUpdate({ addBlockedBy })
251
+ 7. Kick first executable task -> Phase 4 coordination loop
252
+
253
+ ---
254
+
255
+ ## Error Handling
256
+
257
+ | Scenario | Resolution |
258
+ |----------|------------|
259
+ | Unknown command | Error with available command list |
260
+ | Dynamic role-spec not found | Error, coordinator may need to regenerate |
261
+ | Command file not found | Fallback to inline execution |
262
+ | CLI tool fails | Worker proceeds with direct implementation, logs warning |
263
+ | Explore cache corrupt | Clear cache, re-explore |
264
+ | Fast-advance spawns wrong task | Coordinator reconciles on next callback |
265
+ | capability_gap reported | Coordinator generates new role-spec via handleAdapt |
266
+ | Completion action fails | Default to Keep Active, log warning |
@@ -0,0 +1,247 @@
1
+ # Command: analyze-task
2
+
3
+ ## Purpose
4
+
5
+ Parse user task description -> detect required capabilities -> build dependency graph -> design dynamic roles with role-spec metadata. Outputs structured task-analysis.json with frontmatter fields for role-spec generation.
6
+
7
+ ## CRITICAL CONSTRAINT
8
+
9
+ **TEXT-LEVEL analysis only. MUST NOT read source code or explore codebase.**
10
+
11
+ **Allowed:**
12
+ - Parse user task description text
13
+ - AskUserQuestion for clarification
14
+ - Keyword-to-capability mapping
15
+ - Write `task-analysis.json`
16
+
17
+ If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.
18
+
19
+ ## When to Use
20
+
21
+ | Trigger | Condition |
22
+ |---------|-----------|
23
+ | New task | Coordinator Phase 1 receives task description |
24
+ | Re-analysis | User provides revised requirements |
25
+ | Adapt | handleAdapt extends analysis for new capability |
26
+
27
+ ## Strategy
28
+
29
+ - **Delegation**: Inline execution (coordinator processes directly)
30
+ - **Mode**: Text-level analysis only (no codebase reading)
31
+ - **Output**: `<session>/task-analysis.json`
32
+
33
+ ## Phase 2: Context Loading
34
+
35
+ | Input | Source | Required |
36
+ |-------|--------|----------|
37
+ | Task description | User input from Phase 1 | Yes |
38
+ | Clarification answers | AskUserQuestion results (if any) | No |
39
+ | Session folder | From coordinator Phase 2 | Yes |
40
+
41
+ ## Phase 3: Task Analysis
42
+
43
+ ### Step 1: Signal Detection
44
+
45
+ Scan task description for capability keywords:
46
+
47
+ | Signal | Keywords | Capability | Prefix | Responsibility Type |
48
+ |--------|----------|------------|--------|---------------------|
49
+ | Research | investigate, explore, compare, survey, find, research, discover, benchmark, study | researcher | RESEARCH | orchestration |
50
+ | Writing | write, draft, document, article, report, blog, describe, explain, summarize, content | writer | DRAFT | code-gen (docs) |
51
+ | Coding | implement, build, code, fix, refactor, develop, create app, program, migrate, port | developer | IMPL | code-gen (code) |
52
+ | Design | design, architect, plan, structure, blueprint, model, schema, wireframe, layout | designer | DESIGN | orchestration |
53
+ | Analysis | analyze, review, audit, assess, evaluate, inspect, examine, diagnose, profile | analyst | ANALYSIS | read-only |
54
+ | Testing | test, verify, validate, QA, quality, check, assert, coverage, regression | tester | TEST | validation |
55
+ | Planning | plan, breakdown, organize, schedule, decompose, roadmap, strategy, prioritize | planner | PLAN | orchestration |
56
+
57
+ **Multi-match**: A task may trigger multiple capabilities.
58
+
59
+ **No match**: Default to a single `general` capability with `TASK` prefix.
60
+
61
+ ### Step 2: Artifact Inference
62
+
63
+ Each capability produces default output artifacts:
64
+
65
+ | Capability | Default Artifact | Format |
66
+ |------------|-----------------|--------|
67
+ | researcher | Research findings | `<session>/artifacts/research-findings.md` |
68
+ | writer | Written document(s) | `<session>/artifacts/<doc-name>.md` |
69
+ | developer | Code implementation | Source files + `<session>/artifacts/implementation-summary.md` |
70
+ | designer | Design document | `<session>/artifacts/design-spec.md` |
71
+ | analyst | Analysis report | `<session>/artifacts/analysis-report.md` |
72
+ | tester | Test results | `<session>/artifacts/test-report.md` |
73
+ | planner | Execution plan | `<session>/artifacts/execution-plan.md` |
74
+
75
+ ### Step 2.5: Key File Inference
76
+
77
+ For each task, infer relevant files based on capability type and task keywords:
78
+
79
+ | Capability | File Inference Strategy |
80
+ |------------|------------------------|
81
+ | researcher | Extract domain keywords → map to likely directories (e.g., "auth" → `src/auth/**`, `middleware/auth.ts`) |
82
+ | developer | Extract feature/module keywords → map to source files (e.g., "payment" → `src/payments/**`, `types/payment.ts`) |
83
+ | designer | Look for architecture/config keywords → map to config/schema files |
84
+ | analyst | Extract target keywords → map to files under analysis |
85
+ | tester | Extract test target keywords → map to source + test files |
86
+ | writer | Extract documentation target → map to relevant source files for context |
87
+ | planner | No specific files (planning is abstract) |
88
+
89
+ **Inference rules:**
90
+ - Extract nouns and verbs from task description
91
+ - Match against common directory patterns (src/, lib/, components/, services/, utils/)
92
+ - Include related type definition files (types/, *.d.ts)
93
+ - For "fix bug" tasks, include error-prone areas (error handlers, validation)
94
+ - For "implement feature" tasks, include similar existing features as reference
95
+
96
+ ### Step 3: Dependency Graph Construction
97
+
98
+ Build a DAG of work streams using natural ordering tiers:
99
+
100
+ | Tier | Capabilities | Description |
101
+ |------|-------------|-------------|
102
+ | 0 | researcher, planner | Knowledge gathering / planning |
103
+ | 1 | designer | Design (requires context from tier 0 if present) |
104
+ | 2 | writer, developer | Creation (requires design/plan if present) |
105
+ | 3 | analyst, tester | Validation (requires artifacts to validate) |
106
+
107
+ ### Step 4: Complexity Scoring
108
+
109
+ | Factor | Weight | Condition |
110
+ |--------|--------|-----------|
111
+ | Capability count | +1 each | Number of distinct capabilities |
112
+ | Cross-domain factor | +2 | Capabilities span 3+ tiers |
113
+ | Parallel tracks | +1 each | Independent parallel work streams |
114
+ | Serial depth | +1 per level | Longest dependency chain length |
115
+
116
+ | Total Score | Complexity | Role Limit |
117
+ |-------------|------------|------------|
118
+ | 1-3 | Low | 1-2 roles |
119
+ | 4-6 | Medium | 2-3 roles |
120
+ | 7+ | High | 3-5 roles |
121
+
122
+ ### Step 5: Role Minimization
123
+
124
+ Apply merging rules to reduce role count (cap at 5).
125
+
126
+ ### Step 6: Role-Spec Metadata Assignment
127
+
128
+ For each role, determine frontmatter and generation hints:
129
+
130
+ | Field | Derivation |
131
+ |-------|------------|
132
+ | `prefix` | From capability prefix (e.g., RESEARCH, DRAFT, IMPL) |
133
+ | `inner_loop` | `true` if role has 2+ serial same-prefix tasks |
134
+ | `CLI tools` | Suggested, not mandatory — coordinator may adjust based on task needs |
135
+ | `pattern_hint` | Reference pattern name from role-spec-template (research/document/code/analysis/validation) — guides coordinator's Phase 2-4 composition, NOT a rigid template selector |
136
+ | `output_type` | `artifact` (new files in session/artifacts/) / `codebase` (modify existing project files) / `mixed` (both) — determines verification strategy in Behavioral Traits |
137
+ | `message_types.success` | `<prefix>_complete` |
138
+ | `message_types.error` | `error` |
139
+
140
+ **output_type derivation**:
141
+
142
+ | Task Signal | output_type | Example |
143
+ |-------------|-------------|---------|
144
+ | "write report", "analyze", "research" | `artifact` | New analysis-report.md in session |
145
+ | "update docs", "modify code", "fix bug" | `codebase` | Modify existing project files |
146
+ | "implement feature + write summary" | `mixed` | Code changes + implementation summary |
147
+
148
+ ## Phase 4: Output
149
+
150
+ Write `<session-folder>/task-analysis.json`:
151
+
152
+ ```json
153
+ {
154
+ "task_description": "<original user input>",
155
+ "capabilities": [
156
+ {
157
+ "name": "researcher",
158
+ "prefix": "RESEARCH",
159
+ "responsibility_type": "orchestration",
160
+ "tasks": [
161
+ {
162
+ "id": "RESEARCH-001",
163
+ "goal": "What this task achieves and why",
164
+ "steps": [
165
+ "step 1: specific action with clear verb",
166
+ "step 2: specific action with clear verb",
167
+ "step 3: specific action with clear verb"
168
+ ],
169
+ "key_files": [
170
+ "src/path/to/relevant.ts",
171
+ "src/path/to/other.ts"
172
+ ],
173
+ "upstream_artifacts": [],
174
+ "success_criteria": "Measurable completion condition",
175
+ "constraints": "Scope limits, focus areas"
176
+ }
177
+ ],
178
+ "artifacts": ["research-findings.md"]
179
+ }
180
+ ],
181
+ "dependency_graph": {
182
+ "RESEARCH-001": [],
183
+ "DRAFT-001": ["RESEARCH-001"],
184
+ "ANALYSIS-001": ["DRAFT-001"]
185
+ },
186
+ "roles": [
187
+ {
188
+ "name": "researcher",
189
+ "prefix": "RESEARCH",
190
+ "responsibility_type": "orchestration",
191
+ "task_count": 1,
192
+ "inner_loop": false,
193
+ "role_spec_metadata": {
194
+ "CLI tools": ["explore"],
195
+ "pattern_hint": "research",
196
+ "output_type": "artifact",
197
+ "message_types": {
198
+ "success": "research_complete",
199
+ "error": "error"
200
+ }
201
+ }
202
+ }
203
+ ],
204
+ "complexity": {
205
+ "capability_count": 2,
206
+ "cross_domain_factor": false,
207
+ "parallel_tracks": 0,
208
+ "serial_depth": 2,
209
+ "total_score": 3,
210
+ "level": "low"
211
+ },
212
+ "needs_research": false,
213
+ "artifacts": [
214
+ { "name": "research-findings.md", "producer": "researcher", "path": "artifacts/research-findings.md" }
215
+ ]
216
+ }
217
+ ```
218
+
219
+ ## Complexity Interpretation
220
+
221
+ **CRITICAL**: Complexity score is for **role design optimization**, NOT for skipping team workflow.
222
+
223
+ | Complexity | Team Structure | Coordinator Action |
224
+ |------------|----------------|-------------------|
225
+ | Low (1-2 roles) | Minimal team | Generate 1-2 role-specs, create team, spawn workers |
226
+ | Medium (2-3 roles) | Standard team | Generate role-specs, create team, spawn workers |
227
+ | High (3-5 roles) | Full team | Generate role-specs, create team, spawn workers |
228
+
229
+ **All complexity levels use team-worker architecture**:
230
+ - Single-role tasks still spawn team-worker agent
231
+ - Coordinator NEVER executes task work directly
232
+ - Team infrastructure provides session management, message bus, fast-advance
233
+
234
+ **Purpose of complexity score**:
235
+ - ✅ Determine optimal role count (merge vs separate)
236
+ - ✅ Guide dependency graph design
237
+ - ✅ Inform user about task scope
238
+ - ❌ NOT for deciding whether to use team workflow
239
+
240
+ ## Error Handling
241
+
242
+ | Scenario | Resolution |
243
+ |----------|------------|
244
+ | No capabilities detected | Default to single `general` role with TASK prefix |
245
+ | Circular dependency in graph | Break cycle at lowest-tier edge, warn |
246
+ | Task description too vague | Return minimal analysis, coordinator will AskUserQuestion |
247
+ | All capabilities merge into one | Valid -- single-role execution via team-worker |