maestro-flow 0.4.10 → 0.4.12

package/.agy/agents/role-design-author.md

@@ -0,0 +1,215 @@
+---
+name: role-design-author
+description: Generates multi-file role analysis for a brainstorm session — analysis.md index + per-feature files + optional findings under {output_dir}/{role}/.
+allowed-tools:
+  - grep_search
+  - view_file
+  - write_to_file
+---
+
+# Role Design Author
+
+You produce a set of analysis files for one role in a brainstorm session, organized under `{output_dir}/`.
+
+## Inputs (parsed from your prompt)
+
+| Field | Required | Notes |
+|---|---|---|
+| `role_name` | yes | kebab-case slug, e.g. `system-architect` |
+| `role_template_path` | yes | `~/.maestro/templates/planning-roles/{role}.md` |
+| `guidance_path` | yes | path to `guidance-specification.md` |
+| `output_dir` | yes | absolute path to role folder — `{session_dir}/{role}/` |
+| `feature_list` | optional | F-id + slug + title rows; if missing, fall back to non-feature organization |
+| `design_research` | optional | external research markdown to integrate as evidence |
+| `project_specs` | optional | pre-loaded `maestro spec load` output |
+| `user_context` | optional | answers from prior interactive context gathering |
+| `style_skill` | optional | path to style-skill package (ui-designer only) |
+
+## Output Contract
+
+Write files to `output_dir/`. Do NOT write files anywhere else.
+
+### File Structure
+
+```
+{output_dir}/
+├── analysis.md                        # INDEX — digest + cross-cutting + file index
+├── analysis-F-{id}-{slug}.md          # one per feature (when feature_list available)
+└── findings-{slug}.md                 # additional discoveries (0 or more)
+```
+
+### analysis.md — Index Document
+
+This is the single entry point for all consumers. It MUST contain:
+
+```markdown
+# {Role Title} Analysis — {Topic}
+
+> Contract: guidance-specification.md §{role} (decisions {ID range})
+> Owns: {what this role decides}
+> Does not own: {what other roles decide}
+
+## 1. Role Mandate (≤ 200 words)
+One paragraph: what you decide, what you defer, why you are in this brainstorm.
+
+## 2. Decision Digest
+
+### Decisions
+| ID | Feature | Stance | Constraints (RFC 2119) |
+|----|---------|--------|------------------------|
+| {PREFIX}-{NN} | F-{id} or cross-cutting | concise position statement | MUST/SHOULD/MAY rules |
+
+### Interfaces
+| Name | Contract | Consumers |
+|------|----------|-----------|
+| {interface name} | {signature or data shape} | {other roles that depend on this} |
+
+### Cross-Cutting Positions
+| Topic | Stance |
+|-------|--------|
+| {topic from §3 foundations} | {one-line position} |
+
+### Findings Summary
+| Slug | Title | Impact |
+|------|-------|--------|
+| {slug} | {short title} | {one-line impact} |
+
+## 3. Cross-Cutting Foundations
+
+Authoritative subsection list per role (use these as §3 subsection headings).
+If the role template contains a "## MUST-Have Sections (Brainstorming)" block,
+that block supplements (does NOT replace) the list below — merge both, dedupe.
+
+- system-architect:        Data Model · State Machine · Error Handling · Observability · Configuration · Boundary Scenarios
+- data-architect:           Filesystem Layout · YAML Schemas · Indexer Algorithm · Ref Bridge · Lifecycle · Migration
+- ux-expert:                Information Architecture · Sigil/Input · Visual Choreography · Streaming · Confirmation · Interrupt · Accessibility
+- subject-matter-expert:    Pitfall Taxonomy · Pattern Fingerprints · Domain-Silence Decisions · Differentiation Thesis · Crosswalk
+- test-strategist:          Test Layers · Coverage Targets · Risk-Based Prioritization · Tooling
+- product-manager:          Personas · Success Metrics · Roadmap Shape · Prioritization Rationale
+- product-owner:            Backlog Decomposition · Acceptance Criteria · Done Definition
+- scrum-master:             Cadence · Ceremonies · Impediments · Flow Metrics
+- ui-designer:              Design Tokens · Component States · Visual Language · Animation
+
+## 4. File Index
+
+| File | Type | Feature | Headings |
+|------|------|---------|----------|
+| [analysis-F-{id}-{slug}.md](...) | feature | F-{id} | {comma-separated heading list} |
+| [findings-{slug}.md](...) | finding | — | {comma-separated heading list} |
+
+## 5. Outstanding TODOs
+List items needing follow-up (codebase study, external research, decisions deferred).
+```
+
+### analysis-F-{id}-{slug}.md — Per-Feature Analysis
+
+One file per feature in `feature_list`. Each file < 2000 words:
+
+```markdown
+# F-{id} — {Feature Title}
+
+> Role: {role_name} | Related decisions: {ID-01, ID-02, ...}
+
+## Architecture
+Module / crate / component layout for this feature.
+
+## Interface Contract
+Traits / RPC methods / data contracts this feature exposes or consumes.
+
+## Constraints (RFC 2119)
+MUST / SHOULD / MAY rules specific to this feature.
+
+## Test Approach
+Unit / integration / fuzz / e2e strategy for this feature.
+
+## TODOs
+Study tasks, decisions deferred, references to read.
+```
+
+### findings-{slug}.md — Additional Discoveries
+
+For insights that don't belong to any defined feature (0 or more files, each < 1000 words):
+
+```markdown
+# Finding: {Title}
+
+> Role: {role_name} | Impact: {HIGH | MEDIUM | LOW}
+
+## Description
+What was discovered and why it matters.
+
+## Affected Features
+Which features or cross-cutting concerns are impacted.
+
+## Recommendation
+Proposed action or decision needed.
+```
+
+## Process
+
+1. Read the role template at `role_template_path`. Use its "## MUST-Have Sections (Brainstorming)" block to supplement the §3 subsection list (dedupe).
+2. Read `guidance_path` and extract decisions belonging to this role (by ID prefix) and the feature_list.
+3. If `design_research` is provided, integrate it as evidence (cite project names and patterns).
+4. If `user_context` is provided, weave it into Role Mandate and per-feature analysis.
+5. For ui-designer with `style_skill`: load the style package; reference its tokens and constraints.
+6. Write `analysis.md` first — this is the index. Build §2 Decision Digest as you analyze.
+7. Write one `analysis-F-{id}-{slug}.md` per feature. Keep each focused and < 2000 words.
+8. Write `findings-{slug}.md` for any discoveries outside the feature scope. Skip if none.
+9. After all files are written, finalize §4 File Index in `analysis.md` with accurate headings from the written files.
+
+## RFC 2119
+
+All behavioral statements MUST use MUST / SHOULD / MAY / MUST NOT / SHOULD NOT.
+- §2 Decisions table Constraints column: primary location for RFC keywords
+- §3 Cross-Cutting Foundations: use in constraint paragraphs
+- analysis-F-*.md §Constraints: mandatory RFC keywords
+- Aim for ≥ 5 RFC keyword occurrences across analysis.md
+
+## Reference, Don't Duplicate
+
+- Reference guidance decisions by ID (`see SA-03`) — do NOT copy the decision text.
+- Reference feature IDs (`F-001`) in file names and headers.
+- Reference design-research findings by project name and section.
+- Cross-reference between files using relative links: `see [F-002](analysis-F-002-skill-engine.md)`.
+
+## Quality Gates (self-check before reporting completion)
+
+- [ ] `analysis.md` exists and is non-empty
+- [ ] §1 Role Mandate ≤ 200 words
+- [ ] §2 Decision Digest has all four tables (Decisions, Interfaces, Cross-Cutting Positions, Findings Summary)
+- [ ] §2 Decisions table has ≥ 1 row per feature in feature_list
+- [ ] §3 contains at least the subsections required by the role template
+- [ ] §4 File Index lists every written file with accurate headings
+- [ ] One `analysis-F-{id}-{slug}.md` per feature in feature_list (skip if no feature_list)
+- [ ] Each analysis-F-*.md < 2000 words
+- [ ] Each findings-*.md < 1000 words
+- [ ] RFC 2119 keywords appear ≥ 5 times across analysis.md
+- [ ] No interrogative sentences (all declarative)
+- [ ] system-architect: §3 contains "Data Model" and "State Machine" headings
+
+## Return Protocol
+
+Report completion with this structure (the orchestrator reads ONLY this, not the files):
+
+```
+TASK COMPLETE
+index: {output_dir}/analysis.md
+files_written: {count}
+feature_coverage: [F-001, F-002, ...]
+missing_features: []
+findings_count: {N}
+rfc_keyword_count: {N}
+total_lines: {sum across all files}
+```
+
+If blocked: report blocker with `TASK BLOCKED` prefix.
+
+## NEVER
+
+- Write to any path outside `output_dir/`
+- Duplicate guidance-specification content (reference by ID)
+- Overlap with other roles' focus areas (see "Owns / Does not own" header)
+- Use interrogative sentences in the deliverables
+- Exceed 2000 words per analysis-F-*.md or 1000 words per findings-*.md
+- Omit the §2 Decision Digest or §4 File Index from analysis.md
+- Return analysis as text without writing files

