maestro-flow 0.4.11 → 0.4.13

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

@@ -0,0 +1,123 @@
+---
+name: maestro-blueprint
+description: Generate formal specification package (Product Brief, PRD, Architecture, Epics) through 7-phase document chain (P0 Spec Study → P1 Discovery → P1.5 Req Expansion → P2 Product Brief → P3 PRD → P4 Architecture → P5 Epics → P6 Readiness Check)
+argument-hint: "<idea or @file> [-y] [-c] [--from <source>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, spawn_agents_on_csv, request_user_input
+---
+<purpose>
+Formal specification document chain producing a complete specification package through 7 sequential phases (P0–P6, plus P1.5 requirement expansion) with multi-CLI analysis and interactive refinement. Pure documentation — no code generation, no roadmap generation.
+
+Parallel to `brainstorm` as an upstream origin command:
+- **brainstorm** = divergent exploration (lightweight, multi-role creative)
+- **blueprint** = convergent documentation (heavyweight, 7-phase formal spec chain)
+
+Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD, Architecture, and Epics.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/blueprint.md
+</required_reading>
+
+<deferred_reading>
+- [blueprint-config.json](~/.maestro/templates/blueprint-config.json) — read when initializing blueprint configuration
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- idea text, @file reference, or upstream context source.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint (reads blueprint-config.json)
+- `--from <source>`: Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json
+- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
+
+**Input types:**
+- Direct text: `"Build a real-time collaboration platform with WebSocket"`
+- File reference: `@requirements.md`
+- Context import: `--from brainstorm:BRN-001` or `--from @requirements.md` or `--from path/`
+- Resume: `-c` (resumes from first incomplete phase)
+
+**Pipeline position:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md / context-package.json
+maestro-blueprint
+        ↓ .workflow/blueprint/BLP-{slug}-{date}/
+maestro-analyze → maestro-roadmap → maestro-plan
+```
+
+**Output boundary**: ALL file writes MUST target `.workflow/blueprint/BLP-{slug}-{date}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for architecture decisions (Phase 4).
+2. Optional — proceed without if unavailable.
+</context>
+
+<interview_protocol>
+Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
+
+- Ask one question per turn via request_user_input and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. The user controls termination — keep interviewing until convergence; they can interrupt naturally 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 — `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>

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

@@ -1,49 +1,215 @@
 ---
 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. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
+- Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
+- Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
+
+Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
+
+Exit: on consensus or explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
 <csv_schema>
 ```csv
-id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,analysis_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","","","",""
+id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,output_file,error
+"1","Guidance Spec","<W1 prompt — see <agent_prompt_template>>","guidance-generator","<topic>","","","","1","","","",""
+"2","System Architect","<W2 prompt — see <agent_prompt_template>>","system-architect","<topic>","","1","1","2","","","<ABS_SESSION>/system-architect/analysis.md",""
+"3","UI Designer","<W2 prompt — see <agent_prompt_template>>","ui-designer","<topic>","","1","1","2","","","<ABS_SESSION>/ui-designer/analysis.md",""
+"4","Cross-Role Review","<W3 prompt — see <agent_prompt_template>>","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.
+
+**Column semantics (orchestrator MUST honor when generating tasks.csv)**:
+- `description`: full agent prompt — orchestrator MUST inflate `<W1/W2/W3 prompt>` placeholders using the templates in `<agent_prompt_template>` below. Never leave it as `"..."` — the spawned agent reads ONLY this field as its task brief.
+- `output_file`: **index file only** (single primary deliverable used by Wave 3 reviewer to locate the role). Wave 2 role agents write multiple files (`analysis.md` + per-feature + findings) under the same `{role}/` directory; the CSV only tracks the index path for dependency wiring.
+- **All paths in CSV (`output_file`, any path referenced in `description`) MUST be absolute.** Orchestrator MUST resolve `<ABS_SESSION>` to the absolute session dir (e.g. `D:/proj/.workflow/.csv-wave/20260521-brainstorm-foo/`) before writing tasks.csv. Relative paths break agent Write calls.
+
+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>
 
