maestro-flow-one 0.2.26 → 0.2.27

package/maestro-flow/commands/lifecycle/analyze.md

@@ -20,6 +20,8 @@ Combines structured 6-dimension scoring with iterative deepening and decision ex
 Use `-q` for quick decision extraction only (skip exploration + scoring).
 
 Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyze). Loads issues from issues.jsonl, performs CLI exploration against issue context/location, synthesizes root cause into issue.analysis, and outputs context.md for downstream `plan --gaps`.
+
+Pipeline position: downstream of maestro-grill, maestro-brainstorm, and maestro-blueprint (optional upstream enrichment); upstream of maestro-plan and maestro-roadmap (consumes analysis context).
 </purpose>
 
 <required_reading>
@@ -45,31 +47,47 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 - Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
-- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
-- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
-- `--from <source>`: Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path)
-- `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
-Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive scoping, use recommended defaults, auto-deepen | false |
+| `-c` / `--continue` | Resume from existing session (auto-detect session folder + discussion.md) | false |
+| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only) | false |
+| `--from <source>` | Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path) | — |
+| `--gaps [ISS-ID]` | Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl | — |
+
+**Scope routing:**
+| Input | Mode | Scope |
+|-------|------|-------|
+| Pure digits (e.g. `1`, `42`) | micro | Phase-level deep analysis |
+| Non-numeric text (e.g. `auth-refactor`) | macro | Topic impact surface |
+| No positional arg + roadmap | micro | Milestone-wide |
+| No positional arg + no roadmap | macro | Fallback |
+| `--gaps [ISS-ID]` | gaps | Issue root cause analysis |
+
+Output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Output Structure section).
+
+### Pre-load
+
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
+2. **Specs**: `maestro spec load --category arch` — load architecture constraints
+3. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+4. All optional — proceed without if unavailable (log warning)
 
 ### Role Knowledge
 `maestro wiki list --category debug` → select relevant → `maestro wiki load`
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (explicit phase number or unambiguous topic).
-
-- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each settled decision is immediately appended/updated in `discussion.md` (top table) and mirrored into `context.md` "Interview Decisions". Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
-- Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
-- Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
-
-Decision points: scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold.
-
-Exit: when all decision points are settled (or user explicitly signals to proceed), finalize session metadata. The decision table (populated incrementally during interview) uses this schema:
-`| # | Decision | Choice | Source (user / code / default) |`
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold
+**Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
+**Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
+**Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
+**Additional skip conditions**: input is already specific (explicit phase number or unambiguous topic)
+**Exit condition**: all decision points settled → finalize session metadata
 </interview_protocol>
 
 <execution>
@@ -106,23 +124,52 @@ Phase 4: Output context.md for downstream plan --gaps
 - `large` (3+ independent subsystems or hard serial dependencies) → suggest `/maestro-roadmap --from analyze:ANL-xxx`
 - `medium` (1-2 subsystems, parallelizable) → suggest `/maestro-plan --from analyze:ANL-xxx`
 - `small` (single-file or few-file change) → suggest `/maestro-plan --from analyze:ANL-xxx`
+</execution>
 
-**Next-step routing on completion:**
+<completion>
+### Standalone report
 
-Phase/Milestone scope (micro mode):
-- Go recommendation, UI work needed → `/maestro-impeccable build {target}`
-- Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
-- No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
+```
+=== ANALYSIS READY ===
+Artifact: ANL-{id}
+Scope: {micro|macro|adhoc|gaps}
+Go/No-Go: {GO|NO-GO|CONDITIONAL}
+Confidence: {high|medium|low}
+Outputs: analysis.md, context.md, conclusions.json, discussion.md
+Session dir: {output_dir}
+===
+```
 
-Macro/Adhoc/Standalone scope:
-- scope_verdict = large → `/maestro-roadmap --from analyze:ANL-xxx`
-- scope_verdict = medium/small → `/maestro-plan --from analyze:ANL-xxx`
-- Need more exploration → `/maestro-analyze {topic} -c`
+### Ralph-invoked completion
 
