maestro-flow 0.4.10 → 0.4.12

package/.codex/skills/maestro-amend/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: maestro-amend
+description: Generate overlays to fix workflow command deficiencies
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+allowed-tools: Read, Write, Bash, Glob, Grep, request_user_input
+---
+<purpose>
+Signal-driven overlay generator — collect workflow deficiency signals from multiple sources, diagnose which commands need amendment, batch-generate targeted overlays. All amendments use overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
+
+Differs from `/maestro-overlay` (single explicit intent). This command **discovers** what needs amending by analyzing workflow artifacts.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+$ARGUMENTS — optional description and/or source flags.
+
+**Signal sources**:
+
+| Flag | Source | Collects |
+|------|--------|----------|
+| `--from-verify <dir>` | verification.json | Workflow gaps from verify failures |
+| `--from-review <dir>` | review.json | Process deficiencies from code review |
+| `--from-session <id>` | Session artifacts | Problems during workflow execution |
+| `--from-issues ISS-xxx,...` | issues.jsonl | Issues tracing to command deficiency |
+| `--scan` | Auto-scan .workflow/ | Discover all workflow-related signals |
+| _(positional text)_ | User description | Direct observation |
+
+Multiple combinable. No flags + no description → interactive (scan + AskUserQuestion).
+
+**Control**: `--dry-run` (preview, don't install), `-y` (skip confirmations)
+
+**CLI targeting**: `"cli": "claude"` (default, patches .claude/commands/), `"codex"` (patches .codex/skills/), `"both"` (both paths)
+
+**Output**: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`
+</context>
+
+<state_machine>
+
+<states>
+S_COLLECT      — 收集信号（从 flags / scan / description）    PERSIST: —
+S_DIAGNOSE     — 映射信号到命令补丁                           PERSIST: —
+S_GROUP        — 分组、规划 overlay 粒度                      PERSIST: —
+S_PREVIEW      — 展示注入点地图、用户确认                     PERSIST: —
+S_DRAFT        — 生成 overlay JSON                            PERSIST: overlay files
+S_INSTALL      — 安装 overlay                                 PERSIST: command files
+S_REPORT       — 报告摘要 + post-patch routing                PERSIST: —
+</states>
+
+<transitions>
+
+S_COLLECT:
+  → S_DIAGNOSE    WHEN: signals found                      DO: A_COLLECT_SIGNALS
+  → ERROR(E001)   WHEN: no signals from any source
+
+S_DIAGNOSE:
+  → S_GROUP       WHEN: command deficiencies identified     DO: A_DIAGNOSE_SIGNALS
+  → ERROR(E003)   WHEN: all signals are code bugs (not command gaps)
+
+S_GROUP:
+  → S_PREVIEW     DO: A_GROUP_OVERLAYS
+
+S_PREVIEW:
+  → S_DRAFT       WHEN: user confirms "Apply all" or selects patches
+  → S_PREVIEW     WHEN: user selects "Edit"                DO: modify signal target/section
+  → END           WHEN: user cancels
+
+S_DRAFT:
+  → S_INSTALL     WHEN: not --dry-run                      DO: A_DRAFT_OVERLAYS
+  → END           WHEN: --dry-run                          DO: display JSON + section map preview
+
+S_INSTALL:
+  → S_REPORT      DO: A_INSTALL_OVERLAYS (`maestro overlay add`, retry max 2 on validation failure)
+
+S_REPORT:
+  → END           DO: display summary (signals collected/applied/skipped, overlay details, skipped code-bug routing)
+
+</transitions>
+
+<actions>
+
+### A_COLLECT_SIGNALS
+
+**If source flags**: extract signals from each specified source.
+**If --scan or interactive**: scan .workflow/ for:
+- verification.json → must_have_failures, anti_patterns (filter for command gap direction)
+- review.json → findings tagged "process" or "workflow"
+- debug understanding.md → root causes with workflow/command cause_type
+- issues.jsonl → status=open AND tags include "workflow"/"command"
+- execution summaries → plan deviations suggesting missing command step
+
+**If only description**: parse for affected command(s), what's missing, expected behavior.
+
+### A_DIAGNOSE_SIGNALS
+
+Per signal, determine:
+- signal_id, source, description, target_command, target_section, patch_mode, fix_direction, severity
+
+**Section mapping**:
+
+| Signal pattern | Section | Mode |
+|---------------|---------|------|
+| Missing pre-check/gate | execution | prepend |
+| Missing post-step/verification | execution | append |
+| Missing reading/context | required_reading / deferred_reading | append |
+| Incomplete success criteria | success_criteria | append |
+| Missing error handling | error_codes | append |
+| Scope/context gap | context | append |
+| Entirely new concern | _(new section)_ | new-section |
+
+Read pristine source from `$PKG_ROOT/.claude/commands/<name>.md` to confirm section.
+Classify: command deficiency → proceed; code bug → skip (suggest /maestro-quick).
+
+### A_GROUP_OVERLAYS
+
+Group by target command + section (merge same command+section).
+Granularity: 1-2 signals → `patch-{command}-{slug}.json`; 3+ cross-command → `amend-{slug}.json`.
+Read target commands to verify sections exist, check existing overlays.
+
+Display section map with injection points per target command.
+
+### A_DRAFT_OVERLAYS
+
+Build overlay JSON per schema: name, description, targets[], cli, priority (60), enabled, patches[{section, mode, content}].
+Content rules: heading includes `(patch: SIG-NNN)`, concise, supplementary doc to `~/.maestro/overlays/docs/` if >10 lines.
+
+### A_INSTALL_OVERLAYS
+
+```bash
+maestro overlay add ~/.maestro/overlays/amend-{slug}.json
+```
+On validation failure: fix JSON, retry (max 2).
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | No signals from any source | Verify artifact paths or provide description |
+| E003 | All signals are code bugs, not command gaps | Use /maestro-quick or /maestro-plan --gaps |
+| E004 | Overlay validation failed after 2 retries | Review JSON manually |
+| W001 | Some signals skipped (code bugs) | Route to appropriate fix command |
+| W002 | Target command has >= 3 existing overlays | Consider consolidating |
+</error_codes>
+
+<success_criteria>
+- [ ] Signals classified: command deficiency vs code bug
+- [ ] Pristine command sources read to verify injection points
+- [ ] Section map with injection points confirmed by user
+- [ ] Overlay JSON installed successfully; command files contain overlay markers
+- [ ] Skipped code-bug signals routed to alternatives
+</success_criteria>

package/.codex/skills/maestro-analyze/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
@@ -10,6 +10,12 @@ Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topol
 Wave 1 (CLI exploration, parallel) -> Wave 2 (6-dimension scoring, parallel) -> Wave 3 (decision synthesis).
 
 **Tri-depth**: Full mode (all 3 waves), Quick mode (`-q`, Wave 3 only), Gaps mode (`--gaps`, issue root cause pipeline).
+
+**Dual-layer scope (D-003)**:
+- **Macro layer** (text argument, e.g. `analyze "auth refactor"`): broad impact exploration. Produces `scope_verdict ∈ {small, medium, large}` to drive downstream routing (roadmap vs plan).
+- **Phase layer** (numeric argument, e.g. `analyze 1`): phase-scoped deep analysis under `current_milestone`. Milestone resolved via D-007 `phase_slugs` reverse lookup, NEVER direct `current_milestone` read.
+
+Produces context-package.json (standardized cross-command context contract) in all modes.
 </purpose>
 
 <context>
@@ -21,11 +27,26 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 - `--continue`: Resume existing session
 - `-q, --quick`: Skip exploration + scoring, Wave 3 only
 - `--gaps [ISS-ID]`: Issue root cause analysis. If ISS-ID: single issue. If omitted: all open/registered from issues.jsonl.
+- `--from <source>`: Load upstream context package (brainstorm:ID, analyze:ID, @file, or path). Resolves to context-package.json for upstream context inheritance.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/`
-**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md (all modes), analysis.md + conclusions.json (full mode only)
+**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, context-package.json (all modes), analysis.md + conclusions.json (full mode AND quick mode; quick writes minimal conclusions.json with `scope_verdict` + `implementation_scope[]` only)
 </context>
 
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--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; every question must include a `Proceed now` option so the user can end the interview at any time.
+- Never ask what code can verify — resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, or Read.
+- 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: on `Proceed now` or when all decision points are settled, write the table below into `context.md` under an `Interview Decisions` section (and mirror into `analysis.md` in full mode):
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <csv_schema>
 
 ### tasks.csv
@@ -62,7 +83,9 @@ Available exploration dimensions: architecture, implementation, performance, sec
 5. **Quick mode shortcut**: -q generates only wave 3 task
 6. **Gaps mode pipeline**: --gaps follows: Load issues from issues.jsonl -> Classify & group by location/component -> CSV gen (W1: 1 explore row per issue, W2: 1 synthesis per group) -> Execute waves -> Write issue.analysis record per issue -> Append history `{ action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }` -> Output context.md for plan --gaps
 7. **Graceful degradation**: Missing exploration reduces scoring quality; missing scoring reduces synthesis quality
-8. **Tri-output**: context.md always. analysis.md + conclusions.json full-mode only. Gaps mode writes to issues.jsonl + context.md
+8. **Tri-output**: context.md + context-package.json always. analysis.md (full only) + conclusions.json (full + quick — quick writes minimal with `scope_verdict` + `implementation_scope[]`). Gaps mode writes to issues.jsonl + context.md + context-package.json
+9. **D-007 milestone resolution**: numeric scope MUST reverse-lookup `state.json.milestones[].phase_slugs`. NEVER read `current_milestone` directly for phase-scoped artifact registration.
+10. **scope_verdict mandatory** (D-003): macro/adhoc/standalone scopes MUST produce `scope_verdict ∈ {small, medium, large}` in conclusions.json. Drives downstream chain (roadmap vs plan).
 </invariants>
 
 <state_machine>
@@ -80,21 +103,30 @@ S_AGGREGATE  -- 注册 artifact、输出摘要                    PERSIST: state
 <transitions>
 
 S_PARSE:
-  -> S_CONTEXT    WHEN: scope resolved (milestone/phase/adhoc/standalone/gaps)
+  -> S_CONTEXT    WHEN: scope resolved (milestone/phase/macro/adhoc/standalone/gaps)
   -> ERROR(E001)  WHEN: no args and no roadmap
 
-  **Scope routing**:
-  | Condition | Scope | Slug |
-  |-----------|-------|------|
-  | --gaps flag | gaps | ISS-ID slugified or "issue-gaps" |
-  | Empty subject + milestone + roadmap | milestone | milestone name slugified |
-  | Empty subject, no roadmap | ERROR E001 | -- |
-  | Numeric + milestone + roadmap | phase | phase slug from roadmap |
-  | Text subject + milestone | adhoc | subject slugified (max 40) |
-  | Text subject, no milestone | standalone | subject slugified (max 40) |
+  **Scope routing** (text → macro layer, numeric → phase layer per D-003):
+  | Condition | Scope | Layer | Slug |
+  |-----------|-------|-------|------|
+  | --gaps flag | gaps | — | ISS-ID slugified or "issue-gaps" |
+  | Empty subject + milestone + roadmap | milestone | phase | milestone name slugified |
+  | Empty subject, no roadmap | ERROR E001 | — | -- |
+  | Numeric + milestone + roadmap | phase | phase | phase slug from roadmap |
+  | Text subject + milestone | macro | macro | subject slugified (max 40) |
+  | Text subject, no milestone | macro | macro | subject slugified (max 40) |
+
+  **D-007 milestone reverse lookup** (numeric scope only):
+  ```
+  resolve_milestone(phase_number):
+    for ms in state.json.milestones[]:
+      if str(phase_number) in ms.phase_slugs: return ms.id
+    return state.json.current_milestone   # fallback (standalone)
+  ```
+  Write resolved milestone into `session.milestone` and artifact registration; NEVER use `current_milestone` directly for phase-scoped runs.
 
 S_CONTEXT:
-  -> S_CSV_GEN    DO: load project.md, roadmap.md, state.json, prior artifacts, specs
+  -> S_CSV_GEN    DO: load project.md, roadmap.md, state.json, prior artifacts, specs, upstream context-package (if --from)
 
 S_CSV_GEN:
   -> S_WAVE_1     WHEN: full mode         DO: generate N explore + 6 score + 1 synthesis rows
@@ -144,9 +176,18 @@ Merge results -> master tasks.csv.
 Filter wave==3 -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn.
 
 **Synthesis agent**:
-- Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), conclusions.json
-- Quick mode: context.md only from available project context
-- Gaps mode: per-issue analysis records -> issues.jsonl + context.md for plan --gaps
+- Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), context-package.json, conclusions.json (with `scope_verdict` + `implementation_scope[]`)
+- Quick mode: context.md + context-package.json + **minimal conclusions.json** (`scope_verdict` + `implementation_scope[]` only — seeds plan task generation per redesign §8.3)
+- Gaps mode: per-issue analysis records -> issues.jsonl + context.md + context-package.json for plan --gaps
+
+**`scope_verdict` evaluation** (D-003 §5.3, macro/standalone/adhoc scopes only):
+| Verdict | Criteria |
+|---------|----------|
+| `large` | 3+ independent subsystems, OR hard dependencies requiring serialized verification points |
+| `medium` | 1-2 subsystems, parallel-safe |
+| `small` | Single file or few files, directly executable |
+
+Write to `conclusions.json.scope_verdict` (all modes that produce conclusions); mirror into `context.md` and `context-package.json.source.scope_verdict`. Phase-scoped runs may omit (default null).
 
 Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specific (skip prior decided areas).
 