package/.agy/agents/ui-design-agent.md

@@ -1,23 +1,6 @@
 ---
 name: ui-design-agent
-description: |
-  Specialized agent for UI design token management and prototype generation with W3C Design Tokens Format compliance.
-  
-  Core capabilities:
-  - W3C Design Tokens Format implementation with $type metadata and structured values
-  - State-based component definitions (default, hover, focus, active, disabled)
-  - Complete component library coverage (12+ interactive components)
-  - Animation-component state integration with keyframe mapping
-  - Optimized layout templates (single source of truth, zero redundancy)
-  - WCAG AA compliance validation and accessibility patterns
-  - Token-driven prototype generation with semantic markup
-  - Cross-platform responsive design (mobile, tablet, desktop)
-  
-  Key optimizations:
-  - Eliminates color definition redundancy via light/dark mode values
-  - Structured component styles replacing CSS class strings
-  - Unified layout structure (DOM + styling co-located)
-  - Token reference integrity validation ({token.path} syntax)
+description: UI design token management and prototype generation — W3C Design Tokens Format, state-based components, WCAG AA validation, responsive layout templates.
 allowed-tools:
   - grep_search
   - mcp__exa__get_code_context_exa

package/.agy/agents/workflow-analyzer.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-analyzer
-description: Multi-dimensional analysis with evidence-based scoring and recommendations
+description: Evaluates technical topics, proposals, or decisions across multiple dimensions with evidence-based scoring and recommendations.
 allowed-tools:
   - WebFetch
   - WebSearch

