diff --git a/.claude/commands/workflow/execute.md b/.claude/commands/workflow/execute.md index bcd1deee..efeea693 100644 --- a/.claude/commands/workflow/execute.md +++ b/.claude/commands/workflow/execute.md @@ -70,9 +70,10 @@ Workflow Discovery: - [ ] **TASK-003**: [Agent: code-review-agent] Review implementations - [ ] **TASK-004**: Update task statuses and session state -**Marker Legend**: +**Marker Legend**: - [GEMINI_CLI_REQUIRED] = Agent must use Gemini CLI for pattern analysis - [CODEX_CLI_REQUIRED] = Agent must use Codex CLI for autonomous analysis +- [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement) ``` ### 3. Agent Context Assignment @@ -144,20 +145,30 @@ For each executable task: - **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" +- **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists ### 4. Agent Execution & Progress Tracking ```bash Task(subagent_type="code-developer", - prompt="[GEMINI_CLI_REQUIRED] Implement authentication logic based on schema - - Task Context: impl-1.2 - Implement auth logic + prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Analyze auth patterns and implement JWT authentication system + + Task Context: impl-1.2 - Saturated task with merged preparation and execution + + PREPARATION PHASE (preparation_complexity: simple, estimated_prep_time: 20min): + 1. Review existing auth patterns in the codebase + 2. Check JWT library compatibility with current stack + 3. Analyze current session management approach + + EXECUTION PHASE: + Based on preparation findings, implement JWT authentication system + Session Context: - Workflow Directory: .workflow/WFS-user-auth/ - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md - Summaries Directory: .workflow/WFS-user-auth/.summaries/ - Task JSON Location: .workflow/WFS-user-auth/.task/impl-1.2.json - + Implementation Details: - Target File: src/auth/models/User.ts - Function: UserSchema (lines 10-50) @@ -167,13 +178,15 @@ Task(subagent_type="code-developer", - Dependencies: mongoose, jsonwebtoken - Risks: Schema changes require database migration, Existing user data compatibility - Performance: Index JWT fields for faster lookups - - Focus Paths (from task JSON): $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) - Gemini Command: gemini -p "$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}" - - IMPORTANT: Update TODO_LIST.md and create summary in provided directories upon completion. - Use implementation details above for precise, targeted development.", - description="Execute impl-1.2 with full workflow context and implementation details") + + Focus Paths (from task JSON): $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) + Gemini Command: ~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}" + + IMPORTANT: + 1. Document both preparation analysis results and implementation in summary + 2. Update TODO_LIST.md and create summary in provided directories upon completion + 3. Use preparation findings to inform implementation decisions", + description="Execute saturated task with preparation and implementation phases") ``` **Execution Protocol:** @@ -226,28 +239,42 @@ Based on discovered task data: ### Discovery-Based Assignment ```bash -# Agent receives complete discovered context +# Agent receives complete discovered context with saturation handling Task(subagent_type="code-developer", - prompt="[GEMINI_CLI_REQUIRED] Execute impl-1.2: Implement auth logic - + prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Execute impl-1.2: Analyze and implement auth logic + + TASK TYPE: Saturated task (preparation_complexity: simple) + + PREPARATION PHASE: + - Review existing auth patterns and conventions + - Check JWT library compatibility + - Analyze current session management + + EXECUTION PHASE: + Implement JWT authentication based on preparation findings + Context from discovery: - Requirements: JWT authentication, OAuth2 support - Scope: src/auth/*, tests/auth/* - Dependencies: impl-1.1 (completed) - Workflow: WFS-user-auth authentication system - + Session Context: - Workflow Directory: .workflow/WFS-user-auth/ - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md - Summaries Directory: .workflow/WFS-user-auth/.summaries/ - Task JSON: .workflow/WFS-user-auth/.task/impl-1.2.json - - Focus Paths: $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) - Analysis Command: Use gemini -p \"$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\" - - CRITICAL: Use task-specific paths for focused analysis. Update TODO_LIST.md and create completion summary using provided paths.", - - description="Agent executes with task-specific paths and full discovered context") + + Focus Paths: $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) + Analysis Command: Use ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\" + + CRITICAL: + 1. Execute preparation phase first, then use findings for implementation + 2. Use task-specific paths for focused analysis + 3. Document both phases in completion summary + 4. Update TODO_LIST.md and create completion summary using provided paths.", + + description="Agent executes saturated task with preparation and implementation phases") ``` ### Status Tracking Integration @@ -341,13 +368,3 @@ mark_dependent_tasks_ready(task_dependencies) /workflow:review # Move to review phase when complete ``` -## Related Commands - -- `/context` - View discovered tasks and current status -- `/task:execute` - Execute individual tasks (user-controlled) -- `/workflow:session:status` - Check session progress and dependencies -- `/workflow:review` - Move to review phase after completion - ---- - -**System ensures**: Intelligent task discovery with context-rich agent coordination and automatic progress tracking \ No newline at end of file diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 8af3156d..b4a689fb 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -7,7 +7,6 @@ examples: - /workflow:plan "Build authentication system" - /workflow:plan requirements.md - /workflow:plan ISS-001 - - /workflow:plan web-api --- # Workflow Plan Command (/workflow:plan) @@ -32,7 +31,6 @@ Optional flag to specify which CLI tool to use for context analysis: ```bash /workflow:plan --AM codex "Build authentication system" /workflow:plan --AM gemini requirements.md -/workflow:plan ISS-001 # Uses default (gemini) ``` ## Input Detection Logic @@ -41,9 +39,7 @@ The command automatically detects input type: ### File Input (Auto-detected) ```bash /workflow:plan requirements.md -/workflow:plan PROJECT_SPEC.txt /workflow:plan config.json -/workflow:plan spec.yaml ``` **Triggers**: Extensions: .md, .txt, .json, .yaml, .yml **Processing**: Reads file contents and extracts requirements @@ -52,25 +48,14 @@ The command automatically detects input type: ```bash /workflow:plan ISS-001 /workflow:plan ISSUE-123 -/workflow:plan feature-request-45 ``` **Triggers**: Patterns: ISS-*, ISSUE-*, *-request-* **Processing**: Loads issue data and acceptance criteria -### Template Input (Auto-detected) -```bash -/workflow:plan web-api -/workflow:plan mobile-app -/workflow:plan database-migration -/workflow:plan security-feature -``` -**Triggers**: Known template names -**Processing**: Loads template and prompts for customization ### Text Input (Default) ```bash /workflow:plan "Build user authentication with JWT and OAuth2" -/workflow:plan "Fix performance issues in dashboard" ``` **Triggers**: Everything else **Processing**: Parse natural language requirements @@ -82,87 +67,55 @@ The command automatically detects input type: - Uses active session if available - Generates session ID: WFS-[topic-slug] -### Complexity Detection -- **Simple**: <5 tasks → Direct IMPL_PLAN.md -- **Medium**: 5-15 tasks → IMPL_PLAN.md + TODO_LIST.md -- **Complex**: >15 tasks → Full decomposition +### Complexity Detection with Saturation +- **Simple**: <3 saturated tasks → Direct IMPL_PLAN.md +- **Medium**: 3-8 saturated tasks → IMPL_PLAN.md + TODO_LIST.md +- **Complex**: >8 saturated tasks → Full decomposition -### Task Generation +**Note**: 1 complex preparation task = 0.5 saturated task for counting + +### Task Generation with Saturation Control +- **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 - Automatically creates .task/ files when complexity warrants -- Generates hierarchical task structure (max 3 levels) +- Generates hierarchical task structure (max 2 levels) - Main tasks with subtasks become container tasks (not directly executable) - Updates session state with task references - Runs project structure analysis to populate paths field -### Implementation Field Requirements -⚠️ **CRITICAL**: All generated tasks must include detailed implementation guidance +### Task Saturation Assessment +Evaluates whether to merge preparation and execution: -**analysis_source Assignment Rules**: -- **"manual"**: User provides complete implementation details (including specific files and code snippets) -- **"gemini"**: Insufficient information, requires Gemini analysis (missing file paths or code context) -- **"codex"**: Insufficient information, requires Codex autonomous development analysis (complex refactoring or intelligent file discovery) -- **"auto-detected"**: System automatically infers implementation details (based on pattern recognition) +**Merge Conditions** (Saturated Tasks): +- Preparation work < 30min estimated +- Analysis scope ≤ 3 files +- No complex dependencies +- Single module operation -**Decision Flow**: -1. **IF** user provides file paths + code snippets → "manual" -2. **ELIF** system can infer implementation location → "auto-detected" -3. **ELIF** --AM codex specified → "codex" (requires autonomous development analysis) -4. **ELSE** → "gemini" (requires deep analysis, default method) +**Separate Preparation Conditions**: +- Cross-module architecture analysis (>5 modules) +- Deep performance analysis or security audit required +- Database migration design needed +- Third-party API integration research -**Auto-fill Strategy**: -1. **Sufficient Information**: Auto-fill implementation field based on user input and project context -2. **Insufficient Information**: Mark analysis_source appropriately and prompt: - - **For Gemini Analysis (default)**: - ``` - ⚠️ Implementation details incomplete, recommend using gemini analysis: - gemini --all-files -p "@{relevant-file-patterns} @{CLAUDE.md} - Analyze task: [task description] - Extract: 1) File locations and code snippets 2) Modification logic and data flow 3) Risks and dependencies" - ``` - - **For Codex Analysis (when --AM codex specified)**: - ``` - ⚠️ Implementation details incomplete, recommend using codex analysis: - codex --full-auto exec "Analyze and implement: [task description] - Context: Autonomous analysis and implementation guidance needed - Extract: 1) Intelligent file discovery 2) Implementation strategy 3) Autonomous development approach" - ``` +**Task Examples**: +- **Saturated**: "IMPL-001: Analyze auth patterns and implement JWT token management" +- **Split needed**: "IMPL-001: Design cross-service auth architecture" + "IMPL-002: Implement auth service" -**Required Implementation Sub-fields**: -- **files**: Must contain at least 1 file with detailed info (path, location, original_code, modifications) -- **context_notes**: Dependencies, risks, performance considerations -- **analysis_source**: manual|gemini|codex|auto-detected +### Task Breakdown Process +- **Automatic decomposition**: Tasks with complexity >5 are broken into subtasks (impl-N.M format) +- **Container tasks**: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST) +- **Smart decomposition**: AI analyzes task title to suggest logical subtask structure +- **Context inheritance**: Subtasks inherit parent's requirements and scope, refined for specific needs +- **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review) +- **Maximum depth**: 2 levels (impl-N.M) to maintain manageable hierarchy -**Paths Field Population Process**: -1. **Project Structure Analysis**: Run `get_modules_by_depth.sh` to discover project structure -2. **Relevance Filtering**: Match discovered modules to task requirements -3. **Path Selection**: Choose concrete directories/files (avoid wildcards) -4. **Format**: Semicolon-separated list (e.g., `"src/auth;tests/auth;config/auth.json"`) - -**Path Selection Strategy**: -```pseudo -# Step 1: Analyze project structure -modules = Bash(.claude/scripts/get_modules_by_depth.sh list) - -# Step 2: Extract relevant modules based on task scope -relevant_paths = [] -for module in modules: - if matches_task_scope(module.path, task_requirements): - relevant_paths.append(module.path) - -# Step 3: Add specific files mentioned in requirements -specific_files = extract_file_mentions(task_requirements) -relevant_paths.extend(specific_files) - -# Step 4: Format as semicolon-separated string -task.paths = join(relevant_paths, ";") -``` - -**Quality Standards**: -- logic_flow must use specified symbols (───►, ◊───, ◄───) -- Each file must have specific location (function name or line range) -- risks array cannot be empty, must contain at least 1 risk assessment +### 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 +- **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json") ## Session Check Process ⚠️ **CRITICAL**: Check for existing active session before planning @@ -173,6 +126,21 @@ task.paths = join(relevant_paths, ";") ## Output Documents +### Document References for Execution + +#### Primary References +- **Planning Document**: `.workflow/WFS-[topic-slug]/IMPL_PLAN.md` + - Used by: `/workflow:execute` for context loading + - Contains: Requirements, task overview, success criteria + +- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/impl-*.json` + - Used by: Agents for implementation context + - Contains: Complete task details with implementation field including preparation_complexity + +- **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md` + - Used by: `/workflow:execute` for status tracking + - Updated by: Agents after task completion + ### IMPL_PLAN.md (Always Created) ```markdown # Implementation Plan - [Project Name] @@ -182,7 +150,7 @@ task.paths = join(relevant_paths, ";") [Extracted requirements from input source] ## Task Breakdown -- **IMPL-001**: [Task description] +- **IMPL-001**: [Saturated task description with merged preparation and execution] - **IMPL-002**: [Task description] ## Success Criteria @@ -208,22 +176,8 @@ Generated in .task/ directory when decomposition enabled - **Invalid issue**: Verify issue ID exists - **Unknown template**: List available templates - **Empty input**: Prompt for valid input - -## Integration Points - -### Related Commands -- `/workflow:session:start` - Create new session first -- `/context` - View generated plan -- `/task/execute` - Execute decomposed tasks -- `/workflow:execute` - Run implementation phase - -### Template System -Available templates: -- `web-api`: REST API development -- `mobile-app`: Mobile application -- `database-migration`: Database changes -- `security-feature`: Security implementation - ---- +- **Vague text input**: Auto-reject without guidance + - Rejected examples: "do something", "fix it", "make it better", "add feature" + - Response: Direct rejection message, no further assistance **System ensures**: Unified planning interface with intelligent input detection and automatic complexity handling \ No newline at end of file diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index 0c08f546..1a4ef8a8 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -107,6 +107,13 @@ All task files use this 10-field schema: }, "implementation": { + "preparation_complexity": "simple|moderate|complex", + "preparation_tasks": [ + "Review existing auth patterns", + "Check JWT library compatibility", + "Analyze current session management" + ], + "estimated_prep_time": "20min", "files": [ { "path": "src/auth/login.ts", @@ -120,7 +127,7 @@ All task files use this 10-field schema: "current_state": "Currently using simple password validation", "proposed_changes": [ "Add JWT token generation logic", - "Integrate OAuth2 authentication flow", + "Integrate OAuth2 authentication flow", "Enhance error handling mechanisms" ], "logic_flow": [ @@ -193,6 +200,20 @@ The **implementation** field provides detailed code implementation guidance with - **reason**: Modification rationale and objectives - **expected_outcome**: Expected results +#### preparation_complexity - Task Saturation Assessment +- **simple**: Preparation work < 30min, ≤ 3 files, single module → Merge with execution +- **moderate**: Cross-module analysis needed, 30min-2h prep → Consider separation +- **complex**: Architecture design, >2h prep, >5 modules → Separate preparation task + +#### preparation_tasks - Preparation Work List +- Array of specific preparation activities to be performed +- Used to estimate complexity and decide merge/split strategy +- Examples: ["Review patterns", "Check dependencies", "Analyze performance"] + +#### estimated_prep_time - Time Estimation +- String format time estimate (e.g., "20min", "2h", "half-day") +- Helps determine if preparation should be merged with execution + #### context_notes - Implementation Context Information - **dependencies**: Required dependency packages or modules - **affected_modules**: Other modules that will be affected