refactor: Enhance agent definitions and workflow documentation structure

- Update agent role definitions with clearer responsibilities and capabilities - Refine task execution workflows with improved context gathering protocols - Enhance tool implementation guide with better command examples - Streamline workflow architecture documentation for better clarity 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-13 02:41:50 +08:00 · 2025-09-15 15:58:06 +08:00
parent d0b08794ca
commit 12f9e34223
12 changed files with 249 additions and 127 deletions
--- a/.claude/commands/workflow/execute.md
+++ b/.claude/commands/workflow/execute.md
@@ -23,19 +23,20 @@ The intelligent execution approach focuses on:
 - **Dynamic task orchestration** - Coordinate based on discovered task relationships
 - **Progress tracking** - Update task status after agent completion

-**Analysis Markers**:
- **[GEMINI_CLI_REQUIRED]**: Forces agent to use Gemini CLI for pattern-based codebase analysis
-  - **Auto-trigger**: When task.analysis_source = "gemini" OR scope > 3 files (default)
-  - **Agent Action**: MUST execute Gemini CLI as first step
- **[CODEX_CLI_REQUIRED]**: Forces agent to use Codex CLI for autonomous development analysis
-  - **Auto-trigger**: When task.analysis_source = "codex"
-  - **Agent Action**: MUST execute Codex CLI in autonomous mode as first step
+**Analysis Marker**:
+- **[MULTI_STEP_ANALYSIS]**: Indicates sequential pre-execution analysis required
+  - **Auto-trigger**: When task.pre_analysis is an array (default format)
+  - **Agent Action**: Execute comprehensive pre-analysis BEFORE implementation begins
+    - Process each step sequentially with specified templates and methods
+    - Expand brief actions into full analysis tasks
+    - Gather context, understand patterns, identify requirements
+    - Use method specified in each step (gemini/codex/manual/auto-detected)

-**analysis_source to Marker Mapping**:
- **"gemini"** → Add [GEMINI_CLI_REQUIRED]
- **"codex"** → Add [CODEX_CLI_REQUIRED]
- **"auto-detected"** + scope > 3 files → Add [GEMINI_CLI_REQUIRED] (default)
- **"manual"** → No marker added
+**pre_analysis to Marker Mapping**:
+- **Array format (multi-step pre-analysis)**:
+  - Add [MULTI_STEP_ANALYSIS] - triggers comprehensive pre-execution analysis
+  - Agent processes each step with specified method (gemini/codex/manual/auto-detected)
+  - Agent expands each action into comprehensive analysis based on template

 ## Execution Flow

@@ -65,14 +66,13 @@ Workflow Discovery:
 *Session: WFS-[topic-slug]*

 ## Execution Plan
