maestro-flow 0.4.11 → 0.4.13

package/.agy/skills/learn-investigate/SKILL.md

@@ -30,9 +30,9 @@ $ARGUMENTS — question text and optional flags.
 - `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
 - `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding
 - `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
-- `specs/learnings.md` — appended `<spec-entry>` blocks
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
 
-**Storage read**: source files in scope + `maestro wiki search` + `specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+**Storage read**: source files in scope + `maestro wiki search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
 </context>
 
 <state_machine>
@@ -45,7 +45,7 @@ S_HYPOTHESIZE    — 生成假设列表                                PERSIST:
 S_CLI_EXPLORE    — CLI 辅助探索（可选）                         PERSIST: evidence.ndjson (append)
 S_TEST           — 逐假设测试                                  PERSIST: evidence.ndjson + understanding.md
 S_ESCALATE       — 3-strike 升级                               PERSIST: —
-S_REPORT         — 综合报告 + persist                          PERSIST: report.md + specs/learnings.md
+S_REPORT         — 综合报告 + persist                          PERSIST: report.md + .workflow/specs/learnings.md
 </states>
 
 <transitions>
@@ -57,7 +57,7 @@ S_EVIDENCE:
   → S_PATTERN     DO: A_COLLECT_EVIDENCE
 
 S_PATTERN:
-  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + specs/learnings.md patterns
+  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + .workflow/specs/learnings.md patterns
 
 S_HYPOTHESIZE:
   → S_CLI_EXPLORE WHEN: CLI tools enabled AND hypotheses non-trivial    DO: A_FORM_HYPOTHESES
@@ -85,7 +85,7 @@ S_REPORT:
 ### A_FRAME_QUESTION
 
 1. Parse question, generate slug, create KNW-investigate-{slug}/
-2. Search prior knowledge: `maestro wiki search "<question>"` + search specs/learnings.md + read debug-notes.md
+2. Search prior knowledge: `maestro wiki search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
 3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
 
 ### A_COLLECT_EVIDENCE
@@ -126,7 +126,7 @@ For each hypothesis (rank order):
 ### A_SYNTHESIZE_REPORT
 
 Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions.
-Append to specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
+Append to .workflow/specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
 
 </actions>
 

package/.agy/skills/learn-retro/SKILL.md

@@ -16,7 +16,7 @@ allowed-tools:
 <purpose>
 Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
 
-All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
+All insights persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -30,9 +30,9 @@ $ARGUMENTS — lens selection and scope flags.
 **Storage write**:
 - `.workflow/knowhow/KNW-retro-{date}.md` — unified report
 - `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
-- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
+- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
 
-**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `.workflow/specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
 </context>
 
 <state_machine>
@@ -42,7 +42,7 @@ S_PARSE       — 解析 lens + flags                           PERSIST: —
 S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
 S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
 S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
-S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+S_PERSIST     — 写 spec-entry 块                             PERSIST: .workflow/specs/learnings.md
 </states>
 
 <transitions>
@@ -62,7 +62,7 @@ S_REPORT:
   → S_PERSIST     DO: write KNW-retro-{date}.md + .json
 
 S_PERSIST:
-  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  → END           DO: append insights to .workflow/specs/learnings.md via `maestro spec add learning`
   RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
 
 </transitions>