-Gaps scope:
-- Issues analyzed → `/maestro-plan --gaps` (plan fix tasks linked to issues)
-- Need more context → `/maestro-analyze --gaps {ISS-ID}` (re-analyze specific issue)
-</execution>
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Phase/Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
+| Phase/Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {phase}` |
+| Phase/Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
+| Macro/Adhoc, scope_verdict = large | `/maestro-roadmap --from analyze:ANL-xxx` |
+| Macro/Adhoc, scope_verdict = medium/small | `/maestro-plan --from analyze:ANL-xxx` |
+| Need more exploration | `/maestro-analyze {topic} -c` |
+| Gaps scope, issues analyzed | `/maestro-plan --gaps` |
+| Gaps scope, need more context | `/maestro-analyze --gaps {ISS-ID}` |
+
+### Session seal
+
+@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
@@ -166,6 +213,3 @@ Both modes (full + quick):
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>
 
-<on_complete>
-@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
-</on_complete>

package/maestro-flow/commands/lifecycle/blueprint.md

@@ -20,6 +20,8 @@ Parallel to `brainstorm` as an upstream origin command:
 - **blueprint** = convergent documentation (heavyweight, 6-phase formal spec chain)
 
 Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD, Architecture, and Epics.
+
+Pipeline position: downstream of maestro-brainstorm (optional). Upstream of maestro-analyze, maestro-roadmap, and maestro-plan.
 </purpose>
 
 <required_reading>
@@ -34,10 +36,13 @@ Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD,
 $ARGUMENTS -- idea text, @file reference, or upstream context source.
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint (reads blueprint-config.json)
-- `--from <source>`: Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json
-- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
+| `-c` / `--continue` | Resume from last checkpoint (reads blueprint-config.json) | false |
+| `--from <source>` | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json | — |
+| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
 
 **Input types:**
 - Direct text: `"Build a real-time collaboration platform with WebSocket"`
@@ -56,23 +61,22 @@ maestro-analyze → maestro-roadmap → maestro-plan
 
 **Output boundary**: ALL file writes MUST target `.workflow/blueprint/BLP-{slug}-{date}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for architecture decisions (Phase 4).
-2. Optional — proceed without if unavailable.
+### Pre-load
+
+1. **Specs**: `maestro spec load --category arch` — load architecture constraints for Phase 4 decisions
+2. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → prior knowledge context
+3. All optional — proceed without if unavailable
 </context>
 
 <interview_protocol>
-Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
-
-- Ask one question per turn via AskUserQuestion and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing artifacts, `maestro spec load`, direct codebase exploration (Glob/Grep/Read), or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each settled decision is immediately persisted into `blueprint-config.json` before the next question. Do NOT batch writeback to the end — partial decisions must already be on disk.
-- Walk the decision dependency tree depth-first: scope → spec type → focus areas → requirement priorities. Do not open the next branch until the current one is settled.
-- Scope guard: only decide the shape of the specification. Do not pre-resolve roadmap phases or plan tasks — those belong to downstream commands.
-
-Decision points: scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration.
-
-Exit: on consensus or explicit user signal to proceed, finalize blueprint-config.json (decisions already written incrementally) and proceed to Phase 1.
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven, depth-first
+**Decision tree** (strict depth-first): scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration → requirement priorities
+**Scope guard**: only specification shape; do not pre-resolve roadmap phases or plan tasks
+**Writeback target**: blueprint-config.json (each decision persisted before next question)
+**Additional skip conditions**: none beyond standard (-y, -c)
+**Exit condition**: all decision points settled → finalize blueprint-config.json, proceed to Phase 1
 </interview_protocol>
 
 <execution>
@@ -86,15 +90,44 @@ P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief
 
 P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail (<60%) → P6.5 Auto-Fix (max 2 iter) → re-check
 
-### Next-step routing on completion
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== BLUEPRINT READY ===
+Session: BLP-{slug}-{date}
+Phases completed: P0–P6
+Readiness score: {score}%
+Gate verdict: {Pass|Review|Fail}
+Output: .workflow/blueprint/BLP-{slug}-{date}/
+Key artifacts: product-brief.md, requirements/, architecture/, epics/, readiness-report.md
+===
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Need codebase analysis | /maestro-analyze {topic} --from blueprint:BLP-xxx |
-| Ready for roadmap | /maestro-roadmap --from blueprint:BLP-xxx |
-| Small scope, direct plan | /maestro-plan --from blueprint:BLP-xxx |
-| Need project setup | /maestro-init |
-</execution>
+| Need codebase analysis | `/maestro-analyze {topic} --from blueprint:BLP-xxx` |
+| Ready for roadmap | `/maestro-roadmap --from blueprint:BLP-xxx` |
+| Small scope, direct plan | `/maestro-plan --from blueprint:BLP-xxx` |
+| Need project setup | `/maestro-init` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -13,6 +13,8 @@ allowed-tools:
 ---
 <purpose>
 Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+
+Pipeline position: downstream of maestro-grill (optional stress-test). Upstream of maestro-roadmap, maestro-analyze, and maestro-blueprint (all consume brainstorm output).
 </purpose>
 
 <required_reading>
