maestro-flow 0.4.11 → 0.4.13

package/workflows/analyze.md

@@ -8,7 +8,7 @@ Multi-dimensional iterative analysis with CLI exploration, multi-perspective syn
 maestro-brainstorm (optional upstream)
         ↓ ideas, scored options
 maestro-analyze ← THIS
-        ↓ analysis.md, discussion.md, conclusions.json, context.md
+        ↓ analysis.md, discussion.md, conclusions.json, context.md, context-package.json
 maestro-plan → maestro-execute → maestro-verify
 ```
 
@@ -41,7 +41,7 @@ Quick mode (-q):
 ## Arguments
 
 ```
-$ARGUMENTS: "[phase|topic] [-y] [-c] [-q]"
+$ARGUMENTS: "[phase|topic] [-y] [-c] [-q] [--from <source>]"
 
 (no args)   -- Milestone-wide analysis (requires init + roadmap)
 <phase>     -- Phase number (phase-scoped, requires init + roadmap)
@@ -49,6 +49,7 @@ $ARGUMENTS: "[phase|topic] [-y] [-c] [-q]"
 -y / --yes  -- Auto mode, skip interactive scoping, auto-deepen
 -c / --continue -- Resume from existing session
 -q / --quick -- Quick mode, skip exploration + scoring, go straight to decision extraction
+--from <source>  -- Load upstream context package (brainstorm:ID, analyze:ID, @file, or path). Replaces --from-brainstorm
 ```
 
 ## Scope Routing
@@ -59,12 +60,31 @@ Worktree guard: If .workflow/worktree-scope.json exists, reject phase args not i
 Auto-bootstrap: Create minimal .workflow/state.json if missing.
 
 Scope determination → OUTPUT_DIR:
-  (no args) + milestone + roadmap → scope="milestone", OUTPUT_DIR=.workflow/scratch/analyze-{milestone_slug}-{date}/
+  (no args) + milestone + roadmap → scope="milestone", mode="micro", OUTPUT_DIR=.workflow/scratch/analyze-{milestone_slug}-{date}/
   (no args) without milestone/roadmap → ERROR E001
-  (number) + milestone + roadmap   → scope="phase", OUTPUT_DIR=.workflow/scratch/analyze-{phase_slug}-{date}/
+  (number) + milestone + roadmap   → scope="phase", mode="micro", OUTPUT_DIR=.workflow/scratch/analyze-{phase_slug}-{date}/
   (number) without milestone/roadmap → ERROR
-  (text) + milestone               → scope="adhoc", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
-  (text) without milestone         → scope="standalone", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
+  (text) + milestone               → scope="adhoc", mode="macro", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
+  (text) without milestone         → scope="standalone", mode="macro", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
+
+Macro mode additions (scope="adhoc" or "standalone"):
+  - In Step 6 Synthesis, evaluate scope_verdict: "small" | "medium" | "large"
+    - large: 3+ independent subsystems or hard serial dependency barriers
+    - medium: 1-2 subsystems, parallelizable
+    - small: single-file or few-file change
+  - Write scope_verdict to context.md conclusions section
+  - Include scope_verdict in context-package.json for downstream consumption
+
+Phase-to-Milestone resolution (when scope="phase"):
+  FOR each ms in state.json.milestones[]:
+    IF phase_number in ms.phases[]:
+      target_milestone = ms.id
+      BREAK
+  IF no match: target_milestone = current_milestone (fallback)
+
+  Use target_milestone (not current_milestone) for:
+    - artifact registration (milestone field in Step 8.9)
+    - loading prior artifacts (Step 1 context loading)
 
 Create OUTPUT_DIR.
 ```
@@ -79,7 +99,8 @@ Create OUTPUT_DIR.
 ├── explorations.json          # Single perspective aggregated findings (skip in -q)
 ├── perspectives.json          # Multi-perspective findings + synthesis (skip in -q)
 ├── conclusions.json           # Final synthesis, recommendations, decision trail (skip in -q)
