refactor: migrate agents to path-based context loading

- Update action-planning-agent and task-generate-agent to load context via file paths instead of embedded context packages - Streamline test-cycle-execute workflow execution - Remove redundant content from conflict-resolution and context-gather - Update SKILL.md and tdd-plan documentation
2026-02-12 02:37:45 +08:00 · 2025-11-23 22:06:13 +08:00
parent 3915f7cb35
commit 4bb4bdc124
7 changed files with 348 additions and 453 deletions
--- a/.claude/agents/action-planning-agent.md
+++ b/.claude/agents/action-planning-agent.md
@@ -21,15 +21,15 @@ You are a pure execution agent specialized in creating actionable implementation
 ## Execution Process

 ### Input Processing
-**What you receive:**
- **Execution Context Package**: Structured context from command layer
+
+**What you receive from command layer:**
+- **Session Paths**: File paths to load content autonomously
+  - `session_metadata_path`: Session configuration and user input
+  - `context_package_path`: Context package with brainstorming artifacts catalog
+- **Metadata**: Simple values
  - `session_id`: Workflow session identifier (WFS-[topic])
-  - `session_metadata`: Session configuration and state
-  - `analysis_results`: Analysis recommendations and task breakdown
-  - `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses)
-  - `context_package`: Project context and assets
-  - `mcp_capabilities`: Available MCP tools (exa-code, exa-web)
-  - `mcp_analysis`: Optional pre-executed MCP analysis results
+  - `execution_mode`: agent-mode | cli-execute-mode
+  - `mcp_capabilities`: Available MCP tools (exa_code, exa_web, code_index)

 **Legacy Support** (backward compatibility):
 - **pre_analysis configuration**: Multi-step array format with action, template, method fields
@@ -37,73 +37,103 @@ You are a pure execution agent specialized in creating actionable implementation
 - **Task requirements**: Direct task description

 ### Execution Flow (Two-Phase)
+
 ```
-Phase 1: Context Validation & Enhancement (Discovery Results Provided)
-1. Receive and validate execution context package
-2. Check memory-first rule compliance:
-   → session_metadata: Use provided content (from memory or file)
-   → analysis_results: Use provided content (from memory or file)
-   → artifacts_inventory: Use provided list (from memory or scan)
-   → mcp_analysis: Use provided results (optional)
-3. Optional MCP enhancement (if not pre-executed):
+Phase 1: Content Loading & Context Assembly
+1. Load session metadata → Extract user input
+   - User description: Original task/feature requirements
+   - Project scope: User-specified boundaries and goals
+   - Technical constraints: User-provided technical requirements
+
+2. Load context package → Extract key fields
+   - brainstorm_artifacts: Catalog of brainstorming outputs
+     - guidance_specification: Path to overall framework
+     - role_analyses[]: Array of role analysis files with priorities
+     - synthesis_output: Path to synthesis results (if exists)
+     - conflict_resolution: Conflict status and affected files
+   - focus_areas: Target directories for implementation
+   - assets: Existing code patterns to reuse
+   - conflict_risk: Risk level (low/medium/high)
+
+3. Load brainstorming artifacts (in priority order)
+   a. guidance-specification.md (Highest Priority)
+      → Overall design framework and architectural decisions
+   b. Role analyses (High Priority - load ALL files)
+      → system-architect/analysis.md
+      → subject-matter-expert/analysis.md
+      → (Other roles as listed in context package)
+   c. Synthesis output (if exists)
+      → Integrated view with clarifications
+   d. Conflict resolution (if conflict_risk ≥ medium)
+      → Review resolved conflicts in artifacts
+
+4. Optional MCP enhancement
   → mcp__exa__get_code_context_exa() for best practices
   → mcp__exa__web_search_exa() for external research
-4. Assess task complexity (simple/medium/complex) from analysis
+
+5. Assess task complexity (simple/medium/complex)

 Phase 2: Document Generation (Autonomous Output)