@@ -38,13 +40,16 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 **Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
 **Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--yes` / `-y` | Auto mode — skip interactive questions, use defaults | false |
+| `--count N` | Number of roles to select (max 9) | 3 |
+| `--session ID` | Use existing session | — |
+| `--update` | Update existing analysis (single role) | false |
+| `--skip-questions` | Skip context gathering questions | false |
+| `--include-questions` | Force context gathering even if analysis exists | false |
+| `--style-skill PKG` | Style package for ui-designer role | — |
 
 ### Pre-load specs
 1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
@@ -60,39 +65,69 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `--yes/-y`, `--skip-questions`, `--session` (existing session), or input is already specific.
-
-- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
-- Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
-- Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
-
-Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source (grill:ID, blueprint:ID, @file, path) / whether to enable design-research and the DESIGN.md sub-pipeline.
-
-Exit: on consensus or explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
-`| # | Decision | Choice | Source (user / code / default) |`
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (flexible order — user may jump between branches): mode (auto / single-role / review-only) → role selection and --count → --from upstream source (grill:ID, blueprint:ID, @file, path) → whether to enable design-research and DESIGN.md sub-pipeline
+**Scope guard**: only brainstorm decisions; do not pre-resolve roadmap/plan choices
+**Writeback target**: guidance-specification.md §11 (create section if absent)
+**Additional skip conditions**: --skip-questions, --session (existing session)
+**Exit condition**: on consensus or explicit user signal → finalize session metadata
 </interview_protocol>
 
 <execution>
 Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need formal spec package → Skill({ skill: "maestro-blueprint", args: "--from brainstorm:{artifact_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from brainstorm:{artifact_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic} --from brainstorm:{artifact_id}" })
-- Need stress-testing first → Skill({ skill: "maestro-grill", args: "{topic}" })
-- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
 </execution>
 
+<completion>
+### Standalone report
+
+```
+=== BRAINSTORM READY ===
+Session: {session_id}
+Output:  {output_dir}
+Mode:    {auto|single-role}
+Roles:   {selected_roles}
+Findings: {review_findings_count} cross-role issues, {resolutions_applied} resolutions applied
+Status:  COMPLETE
+========================
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+**Auto mode:**
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Project not initialized | `/maestro-init` |
+| Need formal spec package | `/maestro-blueprint --from brainstorm:{artifact_id}` |
+| Quick roadmap needed | `/maestro-roadmap --from brainstorm:{artifact_id}` |
+| Need deeper analysis first | `/maestro-analyze {topic} --from brainstorm:{artifact_id}` |
+| Need stress-testing first | `/maestro-grill {topic}` |
+| `html-prototypes/` produced with 2+ files and user wants to browse | Load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server |
+| DESIGN.md established during Step 3.5 | `/maestro-impeccable build <feature-description>` |
+
+**Single role mode:**
+
+| Condition | Suggestion |
+|-----------|-----------|
+| More roles needed | `/maestro-brainstorm {next_role} --session {session_id}` |
+| All roles done, run synthesis | `/maestro-brainstorm {topic} --session {session_id}` |
+</completion>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|

package/maestro-flow/commands/lifecycle/execute.md

@@ -16,6 +16,8 @@ allowed-tools:
 Execute all tasks in a plan using wave-based parallel execution with dependency-aware ordering. Each plan is executed independently (plans串行, plan内wave并行). Task summaries are written to the plan's scratch directory under `.summaries/`. Registers EXC artifact in state.json.
 
 Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
+
+Pipeline position: upstream from maestro-plan (consumes confirmed plan), downstream to maestro-verify.
 </purpose>
 
 <required_reading>
@@ -30,7 +32,26 @@ Invoked after /maestro-plan produces a confirmed plan. When called without args
 <context>
 $ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
 
-Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
+### Flags
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--auto-commit` | Auto-commit after each completed task | false |
+| `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
+| `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
+| `--dir <path>` | Execute a specific plan directory instead of auto-discovery | — |
+| `-y` / `--yes` | Auto mode — skip interactive questions | false |
+
+### Scope routing
+
+| Input | Scope | Resolution |
+|-------|-------|------------|
+| numeric arg | phase | Resolve plan from roadmap phase |
+| `--dir <path>` | explicit | Use specified plan directory |
+| no args + milestone | milestone | Find all pending plans, execute sequentially |
+| no args + no milestone | error E001 | No plan found |
+
+Full resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
 
 ### Pre-load context (before task execution)
 
@@ -81,7 +102,10 @@ For each completed/failed TASK with issue_id:
   Write updated issue back to issues.jsonl
 ```
 
-**Report format on completion:**
+</execution>
+
+<completion>
+### Standalone report
 
 ```
 === EXECUTION COMPLETE ===
@@ -91,24 +115,30 @@ Failed:    {failed_count} tasks
 
 Summaries: {plan_dir}/.summaries/
 Tasks:     {plan_dir}/.task/
