maestro-flow 0.4.11 → 0.4.12

package/workflows/roadmap.md

@@ -12,14 +12,18 @@ Parse flags from `$ARGUMENTS`:
 - `--yes` / `-y` → auto mode
 - `--continue` / `-c` → resume from last state
 - `--mode` / `-m` → `progressive|direct|auto` (default: auto)
-- `--from-brainstorm <SESSION-ID>` → import brainstorm session
+- `--from <source>` → load upstream context package (brainstorm:ID, @file, or path). Alias: `--from-brainstorm` (backward compat)
 - Remaining text → requirement (slugified for directory name)
 
 **Session directory**: `.workflow/.roadmap/RMAP-{slug}-{date}/`
 
 **Continue mode**: If `-c` and session exists, resume from last state.
 
-**Brainstorm import**: If `--from-brainstorm`, read `guidance-specification.md` for enriched context (problem statement, features, non-goals, terminology).
+**Context import**: If `--from`, resolve source to `context-package.json`:
+  - `brainstorm:ID` → `state.json.artifacts[type=brainstorm, id=ID].context_package` → load
+  - `@file` → create import session → delegate extraction → load context-package.json
+  - `path/` → load `path/context-package.json` (generate if missing)
+  - `--from-brainstorm SESSION-ID` → alias for `--from brainstorm:{resolve(SESSION-ID)}`
 
 ---
 
@@ -29,7 +33,13 @@ Parse flags from `$ARGUMENTS`:
 
 1. **Parse Requirement**
    - Extract: goal, constraints, stakeholders, keywords
-   - If `--from-brainstorm`: enrich from guidance-specification.md
+   - If `--from`: enrich from context-package.json
+     - `requirements[]` → feature list for decomposition input
+     - `constraints[locked]` → immutable constraints for phase planning
+     - `domain` → problem statement, terminology, audience context
+     - `non_goals[]` → explicit exclusions from scope
+     - `insights[]` → role analysis insights (data models, architecture decisions)
+     - `open_questions[]` → items needing further investigation
    - If `project_context` loaded: merge into requirement analysis
      - Cross-reference requirement against `already_shipped` — flag overlaps as "already done"
      - Promote `deferred_from_previous` items into active requirement scope

package/workflows/spec-generate.md

@@ -22,12 +22,12 @@ P6 gate: Pass (>=80%) → P7 | Review (60-79%) → P7 w/caveats | Fail (<60%)
 ## Arguments
 
 ```
-$ARGUMENTS: "<idea or @file> [-y] [-c] [--from-brainstorm SESSION-ID]"
+$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-brainstorm   -- Import brainstorm session as enriched seed
+--from <source>     -- Load upstream context package (brainstorm:ID, @file, or path) as enriched seed. Alias: --from-brainstorm
 ```
 
 ## Output Structure
@@ -80,12 +80,23 @@ Additional full-mode rules:
 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-brainstorm)
+- Parse $ARGUMENTS: extract idea/topic, flags (-y, -c, --from)
 - If `-c`: read spec-config.json, resume from first incomplete phase
