maestro-flow 0.3.27 → 0.3.29

package/.codex/skills/maestro-ralph-execute/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: maestro-ralph-execute
+description: Single-step skill executor — spawned by maestro-ralph via CSV, reads ralph session context, executes one skill command, reports result
+argument-hint: "<skill_call>"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Worker agent spawned by maestro-ralph via `spawn_agents_on_csv`.
+Each invocation executes exactly ONE skill command and reports the result.
+
+Receives `skill_call` (e.g. `$maestro-plan 1`) from the wave CSV.
+Before execution, reads the ralph session status.json to obtain execution context
+(phase, milestone, intent, artifact paths) — uses this to enrich skill args when needed.
+
+Writes back **nothing** to status.json — ralph coordinator reads the result CSV and updates status.json itself.
+Decision nodes never arrive here — ralph processes them directly.
+</purpose>
+
+<context>
+**From CSV row:**
+- `skill_call` — full skill invocation string (e.g. `$maestro-plan 1`, `$quality-review 1`)
+- `topic` — brief description of what this step does
+
+**The skill_call format:** `$<skill-name> <args>`
+
+**Ralph session status.json** — located at `.workflow/.ralph/ralph-*/status.json` (latest running session).
+Read-only for this agent. Provides:
+
+```json
+{
+  "id": "ralph-{YYYYMMDD-HHmmss}",
+  "intent": "用户原始输入",
+  "status": "running",
+  "phase": 1,
+  "milestone": "MVP",
+  "lifecycle_position": "plan",
+  "context": {
+    "plan_dir": ".workflow/scratch/...",
+    "analysis_dir": ".workflow/scratch/...",
+    "brainstorm_dir": null
+  },
+  "steps": [...],
+  "current_step": 3
+}
+```
+
+**Project state** — `.workflow/state.json` provides artifact registry:
+```json
+{
+  "current_milestone": "MVP",
+  "artifacts": [
+    { "id": "ANL-001", "type": "analyze", "phase": 1,
+      "path": "phases/01-auth-multi-tenant", "status": "completed" }
+  ]
+}
+```
+</context>
+
+<execution>
+
+## Step 1: Parse skill_call
+
+```
+Extract from skill_call:
+  skill_name = text between $ and first space (e.g. "maestro-plan")
+  skill_args = remainder after first space (e.g. "1")
+
+If skill_call is empty or malformed:
+  → report_agent_job_result({ status: "failed", error: "Invalid skill_call" })
+  → End.
+```
+
+## Step 2: Load ralph session context
+
+```
+Glob .workflow/.ralph/ralph-*/status.json
+  Filter: status == "running"
+  Sort by created_at DESC, take first
+  → ralph_session
+
+If not found: proceed with skill_args as-is (standalone execution)
+```
+
+Extract from ralph_session:
+- `phase` — current phase number
+- `milestone` — current milestone name
+- `intent` — user's original input text
+- `context.plan_dir` — latest plan artifact directory
+- `context.analysis_dir` — latest analysis artifact directory
+- `context.brainstorm_dir` — brainstorm output directory
+
+Also read `.workflow/state.json` for artifact registry when needed.
+
+## Step 3: Enrich skill args
+
+If skill_args contain unresolved context or are insufficient, enrich based on skill type:
+
+```
+Per-skill enrichment (when args need context from session):
+
+maestro-brainstorm:
+  If args empty → args = '"{intent}"'
+
+maestro-roadmap:
+  If args empty → args = '"{intent}"'
+
+maestro-analyze:
+  If args is just a number → keep as phase number
+  If args empty → args = '{phase}' or '"{intent}"'
+
+maestro-plan:
+  If args is number → keep as phase
+  If needs artifact dir → resolve latest analyze artifact:
+    state.json.artifacts[] → filter(type=="analyze", phase==session.phase) → latest → --dir .workflow/scratch/{path}
+
+maestro-execute:
+  If args is number → keep as phase
+  If needs artifact dir → resolve latest plan artifact:
+    state.json.artifacts[] → filter(type=="plan", phase==session.phase) → latest → --dir .workflow/scratch/{path}
+
+quality-debug:
+  Read previous step's result artifacts for gap/failure context
+  If from verify: append gap summary from verification.json
+  If from test: append --from-uat {phase}
+  If from business-test: append --from-business-test {phase}
+
+quality-* (review, test, test-gen, business-test):
+  If args empty → args = '{phase}'
+
+maestro-verify, maestro-milestone-audit, maestro-milestone-complete:
+  If args empty → args = '{phase}' (or empty for milestone-*)
+```
+
+## Step 4: Execute skill
+
+```
+Read .codex/skills/{skill_name}/SKILL.md to understand the skill
+Execute the skill with enriched skill_args as $ARGUMENTS
+
+Track:
+  - Artifact paths produced (scratch dirs, plan.json, verification.json, etc.)
+  - Session IDs created (WFS-*, ANL-*, PLN-*, etc.)
+  - Success/failure status
+```
+
+## Step 5: Report result
+
+```
+report_agent_job_result({
+  status: "completed" | "failed",
+  skill_call: "{original_skill_call}",
+  summary: "one-line result description",
+  artifacts: "comma-separated artifact paths or empty string",
+  error: "failure reason or empty string"
+})
+```
+
+**Artifact paths to report** (for ralph's barrier analysis):
+| Skill | Report |
+|-------|--------|
+| maestro-analyze | scratch dir path containing context.md |
+| maestro-plan | scratch dir path containing plan.json |
+| maestro-execute | scratch dir path containing .summaries/ |
+| maestro-brainstorm | .brainstorming/ output dir |
+| maestro-roadmap | roadmap.md path |
+| maestro-verify | verification.json path |
+| quality-review | review.json path |
+| quality-test | uat.md path |
+| quality-business-test | business test output path |
+| Others | empty or relevant output path |
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | skill_call parsing failed | Report failed |
+| E002 | error | Skill SKILL.md not found | Report failed |
+| E003 | error | Skill execution error | Report failed with error details |
+| E004 | error | Ralph session not found (standalone mode) | Execute with args as-is |
+| W001 | warning | Artifact dir not found for enrichment | Use args as-is, warn in summary |
+</error_codes>
+
+<success_criteria>
+- [ ] skill_call correctly parsed into skill_name + skill_args
+- [ ] Ralph session status.json read for context (phase, intent, artifact paths)
+- [ ] Args enriched per-skill when context needed (brainstorm→intent, plan→dir, debug→gaps)
+- [ ] Skill executed via its own SKILL.md
+- [ ] Artifact paths accurately reported for ralph's barrier analysis
+- [ ] status.json NEVER written by this agent
+- [ ] Result reported via report_agent_job_result
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.27",
+  "version": "0.3.29",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/workflows/maestro-chain-execute.md

@@ -3,10 +3,11 @@
 Upgraded version of maestro's original direct execution strategy.
 Reads session status.json, loops through steps with per-step engine selection,
 context propagation, post-step Gemini analysis, and error handling.
-Tracks all progress via status.json (the JSON file created during selection).
+Dual-track progress: status.json (persistence + resume) and TodoWrite (UI visibility).
 
 **Prerequisites:**
 - Session directory with valid status.json (status: "running", pending steps)
+- TodoWrite initialized by selection workflow (Step 3h) with `MAESTRO:{chain_name}:` prefix
 - $SESSION_PATH passed from maestro.md dispatch
 
 ## Step 1: Load Session
@@ -19,6 +20,18 @@ Set `$STEP_INDEX` = `current_step` (first pending step).
 
 Validate: `status == "running"` and at least one pending step exists.
 
+**TodoWrite sync (resume mode):** If TodoWrite has no `MAESTRO:{chain_name}:` entries (e.g., fresh context after `/maestro -c`), rebuild from status.json:
+
+```javascript
+const todos = steps.map((step, i) => ({
+  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
+  status: step.status === 'completed' ? 'completed'
+        : i === $STEP_INDEX ? 'in_progress'
+        : 'pending'
+}));
+TodoWrite({ todos });
+```
+
 Display banner:
 
 ```
@@ -127,15 +140,35 @@ CLI: capture `exec_id` from stderr `[MAESTRO_EXEC_ID=<id>]`.
 
 **Persist context back to status.json** after each step — write updated `context` field and `current_step`. This enables resume via `/maestro -c`.
 
-### 3d. Handle result
-
-**Success:** mark step `status = "completed"`, set `completed_at` in status.json.
-CLI: save output to `step-{N}-output.txt` in session directory.
+### 3d. Handle result & sync dual tracking
+
+**Success:**
+1. status.json: mark step `status = "completed"`, set `completed_at`
+2. TodoWrite: mark current step `completed`, next step `in_progress`
+3. CLI: save output to `step-{N}-output.txt` in session directory
+
+```javascript
+// Dual-track update after each step
+function updateDualTracking(stepIndex, total, chain_name, result) {
+  // 1. status.json — already updated in 3c
+  // 2. TodoWrite — sync UI
+  const todos = getAllTodos().map(todo => {
+    if (!todo.content.startsWith(`MAESTRO:${chain_name}:`)) return todo;
+    const num = extractStepNum(todo.content);
+    if (num === stepIndex + 1) return { ...todo, status: result };
+    if (num === stepIndex + 2 && result === 'completed') return { ...todo, status: 'in_progress' };
+    return todo;
+  });
+  TodoWrite({ todos });
+}
+```
 
 **Failure:**
-- `auto_mode` → retry once, then skip (mark `"skipped"`).
-- Interactive → offer: Retry (max 2) / Skip / Abort.
-- Abort → **Error E003** — update status.json `status = "aborted"`, display resume hint: `/maestro -c`.
+1. status.json: mark step `"failed"` or `"skipped"`
+2. TodoWrite: mark step `completed` (skipped) or keep `in_progress` (retry)
+3. `auto_mode` → retry once, then skip
+4. Interactive → offer: Retry (max 2) / Skip / Abort
+5. Abort → status.json `status = "aborted"`, TodoWrite mark remaining `pending`, display resume hint: `/maestro -c`
 
 ### 3e. Post-step analysis (CLI steps only)
 
@@ -176,7 +209,9 @@ On callback:
 
 ## Step 4: Completion Report
 
-Update status.json: `status = "completed"`.
+Finalize dual tracking:
+1. status.json: `status = "completed"`
+2. TodoWrite: all steps marked `completed` (or `completed` for skipped)
 
 ```
 ============================================================

package/workflows/maestro.codex.md

@@ -290,8 +290,8 @@ Build context: `{ current_phase, user_intent, issue_id, spec_session_id: null, s
 
 ```
 MAESTRO-COORDINATE: {chain_name}  (dry run)
-  1. ${step.cmd} {step.args}
-  2. ${step.cmd} {step.args}
+  1. ${step.skill} {step.args}
+  2. ${step.skill} {step.args}
   …
 ```
 
@@ -310,7 +310,7 @@ Create session directory `.workflow/.maestro/maestro-{timestamp}/`.
 
 **Auto-flag injection** (when AUTO_YES): `maestro-analyze/-brainstorm/-roadmap/-ui-design` → `-y`, `maestro-plan` → `--auto`, `quality-test` → `--auto-fix`, `quality-retrospective` → `--auto-yes`.
 
-Initialize `state.json` with: session_id, intent, chain_name, auto_yes, context (phase, dirs, issue_id, gaps), waves[], and steps[] (each with index, cmd, args, status=pending).
+Initialize `state.json` with: session_id, intent, chain_name, auto_yes, context (phase, dirs, issue_id, gaps), waves[], and steps[] (each with index, skill, args, status=pending).
 
 ---
 

package/workflows/maestro.md

@@ -272,15 +272,27 @@ Create session directory `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/` and wri
     "spec_session_id": null,
     "scratch_dir": null
   },
-  "steps": [{ "index": 0, "skill": "{skill_name}", "args": "{args}", "engine": "{cli|internal from 3e}", "status": "pending", "started_at": null, "completed_at": null }],
+  "steps": [{ "index": 0, "skill": "{chainMap[].cmd}", "args": "{chainMap[].args}", "engine": "{cli|internal from 3e}", "status": "pending", "started_at": null, "completed_at": null }],
   "current_step": "{$START_STEP or 0}",
   "status": "running"
 }
 ```
 
+### 3h: Initialize TodoWrite tracking
+
+Create TodoWrite entries with `MAESTRO:{chain_name}:` prefix for UI-visible progress tracking. TodoWrite and status.json form dual-track system — TodoWrite for user visibility, status.json for persistence and resume.
+
+```javascript
+const todos = steps.map((step, i) => ({
+  content: `MAESTRO:${chain_name}: [${i + 1}/${steps.length}] ${step.skill}`,
+  status: i === 0 ? 'in_progress' : 'pending'
+}));
+TodoWrite({ todos });
+```
+
 ## Step 4: Dispatch to execution workflow
 
-status.json already created in Step 3g with `steps[]` and `context`.
+status.json already created in Step 3g, TodoWrite initialized in Step 3h.
 
 1. Read `~/.maestro/workflows/maestro-chain-execute.md`
 2. Follow it with `$SESSION_PATH` = session directory from Step 3g