-
-Next steps:
-  /maestro-verify              -- Verify execution results
-  /maestro-verify --dir {dir}  -- Verify specific plan
-  /manage-status               -- View project dashboard
 ```
 
-**Completion status:**
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
 ```
---- COMPLETION STATUS ---
-STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
-CONCERNS: {failed_count} tasks failed (if any)
-NEXT: /maestro-verify
---- END STATUS ---
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 ```
 
-If failed tasks exist, suggest /quality-debug for investigation.
-</execution>
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tasks completed successfully | `/maestro-verify` |
+| Specific plan needs verification | `/maestro-verify --dir {dir}` |
+| Failed tasks exist | `/quality-debug` |
+| View project dashboard | `/manage-status` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/lifecycle/grill.md

@@ -35,57 +35,82 @@ $ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstrea
 - **Resume mode** (`-c` or `--session ID`): Continue from a previous grill session
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — CLI exploration replaces human answers
-- `-c` / `--continue`: Resume from last grill session
-- `--session ID`: Resume specific session
-- `--depth shallow|standard|deep`: Branch count 3/5/8 (default: standard)
-- `--from <source>`: Load upstream material (`blueprint:ID`, `@file`, or path)
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — CLI exploration replaces human answers | `false` |
+| `-c` / `--continue` | Resume from last grill session | — |
+| `--session ID` | Resume specific session | — |
+| `--depth shallow\|standard\|deep` | Branch count 3/5/8 | `standard` |
+| `--from <source>` | Load upstream material (`blueprint:ID`, `@file`, or path) | — |
 
 **Output directory**: `.workflow/scratch/{YYYYMMDD}-grill-{slug}/`
 **Produced files**: `grill-report.md`, `terminology.md`, `context-package.json`
 
-### Role Knowledge
-`maestro wiki search "{topic keywords}"` → load relevant entries before grilling.
-`maestro spec load --category arch` → load architecture constraints.
+### Pre-load
+
+1. **Specs**: `maestro spec load --category arch` — load architecture constraints
+2. **Wiki search**: `maestro wiki search "{topic keywords}"` → load relevant entries before grilling
+3. All optional — proceed without if unavailable
 </context>
 
 <interview_protocol>
-Grill the user relentlessly until every branch of the decision tree is walked. This is NOT a menu-driven interview — it is adversarial Socratic questioning. Active only in interactive mode; skip when `-y/--yes` or `-c/--continue`.
-
-Core protocol:
-- **One question per turn**. Each question probes ONE specific aspect. Never ask compound questions.
-- **Code-grounded**: Before asking, search the codebase for evidence. Use findings to sharpen the question or challenge the user's answer. Never ask what code can verify — search first, then confront.
-- **Escalating depth**: Start with scope boundaries, progress to data model, edge cases, failure modes. Each branch goes basic → specific → adversarial.
-- **Immediate writeback**: After each answered question, immediately append the Q&A + decision to `grill-report.md`. Do NOT batch — partial progress must be on disk before the next question.
-- **Challenge contradictions**: If an answer conflicts with code evidence or a prior answer, immediately surface the contradiction and demand resolution.
-- **Terminology enforcement**: When the user uses a term that conflicts with codebase naming, challenge it immediately. Propose the code-consistent alternative. Update `terminology.md` as terms crystallize.
-
-Question framing rules:
-- Reference specific code findings: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
-- Use concrete scenarios: "What happens when a user does {action} while {condition} is true?"
-- Probe boundaries: "You said {X} is in scope — does that include {edge_case}, or is that separate?"
-- Challenge scale: "This touches `{table}` — at 10x current data volume, which query breaks first?"
-
-Branch walking order: Scope & Boundaries → Data Model & State → Edge Cases & Failure Modes → Integration & Dependencies → Scale & Performance → Security & Access Control → Observability & Operations → Migration & Rollback. Number of branches determined by `--depth`.
-
-Exit: When all depth-selected branches are fully walked (every question answered or explicitly deferred), finalize the report and generate context-package.json.
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode override**: adversarial Socratic — NOT menu-driven
+**Question style**:
+  - Reference specific code: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+  - Concrete scenarios: "What happens when {action} while {condition}?"
+  - Challenge contradictions: immediately surface conflicts with code evidence or prior answers
+  - Escalating depth: per branch basic → specific → adversarial
+**Branch traversal** (depth-gated, --depth controls count): Scope & Boundaries → Data Model & State → Edge Cases & Failure Modes → Integration & Dependencies → Scale & Performance → Security & Access Control → Observability & Operations → Migration & Rollback
+**Writeback target**: grill-report.md (Q&A append per question) + terminology.md (term crystallization)
+**Additional skip conditions**: none beyond standard (-y, -c)
+**Exit condition**: all depth-selected branches fully walked → finalize report + context-package.json
 </interview_protocol>
 
 <execution>
 Follow '~/.maestro/workflows/grill.md' completely.
-
-**Next-step routing on completion:**
-
-Standard routing:
-- Need multi-role elaboration → Skill({ skill: "maestro-brainstorm", args: "{topic} --from grill:{artifact_id}" })
-- Need deep technical analysis → Skill({ skill: "maestro-analyze", args: "{topic} --from grill:{artifact_id}" })
-- Scope is clear, ready for roadmap → Skill({ skill: "maestro-roadmap", args: "--from grill:{artifact_id}" })
-- Need formal spec package → Skill({ skill: "maestro-blueprint", args: "--from grill:{artifact_id}" })
-
-Resume routing:
-- More branches to walk → Skill({ skill: "maestro-grill", args: "{topic} -c" })
 </execution>
 
+<completion>
+### Standalone report
+
+```
+=== GRILL READY ===
+Topic: {topic}
+Branches walked: {count}/{depth_target}
+Decisions locked: {locked_count}
+Open risks: {risk_count}
+Output: {output_dir}
+Artifact: GRL-{id}
+=== END GRILL ===
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Need multi-role elaboration | `Skill({ skill: "maestro-brainstorm", args: "{topic} --from grill:{artifact_id}" })` |
+| Need deep technical analysis | `Skill({ skill: "maestro-analyze", args: "{topic} --from grill:{artifact_id}" })` |
+| Scope is clear, ready for roadmap | `Skill({ skill: "maestro-roadmap", args: "--from grill:{artifact_id}" })` |
+| Need formal spec package | `Skill({ skill: "maestro-blueprint", args: "--from grill:{artifact_id}" })` |
+| More branches to walk | `Skill({ skill: "maestro-grill", args: "{topic} -c" })` |
+</completion>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|

