maestro-flow 0.3.28 → 0.3.29
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.
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: maestro-ralph-execute
|
|
3
|
+
description: Single-step skill executor — spawned by maestro-ralph via CSV, reads ralph session context, executes one skill command, reports result
|
|
4
|
+
argument-hint: "<skill_call>"
|
|
5
|
+
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<purpose>
|
|
9
|
+
Worker agent spawned by maestro-ralph via `spawn_agents_on_csv`.
|
|
10
|
+
Each invocation executes exactly ONE skill command and reports the result.
|
|
11
|
+
|
|
12
|
+
Receives `skill_call` (e.g. `$maestro-plan 1`) from the wave CSV.
|
|
13
|
+
Before execution, reads the ralph session status.json to obtain execution context
|
|
14
|
+
(phase, milestone, intent, artifact paths) — uses this to enrich skill args when needed.
|
|
15
|
+
|
|
16
|
+
Writes back **nothing** to status.json — ralph coordinator reads the result CSV and updates status.json itself.
|
|
17
|
+
Decision nodes never arrive here — ralph processes them directly.
|
|
18
|
+
</purpose>
|
|
19
|
+
|
|
20
|
+
<context>
|
|
21
|
+
**From CSV row:**
|
|
22
|
+
- `skill_call` — full skill invocation string (e.g. `$maestro-plan 1`, `$quality-review 1`)
|
|
23
|
+
- `topic` — brief description of what this step does
|
|
24
|
+
|
|
25
|
+
**The skill_call format:** `$<skill-name> <args>`
|
|
26
|
+
|
|
27
|
+
**Ralph session status.json** — located at `.workflow/.ralph/ralph-*/status.json` (latest running session).
|
|
28
|
+
Read-only for this agent. Provides:
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"id": "ralph-{YYYYMMDD-HHmmss}",
|
|
33
|
+
"intent": "用户原始输入",
|
|
34
|
+
"status": "running",
|
|
35
|
+
"phase": 1,
|
|
36
|
+
"milestone": "MVP",
|
|
37
|
+
"lifecycle_position": "plan",
|
|
38
|
+
"context": {
|
|
39
|
+
"plan_dir": ".workflow/scratch/...",
|
|
40
|
+
"analysis_dir": ".workflow/scratch/...",
|
|
41
|
+
"brainstorm_dir": null
|
|
42
|
+
},
|
|
43
|
+
"steps": [...],
|
|
44
|
+
"current_step": 3
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**Project state** — `.workflow/state.json` provides artifact registry:
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"current_milestone": "MVP",
|
|
52
|
+
"artifacts": [
|
|
53
|
+
{ "id": "ANL-001", "type": "analyze", "phase": 1,
|
|
54
|
+
"path": "phases/01-auth-multi-tenant", "status": "completed" }
|
|
55
|
+
]
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
</context>
|
|
59
|
+
|
|
60
|
+
<execution>
|
|
61
|
+
|
|
62
|
+
## Step 1: Parse skill_call
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
Extract from skill_call:
|
|
66
|
+
skill_name = text between $ and first space (e.g. "maestro-plan")
|
|
67
|
+
skill_args = remainder after first space (e.g. "1")
|
|
68
|
+
|
|
69
|
+
If skill_call is empty or malformed:
|
|
70
|
+
→ report_agent_job_result({ status: "failed", error: "Invalid skill_call" })
|
|
71
|
+
→ End.
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Step 2: Load ralph session context
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
Glob .workflow/.ralph/ralph-*/status.json
|
|
78
|
+
Filter: status == "running"
|
|
79
|
+
Sort by created_at DESC, take first
|
|
80
|
+
→ ralph_session
|
|
81
|
+
|
|
82
|
+
If not found: proceed with skill_args as-is (standalone execution)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Extract from ralph_session:
|
|
86
|
+
- `phase` — current phase number
|
|
87
|
+
- `milestone` — current milestone name
|
|
88
|
+
- `intent` — user's original input text
|
|
89
|
+
- `context.plan_dir` — latest plan artifact directory
|
|
90
|
+
- `context.analysis_dir` — latest analysis artifact directory
|
|
91
|
+
- `context.brainstorm_dir` — brainstorm output directory
|
|
92
|
+
|
|
93
|
+
Also read `.workflow/state.json` for artifact registry when needed.
|
|
94
|
+
|
|
95
|
+
## Step 3: Enrich skill args
|
|
96
|
+
|
|
97
|
+
If skill_args contain unresolved context or are insufficient, enrich based on skill type:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
Per-skill enrichment (when args need context from session):
|
|
101
|
+
|
|
102
|
+
maestro-brainstorm:
|
|
103
|
+
If args empty → args = '"{intent}"'
|
|
104
|
+
|
|
105
|
+
maestro-roadmap:
|
|
106
|
+
If args empty → args = '"{intent}"'
|
|
107
|
+
|
|
108
|
+
maestro-analyze:
|
|
109
|
+
If args is just a number → keep as phase number
|
|
110
|
+
If args empty → args = '{phase}' or '"{intent}"'
|
|
111
|
+
|
|
112
|
+
maestro-plan:
|
|
113
|
+
If args is number → keep as phase
|
|
114
|
+
If needs artifact dir → resolve latest analyze artifact:
|
|
115
|
+
state.json.artifacts[] → filter(type=="analyze", phase==session.phase) → latest → --dir .workflow/scratch/{path}
|
|
116
|
+
|
|
117
|
+
maestro-execute:
|
|
118
|
+
If args is number → keep as phase
|
|
119
|
+
If needs artifact dir → resolve latest plan artifact:
|
|
120
|
+
state.json.artifacts[] → filter(type=="plan", phase==session.phase) → latest → --dir .workflow/scratch/{path}
|
|
121
|
+
|
|
122
|
+
quality-debug:
|
|
123
|
+
Read previous step's result artifacts for gap/failure context
|
|
124
|
+
If from verify: append gap summary from verification.json
|
|
125
|
+
If from test: append --from-uat {phase}
|
|
126
|
+
If from business-test: append --from-business-test {phase}
|
|
127
|
+
|
|
128
|
+
quality-* (review, test, test-gen, business-test):
|
|
129
|
+
If args empty → args = '{phase}'
|
|
130
|
+
|
|
131
|
+
maestro-verify, maestro-milestone-audit, maestro-milestone-complete:
|
|
132
|
+
If args empty → args = '{phase}' (or empty for milestone-*)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Step 4: Execute skill
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
Read .codex/skills/{skill_name}/SKILL.md to understand the skill
|
|
139
|
+
Execute the skill with enriched skill_args as $ARGUMENTS
|
|
140
|
+
|
|
141
|
+
Track:
|
|
142
|
+
- Artifact paths produced (scratch dirs, plan.json, verification.json, etc.)
|
|
143
|
+
- Session IDs created (WFS-*, ANL-*, PLN-*, etc.)
|
|
144
|
+
- Success/failure status
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## Step 5: Report result
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
report_agent_job_result({
|
|
151
|
+
status: "completed" | "failed",
|
|
152
|
+
skill_call: "{original_skill_call}",
|
|
153
|
+
summary: "one-line result description",
|
|
154
|
+
artifacts: "comma-separated artifact paths or empty string",
|
|
155
|
+
error: "failure reason or empty string"
|
|
156
|
+
})
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**Artifact paths to report** (for ralph's barrier analysis):
|
|
160
|
+
| Skill | Report |
|
|
161
|
+
|-------|--------|
|
|
162
|
+
| maestro-analyze | scratch dir path containing context.md |
|
|
163
|
+
| maestro-plan | scratch dir path containing plan.json |
|
|
164
|
+
| maestro-execute | scratch dir path containing .summaries/ |
|
|
165
|
+
| maestro-brainstorm | .brainstorming/ output dir |
|
|
166
|
+
| maestro-roadmap | roadmap.md path |
|
|
167
|
+
| maestro-verify | verification.json path |
|
|
168
|
+
| quality-review | review.json path |
|
|
169
|
+
| quality-test | uat.md path |
|
|
170
|
+
| quality-business-test | business test output path |
|
|
171
|
+
| Others | empty or relevant output path |
|
|
172
|
+
|
|
173
|
+
</execution>
|
|
174
|
+
|
|
175
|
+
<error_codes>
|
|
176
|
+
| Code | Severity | Description | Recovery |
|
|
177
|
+
|------|----------|-------------|----------|
|
|
178
|
+
| E001 | error | skill_call parsing failed | Report failed |
|
|
179
|
+
| E002 | error | Skill SKILL.md not found | Report failed |
|
|
180
|
+
| E003 | error | Skill execution error | Report failed with error details |
|
|
181
|
+
| E004 | error | Ralph session not found (standalone mode) | Execute with args as-is |
|
|
182
|
+
| W001 | warning | Artifact dir not found for enrichment | Use args as-is, warn in summary |
|
|
183
|
+
</error_codes>
|
|
184
|
+
|
|
185
|
+
<success_criteria>
|
|
186
|
+
- [ ] skill_call correctly parsed into skill_name + skill_args
|
|
187
|
+
- [ ] Ralph session status.json read for context (phase, intent, artifact paths)
|
|
188
|
+
- [ ] Args enriched per-skill when context needed (brainstorm→intent, plan→dir, debug→gaps)
|
|
189
|
+
- [ ] Skill executed via its own SKILL.md
|
|
190
|
+
- [ ] Artifact paths accurately reported for ralph's barrier analysis
|
|
191
|
+
- [ ] status.json NEVER written by this agent
|
|
192
|
+
- [ ] Result reported via report_agent_job_result
|
|
193
|
+
</success_criteria>
|