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-03-30 20:21:09 +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/agents/action-planning-agent.md
+++ b/.claude/agents/action-planning-agent.md
@@ -82,9 +82,17 @@ color: yellow
 4. Load brainstorming artifacts (in priority order)
   a. guidance-specification.md (Highest Priority)
      → Overall design framework and architectural decisions
-   b. Role analyses (progressive loading: load incrementally by priority)
+   b. Feature specs (on-demand via feature-index.json)
+      → If .brainstorming/feature-specs/feature-index.json exists:
+        1. Load feature-index.json → get feature catalog (id, slug, priority, spec_path)
+        2. Load only feature-specs referenced by current task (1-2 per task)
+        3. Load cross-cutting specs only when task touches shared concerns
+      → Reason: On-demand loading reduces per-task context from 40K+ to 3-5K words
+      → Backward compatibility: If feature-index.json does NOT exist →
+        Fall back to role analyses (progressive loading by priority, see 4b-fallback)
+   b-fallback. Role analyses (legacy, only when feature-index.json absent)
      → Load role analysis files one at a time as needed
-      → Reason: Each analysis.md is long; progressive loading prevents token overflow
+      → Progressive loading prevents token overflow
   c. Synthesis output (if exists)
      → Integrated view with clarifications
   d. Conflict resolution (if conflict_risk ≥ medium)