+<agent_prompt_template>
+The orchestrator MUST inflate the CSV `description` field per row using these templates before invoking `spawn_agents_on_csv`. Without inflation, spawned agents have no contract and will not write files.
+
+### W1 prompt (role: guidance-generator)
+
+```
+You are the guidance generator for a brainstorm session on: <topic>.
+
+OUTPUT: Write `<ABS_SESSION>/guidance-specification.md` using the Write tool. MUST be on disk; do NOT return as chat text.
+
+CONTRACT — guidance-specification.md sections:
+  §1 Project Positioning & Goals
+  §2 Concepts & Terminology (5–10 core terms table)
+  §3 Non-Goals (Out of Scope) with rationale
+  §4–N Role Decisions with RFC 2119 keywords (MUST / SHOULD / MAY / MUST NOT / SHOULD NOT)
+  Cross-Role Integration
+  Risks & Constraints
+  §10 Feature Decomposition (max 8 features, F-{3-digit} id + slug, independently implementable)
+  §11 Decision Tracking appendix (incrementally populated during interview)
+  §12 Cross-Role Resolutions (initially empty — populated by Wave 3)
+
+CONSTRAINTS:
+- All behavioural statements MUST use RFC 2119 keywords.
+- No interrogative sentences in the deliverable (all declarative).
+- After write, verify with Glob; emit `TASK COMPLETE` only after file exists on disk.
+```
+
+### W2 prompt (role: one of the 9 valid roles)
+
+```
+You are the <role> for a brainstorm session on: <topic>.
+
+INPUTS:
+- Read guidance-specification.md at: <ABS_SESSION>/guidance-specification.md
+- Extract decisions belonging to your role (by ID prefix) and the §10 feature list.
+- If <ABS_SESSION>/design-research.md exists, integrate it as evidence (cite by project name + section).
+
+OUTPUT: Write multiple files under `<ABS_SESSION>/<role>/` using the Write tool. Files on disk are the ONLY valid deliverable — do NOT return analysis as chat text.
+
+FILE LAYOUT (all under <ABS_SESSION>/<role>/):
+  analysis.md                          — INDEX (see structure below)
+  analysis-F-{id}-{slug}.md            — one per feature in guidance §10 (< 2000 words each)
+  findings-{slug}.md                   — additional discoveries (0 or more, < 1000 words each)
+
+analysis.md structure (MUST contain):
+  §1 Role Mandate (≤ 200 words: what you decide, what you defer, why you are here)
+  §2 Decision Digest — four tables:
+       Decisions      | ID | Feature | Stance | Constraints (RFC 2119) |
+       Interfaces     | Name | Contract | Consumers |
+       Cross-Cutting Positions | Topic | Stance |
+       Findings Summary | Slug | Title | Impact |
+     MUST have ≥ 1 Decisions row per feature in §10.
+  §3 Cross-Cutting Foundations — role-specific subsections (see role-specific addendum below).
+  §4 File Index — list every written file with its top-level headings.
+  §5 Outstanding TODOs
+
+REFERENCE, DON'T DUPLICATE:
+- Reference guidance decisions by ID (e.g., SA-03) — do NOT copy decision text.
+- Cross-link sub-files with relative links: `see [F-002](analysis-F-002-skill-engine.md)`.
+
+CONSTRAINTS:
+- Aim for ≥ 5 RFC 2119 keyword occurrences across analysis.md.
+- No interrogative sentences.
+- After all writes, verify with Glob that analysis.md and every analysis-F-*.md exist. Only then emit `TASK COMPLETE`.
+
+ROLE-SPECIFIC §3 ADDENDUM (use these as §3 subsection headings):
+- 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
+
+(Orchestrator inflates only the addendum line matching the current row's role.)
+```
+
+### W3 prompt (role: cross-role-reviewer)
+
+```
+You are the cross-role reviewer for a brainstorm session on: <topic>.
+
+INPUTS — read these files (do NOT modify):
+- <ABS_SESSION>/guidance-specification.md
+- <ABS_SESSION>/<role_1>/analysis.md
+- <ABS_SESSION>/<role_2>/analysis.md
+- ... (one per role from Wave 2)
+
+(Orchestrator MUST inject the actual absolute paths for all completed Wave 2 rows.)
+
+TASK: Compare §2 Decision Digests across role analysis.md index files. Identify:
+- Conflicts: contradictory stances between roles on the same feature/topic
+- Gaps: §2 Interfaces consumers referencing definitions that no role owns
+- Synergies: §2 Findings Summary items that align across roles and should cross-reference
+
+OUTPUT — return this structured markdown report as your final message (do NOT write files; the orchestrator parses your output and applies patches):
+
+  ## Conflicts (need user decision)
+  ### C-001: <one-line summary>
+    patch_targets:
+      - target_file: <ABS_SESSION>/<role-A>/analysis-F-{id}-{slug}.md  (or <role-A>/analysis.md for cross-cutting)
+        target_heading: ## <exact heading text from §4 File Index>
+        edit_type: annotate_and_strikeout
+        edit_content: > **Cross-Role Resolution (C-001)**: <1-line resolution>
+      - target_file: <ABS_SESSION>/<role-B>/analysis-F-{id}-{slug}.md
+        target_heading: ## <exact heading text>
+        edit_type: annotate_and_strikeout
+
+  ## Gaps
+  ### G-001: ...
+    patch_targets:
+      - target_file: <ABS_SESSION>/<ref-role>/analysis.md   edit_type: annotate_after_heading
+        target_heading: ### Interfaces
+      - target_file: <ABS_SESSION>/<owner-role>/analysis.md edit_type: append_to_section
+        target_heading: ### Decisions
+
+  ## Synergy Opportunities
+  ### S-001: ...
+    patch_targets:
+      - target_file: <ABS_SESSION>/<role-A>/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+      - target_file: <ABS_SESSION>/<role-B>/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+
+  ## Summary
+  conflicts_count / gaps_count / synergies_count / review_confidence (0–1)
+
+CONSTRAINTS:
+- `edit_type` is a CLOSED vocabulary: only `annotate_after_heading` / `annotate_and_strikeout` / `append_to_section`.
+- `target_heading` MUST match the heading text verbatim as it appears in the target file's §4 File Index (case + punctuation). Never invent.
+- If zero conflicts/gaps/synergies detected, return a `## Summary` block with all counts = 0 and a one-line explanation. Do not fabricate findings.
+```
+</agent_prompt_template>
+
 <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 +221,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 +249,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 +267,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 +319,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 +354,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 +364,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-fork/SKILL.md

@@ -12,6 +12,8 @@ the worktree. Since `.workflow/` is gitignored, this command explicitly copies p
 and milestone scratch artifacts into the worktree.
 
 Also supports `--sync` mode to pull latest main into an active worktree.
+
+Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree, and writes a scoped `state.json` inside the worktree containing only the forked milestone's artifacts.
 </purpose>
 
 <required_reading>

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

@@ -73,10 +73,11 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 - Write config
 
 **`deny <path>`:**
-- Normalize path to forward slashes
+- Normalize path to forward slashes, ensure trailing slash for directories
+- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
-- Set `guard.enabled = true` if not already
+- Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)
 - Write config
 
 **Step 4: Confirm**