- [ ] **TASK-001**: [Agent: planning-agent] [GEMINI_CLI_REQUIRED] Design auth schema (impl-1.1)
- [ ] **TASK-002**: [Agent: code-developer] [CODEX_CLI_REQUIRED] Implement auth logic (impl-1.2)  
+- [ ] **TASK-001**: [Agent: planning-agent] [MULTI_STEP_ANALYSIS] Design auth schema (impl-1.1)
+- [ ] **TASK-002**: [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement auth logic (impl-1.2)  
 - [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
 - [ ] **TASK-004**: Update task statuses and session state

 **Marker Legend**:
- [GEMINI_CLI_REQUIRED] = Agent must use Gemini CLI for pattern analysis
- [CODEX_CLI_REQUIRED] = Agent must use Codex CLI for autonomous analysis
+- [MULTI_STEP_ANALYSIS] = Agent must execute multi-step pre-execution analysis
 - [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement)
 ```

@@ -124,7 +124,23 @@ For each executable task:
        "performance_considerations": "Index JWT fields for faster lookups",
        "error_handling": "Graceful schema validation errors"
      },
-      "analysis_source": "auto-detected"
+      "pre_analysis": [
+        {
+          "action": "analyze auth",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+          "method": "gemini"
+        },
+        {
+          "action": "security review",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/security.txt",
+          "method": "gemini"
+        },
+        {
+          "action": "implement feature",
+          "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
+          "method": "codex"
+        }
+      ]
    }
  },
  "workflow": {
@@ -144,14 +160,14 @@ For each executable task:
 - **Risk Awareness**: Alert agents to implementation.context_notes.risks before execution
 - **Workflow Integration**: Include session state and IMPL_PLAN.md context
 - **Scope Focus**: Direct agents to specific files from implementation.files[].path
- **Gemini Marker**: Auto-add [GEMINI_CLI_REQUIRED] when analysis_source = "gemini"
+- **Analysis Marker**: Auto-add [MULTI_STEP_ANALYSIS] when pre_analysis is array format
 - **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists

 ### 4. Agent Execution & Progress Tracking

 ```bash
 Task(subagent_type="code-developer",
-     prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Analyze auth patterns and implement JWT authentication system
+     prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Analyze auth patterns and implement JWT authentication system

     Task Context: impl-1.2 - Saturated task with merged preparation and execution

@@ -241,7 +257,7 @@ Based on discovered task data:
 ```bash
 # Agent receives complete discovered context with saturation handling
 Task(subagent_type="code-developer",
-     prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Execute impl-1.2: Analyze and implement auth logic
+     prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Execute impl-1.2: Analyze and implement auth logic

     TASK TYPE: Saturated task (preparation_complexity: simple)

--- a/.claude/commands/workflow/plan-deep.md
+++ b/.claude/commands/workflow/plan-deep.md
@@ -90,8 +90,8 @@ Task(action-planning-agent):
    - Execute comprehensive Gemini CLI analysis (4 dimensions)
    - Skip PRD processing (no PRD provided)
    - Skip session inheritance (standalone planning)
-    - Force GEMINI_CLI_REQUIRED flag = true
-    - Set analysis_source = "gemini" (深度分析固定值)
+    - Force MULTI_STEP_ANALYSIS flag = true
+    - Set pre_analysis = multi-step array format with comprehensive analysis steps
    - Generate hierarchical task decomposition (max 2 levels: impl-N.M)
    - Create detailed IMPL_PLAN.md with subtasks
    - Generate TODO_LIST.md for tracking
@@ -126,8 +126,8 @@ def process_plan_deep_command(input):
    TASK: {task_description}
    
    MANDATORY FLAGS:
-    - GEMINI_CLI_REQUIRED = true
-    - analysis_source = "gemini" (固定设置)
+    - MULTI_STEP_ANALYSIS = true
+    - pre_analysis = multi-step array format for comprehensive pre-analysis
    - FORCE_PARALLEL_ANALYSIS = true
    - SKIP_PRD = true
    - SKIP_SESSION_INHERITANCE = true
--- a/.claude/commands/workflow/plan.md
+++ b/.claude/commands/workflow/plan.md
@@ -24,7 +24,7 @@ Creates actionable implementation plans with intelligent input source detection.

 ### Analysis Method Flag (--AM)
 Optional flag to specify which CLI tool to use for context analysis:
- **gemini** (default): Uses Gemini CLI for pattern-based analysis and architectural understanding
+- **gemini** (default): Uses Gemini CLI for pattern-based analysis, architectural understanding, and broader context acquisition
 - **codex**: Uses Codex CLI for autonomous development context gathering with intelligent file discovery

 **Examples**:
@@ -67,7 +67,30 @@ The command automatically detects input type:
 - Uses active session if available
 - Generates session ID: WFS-[topic-slug]

+### Pre-Planning Analysis
+⚠️ **CRITICAL**: Determine decomposition strategy BEFORE generating any plan documents
+
+**Required Pre-Analysis Steps**:
+1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
+2. **Decomposition Strategy**: Based on complexity, decide:
+   - Task structure (flat vs hierarchical)
+   - Subtask necessity (>15 tasks triggers decomposition)
+   - Task saturation level (merged vs separated)
+3. **Quantity Prediction**: Calculate expected:
+   - Total main tasks (IMPL-XXX)
+   - Subtasks per main task (impl-N.M)
+   - Container vs leaf task ratio
+
+**Pre-Planning Outputs**:
+- Complexity level: Simple (≤8) | Medium (9-15) | Complex (>15)
+- Decomposition approach: Flat | Two-level hierarchy
+- Estimated task count: [number] main tasks, [number] total leaf tasks
+- Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json)
+
+**Only after completing pre-planning analysis**: Proceed to generate actual plan documents
+
 ### Complexity Detection with Saturation
+*Based on Pre-Planning Analysis results:*
 - **Simple**: ≤8 saturated tasks → Direct IMPL_PLAN.md
 - **Medium**: 9-15 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
 - **Complex**: >15 saturated tasks → Full decomposition
@@ -93,6 +116,7 @@ The command automatically detects input type:
 - IMPL-002: Implement data export functionality (includes processing logic, UI, file generation)

 ### Task Generation with Saturation Control
+*Using decomposition strategy determined in Pre-Planning Analysis:*
 - **Task Saturation Assessment**: Evaluates whether to merge preparation and execution
 - **Default merge mode**: "Analyze and implement X" instead of "Analyze X" + "Implement X"
 - **Smart splitting**: Only separate when preparation complexity > threshold
@@ -157,10 +181,15 @@ Evaluates whether to merge preparation and execution:
 - **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review)
 - **Maximum depth**: 2 levels (impl-N.M) to maintain manageable hierarchy

-### Implementation Field Requirements  
- **analysis_source**: Determines context gathering method (manual|auto-detected|gemini|codex)
- **Auto-assignment**: manual (user provides details) → auto-detected (system infers) → gemini/codex (needs analysis)
- **Required fields**: files (with path/location/modifications), context_notes, analysis_source
+### Implementation Field Requirements
+- **pre_analysis**: Multi-step analysis configuration array containing:
+  - `action`: Brief 2-3 word description (e.g., "analyze patterns", "review security") - agent expands based on context
+  - `template`: Full template path (e.g., "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt")
+  - `method`: Analysis method ("manual"|"auto-detected"|"gemini"|"codex")
+  - **Agent Behavior**: Agents interpret brief actions and expand them into comprehensive analysis tasks
+  - **Execution**: Steps processed sequentially, results accumulated for comprehensive context
+- **Auto-assignment**: Defaults to appropriate multi-step configuration based on complexity
+- **Required fields**: files (with path/location/modifications), context_notes, pre_analysis
 - **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json")

 ## Session Check Process