maestro-flow 0.4.10 → 0.4.12

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

@@ -1,49 +1,74 @@
 ---
 name: maestro-brainstorm
 description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic] [-y|--yes] [-c|--concurrency N] [--continue] [--count N] [--skip-questions]"
+argument-hint: "[topic] [-y|--yes] [-c|--concurrency N] [--continue] [--count N] [--skip-questions] [--review-only]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
 Wave-based multi-role brainstorming via `spawn_agents_on_csv`. Diamond topology:
-Wave 1 (guidance spec) → Wave 2 (parallel role analysis, 3-9 agents) → Wave 3 (synthesis + feature index).
+Wave 1 (guidance spec) → Wave 2 (parallel role analysis, 3-9 agents) → Wave 3 (cross-role review + resolution writeback).
+Wave 2 agents produce multi-file analysis per role under `{role}/` (analysis.md index + per-feature files + findings).
+Wave 3 compares Decision Digests from each role's `analysis.md` §2 and patches the role files. Audit trail appended to `guidance-specification.md` §12.
 </purpose>
 
 <context>
 $ARGUMENTS — topic text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 6), `--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`
+**Flags**: `-y` (auto), `-c N` (concurrency, default 6), `--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md)
 
 **9 valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
 ### Pre-load specs
-1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role analysis (roles respect documented decisions).
+1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
 2. **Role Knowledge**: `maestro wiki list --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
 3. Both optional — proceed without if unavailable.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/`
-**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.brainstorming/` (guidance-specification.md, feature-index.json, synthesis-changelog.md, feature-specs/, {role}/analysis*.md)
+
+**Output** (per session):
+- `guidance-specification.md` — machine contract (Wave 1; consumed by downstream roadmap/analyze/blueprint). §11 Decision Tracking, §12 Cross-Role Resolutions.
+- `design-research.md` — optional, external research from Wave 1
+- `{role}/analysis.md` — index + Decision Digest + cross-cutting foundations per selected role (Wave 2)
+- `{role}/analysis-F-{id}-{slug}.md` — per-feature analysis files (Wave 2)
+- `{role}/findings-{slug}.md` — additional discoveries (Wave 2, optional)
+- `context-package.json` — standardized context contract (context-package/1.0 schema) for downstream commands
+- `tasks.csv`, `results.csv`, `discoveries.ndjson`, `context.md` — wave-engine bookkeeping
 </context>
 
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--skip-questions`, `--continue` (existing session), or input is already specific.
+
+- One decision per turn via request_user_input with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, the session directory, `maestro spec load`, or `maestro wiki search`.
+- Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
+- Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
+
+Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
+
+Exit: on consensus or `Proceed now`, write the table below into `guidance-specification.md` §11 and session metadata:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <csv_schema>
 ```csv
-id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,analysis_file,error
+id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,output_file,error
 "1","Guidance Spec","...","guidance-generator","<topic>","","","","1","","","",""
