From 12f9e34223924cab1912432b53eb1f6caca4a0fd Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 15 Sep 2025 15:58:06 +0800 Subject: [PATCH] refactor: Enhance agent definitions and workflow documentation structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .claude/agents/action-planning-agent.md | 65 +++++++++++-------- .claude/agents/code-developer.md | 30 ++++----- .claude/agents/code-review-test-agent.md | 62 +++++++++--------- .claude/agents/conceptual-planning-agent.md | 41 ++++++------ .claude/commands/task/create.md | 2 +- .claude/commands/task/execute.md | 8 ++- .claude/commands/workflow/execute.md | 56 ++++++++++------ .claude/commands/workflow/plan-deep.md | 8 +-- .claude/commands/workflow/plan.md | 39 +++++++++-- .claude/workflows/task-core.md | 15 ++++- .../workflows/tools-implementation-guide.md | 33 ++++++++++ .claude/workflows/workflow-architecture.md | 17 ++++- 12 files changed, 249 insertions(+), 127 deletions(-) diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index f559bf1d..0c357191 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -22,6 +22,10 @@ You are a pure execution agent specialized in creating actionable implementation ## Execution Process ### Input Processing +**What you receive:** +- **pre_analysis configuration**: Multi-step array format with action, template, method fields +- **Brief actions**: 2-3 word descriptions to expand into comprehensive analysis tasks + **What you receive:** - Task requirements and context - Control flags from command layer (DEEP_ANALYSIS_REQUIRED, etc.) @@ -30,43 +34,48 @@ You are a pure execution agent specialized in creating actionable implementation ### Execution Flow ``` 1. Parse input requirements and extract control flags -2. IF DEEP_ANALYSIS_REQUIRED flag present: - → Check for analysis method markers: - - [GEMINI_CLI_REQUIRED] → Execute comprehensive Gemini CLI analysis using gemini-wrapper - - [CODEX_CLI_REQUIRED] → Execute autonomous Codex CLI analysis - → Use analysis results for planning context -3. Assess task complexity (simple/medium/complex) +2. Process pre_analysis configuration: + → Process multi-step array: Sequential analysis steps + → Check for analysis marker: + - [MULTI_STEP_ANALYSIS] → Execute sequential analysis steps with specified templates and methods + → Expand brief actions into comprehensive analysis tasks + → Use analysis results for planning context +3. Assess task complexity (simple/medium/complex) 4. Create staged implementation plan 5. Generate required documentation 6. Update workflow structure ``` -**Analysis CLI Usage Standards**: -- **Gemini CLI**: Use task-specific paths: `bash(~/.claude/scripts/gemini-wrapper -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md}")` -- **Codex CLI**: Use task-specific paths: `bash(codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")` +**Pre-Execution Analysis Standards**: +- **Multi-step Pre-Analysis**: Execute comprehensive analysis BEFORE implementation begins + - **Purpose**: Gather context, understand patterns, identify requirements before coding + - **Sequential Processing**: Process each step sequentially, expanding brief actions + - **Example**: "analyze auth" → "Analyze existing authentication patterns, identify current implementation approaches, understand dependency relationships" + - **Template Usage**: Use full template paths with $(cat template_path) for enhanced prompts + - **Method Selection**: Use method specified in each step (gemini/codex/manual/auto-detected) +- **CLI Commands**: + - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")` + - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]")` - **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md -### Deep Analysis Execution -**When DEEP_ANALYSIS_REQUIRED flag is present:** +### Pre-Execution Analysis +**When [MULTI_STEP_ANALYSIS] marker is present:** -#### Gemini CLI Analysis (Pattern-Based) -**When [GEMINI_CLI_REQUIRED] marker present:** -1. Execute comprehensive Gemini CLI analysis across 4 dimensions: - - Architecture patterns and component relationships - - Implementation conventions and coding standards - - Module dependencies and integration points - - Testing requirements and coverage patterns -2. Consolidate analysis results for planning context -3. Use analysis to inform implementation stages and task breakdown +#### Multi-Step Pre-Analysis Execution +1. Process each analysis step sequentially from pre_analysis array +2. For each step: + - Expand brief action into comprehensive analysis task + - Use specified template with $(cat template_path) + - Execute with specified method (gemini/codex/manual/auto-detected) +3. Accumulate results across all steps for comprehensive context +4. Use consolidated analysis to inform implementation stages and task breakdown -#### Codex CLI Analysis (Autonomous Development) -**When [CODEX_CLI_REQUIRED] marker present:** -1. Execute autonomous Codex CLI analysis: - - Intelligent file discovery and code pattern recognition - - Autonomous implementation strategy development - - System-wide impact assessment and integration planning - - Automated testing and validation approach recommendations -2. Integrate autonomous analysis results into planning framework +#### Analysis Dimensions Coverage +- Architecture patterns and component relationships +- Implementation conventions and coding standards +- Module dependencies and integration points +- Testing requirements and coverage patterns +- Security considerations and performance implications 3. Use Codex insights to create self-guided implementation stages ## Core Functions diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md index e717c228..c5876554 100644 --- a/.claude/agents/code-developer.md +++ b/.claude/agents/code-developer.md @@ -38,26 +38,26 @@ You are a code execution specialist focused on implementing high-quality, produc IF context sufficient for implementation: → Proceed with execution ELIF context insufficient OR task has analysis marker: - → Check marker type: - - [GEMINI_CLI_REQUIRED] → Execute Gemini CLI for codebase analysis (MANDATORY) - - [CODEX_CLI_REQUIRED] → Execute Codex CLI for autonomous context gathering (MANDATORY) + → Check for [MULTI_STEP_ANALYSIS] marker: + - Execute comprehensive pre-analysis BEFORE implementation begins + - Process each step with specified method (gemini/codex/manual/auto-detected) + - Expand brief actions into comprehensive analysis tasks → Extract patterns and conventions → Proceed with execution ``` -**Analysis CLI Marker System**: -- **[GEMINI_CLI_REQUIRED]**: Mandatory Gemini analysis flag - - **Trigger**: Auto-added when task.analysis_source = "gemini" or scope > 3 files (default) - - **Action**: MUST run Gemini CLI first to gather context - - **Purpose**: Ensures code aligns with existing patterns through pattern-based analysis -- **[CODEX_CLI_REQUIRED]**: Mandatory Codex analysis flag - - **Trigger**: Auto-added when task.analysis_source = "codex" - - **Action**: MUST run Codex CLI in autonomous mode first to gather context - - **Purpose**: Enables autonomous development with intelligent file discovery and code generation +**Pre-Execution Analysis System**: +- **[MULTI_STEP_ANALYSIS]**: Mandatory pre-execution analysis flag + - **Trigger**: Auto-added when task.pre_analysis is an array (default format) + - **Action**: MUST run multi-step pre-analysis first to gather comprehensive context + - **Purpose**: Ensures code aligns with existing patterns through comprehensive pre-execution analysis -**Analysis CLI Usage Standards**: -- **Gemini CLI**: Use task-specific paths from JSON: `bash(~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")` -- **Codex CLI**: Use task-specific paths from JSON: `bash(codex --full-auto exec "$(~/.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]")` +**Pre-Analysis CLI Usage Standards**: +- **Multi-step Processing**: Execute each analysis step sequentially with specified templates +- **Method Selection**: Use method specified in each step (gemini/codex/manual/auto-detected) +- **CLI Commands**: + - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]")` + - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [expanded_action]")` - **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md diff --git a/.claude/agents/code-review-test-agent.md b/.claude/agents/code-review-test-agent.md index 195177e5..741bdf61 100644 --- a/.claude/agents/code-review-test-agent.md +++ b/.claude/agents/code-review-test-agent.md @@ -50,54 +50,58 @@ You will review code changes AND handle test implementation by understanding the ## Analysis CLI Context Activation Rules **ðŸŽŊ Analysis Marker Detection** -When task assignment includes analysis markers: -- **[GEMINI_CLI_REQUIRED]**: Execute Gemini CLI context gathering as first step -- **[CODEX_CLI_REQUIRED]**: Execute Codex CLI autonomous analysis as first step +When task assignment includes analysis marker: +- **[MULTI_STEP_ANALYSIS]**: Execute sequential analysis steps with specified templates, expanding brief actions + +**Multi-Step Analysis Support**: +- **Process pre_analysis array**: Handle multi-step array format +- **Expand brief actions**: Convert 2-3 word descriptions into comprehensive analysis tasks +- **Sequential execution**: Execute each analysis step in order, accumulating context +- **Template integration**: Use full template paths for enhanced analysis prompts **Context Gathering Decision Logic**: ``` -IF task contains [GEMINI_CLI_REQUIRED] flag: - → Execute Gemini CLI context gathering (MANDATORY) - → Use pattern-based code review analysis -ELIF task contains [CODEX_CLI_REQUIRED] flag: - → Execute Codex CLI autonomous analysis (MANDATORY) - → Use autonomous development context for review +IF task contains [MULTI_STEP_ANALYSIS] flag: + → Execute each analysis step sequentially with specified templates + → Expand brief actions into comprehensive analysis tasks + → Use method specified in each step (gemini/codex/manual/auto-detected) + → Accumulate results for comprehensive context ELIF reviewing >3 files OR security changes OR architecture modifications: - → Execute Gemini CLI context gathering (AUTO-TRIGGER, default) + → Execute default multi-step analysis (AUTO-TRIGGER) ELSE: → Proceed with review using standard quality checks ``` -## Context Gathering Phase (Execute When Required) +## Multi-Step Pre-Analysis Phase (Execute When Required) -### Gemini CLI Context Gathering -When [GEMINI_CLI_REQUIRED] flag is present or complexity triggers apply, gather precise, change-focused context: +### Multi-Step Analysis Execution +When [MULTI_STEP_ANALYSIS] flag is present, execute comprehensive pre-review analysis: -Use the targeted review context template: -@~/.claude/workflows/tools-implementation-guide.md +Process each step from pre_analysis array sequentially: -**Gemini CLI Command**: +**Multi-Step Analysis Process**: +1. For each analysis step: + - Extract action, template, method from step configuration + - Expand brief action into comprehensive analysis task + - Execute with specified method and template + +**Example CLI Commands**: ```bash -bash(~/.claude/scripts/gemini-wrapper -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md} [review-analysis-prompt]") +# For method="gemini" +bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [expanded_action]") + +# For method="codex" +bash(codex --full-auto exec "$(cat template_path) [expanded_action]") ``` -This executes a change-specific Gemini CLI command that identifies: +This executes comprehensive pre-review analysis that covers: - **Change understanding**: What specific task was being implemented - **Repository conventions**: Standards used in similar files and functions - **Impact analysis**: Other code that might be affected by these changes - **Test coverage validation**: Whether changes are properly tested - **Integration verification**: If necessary integration points are handled - -### Codex CLI Context Gathering -When [CODEX_CLI_REQUIRED] flag is present, execute autonomous analysis: - -Use the autonomous development context template: -@~/.claude/workflows/tools-implementation-guide.md - -**Codex CLI Command**: -```bash -bash(codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [autonomous-review-prompt]") -``` +- **Security implications**: Potential security considerations +- **Performance impact**: Performance-related changes and implications This executes autonomous Codex CLI analysis that provides: - **Autonomous understanding**: Intelligent discovery of implementation context diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index f48b41fb..4ad1372f 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.claude/agents/conceptual-planning-agent.md @@ -37,9 +37,8 @@ You are a conceptual planning specialist focused on single-role strategic thinki ## Analysis Method Integration ### Detection and Activation -When receiving task prompt, check for analysis markers: -- **[GEMINI_CLI_REQUIRED]** - Execute mandatory Gemini CLI pattern-based analysis -- **[CODEX_CLI_REQUIRED]** - Execute mandatory Codex CLI autonomous analysis +When receiving task prompt, check for analysis marker: +- **[MULTI_STEP_ANALYSIS]** - Execute mandatory multi-step pre-execution analysis - **ASSIGNED_ROLE** - Extract the specific role for focused analysis - **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions @@ -49,22 +48,26 @@ def handle_analysis_markers(prompt): role = extract_value("ASSIGNED_ROLE", prompt) dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt) topic = extract_topic(prompt) - - if "[GEMINI_CLI_REQUIRED]" in prompt: - for dimension in dimensions: - result = execute_gemini_cli( - command=f"bash(~/.claude/scripts/gemini-wrapper -p \"$(.claude/scripts/read-task-paths.sh [task-json-file]) @{{CLAUDE.md}} {dimension}\")", - dimension=dimension, - role_context=role, - topic=topic - ) - integrate_to_role_output(result, role) - - elif "[CODEX_CLI_REQUIRED]" in prompt: - result = execute_codex_cli( - command=f"bash(codex --full-auto exec \"$(.claude/scripts/read-task-paths.sh [task-json-file]) {topic}\")", - autonomous_analysis=True, - role_context=role, + + if "[MULTI_STEP_ANALYSIS]" in prompt: + analysis_steps = extract_pre_analysis_array(prompt) + for step in analysis_steps: + action = step["action"] + template = step["template"] + method = step["method"] + + expanded_action = expand_brief_action(action, role, topic) + + if method == "gemini": + result = execute_gemini_cli( + command=f"bash(~/.claude/scripts/gemini-wrapper -p \"$(cat {template}) {expanded_action}\")", + role_context=role, + topic=topic + ) + elif method == "codex": + result = execute_codex_cli( + command=f"bash(codex --full-auto exec \"$(cat {template}) {expanded_action}\")", + role_context=role, topic=topic ) integrate_autonomous_insights(result, role) diff --git a/.claude/commands/task/create.md b/.claude/commands/task/create.md index 620711f2..1e9ba99b 100644 --- a/.claude/commands/task/create.md +++ b/.claude/commands/task/create.md @@ -72,7 +72,7 @@ Status: pending ### Auto-Population Strategy - **Detailed info**: Extract from task description and scope -- **Missing info**: Mark `analysis_source` as "gemini" for later analysis +- **Missing info**: Mark `pre_analysis` as multi-step array format for later pre-analysis - **Basic structure**: Initialize with standard template ### Analysis Triggers diff --git a/.claude/commands/task/execute.md b/.claude/commands/task/execute.md index f6207a46..25cb1d4f 100644 --- a/.claude/commands/task/execute.md +++ b/.claude/commands/task/execute.md @@ -189,7 +189,13 @@ This is the simplified data structure loaded to provide context for task executi "performance_considerations": "JWT validation adds ~10ms per request, OAuth callbacks may timeout", "error_handling": "Ensure sensitive authentication errors don't leak user enumeration data" }, - "analysis_source": "gemini" + "pre_analysis": [ + { + "action": "analyze patterns", + "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", + "method": "gemini" + } + ] } }, "workflow": { diff --git a/.claude/commands/workflow/execute.md b/.claude/commands/workflow/execute.md index efeea693..50eed596 100644 --- 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) diff --git a/.claude/commands/workflow/plan-deep.md b/.claude/commands/workflow/plan-deep.md index 7804bcb5..3ed6d0ff 100644 --- 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 diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index d3bc2bfe..97e6d5e8 100644 --- 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 diff --git a/.claude/workflows/task-core.md b/.claude/workflows/task-core.md index ec5f59b8..c76ce56f 100644 --- a/.claude/workflows/task-core.md +++ b/.claude/workflows/task-core.md @@ -71,7 +71,18 @@ All task files use this unified 10-field structure: "performance_considerations": "JWT adds ~5ms latency", "error_handling": "No sensitive data in errors" }, - "analysis_source": "manual|gemini|codex|auto-detected" + "pre_analysis": [ + { + "action": "analyze patterns", + "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", + "method": "gemini" + }, + { + "action": "implement feature", + "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt", + "method": "codex" + } + ] } } ``` @@ -96,7 +107,7 @@ All task files use this unified 10-field structure: - **performance_considerations**: Performance impact - **error_handling**: Error handling requirements -### analysis_source Options +### pre_analysis Options - **manual**: User-provided details - **auto-detected**: System-inferred - **gemini**: Requires Gemini CLI analysis diff --git a/.claude/workflows/tools-implementation-guide.md b/.claude/workflows/tools-implementation-guide.md index 1c358b0b..02158cbb 100644 --- a/.claude/workflows/tools-implementation-guide.md +++ b/.claude/workflows/tools-implementation-guide.md @@ -22,6 +22,39 @@ type: technical-guideline **Usage**: `$(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt)` +### 📚 Template Quick Reference Map + +**Full Path Format**: All templates use complete paths starting with `~/.claude/` + +**Analysis Templates**: +- `~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt` - Pattern detection and convention analysis +- `~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt` - System architecture review +- `~/.claude/workflows/cli-templates/prompts/analysis/security.txt` - Security vulnerability assessment +- `~/.claude/workflows/cli-templates/prompts/analysis/performance.txt` - Performance bottleneck analysis +- `~/.claude/workflows/cli-templates/prompts/analysis/quality.txt` - Code quality and maintainability review + +**Development Templates**: +- `~/.claude/workflows/cli-templates/prompts/development/feature.txt` - Feature implementation guidance +- `~/.claude/workflows/cli-templates/prompts/development/component.txt` - Component development patterns +- `~/.claude/workflows/cli-templates/prompts/development/refactor.txt` - Refactoring strategies +- `~/.claude/workflows/cli-templates/prompts/development/testing.txt` - Test generation and coverage +- `~/.claude/workflows/cli-templates/prompts/development/debugging.txt` - Issue diagnosis and resolution + +**Planning Templates**: +- `~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt` - Task decomposition strategy +- `~/.claude/workflows/cli-templates/prompts/planning/migration.txt` - Migration planning and execution + +**Automation Templates**: +- `~/.claude/workflows/cli-templates/prompts/automation/scaffold.txt` - Project scaffolding automation +- `~/.claude/workflows/cli-templates/prompts/automation/deployment.txt` - Deployment configuration + +**Review Templates**: +- `~/.claude/workflows/cli-templates/prompts/review/code-review.txt` - Code review checklist + +**Integration Templates**: +- `~/.claude/workflows/cli-templates/prompts/integration/api-design.txt` - API design patterns +- `~/.claude/workflows/cli-templates/prompts/integration/database.txt` - Database schema design + ### 📂 File Pattern Wildcards ```bash diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index 34341954..f74c252c 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -152,7 +152,18 @@ All task files use this 10-field schema: "performance_considerations": "JWT validation will add approximately 5ms latency", "error_handling": "Ensure sensitive information is not leaked in error responses" }, - "analysis_source": "manual|gemini|codex|auto-detected" + "pre_analysis": [ + { + "action": "analyze patterns", + "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", + "method": "gemini" + }, + { + "action": "generate implementation", + "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt", + "method": "codex" + } + ] } } ``` @@ -221,7 +232,7 @@ The **implementation** field provides detailed code implementation guidance with - **performance_considerations**: Performance impact assessment - **error_handling**: Error handling requirements -#### analysis_source - Information Source Identifier +#### pre_analysis - Information Source Identifier - **manual**: Detailed information manually provided by user - **gemini**: Automatically obtained through Gemini CLI analysis - **codex**: Automatically obtained through Codex CLI analysis @@ -419,7 +430,7 @@ generate_todo_list_from_json .task/ 5. **Status Consistency**: Status values from defined enumeration 6. **Required Fields**: All 9 core fields must be present 7. **Implementation Structure**: implementation.files array must contain valid file paths -8. **Analysis Source**: analysis_source must be one of: manual|gemini|codex|auto-detected +8. **Pre-Analysis Source**: pre_analysis must be multi-step array format with action, template, method ### Session Consistency Checks ```bash