maestro-flow 0.4.10 → 0.4.11

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

@@ -0,0 +1,259 @@
+---
+name: maestro-ralph-execute
+description: Execute next pending step in ralph session
+argument-hint: "[-y] [session-id]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - invoke_skill
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Single-step executor for ralph (adaptive) and maestro (static) sessions.
+Each invocation: locate session → find next step → resolve args → execute → update → self-invoke next.
+
+Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
+Session: `.workflow/.maestro/*/status.json`
+</purpose>
+
+<context>
+$ARGUMENTS — optional `-y` flag + optional session ID.
+
+**Parse:**
+```
+-y / --yes → auto = true
+Remaining  → session_id (if matches maestro-* or ralph-*)
+```
+Also read `session.auto_mode` from status.json — if true, treat as `-y`.
+
+**Node types:**
+
+| Type | Execution | Flow after |
+|------|-----------|------------|
+| decision (ralph-only) | `invoke_skill("maestro-ralph")` — ralph re-evaluates | Execution ends here |
+| internal | `invoke_skill({ skill, args })` — synchronous | Self-invoke next |
+| external | `maestro delegate --to claude --mode write` | STOP → callback → self-invoke |
+
+HARD RULE: External nodes ALWAYS append `-y` to skill args inside the prompt — delegate sessions are non-interactive.
+HARD RULE: External nodes ALWAYS delegate to `claude` — only Claude Code can execute slash-command skills.
+</context>
+
+<invariants>
+1. **Every step via invoke_skill() or delegate** — never simulate or inline a skill's work
+2. **External → claude only** — `session.cli_tool` is for analysis delegates, NOT execution
+3. **Self-invocation chain** — continues until all steps complete or session paused
+4. **Status.json updated after every change** — resume-safe
+</invariants>
+
+<state_machine>
+
+<states>
+S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
+S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
+S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
+S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.status, session.context
+S_HANDLE_FAIL   — 处理失败（重试/跳过/中止）              PERSIST: step.status, session.status
+S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
+S_FALLBACK      — 无 session 可执行                      PERSIST: —
+</states>
+
+<transitions>
+
+S_LOCATE:
+  → S_RESOLVE_ARGS  WHEN: pending step found                DO: A_LOCATE_SESSION
+  → S_COMPLETE      WHEN: no pending steps
+  → S_FALLBACK      WHEN: no running session
+
+S_RESOLVE_ARGS:
+  → S_EXECUTE       DO: A_RESOLVE_ARGS
+
+S_EXECUTE:
+  → END             WHEN: step.type == "decision"           DO: A_EXEC_DECISION
+  → S_POST_EXEC     WHEN: step.type == "internal" + success DO: A_EXEC_INTERNAL
+  → S_HANDLE_FAIL   WHEN: step.type == "internal" + failure DO: A_EXEC_INTERNAL
+  → END             WHEN: step.type == "external"           DO: A_EXEC_EXTERNAL
+                     (STOP after background delegate; on callback → S_POST_EXEC or S_HANDLE_FAIL)
+
+S_POST_EXEC:
+  → S_LOCATE        DO: A_MARK_COMPLETE + invoke_skill("maestro-ralph-execute")
+
+S_HANDLE_FAIL:
+  → S_LOCATE        WHEN: auto + not retried               DO: A_RETRY
+  → END             WHEN: auto + retried                    DO: A_PAUSE_SESSION
+  → S_LOCATE        WHEN: interactive + user selects retry  DO: A_RETRY
+  → S_LOCATE        WHEN: interactive + user selects skip   DO: A_SKIP_STEP
+  → END             WHEN: interactive + user selects abort  DO: A_PAUSE_SESSION
+
+S_COMPLETE:
+  → END             DO: A_COMPLETE_SESSION
+
+S_FALLBACK:
+  → END             DO: display "无运行中的会话。使用 /maestro 或 /maestro-ralph 创建。"
+
+</transitions>
+
+<actions>
+
+### A_LOCATE_SESSION
+
+1. If session_id provided → load `.workflow/.maestro/{session_id}/status.json`
+2. Else: scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC, take first
+3. Extract: session_id, source, steps[], current_step, phase, milestone, intent, auto_mode, context, cli_tool
+4. Find first step with `status == "pending"` → next step
+
+### A_RESOLVE_ARGS
+
+**Placeholder substitution:**
+
+| Placeholder | Source |
+|-------------|--------|
+| `{phase}` | session.phase |
+| `{milestone}` | session.milestone |
+| `{intent}` | session.intent |
+| `{description}` | session.intent (alias) |
+| `{scratch_dir}` | session.context.scratch_dir or latest artifact path |
+| `{plan_dir}` | session.context.plan_dir |
+| `{analysis_dir}` | session.context.analysis_dir |
+| `{issue_id}` | session.context.issue_id |
+| `{milestone_num}` | session.context.milestone_num |
+
+**Per-skill enrichment** (when args empty or minimal):
+
+| Skill | Required context | Source |
+|-------|-----------------|--------|
+| maestro-brainstorm | topic | `"{intent}"` |
+| maestro-roadmap | description | `"{intent}"` |
+| maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
+| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` if standalone |
+| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` if standalone |
+| quality-debug | gap context | Read previous step's error/gap from artifact dir |
+| quality-* | phase | `{phase}` |
+
+**Artifact dir resolution for --dir:**
+```
+Read state.json → filter artifacts by milestone + phase
+plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
+execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
+```
+
+Write enriched args back to status.json (resume-safe).
+
+### A_EXEC_DECISION
+
+1. Mark step running, write status.json
+2. Display: `[{index}/{total}] ◆ {skill} [decision] Retry: {retry}/{max}`
+3. `invoke_skill({ skill: "maestro-ralph" })` — ralph detects running decision → evaluates → handoff
+4. **This execution ends here** — ralph handles the handoff back
+
+### A_EXEC_INTERNAL
+
+1. Mark step running, write status.json
+2. Display: `[{index}/{total}] {skill} [internal]`
+3. Resolve auto flag: `auto ? (flag_map[skill] || "") : ""`
+4. `invoke_skill({ skill: next.skill, args: effective_args })`
+5. Return success/failure
+
+**Auto flag map:** all lifecycle skills → `-y`; `quality-test` → `-y --auto-fix`; unlisted internal → no flag
+
+### A_EXEC_EXTERNAL
+
+1. Mark step running, write status.json
+2. Display: `[{index}/{total}] ⚡ {skill} [external]`
+3. Always append `-y` to skill args (delegates are non-interactive): `flag = flag_map[skill] || "-y"`
+4. Execute:
+   ```
+   shell({
+     command: `maestro delegate "/${skill} ${effective_args}" --to claude --mode write`,
+     run_in_background: true, timeout: 600000
+   })
+   STOP — wait for callback.
+   ```
+5. On callback: retrieve output → S_POST_EXEC or S_HANDLE_FAIL
+
+### A_MARK_COMPLETE
+
+1. `step.status = "completed"`, `step.completed_at = now`
+2. Scan output for context signals:
+   - `PHASE: N` → session.phase
+   - `scratch_dir: path` → context.scratch_dir
+   - `SPEC-xxx` → context.spec_session_id
+3. Scan output for `--- COMPLETION STATUS ---` block. If found, parse and map:
+   - `STATUS: DONE` → `step.status = "completed"`
+   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.concerns = CONCERNS value`
+   - `STATUS: NEEDS_RETRY` → trigger retry: set `step.status = "pending"`, `step.retried = true` → S_HANDLE_FAIL
+   - `STATUS: BLOCKED` → `session.status = "paused"`, display blocker reason from CONCERNS
+   - `STATUS: NEEDS_CONTEXT` → `session.status = "paused"`, display context gap from CONCERNS
+   - If no `--- COMPLETION STATUS ---` block found → fall back to existing heuristic (backward compatible)
+4. Write status.json
+5. Display: `[{index}/{total}] ✓ {skill} completed`
+
+### A_RETRY
+
+1. `step.retried = true`, `step.status = "pending"`, `step.error = null`
+2. Write status.json
+
+### A_SKIP_STEP
+
+1. `step.status = "skipped"`
+2. Write status.json
+
+### A_PAUSE_SESSION
+
+1. `session.status = "paused"`, write status.json
+2. Display: `[{index}/{total}] ✗ {skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
+
+### A_COMPLETE_SESSION
+
+1. `session.status = "completed"`, write status.json
+2. Display completion report:
+   ```
+   ============================================================
+     SESSION COMPLETE
+   ============================================================
+     Session:  {session_id} [{source}]
+     Steps:    {completed}/{total}
+
+     [✓] 0.   maestro-plan 1            [internal]
+     [✓] 1. ⚡ maestro-execute 1         [external]
+     [✓] 2.   maestro-verify 1          [internal]
+     [✓] 3. ◆ post-verify               [decision]
+     ...
+   ============================================================
+   ```
+   Icons: `✓` completed, `—` skipped, `✗` failed, `◆` decision, `⚡` external
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Error Codes
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
+| E002 | error | status.json corrupt | Show path, suggest manual check |
+| E003 | error | Delegate failed + user abort | Mark paused, suggest resume |
+| W001 | warning | Step completed with warnings | Log and continue |
+
+### Success Criteria
+
+- [ ] Session discovery covers both maestro-* and ralph-*
+- [ ] `-y` parsed from args OR inherited from session.auto_mode
+- [ ] Placeholders resolved from session context
+- [ ] Per-skill enrichment provides correct args
+- [ ] Decision nodes hand off to maestro-ralph via invoke_skill()
+- [ ] Internal nodes execute via invoke_skill() with auto flag
+- [ ] External nodes delegate to claude with `-y` in prompt args, run_in_background + STOP
+- [ ] Context signals propagate to status.json
+- [ ] Auto mode: retry once then pause
+- [ ] Interactive: ask_user retry/skip/abort
+- [ ] Self-invocation continues until complete or paused
+
+</appendix>

package/.agents/skills/maestro-roadmap/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: maestro-roadmap
+description: Generate roadmap from requirements (light or full mode)
+argument-hint: "<requirement> [--mode light|full] [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Unified roadmap generation with two execution paths:
+
+- **Light mode** (default): Directly from requirements to roadmap. No specification documents.
+- **Full mode** (`--mode full`): 7-phase document chain (Product Brief → PRD → Architecture → Epics → Roadmap) producing a complete specification package in `.workflow/.spec/` plus `.workflow/roadmap.md`.
+
+Additional operation modes (light mode only):
+- **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
+- **Review** (`--review`): Health assessment of current roadmap (read-only)
+
+Both modes produce `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/roadmap-common.md
+@~/.maestro/templates/roadmap.md
+</required_reading>
+
+<deferred_reading>
+- [roadmap.md](~/.maestro/workflows/roadmap.md) — read when mode is light (default)
+- [spec-generate.md](~/.maestro/workflows/spec-generate.md) — read when mode is full
+- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration (full mode)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- requirement text, @file reference, or brainstorm session reference.
+
+**Flags (shared):**
+- `--mode light|full`: Execution path (default: light)
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint
+- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+
+**Flags (light mode only):**
+- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
+- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress.
+- `--review`: Roadmap health assessment (read-only)
+
+**Input types:**
+- Direct text: `"Implement user authentication system with OAuth and 2FA"`
+- File reference: `@requirements.md`
+- Brainstorm import: `--from-brainstorm WFS-xxx`
+- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
+
+**Pipeline position:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md
+maestro-init (project setup)
+        ↓ project.md, state.json, config.json
+maestro-roadmap [--mode light]     → roadmap.md directly
+maestro-roadmap --mode full        → spec package + roadmap.md
+        ↓
+maestro-plan → maestro-execute → maestro-verify
+```
+
+**Note (full mode):** `maestro-init` MUST run before `--mode full`. It creates the `.workflow/` directory and project context.
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
+2. Optional — proceed without if unavailable.
+</context>
+
+<execution>
+
+### Mode routing
+
+1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
+2. Parse `--mode` flag:
+   - `light` or omitted → read `@~/.maestro/workflows/roadmap.md`, follow its process
+   - `full` → read `@~/.maestro/workflows/spec-generate.md`, follow its process
+3. If `--revise` or `--review` present → force light mode (these are light-mode-only operations)
+
+### Light mode (default)
+
+Follow `~/.maestro/workflows/roadmap.md` completely.
+
+Sub-modes:
+- **Create** (default): Build roadmap from requirements
+- **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
+- **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
+
+### Full mode (`--mode full`)
+
+Follow `~/.maestro/workflows/spec-generate.md` completely.
+
+### Next-step routing on completion
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Roadmap approved, need analysis | /maestro-analyze 1 |
+| Simple project, ready to plan | /maestro-plan 1 |
+| Need UI design first | /maestro-impeccable build |
+| View project dashboard | /manage-status |
+| Need project setup (full mode) | /maestro-init |
+</execution>
+
+<error_codes>
+
+**Shared:**
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Requirement/idea text or @file required | Prompt user for input |
+| E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+
+**Light mode:**
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
+| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
+| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
+| W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
+
+**Full mode:**
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E006 | error | `.workflow/` not initialized | Run maestro-init first |
+| E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
+| W002 | warning | Codebase exploration failed | Continue without codebase context |
+| W003 | warning | Glossary has < 5 terms | Note in readiness check |
+| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
+</error_codes>
+
+<success_criteria>
+
+**Light mode:**
+- [ ] Requirement parsed with goal, constraints, stakeholders
+- [ ] Decomposition strategy selected (progressive or direct)
+- [ ] Phases defined with success criteria, dependencies, and requirement mappings
+- [ ] Every Active requirement from project.md mapped to exactly one phase
+- [ ] No circular dependencies in phase ordering
+- [ ] User approved roadmap (or auto-approved with -y)
+- [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
+- [ ] No phase directories created (phases are labels in roadmap, not directories)
+
+**Full mode (in addition to light mode criteria for roadmap):**
+- [ ] `spec-config.json` created with session metadata and phase tracking
+- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
+- [ ] `glossary.json` with 5+ core terms for cross-document consistency
+- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
+- [ ] All requirements have RFC 2119 keywords and acceptance criteria
+- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
+- [ ] Architecture includes state machine, config model, error handling, observability (service type)
+- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
+- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
+- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
+- [ ] `spec-summary.md` with one-page executive summary
+- [ ] All documents have valid YAML frontmatter with session_id
+- [ ] Glossary terms used consistently across all documents
+- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
+- [ ] `.workflow/roadmap.md` written
+</success_criteria>

package/.agents/skills/maestro-tools-execute/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: maestro-tools-execute
+description: Load and execute tool specs by category or name
+argument-hint: "[<tool-name> | --category <category>] [--list]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - ask_user
+  - delegate_subagent
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Load registered tool documents and execute them step-by-step. Two invocation modes:
+
+1. **Direct** — Specify tool name, load full steps, execute sequentially
+2. **Category-based** — List available tools for a category, user selects, then execute
+
+Execution follows the tool definition steps in order, reporting progress per step and asking user on blockers.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/tools-spec.md
+</required_reading>
+
+<context>
+$ARGUMENTS — Tool name, keyword, or --category filter
+
+**Examples**:
+```
+/maestro-tools-execute integration-test
+/maestro-tools-execute --category coding
+/maestro-tools-execute --category review --keyword api
+/maestro-tools-execute
+```
+
+Empty arguments enters interactive mode: list all tools for user selection.
+</context>
+
+<execution>
+
+### Step 1: Load Tool
+
+**By name**:
+```bash
+maestro spec load --category coding --keyword <name>
+```
+Match knowhow documents with `tool: true` whose title or keywords contain the name.
+
+**By category**:
+```bash
+maestro spec load --category <category>
+```
+Extract tool entries from the "Available Tools" section in output.
+
+**Empty args**:
+Load all categories, collect tool entries, present to user with ask_user for selection.
+
+### Step 2: Display Tool
+
+Show tool information:
+- Name, category, keywords
+- Steps overview (for ref entries, expand knowhow detail first)
+
+Expand ref entries:
+```bash
+maestro wiki load <knowhow-id>
+```
+
+### Step 3: Confirm Execution
+
+Ask user:
+- Execute steps as-is?
+- Adjust parameters/scope?
+- View only, do not execute?
+
+### Step 4: Step-by-Step Execution
+
+Follow the tool definition steps in order:
+1. Read current step description
+2. Execute step action (file ops, commands, code changes, etc.)
+3. Verify step completion
+4. Report progress: `[Step N/M] done — <step_name>`
+5. Proceed to next step
+
+**Blocker handling**:
+- Step fails → report error, ask user: retry / skip / abort
+- Needs user input → ask_user for parameters
+- Prerequisites unmet → show missing items, ask how to proceed
+
+### Step 5: Report Results
+
+After completion, output:
+- Completed steps list
+- Skipped/failed steps (if any)
+- Artifacts produced (generated files, test results, etc.)
+- Suggested next actions
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | No matching tool found — check name/keyword |
+| E002 | warning | Multiple tools match — list options for user selection |
+| E003 | warning | Step execution failed — ask user how to proceed |
+</error_codes>
+
+<success_criteria>
+- [ ] Tool correctly loaded (ref expanded if applicable)
+- [ ] User confirmed before execution starts
+- [ ] Each step has progress feedback
+- [ ] Blockers handled interactively
+- [ ] Results reported clearly
+</success_criteria>