From 2fa9d4251e16f280f1d9260d86ed0287200c328a Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 29 Sep 2025 23:56:59 +0800 Subject: [PATCH] feat(workflow): enhance planning command documentation and execution lifecycle --- .claude/commands/workflow/plan.md | 138 ++++++++++++------ .../workflow/tools/concept-enhanced.md | 48 +++--- .../workflows/intelligent-tools-strategy.md | 12 +- 3 files changed, 123 insertions(+), 75 deletions(-) diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index c4af2855..98f29952 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -12,9 +12,9 @@ examples: # Workflow Plan Command (/workflow:plan) ## Overview -Creates implementation plans by orchestrating intelligent context gathering and analysis modules. +Creates comprehensive implementation plans by orchestrating intelligent context gathering and analysis modules. Integrates with workflow session management, brainstorming artifacts, and automated task generation. -## Core Principles +## Core Planning Principles ### Task Decomposition Standards @@ -26,13 +26,13 @@ Creates implementation plans by orchestrating intelligent context gathering and - **Dependency Blocking**: Subsequent tasks must wait for prerequisite task completion - **Parallel Execution**: Independent features that can be developed simultaneously by different developers -**Rules**: +**Task Limits & Structure**: - **Maximum 10 tasks**: Hard limit - exceeding requires re-scoping - **Function-based**: Complete functional units with related files (logic + UI + tests + config) - **File cohesion**: Group tightly coupled components in same task - **Hierarchy**: Flat (≤5 tasks) | Two-level (6-10 tasks) | Re-scope (>10 tasks) -**Task Patterns**: +**Task Pattern Examples**: - ✅ **Correct (Function-based)**: `IMPL-001: User authentication system` (models + routes + components + middleware + tests) - ❌ **Wrong (File/step-based)**: `IMPL-001: Create database model`, `IMPL-002: Create API endpoint` @@ -54,9 +54,12 @@ Creates implementation plans by orchestrating intelligent context gathering and 5. **Build Enhanced Flow Control**: Define pre_analysis steps with artifact loading and implementation approach 6. **Create Artifact-Aware JSON Files**: Generate individual .task/IMPL-*.json files with enhanced schema -### Session Management ⚠️ CRITICAL -- **Command**: Uses `/workflow:session:start` command for intelligent session discovery and creation -- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before any planning +## Critical Process Requirements + +### Session Management ⚠️ CRITICAL FIRST STEP +- **⚡ FIRST ACTION**: Execute `SlashCommand(command="/workflow:session:start")` for intelligent session discovery +- **Command Integration**: Uses `/workflow:session:start` command for intelligent session discovery and creation +- **Active Session Check**: Check for all `.workflow/.active-*` markers before any planning - **Relevance Analysis**: Automatically analyzes task relevance with existing sessions - **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists or task is unrelated - **Session continuity**: MUST use selected active session to maintain context @@ -65,7 +68,7 @@ Creates implementation plans by orchestrating intelligent context gathering and ### Session ID Transmission Guidelines ⚠️ CRITICAL - **Format**: `WFS-[topic-slug]` from active session markers -- **Usage**: `/workflow:tools:context-gather --session WFS-[id]` and `/workflow:tools:plan-enchanced --session WFS-[id]` +- **Usage**: `SlashCommand(command="/workflow:tools:context-gather --session WFS-[id]")` and `SlashCommand(command="/workflow:tools:plan-enchanced --session WFS-[id]")` - **Rule**: ALL modular commands MUST receive current session ID for context continuity ### Brainstorming Artifacts Integration ⚠️ NEW FEATURE @@ -74,60 +77,99 @@ Creates implementation plans by orchestrating intelligent context gathering and - **Artifact References**: Create structured references to design documents and specifications - **Context Enhancement**: Load artifacts in pre_analysis steps to provide complete design context +## Planning Execution Lifecycle -## Execution Lifecycle +### Phase 1: Session Management & Discovery ⚠️ TodoWrite Control +1. **TodoWrite Initialization**: Initialize flow control, mark first phase as `in_progress` +2. **Session Discovery**: Execute `SlashCommand(command="/workflow:session:start [task-description]")` +3. **Relevance Analysis**: Automatically analyze task relevance with existing sessions +4. **Session Selection**: Auto-select or create session based on relevance analysis +5. **Context Preparation**: Load session state and prepare for planning +6. **TodoWrite Update**: Mark phase 1 as `completed`, phase 2 as `in_progress` -### Phase 1: Session Management -1. **Session Discovery**: Use `/workflow:session:start` command for intelligent session discovery -2. **Relevance Analysis**: Automatically analyze task relevance with existing sessions -3. **Session Selection**: Auto-select or create session based on relevance analysis -4. **Context Preparation**: Load session state and prepare for planning - -### Phase 2: Context Gathering -1. **Context Collection**: Execute `/workflow:tools:context-gather` with task description and session ID +### Phase 2: Context Gathering & Asset Discovery ⚠️ TodoWrite Control +1. **Context Collection**: Execute `SlashCommand(command="/workflow:tools:context-gather --session WFS-[id] \"task description\"")` 2. **Asset Discovery**: Gather relevant documentation, code, and configuration files 3. **Context Packaging**: Generate standardized context-package.json -4. **Validation**: Ensure context package contains sufficient information +4. **Validation**: Ensure context package contains sufficient information for analysis +5. **TodoWrite Update**: Mark phase 2 as `completed`, phase 3 as `in_progress` -### Phase 3: Intelligent Analysis -1. **Analysis Execution**: Run `/workflow:tools:plan-enchanced` with context package and session ID +### Phase 3: Intelligent Analysis & Tool Orchestration ⚠️ TodoWrite Control +1. **Analysis Execution**: Execute `SlashCommand(command="/workflow:tools:plan-enchanced --session WFS-[id] --context path/to/context-package.json")` 2. **Tool Selection**: Automatically select optimal analysis tools (Gemini/Qwen/Codex) -3. **Result Generation**: Produce structured ANALYSIS_RESULTS.md +3. **Result Generation**: Produce structured ANALYSIS_RESULTS.md with task recommendations 4. **Validation**: Verify analysis completeness and task recommendations +5. **TodoWrite Update**: Mark phase 3 as `completed`, phase 4 as `in_progress` -### Phase 4: Plan Assembly & Document Generation +### Phase 4: Plan Assembly & Artifact Integration ⚠️ TodoWrite Control 1. **Artifact Detection**: Scan session for brainstorming outputs (.brainstorming/ directory) 2. **Plan Generation**: Create IMPL_PLAN.md from analysis results and artifacts 3. **Enhanced Task JSON Creation**: Generate task JSON files with artifacts integration 4. **TODO List Creation**: Generate TODO_LIST.md with artifact references 5. **Session Update**: Mark session as ready for execution with artifact context +6. **TodoWrite Completion Validation**: Ensure all phases are marked as `completed` for complete execution -## TodoWrite Progress Tracking -**Comprehensive planning tracking** with real-time status updates throughout entire planning lifecycle: +## TodoWrite Progress Tracking ⚠️ CRITICAL FLOW CONTROL -### TodoWrite Planning Rules -1. **Initial Creation**: Generate TodoWrite from planning phases -2. **Single In-Progress**: Mark ONLY ONE phase as `in_progress` at a time -3. **Immediate Updates**: Update status after each phase completion -4. **Continuous Tracking**: Maintain TodoWrite throughout entire planning workflow +**TodoWrite Control Ensures Complete Workflow Execution** - Guarantees planning lifecycle integrity through real-time status tracking: + +### TodoWrite Flow Control Rules ⚠️ MANDATORY +1. **Process Integrity Guarantee**: TodoWrite is the key control mechanism ensuring all planning phases execute in sequence +2. **Phase Gating**: Must wait for previous phase `completed` before starting next phase +3. **SlashCommand Synchronization**: Update TodoWrite status before and after each SlashCommand execution +4. **Error Recovery**: If phase fails, TodoWrite maintains `in_progress` status until issue resolved +5. **Process Validation**: Verify all required phases completed through TodoWrite + +### TodoWrite Execution Control Rules +1. **Initial Creation**: Generate TodoWrite task list from planning phases +2. **Single Execution**: Only one task can be `in_progress` at any time +3. **Immediate Updates**: Update status to `completed` immediately after each phase completion +4. **Continuous Tracking**: Maintain TodoWrite state throughout entire planning workflow +5. **Integrity Validation**: Final verification that all tasks are `completed` status ### TodoWrite Tool Usage -**Core Rule**: Monitor slash command completion before proceeding to next step +**Core Control Rule**: Monitor SlashCommand completion status to ensure sequential execution ```javascript -// Initialize planning workflow tracking +// Flow Control Example: Ensure Complete Execution of All Planning Phases +// Step 1: Initialize Flow Control TodoWrite({ todos: [ - {"content": "Initialize session management", "status": "pending", "activeForm": "Initializing session management"}, + {"content": "Initialize session management and discovery", "status": "in_progress", "activeForm": "Initializing session management and discovery"}, {"content": "Detect and analyze brainstorming artifacts", "status": "pending", "activeForm": "Detecting and analyzing brainstorming artifacts"}, - {"content": "Gather intelligent context", "status": "pending", "activeForm": "Gathering intelligent context"}, - {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"}, + {"content": "Gather intelligent context and assets", "status": "pending", "activeForm": "Gathering intelligent context and assets"}, + {"content": "Execute intelligent analysis and tool orchestration", "status": "pending", "activeForm": "Executing intelligent analysis and tool orchestration"}, {"content": "Generate artifact-enhanced implementation plan and tasks", "status": "pending", "activeForm": "Generating artifact-enhanced implementation plan and tasks"} ] }) + +// Step 2: Execute SlashCommand and Update Status Immediately +SlashCommand(command="/workflow:session:start task-description") +// After command completion: +TodoWrite({ + todos: [ + {"content": "Initialize session management and discovery", "status": "completed", "activeForm": "Initializing session management and discovery"}, + {"content": "Detect and analyze brainstorming artifacts", "status": "in_progress", "activeForm": "Detecting and analyzing brainstorming artifacts"}, + {"content": "Gather intelligent context and assets", "status": "pending", "activeForm": "Gathering intelligent context and assets"}, + {"content": "Execute intelligent analysis and tool orchestration", "status": "pending", "activeForm": "Executing intelligent analysis and tool orchestration"}, + {"content": "Generate artifact-enhanced implementation plan and tasks", "status": "pending", "activeForm": "Generating artifact-enhanced implementation plan and tasks"} + ] +}) + +// Step 3: Continue Next SlashCommand +SlashCommand(command="/workflow:tools:context-gather --session WFS-[id] \"task description\"") +// Repeat this pattern until all phases completed ``` +### Flow Control Validation Checkpoints +- ✅ **Phase Completion Verification**: Check return status after each SlashCommand execution +- ✅ **Dependency Checking**: Ensure prerequisite phases completed before starting next phase +- ✅ **Error Handling**: If command fails, remain in current phase until issue resolved +- ✅ **Final Validation**: All todos status must be `completed` for planning completion + + +## Output Document Structures ### IMPL_PLAN.md Structure ⚠️ REQUIRED FORMAT @@ -156,8 +198,7 @@ TodoWrite({ - **Resource Requirements** - Required resources and tool selection - **Success Criteria** - Success criteria and acceptance conditions - -## Reference Information +## Technical Reference ### Enhanced Task JSON Schema (5-Field + Artifacts) Each task.json uses the workflow-architecture.md 5-field schema enhanced with artifacts: @@ -313,16 +354,16 @@ The following pre_analysis steps are generated for agent execution: } ``` -## Artifact Detection & Integration ⚠️ ENHANCED FEATURE +## Advanced Features + +### Artifact Detection & Integration ⚠️ ENHANCED FEATURE -### Artifact Detection Logic **Automatic Brainstorming Artifact Scanning**: 1. **Session Scan**: Check `.workflow/WFS-[session]/.brainstorming/` directory 2. **Role Detection**: Identify completed role analyses (ui-designer, system-architect, etc.) 3. **Artifact Mapping**: Map artifacts to relevant task types 4. **Relevance Scoring**: Assign relevance scores based on task-artifact alignment -### Role-Task Mapping Rules **Artifact-Task Relevance Matrix**: - **ui-designer** → UI/Frontend/Component tasks (high relevance) - **system-architect** → Architecture/Backend/Database tasks (high relevance) @@ -331,7 +372,6 @@ The following pre_analysis steps are generated for agent execution: - **product-manager** → Feature/Business Logic tasks (medium relevance) - **topic-framework.md** → All tasks (low-medium relevance for context) -### Enhanced Task Generation **Artifact-Enhanced Task Creation Process**: 1. **Standard Task Generation**: Create base task from analysis results 2. **Artifact Detection**: Scan for relevant brainstorming outputs @@ -339,8 +379,7 @@ The following pre_analysis steps are generated for agent execution: 4. **Pre-Analysis Enhancement**: Insert artifact loading steps 5. **Implementation Update**: Reference artifacts in task description and approach -### Artifact Loading in Pre-Analysis -**Automatic Artifact Integration**: +**Automatic Artifact Integration Example**: ```json { "step": "load_brainstorming_artifacts", @@ -354,11 +393,16 @@ The following pre_analysis steps are generated for agent execution: } ``` -### File Structure Reference -**Architecture**: @~/.claude/workflows/workflow-architecture.md +### Integration & Output -### Execution Integration -Documents created for `/workflow:execute`: +**Architecture Reference**: `@~/.claude/workflows/workflow-architecture.md` + +**Documents Created for `/workflow:execute`**: - **IMPL_PLAN.md**: Context loading and requirements with artifact references - **.task/*.json**: Agent implementation context with enhanced artifact loading -- **TODO_LIST.md**: Status tracking (container tasks with ▸, leaf tasks with checkboxes) \ No newline at end of file +- **TODO_LIST.md**: Status tracking (container tasks with ▸, leaf tasks with checkboxes) + +**Command Chain Integration**: +1. `/workflow:plan` → Creates implementation plan with task breakdown +2. `/workflow:execute` → Executes tasks using generated plan and context +3. Task management system → Tracks progress and dependencies \ No newline at end of file diff --git a/.claude/commands/workflow/tools/concept-enhanced.md b/.claude/commands/workflow/tools/concept-enhanced.md index 27556966..6a736cd9 100644 --- a/.claude/commands/workflow/tools/concept-enhanced.md +++ b/.claude/commands/workflow/tools/concept-enhanced.md @@ -113,35 +113,39 @@ Advanced intelligent planning engine with parallel CLI execution that processes ### Phase 3: Parallel Analysis Execution 1. **Gemini Comprehensive Analysis & Documentation** - - **Tool Configuration**: `gemini-wrapper --approval-mode yolo` for write permissions - - **Purpose**: Enhanced comprehensive analysis with actionable suggestions, design blueprints, and documentation generation - - **Expected Outputs**: - - Current State Analysis: Architecture patterns, code quality, technical debt, performance bottlenecks - - Enhanced Suggestions: Implementation blueprints, code organization, API specifications, security guidelines - - Implementation Roadmap: Phase-by-phase plans, CI/CD blueprints, testing strategies - - Actionable Examples: Code templates, configuration scripts, integration patterns - - Documentation Generation: Technical documentation, API docs, user guides, and README files - - **Prompt Template**: - ``` + - **Tool Configuration**: + ```bash + cd .workflow/{session_id}/.process && ~/.claude/scripts/gemini-wrapper -p " PURPOSE: Generate comprehensive analysis and documentation for {task_description} TASK: Analyze codebase, create implementation blueprints, and generate supporting documentation CONTEXT: {context_package_assets} EXPECTED: - 1. Complete technical analysis with implementation strategy - 2. Generated documentation files (README.md, API.md, GUIDE.md as needed) - 3. Code examples and configuration templates - 4. Implementation roadmap with phase-by-phase plans - RULES: Create both analysis blueprints AND user-facing documentation. Generate actual documentation files, not just analysis of documentation needs. + 1. Current State Analysis: Architecture patterns, code quality, technical debt, performance bottlenecks + 2. Enhanced Suggestions: Implementation blueprints, code organization, API specifications, security guidelines + 3. Implementation Roadmap: Phase-by-phase plans, CI/CD blueprints, testing strategies + 4. Actionable Examples: Code templates, configuration scripts, integration patterns + 5. Documentation Generation: Technical documentation, API docs, user guides, and README files + 6. Generate .workflow/{session_id}/.process/gemini-enhanced-analysis.md with all analysis results + RULES: Create both analysis blueprints AND user-facing documentation. Generate actual documentation files, not just analysis of documentation needs. Focus on planning documents, architectural designs, and specifications - do NOT generate specific code implementations. + " --approval-mode yolo ``` - **Output Location**: `.workflow/{session_id}/.process/gemini-enhanced-analysis.md` + generated docs 2. **Codex Implementation Validation** (Complex Tasks Only) - - **Tool Configuration**: `codex --skip-git-repo-check --full-auto exec -s danger-full-access` for implementation validation - - **Purpose**: Technical feasibility validation with write-enabled blueprint generation - - **Expected Outputs**: - - Feasibility Assessment: Complexity analysis, resource requirements, technology compatibility - - Implementation Validation: Quality recommendations, security assessments, testing frameworks - - Implementation Guides: Step-by-step procedures, configuration management, monitoring setup + - **Tool Configuration**: + ```bash + codex -C .workflow/{session_id}/.process --full-auto exec " + PURPOSE: Technical feasibility validation with write-enabled blueprint generation + TASK: Validate implementation feasibility and generate comprehensive blueprints + CONTEXT: {context_package_assets} and {gemini_analysis_results} + EXPECTED: + 1. Feasibility Assessment: Complexity analysis, resource requirements, technology compatibility + 2. Implementation Validation: Quality recommendations, security assessments, testing frameworks + 3. Implementation Guides: Step-by-step procedures, configuration management, monitoring setup + 4. Generate .workflow/{session_id}/.process/codex-validation-analysis.md with all validation results + RULES: Focus on technical validation, security assessments, and implementation planning examples. Create comprehensive validation documentation with architectural guidance and specifications - do NOT generate specific code implementations. + " --skip-git-repo-check -s danger-full-access + ``` - **Output Location**: `.workflow/{session_id}/.process/codex-validation-analysis.md` 3. **Parallel Execution Management** @@ -406,7 +410,7 @@ fi ### Success Criteria - ✅ **Enhanced Output Generation**: Comprehensive ANALYSIS_RESULTS.md with implementation blueprints and machine-readable summary -- ✅ **Write-Enabled CLI Tools**: Full write permissions for Gemini (--approval-mode yolo) and Codex (--skip-git-repo-check -s danger-full-access) +- ✅ **Write-Enabled CLI Tools**: Full write permissions for Gemini (--approval-mode yolo) and Codex (exec ... --skip-git-repo-check -s danger-full-access) - ✅ **Enhanced Suggestions**: Concrete implementation examples, configuration templates, and step-by-step procedures - ✅ **Design Blueprints**: Detailed technical architecture with component diagrams and API specifications - ✅ **Parallel Execution**: Efficient concurrent tool execution with proper monitoring and timeout handling diff --git a/.claude/workflows/intelligent-tools-strategy.md b/.claude/workflows/intelligent-tools-strategy.md index 43e6d8d0..f4c1d0b5 100644 --- a/.claude/workflows/intelligent-tools-strategy.md +++ b/.claude/workflows/intelligent-tools-strategy.md @@ -60,13 +60,13 @@ RULES: [template reference and constraints] " # Codex Development -codex -C [directory] --skip-git-repo-check --full-auto exec " +codex -C [directory] --full-auto exec " PURPOSE: [clear development goal] TASK: [specific development task] CONTEXT: [file references and memory context] EXPECTED: [expected deliverables] RULES: [template reference and constraints] -" -s danger-full-access +" --skip-git-repo-check -s danger-full-access ``` ### Template Structure @@ -178,13 +178,13 @@ RULES: $(cat "~/.claude/workflows/cli-templates/prompts/analysis/architecture.tx " # Feature Development (in target directory) -codex -C path/to/project --skip-git-repo-check --full-auto exec " +codex -C path/to/project --full-auto exec " PURPOSE: Implement user authentication TASK: Create JWT-based authentication system CONTEXT: @{src/auth/**/*} Database schema from session memory EXPECTED: Complete auth module with tests RULES: $(cat "~/.claude/workflows/cli-templates/prompts/development/feature.txt") | Follow security best practices -" -s danger-full-access +" --skip-git-repo-check -s danger-full-access # Code Review Preparation ~/.claude/scripts/gemini-wrapper -p " @@ -220,7 +220,7 @@ For every development task: - **Best For**: System design, code scaffolding, architectural planning ### Codex -- **Command**: `codex --skip-git-repo-check --full-auto exec` +- **Command**: `codex --full-auto exec` - **Strengths**: Autonomous development, mathematical reasoning - **Best For**: Implementation, testing, automation - **Required**: `-s danger-full-access` and `--skip-git-repo-check` for development @@ -257,7 +257,7 @@ cd src/auth && ~/.claude/scripts/gemini-wrapper -p "analyze auth patterns" cd src/auth && ~/.claude/scripts/qwen-wrapper -p "design auth architecture" # Focused implementation (Codex) -codex -C src/auth --skip-git-repo-check --full-auto exec "analyze auth implementation" +codex -C src/auth --full-auto exec "analyze auth implementation" --skip-git-repo-check # Multi-scope (stay in root) ~/.claude/scripts/gemini-wrapper -p "CONTEXT: @{src/auth/**/*,src/api/**/*}"