diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md index 40d71ca3..1513c50e 100644 --- a/.claude/agents/code-developer.md +++ b/.claude/agents/code-developer.md @@ -25,6 +25,8 @@ You are a code execution specialist focused on implementing high-quality, produc - **Context-driven** - Use provided context and existing code patterns - **Quality over speed** - Write boring, reliable code that works + + ## Execution Process ### 1. Context Assessment @@ -49,28 +51,9 @@ ELIF context insufficient OR task has flow control marker: → Extract patterns and conventions from accumulated context → Proceed with execution ``` +### Module Verification Guidelines -**Flow Control Execution System**: -- **[FLOW_CONTROL]**: Mandatory flow control execution flag -- **Sequential Processing**: Execute pre_analysis steps in order with context flow -- **Variable Accumulation**: Build comprehensive context through step chain -- **Error Handling**: Apply per-step error strategies (skip_optional, fail, retry_once, manual_intervention) - - **Trigger**: Auto-added when task.flow_control.pre_analysis exists (default format) - - **Action**: MUST run flow control steps first to gather comprehensive context - - **Purpose**: Ensures code aligns with existing patterns through comprehensive context accumulation - -**Flow Control Execution Standards**: -- **Sequential Step Processing**: Execute flow_control.pre_analysis steps in defined order -- **Context Variable Handling**: Process [variable_name] references in commands -- **四种上下文获取方式**: - - **文档引用**: `bash(cat 相关文档路径)` - 读取CLAUDE.md、依赖任务总结等 - - **搜索命令**: `bash(grep/rg/find等)` - 灵活搜索代码模式 - - **CLI分析**: `bash(gemini/codex分析命令)` - 深度分析理解 - - **自由探索**: Agent自主使用Read、Grep、Search等工具 -- **灵活性原则**: 根据任务需求灵活组合,步骤数量1-N自由决定 -- **Error Handling**: Apply on_error strategies per step (skip_optional, fail, retry_once, manual_intervention) -- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md - +**Rule**: Before referencing modules/components, use `rg` or search to verify existence first. **Test-Driven Development**: - Write tests first (red → green → refactor) @@ -113,7 +96,7 @@ ELIF context insufficient OR task has flow control marker: - Update TODO_LIST.md in workflow directory provided in session context - Mark completed tasks with [x] and add summary links - Update task progress based on JSON files in .task/ directory - - **CRITICAL**: Use session context paths provided by workflow:execute + - **CRITICAL**: Use session context paths provided by context **Session Context Usage**: - Always receive workflow directory path from agent prompt @@ -141,7 +124,7 @@ ELIF context insufficient OR task has flow control marker: ## Task Progress ▸ **IMPL-001**: Create auth module → [📋](./.task/IMPL-001.json) - - [x] **IMPL-001.1**: Database schema → [📋](./.task/IMPL-001.1.json) | [✅](./.summaries/IMPL-001.1.md) + - [x] **IMPL-001.1**: Database schema → [📋](./.task/IMPL-001.1.json) | [✅](./.summaries/IMPL-001.1-summary.md) - [ ] **IMPL-001.2**: API endpoints → [📋](./.task/IMPL-001.2.json) - [ ] **IMPL-002**: Add JWT validation → [📋](./.task/IMPL-002.json) @@ -220,13 +203,14 @@ ELIF context insufficient OR task has flow control marker: ## Quality Checklist Before completing any task, verify: +- [ ] **Module verification complete** - All referenced modules/packages exist (verified with rg/grep/search) - [ ] Code compiles/runs without errors - [ ] All tests pass - [ ] Follows project conventions - [ ] Clear naming and error handling - [ ] No unnecessary complexity - [ ] Minimal debug output (essential logging only) -- [ ] ASCII-only characters (no emojis/Unicode) +- [ ] ASCII-only characters (no emojis/Unicode) - [ ] GBK encoding compatible - [ ] TODO list updated - [ ] Comprehensive summary document generated with all new components/methods listed @@ -234,6 +218,7 @@ Before completing any task, verify: ## Key Reminders **NEVER:** +- Reference modules/packages without verifying existence first (use rg/grep/search) - Write code that doesn't compile/run - Add excessive debug output (verbose print(), console.log) - Use emojis or non-ASCII characters @@ -241,6 +226,7 @@ Before completing any task, verify: - Create unnecessary complexity **ALWAYS:** +- Verify module/package existence with rg/grep/search before referencing - Write working code incrementally - Test your implementation thoroughly - Minimize debug output - keep essential logging only diff --git a/.claude/agents/code-review-test-agent.md b/.claude/agents/code-review-test-agent.md index caf9178d..d15627bb 100644 --- a/.claude/agents/code-review-test-agent.md +++ b/.claude/agents/code-review-test-agent.md @@ -77,54 +77,6 @@ ELSE: → Proceed with review using standard quality checks ``` -## Flow Control Pre-Analysis Phase (Execute When Required) - -### Flow Control Execution -When [FLOW_CONTROL] flag is present, execute comprehensive pre-review analysis: - -Process each step from pre_analysis array sequentially: - -**多步上下文获取过程**: -1. 按顺序执行pre_analysis步骤: - - 文档引用:读取项目规范、依赖任务总结 - - 搜索命令:灵活搜索相关代码和模式 - - CLI分析:使用gemini/codex进行深度分析 - - 自由探索:使用Read、Grep等工具获取补充上下文 - -**灵活命令示例**: -```bash -# 读取依赖任务总结 -bash(cat .workflow/WFS-[session-id]/.summaries/IMPL-1.1-summary.md) - -# 搜索相关代码 -bash(rg "test|spec" src/ | head -20) - -# 深度分析 -bash(gemini-wrapper -p "分析代码质量和测试覆盖") -``` - -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 -- **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 -- **Code generation insights**: Autonomous development recommendations -- **System-wide impact**: Comprehensive integration analysis -- **Automated testing strategy**: Autonomous test implementation approach -- **Quality assurance**: Self-guided validation and optimization recommendations - -**Context Application for Review**: -- Review changes against repository-specific standards for similar code -- Compare implementation approach with established patterns for this type of feature -- Validate test coverage specifically for the functionality that was implemented -- Ensure integration points are properly handled based on repository practices - ## Review Process (Mode-Adaptive) ### Deep Mode Review Process @@ -173,11 +125,10 @@ if [FAST_MODE]: apply targeted review process - Input validation and sanitization ### Code Quality & Dependencies +- **Module import verification first** - Use `rg` to check all imports exist before other checks - Import/export correctness and path validation - Missing or unused imports identification - Circular dependency detection -- Single responsibility principle -- Clear variable and function names ### Performance - Algorithm complexity (time and space) @@ -230,7 +181,7 @@ if [FAST_MODE]: apply targeted review process 2. **Update TODO_LIST.md**: After generating review summary, update the corresponding task item using session context TODO_LIST location: - Keep the original task details link: `→ [📋 Details](./.task/[Task-ID].json)` - - Add review summary link after pipe separator: `| [✅ Review](./.summaries/[Task-ID]-review.md)` + - Add review summary link after pipe separator: `| [✅ Review](./.summaries/IMPL-[Task-ID]-summary.md)` - Mark the checkbox as completed: `- [x]` - Update progress percentages in the progress overview section @@ -240,9 +191,9 @@ if [FAST_MODE]: apply targeted review process - Update last modified timestamp 4. **Review Summary Document Naming Convention**: - - Implementation Task Reviews: `IMPL-001-review.md` - - Subtask Reviews: `IMPL-001.1-review.md` - - Detailed Subtask Reviews: `IMPL-001.1.1-review.md` + - Implementation Task Reviews: `IMPL-001-summary.md` + - Subtask Reviews: `IMPL-001.1-summary.md` + - Detailed Subtask Reviews: `IMPL-001.1.1-summary.md` ## Output Format diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 656a8e54..238fb5a6 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -28,6 +28,40 @@ examples: ## Core Rules +### Dependency Context Resolution (CRITICAL) +⚠️ **For tasks with dependencies or documentation associations**: MUST include bash content retrieval as first step in flow_control.pre_analysis + +**Required Pattern**: +```json +"flow_control": { + "pre_analysis": [ + { + "step": "load_dependencies", + "action": "Retrieve dependency task summaries", + "command": "bash(cat .workflow/WFS-[session]/.summaries/IMPL-[dependency_id]-summary.md 2>/dev/null || echo 'dependency summary not found')", + "output_to": "dependency_context" + }, + { + "step": "load_documentation", + "action": "Retrieve project documentation", + "command": "bash(cat CLAUDE.md README.md 2>/dev/null || echo 'documentation not found')", + "output_to": "doc_context" + } + ] +} +``` + +**Trigger Conditions**: +- Task has `context.depends_on` array with task IDs +- Task references external documentation files +- Task builds upon previous implementation summaries +- Task requires configuration or schema files + +**Content Sources**: +- Task summaries: `.workflow/WFS-[session]/.summaries/IMPL-[task-id]-summary.md` (主任务) / `IMPL-[task-id].[subtask-id]-summary.md` (子任务) +- Documentation: `CLAUDE.md`, `README.md`, config files +- Schema definitions: `.json`, `.yaml`, `.sql` files +- Dependency contexts: `.workflow/WFS-[session]/.task/IMPL-*.json` ### File Structure Reference **Architecture**: @~/.claude/workflows/workflow-architecture.md @@ -62,17 +96,12 @@ examples: - **Session isolation**: Each session maintains independent context and state ### Project Structure Analysis & Engineering Enhancement -**Process**: Context → Analyze → Implement (Simple: CLI direct | Complex: Task + CLI hybrid) -**Tool Priority**: Task(complex) > CLI(simple) > Hybrid(mixed complexity) - -**Always First**: Run project hierarchy analysis before planning -```bash -# Get project structure with depth analysis -~/.claude/scripts/get_modules_by_depth.sh - -# Results populate task paths automatically -# Used for focus_paths and target_files generation -``` +**⚠️ CRITICAL PRE-PLANNING STEP**: Must complete comprehensive project analysis before any task planning begins +**Analysis Process**: Context Gathering → Codebase Exploration → Pattern Recognition → Implementation Strategy +**Tool Selection Protocol**: +- **Simple patterns** (≤3 modules): Use `~/.claude/scripts/gemini-wrapper` or `codex --full-auto exec` +- **Complex analysis** (>3 modules): Launch Task agents with integrated CLI tool access +**Tool Priority**: Task(complex) > Direct CLI(simple) > Hybrid(mixed complexity) **Core Principles**: - **Complexity-Driven Selection**: Simple patterns use direct CLI, complex analysis uses Task agents with CLI integration @@ -99,6 +128,9 @@ examples: ## Output Documents +### Document Workflow +**Identifier Creation** → **Folder Structure Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md** + ### Always Created - **IMPL_PLAN.md**: Requirements, task breakdown, success criteria - **Session state**: Task references and paths @@ -148,53 +180,10 @@ Documents created for `/workflow:execute`: - **File not found**: Clear suggestions - **>10 tasks**: Force re-scoping into iterations - -### Detailed Context Gathering Commands - -#### Gemini Analysis Templates -```bash -# Module pattern analysis -cd [module] && ~/.claude/scripts/gemini-wrapper -p "Analyze patterns, conventions, and file organization in this module" - -# Architectural analysis -cd [module] && ~/.claude/scripts/gemini-wrapper -p "Analyze [scope] architecture, relationships, and integration points" - -# Cross-module dependencies -~/.claude/scripts/gemini-wrapper -p "@{src/**/*} @{CLAUDE.md} analyze module relationships and dependencies" - - -#### Codex Analysis Templates -```bash -# Architectural analysis -codex --full-auto exec "analyze [scope] architecture and identify optimization opportunities" -s danger-full-access - -# Pattern-based development -codex --full-auto exec "analyze existing patterns for [feature] implementation with concrete examples" -s danger-full-access - -# Project understanding -codex --full-auto exec "analyze project structure, conventions, and development requirements" -s danger-full-access -``` - ### Context Accumulation & Inheritance **Context Flow Process**: -1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy +1. **Structure Analysis**: project hierarchy 2. **Pattern Analysis**: Tool-specific commands → existing patterns 3. **Dependency Mapping**: Previous task summaries → inheritance context 4. **Task Context Generation**: Combined analysis → task.context fields -**Context Inheritance Rules**: -- **Parent → Child**: Container tasks pass context to subtasks via `context.inherited` -- **Dependency → Dependent**: Previous task summaries loaded via `context.depends_on` -- **Session → Task**: Global session context included in all tasks -- **Module → Feature**: Module patterns inform feature implementation context - -### Variable System & Path Rules -**Flow Control Variables**: Use `[variable_name]` format (see workflow-architecture.md) -- **Step outputs**: `[dependency_context]`, `[pattern_analysis]` -- **Task properties**: `[depends_on]`, `[focus_paths]`, `[parent]` -- **Commands**: Wrapped in `bash()` with error handling strategies - -**Focus Paths**: Concrete paths only (no wildcards) -- Use `get_modules_by_depth.sh` results for actual directory names -- Include both directories and specific files from requirements -- Format: `["src/auth", "tests/auth", "config/auth.json"]` \ No newline at end of file diff --git a/.claude/workflows/intelligent-tools-strategy.md b/.claude/workflows/intelligent-tools-strategy.md index faf6530d..fd77c4fa 100644 --- a/.claude/workflows/intelligent-tools-strategy.md +++ b/.claude/workflows/intelligent-tools-strategy.md @@ -6,83 +6,188 @@ type: strategic-guideline # Intelligent Tools Selection Strategy -## ⚡ Core Decision Framework +## ⚡ Core Framework -**Gemini**: Analysis & understanding large codebases -**Codex**: Development & autonomous implementation +**Gemini**: Analysis, understanding, exploration & documentation +**Codex**: Development, implementation & automation -> **Implementation Details**: See @~/.claude/workflows/tools-implementation-guide.md +### Decision Principles +- **Use tools early and often** - Tools are faster, more thorough, and reliable than manual approaches +- **When in doubt, use both** - Parallel usage provides comprehensive coverage +- **Default to tools** - Use specialized tools for most coding tasks, no matter how small +- **Lower barriers** - Engage tools immediately when encountering any complexity -## 🎯 Tool Selection Matrix +### Quick Decision Rules +1. **Exploring/Understanding?** → Start with Gemini +2. **Building/Fixing?** → Start with Codex +3. **Not sure?** → Use both in parallel +4. **Small task?** → Still use tools - they're faster than manual work -### When to Use Gemini -- **Command**: `~/.claude/scripts/gemini-wrapper -p "prompt"` -- **Strengths**: Large context window, pattern recognition across modules -- **Best For**: - - Project architecture analysis (>50 files) - - Cross-module pattern detection - - Coding convention analysis - - Refactoring with broad dependencies - - Large codebase understanding +## 🎯 Tool Specifications -### When to Use Codex -- **Command**: `codex --full-auto exec "prompt" -s danger-full-access` -- **Strengths**: Mathematical reasoning, autonomous development -- **Best For**: - - Complex algorithm analysis - - Security vulnerability assessment - - Performance optimization - - Database schema design - - API protocol specifications - - Autonomous feature development +### Gemini (Analysis & Understanding) +**Command**: `~/.claude/scripts/gemini-wrapper -p "PURPOSE: [analysis goal] | TASK: [what to do] | EXPECTED: [expected results]"` -## 📊 Decision Framework +**Strengths**: Large context window, pattern recognition across modules -| Analysis Need | Recommended Tool | Rationale | -|--------------|------------------|-----------| -| Project Architecture | Gemini | Needs broad context across many files | -| Algorithm Optimization | Codex | Requires deep mathematical reasoning | -| Security Analysis | Codex | Leverages deeper security knowledge | -| Code Patterns | Gemini | Pattern recognition across modules | -| Refactoring | Gemini | Needs understanding of all dependencies | -| API Design | Codex | Technical specification expertise | -| Test Coverage | Gemini | Cross-module test understanding | -| Performance Tuning | Codex | Mathematical optimization capabilities | -| Feature Implementation | Codex | Autonomous development capabilities | -| Architectural Review | Gemini | Large context analysis | +**Use Cases**: +- Any project analysis (≥5 files) +- Quick code exploration and familiarization +- Cross-module pattern detection and consistency checks +- Coding convention analysis and standardization +- Refactoring planning with dependency mapping +- Legacy code understanding and modernization paths +- API surface analysis and integration points +- Test coverage gaps and quality assessment +- Configuration file analysis and optimization +- Dependency audit and relationship mapping +- Code review preparation and checklist generation +- Documentation generation from existing code -## 🔄 Parallel Analysis Strategy +### Codex (Development & Implementation) +**Command**: `codex --full-auto exec "PURPOSE: [development goal] | TASK: [what to implement] | EXPECTED: [expected code/features]" -s danger-full-access` +**Strengths**: Mathematical reasoning, autonomous development + +**Use Cases**: +- Any feature development (simple to complex) +- Quick prototyping and proof-of-concepts +- Bug fixes and issue resolution +- Test generation and validation +- Code scaffolding and boilerplate creation +- Configuration setup and environment preparation +- Algorithm implementation and optimization +- Security vulnerability assessment and fixes +- Performance optimization and profiling +- Database schema design and migration +- API development and integration +- DevOps automation and deployment scripts +- Documentation automation and generation +- Code modernization and refactoring execution +- Dependency management and updates +- Build system optimization and tooling + +### Structured Prompt Templates +```bash +# Gemini Analysis +~/.claude/scripts/gemini-wrapper -p " +PURPOSE: [clear analysis goal] +TASK: [specific analysis task] +EXPECTED: [expected output] +" + +# Codex Development +codex --full-auto exec " +PURPOSE: [clear development goal] +TASK: [specific development task] +EXPECTED: [expected deliverables] +" -s danger-full-access +``` + +**Prompt Checklist**: +- [ ] **PURPOSE** - Clear goal and intent +- [ ] **TASK** - Specific execution task +- [ ] **EXPECTED** - Clear expected results + +## 📊 Decision Matrix + +| Task Category | Tool | Rationale | Frequency | +|--------------|------|-----------|-----------| +| **Understanding & Analysis** | +| Project Architecture | Gemini | Broad context across files | Weekly/Monthly | +| Code Exploration | Gemini | Quick module familiarization | Daily | +| Legacy Code Analysis | Gemini | Pattern recognition across systems | As needed | +| Dependency Mapping | Gemini | Cross-module relationship analysis | Sprint planning | +| Code Review Prep | Gemini | Comprehensive context understanding | Before reviews | +| **Development & Implementation** | +| Feature Development | Codex | Autonomous implementation capabilities | Daily | +| Bug Fixes | Codex | Targeted problem resolution | As issues arise | +| Prototyping | Codex | Rapid development and iteration | Weekly | +| Test Generation | Codex | Automated test creation | After feature work | +| Configuration Setup | Codex | Environment and tooling setup | Project setup | +| **Optimization & Maintenance** | +| Algorithm Optimization | Codex | Mathematical reasoning capabilities | Performance sprints | +| Security Analysis | Codex | Security knowledge and fixes | Security reviews | +| Performance Tuning | Codex | Mathematical optimization | Performance reviews | +| Code Modernization | Both | Gemini for planning, Codex for execution | Quarterly | +| **Documentation & Quality** | +| Documentation Generation | Both | Gemini for analysis, Codex for automation | Continuous | +| Coding Standards | Gemini | Pattern recognition and consistency | Code reviews | +| Test Coverage Analysis | Gemini | Cross-module test understanding | Sprint retrospectives | + +## 📋 Workflow Integration + +### Mandatory Planning Process +When planning any coding task, **ALWAYS** integrate CLI tools: + +#### 1. Understanding Phase (Required) +- **Gemini Analysis**: Understand existing patterns, architecture, dependencies +- **Context Discovery**: Map related modules and integration points +- **Pattern Recognition**: Identify existing conventions and standards + +#### 2. Development Strategy +- **Understanding/Analysis**: Gemini (primary), Codex (occasional) +- **Implementation**: Codex (occasional), manual development (primary) +- **Complex Tasks**: Both tools in sequence + +#### 3. Workflow Pattern +``` +Planning → Gemini Analysis → Manual Development → Codex Assistance (as needed) +``` + +### Tool Usage Guidelines + +#### Gemini (Primary for Understanding) +- Always use for initial codebase analysis +- Pattern discovery and convention mapping +- Architecture understanding before implementation +- Dependency analysis and impact assessment +- Code review preparation + +#### Codex (Occasional for Development) +- Selective use for complex algorithms +- Prototype generation for proof-of-concepts +- Boilerplate creation when patterns are clear +- Test generation and validation +- Performance optimization tasks + +### Planning Checklist +For every development task: +- [ ] **Gemini analysis** completed for understanding +- [ ] **Existing patterns** identified and documented +- [ ] **Dependencies mapped** and integration points clear +- [ ] **CLI tool usage points** identified in workflow +- [ ] **Manual development approach** defined +- [ ] **Codex assistance triggers** identified (if applicable) + +## 🚀 Usage Patterns + +### Immediate Engagement Triggers +- **New codebase**: Use Gemini to understand structure before changes +- **Bug reports**: Use Codex to investigate and propose fixes +- **Feature requests**: Use Codex for rapid prototyping and implementation +- **Code reviews**: Use Gemini to prepare comprehensive analysis +- **Refactoring needs**: Use Gemini for impact analysis, Codex for execution + +### Daily Integration Points +- **Morning standup prep**: Gemini for codebase overview +- **Sprint planning**: Both tools for effort estimation +- **Development tasks**: Codex for implementation +- **Testing**: Codex for test generation and coverage +- **Documentation**: Both tools for comprehensive docs + +### Parallel Strategy For complex projects requiring both broad context and deep analysis: - **Gemini** for architectural understanding - **Codex** for focused development tasks - Run both via Task agents when comprehensive coverage needed -## 📈 Complexity-Based Selection +### Frequency Guidelines +- **Daily**: Use tools for routine development tasks +- **Immediate**: Engage tools at first sign of complexity +- **Continuous**: Integrate tools into regular workflow +- **Proactive**: Don't wait for problems - use tools preventively -### Simple Projects (≤50 files) -- **Content-driven choice**: Mathematical → Codex, Structural → Gemini +## 🔗 Reference -### Medium Projects (50-200 files) -- **Gemini first** for overview and patterns -- **Codex second** for specific implementations - -### Large Projects (>200 files) -- **Parallel analysis** with both tools -- **Gemini** for architectural understanding -- **Codex** for focused development tasks - -## 🎯 Strategic Guidelines - -1. **Task-driven selection**: Let project characteristics drive tool choice -2. **Start simple**: Begin with single tool, escalate to parallel if needed -3. **Context first**: Understand scope before selecting approach -4. **Trust autonomous capabilities**: Let tools handle their specialized domains - -## 🔗 Implementation Details - -**Complete syntax and usage patterns**: @~/.claude/workflows/tools-implementation-guide.md - ---- - -**Decision Principle**: Choose based on task nature - Gemini excels at understanding, Codex excels at building. \ No newline at end of file +**Complete syntax and usage patterns**: @~/.claude/workflows/tools-implementation-guide.md \ No newline at end of file diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index 4ad92623..348f12fa 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -126,19 +126,31 @@ All task files use this unified 5-field schema: { "step": "check_patterns", "action": "Analyze existing patterns", - "command": "bash(rg 'auth' src/ | head -10)", - "output_to": "auth_patterns" + "command": "bash(rg 'auth' [focus_paths] | head -10)", + "output_to": "patterns" + }, + { + "step": "analyze_architecture", + "action": "Review system architecture", + "command": "~/.claude/scripts/gemini-wrapper -p \"analyze patterns: [patterns]\"", + "output_to": "design" + }, + { + "step": "check_deps", + "action": "Check dependencies", + "command": "bash(echo [depends_on] | xargs cat)", + "output_to": "context" } ], "implementation_approach": { - "task_description": "Implement JWT authentication following existing patterns", + "task_description": "Implement JWT authentication following [design]", "modification_points": [ - "Add JWT generation in login handler", - "Implement token validation middleware" + "Add JWT generation using [parent] patterns", + "Implement validation middleware from [context]" ], "logic_flow": [ - "User login → validate → generate JWT → return token", - "Protected route → extract JWT → validate → allow/deny" + "User login → validate with [inherited] → generate JWT", + "Protected route → extract JWT → validate using [shared] rules" ] }, "target_files": [ @@ -162,7 +174,7 @@ The **focus_paths** field specifies concrete project paths for task implementati The **flow_control** field manages task execution with two main components: **pre_analysis** - Context gathering phase: -- **Flexible commands**: Supports bash pipelines, CLI tools, and agent calls +- **Flexible commands**: Supports multiple tool types (see Tool Reference below) - **Step structure**: Each step has `step`, `action`, `command` fields - **Variable accumulation**: Steps can reference previous outputs via `[variable_name]` - **Error handling**: `skip_optional`, `fail`, `retry_once`, `manual_intervention` @@ -173,13 +185,39 @@ The **flow_control** field manages task execution with two main components: - **logic_flow**: Business logic execution sequence - **target_files**: Target file list in `file:function:lines` format +#### Tool Reference +**Command Types Available**: +- **Gemini CLI**: `~/.claude/scripts/gemini-wrapper -p "prompt"` +- **Codex CLI**: `codex --full-auto exec "task" -s danger-full-access` +- **Built-in Tools**: `grep(pattern)`, `glob(pattern)`, `search(query)` +- **Bash Commands**: `bash(rg 'pattern' src/)`, `bash(find . -name "*.ts")` + +#### Variable System & Context Flow +**Flow Control Variables**: Use `[variable_name]` format for dynamic content: +- **Step outputs**: `[step_output_name]` - Reference any pre_analysis step output +- **Task properties**: `[task_property]` - Reference any task context field +- **Previous results**: `[analysis_result]` - Reference accumulated context +- **Commands**: All commands wrapped with appropriate error handling + +**Context Accumulation Process**: +1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy +2. **Pattern Analysis**: Tool-specific commands → existing patterns +3. **Dependency Mapping**: Previous task summaries → inheritance context +4. **Task Context Generation**: Combined analysis → task.context fields + +**Context Inheritance Rules**: +- **Parent → Child**: Container tasks pass context via `context.inherited` +- **Dependency → Dependent**: Previous task summaries via `context.depends_on` +- **Session → Task**: Global session context included in all tasks +- **Module → Feature**: Module patterns inform feature implementation + ### Task Validation Rules 1. **ID Uniqueness**: All task IDs must be unique 2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels) 3. **Parent References**: All parent IDs must exist as JSON files 4. **Status Consistency**: Status values from defined enumeration 5. **Required Fields**: All 5 core fields must be present -6. **Focus Paths Structure**: context.focus_paths must contain valid project paths +6. **Focus Paths Structure**: context.focus_paths must contain concrete paths (no wildcards) 7. **Flow Control Format**: pre_analysis must be array with required fields 8. **Dependency Integrity**: All depends_on task IDs must exist as JSON files @@ -199,8 +237,8 @@ All workflows use the same file structure definition regardless of complexity. * ├── IMPL_PLAN.md # Planning document (REQUIRED) ├── TODO_LIST.md # Progress tracking (REQUIRED) ├── [.summaries/] # Task completion summaries (created when tasks complete) -│ ├── IMPL-*.md # Main task summaries -│ └── IMPL-*.*.md # Subtask summaries +│ ├── IMPL-*-summary.md # Main task summaries +│ └── IMPL-*.*-summary.md # Subtask summaries └── .task/ # Task definitions (REQUIRED) ├── IMPL-*.json # Main task definitions └── IMPL-*.*.json # Subtask definitions (created dynamically) @@ -242,9 +280,9 @@ All workflows use the same file structure definition regardless of complexity. * ## Task Progress ▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json) - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json) - - [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2.md) + - [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md) -- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002.md) +- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md) ## Status Legend - `▸` = Container task (has subtasks) @@ -314,22 +352,25 @@ fi | **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination | | **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration | -### Workflow Characteristics +### Workflow Characteristics & Tool Guidance #### Simple Workflows - **Examples**: Bug fixes, small feature additions, configuration changes - **Task Decomposition**: Usually single-level tasks, minimal breakdown needed - **Agent Coordination**: Direct execution without complex orchestration +- **Tool Strategy**: `bash()` commands, `grep()` for pattern matching #### Medium Workflows - **Examples**: New features, API endpoints with integration, database schema changes - **Task Decomposition**: Two-level hierarchy when decomposition is needed - **Agent Coordination**: Context coordination between related tasks +- **Tool Strategy**: `gemini-wrapper` for pattern analysis, `codex --full-auto` for implementation #### Complex Workflows - **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments - **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation - **Agent Coordination**: Multi-agent orchestration with deep context analysis +- **Tool Strategy**: `gemini-wrapper` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis ### Assessment & Upgrades - **During Creation**: System evaluates requirements and assigns complexity diff --git a/CLAUDE.md b/CLAUDE.md index 341cc56c..0efa2abf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,22 +5,9 @@ This document defines project-specific coding standards and development principles. ### CLI Tool Context Protocols For all CLI tool usage, command syntax, and integration guidelines: -- **Tool Selection Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md +- **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md - **Implementation Guide**: @~/.claude/workflows/tools-implementation-guide.md -### Intelligent Context Acquisition - -**Core Rule**: No task execution without sufficient context. Must gather project understanding before implementation. - -**Context Tools**: -- **Structure**: Bash(~/.claude/scripts/get_modules_by_depth.sh) for project hierarchy -- **Module Analysis**: Bash(cd [module] && ~/.claude/scripts/gemini-wrapper -p "analyze patterns") -- **Full Analysis**: - -Bash(cd [module] && ~/.claude/scripts/gemini-wrapper -p "analyze [scope] architecture") - -Bash(codex --full-auto exec "analyze [scope] architecture" -s danger-full-access) - **Context Requirements**: - Identify 3+ existing similar patterns before implementation - Map dependencies and integration points