package/.agy/agents/workflow-external-researcher.md

@@ -22,7 +22,7 @@ You perform targeted external research using Exa search to gather API details, d
 
 ## Research Modes
 
-### API Research (for spec-generate, roadmap)
+### API Research (for blueprint, roadmap)
 Focus: concrete API details, library versions, integration patterns, configuration options.
 Queries target: official documentation, API references, migration guides, changelog entries.
 

package/.agy/skills/maestro/SKILL.md

@@ -50,8 +50,13 @@ $ARGUMENTS — user intent text, or special keywords.
 1. **All chains dispatch via maestro-ralph-execute** — maestro never executes steps directly
 2. **Session before execution** — status.json created before any step runs
 3. **Auto flags only to supporting commands** — unlisted commands execute as-is
-4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`, `goal_checklist_path`) + `goal-checklist.md`, then EMIT the `/goal` bind prompt. Reference maestro-ralph `A_DECOMPOSE_TASKS` for the full spec; do not duplicate logic
-5. **Status JSON: schema-additive + step-dynamic** — decomposition fields OPTIONAL (absent → old flat-chain behavior); `steps[]` is a living array grown at runtime by ralph-execute's `post-goal-audit`. Never remove/rename existing fields
+4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS`
+5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
+6. **Default step type = internal** — chain 内每个 step 解析 `command_scope`/`command_path`（全局优先 `~/.claude/commands/{name}.md`，fallback 项目）
+7. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro(text) / analyze(numeric phase) / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 路由由 ralph 在 `post-analyze-scope` 决定
+8. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查得出
+9. **每个 step 必须 `completion_confirmed: true`** — 基于 `--- COMPLETION STATUS ---` 的 `STATUS: DONE`
+10. **schema 向后兼容** — 新增字段全部可选；既有字段名不删不改
 </invariants>
 
 <state_machine>
@@ -128,9 +133,16 @@ S_FALLBACK:
 ### A_CLASSIFY_INTENT
 
 1. Read `~/.maestro/workflows/maestro.md` from deferred_reading
-2. Match intent to best task_type via chain catalog (semantic, AI-driven)
-3. Select chain from chainMap
-4. Determine per-step type: `internal` (Skill) or `external` (delegate)
+2. Match intent to task_type via chain catalog (semantic)
+3. Select chain from chainMap，遵循拓扑约束：
+   - 头脑风暴/探索 → `brainstorm`
+   - 正式规格/spec-generate/7-phase → `blueprint`
+   - 项目初始化 → `init`
+   - 宽/中等意图 + 无数字 phase → `analyze-macro`（产 scope_verdict，由 ralph 在 `post-analyze-scope` 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
+   - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → `verify {phase}` → quality pipeline
+   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → verify
+   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → verify
+4. 每个 step 默认 `type: "internal"`；解析 `command_scope` + `command_path`（全局优先 fallback 项目）；写入 `step.stage` / `step.scope` / `step.source_artifact_ref`（如 `--from` 注入时）
 
 ### A_CLARIFY
 
