diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index cb26b061..be7dfe39 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -151,9 +151,17 @@ Generate individual `.task/IMPL-*.json` files with: "agent": "@code-developer" }, "context": { - "requirements": ["from analysis_results"], - "focus_paths": ["src/paths"], - "acceptance": ["measurable criteria"], + "requirements": [ + "Implement 3 features: [authentication, authorization, session management]", + "Create 5 files: [auth.service.ts, auth.controller.ts, auth.middleware.ts, auth.types.ts, auth.test.ts]", + "Modify 2 existing functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]" + ], + "focus_paths": ["src/auth", "tests/auth"], + "acceptance": [ + "3 features implemented: verify by npm test -- auth (exit code 0)", + "5 files created: verify by ls src/auth/*.ts | wc -l = 5", + "Test coverage >=80%: verify by npm test -- --coverage | grep auth" + ], "depends_on": ["IMPL-N"], "artifacts": [ { @@ -181,23 +189,50 @@ Generate individual `.task/IMPL-*.json` files with: { "step": 1, "title": "Load and analyze role analyses", - "description": "Load role analyses from artifacts and extract requirements", - "modification_points": ["Load role analyses", "Extract requirements and design patterns"], - "logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"], + "description": "Load 3 role analysis files and extract quantified requirements", + "modification_points": [ + "Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]", + "Extract 15 requirements from role analyses", + "Parse 8 architecture decisions from system-architect analysis" + ], + "logic_flow": [ + "Read 3 role analyses from artifacts inventory", + "Parse architecture decisions (8 total)", + "Extract implementation requirements (15 total)", + "Build consolidated requirements list" + ], "depends_on": [], "output": "synthesis_requirements" }, { "step": 2, "title": "Implement following specification", - "description": "Implement task requirements following consolidated role analyses", - "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"], - "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"], + "description": "Implement 3 features across 5 files following consolidated role analyses", + "modification_points": [ + "Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]", + "Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]", + "Implement 3 core features: [JWT authentication, role-based authorization, session management]" + ], + "logic_flow": [ + "Apply 15 requirements from [synthesis_requirements]", + "Implement 3 features across 5 new files (600 total lines)", + "Modify 2 existing functions (30 lines total)", + "Write 25 test cases covering all features", + "Validate against 3 acceptance criteria" + ], "depends_on": [1], "output": "implementation" } ], - "target_files": ["file:function:lines", "path/to/NewFile.ts"] + "target_files": [ + "src/auth/auth.service.ts", + "src/auth/auth.controller.ts", + "src/auth/auth.middleware.ts", + "src/auth/auth.types.ts", + "tests/auth/auth.test.ts", + "src/users/users.service.ts:validateUser:45-60", + "src/utils/utils.ts:hashPassword:120-135" + ] } } ``` @@ -285,6 +320,35 @@ Use `analysis_results.complexity` or task count to determine structure: - **Re-scope required**: Maximum 10 tasks hard limit - If analysis_results contains >10 tasks, consolidate or request re-scoping +## Quantification Requirements (MANDATORY) + +**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications. + +**Core Rules**: +1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly +2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]` +3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`) +4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers) +5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements + +**Standard Formats**: +- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"` +- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"` +- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"` + +**Validation Checklist** (Apply to every generated task JSON): +- [ ] Every requirement contains explicit count or enumerated list +- [ ] Every acceptance criterion is measurable with verification command +- [ ] Every modification_point specifies exact targets (files/functions/lines) +- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts) +- [ ] Each implementation step has its own acceptance criteria + +**Examples**: +- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"` +- ❌ BAD: `"Implement new commands"` +- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"` +- ❌ BAD: `"All commands implemented successfully"` + ## Quality Standards **Planning Principles:** @@ -305,6 +369,7 @@ Use `analysis_results.complexity` or task count to determine structure: ## Key Reminders **ALWAYS:** +- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations - **Use provided context package**: Extract all information from structured context - **Respect memory-first rule**: Use provided content (already loaded from memory/file) - **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control @@ -313,6 +378,7 @@ Use `analysis_results.complexity` or task count to determine structure: - **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded - **Use session paths**: Construct all paths using provided session_id - **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries) +- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs **NEVER:** - Load files directly (use provided context package instead) diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index 846e3897..a59e88ee 100644 --- a/.claude/commands/workflow/tools/task-generate-agent.md +++ b/.claude/commands/workflow/tools/task-generate-agent.md @@ -179,84 +179,47 @@ If conflict_risk was medium/high, modifications have been applied to: ### Quantification Requirements (MANDATORY) -**CRITICAL**: All task specifications MUST include explicit counts and enumerations to eliminate ambiguity. +**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications. **Core Rules**: -1. **Extract Counts from Analysis**: If analysis mentions "implement features", search for HOW MANY and list them explicitly -2. **Enforce Explicit Lists**: Every deliverable MUST use format \`{count} {type}: [{explicit_list}]\` -3. **Make Acceptance Measurable**: Replace vague terms ("complete", "comprehensive") with verifiable criteria -4. **Quantify Modification Points**: Each point must specify exact targets (files, functions, features with line counts) -5. **Step-Level Verification**: Each implementation step includes its own verification criteria +1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly +2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]` +3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`) +4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers) +5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements -**Mandatory Task JSON Formats**: +**Standard Formats**: +- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"` +- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"` +- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"` -**Requirements Format**: -\`\`\` -"requirements": [ - "GOOD: Implement 5 session commands: [session-start, session-resume, session-list, session-complete, session-archive]", - "GOOD: Create 3 directories: [.workflow/, .task/, .summaries/]", - "BAD: Implement session management system", - "BAD: Complete workflow infrastructure" -] -\`\`\` - -**Acceptance Format**: -\`\`\` -"acceptance": [ - "GOOD: 5 command files created: verify by ls .claude/commands/workflow/session/*.md | wc -l = 5", - "GOOD: 3 directories exist: verify by ls .workflow/ | grep -E '(task|summaries|process)' | wc -l = 3", - "GOOD: Each command contains: usage section + 3 examples + parameter docs", - "BAD: All session commands implemented successfully", - "BAD: Workflow infrastructure complete" -] -\`\`\` - -**Modification Points Format**: -\`\`\` -"modification_points": [ - "GOOD: Create 5 command files in .claude/commands/workflow/session/: [start.md, resume.md, list.md, complete.md, archive.md]", - "GOOD: Modify 2 functions: [executeTask() in executor.ts lines 45-120, validateSession() in validator.ts lines 30-55]", - "BAD: Apply requirements from role analysis", - "BAD: Implement features following specifications" -] -\`\`\` - -**Forbidden Language Patterns** (REJECT these during generation): -- BAD: "Implement feature" -> GOOD: "Implement 3 features: [auth, validation, logging]" -- BAD: "Complete refactoring" -> GOOD: "Refactor 5 files: [file1.ts, file2.ts, ...] (total 800 lines)" -- BAD: "Reorganize structure" -> GOOD: "Move 12 files from old/ to new/ directory structure" -- BAD: "Comprehensive tests" -> GOOD: "Write 25 test cases covering: [scenario1, scenario2, ...] (>=80% coverage)" - -**Quantification Extraction Process** (Apply during Step 2): -1. **Scan Analysis Documents**: Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features") -2. **Enumerate Lists**: Build explicit lists for each deliverable (no "..." unless list >20 items) -3. **Assign Verification Methods**: For each deliverable, specify how to verify (bash command, count check, coverage metric) -4. **Flag Ambiguity**: Detect vague language ("complete", "comprehensive", "reorganize") and require quantification - -**Validation Checklist** (Run before generating task JSON): +**Validation Checklist**: - [ ] Every requirement contains explicit count or enumerated list - [ ] Every acceptance criterion is measurable with verification command - [ ] Every modification_point specifies exact targets (files/functions/lines) -- [ ] No vague language in requirements, acceptance, or modification_points +- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts) - [ ] Each implementation step has its own acceptance criteria ### Required Outputs #### 1. Task JSON Files (.task/IMPL-*.json) -**Location**: .workflow/{session-id}/.task/ -**Template**: Read from the template path provided above -**Task JSON Template Loading**: -\`\`\` -Read({template_path}) -\`\`\` +**Location**: `.workflow/{session-id}/.task/` +**Template Path**: Provided by command (agent-mode or cli-mode template) -**Important**: -- Read the template from the path provided in context -- Use the template structure exactly as written -- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths -- Include MCP tool integration in pre_analysis steps +**Key Responsibilities**: +- Read template from provided path: `Read({template_path})` +- Replace placeholder variables with session-specific paths +- Include MCP tool integration in `pre_analysis` steps - Map artifacts based on task domain (UI → ui-designer, Backend → system-architect) +- Apply quantification requirements to all task fields +- Ensure all tasks follow template structure exactly + +**Template Selection** (Pre-selected by command): +- **Agent Mode**: `~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt` +- **CLI Mode**: `~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt` + +**Note**: Agent does NOT choose template - it's pre-selected based on `--cli-execute` flag and provided in context #### 2. IMPL_PLAN.md **Location**: .workflow/{session-id}/IMPL_PLAN.md @@ -344,34 +307,10 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt) - Update workflow-session.json with task count and artifact inventory - Mark session ready for execution -### MCP Enhancement Examples +### MCP Enhancement (Optional) -**Code Index Usage**: -\`\`\`javascript -// Discover authentication-related files -bash(find . -name "*auth*" -type f) - -// Search for OAuth patterns -bash(rg "oauth|jwt|authentication" -g "*.{ts,js}") - -// Get file summary for key components -bash(rg "^(class|function|export|interface)" src/auth/index.ts) -\`\`\` - -**Exa Research Usage**: -\`\`\`javascript -// Get best practices for task implementation -mcp__exa__get_code_context_exa( - query="TypeScript OAuth2 implementation patterns", - tokensNum="dynamic" -) - -// Research specific API usage -mcp__exa__get_code_context_exa( - query="Express.js JWT middleware examples", - tokensNum=5000 -) -\`\`\` +**Code Analysis**: Use `find`, `rg` for file discovery and pattern search +**External Research**: Use `mcp__exa__get_code_context_exa` for best practices and API examples ### Quality Validation diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md index 296f756a..e90e6f4d 100644 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/commands/workflow/tools/task-generate-tdd.md @@ -59,87 +59,23 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact ## Quantification Requirements for TDD (MANDATORY) -**Purpose**: Eliminate ambiguity in TDD task generation by enforcing explicit test case counts, coverage metrics, and implementation scope. +**Purpose**: Eliminate ambiguity by enforcing explicit test case counts, coverage metrics, and implementation scope. **Core Rules**: -1. **Explicit Test Case Counts**: Red phase MUST specify exact number of test cases with enumerated list -2. **Quantified Coverage**: Acceptance criteria MUST include measurable coverage percentage (e.g., ">=85%") -3. **Detailed Implementation Scope**: Green phase MUST enumerate exact files, functions, and line counts -4. **Enumerated Refactoring Targets**: Refactor phase MUST list specific improvements with counts +1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list +2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%") +3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts +4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts -**Test Case Format (Red Phase)**: -``` -"requirements": [ - "GOOD: Red Phase - Write 15 test cases: [test_user_auth_success, test_user_auth_invalid_password, test_user_auth_missing_token, test_session_create, test_session_resume, test_session_expire, test_api_post_valid, test_api_post_invalid, test_api_get_list, test_api_get_item, test_validation_required_fields, test_validation_type_checking, test_error_404, test_error_500, test_integration_full_flow]", - "BAD: Red Phase - Write comprehensive test suite covering all scenarios" -] -``` +**TDD Phase Formats**: +- **Red Phase**: `"Write N test cases: [test1, test2, ...]"` +- **Green Phase**: `"Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"` +- **Refactor Phase**: `"Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"` +- **Acceptance**: `"All N tests pass with >=X% coverage: verify by [test command]"` -**Coverage Format (Acceptance)**: -``` -"acceptance": [ - "GOOD: All 15 tests pass with >=85% coverage: verify by pytest --cov=src/auth --cov-report=term | grep TOTAL", - "GOOD: Test 5 functions: [authenticate(), createSession(), validateToken(), refreshSession(), revokeSession()]", - "BAD: All tests pass with good coverage", - "BAD: Test suite complete" -] -``` +**TDD Cycles Array**: Each cycle must include `test_count`, `test_cases` array, `implementation_scope`, and `expected_coverage` -**Implementation Scope Format (Green Phase)**: -``` -"modification_points": [ - "GOOD: Implement 5 functions in src/auth/service.ts lines 20-180: [authenticate() 20-45, createSession() 50-75, validateToken() 80-100, refreshSession() 105-135, revokeSession() 140-160]", - "GOOD: Create 3 files: [src/auth/service.ts (180 lines), src/auth/models.ts (50 lines), src/auth/utils.ts (30 lines)]", - "BAD: Implement authentication service following requirements", - "BAD: Create necessary files for feature" -] -``` - -**Refactoring Targets Format (Refactor Phase)**: -``` -"modification_points": [ - "GOOD: Apply 4 refactorings: [extract validateInput() helper (15 lines), merge duplicate error handlers (3 occurrences), rename confusing variables (token->authToken in 8 locations), add JSDoc to 5 public functions]", - "BAD: Improve code quality and maintainability", - "BAD: Refactor implementation" -] -``` - -**TDD Cycles Array Format**: -``` -"tdd_cycles": [ - { - "cycle": 1, - "feature": "User authentication with password validation", - "test_count": 5, - "test_cases": [ - "test_auth_valid_credentials", - "test_auth_invalid_password", - "test_auth_missing_username", - "test_auth_account_locked", - "test_auth_password_expired" - ], - "implementation_scope": "Implement authenticate() function in src/auth/service.ts lines 20-65 (45 lines)", - "expected_coverage": ">=90%" - }, - { - "cycle": 2, - "feature": "Session management lifecycle", - "test_count": 6, - "test_cases": [ - "test_session_create", - "test_session_resume", - "test_session_expire", - "test_session_refresh", - "test_session_revoke", - "test_session_concurrent_limit" - ], - "implementation_scope": "Implement 3 functions in src/auth/service.ts lines 70-150: [createSession() 70-95, resumeSession() 100-125, revokeSession() 130-150]", - "expected_coverage": ">=85%" - } -] -``` - -**Validation Checklist** (Run before TDD task generation): +**Validation Checklist**: - [ ] Every Red phase specifies exact test case count with enumerated list - [ ] Every Green phase enumerates files, functions, and estimated line counts - [ ] Every Refactor phase lists specific improvements with counts @@ -220,309 +156,87 @@ For each feature, generate task(s) with ID format: #### Task JSON Structure Reference -**Simple Feature Task (IMPL-N.json)** - Recommended for most features: -```json -{ - "id": "IMPL-N", // Task identifier - "title": "Feature description with TDD", // Human-readable title - "status": "pending", // pending | in_progress | completed | container - "context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package - "meta": { - "type": "feature", // Task type - "agent": "@code-developer", // Assigned agent - "tdd_workflow": true, // REQUIRED: Enables TDD flow - "max_iterations": 3, // Green phase test-fix cycle limit - "use_codex": false // false=manual fixes, true=Codex automated fixes - }, - "context": { - "requirements": [ // Feature requirements with TDD phases (QUANTIFIED) - "Implement user authentication with session management", - "Red: Write 11 test cases: [test_auth_valid, test_auth_invalid_pwd, test_auth_missing_user, test_session_create, test_session_resume, test_session_expire, test_session_refresh, test_session_revoke, test_validation_required, test_error_401, test_integration_full_auth_flow]", - "Green: Implement 5 functions in src/auth/service.ts (160 lines total): [authenticate() 20-50, createSession() 55-80, validateToken() 85-105, refreshSession() 110-135, revokeSession() 140-160]", - "Refactor: Apply 3 improvements: [extract validateInput() helper (12 lines), merge 2 duplicate error handlers, add JSDoc to 5 public functions]" - ], - "tdd_cycles": [ // REQUIRED: Detailed test cycles with counts - { - "cycle": 1, - "feature": "User authentication with password validation", - "test_count": 5, - "test_cases": [ - "test_auth_valid_credentials", - "test_auth_invalid_password", - "test_auth_missing_username", - "test_auth_account_locked", - "test_auth_session_created" - ], - "implementation_scope": "Implement authenticate() function in src/auth/service.ts lines 20-50 (30 lines)", - "expected_coverage": ">=90%" - }, - { - "cycle": 2, - "feature": "Session lifecycle management", - "test_count": 6, - "test_cases": [ - "test_session_create", - "test_session_resume_valid", - "test_session_expire_timeout", - "test_session_refresh_extend", - "test_session_revoke_immediate", - "test_session_concurrent_limit" - ], - "implementation_scope": "Implement 3 functions in src/auth/service.ts lines 55-160: [createSession() 55-80, validateToken() 85-105, refreshSession() 110-135, revokeSession() 140-160]", - "expected_coverage": ">=85%" - } - ], - "focus_paths": ["D:\\project\\src\\path", "./tests/path"], // Absolute or clear relative paths from project root - "acceptance": [ // Success criteria (QUANTIFIED) - "All 11 tests pass: verify by npm test -- tests/auth/ (exit code 0)", - "Test coverage >=85%: verify by npm test -- --coverage | grep TOTAL | awk '{print $4}' >= 85", - "5 functions implemented with proper error handling", - "3 refactoring improvements applied: code passes npm run lint with 0 warnings" - ], - "depends_on": [] // Task dependencies - }, - "flow_control": { - "pre_analysis": [ // OPTIONAL: Pre-execution checks - { - "step": "check_test_framework", - "action": "Verify test framework", - "command": "bash(npm list jest)", - "output_to": "test_framework_info", - "on_error": "warn" - } - ], - "implementation_approach": [ // REQUIRED: 3 TDD phases - { - "step": 1, - "title": "RED Phase: Write failing tests", - "tdd_phase": "red", // REQUIRED: Phase identifier - "description": "Write 11 failing test cases for authentication and session management", - "modification_points": [ - "Create tests/auth/authentication.test.ts with 5 test cases: [test_auth_valid_credentials, test_auth_invalid_password, test_auth_missing_username, test_auth_account_locked, test_auth_session_created]", - "Create tests/auth/session.test.ts with 6 test cases: [test_session_create, test_session_resume_valid, test_session_expire_timeout, test_session_refresh_extend, test_session_revoke_immediate, test_session_concurrent_limit]" - ], - "logic_flow": [ - "Create test file structure: tests/auth/ directory", - "Write 5 authentication test cases in authentication.test.ts", - "Write 6 session management test cases in session.test.ts", - "Verify all 11 tests fail with expected errors" - ], - "acceptance": [ - "11 test cases written: verify by grep -E 'test_.*\\(' tests/auth/*.test.ts | wc -l = 11", - "All tests fail: npm test -- tests/auth/ exits with non-zero status", - "Each test has clear assertion and expected failure reason" - ], - "depends_on": [], - "output": "failing_tests" - }, - { - "step": 2, - "title": "GREEN Phase: Implement to pass tests", - "tdd_phase": "green", // REQUIRED: Phase identifier - "description": "Implement 5 functions (160 lines) in src/auth/service.ts with test-fix cycle", - "modification_points": [ - "Create src/auth/service.ts implementing 5 functions (160 lines total): [authenticate() 20-50, createSession() 55-80, validateToken() 85-105, refreshSession() 110-135, revokeSession() 140-160]", - "Create src/auth/models.ts with 2 interfaces: [User, Session]", - "Create src/auth/utils.ts with 2 helper functions: [hashPassword(), generateToken()]" - ], - "logic_flow": [ - "Implement minimal code for 5 functions", - "Run tests: npm test -- tests/auth/", - "If fail -> Enter iteration loop (max 3):", - " 1. Extract failure messages from test output", - " 2. Use Gemini for bug-fix diagnosis", - " 3. Apply fixes to failing functions", - " 4. Rerun tests", - "If max_iterations reached -> Auto-revert via git reset --hard HEAD" - ], - "acceptance": [ - "All 11 tests pass: npm test -- tests/auth/ exits with status 0", - "5 functions implemented: grep -E '^(export )?function ' src/auth/service.ts | wc -l = 5", - "Test coverage >=85%: npm test -- --coverage | grep TOTAL | awk '{print $4}' >= 85" - ], - "command": "bash(npm test -- tests/auth/)", - "depends_on": [1], - "output": "passing_implementation" - }, - { - "step": 3, - "title": "REFACTOR Phase: Improve code quality", - "tdd_phase": "refactor", // REQUIRED: Phase identifier - "description": "Apply 3 refactoring improvements while maintaining test coverage", - "modification_points": [ - "Extract validateInput() helper function (12 lines) from authenticate() and createSession()", - "Merge 2 duplicate error handlers in session.ts into single handleSessionError() function", - "Add JSDoc comments to 5 public functions: [authenticate(), createSession(), validateToken(), refreshSession(), revokeSession()]" - ], - "logic_flow": [ - "Extract validateInput() helper, update 2 call sites", - "Merge duplicate error handlers, verify 2 usages updated", - "Add JSDoc to 5 functions with @param, @returns, @throws", - "Run tests after each refactoring to ensure green state", - "Run linter: npm run lint (expect 0 warnings)" - ], - "acceptance": [ - "All 11 tests still pass: npm test -- tests/auth/ exits with status 0", - "3 refactorings applied: validateInput() extracted + error handlers merged + 5 JSDoc added", - "Lint passes: npm run lint exits with 0 warnings", - "Test coverage maintained >=85%" - ], - "command": "bash(npm run lint && npm test)", - "depends_on": [2], - "output": "refactored_implementation" - } - ], - "post_completion": [ // OPTIONAL: Final verification - { - "step": "verify_full_tdd_cycle", - "action": "Confirm complete TDD cycle", - "command": "bash(npm test && echo 'TDD complete')", - "output_to": "final_validation", - "on_error": "fail" - } - ], - "error_handling": { // OPTIONAL: Error recovery - "green_phase_max_iterations": { - "action": "revert_all_changes", - "commands": ["bash(git reset --hard HEAD)"], - "report": "Generate failure report" - } - } - } -} -``` +Each TDD task JSON contains complete Red-Green-Refactor cycle with these key fields: -**Key JSON Fields Summary**: -- `meta.tdd_workflow`: Must be `true` -- `meta.max_iterations`: Green phase fix cycle limit (default: 3) -- `meta.use_codex`: Automated fixes (false=manual, true=Codex) -- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor" -- `context.tdd_cycles`: Optional detailed test cycle specifications -- `context.parent`: Required for subtasks (IMPL-N.M) +**Top-Level Fields**: +- `id`: Task identifier (`IMPL-N` or `IMPL-N.M` for subtasks) +- `title`: Feature description with TDD +- `status`: `pending | in_progress | completed | container` +- `context_package_path`: Path to context package +- `meta`: TDD-specific metadata +- `context`: Requirements, cycles, paths, acceptance +- `flow_control`: Pre-analysis, 3 TDD phases, post-completion, error handling + +**Meta Object (TDD-Specific)**: +- `type`: "feature" +- `agent`: "@code-developer" +- `tdd_workflow`: `true` (REQUIRED - enables TDD flow) +- `max_iterations`: Green phase test-fix cycle limit (default: 3) +- `use_codex`: `false` (manual fixes) or `true` (Codex automated fixes) + +**Context Object**: +- `requirements`: Quantified feature requirements with TDD phase details +- `tdd_cycles`: Array of test cycles (each with `test_count`, `test_cases`, `implementation_scope`, `expected_coverage`) +- `focus_paths`: Target directories (absolute or relative from project root) +- `acceptance`: Measurable success criteria with verification commands +- `depends_on`: Task dependencies +- `parent`: Parent task ID (for subtasks only) + +**Flow Control Object**: +- `pre_analysis`: Optional pre-execution checks +- `implementation_approach`: Exactly 3 steps with `tdd_phase` field: + 1. **Red Phase** (`tdd_phase: "red"`): Write failing tests + 2. **Green Phase** (`tdd_phase: "green"`): Implement to pass tests (includes test-fix cycle) + 3. **Refactor Phase** (`tdd_phase: "refactor"`): Improve code quality +- `post_completion`: Optional final verification +- `error_handling`: Error recovery strategies (e.g., auto-revert on max iterations) + +**Implementation Approach Step Structure**: +Each step includes: +- `step`: Step number +- `title`: Phase description +- `tdd_phase`: Phase identifier ("red" | "green" | "refactor") +- `description`: Detailed phase description +- `modification_points`: Quantified changes to make +- `logic_flow`: Step-by-step execution logic +- `acceptance`: Phase-specific acceptance criteria +- `command`: Test/verification command (optional) +- `depends_on`: Previous step dependencies +- `output`: Step output identifier #### IMPL_PLAN.md Structure -Generate IMPL_PLAN.md with 8-section structure: +**Frontmatter** (TDD-specific fields): +- `workflow_type`: "tdd" +- `tdd_workflow`: true +- `feature_count`, `task_count` (≤10 total) +- `task_breakdown`: simple_features, complex_features, total_subtasks +- `test_context`: Path to test-context-package.json (if exists) +- `conflict_resolution`: Path to CONFLICT_RESOLUTION.md (if exists) +- `verification_history`, `phase_progression` -**Frontmatter** (required fields): -```yaml ---- -identifier: WFS-{session-id} -source: "User requirements" | "File: path" -conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md # if exists -context_package: .workflow/{session-id}/.process/context-package.json -context_package_path: .workflow/{session-id}/.process/context-package.json -test_context: .workflow/{session-id}/.process/test-context-package.json # if exists -workflow_type: "tdd" -verification_history: - conflict_resolution: "executed | skipped" # based on conflict_risk - action_plan_verify: "pending" -phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning" -feature_count: N -task_count: N # ≤10 total -task_breakdown: - simple_features: K - complex_features: L - total_subtasks: M -tdd_workflow: true ---- -``` - -**8 Sections Structure**: - -```markdown -# Implementation Plan: {Project Title} - -## 1. Summary -- Core requirements and objectives (2-3 paragraphs) -- TDD-specific technical approach - -## 2. Context Analysis -- CCW Workflow Context (Phase progression, Quality gates) -- Context Package Summary (Focus paths, Test context) -- Project Profile (Type, Scale, Tech Stack, Timeline) -- Module Structure (Directory tree) -- Dependencies (Primary, Testing, Development) -- Patterns & Conventions - -## 3. Brainstorming Artifacts Reference -- Artifact Usage Strategy - - CONFLICT_RESOLUTION.md (if exists - selected resolution strategies) - - role analysis documents (primary reference) - - test-context-package.json (test patterns) - - context-package.json (smart context) -- Artifact Priority in Development - -## 4. Implementation Strategy -- Execution Strategy (TDD Cycles: Red-Green-Refactor) -- Architectural Approach -- Key Dependencies (Task dependency graph) -- Testing Strategy (Coverage targets, Quality gates) - -## 5. TDD Implementation Tasks -- Feature-by-Feature TDD Tasks - - Each task: IMPL-N with internal Red → Green → Refactor - - Dependencies and complexity metrics -- Complex Feature Examples (when subtasks needed) -- TDD Task Breakdown Summary - -## 6. Implementation Plan (Detailed Phased Breakdown) -- Execution Strategy (feature-by-feature sequential) -- Phase breakdown (Phase 1, Phase 2, etc.) -- Resource Requirements (Team, Dependencies, Infrastructure) - -## 7. Risk Assessment & Mitigation -- Risk table (Risk, Impact, Probability, Mitigation, Owner) -- Critical Risks (TDD-specific) -- Monitoring Strategy - -## 8. Success Criteria -- Functional Completeness -- Technical Quality (Test coverage ≥80%) -- Operational Readiness -- TDD Compliance -``` +**8 Sections**: +1. **Summary**: Core requirements, TDD-specific approach +2. **Context Analysis**: CCW workflow context, project profile, module structure, dependencies +3. **Brainstorming Artifacts Reference**: Artifact usage strategy, priority order +4. **Implementation Strategy**: TDD cycles (Red-Green-Refactor), architectural approach, testing strategy +5. **TDD Implementation Tasks**: Feature-by-feature tasks with internal TDD cycles, dependencies +6. **Implementation Plan**: Phased breakdown, resource requirements +7. **Risk Assessment & Mitigation**: Risk table, TDD-specific risks, monitoring +8. **Success Criteria**: Functional completeness, technical quality (≥80% coverage), TDD compliance ### Phase 4: TODO_LIST.md Generation Generate task list with internal TDD phase indicators: -**For Simple Features (1 task per feature)**: -```markdown -## TDD Implementation Tasks - -### Feature 1: {Feature Name} -- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json) - - Internal phases: Red → Green → Refactor - - Dependencies: None - -### Feature 2: {Feature Name} -- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json) - - Internal phases: Red → Green → Refactor - - Dependencies: IMPL-1 -``` - -**For Complex Features (with subtasks)**: -```markdown -### Feature 3: {Complex Feature Name} -▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json) - - [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json) - - Internal phases: Red → Green → Refactor - - [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json) - - Internal phases: Red → Green → Refactor - - Dependencies: IMPL-3.1 -``` +**Structure**: +- Simple features: `- [ ] **IMPL-N**: Feature with TDD` (Internal phases: Red → Green → Refactor) +- Complex features: `▸ **IMPL-N**: Container` with subtasks `- [ ] **IMPL-N.M**: Sub-feature` **Status Legend**: -```markdown -## Status Legend -- ▸ = Container task (has subtasks) -- [ ] = Pending task -- [x] = Completed task -- Red = Write failing tests -- Green = Implement to pass tests (with test-fix cycle) -- Refactor = Improve code quality -``` +- `▸` = Container task (has subtasks) +- `[ ]` = Pending | `[x]` = Completed +- Red → Green → Refactor = TDD phases ### Phase 5: Session State Update @@ -615,12 +329,12 @@ Update workflow-session.json with TDD metadata: ## Integration & Usage -### Command Chain -- **Called By**: `/workflow:tdd-plan` (Phase 4) -- **Calls**: Gemini CLI for TDD breakdown -- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify` +**Command Chain**: +- Called by: `/workflow:tdd-plan` (Phase 4) +- Calls: Gemini CLI for TDD breakdown +- Followed by: `/workflow:execute`, `/workflow:tdd-verify` -### Basic Usage +**Basic Usage**: ```bash # Manual mode (default) /workflow:tools:task-generate-tdd --session WFS-auth @@ -629,38 +343,11 @@ Update workflow-session.json with TDD metadata: /workflow:tools:task-generate-tdd --session WFS-auth --agent ``` -### Expected Output -``` -TDD task generation complete for session: WFS-auth - -Features analyzed: 5 -Total tasks: 5 (1 task per feature with internal TDD cycles) - -Task breakdown: -- Simple features: 4 tasks (IMPL-1 to IMPL-4) -- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2) -- Total task count: 6 (within 10-task limit) - -Structure: -- IMPL-1: User Authentication (Internal: Red → Green → Refactor) -- IMPL-2: Password Reset (Internal: Red → Green → Refactor) -- IMPL-3: Email Verification (Internal: Red → Green → Refactor) -- IMPL-4: Role Management (Internal: Red → Green → Refactor) -- IMPL-5: Payment System (Container) - - IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor) - - IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor) - -Plans generated: -- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section) -- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators) - -TDD Configuration: -- Each task contains complete Red-Green-Refactor cycle -- Green phase includes test-fix cycle (max 3 iterations) -- Auto-revert on max iterations reached - -Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth -``` +**Output**: +- Task JSON files in `.task/` directory (IMPL-N.json format) +- IMPL_PLAN.md with TDD Implementation Tasks section +- TODO_LIST.md with internal TDD phase indicators +- Session state updated with task count and TDD metadata ## Test Coverage Analysis Integration diff --git a/.claude/commands/workflow/tools/task-generate.md b/.claude/commands/workflow/tools/task-generate.md index 6d020ce4..1c35fdaf 100644 --- a/.claude/commands/workflow/tools/task-generate.md +++ b/.claude/commands/workflow/tools/task-generate.md @@ -53,56 +53,23 @@ This command is built on a set of core principles to ensure efficient and reliab **Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications. **Core Rules**: -1. **Extract Counts from Analysis**: If analysis mentions "implement commands", search for HOW MANY and list them explicitly -2. **Enforce Explicit Lists**: Every deliverable MUST use format `{count} {type}: [{explicit_list}]` -3. **Make Acceptance Measurable**: Replace vague terms ("complete", "comprehensive") with verifiable criteria -4. **Quantify Modification Points**: Each point must specify exact targets (files, functions, features) -5. **Step-Level Verification**: Each implementation step includes its own verification criteria +1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly +2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]` +3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`) +4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers) +5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements -**Mandatory Formats**: +**Standard Formats**: -**Requirements Format**: -``` -"requirements": [ - "GOOD: Implement 17 commands: [literature:add, literature:search, ..., context:synthesize]", - "GOOD: Create 5 directories: [literature/, experiment/, data-analysis/, visualization/, context/]", - "BAD: Implement new commands for material management", - "BAD: Reorganize command structure" -] -``` +- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"` +- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"` +- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"` -**Acceptance Format**: -``` -"acceptance": [ - "GOOD: 17 commands implemented: verify by ls .claude/commands/*/*.md | wc -l = 17", - "GOOD: 5 directories created: verify by ls .claude/commands/ | grep -E '(lit|exp|...)' | wc -l = 5", - "GOOD: Each command file contains: usage section, 3+ examples, parameter documentation", - "BAD: All commands implemented successfully", - "BAD: Command structure reorganized logically" -] -``` - -**Modification Points Format**: -``` -"modification_points": [ - "GOOD: Create 5 files: [session-start.md, session-resume.md, session-list.md, session-complete.md, session-archive.md]", - "GOOD: Modify 3 functions: [parseConfig() lines 15-30, validateInput() lines 45-60, executeTask() lines 80-120]", - "BAD: Apply requirements from role analysis", - "BAD: Implement feature following specifications" -] -``` - -**Forbidden Language Patterns**: -- BAD: "Implement feature" -> GOOD: "Implement 3 features: [auth, validation, logging]" -- BAD: "Complete refactoring" -> GOOD: "Refactor 5 files: [file1.ts, file2.ts, ...] (total 800 lines)" -- BAD: "Reorganize structure" -> GOOD: "Move 12 files from old/ to new/ directory structure" -- BAD: "Comprehensive tests" -> GOOD: "Write 25 test cases covering: [scenario1, scenario2, ...] (>=80% coverage)" - -**Validation Checklist** (Run before task generation): +**Validation Checklist**: - [ ] Every requirement contains explicit count or enumerated list - [ ] Every acceptance criterion is measurable with verification command - [ ] Every modification_point specifies exact targets (files/functions/lines) -- [ ] No vague language ("complete", "comprehensive", "reorganize", "refactor") +- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts) - [ ] Each implementation step has its own acceptance criteria ## 4. Execution Flow @@ -251,47 +218,82 @@ function assignExecutionGroups(tasks) { The command produces three key documents and a directory of task files. ### 6.1. Task JSON Schema (`.task/IMPL-*.json`) -This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps. +Each task JSON embeds all necessary context, artifacts, and execution steps using this schema: +**Top-Level Fields**: +- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks) +- `title`: Descriptive task name +- `status`: Task state (`pending|active|completed|blocked|container`) +- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`) +- `meta`: Task metadata +- `context`: Task-specific context and requirements +- `flow_control`: Execution steps and workflow + +**Meta Object**: +- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`) +- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`) +- `execution_group`: Parallelization group ID or null +- `context_signature`: Hash for context-based grouping + +**Context Object**: +- `requirements`: Quantified implementation requirements (with counts and explicit lists) +- `focus_paths`: Target directories/files (absolute or relative paths) +- `acceptance`: Measurable acceptance criteria (with verification commands) +- `parent`: Parent task ID for subtasks +- `depends_on`: Prerequisite task IDs +- `inherited`: Shared patterns and dependencies from parent +- `shared_context`: Tech stack and conventions +- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage + +**Flow Control Object**: +- `pre_analysis`: Context loading and preparation steps + - `load_context_package`: Load smart context and artifact catalog + - `load_role_analysis_artifacts`: Load role analyses dynamically from context package + - `load_planning_context`: Load finalized decisions with resolved conflicts + - `codebase_exploration`: Discover existing patterns + - `analyze_task_patterns`: Identify modification targets +- `implementation_approach`: Execution steps + - **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously) + - **CLI Mode**: Steps include `command` field with CLI tool invocation +- `target_files`: Specific files/functions/lines to modify + +**Key Characteristics**: +- **Quantification**: All requirements/acceptance use explicit counts and enumerations +- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`) +- **Context Intelligence**: References context-package.json for smart context and artifact paths +- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts + +**Example Task JSON**: ```json { - "id": "IMPL-N[.M]", - "title": "Descriptive task name", - "status": "pending|active|completed|blocked|container", - "context_package_path": ".workflow/WFS-[session]/.process/context-package.json", + "id": "IMPL-1", + "title": "Implement feature X with Y components", + "status": "pending", + "context_package_path": ".workflow/WFS-session/.process/context-package.json", "meta": { - "type": "feature|bugfix|refactor|test-gen|test-fix|docs", - "agent": "@code-developer|@test-fix-agent|@universal-executor", - "execution_group": "group-id|null", - "context_signature": "hash-of-focus_paths-and-artifacts" + "type": "feature", + "agent": "@code-developer", + "execution_group": "parallel-abc123", + "context_signature": "hash-value" }, "context": { "requirements": [ - "Implement 5 session commands: [session-start, session-resume, session-list, session-complete, session-archive]", - "Create 3 directories: [.workflow/, .task/, .summaries/]", - "Modify 2 functions: [executeTask() in executor.ts lines 45-120, validateSession() in validator.ts lines 30-55]" + "Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]", + "Create 3 directories: [dir1/, dir2/, dir3/]", + "Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]" ], - "focus_paths": ["D:\\project\\src\\module\\path", "./tests/module/path"], + "focus_paths": ["D:\\project\\src\\module", "./tests/module"], "acceptance": [ - "5 command files created: verify by ls .claude/commands/workflow/session/*.md | wc -l = 5", - "3 directories exist: verify by ls .workflow/ | grep -E '(task|summaries|process)' | wc -l = 3", - "Each command file contains: usage section + 3 examples + parameter docs + agent invocation", - "All tests pass: pytest tests/workflow/session/ --cov=src/workflow/session --cov-report=term (>=85% coverage)" + "5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5", + "3 directories exist: verify by ls -d dir*/ | wc -l = 3", + "All tests pass: pytest tests/ --cov=src/module (>=80% coverage)" ], - "parent": "IMPL-N", - "depends_on": ["IMPL-N.M"], - "inherited": {"shared_patterns": [], "common_dependencies": []}, - "shared_context": {"tech_stack": [], "conventions": []}, + "depends_on": [], "artifacts": [ { - "path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}", + "path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md", "priority": "highest", - "usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert." - }, - { - "path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md", - "priority": "high", - "usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place" + "usage": "Architecture decisions and API specifications" } ] }, @@ -299,18 +301,14 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut "pre_analysis": [ { "step": "load_context_package", - "action": "Load context package for artifact paths", - "note": "Context package path is now at top-level field: context_package_path", - "commands": [ - "Read({{context_package_path}})" - ], + "action": "Load context package for artifact paths and smart context", + "commands": ["Read({{context_package_path}})"], "output_to": "context_package", "on_error": "fail" }, { "step": "load_role_analysis_artifacts", - "action": "Load role analyses from context-package.json (supports multiple files per role)", - "note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.", + "action": "Load role analyses from context-package.json", "commands": [ "Read({{context_package_path}})", "Extract(brainstorm_artifacts.role_analyses[].files[].path)", @@ -318,73 +316,36 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut ], "output_to": "role_analysis_artifacts", "on_error": "skip_optional" - }, - { - "step": "load_planning_context", - "action": "Load plan-generated context intelligence with resolved conflicts", - "note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.", - "commands": [ - "Read({{context_package_path}})", - "Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)" - ], - "output_to": "planning_context", - "on_error": "fail", - "usage_guidance": { - "context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)", - "guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)" - } - }, - { - "step": "codebase_exploration", - "action": "Explore codebase using native tools", - "command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")", - "output_to": "codebase_structure" - }, - { - "step": "analyze_task_patterns", - "action": "Analyze existing code patterns and identify modification targets", - "commands": [ - "bash(cd \"[focus_paths]\")", - "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")" - ], - "output_to": "task_context_with_targets", - "on_error": "fail" } ], "implementation_approach": [ { "step": 1, - "title": "Implement task following role analyses and context", - "description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.", + "title": "Implement feature following role analyses", + "description": "Implement feature X using requirements from role analyses and context package", "modification_points": [ - "Create 5 command files in .claude/commands/workflow/session/: [start.md, resume.md, list.md, complete.md, archive.md]", - "Modify 2 functions following role analysis requirements: [executeTask() in src/workflow/executor.ts lines 45-120, validateSession() in src/workflow/validator.ts lines 30-55]", - "Implement 3 features from synthesis enhancements: [session lifecycle hooks, automatic status tracking, rollback on error]", - "Apply 2 design decisions from guidance-specification.md: [use Git-based versioning for sessions, integrate with MaterialDB for context persistence]", - "Follow 4 existing patterns from context-package.json: [SlashCommand structure, agent invocation via Task tool, TodoWrite for progress tracking, conventional commit messages]", - "Add 8 test cases covering: [start workflow, resume existing, list all sessions, complete session, archive session, error handling, validation checks, integration with MaterialDB]" + "Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]", + "Modify funcA() in file1.ts lines 10-25: add validation logic", + "Modify funcB() in file2.ts lines 40-60: integrate with new API" ], "logic_flow": [ - "Load role analyses (requirements, design, enhancements from synthesis)", - "Load guidance-specification.md (finalized decisions with resolved conflicts if any)", - "Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)", - "Extract requirements and design decisions from role documents", - "Review synthesis enhancements and clarifications", - "Use finalized decisions (conflicts already resolved if applicable)", - "Identify modification targets using context package", - "Implement following role requirements and design specs", - "Consult role artifacts for detailed specifications when needed", + "Load role analyses and context package", + "Extract requirements and design decisions", + "Implement commands following existing patterns", + "Update functions with new logic", "Validate against acceptance criteria" ], "depends_on": [], "output": "implementation" } ], - "target_files": ["file:function:lines"] + "target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"] } } ``` +**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`). + ### 6.2. IMPL_PLAN.md Structure This document provides a high-level overview of the entire implementation plan. @@ -678,194 +639,7 @@ Artifacts are mapped to tasks based on their relevance to the task's domain. This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses. -## 8. CLI Execute Mode Details -When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command. - -**Key Points**: -- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array - - **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity -- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field - -### Example 1: Agent Mode - Simple Task (Default, No Command) -```json -{ - "id": "IMPL-001", - "title": "Implement user authentication module", - "context_package_path": ".workflow/WFS-session/.process/context-package.json", - "context": { - "depends_on": [], - "focus_paths": ["src/auth"], - "requirements": ["JWT-based authentication", "Login and registration endpoints"], - "acceptance": [ - "JWT token generation working", - "Login and registration endpoints implemented", - "Tests passing with >70% coverage" - ] - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_role_analyses", - "action": "Load role analyses from context-package.json", - "commands": [ - "Read({{context_package_path}})", - "Extract(brainstorm_artifacts.role_analyses[].files[].path)", - "Read(each extracted path)" - ], - "output_to": "role_analyses", - "on_error": "fail" - }, - { - "step": "load_context", - "action": "Load context package for project structure", - "commands": ["Read({{context_package_path}})"], - "output_to": "context_pkg", - "on_error": "fail" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Implement JWT-based authentication", - "description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns", - "modification_points": [ - "Create auth service with JWT generation", - "Implement login endpoint with credential validation", - "Implement registration endpoint with user creation", - "Add JWT middleware for route protection" - ], - "logic_flow": [ - "User registers → validate input → hash password → create user", - "User logs in → validate credentials → generate JWT → return token", - "Protected routes → validate JWT → extract user → allow access" - ], - "depends_on": [], - "output": "auth_implementation" - } - ], - "target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"] - } -} -``` - -### Example 2: CLI Execute Mode - Single Codex Step -```json -{ - "id": "IMPL-002", - "title": "Implement user authentication module", - "context_package_path": ".workflow/WFS-session/.process/context-package.json", - "context": { - "depends_on": [], - "focus_paths": ["src/auth"], - "requirements": ["JWT-based authentication", "Login and registration endpoints"], - "acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"] - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_role_analyses", - "action": "Load role analyses from context-package.json", - "commands": [ - "Read({{context_package_path}})", - "Extract(brainstorm_artifacts.role_analyses[].files[].path)", - "Read(each extracted path)" - ], - "output_to": "role_analyses", - "on_error": "fail" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Implement authentication with Codex", - "description": "Create JWT-based authentication module", - "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)", - "modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"], - "logic_flow": ["Validate credentials", "Generate JWT", "Return token"], - "depends_on": [], - "output": "auth_implementation" - } - ], - "target_files": ["src/auth/service.ts", "src/auth/middleware.ts"] - } -} -``` - -### Example 3: CLI Execute Mode - Multi-Step with Resume -```json -{ - "id": "IMPL-003", - "title": "Implement role-based access control", - "context_package_path": ".workflow/WFS-session/.process/context-package.json", - "context": { - "depends_on": ["IMPL-002"], - "focus_paths": ["src/auth", "src/middleware"], - "requirements": ["User roles and permissions", "Route protection middleware"], - "acceptance": ["RBAC models created", "Middleware working", "Management API complete"] - }, - "flow_control": { - "pre_analysis": [ - { - "step": "load_context", - "action": "Load context and role analyses from context-package.json", - "commands": [ - "Read({{context_package_path}})", - "Extract(brainstorm_artifacts.role_analyses[].files[].path)", - "Read(each extracted path)" - ], - "output_to": "full_context", - "on_error": "fail" - } - ], - "implementation_approach": [ - { - "step": 1, - "title": "Create RBAC models", - "description": "Define role and permission data models", - "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)", - "modification_points": ["Define role model", "Define permission model", "Create migrations"], - "logic_flow": ["Design schema", "Implement models", "Generate migrations"], - "depends_on": [], - "output": "rbac_models" - }, - { - "step": 2, - "title": "Implement RBAC middleware", - "description": "Create route protection middleware using models from step 1", - "command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)", - "modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"], - "logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"], - "depends_on": [1], - "output": "rbac_middleware" - }, - { - "step": 3, - "title": "Add role management API", - "description": "Create CRUD endpoints for roles and permissions", - "command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)", - "modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"], - "logic_flow": ["Define routes", "Implement controllers", "Add authorization"], - "depends_on": [2], - "output": "role_management_api" - } - ], - "target_files": [ - "src/models/Role.ts", - "src/models/Permission.ts", - "src/middleware/rbac.ts", - "src/routes/roles.ts" - ] - } -} -``` - -**Pattern Summary**: -- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow` -- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package -- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last` -- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field - -## 9. Error Handling +## 8. Error Handling ### Input Validation Errors | Error | Cause | Resolution | @@ -888,21 +662,19 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c | Invalid format | Corrupted file | Skip artifact loading | | Path invalid | Moved/deleted | Update references | -## 10. Integration & Usage +## 10. Usage & Related Commands -### Command Chain -- **Called By**: `/workflow:plan` (Phase 4) -- **Calls**: None (terminal command) -- **Followed By**: `/workflow:execute`, `/workflow:status` - -### Basic Usage +**Basic Usage**: ```bash -/workflow:tools:task-generate --session WFS-auth +/workflow:tools:task-generate --session WFS-auth [--cli-execute] ``` -## 11. Related Commands -- `/workflow:plan` - Orchestrates entire planning -- `/workflow:plan --cli-execute` - Planning with CLI execution mode -- `/workflow:tools:context-gather` - Provides context package -- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional) +**Workflow Integration**: +- Called by: `/workflow:plan` (task generation phase) +- Followed by: `/workflow:execute`, `/workflow:status` + +**Related Commands**: +- `/workflow:plan` - Orchestrates entire planning workflow +- `/workflow:tools:context-gather` - Provides context package input +- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed) - `/workflow:execute` - Executes generated tasks