-"2","System Architect","...","system-architect","<topic>","","1","1","2","","","",""
-"3","UI Designer","...","ui-designer","<topic>","","1","1","2","","","",""
-"4","Synthesis","...","synthesis","<topic>","","2;3","2;3","3","","","",""
+"2","System Architect","...","system-architect","<topic>","","1","1","2","","","system-architect/analysis.md",""
+"3","UI Designer","...","ui-designer","<topic>","","1","1","2","","","ui-designer/analysis.md",""
+"4","Cross-Role Review","...","cross-role-reviewer","<topic>","","2;3","2;3","3","","","",""
 ```
-Wave 1: 1 guidance row. Wave 2: N role rows (parallel). Wave 3: 1 synthesis row.
+Wave 1: 1 guidance row. Wave 2: N role rows (parallel) — each writes `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md`. Wave 3: 1 reviewer row (reads analysis.md §2 Decision Digests; emits structured findings consumed by orchestrator).
 </csv_schema>
 
 <invariants>
-1. **Wave order sacred**: Guidance (W1) MUST complete before roles (W2)
-2. **CSV source of truth**: Master tasks.csv holds all state
-3. **Discovery board append-only**: Never modify/delete discoveries.ndjson
-4. **Skip on failure**: Guidance fails → abort. All roles fail → skip synthesis.
+1. **Wave order sacred**: Guidance (W1) MUST complete before role design (W2); review (W3) MUST run only after all W2 rows complete.
+2. **CSV source of truth**: Master tasks.csv holds all state.
+3. **Discovery board append-only**: Never modify/delete discoveries.ndjson.
+4. **Skip on failure**: Guidance fails → abort. All W2 roles fail → skip review.
 5. **9 valid roles only**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-6. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y)
+6. **Wave 3 is read-only at the agent boundary**: the reviewer emits structured findings (conflicts / gaps / synergies with `patch_targets[]`). The orchestrator (not the agent) applies the patches via Edit.
+7. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y).
 </invariants>
 
 <state_machine>
@@ -55,16 +80,21 @@ S_CSV_GEN    — 生成 tasks.csv                              PERSIST: tasks.cs
 S_WAVE_1     — Guidance Spec (single agent)                PERSIST: guidance-specification.md
 S_CHECK_1    — Checkpoint: 用户审阅 guidance（-y 跳过）    PERSIST: —
 S_DESIGN     — 视觉风格确定 (impeccable teach + explore)   PERSIST: DESIGN.md
-S_WAVE_2     — Role Analysis (parallel spawn)              PERSIST: role analyses
-S_CHECK_2    — Checkpoint: 用户审阅 roles（-y 跳过）       PERSIST: —
-S_WAVE_3     — Synthesis + Feature Index (single agent)    PERSIST: synthesis artifacts
+S_WAVE_2     — Role Analysis (parallel spawn)               PERSIST: {role}/ multi-file × N
+S_CHECK_2    — Checkpoint: 用户审阅分析结果（-y 跳过）     PERSIST: —
+S_WAVE_3     — Cross-Role Review (single agent, read-only) PERSIST: review_findings (in-memory)
+S_RESOLVE    — Apply Resolutions (orchestrator-side)       PERSIST: */analysis.md edits + guidance §12
 S_AGGREGATE  — 生成报告、注册 artifact                     PERSIST: context.md + results.csv
 </states>
 
 <transitions>
-S_PARSE → S_ROLES      DO: parse args, detect mode (phase/scratch), load specs
+S_PARSE → S_ROLES      DO: parse args, detect mode (phase/scratch/review-only), load specs
 S_ROLES → S_CSV_GEN    DO: select roles (-y: auto top N; interactive: request_user_input)
-S_CSV_GEN → S_WAVE_1   DO: generate tasks.csv (1 guidance + N roles + 1 synthesis)
+S_CSV_GEN → S_WAVE_1   DO: generate tasks.csv (1 guidance + N roles + 1 reviewer)
+
+# --review-only path: skip W1/W2, jump straight to W3
+S_PARSE → S_WAVE_3     WHEN: --review-only AND existing session has guidance-specification.md AND */analysis.md
+S_PARSE → END          WHEN: --review-only AND missing prerequisites (E006/E007)
 
 S_WAVE_1 → S_CHECK_1   WHEN: completed    DO: spawn wave-1, merge results, read guidance-spec
 S_WAVE_1 → END         WHEN: failed       DO: abort pipeline
@@ -78,13 +108,16 @@ S_DESIGN → S_WAVE_2    WHEN: DESIGN.md exists OR explore completed    DO: A_DE
 S_DESIGN → S_WAVE_2    WHEN: DESIGN.md already exists (skip explore)
 S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → continue without
 
-S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results
-S_WAVE_2 → S_WAVE_3    WHEN: all failed       DO: skip synthesis
+S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results — each agent writes {role}/analysis.md + sub-files
+S_WAVE_2 → S_AGGREGATE WHEN: all failed       DO: skip review
 
 S_CHECK_2 → S_WAVE_3   WHEN: -y OR user "Proceed"
 S_CHECK_2 → S_WAVE_2   WHEN: user "Add Roles"  DO: add new role rows, spawn only new
 
-S_WAVE_3 → S_AGGREGATE DO: spawn wave-3, merge results
+S_WAVE_3 → S_RESOLVE   DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
+S_WAVE_3 → S_AGGREGATE WHEN: zero findings    DO: log "No cross-role issues detected", skip resolve
+
+S_RESOLVE → S_AGGREGATE  DO: A_APPLY_RESOLUTIONS (orchestrator iterates patch_targets and applies Edits)
 
 S_AGGREGATE → END      DO: A_AGGREGATE
 </transitions>
@@ -93,11 +126,48 @@ S_AGGREGATE → END      DO: A_AGGREGATE
 
 ### Wave agent responsibilities
 
-**Guidance (W1)**: Analyze topic → extract 5-10 terms → define non-goals → decompose features (max 8, F-{3digit}) → RFC 2119 keywords → write guidance-specification.md
+**Guidance (W1, agent role `guidance-generator`)**: Analyze topic → extract 5-10 terms → define non-goals → decompose features (max 8, F-{3digit}) → RFC 2119 keywords → write `guidance-specification.md` with §1-§12 (§11 Decision Tracking, §12 Cross-Role Resolutions initially empty — populated later by S_RESOLVE).
+
+**Role Analysis (W2, agent role = the role name itself)**: Read guidance-spec → produce multi-file analysis under `{role}/`:
+- `analysis.md` — INDEX with §1 Role Mandate (≤ 200 words), §2 Decision Digest (4 tables: Decisions, Interfaces, Cross-Cutting Positions, Findings Summary), §3 Cross-Cutting Foundations, §4 File Index, §5 Outstanding TODOs
+- `analysis-F-{id}-{slug}.md` — one per feature (< 2000 words each)
+- `findings-{slug}.md` — additional discoveries (0 or more, < 1000 words)
+
+system-architect MUST include in §3: Data Model, State Machine, Error Handling, Observability, Configuration, Boundary Scenarios.
 
-**Role (W2)**: Read guidance-spec → analyze through role lens → feature-point organization (analysis.md index + analysis-cross-cutting.md + per-feature analysis-F-{id}.md) or fallback single analysis.md. system-architect MUST include: Data Model, State Machine, Error Handling, Observability, Config Model.
+The agent MUST write files. The agent MUST NOT return analysis as text.
 
-**Synthesis (W3)**: Cross-role consensus/conflicts/unique → conflict tags [RESOLVED]/[SUGGESTED]/[UNRESOLVED] → feature-specs or synthesis-specification.md → feature-index.json + synthesis-changelog.md. Four-layer: Direct Reference → Structured Extraction → Conflict Distillation → Cross-Feature Annotation.
+**Cross-Role Review (W3, agent role `cross-role-reviewer`)**: Read ALL `{role}/analysis.md` files (§2 Decision Digests) + guidance-specification.md → emit structured report (NOT files):
+
+```
+## Conflicts (need user decision)
+### C-001: ...
+  patch_targets:
+    - target_file: {role-A}/analysis-F-{id}-{slug}.md   # or {role-A}/analysis.md for cross-cutting
+      target_heading: ## {exact heading text}
+      edit_type: annotate_and_strikeout
+      edit_content: > **Cross-Role Resolution (C-001)**: {1-line resolution}
+    - target_file: {role-B}/analysis-F-{id}-{slug}.md
+      target_heading: ## {exact heading text}
+      edit_type: annotate_and_strikeout
+
+## Gaps
+### G-001: ...
+  patch_targets:
+    - target_file: {ref-role}/analysis.md   edit_type: annotate_after_heading   # §2 Interfaces table
+    - target_file: {owner-role}/analysis.md edit_type: append_to_section        # §2 Decisions table
+
+## Synergy Opportunities
+### S-001: ...
+  patch_targets:
+    - target_file: {role-A}/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+    - target_file: {role-B}/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+
+## Summary
+conflicts_count / gaps_count / synergies_count / review_confidence
+```
+
+`edit_type` vocabulary is closed: `annotate_after_heading` / `annotate_and_strikeout` / `append_to_section`. The orchestrator MUST refuse any patch outside this set.
 
 ### A_DESIGN_EXPLORE
 
@@ -108,14 +178,29 @@ When ui-designer is among selected roles, establish visual direction before Wave
 3. If both already exist → skip (visual direction already locked)
 
 explore generates multi-style HTML prototypes, visual comparison, user selection/mix, and produces DESIGN.md.
-ui-designer agents in Wave 2 then focus on UX analysis only (interaction flows, state design), not visual styling.
+ui-designer agents in Wave 2 then focus on UX/visual design referencing DESIGN.md.
+
+### A_APPLY_RESOLUTIONS
+
+For each finding in `review_findings`:
+
+1. **Confirm with user** (skip if -y): present finding + suggested resolution; user picks `Accept` / `Pick A` / `Pick B` (conflict only) / `Skip` / `Defer to TODO`.
+2. **Iterate `patch_targets[]`**: for each target, locate `target_heading` verbatim in `target_file`; apply the edit per `edit_type`.
+3. **Heading drift fallback**: if `target_heading` not found verbatim, log W006 and skip that target. Never invent or fuzzy-match headings.
+4. **Append audit row** to `guidance-specification.md` §12 "Cross-Role Resolutions":
+   ```
+   | C-001 | conflict | system-architect/analysis-F-*.md "<heading>" / subject-matter-expert/analysis-F-*.md "<heading>" | {resolution} | both annotated+superseded |
+   ```
+
+If zero findings, S_RESOLVE is bypassed and `guidance §12` is unchanged.
 
 ### A_AGGREGATE
 
 1. Export results.csv
-2. Generate context.md (summary, guidance, per-role findings, synthesis, feature index, next steps)
-3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: >3 UNRESOLVED → warn.
-4. Copy artifacts to target .brainstorming/
+1.5. Generate context-package.json (extract from guidance-specification.md + {role}/analysis.md §2 Digests → standardized schema per context-package/1.0)
+2. Generate context.md (summary, guidance, per-role analyses, review_findings_count, resolutions_applied, patches_skipped, next steps)
+3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: cross_role_consistency < 0.4 → warn.
+4. Copy artifacts to target session directory (preserve `{role}/` subdirs).
 5. Next-step routing: DESIGN.md established → `maestro-impeccable build <feature>`; else UI features detected → `maestro-impeccable build <feature>`; else → maestro-analyze / maestro-plan / maestro-roadmap
 
 </actions>
@@ -128,7 +213,8 @@ ui-designer agents in Wave 2 then focus on UX analysis only (interaction flows,
 | non_goal | title | {title, rationale} |
 | feature_candidate | id | {id, slug, description, roles[], priority} |
 | role_insight | role+topic | {role, topic, insight, confidence} |
-| cross_role_conflict | area | {area, roles[], positions[], resolution} |
+| cross_role_finding | finding_id | {kind: conflict\|gap\|synergy, finding_id: C-/G-/S-XXX, patch_targets[]} |
+| resolution_applied | finding_id | {finding_id, decision, patched_files[], skipped_targets[]} |
 
 Protocol: read before analysis, append-only, dedup by type+key.
 </discovery_board>
@@ -137,23 +223,27 @@ Protocol: read before analysis, append-only, dedup by type+key.
 | Condition | Recovery |
 |-----------|----------|
 | Guidance agent failed | Abort pipeline (W2 depends on guidance) |
-| All role agents failed | Skip synthesis, report partial |
-| Synthesis failed | Use W2 results directly |
+| All role agents failed | Skip review, report partial |
+| Review agent failed | Use analysis files directly, no resolution writeback |
 | Role count > 9 | Cap at 9 with warning |
+| E006 --review-only but no */analysis.md | Run auto mode or single roles first |
+| E007 --review-only but missing guidance-specification.md | Run auto mode first |
+| W006 patch heading drift (no verbatim match) | Skip that patch, surface in final report |
 </error_codes>
 
 <success_criteria>
-- [ ] 3 waves executed: guidance → parallel roles → synthesis
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] Role analysis files for each selected NON-UI role
-- [ ] If ui-designer selected: DESIGN.md established via impeccable explore; analysis.md with UX analysis
-- [ ] Feature specs in `.brainstorming/feature-specs/` or synthesis-specification.md
-- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints
-- [ ] feature-index.json + synthesis-changelog.md + context.md generated
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Confidence scored per role and after cross-role analysis
-- [ ] Readiness gate checked before spec generation (wave 3)
-- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Interactive mode: interview decision table written to `guidance-specification.md` §11 and session metadata
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition (§10), decision tracking (§11)
+- [ ] If ui-designer selected: DESIGN.md established via impeccable explore
+- [ ] {role}/analysis.md written for each selected role with §1 Role Mandate / §2 Decision Digest (4 tables) / §3 Cross-Cutting Foundations / §4 File Index / §5 Outstanding TODOs
+- [ ] {role}/analysis-F-{id}-{slug}.md written per feature (< 2000 words)
+- [ ] system-architect/analysis.md §3 includes Data Model + State Machine when system-architect selected
+- [ ] Each {role}/analysis.md §2 Decisions table has ≥ 1 row per feature
+- [ ] Cross-role review (W3) executed; reviewer output includes `patch_targets[]` for every finding
+- [ ] If findings: resolutions applied via Edit AND logged in guidance §12 "Cross-Role Resolutions"
+- [ ] If zero findings: final report explicitly notes "No cross-role issues detected"; guidance §12 unchanged
+- [ ] Heading-drift patch failures surfaced (not silently dropped)
+- [ ] context-package.json generated with per-item `ref` traceability
 - [ ] discoveries.ndjson append-only throughout
-- [ ] Conflict quality gate: >3 UNRESOLVED → warn
+- [ ] context.md aggregates session results with next-step routing
 </success_criteria>

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

@@ -125,7 +125,7 @@ If spec not found, use built-in fallback:
 | `verify` | skill | `maestro-verify` |
 | `refactor` | skill | `quality-refactor` |
 | `debug` | skill | `quality-debug` |
-| `spec` | skill | `maestro-roadmap --mode full` |
+| `spec` | skill | `maestro-blueprint` |
 | `checkpoint` | checkpoint | — |
 
 **Step 2.1** — Load `intent.json`, map each step to executor.

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

@@ -206,12 +206,21 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 | Input | Resolution |
 |-------|------------|
-| `--dir <path>` | Use path directly (scratch plan dir) |
+| `--dir <path>` | Use path directly (scratch plan dir); scope=standalone |
 | No args | Find all pending plans for current milestone from state.json.artifacts[] |
-| Number (e.g., `3`) | Find pending plans for phase N from state.json.artifacts[] |
+| Number (e.g., `3`) | Find pending plans for phase N from state.json.artifacts[]; **resolve milestone via D-007 reverse lookup** |
 
    For multi-plan: execute sequentially. Each plan is a full CSV session.
 
+   **D-007 milestone reverse lookup** (numeric arg 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
+   ```
+   Use the resolved milestone for EXC artifact registration (`milestone` field) and artifact filtering. NEVER read `current_milestone` directly for phase-scoped runs — phase N may belong to a milestone different from current.
+
 2. **Load plan**: Read `{PLAN_DIR}/plan.json` for wave structure and task assignments
 
 3. **Detect completed tasks (breakpoint resume)**: Read `.task/TASK-{NNN}.json` for each task; exclude completed ones from CSV. Log resume count.