package/maestro-flow/commands/lifecycle/init.md

@@ -13,28 +13,56 @@ allowed-tools:
 ---
 <purpose>
 Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
+
+Pipeline position: entry point (no upstream). Downstream: `maestro-roadmap` or `maestro-brainstorm`.
 </purpose>
 
 <required_reading>
 @~/.maestro/workflows/init.md
-@~/.maestro/templates/project.md
-@~/.maestro/templates/state.json
-@~/.maestro/templates/config.json
 </required_reading>
 
+<deferred_reading>
+- [project.md](~/.maestro/templates/project.md) — read when generating project description
+- [state.json](~/.maestro/templates/state.json) — read when creating initial state
+- [config.json](~/.maestro/templates/config.json) — read when creating workflow configuration
+</deferred_reading>
+
 <context>
+$ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for auto mode.
+
 **Flags:**
-- `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from <source>` -- Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm`
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference. | `false` |
+| `--from <source>` | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm` | — |
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
 </context>
 
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap)
+**Scope guard**: only init decisions; do not prejudge roadmap structure or plan scope
+**Writeback target**: project.md (project description) + config.json (settings) + state.json (initial state)
+**Additional skip conditions**: --from source (upstream context pre-fills decisions)
+**Exit condition**: all configuration questions settled → proceed to workflow execution
+</interview_protocol>
+
 <execution>
+### Pre-flight
+
+1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)
+2. Validate `--from` source is accessible if provided
+
 Follow '~/.maestro/workflows/init.md' completely.
+</execution>
 
-**Report format on completion:**
+<completion>
+### Standalone report
 
 ```
 === WORKFLOW INITIALIZED ===
@@ -46,17 +74,31 @@ Created:
   .workflow/state.json
   .workflow/config.json
   .workflow/specs/
+```
 
-Next steps (choose one path to create roadmap):
-  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light, default)
-  /maestro-roadmap --mode full <idea>                          -- Full spec package + roadmap (heavy)
+### Ralph-invoked completion
 
-Other commands:
-  /manage-status                                               -- View project dashboard
-  /maestro-brainstorm <topic>                                  -- Explore ideas first
-  /maestro-quick <task>                                        -- Quick ad-hoc task
+End the step by calling the CLI (no text block output):
 ```
-</execution>
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Roadmap needed (default light) | `/maestro-roadmap <requirement>` |
+| Full spec package + roadmap | `/maestro-roadmap --mode full <idea>` |
+| Explore ideas first | `/maestro-brainstorm <topic>` |
+| View project dashboard | `/manage-status` |
+| Quick ad-hoc task | `/maestro-quick <task>` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
@@ -68,11 +110,11 @@ Other commands:
 </error_codes>
 
 <success_criteria>
-- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
 - [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
 - [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
 - [ ] `.workflow/config.json` created with workflow / execution / git / gates / codebase / guard / collab / specInjection / dashboard segments
 - [ ] `.workflow/specs/` initialized with convention files
-- [ ] Research completed (if enabled) — 4 parallel agents spawned
-- [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)
+- [ ] All interview decisions written to project.md / config.json before proceeding
+- [ ] Research completed (if enabled) — parallel agents spawned with results merged
+- [ ] Next-step routing displayed in completion report
 </success_criteria>

package/maestro-flow/commands/lifecycle/plan.md

@@ -120,7 +120,13 @@ For each created TASK-{NNN}.json that has issue_id:
 
 This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
 
-**Report format on completion:**
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<completion>
+### Standalone report
 
 ```
 === PLAN READY ===
