claude-code-workflow 6.2.5 → 6.2.6

package/.claude/commands/task/create.md

@@ -0,0 +1,152 @@
+---
+name: create
+description: Generate task JSON from natural language description with automatic file pattern detection, scope inference, and dependency analysis
+argument-hint: "\"task title\""
+---
+
+# Task Create Command (/task:create)
+
+## Overview
+Creates new implementation tasks with automatic context awareness and ID generation.
+
+## Core Principles
+**Task System:** @~/.claude/workflows/task-core.md
+
+## Core Features
+
+### Automatic Behaviors
+- **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"
+- **Agent Assignment**: Suggests agent based on task type
+- **Session Integration**: Updates workflow session stats
+
+### Context Awareness
+- Validates active workflow session exists
+- Avoids duplicate task IDs
+- Inherits session requirements and scope
+- Suggests task relationships
+
+## Usage
+
+### Basic Creation
+```bash
+/task:create "Build authentication module"
+```
+
+Output:
+```
+Task created: IMPL-1
+Title: Build authentication module
+Type: feature
+Agent: code-developer
+Status: pending
+```
+
+### Task Types
+- `feature` - New functionality (default)
+- `bugfix` - Bug fixes
+- `refactor` - Code improvements
+- `test` - Test implementation
+- `docs` - Documentation
+
+## Task Creation Process
+
+1. **Session Validation**: Check active workflow session
+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
+6. **File Creation**: Save JSON to .task/ directory
+7. **Session Update**: Update workflow stats
+
+**Task Schema**: See @~/.claude/workflows/task-core.md for complete JSON structure
+
+## Implementation Field Setup
+
+### Auto-Population Strategy
+- **Detailed info**: Extract from task description and scope
+- **Missing info**: Mark `pre_analysis` as multi-step array format for later pre-analysis
+- **Basic structure**: Initialize with standard template
+
+### Analysis Triggers
+When implementation details incomplete:
+```bash
+Task requires analysis for implementation details
+Suggest running: gemini analysis for file locations and dependencies
+```
+
+## File Management
+
+### JSON Task File
+- **Location**: `.task/IMPL-[N].json` in active session
+- **Content**: Complete task with implementation field
+- **Updates**: Session stats only
+
+### Simple Process
+1. Validate session and inputs
+2. Generate task JSON
+3. Update session stats
+4. Notify completion
+
+## Context Inheritance
+
+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)
+
+## Agent Assignment
+
+Based on task type and title keywords:
+- **Build/Implement** → @code-developer
+- **Design/Plan** → @planning-agent
+- **Test Generation** → @code-developer (type: "test-gen")
+- **Test Execution/Fix** → @test-fix-agent (type: "test-fix")
+- **Review/Audit** → @universal-executor (optional, only when explicitly requested)
+
+## Validation Rules
+
+1. **Session Check** - Active workflow session required
+2. **Duplicate Check** - Avoid similar task titles
+3. **ID Uniqueness** - Auto-increment task IDs
+4. **Schema Validation** - Ensure proper JSON structure
+
+## Error Handling
+
+```bash
+# No workflow session
+No active workflow found
+Use: /workflow init "project name"
+
+# Duplicate task
+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
+```
+
+## Examples
+
+### Feature Task
+```bash
+/task:create "Implement user authentication"
+
+Created IMPL-1: Implement user authentication
+Type: feature
+Agent: code-developer
+Status: pending
+```
+
+### Bug Fix
+```bash
+/task:create "Fix login validation bug" --type=bugfix
+
+Created IMPL-2: Fix login validation bug
+Type: bugfix
+Agent: code-developer
+Status: pending
+```

package/.claude/commands/task/execute.md

