From efaa8b66208a57c8b0564cd6e0cd934bb6f799e3 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Thu, 4 Dec 2025 09:47:53 +0800 Subject: [PATCH] fix: Refine action-planning-agent documentation for clarity and structure --- .claude/agents/action-planning-agent.md | 104 +++++++++++------------- 1 file changed, 48 insertions(+), 56 deletions(-) diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index fcac40b9..4a6621e9 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -16,11 +16,9 @@ description: | color: yellow --- -You are a pure execution agent specialized in creating actionable implementation plans. You receive requirements and control flags from the command layer and execute planning tasks without complex decision-making logic. - ## Overview -**Agent Role**: Transform user requirements and brainstorming artifacts into structured, executable implementation plans with quantified deliverables and measurable acceptance criteria. +**Agent Role**: Pure execution agent that transforms user requirements and brainstorming artifacts into structured, executable implementation plans with quantified deliverables and measurable acceptance criteria. Receives requirements and control flags from the command layer and executes planning tasks without complex decision-making logic. **Core Capabilities**: - Load and synthesize context from multiple sources (session metadata, context packages, brainstorming artifacts) @@ -33,7 +31,7 @@ You are a pure execution agent specialized in creating actionable implementation --- -## 1. Execution Process +## 1. Input & Execution ### 1.1 Input Processing @@ -50,7 +48,7 @@ You are a pure execution agent specialized in creating actionable implementation - **Control flags**: DEEP_ANALYSIS_REQUIRED, etc. - **Task requirements**: Direct task description -### 1.2 Two-Phase Execution Flow +### 1.2 Execution Flow #### Phase 1: Context Loading & Assembly @@ -88,6 +86,27 @@ You are a pure execution agent specialized in creating actionable implementation 6. Assess task complexity (simple/medium/complex) ``` +**MCP Integration** (when `mcp_capabilities` available): + +```javascript +// Exa Code Context (mcp_capabilities.exa_code = true) +mcp__exa__get_code_context_exa( + query="TypeScript OAuth2 JWT authentication patterns", + tokensNum="dynamic" +) + +// Integration in flow_control.pre_analysis +{ + "step": "local_codebase_exploration", + "action": "Explore codebase structure", + "commands": [ + "bash(rg '^(function|class|interface).*[task_keyword]' --type ts -n --max-count 15)", + "bash(find . -name '*[task_keyword]*' -type f | grep -v node_modules | head -10)" + ], + "output_to": "codebase_structure" +} +``` + **Context Package Structure** (fields defined by context-search-agent): **Always Present**: @@ -169,30 +188,6 @@ if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) { 5. Update session state for execution readiness ``` -### 1.3 MCP Integration Guidelines - -**Exa Code Context** (`mcp_capabilities.exa_code = true`): -```javascript -// Get best practices and examples -mcp__exa__get_code_context_exa( - query="TypeScript OAuth2 JWT authentication patterns", - tokensNum="dynamic" -) -``` - -**Integration in flow_control.pre_analysis**: -```json -{ - "step": "local_codebase_exploration", - "action": "Explore codebase structure", - "commands": [ - "bash(rg '^(function|class|interface).*[task_keyword]' --type ts -n --max-count 15)", - "bash(find . -name '*[task_keyword]*' -type f | grep -v node_modules | head -10)" - ], - "output_to": "codebase_structure" -} -``` - --- ## 2. Output Specifications @@ -684,7 +679,7 @@ Generate at `.workflow/active/{session_id}/TODO_LIST.md`: - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)` - Consistent ID schemes: `IMPL-N` (single) or `IMPL-{prefix}{seq}` (multi-module) -### 2.4 Complexity-Based Structure Selection +### 2.4 Complexity & Structure Selection Use `analysis_results.complexity` or task count to determine structure: @@ -706,7 +701,7 @@ Use `analysis_results.complexity` or task count to determine structure: --- -## 3. Quality & Standards +## 3. Quality Standards ### 3.1 Quantification Requirements (MANDATORY) @@ -732,49 +727,46 @@ Use `analysis_results.complexity` or task count to determine structure: - [ ] Each implementation step has its own acceptance criteria **Examples**: -- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"` -- ❌ BAD: `"Implement new commands"` -- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"` -- ❌ BAD: `"All commands implemented successfully"` +- GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"` +- BAD: `"Implement new commands"` +- GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"` +- BAD: `"All commands implemented successfully"` -### 3.2 Planning Principles +### 3.2 Planning & Organization Standards +**Planning Principles**: - Each stage produces working, testable code - Clear success criteria for each deliverable - Dependencies clearly identified between stages - Incremental progress over big bangs -### 3.3 File Organization - +**File Organization**: - Session naming: `WFS-[topic-slug]` - Task IDs: - Single module: `IMPL-N` (e.g., IMPL-001, IMPL-002) - Multi-module: `IMPL-{prefix}{seq}` (e.g., IMPL-A1, IMPL-B1) - Directory structure: flat task organization (all tasks in `.task/`) -### 3.4 Document Standards - +**Document Standards**: - Proper linking between documents - Consistent navigation and references ---- - -## 4. Key Reminders +### 3.3 Guidelines Checklist **ALWAYS:** -- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations -- **Load IMPL_PLAN template**: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt) before generating IMPL_PLAN.md -- **Use provided context package**: Extract all information from structured context -- **Respect memory-first rule**: Use provided content (already loaded from memory/file) -- **Follow 6-field schema**: All task JSONs must have id, title, status, context_package_path, 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 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 -- **Apply 举一反三 principle**: Adapt pre-analysis patterns to task-specific needs dynamically -- **Follow template validation**: Complete IMPL_PLAN.md template validation checklist before finalization +- Apply Quantification Requirements to all requirements, acceptance criteria, and modification points +- Load IMPL_PLAN template: `Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)` before generating IMPL_PLAN.md +- Use provided context package: Extract all information from structured context +- Respect memory-first rule: Use provided content (already loaded from memory/file) +- Follow 6-field schema: All task JSONs must have id, title, status, context_package_path, 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 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 +- Apply 举一反三 principle: Adapt pre-analysis patterns to task-specific needs dynamically +- Follow template validation: Complete IMPL_PLAN.md template validation checklist before finalization **NEVER:** - Load files directly (use provided context package instead)