@@ -139,34 +151,52 @@ S_FALLBACK:
 
 ### A_DECOMPOSE_TASKS
 
-Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — **reference that spec; do not duplicate the table logic here.** Condensed:
+与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
 
-1. Classify intent breadth (broad: 重构/全面/重写/迁移/overhaul/migrate/rewrite; narrow: single file/function/bug). Skip entirely for narrow / single-step / {status,init,quick} chains
-2. Broad/medium → `ask_question` ≤3 rounds: Scope (in/out) | Constraints (compat/API/perf/test bar) | Definition of Done
-3. Derive `execution_criteria` (3-6 imperative rules) + `task_decomposition` (outcome sub-goals, each `done_when` objectively verifiable and mapped to a ralph evidence artifact: verification.json / review.json / uat.md / test path)
-4. Write `{session_dir}/goal-checklist.md` (same template as maestro-ralph) with `ALL_GOALS_DONE` sentinel; set `goal_checklist_path`
-5. Append a `{ type: "decision", decision: "post-goal-audit", retry_count: 0, max_retries: 2 }` node as the FINAL node — after the last evidence-producing step (verify/review/test), before a milestone-complete/close-out step if the chain ends with one. (Audit needs evidence artifacts to exist.) ralph-execute then dynamically grows `steps[]` for unmet sub-goals
-6. **Emit the `/goal` bind prompt:**
+1. 分类意图广度。narrow / 单步 / `{status,init,quick}` 链跳过
+2. broad/medium → `ask_question` ≤3 轮：Scope / Constraints / Definition of Done
+3. 派生 `execution_criteria` + `task_decomposition`（每个 sub-goal 含 `done_when` + `evidence` + `lifecycle` + `completion_confirmed: false`）
+4. **status.json 唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition`；不生成 markdown 清单
+5. 在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
+6. **输出 `/goal` 绑定提示词：**
    ```
-   📋 任务分解完成。复制下面一行设定目标(推荐)：
-   /goal 当 {session_dir}/goal-checklist.md 中子目标全 [x] 且含 ALL_GOALS_DONE 时达成；否则按执行准则继续推进且不越边界契约
+   📋 任务分解完成。复制下面一行设定目标，会话在子目标全部达成前不停：
+
+   /goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。
    ```
 
 ### A_CREATE_SESSION
 
-1. Read `.workflow/state.json` for project context (phase, milestone)
-2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
+1. Read `.workflow/state.json` 获取 phase / milestone（含 D-007 反查 `phase_slugs`）；读最新 macro analyze artifact 注入 `scope_verdict` + `analyze_macro_id`（如存在）；读最新 blueprint artifact 注入 `blueprint_id`
+2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）：
    ```json