@@ -140,8 +148,21 @@ mcp__exa__get_code_context_exa(
 - `brainstorm_artifacts.guidance_specification`: Overall design framework (if exists)
  - Check: `brainstorm_artifacts?.guidance_specification?.exists === true`
  - Content: Use `content` field if present, else load from `path`
- `brainstorm_artifacts.role_analyses[]`: Role-specific analyses (if array not empty)
+- `brainstorm_artifacts.feature_index`: Feature catalog index (if feature-mode brainstorming)
+  - Check: `brainstorm_artifacts?.feature_index?.exists === true`
+  - Content: JSON with `{features[], cross_cutting_specs[]}` - load from `path`
+  - **When present**: Use feature-index as primary entry point for on-demand spec loading
+- `brainstorm_artifacts.feature_specs[]`: Individual feature specification files (from context-package)
+  - Each spec: `feature_specs[i]` has `path` and `content`
+  - **Load on-demand**: Only load specs referenced by current task's feature mapping
+  - **Note**: For structured metadata (`feature_id`, `slug`, `priority`), use `feature_index.features[]` instead
+- `brainstorm_artifacts.cross_cutting_specs[]`: Cross-cutting concern specifications (from context-package)
+  - Each spec: `cross_cutting_specs[i]` has `path` and `content`
+  - **Load on-demand**: Only load when task touches shared/cross-cutting concerns
+  - **Note**: In feature-index.json, `cross_cutting_specs[]` is a plain string array (relative paths)
+- `brainstorm_artifacts.role_analyses[]`: Role-specific analyses (legacy fallback, if array not empty)
  - Each role: `role_analyses[i].files[j]` has `path` and `content`
+  - **Only used when**: `feature_index` does not exist (backward compatibility)
 - `brainstorm_artifacts.synthesis_output`: Synthesis results (if exists)
  - Check: `brainstorm_artifacts?.synthesis_output?.exists === true`
  - Content: Use `content` field if present, else load from `path`
@@ -160,8 +181,31 @@ if (contextPackage.brainstorm_artifacts?.guidance_specification?.exists) {
  const content = spec.content || Read(spec.path);
 }

-if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
-  // Progressive loading: load role analyses incrementally by priority
+// Feature-index driven loading (PREFERRED - on-demand)
+if (contextPackage.brainstorm_artifacts?.feature_index?.exists) {
+  // Step 1: Load feature-index.json for catalog
+  const featureIndex = JSON.parse(Read(contextPackage.brainstorm_artifacts.feature_index.path));
+
+  // Step 2: Load only task-relevant feature specs (1-2 per task)
+  const taskFeatureIds = task.context.artifacts
+    .filter(a => a.type === 'feature_spec')
+    .map(a => a.feature_id);
+  featureIndex.features
+    .filter(f => taskFeatureIds.includes(f.id))
+    .forEach(f => {
+      const specContent = Read(f.spec_path); // On-demand: only what this task needs
+    });
+
+  // Step 3: Load cross-cutting specs only when needed
+  // Note: cross_cutting_specs in feature-index.json is a string array (relative paths)
+  featureIndex.cross_cutting_specs
+    .filter(cs => task.context.artifacts.some(a => a.type === 'cross_cutting_spec' && a.path === cs))
+    .forEach(cs => {
+      const crossCuttingContent = Read(cs);
+    });
+
+} else if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
+  // FALLBACK: Legacy role analysis progressive loading (when feature-index absent)
  contextPackage.brainstorm_artifacts.role_analyses.forEach(role => {
    role.files.forEach(file => {
      const analysis = file.content || Read(file.path); // Load one at a time
@@ -376,12 +420,13 @@ userConfig.executionMethod → meta.execution_config
    },
    "artifacts": [
      {
-        "type": "synthesis_specification|topic_framework|individual_role_analysis",
-        "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
-        "path": "{from artifacts_inventory}",
+        "type": "feature_spec|cross_cutting_spec|synthesis_specification|topic_framework|individual_role_analysis",
+        "source": "brainstorm_feature_specs|brainstorm_cross_cutting|brainstorm_clarification|brainstorm_framework|brainstorm_roles",
+        "path": "{from feature-index.json or artifacts_inventory}",
+        "feature_id": "F-NNN (feature_spec only)",
        "priority": "highest|high|medium|low",
-        "usage": "Architecture decisions and API specifications",
-        "contains": "role_specific_requirements_and_design"
+        "usage": "Feature requirements and design specifications",
+        "contains": "feature_specific_requirements_and_design"
      }
    ]
  }
@@ -398,12 +443,27 @@ userConfig.executionMethod → meta.execution_config
 - `artifacts`: Referenced brainstorming outputs with detailed metadata

 **Artifact Mapping** (from context package):
- Use `artifacts_inventory` from context package
- **Priority levels**:
-  - **Highest**: synthesis_specification (integrated view with clarifications)
-  - **High**: topic_framework (guidance-specification.md)
-  - **Medium**: individual_role_analysis (system-architect, subject-matter-expert, etc.)
-  - **Low**: supporting documentation
+- **Feature-index mode** (when `feature_index` exists): Use feature-index.json as primary catalog
+- **Legacy mode** (fallback): Use `artifacts_inventory` from context package
+
+- **Artifact Types & Priority**:
+  - **`feature_spec`** (Highest): Feature specification from feature-index.json
+    - `{type: "feature_spec", source: "brainstorm_feature_specs", path: "<spec_path>", feature_id: "<F-NNN>", priority: "highest", usage: "<task-specific usage>", contains: "<feature scope description>"}`
+    - Each task references 1-2 feature specs based on task scope
+  - **`cross_cutting_spec`** (High): Cross-cutting concern specification
+    - `{type: "cross_cutting_spec", source: "brainstorm_cross_cutting", path: "<spec_path>", priority: "high", usage: "<why this task needs it>", contains: "<cross-cutting scope>"}`
+    - Load only when task touches shared concerns (auth, logging, error handling, etc.)
+  - **`synthesis_specification`** (High): Integrated view with clarifications
+  - **`topic_framework`** (High): guidance-specification.md
+  - **`individual_role_analysis`** (Medium): Legacy role analyses (system-architect, etc.)
+  - **Low**: Supporting documentation
+
+- **Task-Feature Mapping Rules** (feature-index mode):
+  1. Read feature-index.json `features[]` array
+  2. For each task, identify 1-2 primary features by matching task scope to feature `name`/`slug`
+  3. Add matching feature specs as `feature_spec` artifacts with `feature_id` field
+  4. Check `cross_cutting_refs` in matched features; add referenced cross-cutting specs as `cross_cutting_spec` artifacts
+  5. Result: Each task's `context.artifacts[]` contains only the specs it needs (not all specs)

 #### Flow Control Object

@@ -448,7 +508,7 @@ userConfig.executionMethod → meta.execution_config
 ##### Pre-Analysis Patterns

 **Dynamic Step Selection Guidelines**:
- **Context Loading**: Always include context package and role analysis loading
+- **Context Loading**: Always include context package and feature spec loading (or role analysis fallback)
 - **Architecture Analysis**: Add module structure analysis for complex projects
 - **Pattern Discovery**: Use CLI tools (gemini/qwen/bash) based on task complexity and available tools
 - **Tech-Specific Analysis**: Add language/framework-specific searches for specialized tasks
@@ -465,19 +525,51 @@ userConfig.executionMethod → meta.execution_config
    "on_error": "fail"
  },
  {
-    "step": "load_role_analysis_artifacts",
-    "action": "Load role analyses from context-package.json (progressive loading by priority)",
-    "commands": [
-      "Read({{context_package_path}})",
-      "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
-      "Read(extracted paths progressively)"
-    ],
-    "output_to": "role_analysis_artifacts",
+    "step": "load_brainstorm_artifacts",
+    "action": "Load brainstorm artifacts referenced by this task's context.artifacts[]",
+    "commands": "<<PLAN-TIME EXPANSION: Replace with concrete Read() commands>>",
+    "output_to": "brainstorm_context",
    "on_error": "skip_optional"
  }
 ]
 ```

+**Plan-Time Expansion Rule for `load_brainstorm_artifacts`**:
+
+When generating each task JSON, agent MUST expand this template step into concrete `Read()` commands based on the task's `context.artifacts[]` array. Since the agent writes both `context.artifacts[]` and `flow_control.pre_analysis[]` simultaneously, the artifact paths are known at plan time.
+
+**Expansion Algorithm**:
+```javascript
+function expandArtifactLoadStep(taskArtifacts) {
+  const commands = [];
+  // Expand each artifact reference into a concrete Read() command
+  for (const artifact of taskArtifacts) {
+    commands.push(`Read(${artifact.path})`);
+  }
+  // Fallback: if no artifacts, load role analyses from context-package
+  if (commands.length === 0) {
+    commands.push("Read(brainstorm_artifacts.role_analyses[0].files[0].path)");
+  }
+  return commands;
+}
+```
+
+**Example** - Task with 1 feature spec + 1 cross-cutting spec:
+```json
+{
+  "step": "load_brainstorm_artifacts",
+  "action": "Load feature spec F-001 and cross-cutting architecture spec",
+  "commands": [
+    "Read(.brainstorming/feature-specs/F-001-auth.md)",
+    "Read(.brainstorming/system-architect/analysis-cross-cutting.md)"
+  ],
+  "output_to": "brainstorm_context",
+  "on_error": "skip_optional"
+}
+```
+
+**Key**: `pre_analysis.commands[]` must only contain tool-call formats that code-developer can parse: `Read(path)`, `bash(cmd)`, `Search(pattern,path)`, `Glob(pattern)`, `mcp__xxx__yyy(args)`.
+
 **Optional Steps** (Select and adapt based on task needs):

 ```json
@@ -528,7 +620,7 @@ The examples above demonstrate **patterns**, not fixed requirements. Agent MUST:

 1. **Always Include** (Required):
   - `load_context_package` - Essential for all tasks
-   - `load_role_analysis_artifacts` - Critical for accessing brainstorming insights
+   - `load_brainstorm_artifacts` - Load brainstorm artifacts referenced by task's `context.artifacts[]`; falls back to role analysis progressive loading when no feature_spec artifacts

 2. **Progressive Addition of Analysis Steps**:
   Include additional analysis steps as needed for comprehensive planning:
--- a/.claude/agents/conceptual-planning-agent.md
+++ b/.claude/agents/conceptual-planning-agent.md
@@ -220,23 +220,35 @@ Generate documents according to loaded role template specifications:

 **Output Location**: `.workflow/WFS-[session]/.brainstorming/[assigned-role]/`

-**Output Files**:
- **analysis.md**: Index document with overview (optionally with `@` references to sub-documents)
+**Output Files** (feature-point organization when `feature_list` available):
+- **analysis.md**: Role overview index document with feature point listing and cross-cutting summary (< 1500 words)
+  - Contains: role perspective overview, feature point index with `@` references, cross-cutting summary
  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
- **analysis-{slug}.md**: Section content documents (slug from section heading: lowercase, hyphens)
-  - Maximum 5 sub-documents (merge related sections if needed)
- **Content**: Analysis AND recommendations sections
+- **analysis-cross-cutting.md**: Cross-feature architectural decisions, technology choices, shared patterns (< 2000 words)
+  - Contains: decisions/patterns that span multiple features, shared constraints, role-wide recommendations
+- **analysis-F-{id}-{slug}.md**: Per-feature analysis documents (< 2000 words each)
+  - `{id}` and `{slug}` come from `guidance-specification.md` Feature Decomposition table
+  - Example: `analysis-F-001-real-time-sync.md`, `analysis-F-002-user-auth.md`
+  - Contains: role-specific analysis, recommendations, and considerations for that feature
+  - Generate one sub-document per feature in the feature list

-**File Structure Example**:
+**Backward Compatibility** (when `feature_list` is NOT available):
+- Fall back to existing organization: `analysis-{slug}.md` with arbitrary topic slugs
+- Maximum 5 sub-documents (merge related sections if needed)
+- analysis.md remains the main document with overview
+
+**File Structure Example** (feature-point mode):
 ```
 .workflow/WFS-[session]/.brainstorming/system-architect/
-├── analysis.md                         # Index with overview + @references
-├── analysis-architecture-assessment.md # Section content
-├── analysis-technology-evaluation.md   # Section content
-├── analysis-integration-strategy.md    # Section content
-└── analysis-recommendations.md         # Section content (max 5 sub-docs total)
+├── analysis.md                           # Role overview index (< 1500 words)
+├── analysis-cross-cutting.md             # Cross-feature decisions (< 2000 words)
+├── analysis-F-001-real-time-sync.md      # Per-feature analysis (< 2000 words)
+├── analysis-F-002-user-auth.md           # Per-feature analysis (< 2000 words)
+└── analysis-F-003-data-pipeline.md       # Per-feature analysis (< 2000 words)

-NOTE: ALL files MUST start with 'analysis' prefix. Max 5 sub-documents.
+NOTE: ALL files MUST start with 'analysis' prefix.
+Feature-point mode: 1 index + 1 cross-cutting + N feature docs (N = feature count, max 8).
+Fallback mode: 1 index + max 5 arbitrary sub-docs.
 ```

 ## Role-Specific Planning Process
@@ -256,6 +268,16 @@ NOTE: ALL files MUST start with 'analysis' prefix. Max 5 sub-documents.
 - **Validate Against Template**: Ensure analysis meets role template requirements and standards

 ### 3. Brainstorming Documentation Phase
+
+**Feature-point mode** (when `feature_list` is available from guidance-specification.md):
+- **Read Feature List**: Extract Feature Decomposition table from guidance-specification.md
+- **Create analysis.md**: Role overview index (< 1500 words) with feature point listing and `@` references to sub-documents
+- **Create analysis-cross-cutting.md**: Cross-feature decisions, shared patterns, role-wide recommendations (< 2000 words)
+- **Create analysis-F-{id}-{slug}.md**: One per feature point, using ID and slug from feature list (< 2000 words each)
+- **Validate Output Structure**: Ensure all files saved to correct `.brainstorming/[role]/` directory
+- **Naming Validation**: Verify ALL files start with `analysis` prefix, feature docs match `analysis-F-{id}-{slug}.md` pattern
+
+**Fallback mode** (when `feature_list` is NOT available):
 - **Create analysis.md**: Main document with overview (optionally with `@` references)
 - **Create sub-documents**: `analysis-{slug}.md` for major sections (max 5)
 - **Validate Output Structure**: Ensure all files saved to correct `.brainstorming/[role]/` directory
@@ -311,6 +333,14 @@ When analysis is complete, ensure:
 ## Output Size Limits

 **Per-role limits** (prevent context overflow):
+
+**Feature-point mode** (when `feature_list` available):
+- `analysis.md` (index): < 1500 words
+- `analysis-cross-cutting.md`: < 2000 words
+- `analysis-F-{id}-{slug}.md`: < 2000 words each (one per feature, max 8 features)
+- Total: < 15000 words per role
+
+**Fallback mode** (when `feature_list` NOT available):
 - `analysis.md`: < 3000 words
 - `analysis-*.md`: < 2000 words each (max 5 sub-documents)
 - Total: < 15000 words per role
--- a/.claude/agents/context-search-agent.md
+++ b/.claude/agents/context-search-agent.md
@@ -339,7 +339,25 @@ if (dir_exists(brainstormDir)) {
      path: `${brainstormDir}/synthesis-specification.md`,
      exists: file_exists(`${brainstormDir}/synthesis-specification.md`),
      content: Read(`${brainstormDir}/synthesis-specification.md`) || null
-    }
+    },
+    // Feature index (optional - top level, matches action-planning-agent expected access pattern)
+    feature_index: file_exists(`${brainstormDir}/feature-specs/feature-index.json`) ? {
+      path: `${brainstormDir}/feature-specs/feature-index.json`,
+      exists: true,
+      content: Read(`${brainstormDir}/feature-specs/feature-index.json`) || null
+    } : undefined,
+    // Feature spec files (optional - individual feature specifications)
+    feature_specs: dir_exists(`${brainstormDir}/feature-specs`)
+      ? glob(`${brainstormDir}/feature-specs/F-*-*.md`).map(file => ({
+          path: file,
+          content: Read(file)
+        }))
+      : undefined,
+    // Cross-cutting specs (optional - cross-cutting concern analyses from roles)
+    cross_cutting_specs: glob(`${brainstormDir}/*/analysis-cross-cutting.md`).map(file => ({
+      path: file,
+      content: Read(file)
+    }))
  };
 }
 ```
@@ -462,7 +480,24 @@ Calculate risk level based on:
      "path": ".workflow/WFS-xxx/.brainstorming/synthesis-specification.md",
      "exists": true,
      "content": "# Synthesis Specification\n\n## Cross-Role Integration\n..."
-    }
+    },
+    "feature_index": {
+      "path": ".workflow/WFS-xxx/.brainstorming/feature-specs/feature-index.json",
+      "exists": true,
+      "content": "{\"version\":\"1.0\",\"features\":[...]}"
+    },
+    "feature_specs": [
+      {
+        "path": ".workflow/WFS-xxx/.brainstorming/feature-specs/F-001-auth.md",
+        "content": "# Feature Spec: F-001 - Auth\n..."
+      }
+    ],
+    "cross_cutting_specs": [
+      {
+        "path": ".workflow/WFS-xxx/.brainstorming/system-architect/analysis-cross-cutting.md",
+        "content": "# Cross-Cutting: Architecture Decisions\n..."
+      }
+    ]
  },
  "conflict_detection": {
    "risk_level": "medium",