feat: implement feature-driven artifact architecture for brainstorm-plan-execute pipeline

Restructure brainstorm artifacts from role-dimension to feature-dimension to eliminate information loss at the brainstorm→plan boundary. Key changes: - artifacts.md: Add Phase 4.5 Feature Decomposition in guidance-specification - conceptual-planning-agent.md: Name sub-docs by feature (analysis-F-{id}-{slug}.md) - role-analysis.md: Pass feature list to Phase 3 agent prompts - synthesis.md: Add Phase 6 parallel feature spec generation + feature-index.json - task-generate-agent.md: Inject feature-index.json path into agent prompts - context-search-agent.md: Flatten brainstorm_artifacts structure (feature_index, feature_specs, cross_cutting_specs as top-level fields) - action-planning-agent.md: Add feature-index driven on-demand loading, plan-time expansion for pre_analysis commands, fix cross_cutting_specs string array access
2026-02-13 02:41:50 +08:00 · 2026-02-11 16:32:30 +08:00
parent 8475a724ae
commit 5a4350beb4
7 changed files with 891 additions and 74 deletions
--- a/.claude/commands/workflow/brainstorm/synthesis.md
+++ b/.claude/commands/workflow/brainstorm/synthesis.md
@@ -11,19 +11,22 @@ When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions

 ## Overview

-Six-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
+Eight-phase workflow to eliminate ambiguities, enhance conceptual depth, and generate per-feature specifications:

 **Phase 1-2**: Session detection → File discovery → Path preparation
-**Phase 3A**: Cross-role analysis agent → Generate recommendations
+**Phase 3A**: Cross-role analysis agent → Generate recommendations + feature_conflict_map
 **Phase 4**: User selects enhancements → User answers clarifications (via AskUserQuestion)
 **Phase 5**: Parallel update agents (one per role)
-**Phase 6**: Context package update → Metadata update → Completion report
+**Phase 6**: Parallel feature spec generation (one agent per feature) [feature_mode only]
+**Phase 6.5**: Feature index generation (feature-index.json) [feature_mode only]
+**Phase 7**: Context package update → Metadata update → Completion report

 All user interactions use AskUserQuestion tool (max 4 questions per call, multi-round).

 **Document Flow**:
- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata
+- Input: `[role]/analysis.md` (index files), `guidance-specification.md`, session metadata
 - Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
+- Output (feature_mode): `feature-specs/F-{id}-{slug}.md` per feature + `feature-index.json`

 ---