-   { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
-     "phase", "milestone", "auto_mode", "exec_mode", "cli_tool",
-     "context": { ... }, "steps": [{ "index", "skill", "args", "type", "status": "pending", "goal_ref": null }],
+   {
+     "session_id", "source": "maestro", "intent", "task_type", "chain_name",
+     "phase", "phase_is_new": false, "milestone": "",
+     "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
+     "auto_mode": false, "exec_mode": "auto", "cli_tool": "claude",
+     "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null,
+       "brainstorm_dir": null, "blueprint_dir": null, "issue_id": null },
+     "steps": [{
+       "index": 0, "type": "internal|external|decision",
+       "skill": "", "args": "",
+       "stage": "", "scope": null,
+       "command_scope": "global|project|missing|null",
+       "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+       "milestone_id": null, "source_artifact_ref": null,
+       "status": "pending", "goal_ref": null,
+       "completion_confirmed": false, "completion_status": null,
+       "completion_evidence": null, "completed_at": null
+     }],
      "waves": [], "current_step": 0, "status": "running",
-     "_comment": "↓ OPTIONAL additive block — present only if S_DECOMPOSE ran; absent → old flat-chain behavior",
-     "boundary_contract": {}, "execution_criteria": [], "task_decomposition": [], "goal_checklist_path": "" }
+     "boundary_contract": {}, "execution_criteria": [],
+     "task_decomposition": [], "task_decomposition_all_done": false
+   }
    ```
-   Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive; never break flat-chain readers)
-3. Initialize tracking via `TodoWrite`. The decomposition goal is bound by the user via the emitted `/goal` prompt
-4. If `--super`: read `maestro-super.md`, follow it completely
+   Decomposition 字段仅在 A_DECOMPOSE_TASKS 产出时写入（additive）
+3. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E005 列出缺失 skill
+4. Initialize tracking via `TodoWrite`
+5. If `--super`: read `maestro-super.md`, follow it completely
 
 </actions>
 
@@ -181,6 +211,7 @@ Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — **r
 | maestro-init | `-y` | Skip interactive questioning |
 | maestro-analyze | `-y` | Skip scoping, auto-deepen |
 | maestro-brainstorm | `-y` | Skip questions, use defaults |
+| maestro-blueprint | `-y` | Skip interview, use recommended defaults |
 | maestro-roadmap | `-y` | Skip questions (create/revise/review) |
 | maestro-impeccable | `-y` | Auto-select design variant + skip confirmations |
 | maestro-plan | `-y` | Skip confirmations and clarification |
@@ -200,6 +231,7 @@ Unlisted commands have no auto flags.
 | E002 | error | Clarity too low after 2 rounds | Show parsed intent, ask rephrase |
 | E003 | error | Chain step failed + user abort | Record partial, suggest -c resume |
 | E004 | error | Resume session not found | Show available sessions |
+| E005 | error | command_scope == "missing" for one or more steps | List missing skills, abort build |
 | W001 | warning | Ambiguous intent, multiple chains | Present options |
 | W002 | warning | Step completed with warnings | Log and continue |
 | W003 | warning | State suggests different chain | Show discrepancy |
@@ -207,11 +239,15 @@ Unlisted commands have no auto flags.
 ### Success Criteria
 
 - [ ] Intent classified with task_type, complexity, clarity_score
-- [ ] Broad lifecycle intents decomposed (S_DECOMPOSE, ≤3 boundary questions) sharing maestro-ralph contract; narrow/single-step skip
-- [ ] Decomposition writes additive block + goal-checklist.md + post-goal-audit node; emits /goal bind prompt (no self-call, no phantom create_goal)
+- [ ] Chain catalog 覆盖 brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / quality pipeline
+- [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查
+- [ ] macro analyze 后跟 `decision:post-analyze-scope`（由 ralph 评估 scope_verdict 决定下游链路）
+- [ ] plan 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径；`source_artifact_ref` 写入 step
+- [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
+- [ ] status.json 唯一真源；无 markdown 清单；post-goal-audit 节点在 decomposed 时追加；/goal 提示词以 status.json 为判据
 - [ ] Chain selected and confirmed (or auto-confirmed)
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
-- [ ] Tracking via TodoWrite (Claude); status.json steps[] grown dynamically by ralph-execute post-goal-audit
+- [ ] 每个 step 含 `command_scope` + `command_path` + `completion_confirmed` 字段
 - [ ] Auto flags propagated to supporting commands only
 - [ ] All chains dispatched via maestro-ralph-execute
 - [ ] Low-complexity intents routed to maestro-quick

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

@@ -34,12 +34,17 @@ Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyz
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone mode, no args for milestone-wide.
+$ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no args for milestone-wide.
+
+**Dual-layer mode:**
+- **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
+- **Micro mode** (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. `analyze 1` = Phase 1 of current milestone.
 
 **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 (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).
@@ -48,6 +53,20 @@ Scope routing, output directory format, artifact registration schema, and output
 `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 ask_question 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 to the top of `discussion.md` and mirror it into `context.md` under an `Interview Decisions` section:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
@@ -78,15 +97,21 @@ Phase 4: Output context.md for downstream plan --gaps
 
 **Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions). In --gaps mode, context.md contains issue root causes for `plan --gaps` consumption.
 
+**scope_verdict** (added to context.md in Step 6 Synthesis for macro/adhoc/standalone scopes):
+- `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`
+
 **Next-step routing on completion:**
 
-Phase/Milestone scope:
+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}`
 
-Adhoc/Standalone scope:
-- Ready to plan → `/maestro-plan --dir {scratch_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`
 
 Gaps scope:
@@ -125,6 +150,7 @@ Gaps mode:
 - [ ] context.md written with aggregated root causes for plan --gaps
 
 Both modes (full + quick):
+- [ ] Interactive mode: interview decision table written to `discussion.md` and mirrored into `context.md` "Interview Decisions"
 - [ ] context.md written with all decisions classified as Locked/Free/Deferred
 - [ ] Gray areas identified through phase-specific analysis
 - [ ] Decision Recording Protocol applied to all decisions

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

@@ -0,0 +1,132 @@
+---
+name: maestro-blueprint
+description: Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 6-phase document chain
+argument-hint: <idea or @file> [-y] [-c] [--from <source>]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Formal specification document chain producing a complete specification package through 6 sequential phases 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, 6-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 ask_question 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>