From 9371af8d8d44dd188a1df06c468534d9f895e6b5 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 15 Sep 2025 21:55:28 +0800 Subject: [PATCH] refactor: Enforce 10-task limit and file cohesion across workflow system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update workflow-architecture.md: Streamline structure, enforce 10-task hard limit - Update workflow plan.md: Add file cohesion rules, similar functionality warnings - Update task breakdown.md: Manual breakdown controls, conflict detection - Update task-core.md: Sync JSON schema with workflow-architecture.md - Establish consistent 10-task maximum across all workflow commands - Add file cohesion enforcement to prevent splitting related files - Replace "Complex" classification with "Over-scope" requiring re-planning πŸ€– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .claude/agents/action-planning-agent.md | 2 +- .claude/agents/code-developer.md | 99 ++- .claude/agents/code-review-test-agent.md | 83 +-- .claude/agents/conceptual-planning-agent.md | 42 +- .claude/commands/gemini/execute.md | 2 +- .claude/commands/task/breakdown.md | 120 +++- .claude/commands/task/create.md | 20 +- .claude/commands/task/execute.md | 16 +- .claude/commands/task/replan.md | 32 +- .claude/commands/workflow/execute.md | 220 ++++--- .claude/commands/workflow/issue/list.md | 2 +- .claude/commands/workflow/plan-deep.md | 6 +- .claude/commands/workflow/plan.md | 111 ++-- .claude/commands/workflow/resume.md | 69 ++- .claude/commands/workflow/session/status.md | 2 +- .claude/workflows/task-core.md | 197 +++--- .claude/workflows/workflow-architecture.md | 631 +++++++++----------- 17 files changed, 878 insertions(+), 776 deletions(-) diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 0c357191..9ab44f14 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -102,7 +102,7 @@ For tasks requiring >5 subtasks or spanning >3 modules: ### 4. Document Generation Create workflow documents with proper linking: -- Todo items link to task JSON: `[πŸ“‹ Details](./.task/impl-XXX.json)` +- Todo items link to task JSON: `[πŸ“‹ Details](./.task/IMPL-XXX.json)` - Completed tasks link to summaries: `[βœ… Summary](./.summaries/IMPL-XXX-summary.md)` - Consistent ID schemes (IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z) diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md index c5876554..ac6f900c 100644 --- a/.claude/agents/code-developer.md +++ b/.claude/agents/code-developer.md @@ -37,27 +37,34 @@ 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 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 +ELIF context insufficient OR task has flow control marker: + β†’ Check for [FLOW_CONTROL] marker: + - Execute flow_control.pre_analysis steps sequentially BEFORE implementation + - Process each step with command execution and context accumulation + - Load dependency summaries and parent task context + - Execute CLI tools, scripts, and agent commands as specified + - Pass context between steps via [variable_name] references + β†’ Extract patterns and conventions from accumulated context β†’ Proceed with execution ``` -**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 +**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 -**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]")` +**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 +- **Command Types**: + - **CLI Analysis**: Execute gemini/codex commands with context variables + - **Dependency Loading**: Read summaries from context.depends_on automatically + - **Context Accumulation**: Pass step outputs to subsequent steps via [variable_name] +- **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 @@ -114,7 +121,7 @@ ELIF context insufficient OR task has analysis marker: ``` .workflow/WFS-[session-id]/ # (Path provided in session context) β”œβ”€β”€ TODO_LIST.md # Progress tracking document - β”œβ”€β”€ .task/impl-*.json # Task definitions (source of truth) + β”œβ”€β”€ .task/IMPL-*.json # Task definitions (source of truth) └── .summaries/IMPL-*.md # Task completion summaries ``` @@ -123,12 +130,12 @@ ELIF context insufficient OR task has analysis marker: # Tasks: User Authentication System ## 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) - - [ ] **IMPL-001.2**: API endpoints β†’ [πŸ“‹](./.task/impl-001.2.json) + β–Έ **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) + - [ ] **IMPL-001.2**: API endpoints β†’ [πŸ“‹](./.task/IMPL-001.2.json) - - [ ] **IMPL-002**: Add JWT validation β†’ [πŸ“‹](./.task/impl-002.json) - - [ ] **IMPL-003**: OAuth2 integration β†’ [πŸ“‹](./.task/impl-003.json) + - [ ] **IMPL-002**: Add JWT validation β†’ [πŸ“‹](./.task/IMPL-002.json) + - [ ] **IMPL-003**: OAuth2 integration β†’ [πŸ“‹](./.task/IMPL-003.json) ## Status Legend - `β–Έ` = Container task (has subtasks) @@ -141,15 +148,44 @@ ELIF context insufficient OR task has analysis marker: - Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`) - Link summary in TODO_LIST.md using relative path - **Summary Template**: + **Enhanced Summary Template**: ```markdown # Task: [Task-ID] [Name] - - ## Completed - - Files modified: [list] - - Tests added: [count] - - Key changes: [brief list] - + + ## Implementation Summary + + ### Files Modified + - `[file-path]`: [brief description of changes] + - `[file-path]`: [brief description of changes] + + ### Content Added + - **[ComponentName]** (`[file-path]`): [purpose/functionality] + - **[functionName()]** (`[file:line]`): [purpose/parameters/returns] + - **[InterfaceName]** (`[file:line]`): [properties/purpose] + - **[CONSTANT_NAME]** (`[file:line]`): [value/purpose] + + ## Outputs for Dependent Tasks + + ### Available Components + ```typescript + // New components ready for import/use + import { ComponentName } from '[import-path]'; + import { functionName } from '[import-path]'; + import { InterfaceName } from '[import-path]'; + ``` + + ### Integration Points + - **[Component/Function]**: Use `[import-statement]` to access `[functionality]` + - **[API Endpoint]**: `[method] [url]` for `[purpose]` + - **[Configuration]**: Set `[config-key]` in `[config-file]` for `[behavior]` + + ### Usage Examples + ```typescript + // Basic usage patterns for new components + const example = new ComponentName(params); + const result = functionName(input); + ``` + ## Status: βœ… Complete ``` @@ -178,6 +214,7 @@ Before completing any task, verify: - [ ] ASCII-only characters (no emojis/Unicode) - [ ] GBK encoding compatible - [ ] TODO list updated +- [ ] Comprehensive summary document generated with all new components/methods listed ## Key Reminders @@ -196,3 +233,5 @@ Before completing any task, verify: - Follow existing patterns and conventions - Handle errors appropriately - Keep functions small and focused +- Generate detailed summary documents with complete component/method listings +- Document all new interfaces, types, and constants for dependent task reference diff --git a/.claude/agents/code-review-test-agent.md b/.claude/agents/code-review-test-agent.md index 741bdf61..fe26e2d1 100644 --- a/.claude/agents/code-review-test-agent.md +++ b/.claude/agents/code-review-test-agent.md @@ -49,33 +49,33 @@ 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 marker: -- **[MULTI_STEP_ANALYSIS]**: Execute sequential analysis steps with specified templates, expanding brief actions +**🎯 Flow Control Detection** +When task assignment includes flow control marker: +- **[FLOW_CONTROL]**: Execute sequential flow control steps with context accumulation and variable passing -**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 +**Flow Control Support**: +- **Process flow_control.pre_analysis array**: Handle multi-step flow control format +- **Context variable handling**: Process [variable_name] references in commands +- **Sequential execution**: Execute each step in order, accumulating context through variables +- **Error handling**: Apply per-step error strategies **Context Gathering Decision Logic**: ``` -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 +IF task contains [FLOW_CONTROL] flag: + β†’ Execute each flow control step sequentially with context variables + β†’ Load dependency summaries from connections.depends_on + β†’ Process [variable_name] references in commands + β†’ Accumulate context through step outputs ELIF reviewing >3 files OR security changes OR architecture modifications: - β†’ Execute default multi-step analysis (AUTO-TRIGGER) + β†’ Execute default flow control analysis (AUTO-TRIGGER) ELSE: β†’ Proceed with review using standard quality checks ``` -## Multi-Step Pre-Analysis Phase (Execute When Required) +## Flow Control Pre-Analysis Phase (Execute When Required) -### Multi-Step Analysis Execution -When [MULTI_STEP_ANALYSIS] flag is present, execute comprehensive pre-review analysis: +### Flow Control Execution +When [FLOW_CONTROL] flag is present, execute comprehensive pre-review analysis: Process each step from pre_analysis array sequentially: @@ -163,12 +163,12 @@ if [FAST_MODE]: apply targeted review process - Concurrency issues (race conditions, deadlocks) - Input validation and sanitization -### Code Quality +### Code Quality & Dependencies +- Import/export correctness and path validation +- Missing or unused imports identification +- Circular dependency detection - Single responsibility principle - Clear variable and function names -- Appropriate abstraction levels -- No code duplication (DRY principle) -- Proper documentation for complex logic ### Performance - Algorithm complexity (time and space) @@ -201,40 +201,15 @@ if [FAST_MODE]: apply targeted review process ```markdown # Review Summary: [Task-ID] [Review Name] - ## Review Scope - - [Files/components reviewed] - - [Lines of code reviewed] - - [Review depth applied: Deep/Fast Mode] - - ## Critical Findings - - [Bugs found and fixed] - - [Security issues identified] - - [Breaking changes prevented] - - ## Quality Improvements - - [Code quality enhancements] - - [Performance optimizations] - - [Architecture improvements] - - ## Test Implementation - - [Tests written or updated] + ## Issues Fixed + - [Bugs/security issues resolved] + - [Missing imports added] + - [Unused imports removed] + - [Import path errors corrected] + + ## Tests Added + - [Test files created/updated] - [Coverage improvements] - - [Test quality enhancements] - - ## Compliance Check - - [Standards adherence verified] - - [Convention violations fixed] - - [Documentation completeness] - - ## Recommendations Implemented - - [Suggested improvements applied] - - [Refactoring performed] - - [Test coverage added] - - ## Outstanding Items - - [Deferred improvements] - - [Future considerations] - - [Technical debt noted] ## Approval Status - [x] Approved / [ ] Approved with minor changes / [ ] Needs revision / [ ] Rejected diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index 4ad1372f..c68e4fe1 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.claude/agents/conceptual-planning-agent.md @@ -37,8 +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 marker: -- **[MULTI_STEP_ANALYSIS]** - Execute mandatory multi-step pre-execution analysis +When receiving task prompt, check for flow control marker: +- **[FLOW_CONTROL]** - Execute mandatory flow control steps with context accumulation - **ASSIGNED_ROLE** - Extract the specific role for focused analysis - **ANALYSIS_DIMENSIONS** - Load role-specific analysis dimensions @@ -49,28 +49,28 @@ def handle_analysis_markers(prompt): dimensions = extract_value("ANALYSIS_DIMENSIONS", prompt) topic = extract_topic(prompt) - if "[MULTI_STEP_ANALYSIS]" in prompt: - analysis_steps = extract_pre_analysis_array(prompt) - for step in analysis_steps: + if "[FLOW_CONTROL]" in prompt: + flow_steps = extract_flow_control_array(prompt) + context_vars = {} + + for step in flow_steps: + step_name = step["step"] action = step["action"] - template = step["template"] - method = step["method"] + command = step["command"] + output_to = step.get("output_to") + on_error = step.get("on_error", "fail") - expanded_action = expand_brief_action(action, role, topic) + # Process context variables in command + processed_command = process_context_variables(command, context_vars) - 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) + try: + result = execute_command(processed_command, role_context=role, topic=topic) + if output_to: + context_vars[output_to] = result + except Exception as e: + handle_step_error(e, on_error, step_name) + + integrate_flow_results(context_vars, role) ``` ### Role-Specific Analysis Dimensions diff --git a/.claude/commands/gemini/execute.md b/.claude/commands/gemini/execute.md index ff1917c4..abbf0354 100644 --- a/.claude/commands/gemini/execute.md +++ b/.claude/commands/gemini/execute.md @@ -75,7 +75,7 @@ model: sonnet # Execute specific workflow task /gemini:execute IMPL-001 -# Loads from: .task/impl-001.json +# Loads from: .task/IMPL-001.json # Uses: task context, brainstorming refs, scope definitions # Updates: workflow status, generates summary ``` diff --git a/.claude/commands/task/breakdown.md b/.claude/commands/task/breakdown.md index cc0f27f0..0a244183 100644 --- a/.claude/commands/task/breakdown.md +++ b/.claude/commands/task/breakdown.md @@ -15,25 +15,34 @@ examples: Breaks down complex tasks into executable subtasks with context inheritance and agent assignment. ## Core Principles -**Task System:** @~/.claude/workflows/task-core.md +**Task System:** @~/.claude/workflows/workflow-architecture.md +**File Cohesion:** Related files must stay in same task +**10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping) ## Core Features -⚠️ **CRITICAL**: Check for active session before breakdown to avoid conflicts. +⚠️ **CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations. ### Breakdown Process 1. **Session Check**: Verify active session contains parent task 2. **Task Validation**: Ensure parent is `pending` status -3. **AI Decomposition**: Generate subtasks based on parent title -4. **Context Distribution**: Inherit parent requirements and scope -5. **Agent Assignment**: Auto-assign agents based on subtask type +3. **10-Task Limit Check**: Verify breakdown won't exceed total limit +4. **Manual Decomposition**: User defines subtasks with validation +5. **File Conflict Detection**: Warn if same files appear in multiple subtasks +6. **Similar Function Warning**: Alert if subtasks have overlapping functionality +7. **Context Distribution**: Inherit parent requirements and scope +8. **Agent Assignment**: Auto-assign agents based on subtask type +9. **TODO_LIST Update**: Regenerate TODO_LIST.md with new structure ### Breakdown Rules - Only `pending` tasks can be broken down +- **Manual breakdown only**: Automated breakdown disabled to prevent violations - Parent becomes `container` status (not executable) -- Subtasks use format: impl-N.M (max 2 levels) +- Subtasks use format: IMPL-N.M (max 2 levels) - Context flows from parent to subtasks - All relationships tracked in JSON +- **10-task limit enforced**: Breakdown rejected if total would exceed 10 tasks +- **File cohesion preserved**: Same files cannot be split across subtasks ## Usage @@ -45,23 +54,33 @@ Breaks down complex tasks into executable subtasks with context inheritance and Interactive process: ``` Task: Build authentication module +Current total tasks: 6/10 -Suggested subtasks: -1. Design authentication schema -2. Implement core auth logic -3. Add security middleware -4. Write comprehensive tests +⚠️ MANUAL BREAKDOWN REQUIRED +Define subtasks manually (remaining capacity: 4 tasks): -Accept breakdown? (y/n): y +1. Enter subtask title: User authentication core + Focus files: models/User.js, routes/auth.js, middleware/auth.js -βœ… Task impl-1 broken down: -β–Έ impl-1: Build authentication module (container) - β”œβ”€β”€ impl-1.1: Design schema β†’ planning-agent - β”œβ”€β”€ impl-1.2: Implement logic β†’ code-developer - β”œβ”€β”€ impl-1.3: Add middleware β†’ code-developer - └── impl-1.4: Write tests β†’ code-review-test-agent +2. Enter subtask title: OAuth integration + Focus files: services/OAuthService.js, routes/oauth.js -Files created: .task/impl-1.json + 4 subtask files +⚠️ FILE CONFLICT DETECTED: + - routes/auth.js appears in multiple subtasks + - Recommendation: Merge related authentication routes + +⚠️ SIMILAR FUNCTIONALITY WARNING: + - "User authentication" and "OAuth integration" both handle auth + - Consider combining into single task + +Proceed with breakdown? (y/n): y + +βœ… Task IMPL-1 broken down: +β–Έ IMPL-1: Build authentication module (container) + β”œβ”€β”€ IMPL-1.1: User authentication core β†’ code-developer + └── IMPL-1.2: OAuth integration β†’ code-developer + +Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md ``` ## Decomposition Logic @@ -77,9 +96,39 @@ Files created: .task/impl-1.json + 4 subtask files - Scope refined for specific subtask - Implementation details distributed appropriately +## Safety Controls + +### File Conflict Detection +**Validates file cohesion across subtasks:** +- Scans `focus_paths` in all subtasks +- Warns if same file appears in multiple subtasks +- Suggests merging subtasks with overlapping files +- Blocks breakdown if critical conflicts detected + +### Similar Functionality Detection +**Prevents functional overlap:** +- Analyzes subtask titles for similar keywords +- Warns about potential functional redundancy +- Suggests consolidation of related functionality +- Examples: "user auth" + "login system" β†’ merge recommendation + +### 10-Task Limit Enforcement +**Hard limit compliance:** +- Counts current total tasks in session +- Calculates breakdown impact on total +- Rejects breakdown if would exceed 10 tasks +- Suggests re-scoping if limit reached + +### Manual Control Requirements +**User-driven breakdown only:** +- No automatic subtask generation +- User must define each subtask title and scope +- Real-time validation during input +- Confirmation required before execution + ## Implementation Details -See @~/.claude/workflows/task-core.md for: +See @~/.claude/workflows/workflow-architecture.md for: - Complete task JSON schema - Implementation field structure - Context inheritance rules @@ -92,12 +141,17 @@ See @~/.claude/workflows/task-core.md for: 2. Task found in session 3. Task status is `pending` 4. Not already broken down +5. **10-task limit compliance**: Total tasks + new subtasks ≀ 10 +6. **Manual mode enabled**: No automatic breakdown allowed ### Post-breakdown Actions 1. Update parent to `container` status 2. Create subtask JSON files 3. Update parent subtasks list 4. Update session stats +5. **Regenerate TODO_LIST.md** with new hierarchy +6. Validate file paths in focus_paths +7. Update session task count ## Examples @@ -115,17 +169,35 @@ See @~/.claude/workflows/task-core.md for: ```bash # Task not found -❌ Task impl-5 not found +❌ Task IMPL-5 not found # Already broken down -⚠️ Task impl-1 already has subtasks +⚠️ Task IMPL-1 already has subtasks # Wrong status -❌ Cannot breakdown completed task impl-2 +❌ Cannot breakdown completed task IMPL-2 + +# 10-task limit exceeded +❌ Breakdown would exceed 10-task limit (current: 8, proposed: 4) + Suggestion: Re-scope project into smaller iterations + +# File conflicts detected +⚠️ File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2 + Recommendation: Merge subtasks or redistribute files + +# Similar functionality warning +⚠️ Similar functions detected: "user login" and "authentication" + Consider consolidating related functionality + +# Manual breakdown required +❌ Automatic breakdown disabled. Use manual breakdown process. ``` ## Related Commands - `/task:create` - Create new tasks - `/task:execute` - Execute subtasks -- `/context` - View task hierarchy \ No newline at end of file +- `/workflow:status` - View task hierarchy +- `/workflow:plan` - Plan within 10-task limit + +**System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance \ No newline at end of file diff --git a/.claude/commands/task/create.md b/.claude/commands/task/create.md index 1e9ba99b..2c295dd1 100644 --- a/.claude/commands/task/create.md +++ b/.claude/commands/task/create.md @@ -20,7 +20,7 @@ Creates new implementation tasks with automatic context awareness and ID generat ## Core Features ### Automatic Behaviors -- **ID Generation**: Auto-generates impl-N format (max 2 levels) +- **ID Generation**: Auto-generates IMPL-N format (max 2 levels) - **Context Inheritance**: Inherits from active workflow session - **JSON Creation**: Creates task JSON in active session - **Status Setting**: Initial status = "pending" @@ -42,7 +42,7 @@ Creates new implementation tasks with automatic context awareness and ID generat Output: ``` -βœ… Task created: impl-1 +βœ… Task created: IMPL-1 Title: Build authentication module Type: feature Agent: code-developer @@ -59,7 +59,7 @@ Status: pending ## Task Creation Process 1. **Session Validation**: Check active workflow session -2. **ID Generation**: Auto-increment impl-N +2. **ID Generation**: Auto-increment IMPL-N 3. **Context Inheritance**: Load workflow context 4. **Implementation Setup**: Initialize implementation field 5. **Agent Assignment**: Select appropriate agent @@ -85,7 +85,7 @@ Suggest running: gemini analysis for file locations and dependencies ## File Management ### JSON Task File -- **Location**: `.task/impl-[N].json` in active session +- **Location**: `.task/IMPL-[N].json` in active session - **Content**: Complete task with implementation field - **Updates**: Session stats only @@ -100,7 +100,7 @@ Suggest running: gemini analysis for file locations and dependencies Tasks inherit from: 1. **Active Session** - Requirements and scope from workflow-session.json 2. **Planning Document** - Context from IMPL_PLAN.md -3. **Parent Task** - For subtasks (impl-N.M format) +3. **Parent Task** - For subtasks (IMPL-N.M format) ## Agent Assignment @@ -125,12 +125,12 @@ Based on task type and title keywords: β†’ Use: /workflow init "project name" # Duplicate task -⚠️ Similar task exists: impl-3 +⚠️ Similar task exists: IMPL-3 β†’ Continue anyway? (y/n) # Max depth exceeded -❌ Cannot create impl-1.2.1 (max 2 levels) -β†’ Use: impl-2 for new main task +❌ Cannot create IMPL-1.2.1 (max 2 levels) +β†’ Use: IMPL-2 for new main task ``` ## Examples @@ -139,7 +139,7 @@ Based on task type and title keywords: ```bash /task:create "Implement user authentication" -βœ… Created impl-1: Implement user authentication +βœ… Created IMPL-1: Implement user authentication Type: feature Agent: code-developer Status: pending @@ -149,7 +149,7 @@ Status: pending ```bash /task:create "Fix login validation bug" --type=bugfix -βœ… Created impl-2: Fix login validation bug +βœ… Created IMPL-2: Fix login validation bug Type: bugfix Agent: code-developer Status: pending diff --git a/.claude/commands/task/execute.md b/.claude/commands/task/execute.md index 25cb1d4f..91e68a43 100644 --- a/.claude/commands/task/execute.md +++ b/.claude/commands/task/execute.md @@ -4,9 +4,9 @@ description: Execute tasks with appropriate agents and context-aware orchestrati usage: /task:execute argument-hint: task-id examples: - - /task:execute impl-1 - - /task:execute impl-1.2 - - /task:execute impl-3 + - /task:execute IMPL-1 + - /task:execute IMPL-1.2 + - /task:execute IMPL-3 --- ### πŸš€ **Command Overview: `/task:execute`** @@ -134,7 +134,7 @@ This is the simplified data structure loaded to provide context for task executi ```json { "task": { - "id": "impl-1", + "id": "IMPL-1", "title": "Build authentication module", "type": "feature", "status": "active", @@ -147,8 +147,8 @@ This is the simplified data structure loaded to provide context for task executi }, "relations": { "parent": null, - "subtasks": ["impl-1.1", "impl-1.2"], - "dependencies": ["impl-0"] + "subtasks": ["IMPL-1.1", "IMPL-1.2"], + "dependencies": ["IMPL-0"] }, "implementation": { "files": [ @@ -252,10 +252,10 @@ Different agents receive context tailored to their function, including implement ### πŸ“ **Simplified Summary Template** -Optional summary file generated at `.summaries/impl-[task-id]-summary.md`. +Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`. ```markdown -# Task Summary: impl-1 Build Authentication Module +# Task Summary: IMPL-1 Build Authentication Module ## What Was Done - Created src/auth/login.ts with JWT validation diff --git a/.claude/commands/task/replan.md b/.claude/commands/task/replan.md index 1aec6363..cbd7f89e 100644 --- a/.claude/commands/task/replan.md +++ b/.claude/commands/task/replan.md @@ -4,9 +4,9 @@ description: Replan individual tasks with detailed user input and change trackin usage: /task:replan [input] argument-hint: task-id ["text"|file.md|ISS-001] examples: - - /task:replan impl-1 "Add OAuth2 authentication support" - - /task:replan impl-1 updated-specs.md - - /task:replan impl-1 ISS-001 + - /task:replan IMPL-1 "Add OAuth2 authentication support" + - /task:replan IMPL-1 updated-specs.md + - /task:replan IMPL-1 ISS-001 --- # Task Replan Command (/task:replan) @@ -29,24 +29,24 @@ Replans individual tasks with multiple input options, change tracking, and versi ### Direct Text (Default) ```bash -/task:replan impl-1 "Add OAuth2 authentication support" +/task:replan IMPL-1 "Add OAuth2 authentication support" ``` ### File-based Input ```bash -/task:replan impl-1 updated-specs.md +/task:replan IMPL-1 updated-specs.md ``` Supports: .md, .txt, .json, .yaml ### Issue Reference ```bash -/task:replan impl-1 ISS-001 +/task:replan IMPL-1 ISS-001 ``` Loads issue description and requirements ### Interactive Mode ```bash -/task:replan impl-1 --interactive +/task:replan IMPL-1 --interactive ``` Guided step-by-step modification process with validation @@ -65,14 +65,14 @@ Guided step-by-step modification process with validation Tasks maintain version history: ```json { - "id": "impl-1", + "id": "IMPL-1", "version": "1.2", "replan_history": [ { "version": "1.2", "reason": "Add OAuth2 support", "input_source": "direct_text", - "backup_location": ".task/versions/impl-1-v1.1.json" + "backup_location": ".task/versions/IMPL-1-v1.1.json" } ] } @@ -83,9 +83,9 @@ Tasks maintain version history: ### File Structure ``` .task/ -β”œβ”€β”€ impl-1.json # Current version +β”œβ”€β”€ IMPL-1.json # Current version β”œβ”€β”€ versions/ -β”‚ └── impl-1-v1.1.json # Previous backup +β”‚ └── IMPL-1-v1.1.json # Previous backup └── [new subtasks as needed] ``` @@ -135,7 +135,7 @@ Updates workflow-session.json with: ## Rollback Support ```bash -/task:replan impl-1 --rollback v1.1 +/task:replan IMPL-1 --rollback v1.1 Rollback to version 1.1: - Restore task from backup @@ -151,7 +151,7 @@ Confirm rollback? (y/n): y ### Text Input ```bash -/task:replan impl-1 "Add OAuth2 authentication support" +/task:replan IMPL-1 "Add OAuth2 authentication support" Processing changes... Proposed updates: @@ -167,7 +167,7 @@ Apply changes? (y/n): y ### File Input ```bash -/task:replan impl-2 requirements.md +/task:replan IMPL-2 requirements.md Loading requirements.md... Applying specification changes... @@ -180,11 +180,11 @@ Applying specification changes... ```bash # Task not found -❌ Task impl-5 not found +❌ Task IMPL-5 not found β†’ Check task ID with /context # Task completed -⚠️ Task impl-1 is completed (cannot replan) +⚠️ Task IMPL-1 is completed (cannot replan) β†’ Create new task for additional work # File not found diff --git a/.claude/commands/workflow/execute.md b/.claude/commands/workflow/execute.md index 195d52cb..8fd0162f 100644 --- a/.claude/commands/workflow/execute.md +++ b/.claude/commands/workflow/execute.md @@ -23,20 +23,22 @@ The intelligent execution approach focuses on: - **Dynamic task orchestration** - Coordinate based on discovered task relationships - **Progress tracking** - Update task status after agent completion -**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) +**Flow Control Execution**: +- **[FLOW_CONTROL]**: Indicates sequential flow control execution required + - **Auto-trigger**: When task.flow_control.pre_analysis is an array (default format) + - **Agent Action**: Execute flow control steps sequentially BEFORE implementation begins + - Process each step with command execution and context accumulation + - Load dependency summaries and parent task context + - Execute CLI tools, scripts, and agent commands as specified + - Pass context between steps via named variables + - Handle errors according to per-step error strategies -**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 +**Flow Control Step Processing**: +- **Sequential Execution**: Steps processed in order with context flow + - Each step can use outputs from previous steps via ${variable_name} + - Dependency summaries loaded automatically from .summaries/ + - Context accumulates through the execution chain + - Error handling per step (skip_optional, fail, retry_once, manual_intervention) ## Execution Flow @@ -53,7 +55,7 @@ Workflow Discovery: **Discovery Logic:** - **Folder Detection**: Use provided folder or find current active session -- **Task Inventory**: Load all impl-*.json files from .task/ directory +- **Task Inventory**: Load all IMPL-*.json files from .task/ directory - **Status Analysis**: Check pending/active/completed/blocked states - **Dependency Check**: Verify all task dependencies are met - **Execution Queue**: Build list of ready-to-execute tasks @@ -66,14 +68,13 @@ Workflow Discovery: *Session: WFS-[topic-slug]* ## Execution Plan -- [ ] **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-001**: [Agent: planning-agent] [FLOW_CONTROL] Design auth schema (IMPL-1.1) +- [ ] **TASK-002**: [Agent: code-developer] [FLOW_CONTROL] Implement auth logic (IMPL-1.2) - [ ] **TASK-003**: [Agent: code-review-agent] Review implementations - [ ] **TASK-004**: Update task statuses and session state **Marker Legend**: -- [MULTI_STEP_ANALYSIS] = Agent must execute multi-step pre-execution analysis -- [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement) +- [FLOW_CONTROL] = Agent must execute flow control steps with context accumulation ``` ### 3. Agent Context Assignment @@ -82,126 +83,119 @@ For each executable task: ```json { "task": { - "id": "impl-1.1", + "id": "IMPL-1.1", "title": "Design auth schema", + "status": "pending", + + "meta": { + "type": "feature", + "agent": "code-developer" + }, + "context": { "requirements": ["JWT authentication", "User model design"], - "scope": ["src/auth/models/*"], - "acceptance": ["Schema validates JWT tokens"] - }, - "implementation": { - "files": [ - { - "path": "src/auth/models/User.ts", - "location": { - "function": "UserSchema", - "lines": "10-50", - "description": "User model definition" - }, - "original_code": "// Requires gemini analysis for current schema", - "modifications": { - "current_state": "Basic user model without auth fields", - "proposed_changes": [ - "Add JWT token fields to schema", - "Include OAuth provider fields" - ], - "logic_flow": [ - "createUser() ───► validateSchema() ───► generateJWT()", - "β—Šβ”€β”€β”€ if OAuth ───► linkProvider() ───► storeTokens()" - ], - "reason": "Support modern authentication patterns", - "expected_outcome": "Flexible user schema supporting multiple auth methods" - } - } - ], - "context_notes": { - "dependencies": ["mongoose", "jsonwebtoken"], - "affected_modules": ["auth-middleware", "user-service"], - "risks": [ - "Schema changes require database migration", - "Existing user data compatibility" - ], - "performance_considerations": "Index JWT fields for faster lookups", - "error_handling": "Graceful schema validation errors" + "focus_paths": ["src/auth/models", "tests/auth"], + "acceptance": ["Schema validates JWT tokens"], + "parent": "IMPL-1", + "depends_on": [], + "inherited": { + "from": "IMPL-1", + "context": ["Authentication system architecture completed"] }, + "shared_context": { + "auth_strategy": "JWT with refresh tokens" + } + }, + + "flow_control": { "pre_analysis": [ { - "action": "analyze auth", - "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt", - "method": "gemini" + "step": "gather_context", + "action": "Load dependency summaries", + "command": "bash(echo 'No dependencies for this initial task')", + "output_to": "dependency_context", + "on_error": "skip_optional" }, { - "action": "security review", - "template": "~/.claude/workflows/cli-templates/prompts/analysis/security.txt", - "method": "gemini" + "step": "analyze_patterns", + "action": "Analyze existing auth patterns", + "command": "bash(~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]')", + "output_to": "pattern_analysis", + "on_error": "fail" }, { - "action": "implement feature", - "template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt", - "method": "codex" + "step": "implement", + "action": "Design JWT schema based on analysis", + "command": "bash(codex --full-auto exec 'Design JWT schema using analysis: [pattern_analysis] and context: [dependency_context]')", + "on_error": "manual_intervention" } + ], + "implementation_approach": "Design flexible user schema supporting JWT and OAuth authentication", + "target_files": [ + "src/auth/models/User.ts:UserSchema:10-50" ] } }, "workflow": { - "session": "WFS-user-auth", + "session": "WFS-user-auth", "phase": "IMPLEMENT", "plan_context": "Authentication system with OAuth2 support" - }, - "focus_modules": ["src/auth/", "tests/auth/"] + } } ``` **Context Assignment Rules:** -- **Complete Context**: Use full task JSON context including implementation field for agent execution -- **Implementation Details**: Pass complete implementation.files array to agents for precise execution -- **Code Context**: Include original_code snippets and logic_flow diagrams in agent prompts -- **Risk Awareness**: Alert agents to implementation.context_notes.risks before execution +- **Complete Context**: Use full task JSON context including flow_control field for agent execution +- **Flow Control Processing**: Execute flow_control.pre_analysis steps sequentially with context accumulation +- **Dependency Integration**: Load summaries from context.depends_on automatically +- **Mandatory Dependency Reading**: For tasks with dependencies, MUST read previous task summary documents +- **Context Inheritance**: Use dependency summaries to maintain consistency and include context.inherited data from parent tasks - **Workflow Integration**: Include session state and IMPL_PLAN.md context -- **Scope Focus**: Direct agents to specific files from implementation.files[].path -- **Analysis Marker**: Auto-add [MULTI_STEP_ANALYSIS] when pre_analysis is array format -- **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists +- **Focus Scope**: Direct agents to specific paths from context.focus_paths array +- **Flow Control Marker**: Auto-add [FLOW_CONTROL] when flow_control.pre_analysis exists +- **Target File Guidance**: Use flow_control.target_files for precise file targeting ### 4. Agent Execution & Progress Tracking ```bash Task(subagent_type="code-developer", - prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Analyze auth patterns and implement JWT authentication system + prompt="[FLOW_CONTROL] Execute IMPL-1.2: Implement JWT authentication system with flow control - Task Context: impl-1.2 - Saturated task with merged preparation and execution + Task Context: IMPL-1.2 - Flow control managed 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 + FLOW CONTROL EXECUTION: + Execute the following steps sequentially with context accumulation: - EXECUTION PHASE: - Based on preparation findings, implement JWT authentication system + Step 1 (gather_context): Load dependency summaries + Command: for dep in ${depends_on}; do cat .summaries/$dep-summary.md 2>/dev/null || echo "No summary for $dep"; done + Output: dependency_context + + Step 2 (analyze_patterns): Analyze existing auth patterns + Command: ~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]' + Output: pattern_analysis + + Step 3 (implement): Implement JWT based on analysis + Command: codex --full-auto exec 'Implement JWT using analysis: [pattern_analysis] and context: [dependency_context]' 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 + - 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) - - Current State: Basic user model without auth fields - - Required Changes: Add JWT token fields, Include OAuth provider fields - - Logic Flow: createUser() ───► validateSchema() ───► generateJWT() - - 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: ~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}" + Implementation Guidance: + - Approach: Design flexible user schema supporting JWT and OAuth authentication + - Target Files: src/auth/models/User.ts:UserSchema:10-50 + - Focus Paths: src/auth/models, tests/auth + - Dependencies: From context.depends_on + - Inherited Context: [context.inherited] 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") + 1. Execute flow control steps in sequence with error handling + 2. Accumulate context through step chain + 3. Create comprehensive summary with 'Outputs for Dependent Tasks' section + 4. Update TODO_LIST.md upon completion", + description="Execute task with flow control step processing") ``` **Execution Protocol:** @@ -218,9 +212,9 @@ Task(subagent_type="code-developer", β”œβ”€β”€ workflow-session.json # Session state and stats β”œβ”€β”€ IMPL_PLAN.md # Workflow context and requirements β”œβ”€β”€ .task/ # Task definitions -β”‚ β”œβ”€β”€ impl-1.json # Main tasks -β”‚ β”œβ”€β”€ impl-1.1.json # Subtasks -β”‚ └── impl-1.2.json # Detailed tasks +β”‚ β”œβ”€β”€ IMPL-1.json # Main tasks +β”‚ β”œβ”€β”€ IMPL-1.1.json # Subtasks +β”‚ └── IMPL-1.2.json # Detailed tasks └── .summaries/ # Completed task summaries ``` @@ -256,7 +250,7 @@ Based on discovered task data: ```bash # Agent receives complete discovered context with saturation handling Task(subagent_type="code-developer", - prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Execute impl-1.2: Analyze and implement auth logic + prompt="[FLOW_CONTROL] Execute IMPL-1.2: Analyze and implement auth logic TASK TYPE: Saturated task (preparation_complexity: simple) @@ -271,17 +265,17 @@ Task(subagent_type="code-developer", Context from discovery: - Requirements: JWT authentication, OAuth2 support - Scope: src/auth/*, tests/auth/* - - Dependencies: impl-1.1 (completed) + - 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 + - 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 ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\" + 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 @@ -295,7 +289,7 @@ Task(subagent_type="code-developer", ### Status Tracking Integration ```bash # After agent completion, update discovered task status -update_task_status("impl-1.2", "completed") +update_task_status("IMPL-1.2", "completed") mark_dependent_tasks_ready(task_dependencies) ``` @@ -318,7 +312,7 @@ mark_dependent_tasks_ready(task_dependencies) ```json // Before execution { - "id": "impl-1.2", + "id": "IMPL-1.2", "status": "pending", "execution": { "attempts": 0, @@ -328,7 +322,7 @@ mark_dependent_tasks_ready(task_dependencies) // After execution { - "id": "impl-1.2", + "id": "IMPL-1.2", "status": "completed", "execution": { "attempts": 1, @@ -358,7 +352,7 @@ mark_dependent_tasks_ready(task_dependencies) β†’ Check: /context for task status overview # Missing task files -❌ Task impl-1.2 referenced but JSON file missing +❌ Task IMPL-1.2 referenced but JSON file missing β†’ Fix: /task/create or repair task references ``` @@ -379,7 +373,7 @@ mark_dependent_tasks_ready(task_dependencies) ```bash # After /workflow:execute completion /context # View updated task status -/task:execute impl-X # Execute specific remaining tasks +/task:execute IMPL-X # Execute specific remaining tasks /workflow:review # Move to review phase when complete ``` diff --git a/.claude/commands/workflow/issue/list.md b/.claude/commands/workflow/issue/list.md index 46730ec9..eb9b48c5 100644 --- a/.claude/commands/workflow/issue/list.md +++ b/.claude/commands/workflow/issue/list.md @@ -56,7 +56,7 @@ Simple keyword-based filtering: πŸ”— ISS-004: Implement rate limiting Type: Feature | Priority: Medium Status: Integrated β†’ IMPL-003 - Integrated: 2025-09-06 | Task: impl-3.json + Integrated: 2025-09-06 | Task: IMPL-3.json ``` ## Summary Stats diff --git a/.claude/commands/workflow/plan-deep.md b/.claude/commands/workflow/plan-deep.md index 3ed6d0ff..fe54c831 100644 --- a/.claude/commands/workflow/plan-deep.md +++ b/.claude/commands/workflow/plan-deep.md @@ -90,9 +90,9 @@ Task(action-planning-agent): - Execute comprehensive Gemini CLI analysis (4 dimensions) - Skip PRD processing (no PRD provided) - Skip session inheritance (standalone planning) - - Force MULTI_STEP_ANALYSIS flag = true + - Force FLOW_CONTROL flag = true - Set pre_analysis = multi-step array format with comprehensive analysis steps - - Generate hierarchical task decomposition (max 2 levels: impl-N.M) + - Generate hierarchical task decomposition (max 2 levels: IMPL-N.M) - Create detailed IMPL_PLAN.md with subtasks - Generate TODO_LIST.md for tracking @@ -126,7 +126,7 @@ def process_plan_deep_command(input): TASK: {task_description} MANDATORY FLAGS: - - MULTI_STEP_ANALYSIS = true + - FLOW_CONTROL = true - pre_analysis = multi-step array format for comprehensive pre-analysis - FORCE_PARALLEL_ANALYSIS = true - SKIP_PRD = true diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 97e6d5e8..ddc76edc 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -17,6 +17,10 @@ Creates actionable implementation plans with intelligent input source detection. ## Core Principles **File Structure:** @~/.claude/workflows/workflow-architecture.md +**Dependency Context Rules:** +- **For tasks with dependencies**: MUST read previous task summary documents before planning +- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work + ## Usage ```bash /workflow:plan [--AM gemini|codex] @@ -74,36 +78,42 @@ The command automatically detects input type: 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) + - Re-scoping necessity (>10 tasks triggers re-scoping) - Task saturation level (merged vs separated) + - File grouping strategy (cohesive files together) 3. **Quantity Prediction**: Calculate expected: - Total main tasks (IMPL-XXX) - - Subtasks per main task (impl-N.M) + - 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 +- Complexity level: Simple (≀5) | Medium (6-10) | Over-scoped (>10, requires re-scoping) +- Decomposition approach: Flat | Two-level hierarchy | Re-scope required +- Estimated task count: [number] main tasks, [number] total leaf tasks (max 10) - Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json) +- **Re-scoping recommendation**: If >10 tasks, provide guidance for breaking into iterations **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 +- **Simple**: ≀5 saturated tasks β†’ Direct IMPL_PLAN.md +- **Medium**: 6-10 saturated tasks β†’ IMPL_PLAN.md + TODO_LIST.md +- **Complex**: Exceeding 10 tasks requires re-scoping (maximum enforced) +**10-Task Hard Limit**: Projects exceeding 10 tasks must be re-scoped into smaller iterations **Note**: 1 complex preparation task = 0.5 saturated task for counting ### Task Granularity Principles - **Decompose by function, not by file**: Each task should complete a whole functional unit - **Maintain functional integrity**: Each task produces independently runnable or testable functionality -- **Implement related components together**: UI, logic, tests and other related parts in the same task +- **Group related files together**: Keep related files (UI, logic, tests, config) in same task +- **File cohesion rule**: Files that work together should be modified in the same task - **Avoid technical step decomposition**: Don't make "create file" or "add function" as separate tasks +- **Maximum 10 tasks**: Hard limit enforced; re-scope if exceeded ### Task Decomposition Anti-patterns + ❌ **Wrong Example - File/Step-based Decomposition**: - IMPL-001: Create database model - IMPL-002: Create API endpoint @@ -111,9 +121,18 @@ The command automatically detects input type: - IMPL-004: Add routing configuration - IMPL-005: Write unit tests -βœ… **Correct Example - Function-based Decomposition**: -- IMPL-001: Implement user authentication feature (includes model, API, UI, tests) -- IMPL-002: Implement data export functionality (includes processing logic, UI, file generation) +❌ **Wrong Example - Same File Split Across Tasks**: +- IMPL-001: Add authentication routes to routes/auth.js +- IMPL-002: Add user validation to routes/auth.js +- IMPL-003: Add session handling to routes/auth.js + +βœ… **Correct Example - Function-based with File Cohesion**: +- IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, middleware/auth.js, tests/auth.test.js) +- IMPL-002: Implement data export functionality (includes services/export.js, routes/export.js, components/ExportButton.jsx, utils/fileGenerator.js, tests/export.test.js) + +βœ… **Correct Example - Related Files Grouped**: +- IMPL-001: User management system (includes User model, UserController, UserService, user routes, user tests) +- IMPL-002: Product catalog system (includes Product model, ProductController, catalog components, product tests) ### Task Generation with Saturation Control *Using decomposition strategy determined in Pre-Planning Analysis:* @@ -152,45 +171,53 @@ Three analysis levels available: 3. Populates task paths automatically ### Task Saturation Assessment -Evaluates whether to merge preparation and execution: +Evaluates whether to merge preparation and execution within 10-task limit: **Default Merge Principles** (Saturated Tasks): - All components of the same functional module -- Frontend and backend paired implementation -- Features with their corresponding tests +- Related files that work together (UI, logic, tests, config) +- Features with their corresponding tests and documentation - Configuration with its usage code - Multiple small interdependent functions +- Files that share common interfaces or data structures **Only Separate Tasks When**: -- Completely independent functional modules (no shared code) -- Independent services with different tech stacks (e.g., separate frontend/backend deployment) +- Completely independent functional modules (no shared code or interfaces) +- Independent services with different tech stacks (e.g., separate deployment units) - Modules requiring different expertise (e.g., ML model training vs Web development) - Large features with clear sequential dependencies +- **Critical**: Would exceed 10-task limit otherwise -**Task Examples**: -- **Merged Example**: "IMPL-001: Implement user authentication system (includes JWT management, API endpoints, UI components, and tests)" -- **Separated Example**: "IMPL-001: Design cross-service authentication architecture" + "IMPL-002: Implement frontend authentication module" + "IMPL-003: Implement backend authentication service" +**File Cohesion Examples**: +- **Merged**: "IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, tests/auth.test.js)" +- **Separated**: "IMPL-001: User service authentication" + "IMPL-002: Admin dashboard authentication" (different user contexts) + +**10-Task Compliance**: Always prioritize related file grouping to stay within limit ### Task Breakdown Process -- **Automatic decomposition**: Only when task count >15 are tasks broken into subtasks (impl-N.M format) +- **Automatic decomposition**: Only when task count >10 triggers re-scoping (not decomposition) - **Function-based decomposition**: Split by independent functional boundaries, not by technical layers - **Container tasks**: Parent tasks with subtasks become containers (marked with β–Έ in TODO_LIST) - **Smart decomposition**: AI analyzes task title to suggest logical functional subtask structure - **Complete unit principle**: Each subtask must still represent a complete functional unit - **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 +- **Maximum depth**: 2 levels (IMPL-N.M) to maintain manageable hierarchy +- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping -### 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") +### Flow Control Field Requirements +- **flow_control**: Universal process manager containing: + - `pre_analysis`: Array of sequential process steps with: + - `step`: Unique identifier for the step + - `action`: Human-readable description + - `command`: Executable command with embedded context variables (e.g., `${variable_name}`) + - `output_to`: Variable name to store step results (optional for final steps) + - `on_error`: Error handling strategy + - `implementation_approach`: Brief one-line strategy description + - `target_files`: Array of "file:function:lines" format strings +- **Auto-generation**: Creates flow based on task type and complexity +- **Required fields**: meta (type, agent), context (requirements, focus_paths, acceptance, depends_on), flow_control +- **Focus paths format**: Array of strings (e.g., ["src/auth", "tests/auth", "config/auth.json"]) ## Session Check Process ⚠️ **CRITICAL**: Check for existing active session before planning @@ -208,9 +235,9 @@ Evaluates whether to merge preparation and execution: - Used by: `/workflow:execute` for context loading - Contains: Requirements, task overview, success criteria -- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/impl-*.json` +- **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 + - Contains: Complete task details with 7-field structure including flow_control process manager - **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md` - Used by: `/workflow:execute` for status tracking @@ -233,7 +260,7 @@ Evaluates whether to merge preparation and execution: ``` ### Optional TODO_LIST.md (Auto-triggered) -Created when complexity > simple or task count > 5 +Created when complexity > simple or task count > 3 **TODO_LIST Structure**: Uses unified hierarchical list format - Container tasks (with subtasks) marked with `β–Έ` symbol @@ -258,18 +285,20 @@ Generated in .task/ directory when decomposition enabled ### Recommended Task Patterns #### Complete Feature Implementation -"Implement user management system" - includes CRUD operations, permissions, UI components, API endpoints, and tests +"Implement user management system" - includes all related files: models/User.js, controllers/UserController.js, routes/users.js, components/UserList.jsx, services/UserService.js, tests/user.test.js #### End-to-End Features -"Add Excel export functionality" - includes data processing, file generation, download API, UI buttons, and error handling +"Add Excel export functionality" - includes cohesive file set: services/ExportService.js, utils/excelGenerator.js, routes/export.js, components/ExportButton.jsx, middleware/downloadHandler.js, tests/export.test.js #### System Integration -"Integrate payment gateway" - includes API integration, order processing, payment flows, webhook handling, and testing +"Integrate payment gateway" - includes integration files: services/PaymentService.js, controllers/PaymentController.js, models/Payment.js, components/PaymentForm.jsx, webhooks/paymentWebhook.js, tests/payment.test.js #### Problem Resolution -"Fix and optimize search functionality" - includes bug fixes, performance optimization, UI improvements, and related tests +"Fix and optimize search functionality" - includes related files: services/SearchService.js, utils/searchOptimizer.js, components/SearchBar.jsx, controllers/SearchController.js, tests/search.test.js #### Module Development -"Create notification system" - includes email/SMS sending, template management, subscription handling, and admin interface +"Create notification system" - includes module files: services/NotificationService.js, models/Notification.js, templates/emailTemplates.js, components/NotificationCenter.jsx, workers/notificationQueue.js, tests/notification.test.js -**System ensures**: Unified planning interface with intelligent input detection and function-based task granularity \ No newline at end of file +**File Cohesion Principle**: Each task includes ALL files that work together to deliver the complete functionality + +**System ensures**: Unified planning interface with intelligent input detection, function-based task granularity, file cohesion enforcement, and 10-task maximum limit \ No newline at end of file diff --git a/.claude/commands/workflow/resume.md b/.claude/commands/workflow/resume.md index ed9fc005..90f7171b 100644 --- a/.claude/commands/workflow/resume.md +++ b/.claude/commands/workflow/resume.md @@ -18,6 +18,10 @@ Intelligently resumes interrupted workflows with automatic detection of interrup ## Core Principles **File Structure:** @~/.claude/workflows/workflow-architecture.md +**Dependency Context Rules:** +- **For tasks with dependencies**: MUST read previous task summary documents before resuming +- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work + ## Usage ```bash /workflow:resume [--from TASK-ID] [--retry] [--skip TASK-ID] [--force] @@ -152,7 +156,7 @@ function detect_interruption(): ```bash # Reconstruct complete agent context from interruption point Task(subagent_type="code-developer", - prompt="[RESUME_CONTEXT] [MULTI_STEP_ANALYSIS] Resume impl-1.2: Implement JWT authentication + prompt="[RESUME_CONTEXT] [FLOW_CONTROL] Resume impl-1.2: Implement JWT authentication RESUMPTION CONTEXT: - Interruption Type: agent_timeout @@ -160,6 +164,7 @@ Task(subagent_type="code-developer", - Completed Tasks: impl-1.1 (auth schema design) - Current Task State: in_progress - Recovery Strategy: retry_with_enhanced_context + - Interrupted at Flow Step: analyze_patterns AVAILABLE CONTEXT: - Completed Task Summaries: .workflow/WFS-user-auth/.summaries/impl-1.1-summary.md @@ -167,20 +172,28 @@ Task(subagent_type="code-developer", - Task Definition: .workflow/WFS-user-auth/.task/impl-1.2.json - Session State: .workflow/WFS-user-auth/workflow-session.json - PRE-ANALYSIS REQUIREMENTS: - $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.implementation.pre_analysis[] | "- " + .action + " (" + .method + "): " + .template') + FLOW CONTROL RECOVERY: + Resume from step: analyze_patterns + $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.flow_control.pre_analysis[] | "- Step: " + .step + " | Action: " + .action + " | Command: " + .command') - CONTINUATION INSTRUCTIONS: - 1. Review previous completion summaries for context - 2. Check current codebase state against expected progress - 3. Identify any changes since last execution - 4. Resume from detected interruption point - 5. Complete remaining task objectives + CONTEXT RECOVERY STEPS: + 1. MANDATORY: Read previous task summary documents for all dependencies + 2. Load dependency summaries from context.depends_on + 3. Restore previous step outputs if available + 4. Resume from interrupted flow control step + 5. Execute remaining steps with accumulated context + 6. Generate comprehensive summary with dependency outputs - Focus Paths: $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) - Analysis Command: ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"", + Focus Paths: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.context.focus_paths[]') + Target Files: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.flow_control.target_files[]') - description="Resume interrupted task with complete context reconstruction") + IMPORTANT: + 1. Resume flow control from interrupted step with error recovery + 2. Ensure context continuity through step chain + 3. Create enhanced summary for dependent tasks + 4. Update progress tracking upon successful completion", + + description="Resume interrupted task with flow control step recovery") ``` ### 4. Resume Coordination with TodoWrite @@ -197,7 +210,7 @@ Task(subagent_type="code-developer", ## Resume Execution Plan - [x] **TASK-001**: [Completed] Design auth schema (impl-1.1) -- [ ] **TASK-002**: [RESUME] [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement JWT authentication (impl-1.2) +- [ ] **TASK-002**: [RESUME] [Agent: code-developer] [FLOW_CONTROL] Implement JWT authentication (impl-1.2) - [ ] **TASK-003**: [Pending] [Agent: code-review-agent] Review implementations (impl-1.3) - [ ] **TASK-004**: Update session state and mark workflow complete @@ -326,10 +339,34 @@ Task(subagent_type="code-developer", ## Advanced Resume Features +### Step-Level Recovery +- **Flow Control Interruption Detection**: Identify which flow control step was interrupted +- **Step Context Restoration**: Restore accumulated context up to interruption point +- **Partial Step Recovery**: Resume from specific flow control step +- **Context Chain Validation**: Verify context continuity through step sequence + +#### Step-Level Resume Options +```bash +# Resume from specific flow control step +/workflow:resume --from-step analyze_patterns impl-1.2 + +# Retry specific step with enhanced context +/workflow:resume --retry-step gather_context impl-1.2 + +# Skip failing step and continue with next +/workflow:resume --skip-step analyze_patterns impl-1.2 +``` + +### Enhanced Context Recovery +- **Dependency Summary Integration**: Automatic loading of prerequisite task summaries +- **Variable State Restoration**: Restore step output variables from previous execution +- **Command State Recovery**: Detect partial command execution and resume appropriately +- **Error Context Preservation**: Maintain error information for improved retry strategies + ### Checkpoint System -- **Automatic Checkpoints**: Created after each successful task completion -- **Checkpoint Validation**: Verify codebase state matches expected progress -- **Rollback Capability**: Option to resume from previous valid checkpoint +- **Step-Level Checkpoints**: Created after each successful flow control step +- **Context State Snapshots**: Save variable states at each checkpoint +- **Rollback Capability**: Option to resume from previous valid step checkpoint ### Parallel Task Recovery ```bash diff --git a/.claude/commands/workflow/session/status.md b/.claude/commands/workflow/session/status.md index d4df7953..231b681f 100644 --- a/.claude/commands/workflow/session/status.md +++ b/.claude/commands/workflow/session/status.md @@ -53,7 +53,7 @@ Display comprehensive status information for the currently active workflow sessi πŸ“„ Generated Documents: βœ… IMPL_PLAN.md (Complete) βœ… TODO_LIST.md (Auto-updated) - πŸ“ .task/impl-*.json (5 tasks) + πŸ“ .task/IMPL-*.json (5 tasks) πŸ“Š reports/ (Ready for generation) ``` diff --git a/.claude/workflows/task-core.md b/.claude/workflows/task-core.md index c76ce56f..937e385a 100644 --- a/.claude/workflows/task-core.md +++ b/.claude/workflows/task-core.md @@ -4,122 +4,116 @@ Task commands provide single-execution workflow capabilities with full context awareness, hierarchical organization, and agent orchestration. ## Task JSON Schema -All task files use this unified 10-field structure: +All task files use this simplified 5-field schema (aligned with workflow-architecture.md): ```json { - "id": "impl-1", - "title": "Build authentication module", + "id": "IMPL-1.2", + "title": "Implement JWT authentication", "status": "pending|active|completed|blocked|container", - "type": "feature|bugfix|refactor|test|docs", - "agent": "code-developer|planning-agent|code-review-test-agent", - "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts", + + "meta": { + "type": "feature|bugfix|refactor|test|docs", + "agent": "code-developer|planning-agent|code-review-test-agent" + }, "context": { "requirements": ["JWT authentication", "OAuth2 support"], - "scope": ["src/auth/*", "tests/auth/*"], - "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], - "inherited_from": "WFS-user-auth" - }, - - "relations": { - "parent": null, - "subtasks": ["impl-1.1", "impl-1.2"], - "dependencies": ["impl-0"] - }, - - "execution": { - "attempts": 0, - "last_attempt": null - }, - - "implementation": { - "preparation_complexity": "simple|moderate|complex", - "preparation_tasks": [ - "Review existing auth patterns", - "Check JWT library compatibility" - ], - "estimated_prep_time": "20min", - "files": [ - { - "path": "src/auth/login.ts", - "location": { - "function": "handleLogin", - "lines": "75-120", - "description": "Core login handler function" - }, - "original_code": "// Requires gemini analysis for code extraction", - "modifications": { - "current_state": "Basic password validation", - "proposed_changes": [ - "Add JWT token generation", - "Integrate OAuth2 flow" - ], - "logic_flow": [ - "validateInput() ───► checkCredentials()", - "β—Šβ”€β”€β”€ if valid ───► generateJWT() ───► return token" - ], - "reason": "Meet JWT and OAuth2 requirements", - "expected_outcome": "Flexible login system" - } - } - ], - "context_notes": { - "dependencies": ["jsonwebtoken", "passport-oauth2"], - "affected_modules": ["user-profile", "session-manager"], - "risks": ["Breaking auth middleware changes"], - "performance_considerations": "JWT adds ~5ms latency", - "error_handling": "No sensitive data in errors" + "focus_paths": ["src/auth", "tests/auth", "config/auth.json"], + "acceptance": ["JWT validation works", "OAuth flow complete"], + "parent": "IMPL-1", + "depends_on": ["IMPL-1.1"], + "inherited": { + "from": "IMPL-1", + "context": ["Authentication system design completed"] }, + "shared_context": { + "auth_strategy": "JWT with refresh tokens" + } + }, + + "flow_control": { "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" + "step": "gather_context", + "action": "Read dependency summaries", + "command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)", + "output_to": "auth_design_context", + "on_error": "skip_optional" } + ], + "implementation_approach": { + "task_description": "Implement comprehensive JWT authentication system...", + "modification_points": ["Add JWT token generation...", "..."], + "logic_flow": ["User login request β†’ validate credentials...", "..."] + }, + "target_files": [ + "src/auth/login.ts:handleLogin:75-120", + "src/middleware/auth.ts:validateToken" ] } } ``` -## Implementation Field Details +## Field Structure Details -### preparation_complexity Assessment -- **simple**: <30min prep, ≀3 files, single module β†’ merge with execution -- **moderate**: Cross-module analysis, 30min-2h β†’ consider separation -- **complex**: Architecture design, >2h, >5 modules β†’ separate preparation +### focus_paths Field (within context) +**Purpose**: Specifies concrete project paths relevant to task implementation -### files Array Structure -- **path**: Specific file path -- **location**: Function/class/line range -- **original_code**: Current code (or "requires gemini analysis") -- **modifications**: Detailed change specification +**Format**: +- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]` +- **Concrete paths**: Use actual directory/file names without wildcards +- **Mixed types**: Can include both directories and specific files +- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`) -### context_notes Requirements -- **dependencies**: Required packages -- **affected_modules**: Impact scope -- **risks**: Specific implementation risks -- **performance_considerations**: Performance impact -- **error_handling**: Error handling requirements +**Examples**: +```json +// Authentication system task +"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"] -### pre_analysis Options -- **manual**: User-provided details -- **auto-detected**: System-inferred -- **gemini**: Requires Gemini CLI analysis -- **codex**: Requires Codex CLI analysis +// UI component task +"focus_paths": ["src/components/Button", "src/styles", "tests/components"] +``` + +### flow_control Field Structure +**Purpose**: Universal process manager for task execution + +**Components**: +- **pre_analysis**: Array of sequential process steps +- **implementation_approach**: Task execution strategy +- **target_files**: Specific files to modify in "file:function:lines" format + +**Step Structure**: +```json +{ + "step": "gather_context", + "action": "Human-readable description", + "command": "bash(executable command with [variables])", + "output_to": "variable_name", + "on_error": "skip_optional|fail|retry_once|manual_intervention" +} +``` ## Hierarchical System ### Task Hierarchy Rules -- **Format**: impl-N (main), impl-N.M (subtasks) +- **Format**: IMPL-N (main), IMPL-N.M (subtasks) - uppercase required - **Maximum Depth**: 2 levels only +- **10-Task Limit**: Hard limit enforced across all tasks - **Container Tasks**: Parents with subtasks (not executable) - **Leaf Tasks**: No subtasks (executable) +- **File Cohesion**: Related files must stay in same task + +### Task Complexity Classifications +- **Simple**: ≀5 tasks, single-level tasks, direct execution +- **Medium**: 6-10 tasks, two-level hierarchy, context coordination +- **Over-scope**: >10 tasks requires project re-scoping into iterations + +### Complexity Assessment Rules +- **Creation**: System evaluates and assigns complexity +- **10-task limit**: Hard limit enforced - exceeding requires re-scoping +- **Execution**: Can upgrade (Simpleβ†’Mediumβ†’Over-scope), triggers re-scoping +- **Override**: Users can manually specify complexity within 10-task limit ### Status Rules - **pending**: Ready for execution @@ -143,7 +137,7 @@ Tasks inherit from: 3. `IMPL_PLAN.md` - Planning document ### File Locations -- **Task JSON**: `.workflow/WFS-[topic]/.task/impl-*.json` +- **Task JSON**: `.workflow/WFS-[topic]/.task/IMPL-*.json` (uppercase required) - **Session State**: `.workflow/WFS-[topic]/workflow-session.json` - **Planning Doc**: `.workflow/WFS-[topic]/IMPL_PLAN.md` - **Progress**: `.workflow/WFS-[topic]/TODO_LIST.md` @@ -163,19 +157,22 @@ Each agent receives tailored context: - **test-agent**: Files to test, logic flows to validate - **review-agent**: Quality standards, security considerations -## Paths Field Format +## Deprecated Fields -### Structure -Semicolon-separated list of concrete paths: +### Legacy paths Field +**Deprecated**: The semicolon-separated `paths` field has been replaced by `context.focus_paths` array. + +**Old Format** (no longer used): ```json "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts" ``` -### Selection Strategy -- **Directories**: Relevant module directories -- **Specific Files**: Explicitly mentioned files -- **No Wildcards**: Use concrete paths only -- **Focus Scope**: Only task-related paths +**New Format** (use this instead): +```json +"context": { + "focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"] +} +``` ## Validation Rules @@ -184,7 +181,9 @@ Semicolon-separated list of concrete paths: 2. Task status allows operation 3. Dependencies are met 4. Active workflow session exists -5. Implementation field is complete +5. All 5 core fields present (id, title, status, meta, context, flow_control) +6. Total task count ≀ 10 (hard limit) +7. File cohesion maintained in focus_paths ### Hierarchy Validation - Parent-child relationships valid diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index f74c252c..3adaa1f3 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.claude/workflows/workflow-architecture.md @@ -1,179 +1,85 @@ # Workflow Architecture -## Overview +## Overview & Core Principles -This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition. +This document defines a streamlined workflow system architecture featuring **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition. -## Core Architecture Principles +### Design Philosophy +- **JSON-first data model** - JSON files are single source of truth; markdown is generated views +- **Marker-based sessions** - Ultra-simple active session tracking via marker files +- **Unified structure** - Same file template for all workflows, created on-demand +- **Dynamic decomposition** - Tasks break down as needed during execution +- **On-demand creation** - Files and directories created only when required +- **Agent autonomy** - Complete context preserved for independent execution -### Key Design Decisions -- **JSON files are the single source of truth** - All markdown documents are read-only generated views -- **Marker files for session tracking** - Ultra-simple active session management -- **Unified file structure definition** - Same structure template for all workflows, created on-demand -- **Dynamic task decomposition** - Subtasks created as needed during execution -- **On-demand file creation** - Directories and files created only when required -- **Agent-agnostic task definitions** - Complete context preserved for autonomous execution +## Data Architecture -## Session Management +### JSON-Only Data Model +**Core Principle**: JSON files are the authoritative source; markdown documents are read-only generated views. -### Active Session Marker System -**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]` - -```bash -.workflow/ -β”œβ”€β”€ WFS-oauth-integration/ # Session directory (paused) -β”œβ”€β”€ WFS-user-profile/ # Session directory (paused) -β”œβ”€β”€ WFS-bug-fix-123/ # Session directory (completed) -└── .active-WFS-user-profile # Marker file (indicates active session) -``` - -**Marker File Benefits**: -- **Zero Parsing**: File existence check is atomic and instant -- **Atomic Operations**: File creation/deletion is naturally atomic -- **Visual Discovery**: `ls .workflow/.active-*` shows active session immediately -- **Simple Switching**: Delete old marker + create new marker = session switch - -### Session Operations - -#### Detect Active Session -```bash -active_session=$(find .workflow -name ".active-*" | head -1) -if [ -n "$active_session" ]; then - session_name=$(basename "$active_session" | sed 's/^\.active-//') - echo "Active session: $session_name" -fi -``` - -#### Switch Session -```bash -find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature -``` - -### Individual Session Tracking -Each session directory contains `workflow-session.json`: - -```json -{ - "session_id": "WFS-[topic-slug]", - "project": "feature description", - "type": "simple|medium|complex", - "current_phase": "PLAN|IMPLEMENT|REVIEW", - "status": "active|paused|completed", - "progress": { - "completed_phases": ["PLAN"], - "current_tasks": ["impl-1", "impl-2"] - } -} -``` - -## Data Model - -### JSON-Only Architecture -**JSON files (.task/impl-*.json) are the only authoritative source of task state. All markdown documents are read-only generated views.** - -- **Task State**: Stored exclusively in JSON files +- **Task State**: Stored exclusively in `.task/IMPL-*.json` files - **Documents**: Generated on-demand from JSON data - **No Synchronization**: Eliminates bidirectional sync complexity - **Performance**: Direct JSON access without parsing overhead ### Task JSON Schema -All task files use this 10-field schema: +All task files use this simplified 5-field schema: ```json { - "id": "impl-1", - "title": "Build authentication module", + "id": "IMPL-1.2", + "title": "Implement JWT authentication", "status": "pending|active|completed|blocked|container", - "type": "feature|bugfix|refactor|test|docs", - "agent": "code-developer|planning-agent|code-review-test-agent", - "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts", - + + "meta": { + "type": "feature|bugfix|refactor|test|docs", + "agent": "code-developer|planning-agent|code-review-test-agent" + }, + "context": { "requirements": ["JWT authentication", "OAuth2 support"], - "scope": ["src/auth/*", "tests/auth/*"], - "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], - "inherited_from": "WFS-user-auth" - }, - - "relations": { - "parent": null, - "subtasks": ["impl-1.1", "impl-1.2"], - "dependencies": ["impl-0"] - }, - - "execution": { - "attempts": 0, - "last_attempt": null - }, - - "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", - "location": { - "function": "handleLogin", - "lines": "75-120", - "description": "Core logic of login handler function" - }, - "original_code": "// Related code not provided, requires gemini analysis", - "modifications": { - "current_state": "Currently using simple password validation", - "proposed_changes": [ - "Add JWT token generation logic", - "Integrate OAuth2 authentication flow", - "Enhance error handling mechanisms" - ], - "logic_flow": [ - "validateInput() ───► checkCredentials()", - "β—Šβ”€β”€β”€ if valid ───► generateJWT() ───► return token", - "β—Šβ”€β”€β”€ if OAuth ───► redirectToProvider() ───► handleCallback()", - "β—Šβ”€β”€β”€ if error ───► logError() ───► return errorResponse" - ], - "reason": "Meet JWT and OAuth2 authentication requirements, enhance security", - "expected_outcome": "Flexible login system supporting multiple authentication methods" - } - } - ], - "context_notes": { - "dependencies": ["jsonwebtoken", "passport-oauth2"], - "affected_modules": ["user-profile", "session-manager"], - "risks": [ - "Need to update authentication middleware for all API endpoints", - "May affect existing user sessions", - "Require database migration to add token storage table" - ], - "performance_considerations": "JWT validation will add approximately 5ms latency", - "error_handling": "Ensure sensitive information is not leaked in error responses" + "focus_paths": ["src/auth", "tests/auth", "config/auth.json"], + "acceptance": ["JWT validation works", "OAuth flow complete"], + "parent": "IMPL-1", + "depends_on": ["IMPL-1.1"], + "inherited": { + "from": "IMPL-1", + "context": ["Authentication system design completed"] }, + "shared_context": { + "auth_strategy": "JWT with refresh tokens" + } + }, + + "flow_control": { "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" + "step": "gather_context", + "action": "Read dependency summaries", + "command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)", + "output_to": "auth_design_context", + "on_error": "skip_optional" } + ], + "implementation_approach": { + "task_description": "Implement comprehensive JWT authentication system...", + "modification_points": ["Add JWT token generation...", "..."], + "logic_flow": ["User login request β†’ validate credentials...", "..."] + }, + "target_files": [ + "src/auth/login.ts:handleLogin:75-120", + "src/middleware/auth.ts:validateToken" ] } } ``` -### Paths Field Details +### Focus Paths Field Details -The **paths** field specifies concrete project paths (folders and files) relevant to the task implementation: +The **focus_paths** field within **context** specifies concrete project paths relevant to the task implementation: -#### Path Format -- **Semicolon-separated list**: `"folder1;folder2;specific_file.ts"` +#### Focus Paths Format +- **Array of strings**: `["folder1", "folder2", "specific_file.ts"]` - **Concrete paths**: Use actual directory/file names without wildcards - **Mixed types**: Can include both directories and specific files - **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`) @@ -187,193 +93,226 @@ The **paths** field specifies concrete project paths (folders and files) relevan #### Examples ```json // Authentication system task -"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts" +"focus_paths": ["src/auth", "tests/auth", "config/auth.json", "src/middleware/auth.ts"] // UI component task -"paths": "src/components/Button;src/styles;tests/components" +"focus_paths": ["src/components/Button", "src/styles", "tests/components"] -// Database migration task -"paths": "migrations;src/models;config/database.json" +// Database migration task +"focus_paths": ["migrations", "src/models", "config/database.json"] ``` -### Implementation Field Details +### Flow Control Field Details -The **implementation** field provides detailed code implementation guidance with 4 core components: +The **flow_control** field serves as a universal process manager for task execution with comprehensive flow orchestration: -#### files Array - Detailed File Information -- **path**: File path or filename -- **location**: Specific code location (function name, class name, line range) -- **original_code**: Original code snippet to be modified (mark as "requires gemini analysis" if not obtained) -- **modifications**: Modification details - - **current_state**: Brief description of current code state - - **proposed_changes**: Step-by-step list of modification points - - **logic_flow**: Data flow and call relationship diagram - - **reason**: Modification rationale and objectives - - **expected_outcome**: Expected results +#### pre_analysis Array - Sequential Process Steps +Each step contains: +- **step**: Unique identifier for the step +- **action**: Human-readable description of what the step does +- **command**: Executable command wrapped in `bash()` with embedded context variables (e.g., `bash(command with [variable_name])`) +- **output_to**: Variable name to store step results (optional for final steps) +- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`) +- **success_criteria**: Optional validation criteria (e.g., `exit_code:0`) -#### 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 +#### Context Flow Management +- **Variable Accumulation**: Each step can reference outputs from previous steps via `[variable_name]` +- **Context Inheritance**: Steps can use dependency summaries and parent task context +- **Pipeline Processing**: Results flow sequentially through the analysis chain -#### 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"] +#### Variable Reference Format +- **Context Variables**: Use `[variable_name]` to reference step outputs +- **Task Properties**: Use `[depends_on]`, `[focus_paths]` to reference task JSON properties +- **Bash Compatibility**: Avoids conflicts with bash `${}` variable expansion -#### estimated_prep_time - Time Estimation -- String format time estimate (e.g., "20min", "2h", "half-day") -- Helps determine if preparation should be merged with execution +#### Command Types Supported +- **CLI Analysis**: `bash(~/.claude/scripts/gemini-wrapper -p 'prompt')` +- **Agent Execution**: `bash(codex --full-auto exec 'task description')` +- **Shell Commands**: `bash(cat)`, `bash(grep)`, `bash(find)`, `bash(custom scripts)` +- **Context Processing**: `bash(file reading)`, `bash(dependency loading)`, `bash(context merging)` -#### context_notes - Implementation Context Information -- **dependencies**: Required dependency packages or modules -- **affected_modules**: Other modules that will be affected -- **risks**: Potential risk points and cascading effects -- **performance_considerations**: Performance impact assessment -- **error_handling**: Error handling requirements +#### Error Handling Strategies +- **skip_optional**: Continue execution, step result is empty +- **fail**: Stop execution, mark task as failed +- **retry_once**: Retry step once, then fail if still unsuccessful +- **manual_intervention**: Pause execution for manual review -#### 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 -- **auto-detected**: Auto-detected based on task type and context +#### Example Flow Control Patterns -### Hierarchical Task System -**Maximum Depth**: 2 levels (impl-N.M format) - -``` -impl-1 # Main task -impl-1.1 # Subtask of impl-1 (dynamically created) -impl-1.2 # Another subtask of impl-1 -impl-2 # Another main task -impl-2.1 # Subtask of impl-2 (dynamically created) +**Pattern 1: Multi-Step Analysis** +```json +"pre_analysis": [ + { + "step": "gather_dependencies", + "command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md; done)", + "output_to": "dependency_context" + }, + { + "step": "analyze_codebase", + "command": "bash(gemini -p '@{[focus_paths]} using context: [dependency_context]')", + "output_to": "codebase_analysis" + } +] ``` -**Task Status Rules**: -- **Container tasks**: Parent tasks with subtasks (cannot be directly executed) -- **Leaf tasks**: Only these can be executed directly +**Pattern 2: Direct Implementation** +```json +"pre_analysis": [ + { + "step": "implement", + "command": "bash(codex --full-auto exec 'Implement [title] in [focus_paths]')" + } +] +``` + +#### Benefits of Flow Control +- **Universal Process Manager**: Handles any type of analysis or implementation flow +- **Context Accumulation**: Builds comprehensive context through step chain +- **Error Recovery**: Granular error handling at step level +- **Command Flexibility**: Supports any executable command or agent +- **Dependency Integration**: Automatic loading of prerequisite task results + +### Task Hierarchy +**Structure**: Maximum 2 levels (IMPL-N.M format) + +``` +IMPL-1 # Main task +IMPL-1.1 # Subtask (dynamically created) +IMPL-1.2 # Another subtask +IMPL-2 # Another main task +IMPL-2.1 # Subtask (dynamically created) +``` + +**Rules**: +- **Container tasks**: Parent tasks with subtasks (cannot execute directly) +- **Leaf tasks**: Only executable tasks - **Status inheritance**: Parent status derived from subtask completion -## File Structure +## Session Management -### Unified File Structure -All workflows use the same file structure definition regardless of complexity. **Directories and files are created on-demand as needed**, not all at once during initialization. +### Active Session Marker System +**Ultra-Simple Tracking**: `.workflow/.active-[session-name]` + +```bash +.workflow/ +β”œβ”€β”€ WFS-oauth-integration/ # Session directory (paused) +β”œβ”€β”€ WFS-user-profile/ # Session directory (paused) +β”œβ”€β”€ WFS-bug-fix-123/ # Session directory (completed) +└── .active-WFS-user-profile # Marker file (active session) +``` + +**Benefits**: +- **Zero Parsing**: File existence check is atomic +- **Atomic Operations**: File creation/deletion is naturally atomic +- **Visual Discovery**: `ls .workflow/.active-*` shows active session +- **Simple Switching**: Delete old + create new marker + +### Session Operations + +```bash +# Detect active session +active_session=$(find .workflow -name ".active-*" | head -1) +if [ -n "$active_session" ]; then + session_name=$(basename "$active_session" | sed 's/^\.active-//') + echo "Active session: $session_name" +fi + +# Switch session +find .workflow -name ".active-*" -delete && touch .workflow/.active-WFS-new-feature +``` + +### Session State +Each session directory contains `workflow-session.json`: + +```json +{ + "session_id": "WFS-[topic-slug]", + "project": "feature description", + "type": "simple|medium|complex", + "current_phase": "PLAN|IMPLEMENT|REVIEW", + "status": "active|paused|completed", + "progress": { + "completed_phases": ["PLAN"], + "current_tasks": ["IMPL-1", "IMPL-2"] + } +} +``` + +## File Organization + +### Unified Structure +All workflows use the same structure regardless of complexity. **Files created on-demand only.** -#### Complete Structure Reference ``` .workflow/WFS-[topic-slug]/ -β”œβ”€β”€ workflow-session.json # Session metadata and state (REQUIRED) -β”œβ”€β”€ [.brainstorming/] # Optional brainstorming phase (created when needed) -β”œβ”€β”€ [.chat/] # CLI interaction sessions (created when analysis is run) -β”‚ β”œβ”€β”€ chat-*.md # Saved chat sessions -β”‚ └── analysis-*.md # Analysis results +β”œβ”€β”€ workflow-session.json # Session state (REQUIRED) β”œβ”€β”€ 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 -└── .task/ # Task definitions (REQUIRED) - β”œβ”€β”€ impl-*.json # Main task definitions - └── impl-*.*.json # Subtask definitions (created dynamically) +β”œβ”€β”€ .task/ # Task definitions (REQUIRED) +β”‚ β”œβ”€β”€ IMPL-*.json # Main task definitions +β”‚ └── IMPL-*.*.json # Subtask definitions (dynamic) +β”œβ”€β”€ [.brainstorming/] # Brainstorming phase (on-demand) +β”œβ”€β”€ [.chat/] # CLI sessions (on-demand) +β”‚ β”œβ”€β”€ chat-*.md # Saved chat sessions +β”‚ └── analysis-*.md # Analysis results +└── [.summaries/] # Task summaries (on-demand) + β”œβ”€β”€ IMPL-*.md # Main task summaries + └── IMPL-*.*.md # Subtask summaries ``` -#### Creation Strategy -- **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory -- **On-Demand Creation**: Other directories created when first needed: - - `.brainstorming/` β†’ When brainstorming phase is initiated - - `.chat/` β†’ When CLI analysis commands are executed - - `.summaries/` β†’ When first task is completed -- **Dynamic Files**: Subtask JSON files created during task decomposition +### Creation Strategy +- **Initial**: Only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, `.task/` +- **On-Demand**: + - `.brainstorming/` β†’ When brainstorming initiated + - `.chat/` β†’ When analysis commands executed + - `.summaries/` β†’ When first task completed -### File Naming Conventions +### Naming Conventions +- **Sessions**: `WFS-[topic-slug]` (lowercase with hyphens) +- **Conflicts**: Add `-NNN` suffix if needed +- **Documents**: Standard names (`workflow-session.json`, `IMPL_PLAN.md`, etc.) +- **Chat**: `chat-analysis-*.md` +- **Summaries**: `IMPL-[task-id]-summary.md` -#### Session Identifiers -**Format**: `WFS-[topic-slug]` -- Convert topic to lowercase with hyphens (e.g., "User Auth System" β†’ `WFS-user-auth-system`) -- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`) +## Workflow Classification -#### Document Naming -- `workflow-session.json` - Session state (required) -- `IMPL_PLAN.md` - Planning document (required) -- `TODO_LIST.md` - Progress tracking (auto-generated when needed) -- Chat sessions: `chat-analysis-*.md` -- Task summaries: `IMPL-[task-id]-summary.md` +### Complexity Types +**Based on task count and decomposition needs:** -## Complexity Classification +| Type | Tasks | Depth | Behavior | +|------|-------|-------|----------| +| **Simple** | ≀5 | 1 level | Direct execution, minimal decomposition | +| **Medium** | 6-10 | 2 levels | Moderate decomposition, context coordination | +| **Over-scope** | >10 | Re-scope | Requires project re-scoping into iterations | -### Task Complexity Rules -**Complexity is determined by task count and decomposition needs:** +### Characteristics -| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior | -|------------|------------|----------------|----------------------| -| **Simple** | <5 tasks | 1 level (impl-N) | Direct execution, minimal decomposition | -| **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 | +**Simple**: Bug fixes, small features, config changes +- Single-level tasks, direct execution, ≀5 tasks -### Simple Workflows -**Characteristics**: Direct implementation tasks with clear, limited scope -- **Examples**: Bug fixes, small feature additions, configuration changes -- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed -- **Agent Coordination**: Direct execution without complex orchestration +**Medium**: New features, API endpoints, schema changes +- Two-level hierarchy, context coordination, 6-10 tasks -### Medium Workflows -**Characteristics**: Feature implementation requiring moderate task breakdown -- **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 +**Over-scope**: Major features exceeding 10 tasks +- Requires re-scoping into smaller iterations, never >10 tasks -### Complex Workflows -**Characteristics**: System-wide changes requiring detailed decomposition -- **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 +### Assessment Rules +- **Creation**: System evaluates and assigns complexity +- **10-task limit**: Hard limit enforced - exceeding requires re-scoping +- **Execution**: Can upgrade (Simpleβ†’Mediumβ†’Over-scope), triggers re-scoping +- **Override**: Users can manually specify complexity within 10-task limit -### Automatic Assessment & Upgrades -- **During Creation**: System evaluates requirements and assigns complexity -- **During Execution**: Can upgrade (Simpleβ†’Mediumβ†’Complex) but never downgrade -- **Override Allowed**: Users can specify higher complexity manually +## Task Execution Framework -## Document Templates +### Agent Integration -### IMPL_PLAN.md -Generated based on task complexity and requirements. Contains overview, requirements, and task structure. - -### TODO_LIST.md Template -```markdown -# Tasks: [Session Topic] - -## 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-002**: [Simple Task] β†’ [πŸ“‹](./.task/impl-002.json) | [βœ…](./.summaries/IMPL-002.md) - -β–Έ **IMPL-003**: [Main Task Group] β†’ [πŸ“‹](./.task/impl-003.json) - - [ ] **IMPL-003.1**: [Subtask] β†’ [πŸ“‹](./.task/impl-003.1.json) - - [ ] **IMPL-003.2**: [Subtask] β†’ [πŸ“‹](./.task/impl-003.2.json) - -## Status Legend -- `β–Έ` = Container task (has subtasks) -- `- [ ]` = Pending leaf task -- `- [x]` = Completed leaf task -- Maximum 2 levels: Main tasks and subtasks only - -## Notes -[Optional notes] -``` - -## Agent Integration - -### Agent Assignment -Based on task type and title keywords: -- **Planning tasks** β†’ planning-agent -- **Implementation** β†’ code-developer +**Assignment Rules** (based on task type/keywords): +- **Planning** β†’ planning-agent +- **Implementation** β†’ code-developer - **Testing** β†’ code-review-test-agent - **Review** β†’ review-agent -### Execution Context -Agents receive complete task JSON plus workflow context: +**Execution Context** (agents receive): ```json { "task": { /* complete task JSON */ }, @@ -383,63 +322,47 @@ Agents receive complete task JSON plus workflow context: } } ``` +## Operations Guide +### Basic Operations -## Data Operations - -### Session Initialization ```bash -# Create minimal required structure +# Session initialization mkdir -p .workflow/WFS-topic-slug/.task echo '{"session_id":"WFS-topic-slug",...}' > .workflow/WFS-topic-slug/workflow-session.json echo '# Implementation Plan' > .workflow/WFS-topic-slug/IMPL_PLAN.md echo '# Tasks' > .workflow/WFS-topic-slug/TODO_LIST.md -``` -### Task Creation -```bash -echo '{"id":"impl-1","title":"New task",...}' > .task/impl-1.json -``` +# Task creation +echo '{"id":"IMPL-1","title":"New task",...}' > .task/IMPL-1.json -### Directory Creation (On-Demand) -```bash -# Create directories only when needed -mkdir -p .brainstorming # When brainstorming is initiated -mkdir -p .chat # When analysis commands are run -mkdir -p .summaries # When first task completes -``` +# Task updates +jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json -### Task Updates -```bash -jq '.status = "active"' .task/impl-1.json > temp && mv temp .task/impl-1.json -``` - -### Document Generation -```bash -# Generate TODO_LIST.md from current JSON state +# Document generation generate_todo_list_from_json .task/ ``` -## Validation and Error Handling - -### Task Integrity Rules +### 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. **Depth Limits**: Maximum 2 levels deep -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. **Pre-Analysis Source**: pre_analysis must be multi-step array format with action, template, method +2. **Format**: IMPL-N[.M] pattern (max 2 levels) +3. **References**: Parent IDs must exist as JSON files +4. **Fields**: All 5 core fields required (id, title, status, meta, context, flow_control) +5. **Paths**: context.focus_paths must contain valid project paths +6. **Dependencies**: context.depends_on task IDs must exist + +### Error Recovery +- **Missing Session**: Remove orphaned active marker +- **Multiple Active**: Keep newest, remove others +- **Corrupted Session**: Recreate from template +- **Broken Hierarchy**: Reconstruct parent-child relationships -### Session Consistency Checks ```bash -# Validate active session integrity +# Session consistency check active_marker=$(find .workflow -name ".active-*" | head -1) if [ -n "$active_marker" ]; then session_name=$(basename "$active_marker" | sed 's/^\.active-//') session_dir=".workflow/$session_name" - if [ ! -d "$session_dir" ]; then echo "⚠️ Orphaned active marker, removing..." rm "$active_marker" @@ -447,12 +370,46 @@ if [ -n "$active_marker" ]; then fi ``` -### Recovery Strategies -- **Missing Session Directory**: Remove orphaned active marker -- **Multiple Active Markers**: Keep newest, remove others -- **Corrupted Session File**: Recreate from template -- **Broken Task Hierarchy**: Reconstruct parent-child relationships +## Reference Templates + +### Integration Points +- **[Component Name]**: [how to use/integrate] +- **[API Endpoint]**: [usage details] +- **[Configuration]**: [location and format] + +## Testing Verification +- [Test type]: [location/results] +- [Validation]: [confirmation method] +- [Quality checks]: [what was verified] + +## Notes for Future Tasks +[Any important considerations, limitations, or follow-up items] +``` +### TODO List (TODO_LIST.md) +```markdown +# Tasks: [Session Topic] + +## 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-002**: [Simple Task] β†’ [πŸ“‹](./.task/IMPL-002.json) | [βœ…](./.summaries/IMPL-002.md) + +β–Έ **IMPL-003**: [Main Task Group] β†’ [πŸ“‹](./.task/IMPL-003.json) + - [ ] **IMPL-003.1**: [Subtask] β†’ [πŸ“‹](./.task/IMPL-003.1.json) + - [ ] **IMPL-003.2**: [Subtask] β†’ [πŸ“‹](./.task/IMPL-003.2.json) + +## Status Legend +- `β–Έ` = Container task (has subtasks) +- `- [ ]` = Pending leaf task +- `- [x]` = Completed leaf task +- Maximum 2 levels: Main tasks and subtasks only + +## Notes +[Optional notes] +``` --- -**System ensures**: Unified workflow architecture with ultra-fast session management, JSON-only data model, and unified file structure for all workflows regardless of complexity. \ No newline at end of file +**System Design**: Unified workflow architecture featuring ultra-fast session management, JSON-only data model, and consistent file structure across all workflow types. \ No newline at end of file