@@ -279,7 +288,7 @@ Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with e
    - All task_refs completed -> `issue.status = "resolved"`; any failed -> `"in_progress"`
    - Append history entry: `{ action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }`
 
-4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`
+4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`. `milestone` MUST come from D-007 `phase_slugs` reverse lookup (numeric phase) — inherit from matching plan artifact if available, otherwise reverse-lookup directly.
 
 5. **Extract incremental specs**: Read `.summaries/`, use `maestro spec add` CLI:
    - Learnings/pitfalls → `maestro spec add learning "<title>" "<content>" --keywords ... --source execute:{PLAN_DIR}`
@@ -356,7 +365,7 @@ echo '{"ts":"<ISO>","worker":"TASK-001","type":"code_pattern","data":{"name":"Re
 - [ ] All waves executed in order with cross-wave context propagation
 - [ ] Completed tasks have .summaries/TASK-{NNN}-summary.md
 - [ ] .task/TASK-*.json statuses updated to match execution results
-- [ ] state.json updated with EXC artifact
+- [ ] state.json updated with EXC artifact (numeric scope: milestone resolved via D-007 `phase_slugs` reverse lookup, NOT direct `current_milestone` read)
 - [ ] Issue status synced for tasks with issue_id (all completed → resolved, any failed → in_progress)
 - [ ] Incremental specs extracted from summaries (learnings, design rationale, root causes)
 - [ ] Post-task knowledge inquiry triggered when applicable (deviation, retry>=2, design rationale)

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

