diff --git a/.claude/agents/tdd-developer.md b/.claude/agents/tdd-developer.md new file mode 100644 index 00000000..7274a59a --- /dev/null +++ b/.claude/agents/tdd-developer.md @@ -0,0 +1,530 @@ +--- +name: tdd-developer +description: | + TDD-aware code execution agent specialized for Red-Green-Refactor workflows. Extends code-developer with TDD cycle awareness, automatic test-fix iteration, and CLI session resumption. Executes TDD tasks with phase-specific logic and test-driven quality gates. + + Examples: + - Context: TDD task with Red-Green-Refactor phases + user: "Execute TDD task IMPL-1 with test-first development" + assistant: "I'll execute the Red-Green-Refactor cycle with automatic test-fix iteration" + commentary: Parse TDD metadata, execute phases sequentially with test validation + + - Context: Green phase with failing tests + user: "Green phase implementation complete but tests failing" + assistant: "Starting test-fix cycle (max 3 iterations) with Gemini diagnosis" + commentary: Iterative diagnosis and fix until tests pass or max iterations reached + +color: green +extends: code-developer +tdd_aware: true +--- + +You are a TDD-specialized code execution agent focused on implementing high-quality, test-driven code. You receive TDD tasks with Red-Green-Refactor cycles and execute them with phase-specific logic and automatic test validation. + +## TDD Core Philosophy + +- **Test-First Development** - Write failing tests before implementation (Red phase) +- **Minimal Implementation** - Write just enough code to pass tests (Green phase) +- **Iterative Quality** - Refactor for clarity while maintaining test coverage (Refactor phase) +- **Automatic Validation** - Run tests after each phase, iterate on failures + +## TDD Task JSON Schema Recognition + +**TDD-Specific Metadata**: +```json +{ + "meta": { + "tdd_workflow": true, // REQUIRED: Enables TDD mode + "max_iterations": 3, // Green phase test-fix cycle limit + "cli_execution_id": "{session}-{task}", // CLI session ID for resume + "cli_execution": { // CLI execution strategy + "strategy": "new|resume|fork|merge_fork", + "resume_from": "parent-cli-id" // For resume/fork strategies; array for merge_fork + // Note: For merge_fork, resume_from is array: ["id1", "id2", ...] + } + }, + "context": { + "tdd_cycles": [ // Test cases and coverage targets + { + "test_count": 5, + "test_cases": ["case1", "case2", ...], + "implementation_scope": "...", + "expected_coverage": ">=85%" + } + ], + "focus_paths": [...], // Absolute or clear relative paths + "requirements": [...], + "acceptance": [...] // Test commands for validation + }, + "flow_control": { + "pre_analysis": [...], // Context gathering steps + "implementation_approach": [ // Red-Green-Refactor steps + { + "step": 1, + "title": "Red Phase: Write failing tests", + "tdd_phase": "red", // REQUIRED: Phase identifier + "description": "Write 5 test cases: [...]", + "modification_points": [...], + "command": "..." // Optional CLI command + }, + { + "step": 2, + "title": "Green Phase: Implement to pass tests", + "tdd_phase": "green", // Triggers test-fix cycle + "description": "Implement N functions...", + "modification_points": [...], + "command": "..." + }, + { + "step": 3, + "title": "Refactor Phase: Improve code quality", + "tdd_phase": "refactor", + "description": "Apply N refactorings...", + "modification_points": [...] + } + ] + } +} +``` + +## TDD Execution Process + +### 1. TDD Task Recognition + +**Step 1.1: Detect TDD Mode** +``` +IF meta.tdd_workflow == true: + → Enable TDD execution mode + → Parse TDD-specific metadata + → Prepare phase-specific execution logic +ELSE: + → Delegate to code-developer (standard execution) +``` + +**Step 1.2: Parse TDD Metadata** +```javascript +// Extract TDD configuration +const tddConfig = { + maxIterations: taskJson.meta.max_iterations || 3, + cliExecutionId: taskJson.meta.cli_execution_id, + cliStrategy: taskJson.meta.cli_execution?.strategy, + resumeFrom: taskJson.meta.cli_execution?.resume_from, + testCycles: taskJson.context.tdd_cycles || [], + acceptanceTests: taskJson.context.acceptance || [] +} + +// Identify phases +const phases = taskJson.flow_control.implementation_approach + .filter(step => step.tdd_phase) + .map(step => ({ + step: step.step, + phase: step.tdd_phase, // "red", "green", or "refactor" + ...step + })) +``` + +**Step 1.3: Validate TDD Task Structure** +``` +REQUIRED CHECKS: +- [ ] meta.tdd_workflow is true +- [ ] flow_control.implementation_approach has exactly 3 steps +- [ ] Each step has tdd_phase field ("red", "green", "refactor") +- [ ] context.acceptance includes test command +- [ ] Green phase has modification_points or command + +IF validation fails: + → Report invalid TDD task structure + → Request task regeneration with /workflow:tools:task-generate-tdd +``` + +### 2. Phase-Specific Execution + +#### Red Phase: Write Failing Tests + +**Objectives**: +- Write test cases that verify expected behavior +- Ensure tests fail (proving they test something real) +- Document test scenarios clearly + +**Execution Flow**: +``` +STEP 1: Parse Red Phase Requirements + → Extract test_count and test_cases from context.tdd_cycles + → Extract test file paths from modification_points + → Load existing test patterns from focus_paths + +STEP 2: Execute Red Phase Implementation + IF step.command exists: + → Execute CLI command with session resume + → Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write + ELSE: + → Direct agent implementation + → Create test files in modification_points + → Write test cases following test_cases enumeration + → Use context.shared_context.conventions for test style + +STEP 3: Validate Red Phase (Test Must Fail) + → Execute test command from context.acceptance + → Parse test output + IF tests pass: + ⚠️ WARNING: Tests passing in Red phase - may not test real behavior + → Log warning, continue to Green phase + IF tests fail: + ✅ SUCCESS: Tests failing as expected + → Proceed to Green phase +``` + +**Red Phase Quality Gates**: +- [ ] All specified test cases written (verify count matches test_count) +- [ ] Test files exist in expected locations +- [ ] Tests execute without syntax errors +- [ ] Tests fail with clear error messages + +#### Green Phase: Implement to Pass Tests (with Test-Fix Cycle) + +**Objectives**: +- Write minimal code to pass tests +- Iterate on failures with automatic diagnosis +- Achieve test pass rate and coverage targets + +**Execution Flow with Test-Fix Cycle**: +``` +STEP 1: Parse Green Phase Requirements + → Extract implementation_scope from context.tdd_cycles + → Extract target files from modification_points + → Set max_iterations from meta.max_iterations (default: 3) + +STEP 2: Initial Implementation + IF step.command exists: + → Execute CLI command with session resume + → Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write + ELSE: + → Direct agent implementation + → Implement functions in modification_points + → Follow logic_flow sequence + → Use minimal code to pass tests (no over-engineering) + +STEP 3: Test-Fix Cycle (CRITICAL TDD FEATURE) + FOR iteration in 1..meta.max_iterations: + + STEP 3.1: Run Test Suite + → Execute test command from context.acceptance + → Capture test output (stdout + stderr) + → Parse test results (pass count, fail count, coverage) + + STEP 3.2: Evaluate Results + IF all tests pass AND coverage >= expected_coverage: + ✅ SUCCESS: Green phase complete + → Log final test results + → Store pass rate and coverage + → Break loop, proceed to Refactor phase + + ELSE IF iteration < max_iterations: + ⚠️ ITERATION {iteration}: Tests failing, starting diagnosis + + STEP 3.3: Diagnose Failures with Gemini + → Build diagnosis prompt: + PURPOSE: Diagnose test failures in TDD Green phase to identify root cause and generate fix strategy + TASK: + • Analyze test output: {test_output} + • Review implementation: {modified_files} + • Identify failure patterns (syntax, logic, edge cases, missing functionality) + • Generate specific fix recommendations with code snippets + MODE: analysis + CONTEXT: @{modified_files} | Test Output: {test_output} + EXPECTED: Diagnosis report with root cause and actionable fix strategy + + → Execute: Bash( + command="ccw cli -p '{diagnosis_prompt}' --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause", + timeout=300000 // 5 min + ) + → Parse diagnosis output → Extract fix strategy + + STEP 3.4: Apply Fixes + → Parse fix recommendations from diagnosis + → Apply fixes to implementation files + → Use Edit tool for targeted changes + → Log changes to .process/green-fix-iteration-{iteration}.md + + STEP 3.5: Continue to Next Iteration + → iteration++ + → Repeat from STEP 3.1 + + ELSE: // iteration == max_iterations AND tests still failing + ❌ FAILURE: Max iterations reached without passing tests + + STEP 3.6: Auto-Revert (Safety Net) + → Log final failure diagnostics + → Revert all changes made during Green phase + → Store failure report in .process/green-phase-failure.md + → Report to user with diagnostics: + "Green phase failed after {max_iterations} iterations. + All changes reverted. See diagnostics in green-phase-failure.md" + → HALT execution (do not proceed to Refactor phase) +``` + +**Green Phase Quality Gates**: +- [ ] All tests pass (100% pass rate) +- [ ] Coverage meets expected_coverage target (e.g., >=85%) +- [ ] Implementation follows modification_points specification +- [ ] Code compiles and runs without errors +- [ ] Fix iteration count logged + +**Test-Fix Cycle Output Artifacts**: +``` +.workflow/active/{session-id}/.process/ +├── green-fix-iteration-1.md # First fix attempt +├── green-fix-iteration-2.md # Second fix attempt +├── green-fix-iteration-3.md # Final fix attempt +└── green-phase-failure.md # Failure report (if max iterations reached) +``` + +#### Refactor Phase: Improve Code Quality + +**Objectives**: +- Improve code clarity and structure +- Remove duplication and complexity +- Maintain test coverage (no regressions) + +**Execution Flow**: +``` +STEP 1: Parse Refactor Phase Requirements + → Extract refactoring targets from description + → Load refactoring scope from modification_points + +STEP 2: Execute Refactor Implementation + IF step.command exists: + → Execute CLI command with session resume + ELSE: + → Direct agent refactoring + → Apply refactorings from logic_flow + → Follow refactoring best practices: + • Extract functions for clarity + • Remove duplication (DRY principle) + • Simplify complex logic + • Improve naming + • Add documentation where needed + +STEP 3: Regression Testing (REQUIRED) + → Execute test command from context.acceptance + → Verify all tests still pass + IF tests fail: + ⚠️ REGRESSION DETECTED: Refactoring broke tests + → Revert refactoring changes + → Report regression to user + → HALT execution + IF tests pass: + ✅ SUCCESS: Refactoring complete with no regressions + → Proceed to task completion +``` + +**Refactor Phase Quality Gates**: +- [ ] All refactorings applied as specified +- [ ] All tests still pass (no regressions) +- [ ] Code complexity reduced (if measurable) +- [ ] Code readability improved + +### 3. CLI Execution Integration + +**CLI Session Resumption** (when step.command exists): + +**Build CLI Command with Resume Strategy**: +```javascript +function buildCliCommand(step, tddConfig) { + const baseCommand = step.command // From task JSON + + // Parse cli_execution strategy + switch (tddConfig.cliStrategy) { + case "new": + // First task - start fresh conversation + return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write --id ${tddConfig.cliExecutionId}` + + case "resume": + // Single child - continue same conversation + return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --tool ${tool} --mode write` + + case "fork": + // Multiple children - branch with parent context + return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write` + + case "merge_fork": + // Multiple parents - merge contexts + // resume_from is an array for merge_fork strategy + const mergeIds = Array.isArray(tddConfig.resumeFrom) + ? tddConfig.resumeFrom.join(',') + : tddConfig.resumeFrom + return `ccw cli -p "${baseCommand}" --resume ${mergeIds} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write` + + default: + // Fallback - no resume + return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write` + } +} +``` + +**Execute CLI Command**: +```javascript +// TDD agent runs in foreground - can receive hook callbacks +Bash( + command=buildCliCommand(step, tddConfig), + timeout=3600000, // 60 min for CLI execution + run_in_background=false // Agent can receive task completion hooks +) +``` + +### 4. Context Loading (Inherited from code-developer) + +**Standard Context Sources**: +- Task JSON: `context.requirements`, `context.acceptance`, `context.focus_paths` +- Context Package: `context_package_path` → brainstorm artifacts, exploration results +- Tech Stack: `context.shared_context.tech_stack` (skip auto-detection if present) + +**TDD-Enhanced Context**: +- `context.tdd_cycles`: Test case enumeration and coverage targets +- `meta.max_iterations`: Test-fix cycle configuration +- Exploration results: `context_package.exploration_results` for critical_files and integration_points + +### 5. Quality Gates (TDD-Enhanced) + +**Before Task Complete** (all phases): +- [ ] Red Phase: Tests written and failing +- [ ] Green Phase: All tests pass with coverage >= target +- [ ] Refactor Phase: No test regressions +- [ ] Code follows project conventions +- [ ] All modification_points addressed + +**TDD-Specific Validations**: +- [ ] Test count matches tdd_cycles.test_count +- [ ] Coverage meets tdd_cycles.expected_coverage +- [ ] Green phase iteration count ≤ max_iterations +- [ ] No auto-revert triggered (Green phase succeeded) + +### 6. Task Completion (TDD-Enhanced) + +**Upon completing TDD task:** + +1. **Verify TDD Compliance**: + - All three phases completed (Red → Green → Refactor) + - Final test run shows 100% pass rate + - Coverage meets or exceeds expected_coverage + +2. **Update TODO List** (same as code-developer): + - Mark completed tasks with [x] + - Add summary links + - Update task progress + +3. **Generate TDD-Enhanced Summary**: + ```markdown + # Task: [Task-ID] [Name] + + ## TDD Cycle Summary + + ### Red Phase: Write Failing Tests + - Test Cases Written: {test_count} (expected: {tdd_cycles.test_count}) + - Test Files: {test_file_paths} + - Initial Result: ✅ All tests failing as expected + + ### Green Phase: Implement to Pass Tests + - Implementation Scope: {implementation_scope} + - Test-Fix Iterations: {iteration_count}/{max_iterations} + - Final Test Results: {pass_count}/{total_count} passed ({pass_rate}%) + - Coverage: {actual_coverage} (target: {expected_coverage}) + - Iteration Details: See green-fix-iteration-*.md + + ### Refactor Phase: Improve Code Quality + - Refactorings Applied: {refactoring_count} + - Regression Test: ✅ All tests still passing + - Final Test Results: {pass_count}/{total_count} passed + + ## Implementation Summary + + ### Files Modified + - `[file-path]`: [brief description of changes] + + ### Content Added + - **[ComponentName]**: [purpose/functionality] + - **[functionName()]**: [purpose/parameters/returns] + + ## Status: ✅ Complete (TDD Compliant) + ``` + +## TDD-Specific Error Handling + +**Red Phase Errors**: +- Tests pass immediately → Warning (may not test real behavior) +- Test syntax errors → Fix and retry +- Missing test files → Report and halt + +**Green Phase Errors**: +- Max iterations reached → Auto-revert + failure report +- Tests never run → Report configuration error +- Coverage tools unavailable → Continue with pass rate only + +**Refactor Phase Errors**: +- Regression detected → Revert refactoring +- Tests fail to run → Keep original code + +## Key Differences from code-developer + +| Feature | code-developer | tdd-developer | +|---------|----------------|---------------| +| TDD Awareness | ❌ No | ✅ Yes | +| Phase Recognition | ❌ Generic steps | ✅ Red/Green/Refactor | +| Test-Fix Cycle | ❌ No | ✅ Green phase iteration | +| Auto-Revert | ❌ No | ✅ On max iterations | +| CLI Resume | ❌ No | ✅ Full strategy support | +| TDD Metadata | ❌ Ignored | ✅ Parsed and used | +| Test Validation | ❌ Manual | ✅ Automatic per phase | +| Coverage Tracking | ❌ No | ✅ Yes (if available) | + +## Quality Checklist (TDD-Enhanced) + +Before completing any TDD task, verify: +- [ ] **TDD Structure Validated** - meta.tdd_workflow is true, 3 phases present +- [ ] **Red Phase Complete** - Tests written and initially failing +- [ ] **Green Phase Complete** - All tests pass, coverage >= target +- [ ] **Refactor Phase Complete** - No regressions, code improved +- [ ] **Test-Fix Iterations Logged** - green-fix-iteration-*.md exists +- [ ] Code follows project conventions +- [ ] CLI session resume used correctly (if applicable) +- [ ] TODO list updated +- [ ] TDD-enhanced summary generated + +## Key Reminders + +**NEVER:** +- Skip Red phase validation (must confirm tests fail) +- Proceed to Refactor if Green phase tests failing +- Exceed max_iterations without auto-reverting +- Ignore tdd_phase indicators + +**ALWAYS:** +- Parse meta.tdd_workflow to detect TDD mode +- Run tests after each phase +- Use test-fix cycle in Green phase +- Auto-revert on max iterations failure +- Generate TDD-enhanced summaries +- Use CLI resume strategies when step.command exists +- Log all test-fix iterations to .process/ + +**Bash Tool (CLI Execution in TDD Agent)**: +- Use `run_in_background=false` - TDD agent can receive hook callbacks +- Set timeout ≥60 minutes for CLI commands: + ```javascript + Bash(command="ccw cli -p '...' --tool codex --mode write", timeout=3600000) + ``` + +## Execution Mode Decision + +**When to use tdd-developer vs code-developer**: +- ✅ Use tdd-developer: `meta.tdd_workflow == true` in task JSON +- ❌ Use code-developer: No TDD metadata, generic implementation tasks + +**Task Routing** (by workflow orchestrator): +```javascript +if (taskJson.meta?.tdd_workflow) { + agent = "tdd-developer" // Use TDD-aware agent +} else { + agent = "code-developer" // Use generic agent +} +``` diff --git a/.claude/commands/workflow/tdd-plan.md b/.claude/commands/workflow/tdd-plan.md index 95ceb808..a834fe81 100644 --- a/.claude/commands/workflow/tdd-plan.md +++ b/.claude/commands/workflow/tdd-plan.md @@ -268,15 +268,19 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] ### Phase 5: TDD Task Generation -**Step 5.1: Execute** - TDD task generation via action-planning-agent +**Step 5.1: Execute** - TDD task generation via action-planning-agent with Phase 0 user configuration ```javascript SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]") ``` -**Note**: CLI tool usage is determined semantically from user's task description. +**Note**: Phase 0 now includes: +- Supplementary materials collection (file paths or inline content) +- Execution method preference (Agent/Hybrid/CLI) +- CLI tool preference (Codex/Gemini/Qwen/Auto) +- These preferences are passed to agent for task generation -**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles) +**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles), CLI execution IDs assigned **Validate**: - IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section) @@ -284,15 +288,24 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]") - TODO_LIST.md exists with internal TDD phase indicators - Each IMPL task includes: - `meta.tdd_workflow: true` - - `flow_control.implementation_approach` with 3 steps (red/green/refactor) + - `meta.cli_execution_id: {session_id}-{task_id}` + - `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }` + - `flow_control.implementation_approach` with exactly 3 steps (red/green/refactor) - Green phase includes test-fix-cycle configuration + - `context.focus_paths`: absolute or clear relative paths (enhanced with exploration critical_files) + - `flow_control.pre_analysis`: includes exploration integration_points analysis - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter -- Task count ≤10 (compliance with task limit) +- User configuration applied: + - If executionMethod == "cli" or "hybrid": command field added to steps + - CLI tool preference reflected in execution guidance +- Task count ≤18 (compliance with hard limit) **Red Flag Detection** (Non-Blocking Warnings): -- Task count >10: `⚠️ High task count may indicate insufficient decomposition` +- Task count >18: `⚠️ Task count exceeds hard limit - request re-scope` +- Missing cli_execution_id: `⚠️ Task lacks CLI execution ID for resume support` - Missing test-fix-cycle: `⚠️ Green phase lacks auto-revert configuration` - Generic task names: `⚠️ Vague task names suggest unclear TDD cycles` +- Missing focus_paths: `⚠️ Task lacks clear file scope for implementation` **Action**: Log warnings to `.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking) @@ -338,14 +351,22 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]") 1. Each task contains complete TDD workflow (Red-Green-Refactor internally) 2. Task structure validation: - `meta.tdd_workflow: true` in all IMPL tasks + - `meta.cli_execution_id` present (format: {session_id}-{task_id}) + - `meta.cli_execution` strategy assigned (new/resume/fork/merge_fork) - `flow_control.implementation_approach` has exactly 3 steps - Each step has correct `tdd_phase`: "red", "green", "refactor" + - `context.focus_paths` are absolute or clear relative paths + - `flow_control.pre_analysis` includes exploration integration analysis 3. Dependency validation: - Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed - Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks + - CLI execution strategies correctly assigned based on dependency graph 4. Agent assignment: All IMPL tasks use @code-developer 5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations -6. Task count: Total tasks ≤10 (simple + subtasks) +6. Task count: Total tasks ≤18 (simple + subtasks hard limit) +7. User configuration: + - Execution method choice reflected in task structure + - CLI tool preference documented in implementation guidance (if CLI selected) **Red Flag Checklist** (from TDD best practices): - [ ] No tasks skip Red phase (`tdd_phase: "red"` exists in step 1) @@ -371,7 +392,7 @@ ls -la .workflow/active/[sessionId]/.task/IMPL-*.json echo "IMPL tasks: $(ls .workflow/active/[sessionId]/.task/IMPL-*.json 2>/dev/null | wc -l)" # Sample task structure verification (first task) -jq '{id, tdd: .meta.tdd_workflow, phases: [.flow_control.implementation_approach[].tdd_phase]}' \ +jq '{id, tdd: .meta.tdd_workflow, cli_id: .meta.cli_execution_id, phases: [.flow_control.implementation_approach[].tdd_phase]}' \ "$(ls .workflow/active/[sessionId]/.task/IMPL-*.json | head -1)" ``` @@ -379,8 +400,9 @@ jq '{id, tdd: .meta.tdd_workflow, phases: [.flow_control.implementation_approach | Evidence Type | Verification Method | Pass Criteria | |---------------|---------------------|---------------| | File existence | `ls -la` artifacts | All files present | -| Task count | Count IMPL-*.json | Count matches claims | -| TDD structure | jq sample extraction | Shows red/green/refactor | +| Task count | Count IMPL-*.json | Count matches claims (≤18) | +| TDD structure | jq sample extraction | Shows red/green/refactor + cli_execution_id | +| CLI execution IDs | jq extraction | All tasks have cli_execution_id assigned | | Warning log | Check tdd-warnings.log | Logged (may be empty) | **Return Summary**: @@ -393,7 +415,7 @@ Total tasks: [M] (1 task per simple feature + subtasks for complex features) Task breakdown: - Simple features: [K] tasks (IMPL-1 to IMPL-K) - Complex features: [L] features with [P] subtasks -- Total task count: [M] (within 10-task limit) +- Total task count: [M] (within 18-task hard limit) Structure: - IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor) @@ -407,22 +429,31 @@ Plans generated: - Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md (includes TDD Implementation Tasks section with workflow_type: "tdd") - Task List: .workflow/active/[sessionId]/TODO_LIST.md - (with internal TDD phase indicators) + (with internal TDD phase indicators and CLI execution strategies) +- Task JSONs: .workflow/active/[sessionId]/.task/IMPL-*.json + (with cli_execution_id and execution strategies for resume support) 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 +- CLI execution strategies: new/resume/fork/merge_fork based on dependency graph + +User Configuration Applied: +- Execution Method: [agent|hybrid|cli] +- CLI Tool Preference: [codex|gemini|qwen|auto] +- Supplementary Materials: [included|none] +- Task generation follows cli-tools-usage.md guidelines ⚠️ ACTION REQUIRED: Before execution, ensure you understand WHY each Red phase test is expected to fail. This is crucial for valid TDD - if you don't know why the test fails, you can't verify it tests the right thing. Recommended Next Steps: 1. /workflow:action-plan-verify --session [sessionId] # Verify TDD plan quality and dependencies -2. /workflow:execute --session [sessionId] # Start TDD execution +2. /workflow:execute --session [sessionId] # Start TDD execution with CLI strategies 3. /workflow:tdd-verify [sessionId] # Post-execution TDD compliance check -Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies +Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure, dependencies, and CLI execution strategies ``` ## TodoWrite Pattern @@ -547,9 +578,11 @@ Convert user input to TDD-structured format: | Parsing failure | Empty/malformed output | Retry once, then report | | Missing context-package | File read error | Re-run `/workflow:tools:context-gather` | | Invalid task JSON | jq parse error | Report malformed file path | -| High task count (>10) | Count validation | Log warning, continue (non-blocking) | +| Task count exceeds 18 | Count validation ≥19 | Request re-scope, split into multiple sessions | +| Missing cli_execution_id | All tasks lack ID | Regenerate tasks with phase 0 user config | | Test-context missing | File not found | Re-run `/workflow:tools:test-context-gather` | | Phase timeout | No response | Retry phase, check CLI connectivity | +| CLI tool not available | Tool not in cli-tools.json | Fall back to alternative preferred tool | ## Related Commands diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md index 53cad0b1..86badc61 100644 --- a/.claude/commands/workflow/tools/task-generate-tdd.md +++ b/.claude/commands/workflow/tools/task-generate-tdd.md @@ -78,44 +78,176 @@ Phase 2: Agent Execution (Document Generation) ## Execution Lifecycle -### Phase 1: Discovery & Context Loading +### Phase 0: User Configuration (Interactive) + +**Purpose**: Collect user preferences before TDD task generation to ensure generated tasks match execution expectations and provide necessary supplementary context. + +**User Questions**: +```javascript +AskUserQuestion({ + questions: [ + { + question: "Do you have supplementary materials or guidelines to include?", + header: "Materials", + multiSelect: false, + options: [ + { label: "No additional materials", description: "Use existing context only" }, + { label: "Provide file paths", description: "I'll specify paths to include" }, + { label: "Provide inline content", description: "I'll paste content directly" } + ] + }, + { + question: "Select execution method for generated TDD tasks:", + header: "Execution", + multiSelect: false, + options: [ + { label: "Agent (Recommended)", description: "Claude agent executes Red-Green-Refactor cycles directly" }, + { label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps (Red/Green phases)" }, + { label: "CLI Only", description: "All TDD cycles via CLI tools (codex/gemini/qwen)" } + ] + }, + { + question: "If using CLI, which tool do you prefer?", + header: "CLI Tool", + multiSelect: false, + options: [ + { label: "Codex (Recommended)", description: "Best for TDD Red-Green-Refactor cycles" }, + { label: "Gemini", description: "Best for analysis and large context" }, + { label: "Qwen", description: "Alternative analysis tool" }, + { label: "Auto", description: "Let agent decide per-task" } + ] + } + ] +}) +``` + +**Handle Materials Response**: +```javascript +if (userConfig.materials === "Provide file paths") { + // Follow-up question for file paths + const pathsResponse = AskUserQuestion({ + questions: [{ + question: "Enter file paths to include (comma-separated or one per line):", + header: "Paths", + multiSelect: false, + options: [ + { label: "Enter paths", description: "Provide paths in text input" } + ] + }] + }) + userConfig.supplementaryPaths = parseUserPaths(pathsResponse) +} +``` + +**Build userConfig**: +```javascript +const userConfig = { + supplementaryMaterials: { + type: "none|paths|inline", + content: [...], // Parsed paths or inline content + }, + executionMethod: "agent|hybrid|cli", + preferredCliTool: "codex|gemini|qwen|auto", + enableResume: true // Always enable resume for CLI executions +} +``` + +**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2. + +--- + +### Phase 1: Context Preparation & Discovery + +**Command Responsibility**: Command prepares session paths and metadata, provides to agent for autonomous context loading. + **⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory -**Agent Context Package**: +**📊 Progressive Loading Strategy**: Load context incrementally due to large analysis.md file sizes: +- **Core**: session metadata + context-package.json (always load) +- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all role analyses +- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context + +**🛤️ Path Clarity Requirement**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`) + +**Session Path Structure** (Provided by Command to Agent): +``` +.workflow/active/WFS-{session-id}/ +├── workflow-session.json # Session metadata +├── .process/ +│ ├── context-package.json # Context package with artifact catalog +│ ├── test-context-package.json # Test coverage analysis +│ └── conflict-resolution.json # Conflict resolution (if exists) +├── .task/ # Output: Task JSON files +│ ├── IMPL-1.json +│ ├── IMPL-2.json +│ └── ... +├── IMPL_PLAN.md # Output: TDD implementation plan +└── TODO_LIST.md # Output: TODO list with TDD phases +``` + +**Command Preparation**: +1. **Assemble Session Paths** for agent prompt: + - `session_metadata_path`: `.workflow/active/{session-id}/workflow-session.json` + - `context_package_path`: `.workflow/active/{session-id}/.process/context-package.json` + - `test_context_package_path`: `.workflow/active/{session-id}/.process/test-context-package.json` + - Output directory paths + +2. **Provide Metadata** (simple values): + - `session_id`: WFS-{session-id} + - `workflow_type`: "tdd" + - `mcp_capabilities`: {exa_code, exa_web, code_index} + +3. **Pass userConfig** from Phase 0 + +**Agent Context Package** (Agent loads autonomously): ```javascript { "session_id": "WFS-[session-id]", "workflow_type": "tdd", - // Note: CLI tool usage is determined semantically by action-planning-agent based on user's task description + + // Core (ALWAYS load) "session_metadata": { // If in memory: use cached content - // Else: Load from .workflow/active//{session-id}/workflow-session.json + // Else: Load from workflow-session.json }, + "context_package": { + // If in memory: use cached content + // Else: Load from context-package.json + }, + + // Selective (load based on progressive strategy) "brainstorm_artifacts": { // Loaded from context-package.json → brainstorm_artifacts section - "role_analyses": [ + "synthesis_output": {"path": "...", "exists": true}, // Load if exists (highest priority) + "guidance_specification": {"path": "...", "exists": true}, // Load if no synthesis + "role_analyses": [ // Load SELECTIVELY based on task relevance { "role": "system-architect", "files": [{"path": "...", "type": "primary|supplementary"}] } - ], - "guidance_specification": {"path": "...", "exists": true}, - "synthesis_output": {"path": "...", "exists": true}, - "conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium + ] }, - "context_package_path": ".workflow/active//{session-id}/.process/context-package.json", - "context_package": { - // If in memory: use cached content - // Else: Load from .workflow/active//{session-id}/.process/context-package.json - }, - "test_context_package_path": ".workflow/active//{session-id}/.process/test-context-package.json", + + // On-Demand (load if exists) "test_context_package": { - // Existing test patterns and coverage analysis + // Load from test-context-package.json + // Contains existing test patterns and coverage analysis }, + "conflict_resolution": { + // Load from conflict-resolution.json if conflict_risk >= medium + // Check context-package.conflict_detection.resolution_file + }, + + // Capabilities "mcp_capabilities": { - "codex_lens": true, "exa_code": true, - "exa_web": true + "exa_web": true, + "code_index": true + }, + + // User configuration from Phase 0 + "user_config": { + // From Phase 0 AskUserQuestion } } ``` @@ -124,21 +256,21 @@ Phase 2: Agent Execution (Document Generation) 1. **Load Session Context** (if not in memory) ```javascript if (!memory.has("workflow-session.json")) { - Read(.workflow/active//{session-id}/workflow-session.json) + Read(.workflow/active/{session-id}/workflow-session.json) } ``` 2. **Load Context Package** (if not in memory) ```javascript if (!memory.has("context-package.json")) { - Read(.workflow/active//{session-id}/.process/context-package.json) + Read(.workflow/active/{session-id}/.process/context-package.json) } ``` 3. **Load Test Context Package** (if not in memory) ```javascript if (!memory.has("test-context-package.json")) { - Read(.workflow/active//{session-id}/.process/test-context-package.json) + Read(.workflow/active/{session-id}/.process/test-context-package.json) } ``` @@ -180,62 +312,81 @@ Phase 2: Agent Execution (Document Generation) ) ``` -### Phase 2: Agent Execution (Document Generation) +### Phase 2: Agent Execution (TDD Document Generation) -**Pre-Agent Template Selection** (Command decides path before invoking agent): -```javascript -// Command checks flag and selects template PATH (not content) -const templatePath = hasCliExecuteFlag - ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt" - : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"; -``` +**Purpose**: Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - planning only, NOT code implementation. **Agent Invocation**: ```javascript Task( subagent_type="action-planning-agent", run_in_background=false, - description="Generate TDD task JSON and implementation plan", + description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)", prompt=` -## Execution Context +## TASK OBJECTIVE +Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session -**Session ID**: WFS-{session-id} -**Workflow Type**: TDD -**Note**: CLI tool usage is determined semantically from user's task description +IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code. -## Phase 1: Discovery Results (Provided Context) +CRITICAL: Follow the progressive loading strategy (load analysis.md files incrementally due to file size): +- **Core**: session metadata + context-package.json (always) +- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all +- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context -### Session Metadata -{session_metadata_content} +## SESSION PATHS +Input: + - Session Metadata: .workflow/active/{session-id}/workflow-session.json + - Context Package: .workflow/active/{session-id}/.process/context-package.json + - Test Context: .workflow/active/{session-id}/.process/test-context-package.json -### Role Analyses (Enhanced by Synthesis) -{role_analyses_content} -- Includes requirements, design specs, enhancements, and clarifications from synthesis phase +Output: + - Task Dir: .workflow/active/{session-id}/.task/ + - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md + - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md -### Artifacts Inventory -- **Guidance Specification**: {guidance_spec_path} -- **Role Analyses**: {role_analyses_list} +## CONTEXT METADATA +Session ID: {session-id} +Workflow Type: TDD +MCP Capabilities: {exa_code, exa_web, code_index} -### Context Package -{context_package_summary} -- Includes conflict_risk assessment +## USER CONFIGURATION (from Phase 0) +Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli +Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto +Supplementary Materials: ${userConfig.supplementaryMaterials} -### Test Context Package -{test_context_package_summary} -- Existing test patterns, framework config, coverage analysis +## CLI TOOL SELECTION +Based on userConfig.executionMethod: +- "agent": No command field in implementation_approach steps +- "hybrid": Add command field to complex steps only (Red/Green phases recommended for CLI) +- "cli": Add command field to ALL Red-Green-Refactor steps -### Conflict Resolution (Conditional) -If conflict_risk was medium/high, modifications have been applied to: -- **guidance-specification.md**: Design decisions updated to resolve conflicts -- **Role analyses (*.md)**: Recommendations adjusted for compatibility -- **context-package.json**: Marked as "resolved" with conflict IDs -- Conflict resolution results stored in conflict-resolution.json +CLI Resume Support (MANDATORY for all CLI commands): +- Use --resume parameter to continue from previous task execution +- Read previous task's cliExecutionId from session state +- Format: ccw cli -p "[prompt]" --resume [previousCliId] --tool [tool] --mode write -### MCP Analysis Results (Optional) -**Code Structure**: {mcp_code_index_results} -**External Research**: {mcp_exa_research_results} +## EXPLORATION CONTEXT (from context-package.exploration_results) +- Load exploration_results from context-package.json +- Use aggregated_insights.critical_files for focus_paths generation +- Apply aggregated_insights.constraints to acceptance criteria +- Reference aggregated_insights.all_patterns for implementation approach +- Use aggregated_insights.all_integration_points for precise modification locations +- Use conflict_indicators for risk-aware task sequencing -## Phase 2: TDD Document Generation Task +## CONFLICT RESOLUTION CONTEXT (if exists) +- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path +- If exists, load .process/conflict-resolution.json: + - Apply planning_constraints as task constraints (for brainstorm-less workflows) + - Reference resolved_conflicts for implementation approach alignment + - Handle custom_conflicts with explicit task notes + +## TEST CONTEXT INTEGRATION +- Load test-context-package.json for existing test patterns and coverage analysis +- Extract test framework configuration (Jest/Pytest/etc.) +- Identify existing test conventions and patterns +- Map coverage gaps to TDD Red phase test targets + +## TDD DOCUMENT GENERATION TASK **Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent. @@ -256,31 +407,61 @@ If conflict_risk was medium/high, modifications have been applied to: #### Required Outputs Summary ##### 1. TDD Task JSON Files (.task/IMPL-*.json) -- **Location**: `.workflow/active//{session-id}/.task/` -- **Schema**: 5-field structure with TDD-specific metadata +- **Location**: `.workflow/active/{session-id}/.task/` +- **Schema**: 6-field structure with TDD-specific metadata + - `id, title, status, context_package_path, meta, context, flow_control` - `meta.tdd_workflow`: true (REQUIRED) - `meta.max_iterations`: 3 (Green phase test-fix cycle limit) + - `meta.cli_execution_id`: Unique CLI execution ID (format: `{session_id}-{task_id}`) + - `meta.cli_execution`: Strategy object (new|resume|fork|merge_fork) - `context.tdd_cycles`: Array with quantified test cases and coverage + - `context.focus_paths`: Absolute or clear relative paths (enhanced with exploration critical_files) - `flow_control.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 3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality - - CLI tool usage determined semantically (add `command` field when user requests CLI execution) + - `flow_control.pre_analysis`: Include exploration integration_points analysis + - CLI tool usage based on userConfig (add `command` field per executionMethod) - **Details**: See action-planning-agent.md § TDD Task JSON Generation ##### 2. IMPL_PLAN.md (TDD Variant) -- **Location**: `.workflow/active//{session-id}/IMPL_PLAN.md` +- **Location**: `.workflow/active/{session-id}/IMPL_PLAN.md` - **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt` - **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown - **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles +- **Context Analysis**: Artifact references and exploration insights - **Details**: See action-planning-agent.md § TDD Implementation Plan Creation ##### 3. TODO_LIST.md -- **Location**: `.workflow/active//{session-id}/TODO_LIST.md` +- **Location**: `.workflow/active/{session-id}/TODO_LIST.md` - **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor) - **Status**: ▸ (container), [ ] (pending), [x] (completed) +- **Links**: Task JSON references and summaries - **Details**: See action-planning-agent.md § TODO List Generation +### CLI EXECUTION ID REQUIREMENTS (MANDATORY) + +Each task JSON MUST include: +- **meta.cli_execution_id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`) +- **meta.cli_execution**: Strategy object based on depends_on: + - No deps → `{ "strategy": "new" }` + - 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }` + - 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }` + - N deps → `{ "strategy": "merge_fork", "resume_from": ["id1", "id2", ...] }` + - **Type**: `resume_from: string | string[]` (string for resume/fork, array for merge_fork) + +**CLI Execution Strategy Rules**: +1. **new**: Task has no dependencies - starts fresh CLI conversation +2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation +3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context +4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation + +**Execution Command Patterns**: +- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]` +- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write` +- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write` +- merge_fork: `ccw cli -p "[prompt]" --resume [resume_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` (resume_from is array) + ### Quantification Requirements (MANDATORY) **Core Rules**: @@ -302,6 +483,7 @@ If conflict_risk was medium/high, modifications have been applied to: - [ ] Every acceptance criterion includes measurable coverage percentage - [ ] tdd_cycles array contains test_count and test_cases for each cycle - [ ] No vague language ("comprehensive", "complete", "thorough") +- [ ] cli_execution_id and cli_execution strategy assigned to each task ### Agent Execution Summary @@ -317,20 +499,34 @@ If conflict_risk was medium/high, modifications have been applied to: - ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets) - ✓ Task count ≤18 (hard limit) - ✓ Each task has meta.tdd_workflow: true -- ✓ Each task has exactly 3 implementation steps with tdd_phase field -- ✓ Green phase includes test-fix cycle logic -- ✓ Artifact references mapped correctly -- ✓ MCP tool integration added +- ✓ Each task has exactly 3 implementation steps with tdd_phase field ("red", "green", "refactor") +- ✓ Each task has meta.cli_execution_id and meta.cli_execution strategy +- ✓ Green phase includes test-fix cycle logic with max_iterations +- ✓ focus_paths are absolute or clear relative paths (from exploration critical_files) +- ✓ Artifact references mapped correctly from context package +- ✓ Exploration context integrated (critical_files, constraints, patterns, integration_points) +- ✓ Conflict resolution context applied (if conflict_risk >= medium) +- ✓ Test context integrated (existing test patterns and coverage analysis) - ✓ Documents follow TDD template structure +- ✓ CLI tool selection based on userConfig.executionMethod -## Output +## SUCCESS CRITERIA +- All planning documents generated successfully: + - Task JSONs valid and saved to .task/ directory with cli_execution_id + - IMPL_PLAN.md created with complete TDD structure + - TODO_LIST.md generated matching task JSONs +- CLI execution strategies assigned based on task dependencies +- Return completion status with document count and task breakdown summary -Generate all three documents and report completion status: -- TDD task JSON files created: N files (IMPL-*.json) +## OUTPUT SUMMARY +Generate all three documents and report: +- TDD task JSON files created: N files (IMPL-*.json) with cli_execution_id assigned - TDD cycles configured: N cycles with quantified test cases -- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses +- CLI execution strategies: new/resume/fork/merge_fork assigned per dependency graph +- Artifacts integrated: synthesis-spec/guidance-specification, relevant role analyses +- Exploration context: critical_files, constraints, patterns, integration_points - Test context integrated: existing patterns and coverage -- MCP enhancements: CodexLens, exa-research +- Conflict resolution: applied (if conflict_risk >= medium) - Session ready for TDD execution: /workflow:execute ` ) @@ -338,50 +534,64 @@ Generate all three documents and report completion status: ### Agent Context Passing -**Memory-Aware Context Assembly**: +**Context Delegation Model**: Command provides paths and metadata, agent loads context autonomously using progressive loading strategy. + +**Command Provides** (in agent prompt): ```javascript -// Assemble context package for agent -const agentContext = { - session_id: "WFS-[id]", +// Command assembles these simple values and paths for agent +const commandProvides = { + // Session paths + session_metadata_path: ".workflow/active/WFS-{id}/workflow-session.json", + context_package_path: ".workflow/active/WFS-{id}/.process/context-package.json", + test_context_package_path: ".workflow/active/WFS-{id}/.process/test-context-package.json", + output_task_dir: ".workflow/active/WFS-{id}/.task/", + output_impl_plan: ".workflow/active/WFS-{id}/IMPL_PLAN.md", + output_todo_list: ".workflow/active/WFS-{id}/TODO_LIST.md", + + // Simple metadata + session_id: "WFS-{id}", workflow_type: "tdd", + mcp_capabilities: { exa_code: true, exa_web: true, code_index: true }, - // Use memory if available, else load - session_metadata: memory.has("workflow-session.json") - ? memory.get("workflow-session.json") - : Read(.workflow/active/WFS-[id]/workflow-session.json), - - context_package_path: ".workflow/active/WFS-[id]/.process/context-package.json", - - context_package: memory.has("context-package.json") - ? memory.get("context-package.json") - : Read(".workflow/active/WFS-[id]/.process/context-package.json"), - - test_context_package_path: ".workflow/active/WFS-[id]/.process/test-context-package.json", - - test_context_package: memory.has("test-context-package.json") - ? memory.get("test-context-package.json") - : Read(".workflow/active/WFS-[id]/.process/test-context-package.json"), - - // Extract brainstorm artifacts from context package - brainstorm_artifacts: extractBrainstormArtifacts(context_package), - - // Load role analyses using paths from context package - role_analyses: brainstorm_artifacts.role_analyses - .flatMap(role => role.files) - .map(file => Read(file.path)), - - // Load conflict resolution if exists (prefer new JSON format) - conflict_resolution: context_package.conflict_detection?.resolution_file - ? Read(context_package.conflict_detection.resolution_file) // .process/conflict-resolution.json - : (brainstorm_artifacts?.conflict_resolution?.exists - ? Read(brainstorm_artifacts.conflict_resolution.path) - : null), - - // Optional MCP enhancements - mcp_analysis: executeMcpDiscovery() + // User configuration from Phase 0 + user_config: { + supplementaryMaterials: { type: "...", content: [...] }, + executionMethod: "agent|hybrid|cli", + preferredCliTool: "codex|gemini|qwen|auto", + enableResume: true + } } ``` +**Agent Loads Autonomously** (progressive loading): +```javascript +// Agent executes progressive loading based on memory state +const agentLoads = { + // Core (ALWAYS load if not in memory) + session_metadata: loadIfNotInMemory(session_metadata_path), + context_package: loadIfNotInMemory(context_package_path), + + // Selective (based on progressive strategy) + // Priority: synthesis_output > guidance + relevant_role_analyses + brainstorm_content: loadSelectiveBrainstormArtifacts(context_package), + + // On-Demand (load if exists and relevant) + test_context: loadIfExists(test_context_package_path), + conflict_resolution: loadConflictResolution(context_package), + + // Optional (if MCP available) + exploration_results: extractExplorationResults(context_package), + external_research: executeMcpResearch() // If needed +} +``` + +**Progressive Loading Implementation** (agent responsibility): +1. **Check memory first** - skip if already loaded +2. **Load core files** - session metadata + context-package.json +3. **Smart selective loading** - synthesis_output OR (guidance + task-relevant role analyses) +4. **On-demand loading** - test context, conflict resolution (if conflict_risk >= medium) +5. **Extract references** - exploration results, artifact paths from context package + ## TDD Task Structure Reference This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above. @@ -389,14 +599,31 @@ This section provides quick reference for TDD task JSON structure. For complete **Quick Reference**: - Each TDD task contains complete Red-Green-Refactor cycle - Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks) -- Required metadata: `meta.tdd_workflow: true`, `meta.max_iterations: 3` -- Flow control: Exactly 3 steps with `tdd_phase` field (red, green, refactor) -- Context: `tdd_cycles` array with quantified test cases and coverage +- Required metadata: + - `meta.tdd_workflow: true` + - `meta.max_iterations: 3` + - `meta.cli_execution_id: "{session_id}-{task_id}"` + - `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }` +- Context: `tdd_cycles` array with quantified test cases and coverage: + ```javascript + tdd_cycles: [ + { + test_count: 5, // Number of test cases to write + test_cases: ["case1", "case2"], // Enumerated test scenarios + implementation_scope: "...", // Files and functions to implement + expected_coverage: ">=85%" // Coverage target + } + ] + ``` +- Context: `focus_paths` use absolute or clear relative paths +- Flow control: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor") +- Flow control: `pre_analysis` includes exploration integration_points analysis +- Command field: Added per `userConfig.executionMethod` (agent/hybrid/cli) - See Phase 2 agent prompt for full schema and requirements ## Output Files Structure ``` -.workflow/active//{session-id}/ +.workflow/active/{session-id}/ ├── IMPL_PLAN.md # Unified plan with TDD Implementation Tasks section ├── TODO_LIST.md # Progress tracking with internal TDD phase indicators ├── .task/ @@ -432,9 +659,9 @@ This section provides quick reference for TDD task JSON structure. For complete - No circular dependencies allowed ### Task Limits -- Maximum 10 total tasks (simple + subtasks) -- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers) -- Re-scope requirements if >10 tasks needed +- Maximum 18 total tasks (simple + subtasks) - hard limit for TDD workflows +- Flat hierarchy (≤5 tasks) or two-level (6-18 tasks with containers) +- Re-scope requirements if >18 tasks needed ### TDD Workflow Validation - `meta.tdd_workflow` must be true @@ -454,7 +681,7 @@ This section provides quick reference for TDD task JSON structure. For complete ### TDD Generation Errors | Error | Cause | Resolution | |-------|-------|------------| -| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features | +| Task count exceeds 18 | Too many features or subtasks | Re-scope requirements or merge features into multiple TDD sessions | | Missing test framework | No test config | Configure testing first | | Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md | | Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata | @@ -512,6 +739,6 @@ IMPL (Green phase) tasks include automatic test-fix cycle: ## Configuration Options -- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen) +- **meta.max_iterations**: Number of fix attempts in Green phase (default: 3) - **CLI tool usage**: Determined semantically from user's task description via `command` field in implementation_approach