@@ -104,7 +104,7 @@ maestro wiki search "decision" --json
 maestro wiki list --type spec --json
 git log --oneline --all --grep="decision\|chose\|decided" -20
 ```
-Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, .workflow/specs/learnings.md.
 Apply --phase/--tag/--id filters.
 
 **Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
@@ -148,7 +148,7 @@ Apply --phase/--tag/--id filters.
 - [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
 - [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
 - [ ] Unified report + structured JSON written
-- [ ] specs/learnings.md appended with stable INS-ids
+- [ ] .workflow/specs/learnings.md appended with stable INS-ids
 </success_criteria>
 
 <next_step_routing>

package/.agy/skills/learn-second-opinion/SKILL.md

@@ -19,7 +19,7 @@ Structured second-opinion on code, decisions, or plans. Three modes:
 - **challenge**: single adversarial agent — break assumptions, propose alternatives
 - **consult**: interactive Q&A — agent studies target, answers your questions
 
-Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
 </purpose>
 
 <context>
@@ -47,7 +47,7 @@ S_RESOLVE    — 解析 target                          PERSIST: —
 S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
 S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
 S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
-S_PERSIST    — 写文件、append specs/learnings.md      PERSIST: knowhow files
+S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
 </states>
 
 <transitions>
@@ -68,7 +68,7 @@ S_SYNTHESIZE:
   → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
 
 S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to specs/learnings.md
+  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
 
 </transitions>
 
@@ -114,7 +114,7 @@ Interactive loop:
 <success_criteria>
 - [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
 - [ ] Synthesis with agreements, disagreements, verdict
-- [ ] Report written + findings appended to specs/learnings.md
+- [ ] Report written + findings appended to .workflow/specs/learnings.md
 </success_criteria>
 
 <next_step_routing>

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,36 +151,52 @@ S_FALLBACK:
 
 ### A_DECOMPOSE_TASKS
 
-与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约 —— 引用该规范，不重复表格。Condensed:
+与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
 
-1. 分类意图广度（broad: 重构/全面/重写/迁移/overhaul/migrate/rewrite；narrow: 单文件/函数/bug）。narrow / 单步 / `{status,init,quick}` 链直接跳过
-2. broad/medium → `ask_question` ≤3 轮：Scope（in/out）| Constraints（兼容/API/perf/test）| Definition of Done
-3. 派生 `execution_criteria`（3-6 条命令式规则）+ `task_decomposition`（outcome 子目标，`done_when` 客观可校验，绑定到 ralph 产物：verification.json / review.json / uat.md / test path）
-4. **status.json 为唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition` / `goal_checklist_path`；从 status.json 投影渲染 `{session_dir}/goal-checklist.md`（同 maestro-ralph 的 Sync Rule，含 Resume 区块指向 `/maestro-ralph continue`）
-5. 在链路末尾（evidence 产出步骤之后、milestone-complete/close-out 之前）追加 `{ type: "decision", decision: "post-goal-audit", retry_count: 0, max_retries: 2 }`。ralph-execute 在该节点动态生长 `steps[]` 以收敛未达成子目标
-6. **输出 `/goal` 绑定提示词（参考文档 + 内嵌 ralph 调用）：**
+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}/status.json 中 task_decomposition[*].status 全部为 "done"（等价: {session_dir}/goal-checklist.md 末尾含 ALL_GOALS_DONE）。未达成时: 阅读 {session_dir}/goal-checklist.md 取得"执行准则/边界契约/子目标"作为行动手册, 然后调用 /maestro-ralph continue 推进下一步; 严禁手动执行 skill 或越界。
+   /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。
    ```
-   `/goal` 仅用户可输入；判据以 status.json 为权威，哨兵为等价信号。
 
 ### 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>
 
@@ -183,6 +211,7 @@ S_FALLBACK:
 | 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 |
@@ -202,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 |
@@ -209,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
-- [ ] status.json 为唯一真源；goal-checklist.md 为投影视图（Resume 区块内嵌 `/maestro-ralph continue`）；post-goal-audit 节点追加；/goal 提示词内含"读 checklist + 调 /maestro-ralph continue"双重指引
+- [ ] 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-amend/SKILL.md

@@ -147,6 +147,7 @@ On validation failure: fix JSON, retry (max 2).
 | Code | Condition | Recovery |
 |------|-----------|----------|
 | E001 | No signals from any source | Verify artifact paths or provide description |
+| E002 | Signal source path invalid or unreadable | Check `--from-*` path; ensure artifact exists |
 | 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 |

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

@@ -34,12 +34,23 @@ 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.
+
+**Disambiguation rule (mode selection):**
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase number)
+- First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
+- No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
+- 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 (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 +59,21 @@ 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. 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 `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `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) |`
+</interview_protocol>
+
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
@@ -78,15 +104,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 +157,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,133 @@
+---
+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. 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 `invoke_subagent([{ TypeName: "<TypeName>", Role: "<Role>", Prompt: "<Prompt>", Workspace: "inherit" }])` / `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.
+</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>