@@ -156,17 +197,19 @@ Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specif
 2. **Confidence scoring** (full mode): factors -- findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Thresholds: <60% deeper, 60-80% optional, 80-95% converging, >95% converge.
 3. Auto-create issues from Deferred items -> issues.jsonl
 4. Spec enrichment: Locked decisions -> `maestro spec add arch`; code patterns -> `maestro spec add coding`
-5. Register artifact in state.json (type: analyze)
+5. Register artifact in state.json (type: analyze, includes context_package field pointing to context-package.json)
 6. Copy outputs to scratchDir, display summary
-7. **Next-step routing**:
+7. **Next-step routing** (D-003 §5.3 — macro scope uses `scope_verdict` for downstream chain selection):
 
    | Scope | Condition | Next |
    |-------|-----------|------|
    | Phase/Milestone | Go + UI work needed | `$maestro-impeccable build {target}` |
    | Phase/Milestone | Go + ready to plan | `$maestro-plan` or `$maestro-plan {phase}` |
    | Phase/Milestone | No-Go | `$maestro-brainstorm {topic}` |
-   | Adhoc/Standalone | Ready to plan | `$maestro-plan --dir {scratch_dir}` |
-   | Adhoc/Standalone | Need more exploration | `$maestro-analyze {topic} --continue` |
+   | Macro/Adhoc/Standalone | `scope_verdict == "large"` | `$maestro-roadmap --from analyze:{ANL_ID}` |
+   | Macro/Adhoc/Standalone | `scope_verdict == "medium"` | `$maestro-plan --from analyze:{ANL_ID}` |
+   | Macro/Adhoc/Standalone | `scope_verdict == "small"` | `$maestro-plan --from analyze:{ANL_ID}` |
+   | Macro/Adhoc/Standalone | Need more exploration | `$maestro-analyze {topic} --continue` |
    | Gaps | Issues analyzed | `$maestro-plan --gaps` |
    | Gaps | Need more context | `$maestro-analyze --gaps {ISS-ID}` |
 