@@ -42,13 +42,13 @@ $ARGUMENTS 匹配关键词 → 路由到对应模式：
 
 | 字段 | 内容 |
 |------|------|
-| `commands[]` | 55 个 slash 命令（name, command, category, description, source） |
+| `commands[]` | 56 个 slash 命令（name, command, category, description, source） |
 | `skills[]` | 10 个 Skill（name, category, description, source） |
 | `agents[]` | 22 个 Agent（name, category, description） |
 | `cli_commands[]` | 21 个终端命令（command, description, category） |
 | `guide_files[]` | 17 个 Guide 文档索引 |
 | `essential_commands[]` | 10 个核心命令 |
-| `workflows` | 4 大工作流模板（main_pipeline, quick, issue_loop, init_paths） |
+| `workflows` | 拓扑 + 6 条合法路径 (Path A-F) + 3 个辅助流程 |
 
 ## Project State Detection
 
@@ -96,7 +96,7 @@ Mode 3 (Smart Recommendations) 需要检测项目状态：
 
 Guide 映射：
 - analyze/plan/execute/verify → `guide/command-usage-guide.md`
-- init/roadmap → `guide/quick-start-guide.md`
+- init/roadmap/blueprint → `guide/quick-start-guide.md`
 - ralph → `guide/maestro-ralph-guide.md`
 - maestro (协调器) → `guide/maestro-coordinator-guide.md`
 - delegate → `guide/delegate-async-guide.md`