@@ -131,20 +137,16 @@ Collision: {collision_status}
 
 Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
 Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
-
-Next steps:
-  /maestro-execute              -- Execute the plan
-  /maestro-execute --dir {dir}  -- Execute specific plan
-  /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
-**Completion (when invoked from ralph):**
-End the step by calling the CLI (no `--- COMPLETION STATUS ---` text block):
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
 ```
-maestro ralph complete <idx> --status DONE [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
+maestro ralph complete <idx> --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
 ```
 
-STATUS verdicts (CLI-enforced enum):
+Status verdicts:
 - **DONE** — Plan created/revised and confirmed → next step picks up automatically
 - **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
 - **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
@@ -152,10 +154,14 @@ STATUS verdicts (CLI-enforced enum):
 
 > Ambiguous requirements are NOT a completion status — resolve them in-place via `AskUserQuestion` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
 
-### Mode: Revise / Check
+### Next-step routing
 
-Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
-</execution>
+| Condition | Suggestion |
+|-----------|-----------|
+| Plan confirmed for execution | `/maestro-execute` |
+| Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
+| Re-plan with modifications | `/maestro-plan {phase}` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -36,13 +36,16 @@ For formal specification documents (Product Brief, PRD, Architecture, Epics), us
 $ARGUMENTS -- requirement text, @file reference, or upstream context source.
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint
-- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
-- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json
-- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
-- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress.
-- `--review`: Roadmap health assessment (read-only)
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
+| `-c` / `--continue` | Resume from last checkpoint | false |
+| `-m progressive\|direct\|auto` | Decomposition strategy | auto |
+| `--from <source>` | Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json | — |
+| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
+| `--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"`
@@ -61,24 +64,22 @@ maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
 maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 ```
 
-### 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.
+### Pre-load
+
+1. **Specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+2. **Wiki search**: `maestro wiki search "{requirement keywords}" --json` → prior knowledge
+3. All optional — proceed without if unavailable
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
-
-- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
-- Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
-- Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
-- Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
-
-Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
-
-Exit: on consensus or explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
-`| # | Decision | Choice | Source (user / code / default) |`
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
+**Scope guard**: only roadmap shape; do not pre-resolve intra-phase task breakdown (belongs to plan)
+**Writeback target**: .workflow/roadmap.md "Roadmap Decisions" section (create if absent)
+**Additional skip conditions**: --revise, --review (skip to respective mode)
+**Exit condition**: on consensus or explicit user signal → finalize Roadmap Decisions section
 </interview_protocol>
 
 <execution>
@@ -91,16 +92,45 @@ Sub-modes:
 - **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
 - **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
 
-### Next-step routing on completion
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== ROADMAP READY ===
+Milestones: {count}
+Phases: {total_phases}
+Strategy: {progressive|direct|auto}
+Output: .workflow/roadmap.md
+--- COMPLETION STATUS ---
+Status: {DONE|DONE_WITH_CONCERNS}
+Concerns: {if any}
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
 
 | 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 formal spec documents | /maestro-blueprint |
-</execution>
+| 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 formal spec documents | `/maestro-blueprint` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/lifecycle/verify.md

@@ -37,7 +37,22 @@ Registers VRF artifact in state.json on completion.
 <context>
 $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 
-Flags (`--skip-tests`, `--skip-antipattern`, `--dir`), scope routing, output paths, and VRF artifact registration schema are defined in workflow `verify.md`.
+### Flags
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--skip-tests` | Skip Nyquist test coverage validation (V2), only run Goal-Backward verification | false |
+| `--skip-antipattern` | Skip anti-pattern scan step | false |
+| `--dir <path>` | Verify a single plan directory instead of milestone-wide | — (milestone mode) |
+
+**Scope routing:**
+| Input | Scope | Resolution |
+|-------|-------|------------|
+| `--dir scratch/{dir}` | single plan | Verify one plan, write verification.json into plan dir |
+| numeric arg | phase | Verify all execute artifacts for that phase |
+| no args | milestone | Aggregate all execute artifacts for current milestone |
+
+Output paths and VRF artifact registration schema are defined in workflow `verify.md`.
 
 ### Pre-load context (before verification)
 
@@ -63,28 +78,48 @@ Follow '~/.maestro/workflows/verify.md' completely.
 
 On confirm → `Skill("spec-add", "<category> <content>")`.
 
-**Next-step routing on completion:**
-- All checks pass, no gaps → /quality-review
-- Gaps found (must-have failures or anti-pattern blockers) → /maestro-plan --gaps
-- Low test coverage (Nyquist gaps) → /quality-auto-test
+</execution>
 
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+<completion>
+### Standalone report
 
-**Completion status:**
 ```