-└── context.md                 # Decision extraction: Locked/Free/Deferred decisions for plan
+├── context.md                 # Decision extraction: Locked/Free/Deferred decisions for plan
+└── context-package.json       # Standardized context package for cross-command consumption
 ```
 
 ---
@@ -105,7 +126,17 @@ Parse $ARGUMENTS to determine mode and flags:
 2. Read `.workflow/roadmap.md` — phase structure and dependencies
 3. Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context` (key_decisions, deferred items, blockers)
 4. Find prior analyze artifacts from `state.json.artifacts[]` where type=analyze and same milestone → load their `context.md` to skip already-decided areas
-5. Find brainstorm artifacts from `state.json.artifacts[]` where type=brainstorm and same milestone → load `guidance-specification.md` if exists
+5. **Load upstream context** (priority order):
+   a. If `--from` specified: resolve source → load `context-package.json` (see §9 of workflow-structure-guide.md)
+      - `--from brainstorm:ID` → `state.json.artifacts[type=brainstorm, id=ID].context_package` → load
+      - `--from @file` → create import session, delegate extraction → load context-package.json
+      - `--from path/` → load `path/context-package.json`
+   b. Else: auto-discover from `state.json.artifacts[]` where type=brainstorm and same milestone → if artifact has `context_package` field, load it; else fallback to reading `guidance-specification.md` directly
+   
+   From loaded context-package:
+   - `constraints[status=locked]` → skip these areas (already decided)
+   - `constraints[status=open]` → prioritize for analysis
+   - `open_questions[]` → seed discussion topics
 6. Load project specs: `specs_content = maestro spec load --category arch`
 
 **Load prior context** (adhoc/standalone scope):
@@ -496,7 +527,40 @@ Write to `OUTPUT_DIR/context.md`:
 {relevant code references from exploration or discussion}
 ```
 
-**8.6: Update project.md Key Decisions** (phase mode only)
+**8.6: Write context-package.json**
+
+Write to `OUTPUT_DIR/context-package.json`:
+
+```jsonc
+{
+  "$schema": "context-package/1.0",
+  "source": {
+    "type": "analyze",
+    "artifact_id": "{artifact_id}",
+    "session_path": "{OUTPUT_DIR relative to .workflow/}",
+    "generated_at": "{ISO-8601}"
+  },
+  "requirements": [],      // From conclusions.json implementation_scope items (if any)
+  "constraints": [],        // Locked → { status: "locked" }, Free → { status: "open" }, Deferred → { status: "deferred" }
+  "domain": {},             // Inherit from upstream context-package if loaded via --from
+  "non_goals": [],          // Deferred items → { title, rationale, ref: "context.md#Deferred" }
+  "insights": [],           // From conclusions.json recommendations → { role: "analyzer", area, summary }
+  "open_questions": [],     // Free decisions without strong recommendation → { area, question, options[] }
+  "references": [
+    { "type": "analysis", "path": "context.md" },
+    { "type": "conclusions", "path": "conclusions.json" }
+  ]
+}
+```
+
+Extraction mapping from context.md sections:
+- Each "Locked" decision → `constraints[]` with `status: "locked"`, `ref: "context.md#Locked"`
+- Each "Free" decision → `constraints[]` with `status: "open"`, `ref: "context.md#Free"`
+- Each "Deferred" item → `non_goals[]` with `ref: "context.md#Deferred"`
+- From `conclusions.json.implementation_scope[]` (if exists) → `requirements[]` with `{ id, title: scope.objective, acceptance: scope.acceptance_criteria, ref: "conclusions.json" }`
+- From `conclusions.json.recommendations[]` → `insights[]`
+
+**8.7: Update project.md Key Decisions** (phase mode only)
 
 ```
 Phase mode only: Append each new Locked decision to .workflow/project.md "## Key Decisions" table.
@@ -504,7 +568,7 @@ Row format: | {decision title} | {rationale summary} | Phase {NN} — {date} |
 Skip duplicates (match by title).
 ```
 
-**8.7: Auto-create Issues from Deferred Items**
+**8.8: Auto-create Issues from Deferred Items**
 
 ```
 For each Deferred decision, create an issue in .workflow/issues/issues.jsonl:
@@ -516,7 +580,7 @@ For each Deferred decision, create an issue in .workflow/issues/issues.jsonl:
   tags: ["deferred", "analyze"]
 ```
 
-### Step 8.8: Register Artifact
+### Step 8.9: Register Artifact
 
 ```
 Register artifact in .workflow/state.json:
@@ -525,6 +589,7 @@ Register artifact in .workflow/state.json:
   milestone: current_milestone (null if standalone)
   phase: phase_num (null if milestone/adhoc/standalone)
   path: OUTPUT_DIR relative to .workflow/
+  context_package: "{OUTPUT_DIR}/context-package.json"   // relative to .workflow/
   harvested: false, created_at: session_start_time, completed_at: now()
 Atomic write (tmp + rename).
 ```
@@ -598,6 +663,7 @@ Decisions: {decision_count} (Locked: {n}, Free: {n}, Deferred: {n})
 
 Files:
   context.md           — Locked/Free/Deferred decisions for plan
+  context-package.json — Standardized context package for cross-command consumption
   discussion.md        — Full discussion timeline (full mode)
   analysis.md          — 6-dimension scoring summary (full mode)
   conclusions.json     — Structured conclusions (full mode)
@@ -698,10 +764,12 @@ Replaceable blocks (overwritten each round):
 
 **Both modes (full + quick):**
 - context.md written with all decisions classified as Locked/Free/Deferred
+- context-package.json written with constraints, requirements, insights, and open_questions
 - Gray areas identified through phase-specific analysis
 - Scope creep redirected to Deferred section
 - Every decision follows Context/Options/Chosen/Reason protocol
 - Prior context loaded and applied (no re-asking decided questions)
+- Upstream context loaded via `--from` when specified (context-package.json consumed)
 
 ## Error Handling
 

package/workflows/auto-test.md

@@ -36,7 +36,7 @@ specs_arch = maestro spec load --category arch
 
 ### Step 1: Read State & Route
 
-Read project state signals and auto-select scenario source. This is the **sole branch point** in the pipeline.
+Read project state signals and auto-select scenario source. This is the **primary branch point, with Route-specific extraction in Step 2** (after Step 2 normalization, the downstream pipeline is identical).
 
 ```
 Priority: Resume > Re-run > Spec > Gap > Code
@@ -54,9 +54,14 @@ Priority: Resume > Re-run > Spec > Gap > Code
    Action: load failed/blocked scenarios with status reset to pending
    Skip to Step 4 (scenarios pre-loaded, plan confirmation)
 
+# Note: `integration/state.json` and `business/business-test-report.json` are
+# legacy compat paths read for backward compatibility only. The new pipeline
+# writes exclusively to `.tests/auto-test/state.json` and `.tests/auto-test/report.json`
+# (these legacy paths are superseded; see migration table at end of file).
+
 3. SPEC:
-   Check: .workflow/.spec/SPEC-*/requirements/REQ-*.md exists
-   Resolve: SPEC_DIR from index.json.spec_ref or most recent SPEC-*/
+   Check: .workflow/blueprint/BLP-*/requirements/REQ-*.md exists
+   Resolve: SPEC_DIR from index.json.blueprint_ref or most recent BLP-*/
    If SPEC_DIR found: set ROUTE = "spec", SPEC_MODE = "full"
    If no spec but has success_criteria: set ROUTE = "spec", SPEC_MODE = "degraded"
 