@@ -109,9 +109,11 @@ Guide 映射：
 | 当前状态 | 推荐命令 | 原因 |
 |---------|---------|------|
 | 无 .workflow/ | `/maestro-init` | 项目未初始化 |
-| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图 |
-| roadmap 完成 | `/maestro-analyze` | 开始分析 |
-| analyze 完成 | `/maestro-plan` | 进入规划 |
+| init 完成，无上游 context | `/maestro-brainstorm` 或 `/maestro-analyze "topic"` | 先探索再规划；brainstorm 发散，analyze 宏观探索影响面 |
+| analyze 完成，scope_verdict=large | `/maestro-roadmap --from analyze:ANL-xxx` | 大范围需求，需要 Milestone > Phase 分解 |
+| analyze 完成，scope_verdict=medium/small | `/maestro-plan --from analyze:ANL-xxx` | 跳过 roadmap 直达规划（Path C） |
+| roadmap 完成，phase=pending | `/maestro-analyze 1` | 微观分析：Phase 级深入探索 |
+| analyze (微观) 完成 | `/maestro-plan 1` | Phase 级规划 |
 | plan 完成 | `/maestro-execute` | 开始执行 |
 | execute 完成 | `/maestro-verify` | 验证成果 |
 | verify 有 gaps | `/maestro-analyze --gaps` | 重新分析 |
