mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: Enhance TDD workflow with specialized executor and optimized task generation
- Create tdd-developer.md: Specialized TDD agent with Red-Green-Refactor awareness - Full TDD metadata parsing (tdd_workflow, max_iterations, cli_execution) - Green phase Test-Fix Cycle with automatic diagnosis and repair - CLI session resumption strategies (new/resume/fork/merge_fork) - Auto-revert safety mechanism when max_iterations reached - Optimize task-generate-tdd.md: Enhanced task generation with CLI support - Phase 0: User configuration questionnaire (materials, execution method, CLI tool) - Phase 1: Progressive loading strategy (Core → Selective → On-Demand) - CLI Execution ID management with dependency-based strategy selection - Fixed task limit to 18 (consistent with system-wide limit) - Fixed double-slash path issues in output structure - Enhanced tdd_cycles schema documentation with full structure - Unified resume_from type documentation (string | string[]) - Update tdd-plan.md: Workflow orchestrator improvements - Phase 0 user configuration details - Enhanced validation rules for CLI execution IDs - Updated error handling for 18-task limit Validated by Gemini CLI analysis - complete execution chain compatibility confirmed.
This commit is contained in:
catlog22
530
.claude/agents/tdd-developer.md
Normal file
530
.claude/agents/tdd-developer.md
Normal file
@@ -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
|
||||
}
|
||||
```
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user