@@ -35,10 +38,12 @@ All user interactions use AskUserQuestion tool (max 4 questions per call, multi-
 |-------|------|----------|--------|
 | 1 | Session detection | Main flow | session_id, brainstorm_dir |
 | 2 | File discovery | Main flow | role_analysis_paths |
-| 3A | Cross-role analysis | Agent | enhancement_recommendations |
+| 3A | Cross-role analysis | Agent | enhancement_recommendations, feature_conflict_map |
 | 4 | User interaction | Main flow + AskUserQuestion | update_plan |
 | 5 | Document updates | Parallel agents | Updated analysis*.md |
-| 6 | Finalization | Main flow | context-package.json, report |
+| 6 | Feature spec generation | Parallel agents | feature-specs/F-{id}-{slug}.md [feature_mode] |
+| 6.5 | Feature index generation | Main flow | feature-index.json [feature_mode] |
+| 7 | Finalization | Main flow | context-package.json, report |

 ### AskUserQuestion Pattern

@@ -81,10 +86,12 @@ AskUserQuestion({
 [
  {"content": "Detect session and validate analyses", "status": "pending", "activeForm": "Detecting session"},
  {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"},
-  {"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis"},
+  {"content": "Execute analysis agent (cross-role analysis + feature conflict map)", "status": "pending", "activeForm": "Executing analysis"},
  {"content": "Present enhancements via AskUserQuestion", "status": "pending", "activeForm": "Selecting enhancements"},
  {"content": "Clarification questions via AskUserQuestion", "status": "pending", "activeForm": "Clarifying"},
  {"content": "Execute parallel update agents", "status": "pending", "activeForm": "Updating documents"},
+  {"content": "Generate parallel feature specs (feature_mode only)", "status": "pending", "activeForm": "Generating feature specs"},
+  {"content": "Generate feature-index.json (feature_mode only)", "status": "pending", "activeForm": "Building feature index"},
  {"content": "Update context package and metadata", "status": "pending", "activeForm": "Finalizing"}
 ]
 ```
@@ -100,6 +107,22 @@ AskUserQuestion({
   - `guidance-specification.md` (optional, warn if missing)
   - `*/analysis*.md` (required, error if empty)
 3. **Load User Intent**: Extract from `workflow-session.json`
+4. **Detect Feature Mode**: Check if role analyses use feature-point organization
+   ```javascript
+   // Feature mode is active when:
+   // 1. guidance-specification.md contains Feature Decomposition table
+   // 2. Role directories contain analysis-F-{id}-*.md files
+   const has_feature_decomposition = guidanceSpecContent &&
+     guidanceSpecContent.includes('Feature Decomposition');
+   const has_feature_subdocs = Glob(`${brainstorm_dir}/*/analysis-F-*-*.md`).length > 0;
+   const feature_mode = has_feature_decomposition && has_feature_subdocs;
+
+   // Extract feature_list from guidance-spec if feature_mode
+   if (feature_mode) {
+     feature_list = extractFeatureDecompositionTable(guidanceSpecContent);
+     // feature_list: [{id, slug, description, roles, priority}, ...]
+   }
+   ```

 ### Phase 2: Role Discovery & Path Preparation

@@ -119,23 +142,41 @@ AskUserQuestion({

 **Agent executes cross-role analysis**:

+**Input Optimization (feature_mode)**: When feature_mode is active, only read `{role}/analysis.md` index files (NOT sub-documents like `analysis-F-{id}-*.md` or `analysis-cross-cutting.md`). This reduces input tokens from ~39K to ~4.5K while preserving the role perspective overview, feature point index, and cross-cutting summary needed for conflict detection.
+
+**Input (fallback mode)**: When feature_mode is NOT active, read all `{role}/analysis*.md` files as before.
+
 ```javascript
+// Prepare input paths based on mode
+const analysis_input_paths = feature_mode
+  ? participating_roles.map(r => `${brainstorm_dir}/${r}/analysis.md`)  // Index files only (~4.5K total)
+  : role_analysis_paths;  // All analysis files (fallback)
+
 Task(conceptual-planning-agent, `
 ## Agent Mission
-Analyze role documents, identify conflicts/gaps, generate enhancement recommendations
+Analyze role documents, identify conflicts/gaps, generate enhancement recommendations.
+${feature_mode ? 'Additionally, generate feature_conflict_map for per-feature consensus/conflicts across roles.' : ''}

 ## Input
 - brainstorm_dir: ${brainstorm_dir}
- role_analysis_paths: ${role_analysis_paths}
+- analysis_input_paths: ${analysis_input_paths}
 - participating_roles: ${participating_roles}
+- feature_mode: ${feature_mode}
+${feature_mode ? `- guidance_spec_path: ${brainstorm_dir}/guidance-specification.md (read Feature Decomposition section only)` : ''}

 ## Flow Control Steps
 1. load_session_metadata → Read workflow-session.json
-2. load_role_analyses → Read all analysis files
-3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities
-4. generate_recommendations → Format as EP-001, EP-002, ...
+2. load_role_analyses → Read analysis files from analysis_input_paths
+   ${feature_mode ? '(INDEX files only - each ~500-800 words with role overview, feature index table, cross-cutting summary)' : '(All analysis files)'}
+${feature_mode ? `3. load_feature_decomposition → Read Feature Decomposition table from guidance-specification.md
+4. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities
+5. generate_feature_conflict_map → For each feature in Feature Decomposition, extract per-feature consensus/conflicts/cross-references from role index summaries
+6. generate_recommendations → Format as EP-001, EP-002, ...` : `3. cross_role_analysis → Identify consensus, conflicts, gaps, ambiguities
+4. generate_recommendations → Format as EP-001, EP-002, ...`}

 ## Output Format
+
+### enhancement_recommendations (always)
 [
  {
    "id": "EP-001",
@@ -148,9 +189,79 @@ Analyze role documents, identify conflicts/gaps, generate enhancement recommenda
    "priority": "High"
  }
 ]
+
+${feature_mode ? `### feature_conflict_map (feature_mode only)
+Bridge artifact from Phase 3A to Phase 6. One entry per feature from Feature Decomposition.
+
+{
+  "F-001": {
+    "consensus": [
+      "All roles agree on real-time sync via WebSocket",
+      "Event-driven architecture preferred"
+    ],
+    "conflicts": [
+      {
+        "topic": "State management approach",
+        "views": {
+          "system-architect": "Server-authoritative with CRDT",
+          "ux-expert": "Optimistic local-first updates",
+          "data-architect": "Event-sourced append-only log"
+        },
+        "resolution": "Hybrid: optimistic local with server reconciliation via CRDT"
+      }
+    ],
+    "cross_refs": [
+      "F-003 (offline-mode) depends on sync conflict resolution strategy",
+      "analysis-cross-cutting.md#shared-patterns references this feature"
+    ]
+  },
+  "F-002": { ... }
+}
+
+**feature_conflict_map Rules**:
+- One entry per feature ID from guidance-specification.md Feature Decomposition
+- consensus[]: Statements where 2+ roles explicitly agree (extracted from index summaries)
+- conflicts[]: Disagreements with topic, per-role positions, and suggested resolution
+- cross_refs[]: References to other features or cross-cutting docs that relate to this feature
+- If a feature has no conflicts, set conflicts to empty array (consensus-only is valid)
+- Keep each entry concise: aim for 100-200 words per feature
+
+**Resolution Quality Requirements** (每条 conflict 的 resolution 必须满足):
+1. **Actionable**: resolution 必须是可直接执行的技术方案，而非模糊描述。Bad: "需要权衡" → Good: "采用 JWT 无状态认证，RefreshToken 存 HttpOnly Cookie"
+2. **Justified**: 说明为什么选择该方案而非其他。格式: "[方案] because [原因]，tradeoff: [代价]"
+3. **Scoped**: 明确 resolution 的适用范围。如果仅适用于特定场景，标注 "Applies when: [条件]"
+4. **Resolution Confidence**: 每条 conflict 标注置信度
+   - `[RESOLVED]`: Phase 3A 从角色分析中找到明确共识或用户已决策 → Phase 6 直接采用
+   - `[SUGGESTED]`: Phase 3A 基于角色分析推荐方案，但未被用户显式确认 → Phase 6 采用但标注来源
+   - `[UNRESOLVED]`: 角色之间存在根本分歧且无法从现有信息推导 → Phase 6 标注 [DECISION NEEDED]，列出所有选项供 plan 阶段决策
+
+**conflict entry 增强 schema**:
+```json
+{
+  "topic": "State management approach",
+  "views": {
+    "system-architect": "Server-authoritative with CRDT",
+    "ux-expert": "Optimistic local-first updates"
+  },
+  "resolution": "Hybrid: optimistic local with server reconciliation via CRDT because balances UX responsiveness with data consistency, tradeoff: increased client complexity",
+  "confidence": "[RESOLVED]",
+  "applies_when": "Online mode with collaborative editing"
+}
+```
+` : ''}
 `)
 ```

+**Phase 3A Output Storage**:
+```javascript
+// Store enhancement_recommendations for Phase 4
+const enhancement_recommendations = agent_output.enhancement_recommendations;
+
+// Store feature_conflict_map for Phase 6 (feature_mode only)
+const feature_conflict_map = feature_mode ? agent_output.feature_conflict_map : null;
+```
+```
+
 ### Phase 4: User Interaction

 **All interactions via AskUserQuestion (Chinese questions)**
@@ -300,7 +411,288 @@ Updated ${role}/analysis.md
 - **Dependencies**: Zero cross-agent dependencies
 - **Validation**: All updates must align with original_user_intent

-### Phase 6: Finalization
+### Phase 6: Parallel Feature Spec Generation [feature_mode only]
+
+**Skip condition**: If `feature_mode` is false (no feature list in guidance-spec, or role analyses were not organized by feature points), skip Phase 6 and Phase 6.5 entirely. Proceed directly to Phase 7.
+
+**Purpose**: Generate one consolidated feature specification per feature by aggregating all role perspectives. Each agent reads the detailed per-feature sub-documents from all roles, applies the conflict map from Phase 3A, and produces a unified spec.
+
+#### Step 1: Prepare Feature Spec Directory
+
+```javascript
+// Create feature-specs directory
+const feature_specs_dir = `${brainstorm_dir}/feature-specs`;
+// Ensure directory exists (create if not)
+```
+
+#### Step 2: Build Per-Feature Input Bundles
+
+```javascript
+// For each feature in feature_list (from guidance-spec Feature Decomposition)
+const feature_bundles = feature_list.map(feature => {
+  const fid = feature.id;     // e.g., "F-001"
+  const slug = feature.slug;  // e.g., "real-time-sync"
+
+  // Collect per-feature analysis files from all roles
+  const role_analysis_files = participating_roles
+    .map(role => `${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`)
+    .filter(path => fileExists(path));  // Only existing files
+
+  return {
+    feature_id: fid,
+    feature_slug: slug,
+    feature_name: feature.description,
+    feature_priority: feature.priority,
+    conflict_map_entry: feature_conflict_map[fid],  // From Phase 3A
+    role_analysis_files: role_analysis_files,
+    contributing_roles: role_analysis_files.map(f => extractRoleName(f)),
+    output_path: `${feature_specs_dir}/${fid}-${slug}.md`
+  };
+});
+```
+
+#### Step 3: Execute Parallel Feature Spec Agents
+
+**Execute in parallel** (one agent per feature, mirrors Phase 5 pattern):
+
+```javascript
+// Single message with multiple Task calls for parallelism
+// Each agent generates ONE feature spec document
+
+// For each feature bundle:
+Task(conceptual-planning-agent, `
+## Agent Mission
+Generate consolidated feature specification for ${feature.feature_id}: ${feature.feature_name}
+by aggregating all role-specific analyses with conflict resolution.
+
+## Input
+- feature_id: ${feature.feature_id}
+- feature_slug: ${feature.feature_slug}
+- feature_name: ${feature.feature_name}
+- feature_priority: ${feature.feature_priority}
+- role_analysis_files: ${feature.role_analysis_files}
+- conflict_map_entry: ${JSON.stringify(feature.conflict_map_entry)}
+- output_path: ${feature.output_path}
+- guidance_spec_feature_section: (Feature Decomposition row for this feature from guidance-specification.md)
+
+## Flow Control Steps
+1. load_role_analyses → Read all role-specific analysis files for this feature
+   (Each file ~1500-2000 words, total ~6.5K words for 3-4 roles)
+2. apply_conflict_map → Use conflict_map_entry to identify resolved/unresolved conflicts
+3. four_layer_aggregation → Apply aggregation rules (see below)
+4. generate_feature_spec → Write consolidated spec using template (see below)
+5. write_output → Save to output_path
+
+## Four-Layer Aggregation Rules
+
+### Layer 1: Direct Reference
+- Quote role analyses directly when consensus exists (from conflict_map.consensus)
+- Format: "[Role] recommends: [direct quote]"
+- Use for undisputed technical recommendations
+
+### Layer 2: Structured Extraction
+- Extract and organize key information from each role into unified structure
+- Merge complementary perspectives (e.g., UX user flows + architect data flows)
+- De-duplicate overlapping content across roles
+
+### Layer 3: Conflict Distillation
+- For each conflict in conflict_map_entry.conflicts, handle by confidence level:
+  - **[RESOLVED]**: State the resolution directly as a design decision. Format: "**Decision**: [resolution]. **Rationale**: [from conflict.resolution]. **Trade-off**: [tradeoff]."
+  - **[SUGGESTED]**: Adopt the suggested resolution but mark source. Format: "**Recommended**: [resolution] (suggested by Phase 3A cross-role analysis). **Rationale**: [reason]. **Alternative**: [strongest competing view]."
+  - **[UNRESOLVED]**: Do NOT pick a side. Present all options neutrally for downstream decision. Format: "**[DECISION NEEDED]**: [topic]. **Options**: [role1: approach1] vs [role2: approach2]. **Evaluation**: [pros/cons of each]. **Impact if deferred**: [consequence of not deciding]."
+- For each conflict regardless of confidence:
+  - Present all role positions concisely (who said what)
+  - Document trade-offs of the chosen or suggested approach
+  - If `applies_when` is set, note the scope limitation
+- **Unresolved conflict escalation**: If a feature has 2+ [UNRESOLVED] conflicts, add a prominent warning at the top of Section 2: "⚠ This feature has N unresolved design decisions. Plan stage must resolve before task generation."
+
+### Layer 4: Cross-Feature Annotation
+- For each cross_ref in conflict_map_entry.cross_refs:
+  - Add explicit dependency notes with feature IDs
+  - Document integration points with other features
+  - Note shared constraints or patterns
+
+## Feature Spec Template (7 Sections, target 1500-2500 words)
+
+The output MUST follow this template:
+
+---
+# Feature Spec: ${feature.feature_id} - ${feature.feature_name}
+
+**Priority**: ${feature.feature_priority}
+**Contributing Roles**: [list of roles that analyzed this feature]
+**Status**: Draft (from synthesis)
+
+## 1. Requirements Summary
+[Consolidated requirements from all role perspectives]
+- Functional requirements (from product-manager, product-owner)
+- User experience requirements (from ux-expert, ui-designer)
+- Technical requirements (from system-architect, data-architect, api-designer)
+- Domain requirements (from subject-matter-expert)
+
+## 2. Design Decisions [CORE SECTION]
+[Key architectural and design decisions with rationale]
+For each decision:
+- **Decision**: [What was decided]
+- **Context**: [Why this decision was needed]
+- **Options Considered**: [Alternatives from different roles]
+- **Chosen Approach**: [Selected option with rationale]
+- **Trade-offs**: [What we gain vs. what we sacrifice]
+- **Source**: [Which role(s) drove this decision]
+
+## 3. Interface Contract
+[API endpoints, data models, component interfaces]
+- External interfaces (API contracts from api-designer)
+- Internal interfaces (component boundaries from system-architect)
+- Data interfaces (schemas from data-architect)
+- User interfaces (interaction patterns from ux-expert/ui-designer)
+
+## 4. Constraints & Risks
+[Technical constraints, business risks, mitigation strategies]
+- Performance constraints (from system-architect)
+- Data constraints (from data-architect)
+- UX constraints (from ux-expert)
+- Business/domain constraints (from subject-matter-expert)
+- Risk mitigation strategies (from scrum-master)
+
+## 5. Acceptance Criteria
+[Testable criteria for feature completion]
+- Functional acceptance (from product-owner user stories)
+- Performance acceptance (from system-architect NFRs)
+- UX acceptance (from ux-expert usability criteria)
+- Data integrity acceptance (from data-architect)
+
+## 6. Detailed Analysis References
+[Pointers back to role-specific analysis documents]
+- @../{role}/analysis-${feature.feature_id}-${feature.feature_slug}.md for each contributing role
+- @../guidance-specification.md#feature-decomposition
+
+## 7. Cross-Feature Dependencies
+[Dependencies on and from other features]
+- **Depends on**: [Feature IDs this feature requires]
+- **Required by**: [Feature IDs that depend on this feature]
+- **Shared patterns**: References to analysis-cross-cutting.md patterns
+- **Integration points**: [Specific interfaces between features]
+---
+
+## Completion Criteria
+- All 7 sections populated with aggregated content
+- Section 2 (Design Decisions) is the most detailed section (40%+ of word count)
+- All conflicts from conflict_map_entry addressed with resolutions
+- Cross-feature dependencies explicitly documented
+- Word count between 1500-2500
+- No placeholder text (TODO/TBD) except [DECISION NEEDED] for genuinely unresolved items
+`)
+```
+
+**Agent Characteristics (Phase 6)**:
+- **Isolation**: Each agent processes exactly ONE feature (parallel safe)
+- **Dependencies**: Requires Phase 3A feature_conflict_map and Phase 5 updated role analyses
+- **Input budget**: ~6.5K words per agent (3-4 role sub-docs + conflict map entry)
+- **Output budget**: 1500-2500 words per feature spec
+
+### Phase 6.5: Feature Index Generation [feature_mode only]
+
+**Skip condition**: Same as Phase 6 - skip if `feature_mode` is false.
+
+**Purpose**: Collect all Phase 6 outputs and generate a structured `feature-index.json` for downstream consumption by action-planning-agent and code-developer.
+
+#### Step 1: Collect Feature Spec Outputs
+
+```javascript
+// Read all generated feature spec files
+const feature_spec_files = Glob(`${brainstorm_dir}/feature-specs/F-*-*.md`);
+
+// Also collect cross-cutting spec paths
+const cross_cutting_specs = participating_roles
+  .map(role => `${brainstorm_dir}/${role}/analysis-cross-cutting.md`)
+  .filter(path => fileExists(path));
+```
+
+#### Step 2: Generate feature-index.json
+
+```javascript
+const feature_index = {
+  "version": "1.0",
+  "generated_at": new Date().toISOString(),
+  "session_id": session_id,
+  "feature_mode": true,
+  "features": feature_list.map(feature => {
+    const fid = feature.id;
+    const slug = feature.slug;
+    const spec_path = `feature-specs/${fid}-${slug}.md`;
+    const spec_exists = fileExists(`${brainstorm_dir}/${spec_path}`);
+
+    // Extract contributing roles from the spec file header
+    const contributing_roles = participating_roles.filter(role =>
+      fileExists(`${brainstorm_dir}/${role}/analysis-${fid}-${slug}.md`)
+    );
+
+    // Extract cross-cutting references from conflict_map
+    const cross_cutting_refs = feature_conflict_map[fid]
+      ? feature_conflict_map[fid].cross_refs
+      : [];
+
+    return {
+      "id": fid,
+      "slug": slug,
+      "name": feature.description,
+      "priority": feature.priority,
+      "spec_path": spec_exists ? spec_path : null,
+      "contributing_roles": contributing_roles,
+      "cross_cutting_refs": cross_cutting_refs
+    };
+  }),
+  "cross_cutting_specs": cross_cutting_specs.map(path =>
+    path.replace(brainstorm_dir + '/', '')  // Relative path
+  )
+};
+
+Write(
+  `${brainstorm_dir}/feature-index.json`,
+  JSON.stringify(feature_index, null, 2)
+);
+```
+
+#### feature-index.json Schema
+
+```json
+{
+  "version": "1.0",
+  "generated_at": "2026-02-11T10:00:00.000Z",
+  "session_id": "WFS-xxx",
+  "feature_mode": true,
+  "features": [
+    {
+      "id": "F-001",
+      "slug": "real-time-sync",
+      "name": "Real-time collaborative synchronization",
+      "priority": "High",
+      "spec_path": "feature-specs/F-001-real-time-sync.md",
+      "contributing_roles": ["system-architect", "ux-expert", "data-architect"],
+      "cross_cutting_refs": ["F-003 offline-mode depends on sync strategy"]
+    },
+    {
+      "id": "F-002",
+      "slug": "user-permissions",
+      "name": "Role-based user permissions and access control",
+      "priority": "High",
+      "spec_path": "feature-specs/F-002-user-permissions.md",
+      "contributing_roles": ["system-architect", "product-manager", "subject-matter-expert"],
+      "cross_cutting_refs": []
+    }
+  ],
+  "cross_cutting_specs": [
+    "system-architect/analysis-cross-cutting.md",
+    "ux-expert/analysis-cross-cutting.md",
+    "data-architect/analysis-cross-cutting.md"
+  ]
+}
+```
+
+**Consumers**: `action-planning-agent` reads feature-index.json to generate task JSONs with feature_spec references. `code-developer` loads individual feature specs (3-5K words) as implementation context.
+
+### Phase 7: Finalization

 #### Step 1: Update Context Package

@@ -313,6 +705,13 @@ const context_pkg = Read(".workflow/active/WFS-{session}/.process/context-packag
 // Re-read all role analysis files
 // Update metadata timestamps

+// If feature_mode: add feature-index.json and feature-specs paths
+if (feature_mode) {
+  context_pkg.feature_index_path = `${brainstorm_dir}/feature-index.json`;
+  context_pkg.feature_specs_dir = `${brainstorm_dir}/feature-specs/`;
+  context_pkg.feature_mode = true;
+}
+
 Write(context_pkg_path, JSON.stringify(context_pkg))
 ```

@@ -332,6 +731,13 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
        "categories_clarified": ["Architecture", "UX"],
        "roles_updated": ["role1", "role2"]
      },
+      "feature_spec_results": {
+        "feature_mode": true,
+        "features_generated": ["F-001", "F-002", "F-003"],
+        "feature_index_path": ".brainstorming/feature-index.json",
+        "feature_specs_dir": ".brainstorming/feature-specs/",
+        "conflict_map_generated": true
+      },
      "quality_metrics": {
        "user_intent_alignment": "validated",
        "ambiguity_resolution": "complete",
@@ -342,26 +748,53 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
 }
 ```

+**Note**: `feature_spec_results` is only present when `feature_mode` is true. When `feature_mode` is false, this key is omitted entirely.
+
 #### Step 3: Completion Report

 ```markdown
-## ✅ Clarification Complete
+## Clarification Complete

 **Enhancements Applied**: EP-001, EP-002, EP-003
 **Questions Answered**: 3/5
 **Roles Updated**: role1, role2, role3

+### Feature Specs (feature_mode only)
+**Feature Specs Generated**: F-001, F-002, F-003
+**Feature Index**: .brainstorming/feature-index.json
+**Spec Directory**: .brainstorming/feature-specs/
+
 ### Next Steps
-✅ PROCEED: `/workflow:plan --session WFS-{session-id}`
+PROCEED: `/workflow:plan --session WFS-{session-id}`
 ```

 ---

 ## Output

-**Location**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
+**Location (role analyses)**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md`
+**Location (feature specs)**: `.workflow/active/WFS-{session}/.brainstorming/feature-specs/F-{id}-{slug}.md` [feature_mode]
+**Location (feature index)**: `.workflow/active/WFS-{session}/.brainstorming/feature-index.json` [feature_mode]

-**Updated Structure**:
+**Updated Directory Structure** (feature_mode):
+```
+.workflow/active/WFS-{session}/.brainstorming/
+├── guidance-specification.md
+├── feature-index.json                    # Phase 6.5 output
+├── feature-specs/                        # Phase 6 output directory
+│   ├── F-001-{slug}.md                   # Consolidated feature spec (1500-2500 words)
+│   ├── F-002-{slug}.md
+│   └── F-00N-{slug}.md
+├── {role-1}/
+│   ├── analysis.md                       # Role overview index (read by Phase 3A)
+│   ├── analysis-cross-cutting.md
+│   ├── analysis-F-001-{slug}.md          # Per-feature detail (read by Phase 6)
+│   └── analysis-F-002-{slug}.md
+└── {role-N}/
+    └── ...
+```
+
+**Updated Role Analysis Structure**:
 ```markdown
 ## Clarifications
 ### Session {date}
@@ -378,25 +811,37 @@ Write(context_pkg_path, JSON.stringify(context_pkg))
 - Architecture with rationale
 - Ambiguities resolved, placeholders removed
 - Consistent terminology
+- Feature specs generated with cross-role conflict resolution [feature_mode]
+- Feature index provides structured access for downstream consumers [feature_mode]

 ---

 ## Quality Checklist

 **Content**:
- ✅ All role analyses loaded/analyzed
- ✅ Cross-role analysis (consensus, conflicts, gaps)
- ✅ 9-category ambiguity scan
- ✅ Questions prioritized
+- All role analyses loaded/analyzed
+- Cross-role analysis (consensus, conflicts, gaps)
+- 9-category ambiguity scan
+- Questions prioritized

 **Analysis**:
- ✅ User intent validated
- ✅ Cross-role synthesis complete
- ✅ Ambiguities resolved
- ✅ Terminology consistent
+- User intent validated
+- Cross-role synthesis complete
+- Ambiguities resolved
+- Terminology consistent

 **Documents**:
- ✅ Clarifications section formatted
- ✅ Sections reflect answers
- ✅ No placeholders (TODO/TBD)
- ✅ Valid Markdown
+- Clarifications section formatted
+- Sections reflect answers
+- No placeholders (TODO/TBD)
+- Valid Markdown
+
+**Feature Specs (feature_mode only)**:
+- Phase 3A reads only analysis.md index files (not sub-documents), input token <= 5K words
+- feature_conflict_map generated with consensus/conflicts/cross_refs per feature
+- Phase 6 parallel agents defined: one per feature, input token <= 7K words each
+- Feature spec template has 7 sections, Section 2 (Design Decisions) is core
+- Four-layer aggregation rules applied (direct reference/structured extraction/conflict distillation/cross-feature annotation)
+- Each feature spec is 1500-2500 words
+- feature-index.json generated with features[] + cross_cutting_specs[]
+- feature-specs/ directory created with F-{id}-{slug}.md files