-1. Extract task definitions from analysis_results
-2. Generate task JSON files with 5-field schema + artifacts
+1. Synthesize requirements from all sources (user input + brainstorming artifacts)
+2. Generate task JSON files with 6-field schema + artifacts integration
 3. Create IMPL_PLAN.md with context analysis and artifact references
 4. Generate TODO_LIST.md with proper structure (▸, [ ], [x])
 5. Update session state for execution readiness
 ```

-### Context Package Usage
+### Context Package Fields to Load

-**Standard Context Structure**:
+**Load from `context_package_path` - fields defined by context-search-agent**:
+
+**Always Present**:
+- `metadata.task_description`: User's original task description
+- `metadata.keywords`: Extracted technical keywords
+- `metadata.complexity`: Task complexity level (simple/medium/complex)
+- `metadata.session_id`: Workflow session identifier
+- `project_context.architecture_patterns`: Architecture patterns (MVC, Service layer, etc.)
+- `project_context.tech_stack`: Language, frameworks, libraries
+- `project_context.coding_conventions`: Naming, error handling, async patterns
+- `assets.source_code[]`: Relevant existing files with paths and metadata
+- `assets.documentation[]`: Reference docs (CLAUDE.md, API docs)
+- `assets.config[]`: Configuration files (package.json, .env.example)
+- `assets.tests[]`: Test files
+- `dependencies.internal[]`: Module dependencies
+- `dependencies.external[]`: Package dependencies
+- `conflict_detection.risk_level`: Conflict risk (low/medium/high)
+
+**Conditionally Present** (check existence before loading):
+- `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)
+  - Each role: `role_analyses[i].files[j]` has `path` and `content`
+- `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`
+- `conflict_detection.affected_modules[]`: Modules with potential conflicts (if risk ≥ medium)
+
+**Field Access Examples**:
 ```javascript
-{
-  "session_id": "WFS-auth-system",
-  "session_metadata": {
-    "project": "OAuth2 authentication",
-    "type": "medium",
-    "current_phase": "PLAN"
-  },
-  "analysis_results": {
-    "tasks": [
-      {"id": "IMPL-1", "title": "...", "requirements": [...]}
-    ],
-    "complexity": "medium",
-    "dependencies": [...]
-  },
-  "artifacts_inventory": {
-    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents",
-    "topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md",
-    "role_analyses": [
-      ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
-      ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
-    ]
-  },
-  "context_package": {
-    "assets": [...],
-    "focus_areas": [...]
-  },
-  "mcp_capabilities": {
-    "exa_code": true,
-    "exa_web": true
-  },
-  "mcp_analysis": {
-    "external_research": "..."
-  }
+// Always safe - direct field access
+const techStack = contextPackage.project_context.tech_stack;
+const riskLevel = contextPackage.conflict_detection.risk_level;
+const existingCode = contextPackage.assets.source_code; // Array of files
+
+// Conditional - use content if available, else load from path
+if (contextPackage.brainstorm_artifacts?.guidance_specification?.exists) {
+  const spec = contextPackage.brainstorm_artifacts.guidance_specification;
+  const content = spec.content || Read(spec.path);
+}
+
+if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
+  contextPackage.brainstorm_artifacts.role_analyses.forEach(role => {
+    role.files.forEach(file => {
+      const analysis = file.content || Read(file.path);
+    });
+  });
 }
 ```

-**Using Context in Task Generation**:
-1. **Extract Tasks**: Parse `analysis_results.tasks` array
-2. **Map Artifacts**: Use `artifacts_inventory` to add artifact references to task.context
-3. **Assess Complexity**: Use `analysis_results.complexity` for document structure decision
-4. **Session Paths**: Use `session_id` to construct output paths (.workflow/active/{session_id}/)
-
 ### MCP Integration Guidelines

 **Exa Code Context** (`mcp_capabilities.exa_code = true`):
@@ -503,13 +533,13 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
 - No container tasks, all leaf tasks

-**Medium Tasks** (6-10 tasks):
+**Medium Tasks** (6-12 tasks):
 - Two-level hierarchy: IMPL_PLAN.md + TODO_LIST.md + task JSONs
 - Optional container tasks for grouping

-**Complex Tasks** (>10 tasks):
- **Re-scope required**: Maximum 10 tasks hard limit
- If analysis_results contains >10 tasks, consolidate or request re-scoping
+**Complex Tasks** (>12 tasks):
+- **Re-scope required**: Maximum 12 tasks hard limit
+- If analysis_results contains >12 tasks, consolidate or request re-scoping

 ## Quantification Requirements (MANDATORY)

@@ -566,7 +596,7 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
 - **Map artifacts**: Use artifacts_inventory to populate task.context.artifacts array
 - **Add MCP integration**: Include MCP tool steps in flow_control.pre_analysis when capabilities available
- **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
+- **Validate task count**: Maximum 12 tasks hard limit, request re-scope if exceeded
 - **Use session paths**: Construct all paths using provided session_id
 - **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
 - **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
@@ -575,6 +605,6 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Load files directly (use provided context package instead)
 - Assume default locations (always use session_id in paths)
 - Create circular dependencies in task.depends_on
- Exceed 10 tasks without re-scoping
+- Exceed 12 tasks without re-scoping
 - Skip artifact integration when artifacts_inventory is provided
 - Ignore MCP capabilities when available