@@ -201,8 +244,12 @@ Protocol: read before analysis, append-only, dedup by type+key.
 </error_codes>
 
 <success_criteria>
+- [ ] Interactive mode: interview decision table written to `context.md` "Interview Decisions" (mirrored into `analysis.md` in full mode)
 - [ ] All waves executed in order (or skipped per mode)
-- [ ] context.md produced (all modes); analysis.md + conclusions.json (full mode)
+- [ ] context.md produced (all modes); analysis.md (full mode); conclusions.json (full mode AND quick mode with at minimum `scope_verdict` + `implementation_scope[]`)
+- [ ] context-package.json produced (all modes) with constraints, requirements, insights, open_questions
+- [ ] `scope_verdict ∈ {small, medium, large}` written into conclusions.json + context.md (macro/adhoc/standalone scopes)
+- [ ] D-007 milestone reverse lookup applied for numeric scope; `session.milestone` populated via `phase_slugs`, never via direct `current_milestone` read
 - [ ] context.md contains all decisions classified as Locked/Free/Deferred
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Confidence scored per dimension with factor-based model (full mode)
@@ -210,7 +257,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Pressure pass completed ≥ 1 time on highest-risk dimension before synthesis
 - [ ] Deferred items auto-created as issues
 - [ ] Scope creep redirected to Deferred section