@@ -123,16 +125,24 @@ Guide 映射：
 
 根据任务类型推荐工作流和命令序列：
 
-**新项目**:
-- 最简: `/maestro-init` → `/maestro-roadmap "目标" -y`
-- 头脑风暴: `/maestro-brainstorm "描述"` → `/maestro-init --from-brainstorm ANL-xxx`
-- 完整规范: `/maestro-init` → `/maestro-spec-generate`
+**Path A — 完整新项目**:
+- `brainstorm` → `blueprint`(可选) → `analyze "topic"`(宏观) → `roadmap` → `analyze 1`(微观) → `plan 1` → `execute` → `verify`
 
-**功能开发**:
-- 标准: analyze → plan → execute → verify
+**Path B — 旧项目大功能**:
+- `analyze "feature X"`(宏观) → `roadmap` → `analyze 1`(微观) → `plan 1` → `execute` → `verify`
+
+**Path C — 中等功能（跳过 roadmap）**:
+- `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` → `verify`
+
+**Path D — 小改动**:
+- `plan "fix auth bug"` → `execute` → `verify`
 - 快速: `/maestro-quick "功能描述"`
 - 全自动: `/maestro -y "功能描述"`
 
+**Path E/F — 纯文档/纯探索**:
+- `blueprint "project idea"` → (供人阅读)
+- `brainstorm "idea"` → (供人决策)
+
 **Bug 修复**:
 - 快速: `/maestro-quick "Bug 描述"`
 - Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
