maestro-flow 0.3.28 → 0.3.30

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/.codex/skills/quality-business-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-business-test
 description: PRD-forward business testing with requirement traceability, multi-layer execution (L1 Interface -> L2 Business Rule -> L3 Scenario), fixture generation, and feedback loop.
-argument-hint: "<phase> [--spec SPEC-xxx] [--layer L1|L2|L3] [--gen-code] [--dry-run] [--re-run] [--auto]"
+argument-hint: "<phase> [--spec SPEC-xxx] [--layer L1|L2|L3] [--gen-code] [--dry-run] [--re-run] [-y]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
 ---
 
@@ -37,7 +37,7 @@ $quality-business-test "3 --gen-code"               # generate framework-specifi
 $quality-business-test "3 --dry-run"                # extract scenarios only, don't execute
 $quality-business-test "3 --re-run"                 # re-run only previously failed scenarios
 $quality-business-test "3 --spec SPEC-auth-2026-04" # explicit spec reference
-$quality-business-test "3 --auto"                   # skip plan confirmation
+$quality-business-test "3 -y"                   # skip plan confirmation
 ```
 
 **Flags**:
@@ -47,9 +47,9 @@ $quality-business-test "3 --auto"                   # skip plan confirmation
 - `--gen-code`: Generate framework-specific test classes (JUnit/RestAssured, supertest/vitest, pytest/httpx)
 - `--dry-run`: Extract scenarios and fixtures only, don't execute
 - `--re-run`: Re-run only previously failed/blocked scenarios
-- `--auto`: Skip interactive confirmations
+- `-y`: Skip interactive confirmations
 
-`--auto` skips interactive confirmation of test plan. `--dry-run` extracts scenarios only without execution.
+`-y` skips interactive confirmation of test plan. `--dry-run` extracts scenarios only without execution.
 
 **Output**: `{artifact_dir}/.tests/business/business-test-plan.json` + `business-test-report.json` + `business-test-summary.md`
 </context>
@@ -125,7 +125,7 @@ Three tiers:
 1. Archive previous `business-test-plan.json` to `.history/` if exists
 2. Write `.tests/business/business-test-plan.json` with scenarios, fixtures, mock_contracts, requirement_coverage_plan
 3. Display plan summary (scenario counts per layer, fixture counts, requirement coverage)
-4. If not `--auto`: wait for user confirmation (yes/edit/cancel)
+4. If not `-y`: wait for user confirmation (yes/edit/cancel)
 5. If `--dry-run`: stop here, report plan
 
 ### Step 5: Generate Test Code (if --gen-code)
@@ -209,7 +209,7 @@ Map each result to `REQ-NNN:AC-N`. Per AC: `passed` (all scenarios pass), `faile
 - [ ] Phase resolved and spec package loaded (or degraded mode activated)
 - [ ] Business test scenarios extracted from PRD acceptance criteria
 - [ ] Fixtures generated for all layers
-- [ ] Test plan written and confirmed (or --auto/--dry-run)
+- [ ] Test plan written and confirmed (or -y/--dry-run)
 - [ ] Tests executed progressively L1 -> L2 -> L3 with fail-fast
 - [ ] Traceability matrix maps every result to REQ-NNN:AC-N
 - [ ] Reports generated (JSON + summary markdown)

package/.codex/skills/quality-retrospective/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-retrospective
 description: Multi-lens 复盘 (retrospective) for completed phases. Context-Agent Fork loads phase artifacts once; four parallel lens agents (technical, process, quality, decision) analyze independently; synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and lessons.jsonl.
-argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [--auto-yes]"
+argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
@@ -50,7 +50,7 @@ $quality-retrospective "3"
 $quality-retrospective "2..4"
 $quality-retrospective "--all"
 $quality-retrospective "3 --lens technical --no-route"
-$quality-retrospective "3 --compare 2 --auto-yes"
+$quality-retrospective "3 --compare 2 -y"
 ```
 
 **Flags**:
@@ -61,9 +61,9 @@ $quality-retrospective "3 --compare 2 --auto-yes"
 - `--lens <name>` -- restrict to one lens (repeatable): `technical|process|quality|decision`
 - `--no-route` -- produce retrospective.{md,json} only; skip auto-creation of spec/note/issue
 - `--compare <M>` -- emit a delta section vs phase M's prior retrospective
-- `--auto-yes` -- accept all routing recommendations without prompting
+- `-y` -- accept all routing recommendations without prompting
 
-When `--auto-yes`: Accept all routing recommendations without prompting. Route all insights automatically.
+When `-y`: Accept all routing recommendations without prompting. Route all insights automatically.
 
 **Storage written**:
 - `{target_dir}/retrospective.md` -- human-readable record (target_dir resolved via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`)
@@ -124,7 +124,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 6. **Stable INS-ids**: `INS-{8hex}` from `hash(phase_num + lens + title)` -- re-runs do not create duplicates
 7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
 8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
-9. **Route confirmation**: Unless `--auto-yes`, present routing table and ask per-group before writing spec/issue/knowhow
+9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
 10. **Lessons always written**: Append to `lessons.jsonl` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
 </invariants>
 

package/.codex/skills/quality-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-test
 description: Conversational UAT with session persistence, auto-diagnosis, and gap-plan closure loop. Interactive testing flow with severity inference and parallel debug agents.
-argument-hint: "<phase> [--auto-fix] [--session ID]"
+argument-hint: "<phase> [-y] [--auto-fix] [--session ID]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
 ---
 
@@ -29,7 +29,7 @@ $quality-test "--session 04-comments"  # resume specific session
 - `--auto-fix`: Auto-trigger gap-fix loop (plan --gaps -> execute -> re-verify) on failures
 - `--session ID`: Resume a specific UAT session
 
-No auto mode -- UAT is inherently interactive. `--auto-fix` only automates gap closure, not test execution.
+`-y` implies `--auto-fix`。UAT 执行本身保持交互（展示预期 → 确认），`-y` 仅自动化 gap closure loop。
 
 **Output**: `{target_dir}/uat.md` + `.tests/test-plan.json` + `.tests/test-results.json` + `.tests/coverage-report.json`
 </context>

package/package.json

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