-- [ ] Artifact registered in state.json
+- [ ] Artifact registered in state.json (includes context_package field)
+- [ ] Upstream context loaded via `--from` when specified
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
 </success_criteria>

package/.codex/skills/maestro-blueprint/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: maestro-blueprint
+description: Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 7-phase document chain (P0 Spec Study → P1 Discovery → P1.5 Req Expansion → P2 Product Brief → P3 PRD → P4 Architecture → P5 Epics → P6 Readiness Check)
+argument-hint: "<idea or @file> [-y] [-c] [--from <source>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, spawn_agents_on_csv, request_user_input
+---
+<purpose>
+Formal specification document chain producing a complete specification package through 7 sequential phases (P0–P6, plus P1.5 requirement expansion) with multi-CLI analysis and interactive refinement. Pure documentation — no code generation, no roadmap generation.
+
+Parallel to `brainstorm` as an upstream origin command:
+- **brainstorm** = divergent exploration (lightweight, multi-role creative)
+- **blueprint** = convergent documentation (heavyweight, 7-phase formal spec chain)
+
+Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD, Architecture, and Epics.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/blueprint.md
+</required_reading>
+
+<deferred_reading>
+- [blueprint-config.json](~/.maestro/templates/blueprint-config.json) — read when initializing blueprint configuration
+</deferred_reading>
+
+<context>
+$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`)
+
+**Input types:**
+- Direct text: `"Build a real-time collaboration platform with WebSocket"`
+- File reference: `@requirements.md`
+- Context import: `--from brainstorm:BRN-001` or `--from @requirements.md` or `--from path/`
+- Resume: `-c` (resumes from first incomplete phase)
+
+**Pipeline position:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md / context-package.json
+maestro-blueprint
+        ↓ .workflow/blueprint/BLP-{slug}-{date}/
+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.
+</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 request_user_input and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total, and a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, existing artifacts, `maestro spec load`, or direct codebase exploration (Glob/Grep/Read) instead of prompting.
+- 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 `Proceed now`, persist decisions in blueprint-config.json and proceed to Phase 1.
+</interview_protocol>
+
+<execution>
+Follow `~/.maestro/workflows/blueprint.md` completely.
+
+### Phase chain
+
+```
+P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief → P3: PRD → P4: Architecture → P5: Epics → P6: Readiness Check
+```
+
+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
+
+| 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>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Idea text or @file required | Prompt user for input |
+| E002 | error | Context source not found (--from) | Show available sessions/sources |
+| E006 | error | `.workflow/` not initialized | Run maestro-init first |
+| E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| 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 |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+</error_codes>
+
+<success_criteria>
+- [ ] Interactive mode: interview decisions persisted in blueprint-config.json
+- [ ] `blueprint-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
+- [ ] `blueprint-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
+- [ ] Artifact registered in state.json (type=blueprint)
+- [ ] context-package.json generated for downstream consumption
+</success_criteria>