@@ -0,0 +1,270 @@
+---
+name: execute
+description: Execute task JSON using appropriate agent (@doc-generator/@implementation-agent/@test-agent) with pre-analysis context loading and status tracking
+argument-hint: "task-id"
+---
+
+## Command Overview: /task:execute
+
+**Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
+
+
+## Execution Modes
+
+-   **auto (Default)**
+    -   Fully autonomous execution with automatic agent selection.
+    -   Provides progress updates at each checkpoint.
+    -   Automatically completes the task when done.
+-   **guided**
+    -   Executes step-by-step, requiring user confirmation at each checkpoint.
+    -   Allows for dynamic adjustments and manual review during the process.
+-   **review**
+    -   Optional manual review using `@universal-executor`.
+    -   Used only when explicitly requested by user.
+
+## Agent Selection Logic
+
+The system determines the appropriate agent for a task using the following logic.
+
+```pseudo
+FUNCTION select_agent(task, agent_override):
+    // A manual override always takes precedence.
+    // Corresponds to the --agent=<agent-type> flag.
+    IF agent_override IS NOT NULL:
+        RETURN agent_override
+
+    // If no override, select based on keywords in the task title.
+    ELSE:
+        CASE task.title:
+            WHEN CONTAINS "Build API", "Implement":
+                RETURN "@code-developer"
+            WHEN CONTAINS "Design schema", "Plan":
+                RETURN "@planning-agent"
+            WHEN CONTAINS "Write tests", "Generate tests":
+                RETURN "@code-developer" // type: test-gen
+            WHEN CONTAINS "Execute tests", "Fix tests", "Validate":
+                RETURN "@test-fix-agent" // type: test-fix
+            WHEN CONTAINS "Review code":
+                RETURN "@universal-executor" // Optional manual review
+            DEFAULT:
+                RETURN "@code-developer" // Default agent
+        END CASE
+END FUNCTION
+```
+
+## Core Execution Protocol
+
+`Pre-Execution` -> `Execution` -> `Post-Execution`
+
+### Pre-Execution Protocol
+
+`Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite`
+
+-   **Validation**: Checks for the task's JSON file in `.task/` and resolves its dependencies.
+-   **Context Preparation**: Loads task and workflow context, preparing it for the selected agent.
+-   **Session Context Injection**: Provides workflow directory paths to agents for TODO_LIST.md and summary management.
+-   **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`.
+
+### Post-Execution Protocol
+
+`Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity`
+
+-   Updates status in the task's JSON file and `TODO_LIST.md`.
+-   Creates a summary in `.summaries/`.
+-   Stores outputs and syncs progress across the entire workflow session.
+
+### Task & Subtask Execution Logic
+
+This logic defines how single, multiple, or parent tasks are handled.
+
+```pseudo
+FUNCTION execute_task_command(task_id, mode, parallel_flag):
+    // Handle parent tasks by executing their subtasks.
+    IF is_parent_task(task_id):
+        subtasks = get_subtasks(task_id)
+        EXECUTE_SUBTASK_BATCH(subtasks, mode)
+
+    // Handle wildcard execution (e.g., IMPL-001.*)
+    ELSE IF task_id CONTAINS "*":
+        subtasks = find_matching_tasks(task_id)
+        IF parallel_flag IS true:
+            EXECUTE_IN_PARALLEL(subtasks)
+        ELSE:
+            FOR each subtask in subtasks:
+                EXECUTE_SINGLE_TASK(subtask, mode)
+  
+    // Default case for a single task ID.
+    ELSE:
+        EXECUTE_SINGLE_TASK(task_id, mode)
+END FUNCTION
+```
+
+### Error Handling & Recovery Logic
+
+```pseudo
+FUNCTION pre_execution_check(task):
+    // Ensure dependencies are met before starting.
+    IF task.dependencies ARE NOT MET:
+        LOG_ERROR("Cannot execute " + task.id)
+        LOG_INFO("Blocked by: " + unmet_dependencies)
+        HALT_EXECUTION()
+
+FUNCTION on_execution_failure(checkpoint):
+    // Provide user with recovery options upon failure.
+    LOG_WARNING("Execution failed at checkpoint " + checkpoint)
+    PRESENT_OPTIONS([
+        "Retry from checkpoint",
+        "Retry from beginning",
+        "Switch to guided mode",
+        "Abort execution"
+    ])
+    AWAIT user_input
+    // System performs the selected action.
+END FUNCTION
+```
+
+
+### Simplified Context Structure (JSON)
+
+This is the simplified data structure loaded to provide context for task execution.
+
+```json
+{
+  "task": {
+    "id": "IMPL-1",
+    "title": "Build authentication module",
+    "type": "feature",
+    "status": "active",
+    "agent": "code-developer",
+    "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"]
+    },
+    "implementation": {
+      "files": [
+        {
+          "path": "src/auth/login.ts",
+          "location": {
+            "function": "authenticateUser",
+            "lines": "25-65",
+            "description": "Main authentication logic"
+          },
+          "original_code": "// Code snippet extracted via gemini analysis",
+          "modifications": {
+            "current_state": "Basic password authentication only",
+            "proposed_changes": [
+              "Add JWT token generation",
+              "Implement OAuth2 callback handling",
+              "Add multi-factor authentication support"
+            ],
+            "logic_flow": [
+              "validateCredentials() ───► checkUserExists()",
+              "◊─── if password ───► generateJWT() ───► return token",
+              "◊─── if OAuth ───► validateOAuthCode() ───► exchangeForToken()",
+              "◊─── if MFA ───► sendMFACode() ───► awaitVerification()"
+            ],
+            "reason": "Support modern authentication standards and security requirements",
+            "expected_outcome": "Comprehensive authentication system supporting multiple methods"
+          }
+        }
+      ],
+      "context_notes": {
+        "dependencies": ["jsonwebtoken", "passport", "speakeasy"],
+        "affected_modules": ["user-session", "auth-middleware", "api-routes"],
+        "risks": [
+          "Breaking changes to existing login endpoints",
+          "Token storage and rotation complexity",
+          "OAuth provider configuration dependencies"
+        ],
+        "performance_considerations": "JWT validation adds ~10ms per request, OAuth callbacks may timeout",
+        "error_handling": "Ensure sensitive authentication errors don't leak user enumeration data"
+      },
+      "pre_analysis": [
+        {
+          "action": "analyze patterns",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt",
+          "method": "gemini"
+        }
+      ]
+    }
+  },
+  "workflow": {
+    "session": "WFS-user-auth",
+    "phase": "IMPLEMENT",
+    "session_context": {
+      "workflow_directory": ".workflow/active/WFS-user-auth/",
+      "todo_list_location": ".workflow/active/WFS-user-auth/TODO_LIST.md",
+      "summaries_directory": ".workflow/active/WFS-user-auth/.summaries/",
+      "task_json_location": ".workflow/active/WFS-user-auth/.task/"
+    }
+  },
+  "execution": {
+    "agent": "code-developer",
+    "mode": "auto",
+    "attempts": 0
+  }
+}
+```
+
+### Agent-Specific Context
+
+Different agents receive context tailored to their function, including implementation details:
+
+**`@code-developer`**: 
+- Complete implementation.files array with file paths and locations
+- original_code snippets and proposed_changes for precise modifications
+- logic_flow diagrams for understanding data flow
+- Dependencies and affected modules for integration planning
+- Performance and error handling considerations
+
+**`@planning-agent`**: 
+- High-level requirements, constraints, success criteria
+- Implementation risks and mitigation strategies
+- Architecture implications from implementation.context_notes
+
+**`@test-fix-agent`**:
+- Test files to execute from task.context.focus_paths
+- Source files to fix from implementation.files[].path
+- Expected behaviors from implementation.modifications.logic_flow
+- Error conditions to validate from implementation.context_notes.error_handling
+- Performance requirements from implementation.context_notes.performance_considerations
+
+**`@universal-executor`**:
+- Used for optional manual reviews when explicitly requested
+- Code quality standards and implementation patterns
+- Security considerations from implementation.context_notes.risks
+- Dependency validation from implementation.context_notes.dependencies
+- Architecture compliance checks
+
+### Simplified File Output
+
+-   **Task JSON File (`.task/<task-id>.json`)**: Updated with status and last attempt time only.
+-   **Session File (`workflow-session.json`)**: Updated task stats (completed count).
+-   **Summary File**: Generated in `.summaries/` upon completion (optional).
+
+### Simplified Summary Template
+
+Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`.
+
+```markdown
+# Task Summary: IMPL-1 Build Authentication Module
+
+## What Was Done
+- Created src/auth/login.ts with JWT validation
+- Added tests in tests/auth.test.ts
+
+## Execution Results
+- **Agent**: code-developer
+- **Status**: completed
+
+## Files Modified
+- `src/auth/login.ts` (created)
+- `tests/auth.test.ts` (created)
+```