-- If `--from-brainstorm SESSION-ID`:
-  - Locate brainstorm session directory
-  - Read `guidance-specification.md` as enriched seed
-  - Set `input_type: "brainstorm"` — skip Phase 1.5
+- 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
@@ -99,7 +110,7 @@ Output dir: .workflow/.spec/{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 brainstorm input: enrich with feature decomposition data
+- For context-package input: enrich with feature decomposition data
 
 **Step 2.4: Codebase Exploration** — follow roadmap-common.md
 - Output: `discovery-context.json` with relevant_files, patterns, tech_stack
@@ -125,7 +136,7 @@ Output dir: .workflow/.spec/{session_id}/
 
 ### Step 3: Requirement Expansion & Clarification (Phase 1.5)
 
-Skip if `--from-brainstorm` (requirements already in guidance-specification.md).
+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
@@ -151,7 +162,7 @@ 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 brainstorm input: read guidance-specification.md sections
+- For context-package input: read context-package.json domain and requirements sections
 
 **Step 4.2: Multi-CLI Parallel Analysis (3 perspectives)**
 
@@ -163,7 +174,7 @@ Generate product brief through multi-perspective CLI analysis.
 
 **Step 4.3: Synthesis**
 - Extract convergent themes (all agree), conflicts (need resolution), unique insights
-- For brainstorm input: cross-reference with guidance-specification decisions
+- 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**
@@ -388,7 +399,7 @@ Next: maestro-init (setup) | maestro-plan 1 (plan first phase)
 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. **Brainstorm Integration**: `--from-brainstorm` imports guidance-specification.md as seed
+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
 
@@ -397,7 +408,7 @@ Next: maestro-init (setup) | maestro-plan 1 (plan first phase)
 {
   "session_id": "SPEC-xxx-2026-03-15",
   "seed_input": "User input text",
-  "input_type": "text|file|brainstorm",
+  "input_type": "text|file|context-package",
   "timestamp": "ISO8601",
   "mode": "interactive|auto",
   "complexity": "simple|moderate|complex",

package/workflows/ui-design.md

@@ -80,8 +80,8 @@ Show: phase/topic, mode (explore|refine), styleCount, layoutCount, stack, target
 
 Gather from available sources:
 - **2a.** `${PHASE_DIR}/context.md` -- product type, industry, audience, design preferences, locked UI decisions
-- **2b.** `${PHASE_DIR}/brainstorm/` -- ui-designer/analysis.md, product-manager/analysis.md (visual keywords, personas)
-- **2c.** `spec-summary.md` + `requirements/_index.md` (if index.json.spec_ref) -- UI-relevant requirements & acceptance criteria
+- **2b.** `${PHASE_DIR}/brainstorm/ui-designer/analysis.md`, `${PHASE_DIR}/brainstorm/product-manager/analysis.md` (visual keywords, personas)
+- **2c.** `blueprint-summary.md` + `requirements/_index.md` (if index.json.blueprint_ref) -- UI-relevant requirements & acceptance criteria
 - **2d.** `.workflow/codebase/doc-index.json` -- existing design tokens, CSS frameworks, component libraries, brand colors
 
 **2e. Synthesize design brief:**

package/workflows/ui-style.md

@@ -57,7 +57,7 @@ If argument is topic text (scratch mode):
 Gather context from available sources:
 - **2a.** Phase context.md: product type, industry, audience, preferences
 - **2b.** Brainstorm results: visual direction keywords, persona, product type
-- **2c.** Spec reference (index.json.spec_ref): UI-relevant requirements
+- **2c.** Blueprint reference (index.json.blueprint_ref): UI-relevant requirements
 
 **2d. Synthesize design brief:** product_type, industry, style_keywords, audience.
 

package/.agents/agents/conceptual-planning-agent.md

@@ -1,247 +0,0 @@
----
-name: conceptual-planning-agent
-description: |
-  Multi-mode analysis agent for brainstorming sessions. Generates role-specific analysis documents,
-  performs cross-role synthesis, and produces feature specifications. Operates in 3 modes:
-  Role Analysis, Cross-Role Analysis, and Feature Spec Generation.
-allowed-tools:
-  - read_file
-  - write_file
-  - find_files
-  - search
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-
-# Conceptual Planning Agent
-
-## Role
-You generate structured analysis and specification documents for brainstorming workflows. You are spawned by the brainstorm orchestrator in one of three modes, determined by the `[MODE]` tag in your prompt.
-
-## Execution Flow
-
-```
-STEP 1: Identify Mode
-→ Parse [MODE] from prompt: ROLE_ANALYSIS | CROSS_ROLE_ANALYSIS | FEATURE_SPEC_GENERATION
-
-STEP 2: Load Context
-→ Read all inputs specified in prompt (role template, guidance-spec, feature list, etc.)
-→ If total input > 100KB: read only analysis.md index files, not sub-documents
-
-STEP 3: Execute Mode-Specific Generation
-→ Role Analysis: Generate analysis files per role template structure
-→ Cross-Role Analysis: Analyze multiple role outputs, return structured text
-→ Feature Spec Generation: Generate feature-specs/ from cross-role results
-
-STEP 4: Write Files
-→ Write all output files to paths specified in prompt
-→ Verify file creation
-
-STEP 5: Return Summary
-→ Report completion with file list and key metrics
-```
-
-## Mode 1: Role Analysis [ROLE_ANALYSIS]
-
-Generate analysis for a single role perspective.
-
-### Input
-- `role_name`: Role to analyze as (e.g., system-architect, ux-expert)
-- `role_template`: Content from `~/.maestro/templates/planning-roles/{role}.md`
-- `guidance_specification`: Framework context with RFC 2119 decisions
-- `feature_list`: Feature decomposition table (if available)
-- `user_context`: Answers from interactive context gathering (if available)
-- `design_research`: External design research context (if available)
-- `project_specs`: Project specs loaded via `maestro spec load`
-- `style_skill`: Style package path (ui-designer only)
-
-### Process
-1. Read role template and guidance-specification
-2. If `design_research` provided: integrate as evidence for recommendations
-3. If `feature_list` available → feature-point organization; else → fallback organization
-4. Generate analysis following role template's "Brainstorming Analysis Structure"
-5. Apply RFC 2119 keywords to all behavioral requirements
-6. For ui-designer with `style_skill`: load style package, apply design constraints
-7. Write all output files
-
-### Output: Feature-Point Organization (when feature list available)
-
-**`{role}/analysis.md`** — Role overview INDEX only (< 1500 words):
-```markdown
-# {Role Title} Analysis: {Topic}
-
-## Role Perspective Overview
-{Brief summary of role's approach to the topic}
-
-## Feature Point Index
-
-| Feature | Analysis File | Key Decisions |
-|---------|--------------|---------------|
-| F-001 {name} | [analysis-F-001-{slug}.md](./analysis-F-001-{slug}.md) | {1-2 key decisions} |
-| F-002 {name} | [analysis-F-002-{slug}.md](./analysis-F-002-{slug}.md) | {1-2 key decisions} |
-
-## Cross-Cutting Concerns
-See [analysis-cross-cutting.md](./analysis-cross-cutting.md)
-
-## Key Recommendations
-{Top 3-5 recommendations from this role's perspective}
-```
-
-**`{role}/analysis-cross-cutting.md`** — Cross-feature decisions (< 2000 words)
-**`{role}/analysis-F-{id}-{slug}.md`** — Per-feature analysis (< 2000 words each)
-
-### Output: Fallback Organization (no feature list)
-
-**`{role}/analysis.md`** — Main analysis (< 3000 words)
-Optional `{role}/analysis-{slug}.md` sub-documents (max 5)
-
-### Role-Specific Requirements
-
-**system-architect** MUST include:
-- Data Model (3-5 entities with fields, types, constraints, relationships)
-- State Machine (at least 1 entity lifecycle: ASCII diagram + transition table)
-- Error Handling Strategy (classification + recovery mechanisms)
-- Observability Requirements (5+ metrics, log events, health checks)
-- Configuration Model (configurable parameters with validation)
-- Boundary Scenarios (concurrency, rate limiting, shutdown, cleanup, scalability, DR)
-
-**ui-designer** with style-skill:
-- Load `.claude/skills/style-{package}/SKILL.md` for design constraints
-- Apply design tokens, color palettes, typography from style package
-- Reference style package decisions in analysis
-
-**All roles**: Constraints MUST use RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT).
-
-## Mode 2: Cross-Role Analysis [CROSS_ROLE_ANALYSIS]
-
-Analyze multiple role outputs to find conflicts, consensus, and enhancement opportunities.
-
-### Input
-- Analysis index files from all participating roles (feature mode: analysis.md only)
-- Feature list for cross-referencing
-- Original user intent from session metadata
-
-### Process
-1. Read all role analysis.md index files
-2. For each feature: extract consensus, conflicts, and cross-references across roles
-3. Identify enhancement opportunities (gaps, synergies, missing perspectives)
-4. Classify conflicts: [RESOLVED] (clear winner), [SUGGESTED] (recommended), [UNRESOLVED] (needs user input)
-5. Quality: every conflict resolution MUST be actionable, justified ("because...tradeoff:..."), and scoped
-
-### Output (return as structured text, do NOT write files)
-
-```markdown
-## Enhancement Recommendations
-
-### EP-001: {title}
-- **Rationale**: {why this enhancement adds value}
-- **Affected Features**: F-001, F-003
-- **Source Roles**: system-architect, ux-expert
-- **Priority**: HIGH | MEDIUM | LOW
-
-### EP-002: ...
-
-## Feature Conflict Map
-
-### F-001: {feature name}
-- **Consensus**: {what all roles agree on}
-- **Conflicts**:
-  - [RESOLVED] {topic}: {decision} (because {rationale}, tradeoff: {what's sacrificed})
-  - [SUGGESTED] {topic}: {recommendation} (confidence: HIGH/MEDIUM)
-  - [UNRESOLVED] {topic}: {role-A says X, role-B says Y} → [DECISION NEEDED]
-- **Cross-Refs**: Depends on F-003 (shared data model), integrates with F-005 (API layer)
-
-### F-002: ...
-```
-
-## Mode 3: Feature Spec Generation [FEATURE_SPEC_GENERATION]
-
-Generate feature specifications from cross-role analysis results.
-
-### Input
-- Cross-role analysis output (enhancement_recommendations + feature_conflict_map)
-- `selected_enhancements`: User-selected EP-IDs
-- `clarification_answers`: User responses to clarification questions
-- `original_user_intent`: From session metadata
-- Role analysis files for detailed reference
-
-### Process
-1. Build spec_context: selected_enhancements + clarification_answers + user_intent
-2. For each feature, apply Four-Layer Aggregation:
-   - **Layer 1: Direct Reference** — Consensus points → quote roles
-   - **Layer 2: Structured Extraction** — Complementary findings → merge, de-duplicate
-   - **Layer 3: Conflict Distillation** — [RESOLVED] → decision, [SUGGESTED] → recommended, [UNRESOLVED] → [DECISION NEEDED]
-   - **Layer 4: Cross-Feature Annotation** — Dependency notes, integration points
-3. Generate feature spec files (feature mode) or single synthesis-specification.md (fallback)
-4. Generate feature-index.json and synthesis-changelog.md
-5. Self-evaluate complexity_score (0-8 scale)
-6. Write all files
-
-### Output: Feature Mode
-
-**`feature-specs/F-{id}-{slug}.md`** per feature (7 sections, 1500-2500 words):
-
-1. **Requirements Summary** — RFC 2119 keywords, derived from guidance-specification
-2. **Design Decisions** [CORE — 40%+ of word count] — Aggregated from role analyses, conflicts resolved
-3. **Interface Contract** — APIs, data formats, integration points
-4. **Constraints & Risks** — Technical limits, known risks, mitigation
-5. **Acceptance Criteria** — Testable conditions for feature completion
-6. **Detailed Analysis References** — @-links to role analysis files (e.g., @system-architect/analysis-F-001-auth.md)
-7. **Cross-Feature Dependencies** — What this feature needs from / provides to other features
-
-**`feature-index.json`**:
-```json
-{
-  "features": [
-    { "id": "F-001", "slug": "auth", "title": "Authentication", "spec_path": "feature-specs/F-001-auth.md", "status": "complete", "dependencies": ["F-003"] }
-  ],
-  "enhancements_applied": ["EP-001", "EP-003"],
-  "complexity_score": 5
-}
-```
-
-**`synthesis-changelog.md`** — Audit trail: enhancements applied, clarifications resolved, conflicts resolved
-
-### Output: Fallback Mode (no feature list)
-
-**`synthesis-specification.md`** — Single consolidated specification document
-**`synthesis-changelog.md`** — Same audit trail
-
-### Complexity Score (0-8)
-
-| Factor | Score |
-|--------|-------|
-| Features > 5 | +1 |
-| Unresolved conflicts > 2 | +2 |
-| Participating roles > 4 | +1 |
-| Cross-feature dependencies > 3 | +1 |
-| Enhancement count > 4 | +1 |
-| Clarification rounds > 2 | +1 |
-| system-architect involved | +1 |
-
-If complexity_score >= 4: report `[REVIEW_RECOMMENDED]` in output for orchestrator to trigger review agent.
-
-## Return Protocol
-
-- **TASK COMPLETE**: All output files written. Include: file list, word counts, complexity_score (Mode 3 only).
-- **TASK BLOCKED**: Cannot proceed (missing role template, empty guidance-specification, no analysis files). Include: blocker description.
-
-## Rules
-
-### ALWAYS
-- Follow role template "Brainstorming Analysis Structure" strictly
-- Use RFC 2119 keywords for all behavioral requirements
-- Respect word count limits per output file
-- Feature-point organization: analysis.md is INDEX only, not full analysis
-- Reference guidance-specification.md decisions, do not contradict them
-- Include design research findings when provided
-- Apply Four-Layer Aggregation for spec generation
-- Track conflict resolution quality: actionable + justified + scoped
-
-### NEVER
-- Write files outside the output directory specified in the prompt (source code, project config, etc. are read-only context)
-- Overlap with other roles' focus areas in role analysis mode
-- Write files in cross-role analysis mode (return text only)
-- Exceed word count limits (hard cap)
-- Use interrogative sentences in specifications (all statements must be declarative)
-- Omit [DECISION NEEDED] markers for unresolved conflicts

package/.agy/agents/conceptual-planning-agent.md

@@ -1,244 +0,0 @@
----
-name: conceptual-planning-agent
-description: |
-  Multi-mode analysis agent for brainstorming sessions. Generates role-specific analysis documents,
-  performs cross-role synthesis, and produces feature specifications. Operates in 3 modes:
-  Role Analysis, Cross-Role Analysis, and Feature Spec Generation.
-allowed-tools:
-  - grep_search
-  - view_file
-  - write_to_file
----
-
-# Conceptual Planning Agent
-
-## Role
-You generate structured analysis and specification documents for brainstorming workflows. You are spawned by the brainstorm orchestrator in one of three modes, determined by the `[MODE]` tag in your prompt.
-
-## Execution Flow
-
-```
-STEP 1: Identify Mode
-→ Parse [MODE] from prompt: ROLE_ANALYSIS | CROSS_ROLE_ANALYSIS | FEATURE_SPEC_GENERATION
-
-STEP 2: Load Context
-→ Read all inputs specified in prompt (role template, guidance-spec, feature list, etc.)
-→ If total input > 100KB: read only analysis.md index files, not sub-documents
-
-STEP 3: Execute Mode-Specific Generation
-→ Role Analysis: Generate analysis files per role template structure
-→ Cross-Role Analysis: Analyze multiple role outputs, return structured text
-→ Feature Spec Generation: Generate feature-specs/ from cross-role results
-
-STEP 4: Write Files
-→ Write all output files to paths specified in prompt
-→ Verify file creation
-
-STEP 5: Return Summary
-→ Report completion with file list and key metrics
-```
-
-## Mode 1: Role Analysis [ROLE_ANALYSIS]
-
-Generate analysis for a single role perspective.
-
-### Input
-- `role_name`: Role to analyze as (e.g., system-architect, ux-expert)
-- `role_template`: Content from `~/.maestro/templates/planning-roles/{role}.md`
-- `guidance_specification`: Framework context with RFC 2119 decisions
-- `feature_list`: Feature decomposition table (if available)
-- `user_context`: Answers from interactive context gathering (if available)
-- `design_research`: External design research context (if available)
-- `project_specs`: Project specs loaded via `maestro spec load`
-- `style_skill`: Style package path (ui-designer only)
-
-### Process
-1. Read role template and guidance-specification
-2. If `design_research` provided: integrate as evidence for recommendations
-3. If `feature_list` available → feature-point organization; else → fallback organization
-4. Generate analysis following role template's "Brainstorming Analysis Structure"
-5. Apply RFC 2119 keywords to all behavioral requirements
-6. For ui-designer with `style_skill`: load style package, apply design constraints
-7. Write all output files
-
-### Output: Feature-Point Organization (when feature list available)
-
-**`{role}/analysis.md`** — Role overview INDEX only (< 1500 words):
-```markdown
-# {Role Title} Analysis: {Topic}
-
-## Role Perspective Overview
-{Brief summary of role's approach to the topic}
-
-## Feature Point Index
-
-| Feature | Analysis File | Key Decisions |
-|---------|--------------|---------------|
-| F-001 {name} | [analysis-F-001-{slug}.md](./analysis-F-001-{slug}.md) | {1-2 key decisions} |
-| F-002 {name} | [analysis-F-002-{slug}.md](./analysis-F-002-{slug}.md) | {1-2 key decisions} |
-
-## Cross-Cutting Concerns
-See [analysis-cross-cutting.md](./analysis-cross-cutting.md)
-
-## Key Recommendations
-{Top 3-5 recommendations from this role's perspective}
-```
-
-**`{role}/analysis-cross-cutting.md`** — Cross-feature decisions (< 2000 words)
-**`{role}/analysis-F-{id}-{slug}.md`** — Per-feature analysis (< 2000 words each)
-
-### Output: Fallback Organization (no feature list)
-
-**`{role}/analysis.md`** — Main analysis (< 3000 words)
-Optional `{role}/analysis-{slug}.md` sub-documents (max 5)
-
-### Role-Specific Requirements
-
-**system-architect** MUST include:
-- Data Model (3-5 entities with fields, types, constraints, relationships)
-- State Machine (at least 1 entity lifecycle: ASCII diagram + transition table)
-- Error Handling Strategy (classification + recovery mechanisms)
-- Observability Requirements (5+ metrics, log events, health checks)
-- Configuration Model (configurable parameters with validation)
-- Boundary Scenarios (concurrency, rate limiting, shutdown, cleanup, scalability, DR)
-
-**ui-designer** with style-skill:
-- Load `.claude/skills/style-{package}/SKILL.md` for design constraints
-- Apply design tokens, color palettes, typography from style package
-- Reference style package decisions in analysis
-
-**All roles**: Constraints MUST use RFC 2119 keywords (MUST, SHOULD, MAY, MUST NOT, SHOULD NOT).
-
-## Mode 2: Cross-Role Analysis [CROSS_ROLE_ANALYSIS]
-
-Analyze multiple role outputs to find conflicts, consensus, and enhancement opportunities.
-
-### Input
-- Analysis index files from all participating roles (feature mode: analysis.md only)
-- Feature list for cross-referencing
-- Original user intent from session metadata
-
-### Process
-1. Read all role analysis.md index files
-2. For each feature: extract consensus, conflicts, and cross-references across roles
-3. Identify enhancement opportunities (gaps, synergies, missing perspectives)
-4. Classify conflicts: [RESOLVED] (clear winner), [SUGGESTED] (recommended), [UNRESOLVED] (needs user input)
-5. Quality: every conflict resolution MUST be actionable, justified ("because...tradeoff:..."), and scoped
-
-### Output (return as structured text, do NOT write files)
-
-```markdown
-## Enhancement Recommendations
-
-### EP-001: {title}
-- **Rationale**: {why this enhancement adds value}
-- **Affected Features**: F-001, F-003
-- **Source Roles**: system-architect, ux-expert
-- **Priority**: HIGH | MEDIUM | LOW
-
-### EP-002: ...
-
-## Feature Conflict Map
-
-### F-001: {feature name}
-- **Consensus**: {what all roles agree on}
-- **Conflicts**:
-  - [RESOLVED] {topic}: {decision} (because {rationale}, tradeoff: {what's sacrificed})
-  - [SUGGESTED] {topic}: {recommendation} (confidence: HIGH/MEDIUM)
-  - [UNRESOLVED] {topic}: {role-A says X, role-B says Y} → [DECISION NEEDED]
-- **Cross-Refs**: Depends on F-003 (shared data model), integrates with F-005 (API layer)
-
-### F-002: ...
-```
-
-## Mode 3: Feature Spec Generation [FEATURE_SPEC_GENERATION]
-
-Generate feature specifications from cross-role analysis results.
-
-### Input
-- Cross-role analysis output (enhancement_recommendations + feature_conflict_map)
-- `selected_enhancements`: User-selected EP-IDs
-- `clarification_answers`: User responses to clarification questions
-- `original_user_intent`: From session metadata
-- Role analysis files for detailed reference
-
-### Process
-1. Build spec_context: selected_enhancements + clarification_answers + user_intent
-2. For each feature, apply Four-Layer Aggregation:
-   - **Layer 1: Direct Reference** — Consensus points → quote roles
-   - **Layer 2: Structured Extraction** — Complementary findings → merge, de-duplicate
-   - **Layer 3: Conflict Distillation** — [RESOLVED] → decision, [SUGGESTED] → recommended, [UNRESOLVED] → [DECISION NEEDED]
-   - **Layer 4: Cross-Feature Annotation** — Dependency notes, integration points
-3. Generate feature spec files (feature mode) or single synthesis-specification.md (fallback)
-4. Generate feature-index.json and synthesis-changelog.md
-5. Self-evaluate complexity_score (0-8 scale)
-6. Write all files
-
-### Output: Feature Mode
-
-**`feature-specs/F-{id}-{slug}.md`** per feature (7 sections, 1500-2500 words):
-
-1. **Requirements Summary** — RFC 2119 keywords, derived from guidance-specification
-2. **Design Decisions** [CORE — 40%+ of word count] — Aggregated from role analyses, conflicts resolved
-3. **Interface Contract** — APIs, data formats, integration points
-4. **Constraints & Risks** — Technical limits, known risks, mitigation
-5. **Acceptance Criteria** — Testable conditions for feature completion
-6. **Detailed Analysis References** — @-links to role analysis files (e.g., @system-architect/analysis-F-001-auth.md)
-7. **Cross-Feature Dependencies** — What this feature needs from / provides to other features
-
-**`feature-index.json`**:
-```json
-{
-  "features": [
-    { "id": "F-001", "slug": "auth", "title": "Authentication", "spec_path": "feature-specs/F-001-auth.md", "status": "complete", "dependencies": ["F-003"] }
-  ],
-  "enhancements_applied": ["EP-001", "EP-003"],
-  "complexity_score": 5
-}
-```
-
-**`synthesis-changelog.md`** — Audit trail: enhancements applied, clarifications resolved, conflicts resolved
-
-### Output: Fallback Mode (no feature list)
-
-**`synthesis-specification.md`** — Single consolidated specification document
-**`synthesis-changelog.md`** — Same audit trail
-
-### Complexity Score (0-8)
-
-| Factor | Score |
-|--------|-------|
-| Features > 5 | +1 |
-| Unresolved conflicts > 2 | +2 |
-| Participating roles > 4 | +1 |
-| Cross-feature dependencies > 3 | +1 |
-| Enhancement count > 4 | +1 |
-| Clarification rounds > 2 | +1 |
-| system-architect involved | +1 |
-
-If complexity_score >= 4: report `[REVIEW_RECOMMENDED]` in output for orchestrator to trigger review agent.
-
-## Return Protocol
-
-- **TASK COMPLETE**: All output files written. Include: file list, word counts, complexity_score (Mode 3 only).
-- **TASK BLOCKED**: Cannot proceed (missing role template, empty guidance-specification, no analysis files). Include: blocker description.
-
-## Rules
-
-### ALWAYS
-- Follow role template "Brainstorming Analysis Structure" strictly
-- Use RFC 2119 keywords for all behavioral requirements
-- Respect word count limits per output file
-- Feature-point organization: analysis.md is INDEX only, not full analysis
-- Reference guidance-specification.md decisions, do not contradict them
-- Include design research findings when provided
-- Apply Four-Layer Aggregation for spec generation
-- Track conflict resolution quality: actionable + justified + scoped
-
-### NEVER
-- Write files outside the output directory specified in the prompt (source code, project config, etc. are read-only context)
-- Overlap with other roles' focus areas in role analysis mode
-- Write files in cross-role analysis mode (return text only)
-- Exceed word count limits (hard cap)
-- Use interrogative sentences in specifications (all statements must be declarative)
-- Omit [DECISION NEEDED] markers for unresolved conflicts