@@ -286,7 +291,7 @@ Output: `infrastructure` object passed to Steps 5-6.
 {
   "phase": "{phase}",
   "source_route": "{ROUTE}",
-  "spec_ref": "{SPEC_DIR name or null}",
+  "blueprint_ref": "{SPEC_DIR name or null}",
   "spec_mode": "full|degraded|null",
   "generated_at": "{ISO timestamp}",
   "infrastructure": { "framework": "...", "run_command": "..." },
@@ -307,7 +312,7 @@ Output: `infrastructure` object passed to Steps 5-6.
 === AUTO-TEST PLAN ===
 来源:  {ROUTE}
 阶段:  {phase_name}
-Spec:  {spec_ref or "N/A"}
+Blueprint: {blueprint_ref or "N/A"}
 
 层级分布:
   L0 Static:      {N} checks
@@ -520,7 +525,7 @@ Scored after each REFLECT step. Dimensions (5): scenario_coverage, test_quality,
   "phase": "{phase}",
   "phase_dir": "{PHASE_DIR}",
   "source_route": "spec|gap|code|re-run",
-  "spec_ref": "SPEC-001 | null",
+  "blueprint_ref": "SPEC-001 | null",
   "spec_mode": "full|degraded|null",
   "status": "converged|max_iter_reached|confirmed_defects|single_pass",
   "flags": { "max_iter": 5, "layer": null, "dry_run": false, "re_run": false },
@@ -550,7 +555,7 @@ Scored after each REFLECT step. Dimensions (5): scenario_coverage, test_quality,
 {
   "phase": "{phase}",
   "source_route": "{ROUTE}",
-  "spec_ref": "{spec ref or null}",
+  "blueprint_ref": "{spec ref or null}",
   "spec_mode": "full|degraded|null",
   "completed_at": "{ISO timestamp}",
   "convergence": {

package/workflows/blueprint.md

@@ -0,0 +1,431 @@
+# Workflow: Blueprint
+
+Blueprint specification document chain producing a complete specification package (Product Brief, PRD, Architecture, Epics) through 6 sequential phases with multi-CLI analysis and interactive refinement. Pure documentation — no code generation.
+
+## Pipeline Position
+
+```
+brainstorm (parallel) → blueprint → analyze → plan
+```
+
+## Architecture
+
+```
+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
+```
+
+## Arguments
+
+```
+$ARGUMENTS: "<idea or @file> [-y] [-c] [--from <source>]"
+
+<idea>              -- Idea text or @file reference
+-y / --yes          -- Auto mode, skip interactive questions
+-c / --continue     -- Resume from last checkpoint
+--from <source>     -- Load upstream context package (brainstorm:ID, @file, or path) as enriched seed. Alias: --from-brainstorm
+```
+
+## Output Structure
+
+```
+.workflow/blueprint/BLP-{slug}-{YYYY-MM-DD}/
+├── blueprint-config.json             # Session configuration + phase state
+├── discovery-context.json        # Codebase exploration (optional)
+├── refined-requirements.json     # Phase 1.5: Confirmed requirements
+├── glossary.json                 # Phase 2: Terminology glossary
+├── product-brief.md              # Phase 2: Product brief
+├── requirements/                 # Phase 3: Detailed PRD
+│   ├── _index.md                 #   Summary, MoSCoW table, traceability
+│   ├── REQ-NNN-{slug}.md         #   Functional requirement
+│   └── NFR-{type}-NNN-{slug}.md  #   Non-functional requirement
+├── architecture/                 # Phase 4: Architecture decisions
+│   ├── _index.md                 #   Overview, components, tech stack
+│   └── ADR-NNN-{slug}.md         #   Architecture Decision Record
+├── epics/                        # Phase 5: Epic/Story breakdown
+│   ├── _index.md                 #   Epic table, dependency map, MVP
+│   └── EPIC-NNN-{slug}.md        #   Individual Epic with Stories
+├── readiness-report.md           # Phase 6: Quality report
+└── blueprint-summary.md          # Phase 6: Executive summary
+```
+
+---
+
+## Process
+
+### Step 1: Prerequisite Loading (Phase 0)
+
+Load specification and template documents:
+
+| Document | Purpose | Priority |
+|----------|---------|----------|
+| Document standards | Format, frontmatter, naming conventions | P0 - must read |
+| Quality gates | Per-phase quality criteria and scoring | P0 - must read |
+| Templates | product-brief, requirements-prd, architecture-doc, epics-template | Read on-demand per phase |
+
+**Load project specs and history**:
+
+Additional full-mode rules:
+- Features in `already_shipped` are EXCLUDED from spec generation scope
+- `lessons_learned` inform risk assessment in Phase 1 and architecture decisions in Phase 4
+- Pass assembled `project_context` to Phase 1 seed analysis
+
+### Step 2: Discovery & Seed Analysis (Phase 1)
+
+Parse input, analyze the seed idea, optionally explore codebase, establish session.
+
+**Step 2.1: Input Parsing**
+- Parse $ARGUMENTS: extract idea/topic, flags (-y, -c, --from)
+- If `-c`: read blueprint-config.json, resume from first incomplete phase
+- If `--from <source>` (or `--from-brainstorm SESSION-ID` alias):
+  - Resolve source to `context-package.json`:
+    - `brainstorm:ID` → `state.json.artifacts[type=brainstorm, id=ID].context_package`
+    - `@file` → create import session → delegate extraction → context-package.json
+    - `path/` → load `path/context-package.json`
+    - `--from-brainstorm SESSION-ID` → alias for `--from brainstorm:{resolve(SESSION-ID)}`
+  - Load context-package.json as enriched seed:
+    - `requirements[]` → Phase 3 PRD seed requirements (skip Phase 1.5)
+    - `constraints[]` → Phase 4 Architecture ADR seed
+    - `domain.terminology[]` → Phase 2 Glossary seed
+    - `domain.problem_statement` → Phase 2 Product Brief context
+    - `non_goals[]` → Phase 2 Product Brief exclusions
+    - `insights[]` → Phase 4 Architecture decisions context
+    - `references[]` → available for deep-read when needed
+  - Set `input_type: "context-package"` — skip Phase 1.5
+- If `@file`: read file content as seed
+- If text: use directly as seed
+- Missing input → error E001
+
+**Step 2.2: Session Initialization**
+```
+Session ID: BLP-{slug}-{YYYY-MM-DD}
+Output dir: .workflow/blueprint/{session_id}/
+```
+
+**Step 2.3: Seed Analysis via CLI**
+- Spawn CLI analysis to extract: problem_statement, target_users, domain, constraints, dimensions (3-5)
+- Assess complexity: simple (1-2 components) / moderate (3-5) / complex (6+)
+- For context-package input: enrich with feature decomposition data
+
+**Step 2.4: Codebase Exploration**
+- Output: `discovery-context.json` with relevant_files, patterns, tech_stack
+
+**Step 2.5: External Research**
+
+`apiResearchContext` is passed into:
+- Step 4 (Product Brief): technology feasibility assessment
+- Step 5 (Requirements): API-aware requirement writing with concrete constraints
+- Step 6 (Architecture): informed ADR decisions with version-specific details
+- Step 7 (Epics): realistic story sizing based on API complexity
+
+**Step 2.6: Spec Type Selection**
+- Interactive (AskUserQuestion): Service / API / Library / Platform
+- `--yes`: default to "service"
+- Each type loads a profile template for domain-specific sections
+
+**Step 2.7: User Confirmation (interactive)**
+- Confirm problem statement, select depth (Light/Standard/Comprehensive), select focus areas
+- `--yes`: accept all defaults
+
+**Output**: `blueprint-config.json`, `discovery-context.json` (optional), `apiResearchContext` (in-memory, optional)
+
+### Step 3: Requirement Expansion & Clarification (Phase 1.5)
+
+Skip if `--from` (requirements already in context-package.json).
+
+**Step 3.1: CLI Gap Analysis**
+- Analyze seed for completeness (score 1-10), identify missing dimensions
+- Generate 3-5 clarification areas with questions and expansion suggestions
+- Dimensions checked: functional scope, user scenarios, NFRs, integrations, data model, error handling
+
+**Step 3.2: Interactive Discussion Loop (max 5 rounds)**
+- Round 1: present gap analysis + expansion suggestions via AskUserQuestion
+- Round N: CLI follow-up analysis based on user responses, refine requirements
+- User can: answer questions, accept suggestions, or skip to generation
+- `--yes`: CLI auto-expansion without interaction
+
+**Step 3.3: User Confirmation**
+- Present requirement summary, user confirms or requests adjustments
+- `--yes`: auto-confirm
+
+**Output**: `refined-requirements.json` (confirmed features, NFRs, boundaries, assumptions)
+
+### Step 4: Product Brief (Phase 2)
+
+Generate product brief through multi-perspective CLI analysis.
+
+**Step 4.1: Load Context**
+- Read refined-requirements.json (preferred) or seed_analysis fallback
+- Read discovery-context.json (if codebase detected)
+- For context-package input: read context-package.json domain and requirements sections
+
+**Step 4.2: Multi-CLI Parallel Analysis (3 perspectives)**
+
+| Perspective | Role | Focus |
+|-------------|------|-------|
+| Product | analyze | Vision, market fit, success criteria, scope boundaries |
+| Technical | review | Feasibility, constraints, integration complexity, tech recommendations |
+| User | explore | Personas, journey maps, pain points, UX criteria |
+
+**Step 4.3: Synthesis**
+- Extract convergent themes (all agree), conflicts (need resolution), unique insights
+- For context-package input: cross-reference with context-package insights and constraints
+- If `apiResearchContext` is set: inject API details into technical feasibility assessment
+
+**Step 4.4: Interactive Refinement**
+- Present synthesis, user adjusts scope/vision
+- `--yes`: accept synthesis as-is
+
+**Step 4.5: Generate Outputs**
+- `product-brief.md` from template (YAML frontmatter + filled content)
+- `glossary.json` — 5+ core terms extracted from product brief and CLI analysis
+  - Each term: canonical name, definition, aliases, category (core/technical/business)
+  - Injected into all subsequent phase CLI prompts for terminology consistency
+
+**Output**: `product-brief.md`, `glossary.json`
+
+### Step 5: Requirements / PRD (Phase 3)
+
+Generate detailed PRD with functional/non-functional requirements.
+
+**Step 5.1: Requirement Expansion via CLI**
+- For each product brief goal, generate 3-7 functional requirements
+- Each requirement: REQ-NNN ID, title, description, user story, 2-4 acceptance criteria
+- Generate non-functional requirements: performance, security, scalability, usability
+- Apply RFC 2119 keywords (MUST/SHOULD/MAY) to all behavioral constraints
+- Define core entity data models: fields, types, constraints, relationships
+- Inject glossary.json for terminology consistency
+
+**Step 5.2: MoSCoW Priority Sorting (interactive)**
+- Present requirements grouped by initial priority
+- User adjusts Must/Should/Could/Won't labels
+- Select MVP scope: Must-only / Must+key Should / Comprehensive
+- `--yes`: accept CLI-suggested priorities
+
+**Step 5.3: Generate Directory**
+- `requirements/_index.md` — summary table, MoSCoW breakdown, traceability matrix
+- `requirements/REQ-NNN-{slug}.md` — one per functional requirement
+- `requirements/NFR-{type}-NNN-{slug}.md` — one per non-functional requirement
+
+**Output**: `requirements/` directory (index + individual files)
+
+### Step 6: Architecture (Phase 4)
+
+Generate architecture decisions, component design, and technology selections.
+
+**Step 6.1: Architecture Analysis via CLI (role: review)**
+- System architecture style with justification
+- Core components and responsibilities
+- Component interaction diagram (Mermaid graph TD)
+- Technology stack: languages, frameworks, databases, infrastructure
+- 2-4 Architecture Decision Records (ADRs): context, decision, alternatives, consequences
+- Data model: entities and relationships (Mermaid erDiagram)
+- Security architecture: auth, authorization, data protection
+- **State machine**: ASCII diagram + transition table for lifecycle entities (service/platform type)
+- **Configuration model**: all configurable fields with type, default, constraint
+- **Error handling strategy**: per-component classification (transient/permanent/degraded), recovery mechanisms
+- **Observability**: key metrics (5+), structured log events, health checks
+- Spec type profile injection for domain-specific depth
+- Glossary injection for terminology consistency
+- If `apiResearchContext` is set: inject as "External API Research" context
+
+**Step 6.2: Architecture Review via CLI (role: review)**
+- Challenge each ADR, identify scalability bottlenecks
+- Assess security gaps, evaluate technology choices
+- Rate overall quality 1-5
+
+**Step 6.3: Interactive ADR Decisions**
+- Present ADRs with review feedback, user decides: accept / incorporate feedback / simplify
+- `--yes`: auto-accept
+
+**Step 6.4: Codebase Integration Mapping (conditional)**
+- Map new components to existing code modules
+
+**Step 6.5: Generate Directory**
+- `architecture/_index.md` — overview, component diagram, tech stack, data model, security
+- `architecture/ADR-NNN-{slug}.md` — one per Architecture Decision Record
+
+**Output**: `architecture/` directory (index + individual ADR files)
+
+### Step 7: Epics & Stories (Phase 5)
+
+Decompose specification into executable Epics and Stories.
+
+**Step 7.1: Epic Decomposition via CLI**
+- Group requirements into logical Epics (EPIC-NNN IDs). Epic count is unconstrained — downstream workflows will merge Epics into minimal phases via the minimum-phase principle.
+- Tag MVP subset
+- For each Epic: 2-5 Stories in "As a...I want...So that..." format
+- Each Story: 2-4 testable acceptance criteria, relative size (S/M/L/XL), trace to REQ-NNN
+- Cross-Epic dependency map (Mermaid graph LR)
+- Recommended execution order with rationale
+- MVP definition of done (3-5 criteria)
+
+**Epic sizing awareness** (informs downstream roadmap generation):
+- Epics that are too small (1-2 Stories, all size S) should be flagged for merge downstream
+- Each Epic should carry enough substance to become part of a phase with 5+ tasks
+- Prefer fewer, larger Epics over many tiny ones
+
+**Step 7.2: Interactive Validation**
+- Present Epic overview, user adjusts: merge/split epics, adjust MVP scope
+- `--yes`: accept as-is
+
+**Step 7.3: Generate Directory**
+- `epics/_index.md` — overview table, dependency map, MVP scope, execution order, traceability
+- `epics/EPIC-NNN-{slug}.md` — one per Epic with embedded Stories
+
+**Output**: `epics/` directory (index + individual Epic files)
+
+### Step 8: Readiness Check & Handoff (Phase 6)
+
+Validate specification package and provide execution handoff.
+
+**Step 8.1: Cross-Document Validation via CLI**
+Score on 4 dimensions (25% each):
+1. **Completeness**: all required sections present with substantive content
+2. **Consistency**: terminology uniform (glossary compliance), scope containment, non-goals respected
+3. **Traceability**: goals → requirements → architecture → epics (matrix generated)
+4. **Depth**: acceptance criteria testable, ADRs justified, stories estimable
+
+Gate decision: Pass (>=80) / Review (60-79) / Fail (<60)
+
+**Step 8.2: Generate Reports**
+- `readiness-report.md` — quality scores, issue list (Error/Warning/Info), traceability matrix
+- `blueprint-summary.md` — one-page executive summary
+
+**Step 8.3: Update Document Status**
+- All document frontmatter updated to `status: complete`
+
+**Step 8.4: Gate Routing**
+
+| Gate Result | Action |
+|-------------|--------|
+| Pass (>=80%) | Proceed to Step 11 (Final Handoff) |
+| Review (60-79%) | Proceed to Step 11 with caveats logged |
+| Fail (<60%) | Trigger Step 9 (Auto-Fix), then re-run Step 8 |
+
+### Step 9: Auto-Fix (Phase 6.5, conditional)
+
+Triggered when Phase 6 score < 60%.
+
+**Step 9.1: Parse Readiness Report**
+- Extract Error and Warning items, group by originating phase (2-5), map to affected files
+
+**Step 9.2: Fix Affected Phases (sequential, Phase 2→3→4→5)**
+- Read current phase output
+- CLI re-generation with error context injected
+- Inject glossary for terminology consistency
+- Preserve unflagged content, only fix flagged issues
+- Increment document version
+
+**Step 9.3: Re-run Phase 6**
+- Generate new readiness-report.md
+- If still Fail and iteration_count < 2: loop back
+- If Pass or max iterations (2) reached: proceed to handoff
+
+**Output**: Updated Phase 2-5 documents, updated blueprint-config.json with iteration tracking
+
+### Step 11: Final Handoff
+
+Blueprint specification package is complete. Suggest next workflow steps.
+
+**Step 11.1: Handoff Options (AskUserQuestion)**
+
+| Option | Action |
+|--------|--------|
+| Analyze specification | Run `maestro-analyze` to deep-analyze the blueprint outputs |
+| Generate roadmap | Run `maestro-roadmap` to convert Epics into a phased execution roadmap |
+| Plan first phase | Skill({ skill: "maestro-plan", args: "1" }) |
+| Create issues | Generate issues per Epic via Skill({ skill: "manage-issue" }) |
+| Export only | Blueprint complete, no further action |
+
+### Step 12: Final Report
+
+```
+== blueprint complete ==
+Session: BLP-{slug}-{date} | Quality: {score}% ({gate}) | Phases: {completed_count}/6
+Output: .workflow/blueprint/{session_id}/
+  blueprint-config.json, product-brief.md, requirements/, architecture/, epics/,
+  readiness-report.md, blueprint-summary.md
+
+Next: maestro-analyze (deep analysis) | maestro-roadmap (generate roadmap) | maestro-plan 1 (plan first phase)
+```
+
+---
+
+## Key Design Principles
+
+1. **Document Chain**: Each phase builds on previous outputs with traceability
+2. **Multi-Perspective Analysis**: CLI tools provide product, technical, and user perspectives
+3. **Interactive by Default**: Each phase offers user confirmation; `-y` enables auto mode
+4. **Resumable Sessions**: blueprint-config.json tracks phases; `-c` resumes from checkpoint
+5. **Template-Driven**: All documents from standardized templates with YAML frontmatter
+6. **Spec Type Specialization**: Templates adapt to service/api/library/platform via profiles
+7. **Terminology Consistency**: glossary.json from Phase 2 injected into all subsequent phases
+8. **Iterative Quality**: Phase 6.5 auto-fix loop (max 2 iterations)
+9. **Context Package Integration**: `--from` loads upstream context-package.json as seed (brainstorm:ID, @file, or path). `--from-brainstorm` retained as backward-compatible alias
+
+## State Management
+
+**blueprint-config.json**:
+```json
+{
+  "session_id": "BLP-xxx-2026-03-15",
+  "seed_input": "User input text",
+  "input_type": "text|file|context-package",
+  "timestamp": "ISO8601",
+  "mode": "interactive|auto",
+  "complexity": "simple|moderate|complex",
+  "depth": "light|standard|comprehensive",
+  "focus_areas": [],
+  "spec_type": "service|api|library|platform",
+  "iteration_count": 0,
+  "iteration_history": [],
+  "seed_analysis": {
+    "problem_statement": "...",
+    "target_users": [],
+    "domain": "...",
+    "constraints": [],
+    "dimensions": []
+  },
+  "has_codebase": false,
+  "phasesCompleted": [
+    { "phase": 1, "name": "discovery", "output_file": "blueprint-config.json", "completed_at": "ISO8601" }
+  ]
+}
+```
+
+Resume: `-c` reads blueprint-config.json, resumes from first incomplete phase.
+
+## Quality Dimensions (Phase 6)
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Completeness | 25% | All sections present with substance |
+| Consistency | 25% | Terminology, scope, non-goals alignment |
+| Traceability | 25% | Goals → Reqs → Arch → Epics chain |
+| Depth | 25% | Testable criteria, justified decisions, estimable stories |
+
+**Gate**: Pass (>=80%) / Review (60-79%) / Fail (<60%)
+
+## Handoff to Downstream Workflows
+
+When blueprint completes, the specification package (Product Brief, PRD, Architecture, Epics) is ready.
+Run `maestro-analyze` for deep analysis or `maestro-roadmap` to generate a phased execution roadmap from the Epics.
+
+## Error Handling
+
+| Phase | Error | Blocking? | Action |
+|-------|-------|-----------|--------|
+| Phase 1 | Empty input | Yes | Error and exit |
+| Phase 1 | CLI analysis fails | No | Basic parsing fallback |
+| Phase 1.5 | Gap analysis fails | No | Skip to basic prompts |
+| Phase 2 | Single CLI fails | No | Continue with available |
+| Phase 3 | Gemini fails | No | Codex fallback |
+| Phase 4 | Review fails | No | Skip review |
+| Phase 5 | Story generation fails | No | Generate epics only |
+| Phase 6 | Validation fails | No | Partial report |
+| Phase 6.5 | Max iterations (2) | No | Force handoff |
+| Step 2.5 | External research fails | No | apiResearchContext = null, continue |
+
+CLI Fallback Chain: Role-based resolution → degraded mode (local only)