---- COMPLETION STATUS ---
+=== VERIFY COMPLETE ===
 STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
 CONCERNS: {description if applicable}
 NEXT: /quality-review
---- END STATUS ---
+=== END VERIFY ===
 ```
 
 Status mapping:
 - **DONE** — All checks pass, no gaps → NEXT: /quality-review
 - **DONE_WITH_CONCERNS** — Gaps found (must-have failures or anti-pattern blockers) → NEXT: /maestro-execute (after /maestro-plan --gaps)
 - **NEEDS_RETRY** — Verification could not complete (missing artifacts, corrupt data)
-</execution>
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All checks pass, no gaps | `/quality-review` |
+| Gaps found (must-have failures or anti-pattern blockers) | `/maestro-plan --gaps` |
+| Low test coverage (Nyquist gaps) | `/quality-auto-test` |
+
+**Gap-fix closure loop:**
+Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/milestone/audit.md

@@ -21,6 +21,8 @@ Audit milestone completion using the artifact registry. Checks:
 
 Data source: `state.json.artifacts[]` filtered by current milestone.
 Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
+
+Pipeline position: downstream of maestro-verify (all phases verified), upstream of maestro-milestone-complete.
 </purpose>
 
 <required_reading>
@@ -38,19 +40,60 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 - Plan scratch dirs — for task status verification
 
 **Adhoc milestone support (D-008):** When the target milestone has `type == "adhoc"` (or `type` field is missing, defaulting to `"standard"`), the audit skips roadmap.md parsing and phase coverage checks. It only validates artifact chain completeness (PLN→EXC exists) and runs integration checks.
+
+### Pre-load
+
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for integration checks
+2. **Specs**: `maestro spec load --category review` — load review standards for audit
+3. All optional — proceed without if unavailable
+
+### Role Knowledge
+
+1. Browse: `maestro wiki list --category review`
+2. Select entries relevant to milestone integration audit
+3. Load: `maestro wiki load <id1> [id2...]`
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/milestone-audit.md' completely.
 
 Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
-
-**Next-step routing on completion:**
-- Verdict PASS → `/maestro-milestone-complete {milestone}`
-- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
-- Verdict FAIL, incomplete execution → `/maestro-execute`
 </execution>
 
+<completion>
+### Standalone report
+
+```
+=== MILESTONE AUDIT READY ===
+Milestone: {milestone}
+Verdict: {PASS|FAIL}
+Phases audited: {N}
+Integration gaps: {N}
+Report: .workflow/milestones/{milestone}/audit-report.md
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence .workflow/milestones/{milestone}/audit-report.md]
+```
+
+Status verdicts:
+- **DONE** — Audit passed, no gaps found
+- **DONE_WITH_CONCERNS** — Audit passed with minor caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Verdict PASS | `/maestro-milestone-complete {milestone}` |
+| Verdict FAIL, integration gaps | `/maestro-plan --gaps` |
+| Verdict FAIL, incomplete execution | `/maestro-execute` |
+</completion>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|

package/maestro-flow/commands/milestone/complete.md

@@ -13,13 +13,23 @@ allowed-tools:
 ---
 
 <purpose>
-Mark a milestone as complete after its audit has passed. Archives all scratch artifacts to `milestones/{M}/artifacts/`, moves artifact entries from `state.json.artifacts[]` to `milestone_history`, extracts final knowhow, and advances to the next milestone.
+Mark a milestone as complete after its audit has passed. Performs 6-step archival:
+validation → directory archival → artifact history → knowhow extraction → state advancement → cleanup.
+
+Produces `milestones/{M}/artifacts/` archive and `specs/learnings.md` knowhow entries.
+Supports two milestone types: standard (advances to next milestone) and adhoc (self-contained, sets idle).
+
+Pipeline position: downstream of `maestro-milestone-audit` (requires PASS verdict). Upstream of `maestro-milestone-release` (cut a release) or next milestone planning (`maestro-analyze` / `maestro-plan`).
 </purpose>
 
 <required_reading>
 @~/.maestro/workflows/milestone-complete.md
 </required_reading>
 
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when updating milestone_history and advancing state
+</deferred_reading>
+
 <context>
 Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
 
@@ -50,20 +60,52 @@ After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
 
 If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
 
-**Next-step routing on completion:**
-- Cut a release → `/maestro-milestone-release`
-- Next milestone → `/maestro-analyze` or `/maestro-plan 1` (standard milestones only)
-- View state → `/manage-status`
-
 **Adhoc milestone (D-008):** When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set `current_milestone = null`, `status = "idle"`. Adhoc milestones are self-contained — no successor in roadmap chain.
 </execution>
 
+<completion>
+### Standalone report
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone_id}
+Status: ARCHIVED
+Artifacts archived: {count}
+Knowhow extracted: {count} entries
+Next milestone: {next_id | "none (adhoc)"}
+==============================
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Cut a release | `/maestro-milestone-release` |
+| Next milestone (standard) | `/maestro-analyze` or `/maestro-plan 1` |
+| View state | `/manage-status` |
+</completion>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Milestone identifier required | Check arguments |
 | E002 | error | Audit not passed | Run maestro-milestone-audit first |
 | E003 | error | Incomplete artifacts remain | Complete remaining work first |
+| W001 | warning | Knowhow extraction produced 0 entries | Review milestone work for missed learnings |
+| W002 | warning | Wiki-connect found unlinked knowledge islands | Run `/manage-wiki --fix` manually |
 </error_codes>
 
 <success_criteria>

package/maestro-flow/commands/milestone/release.md

@@ -15,6 +15,8 @@ allowed-tools:
 
 <purpose>
 Package a completed milestone into a releasable version. Bumps the project version (e.g. `package.json`, `pyproject.toml`, or language-specific manifest), generates or appends a changelog entry from phase/milestone summaries and git log, creates an annotated git tag, and optionally pushes to the remote. Runs after `/maestro-milestone-complete` has archived the milestone; serves as the final delivery step in the SDLC loop.
+
+Pipeline position: downstream of `/maestro-milestone-complete` (consumes archived milestone + audit verdict). Terminal command — no downstream consumer.
 </purpose>
 
 <required_reading>
@@ -25,11 +27,14 @@ Package a completed milestone into a releasable version. Bumps the project versi
 $ARGUMENTS -- optional explicit version string and flags.
 
 **Flags:**
-- `<version>` -- explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted.
-- `--bump patch|minor|major` -- semver bump relative to the current version (default: `minor`)
-- `--dry-run` -- compute the next version, changelog diff, and tag name without writing files or creating tags
-- `--no-tag` -- skip git tag creation (version bump + changelog only)
-- `--no-push` -- skip `git push --follow-tags` after tagging
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `<version>` | Explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted | — |
+| `--bump patch\|minor\|major` | Semver bump relative to the current version | `minor` |
+| `--dry-run` | Compute the next version, changelog diff, and tag name without writing files or creating tags | `false` |
+| `--no-tag` | Skip git tag creation (version bump + changelog only) | `false` |
+| `--no-push` | Skip `git push --follow-tags` after tagging | `false` |
 
 **State files:**
 - `.workflow/state.json` -- current_milestone, previous release version
@@ -43,6 +48,13 @@ $ARGUMENTS -- optional explicit version string and flags.
 - Working tree must be clean (no uncommitted changes) unless `--dry-run`
 </context>
 
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Decision points**: version bump type (major / minor / patch / custom), changelog review and confirmation
+**Scope guard**: only release decisions; do not prejudge next milestone scope
+</interview_protocol>
+
 <execution>
 Follow '~/.maestro/workflows/milestone-release.md' completely.
 
@@ -55,7 +67,12 @@ Follow '~/.maestro/workflows/milestone-release.md' completely.
 6. Create annotated git tag `v{version}` with release notes body (unless `--no-tag`)
 7. Push commit + tag to remote (unless `--no-push`)
 
-**Report format on completion:**
+For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<completion>
+### Standalone report
+
 ```
 === RELEASE COMPLETE ===
 Version:   v{previous} → v{new}
@@ -63,14 +80,28 @@ Milestone: {milestone_name}
 Tag:       v{new} {pushed|local-only}
 Changelog: {N} entries written to CHANGELOG.md
 Manifest:  {file_path} updated
+```
+
+### Ralph-invoked completion
 
-Next steps:
-  /maestro-plan {next_phase}   -- Start next milestone's first phase
-  /manage-status               -- View project dashboard
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 ```
 
-For `--dry-run`, print the computed version, changelog diff, and tag name without side effects.
-</execution>
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Release successful, starting next milestone | `/maestro-plan {next_phase}` |
+| Want to view project dashboard | `/manage-status` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"