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.
- package/.claude/agents/team-supervisor.md +18 -8
- package/.claude/agents/team-worker.md +78 -0
- package/.claude/skills/team-coordinate/SKILL.md +266 -0
- package/.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md +247 -0
- package/.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md +131 -0
- package/.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md +358 -0
- package/.claude/skills/team-coordinate/roles/coordinator/role.md +363 -0
- package/.claude/skills/team-coordinate/specs/knowledge-transfer.md +111 -0
- package/.claude/skills/team-coordinate/specs/pipelines.md +97 -0
- package/.claude/skills/team-coordinate/specs/quality-gates.md +112 -0
- package/.claude/skills/team-coordinate/specs/role-spec-template.md +192 -0
- package/.claude/skills/team-executor/SKILL.md +189 -0
- package/.claude/skills/team-executor/roles/executor/commands/monitor.md +239 -0
- package/.claude/skills/team-executor/roles/executor/role.md +171 -0
- package/.claude/skills/team-executor/specs/session-schema.md +264 -0
- package/.claude/skills/team-lifecycle-v4/SKILL.md +209 -0
- package/.claude/skills/team-lifecycle-v4/roles/analyst/role.md +78 -0
- package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/analyze.md +56 -0
- package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +56 -0
- package/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +157 -0
- package/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md +130 -0
- package/.claude/skills/team-lifecycle-v4/roles/executor/commands/fix.md +35 -0
- package/.claude/skills/team-lifecycle-v4/roles/executor/commands/implement.md +62 -0
- package/.claude/skills/team-lifecycle-v4/roles/executor/role.md +67 -0
- package/.claude/skills/team-lifecycle-v4/roles/planner/role.md +76 -0
- package/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/review-code.md +34 -0
- package/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md +44 -0
- package/.claude/skills/team-lifecycle-v4/roles/reviewer/role.md +69 -0
- package/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md +192 -0
- package/.claude/skills/team-lifecycle-v4/roles/tester/role.md +87 -0
- package/.claude/skills/team-lifecycle-v4/roles/writer/role.md +95 -0
- package/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md +112 -0
- package/.claude/skills/team-lifecycle-v4/specs/pipelines.md +125 -0
- package/.claude/skills/team-lifecycle-v4/specs/quality-gates.md +130 -0
- package/.claude/skills/team-lifecycle-v4/templates/architecture.md +254 -0
- package/.claude/skills/team-lifecycle-v4/templates/epics.md +196 -0
- package/.claude/skills/team-lifecycle-v4/templates/product-brief.md +133 -0
- package/.claude/skills/team-lifecycle-v4/templates/requirements.md +224 -0
- package/.claude/skills/team-quality-assurance/SKILL.md +147 -0
- package/.claude/skills/team-quality-assurance/roles/analyst/role.md +80 -0
- package/.claude/skills/team-quality-assurance/roles/coordinator/commands/analyze.md +72 -0
- package/.claude/skills/team-quality-assurance/roles/coordinator/commands/dispatch.md +111 -0
- package/.claude/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +250 -0
- package/.claude/skills/team-quality-assurance/roles/coordinator/role.md +143 -0
- package/.claude/skills/team-quality-assurance/roles/executor/role.md +66 -0
- package/.claude/skills/team-quality-assurance/roles/generator/role.md +68 -0
- package/.claude/skills/team-quality-assurance/roles/scout/role.md +67 -0
- package/.claude/skills/team-quality-assurance/roles/strategist/role.md +71 -0
- package/.claude/skills/team-quality-assurance/specs/pipelines.md +115 -0
- package/.claude/skills/team-quality-assurance/specs/team-config.json +131 -0
- package/.claude/skills/team-review/SKILL.md +147 -0
- package/.claude/skills/team-review/roles/coordinator/commands/analyze.md +71 -0
- package/.claude/skills/team-review/roles/coordinator/commands/dispatch.md +91 -0
- package/.claude/skills/team-review/roles/coordinator/commands/monitor.md +224 -0
- package/.claude/skills/team-review/roles/coordinator/role.md +132 -0
- package/.claude/skills/team-review/roles/fixer/role.md +76 -0
- package/.claude/skills/team-review/roles/reviewer/role.md +68 -0
- package/.claude/skills/team-review/roles/scanner/role.md +71 -0
- package/.claude/skills/team-review/specs/dimensions.md +82 -0
- package/.claude/skills/team-review/specs/finding-schema.json +82 -0
- package/.claude/skills/team-review/specs/pipelines.md +102 -0
- package/.claude/skills/team-review/specs/team-config.json +27 -0
- package/.claude/skills/team-tech-debt/SKILL.md +128 -0
- package/.claude/skills/team-tech-debt/roles/assessor/role.md +69 -0
- package/.claude/skills/team-tech-debt/roles/coordinator/commands/analyze.md +47 -0
- package/.claude/skills/team-tech-debt/roles/coordinator/commands/dispatch.md +156 -0
- package/.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md +209 -0
- package/.claude/skills/team-tech-debt/roles/coordinator/role.md +123 -0
- package/.claude/skills/team-tech-debt/roles/executor/role.md +76 -0
- package/.claude/skills/team-tech-debt/roles/planner/role.md +69 -0
- package/.claude/skills/team-tech-debt/roles/scanner/role.md +82 -0
- package/.claude/skills/team-tech-debt/roles/validator/role.md +78 -0
- package/.claude/skills/team-tech-debt/specs/pipelines.md +47 -0
- package/.claude/skills/team-tech-debt/specs/team-config.json +129 -0
- package/.claude/skills/team-testing/SKILL.md +143 -0
- package/.claude/skills/team-testing/roles/analyst/role.md +95 -0
- package/.claude/skills/team-testing/roles/coordinator/commands/analyze.md +70 -0
- package/.claude/skills/team-testing/roles/coordinator/commands/dispatch.md +108 -0
- package/.claude/skills/team-testing/roles/coordinator/commands/monitor.md +257 -0
- package/.claude/skills/team-testing/roles/coordinator/role.md +134 -0
- package/.claude/skills/team-testing/roles/executor/role.md +99 -0
- package/.claude/skills/team-testing/roles/generator/role.md +98 -0
- package/.claude/skills/team-testing/roles/strategist/role.md +83 -0
- package/.claude/skills/team-testing/specs/pipelines.md +101 -0
- package/.claude/skills/team-testing/specs/team-config.json +93 -0
- package/.codex/skills/maestro-coordinate/SKILL.md +6 -6
- package/.codex/skills/maestro-overlay/SKILL.md +1 -3
- package/.codex/skills/manage-issue-analyze/SKILL.md +2 -2
- package/.codex/skills/quality-retrospective/SKILL.md +30 -31
- package/.codex/skills/team-coordinate/SKILL.md +16 -18
- package/.codex/skills/team-coordinate/roles/coordinator/commands/monitor.md +50 -7
- package/.codex/skills/team-coordinate/roles/coordinator/role.md +4 -4
- package/.codex/skills/team-coordinate/specs/knowledge-transfer.md +2 -0
- package/.codex/skills/team-executor/SKILL.md +11 -13
- package/.codex/skills/team-executor/roles/executor/commands/monitor.md +47 -11
- package/.codex/skills/team-lifecycle-v4/SKILL.md +27 -33
- package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md +94 -0
- package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +1 -1
- package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +94 -27
- package/.codex/skills/team-lifecycle-v4/roles/coordinator/role.md +12 -14
- package/.codex/skills/team-lifecycle-v4/roles/supervisor/role.md +1 -1
- package/.codex/skills/team-lifecycle-v4/specs/knowledge-transfer.md +69 -1
- package/.codex/skills/team-quality-assurance/SKILL.md +14 -16
- package/.codex/skills/team-quality-assurance/roles/coordinator/commands/monitor.md +60 -11
- package/.codex/skills/team-quality-assurance/roles/coordinator/role.md +4 -4
- package/.codex/skills/team-review/SKILL.md +14 -16
- package/.codex/skills/team-review/roles/coordinator/commands/monitor.md +47 -10
- package/.codex/skills/team-review/roles/coordinator/role.md +4 -4
- package/.codex/skills/team-tech-debt/SKILL.md +13 -15
- package/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md +51 -12
- package/.codex/skills/team-tech-debt/roles/coordinator/role.md +4 -4
- package/.codex/skills/team-testing/SKILL.md +15 -17
- package/.codex/skills/team-testing/roles/coordinator/commands/monitor.md +51 -13
- package/.codex/skills/team-testing/roles/coordinator/role.md +4 -4
- package/dashboard/dist-server/dashboard/src/server/agents/stream-json-adapter.js +4 -0
- package/dashboard/dist-server/dashboard/src/server/agents/stream-json-adapter.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/routes/cli-history.js +8 -1
- package/dashboard/dist-server/dashboard/src/server/routes/cli-history.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/server/routes/mcp.js +20 -0
- package/dashboard/dist-server/dashboard/src/server/routes/mcp.js.map +1 -1
- package/dashboard/dist-server/dashboard/src/shared/constants.d.ts +1 -0
- package/dashboard/dist-server/dashboard/src/shared/constants.js +1 -0
- package/dashboard/dist-server/dashboard/src/shared/constants.js.map +1 -1
- package/dashboard/dist-server/src/agents/cli-history-store.js +21 -3
- package/dashboard/dist-server/src/agents/cli-history-store.js.map +1 -1
- package/dist/src/agents/cli-history-store.d.ts.map +1 -1
- package/dist/src/agents/cli-history-store.js +21 -3
- package/dist/src/agents/cli-history-store.js.map +1 -1
- package/dist/src/commands/cli.d.ts.map +1 -1
- package/dist/src/commands/cli.js +20 -8
- package/dist/src/commands/cli.js.map +1 -1
- package/dist/src/commands/uninstall-ui/UninstallFlow.d.ts.map +1 -1
- package/dist/src/commands/uninstall-ui/UninstallFlow.js +5 -4
- package/dist/src/commands/uninstall-ui/UninstallFlow.js.map +1 -1
- package/dist/src/commands/uninstall.js +1 -1
- package/dist/src/commands/uninstall.js.map +1 -1
- package/dist/src/core/manifest.d.ts.map +1 -1
- package/dist/src/core/manifest.js +9 -1
- package/dist/src/core/manifest.js.map +1 -1
- package/package.json +1 -1
- 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. **
|
|
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
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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 |
|