@@ -149,14 +159,14 @@ Guide 映射：
 |------|------|---------|
 | `/maestro` | 智能协调器 | 不确定用哪个命令时 |
 | `/maestro-init` | 初始化项目 | 首次使用 |
-| `/maestro-roadmap` | 路线图 | 初始化后规划 |
-| `/maestro-analyze` | 分析 | 开始 Phase 分析 |
-| `/maestro-plan` | 规划 | 分析完成后 |
+| `/maestro-brainstorm` | 头脑风暴 | 新项目发散探索、多角色创意 |
+| `/maestro-blueprint` | 规格文档化 | 正式 7-phase 收敛规格链 |
+| `/maestro-analyze` | 双层分析 | 宏观: `"topic"` 探索影响面；微观: `1` Phase 级深入 |
+| `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
+| `/maestro-plan` | 规划 | 分析完成后，支持 `--from analyze:ANL-xxx` 直达 |
 | `/maestro-execute` | 执行 | 计划完成后 |
 | `/maestro-verify` | 验证 | 执行完成后 |
 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
-| `/quality-review` | 代码审查 | 执行后质量检查 |
-| `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
 
 快速上手路径：
 1. `maestro install --force`
@@ -175,7 +185,7 @@ Guide 映射：
 
 - **Workflow (15)**: analyzer, planner, executor, verifier, reviewer, debugger, research-agent, roadmapper, plan-checker, phase-researcher, project-researcher, research-synthesizer, codebase-mapper, nyquist-auditor, integration-checker, external-researcher, collab-planner
 - **Team (2)**: supervisor, worker
-- **Planning (1)**: conceptual-planning-agent
+- **Brainstorm (2)**: role-design-author, cross-role-reviewer
 - **CLI (1)**: cli-explore-agent
 - **UI (1)**: ui-design-agent
 

package/.codex/skills/maestro-help/catalog.json

@@ -7,10 +7,11 @@
   "commands": [
     {"name": "maestro", "command": "/maestro", "category": "core", "description": "智能协调器 — 根据意图和项目状态自动选择最优命令链", "source": "../../commands/maestro.md"},
     {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.md"},
-    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图生成 — 基于目标创建里程碑和 Phase 分解", "source": "../../commands/maestro-roadmap.md"},
-    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "多角色头脑风暴 — 生成分析文档和功能规格", "source": "../../commands/maestro-brainstorm.md"},
-    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "多维度分析 — Phase 分析、CLI 辅助探索、gap 分析", "source": "../../commands/maestro-analyze.md"},
-    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 生成执行计划、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — 消费上游 context，纯 Milestone > Phase 分解（不做技术探索）", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "头脑风暴 — 发散探索，多角色创意，上游起源命令", "source": "../../commands/maestro-brainstorm.md"},
+    {"name": "maestro-blueprint", "command": "/maestro-blueprint", "category": "core", "description": "正式规格文档化 — 7-phase 收敛规格链，上游起源命令，产出 .workflow/blueprint/", "source": "../../commands/maestro-blueprint.md"},
+    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "双层分析 — 宏观(文本参数)探索影响面+scope_verdict / 微观(数字参数)Phase 级深入", "source": "../../commands/maestro-analyze.md"},
+    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 支持 --from analyze:ANL-xxx 直达、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
     {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
     {"name": "maestro-verify", "command": "/maestro-verify", "category": "pipeline", "description": "验证确认 — 成果检查、gap 发现、下一阶段建议", "source": "../../commands/maestro-verify.md"},
     {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
@@ -147,16 +148,33 @@
   "essential_commands": [
     "/maestro",
     "/maestro-init",
-    "/maestro-roadmap",
+    "/maestro-brainstorm",
+    "/maestro-blueprint",
     "/maestro-analyze",
+    "/maestro-roadmap",
     "/maestro-plan",
     "/maestro-execute",
     "/maestro-verify",
-    "/maestro-quick",
-    "/quality-review",
-    "/manage-issue"
+    "/maestro-quick"
   ],
   "workflows": {
+    "topology": {
+      "hierarchy": "Roadmap > Milestone > Phase > Task",
+      "layers": {
+        "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
+        "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
+        "orchestration": "roadmap (可选，消费上游 context)",
+        "execution": ["plan", "execute", "verify"]
+      }
+    },
+    "paths": {
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
+      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute → verify",
+      "D_small_fix": "plan → execute → verify",
+      "E_spec_only": "blueprint → (供人阅读)",
+      "F_explore_only": "brainstorm → (供人决策)"
+    },
     "main_pipeline": {
       "name": "主干管线",
       "phases": ["analyze", "plan", "execute", "verify"],
@@ -174,9 +192,9 @@
     },
     "init_paths": {
       "name": "初始化路径",
-      "minimal": "/maestro-init → /maestro-roadmap",
-      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from-brainstorm → /maestro-roadmap",
-      "full_spec": "/maestro-init → /maestro-spec-generate"
+      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from brainstorm:<id> → /maestro-analyze 宏观",
+      "from_blueprint": "/maestro-blueprint → /maestro-init → /maestro-analyze 宏观",
+      "direct": "/maestro-init → /maestro-analyze 宏观"
     }
   }
 }

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-init
 description: Initialize project with auto state detection
-argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+argument-hint: "[-y] [--from <source>]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -16,12 +16,12 @@ When `-y`: After config questions, run research without further interaction. Exp
 ```bash
 $maestro-init ""
 $maestro-init "-y"
-$maestro-init "--from-brainstorm 20260318-brainstorm-auth"
+$maestro-init "--from brainstorm:20260318-brainstorm-auth"
 ```
 
 **Flags**:
 - `-y`: Skip interactive questioning; extract from provided document
-- `--from-brainstorm SESSION-ID`: Import vision/goals/constraints from brainstorm guidance-specification.md
+- `--from <source>`: Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json. Alias: `--from-brainstorm`
 
 **Output**: `.workflow/` directory with project.md, state.json, config.json, specs/
 
@@ -41,7 +41,7 @@ $maestro-init "--from-brainstorm 20260318-brainstorm-auth"
 
 Extract flags from arguments:
 - `-y` flag presence
-- `--from-brainstorm SESSION-ID` value
+- `--from <source>` value (or `--from-brainstorm SESSION-ID` alias)
 - Remaining text as project description
 
 ### Step 2: Detect Project State
@@ -55,7 +55,7 @@ Classify as:
 
 ### Step 3: Gather Project Information
 
-**If `--from-brainstorm`**:
+**If `--from` (or `--from-brainstorm`)**:
 - Read `.workflow/.brainstorm/{SESSION-ID}/guidance-specification.md`
 - Extract these fields from the document (match by heading or frontmatter key):
   - `## Vision` or `vision:` → project.md Core Value Proposition
@@ -132,7 +132,7 @@ If project state is **empty** (greenfield, no source files found in Step 2):
 
 ### Step 10: Completion Report
 
-Display created files and next steps: `$maestro-roadmap --mode full` (full spec), `$maestro-roadmap` (light), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
+Display created files and next steps: `$maestro-blueprint` (full spec), `$maestro-roadmap` (roadmap), `$manage-status`, `$maestro-brainstorm`, `$maestro-quick`.
 
 </execution>
 
@@ -142,7 +142,7 @@ Display created files and next steps: `$maestro-roadmap --mode full` (full spec)
 |------|----------|-------------|----------|
 | E001 | error | No arguments when -y requires document | Ask user for document reference |
 | E002 | error | .workflow/ already exists | Show status, suggest manage-status |
-| E003 | error | Brainstorm session not found | List available sessions |
+| E003 | error | Context source not found (--from / --from-brainstorm) | List available sessions |
 | W001 | warning | Could not detect tech stack | Continue with manual input |
 
 </error_codes>