mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
Add TDD Structure Validation and Verification Phases with Comprehensive Reporting
- Introduced Phase 6: TDD Structure Validation to ensure compliance with TDD workflow standards, including task structure validation, dependency checks, and user configuration verification. - Implemented Phase 7: TDD Verification for full compliance checks, including task chain structure validation, coverage analysis, and TDD cycle verification. - Generated detailed TDD compliance reports with quality gate recommendations based on objective criteria. - Added documentation for new commands and workflows in the Claude Commands index.
This commit is contained in:
catlog22
@@ -0,0 +1,57 @@
|
||||
# Phase 1: Session Discovery
|
||||
|
||||
Create or discover TDD workflow session and extract session ID.
|
||||
|
||||
## Objective
|
||||
|
||||
- Create a new TDD workflow session via `/workflow:session:start`
|
||||
- Extract session ID for subsequent phases
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1.1: Execute Session Start
|
||||
|
||||
```javascript
|
||||
Skill(skill="workflow:session:start", args="--type tdd --auto \"TDD: [structured-description]\"")
|
||||
```
|
||||
|
||||
**TDD Structured Format**:
|
||||
```
|
||||
TDD: [Feature Name]
|
||||
GOAL: [Objective]
|
||||
SCOPE: [Included/excluded]
|
||||
CONTEXT: [Background]
|
||||
TEST_FOCUS: [Test scenarios]
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
TDD: JWT Authentication
|
||||
GOAL: Implement JWT-based authentication
|
||||
SCOPE: Email/password login, token generation, token refresh endpoints
|
||||
CONTEXT: Existing user database schema, REST API
|
||||
TEST_FOCUS: Login flow, token validation, refresh rotation, error cases
|
||||
```
|
||||
|
||||
### Step 1.2: Parse Output
|
||||
|
||||
- Extract: `SESSION_ID: WFS-[id]` (store as `sessionId`)
|
||||
|
||||
**Validation**:
|
||||
- Session ID successfully extracted
|
||||
- Session directory `.workflow/active/[sessionId]/` exists
|
||||
|
||||
**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `.workflow/archives/` for archived sessions.
|
||||
|
||||
**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `sessionId` (WFS-xxx)
|
||||
- **TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 2: Context Gathering](02-context-gathering.md).
|
||||
406
.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md
Normal file
406
.claude/skills/workflow-tdd-plan/phases/02-context-gathering.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# Phase 2: Context Gathering
|
||||
|
||||
Gather project context and analyze codebase via context-search-agent with parallel exploration for TDD planning.
|
||||
|
||||
## Objective
|
||||
|
||||
- Gather project context using context-search-agent
|
||||
- Identify critical files, architecture patterns, and constraints
|
||||
- Detect conflict risk level for Phase 4 decision
|
||||
- Update planning-notes.md with findings
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
|
||||
- **Detection-First**: Check for existing context-package before executing
|
||||
- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
|
||||
- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 2.1: Context-Package Detection
|
||||
|
||||
**Execute First** - Check if valid package already exists:
|
||||
|
||||
```javascript
|
||||
const contextPackagePath = `.workflow/active/${sessionId}/.process/context-package.json`;
|
||||
|
||||
if (file_exists(contextPackagePath)) {
|
||||
const existing = Read(contextPackagePath);
|
||||
|
||||
// Validate package belongs to current session
|
||||
if (existing?.metadata?.session_id === sessionId) {
|
||||
console.log("Valid context-package found for session:", sessionId);
|
||||
console.log("Stats:", existing.statistics);
|
||||
console.log("Conflict Risk:", existing.conflict_detection.risk_level);
|
||||
// Skip execution, store variables and proceed to Step 2.5
|
||||
contextPath = contextPackagePath;
|
||||
conflictRisk = existing.conflict_detection.risk_level;
|
||||
return; // Early exit - skip Steps 2.2-2.4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2.2: Complexity Assessment & Parallel Explore
|
||||
|
||||
**Only execute if Step 2.1 finds no valid package**
|
||||
|
||||
```javascript
|
||||
// 2.2.1 Complexity Assessment
|
||||
function analyzeTaskComplexity(taskDescription) {
|
||||
const text = taskDescription.toLowerCase();
|
||||
if (/architect|refactor|restructure|modular|cross-module/.test(text)) return 'High';
|
||||
if (/multiple|several|integrate|migrate|extend/.test(text)) return 'Medium';
|
||||
return 'Low';
|
||||
}
|
||||
|
||||
const ANGLE_PRESETS = {
|
||||
architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'],
|
||||
security: ['security', 'auth-patterns', 'dataflow', 'validation'],
|
||||
performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
|
||||
bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
|
||||
feature: ['patterns', 'integration-points', 'testing', 'dependencies'],
|
||||
refactor: ['architecture', 'patterns', 'dependencies', 'testing']
|
||||
};
|
||||
|
||||
function selectAngles(taskDescription, complexity) {
|
||||
const text = taskDescription.toLowerCase();
|
||||
let preset = 'feature';
|
||||
if (/refactor|architect|restructure/.test(text)) preset = 'architecture';
|
||||
else if (/security|auth|permission/.test(text)) preset = 'security';
|
||||
else if (/performance|slow|optimi/.test(text)) preset = 'performance';
|
||||
else if (/fix|bug|error|issue/.test(text)) preset = 'bugfix';
|
||||
|
||||
const count = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1);
|
||||
return ANGLE_PRESETS[preset].slice(0, count);
|
||||
}
|
||||
|
||||
const complexity = analyzeTaskComplexity(task_description);
|
||||
const selectedAngles = selectAngles(task_description, complexity);
|
||||
const sessionFolder = `.workflow/active/${sessionId}/.process`;
|
||||
|
||||
// 2.2.2 Launch Parallel Explore Agents
|
||||
const explorationTasks = selectedAngles.map((angle, index) =>
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Explore: ${angle}`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Execute **${angle}** exploration for TDD task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints.
|
||||
|
||||
## Assigned Context
|
||||
- **Exploration Angle**: ${angle}
|
||||
- **Task Description**: ${task_description}
|
||||
- **Session ID**: ${sessionId}
|
||||
- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
|
||||
- **Output File**: ${sessionFolder}/exploration-${angle}.json
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
|
||||
2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
|
||||
3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
|
||||
|
||||
## Exploration Strategy (${angle} focus)
|
||||
|
||||
**Step 1: Structural Scan** (Bash)
|
||||
- get_modules_by_depth.sh -> identify modules related to ${angle}
|
||||
- find/rg -> locate files relevant to ${angle} aspect
|
||||
- Analyze imports/dependencies from ${angle} perspective
|
||||
|
||||
**Step 2: Semantic Analysis** (Gemini CLI)
|
||||
- How does existing code handle ${angle} concerns?
|
||||
- What patterns are used for ${angle}?
|
||||
- Where would new code integrate from ${angle} viewpoint?
|
||||
|
||||
**Step 3: Write Output**
|
||||
- Consolidate ${angle} findings into JSON
|
||||
- Identify ${angle}-specific clarification needs
|
||||
|
||||
## Expected Output
|
||||
|
||||
**File**: ${sessionFolder}/exploration-${angle}.json
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
|
||||
|
||||
**Required Fields** (all ${angle} focused):
|
||||
- project_structure: Modules/architecture relevant to ${angle}
|
||||
- relevant_files: Files affected from ${angle} perspective
|
||||
**MANDATORY**: Every file MUST use structured object format with ALL required fields:
|
||||
[{path: "src/file.ts", relevance: 0.85, rationale: "Contains AuthService.login()", role: "modify_target", discovery_source: "bash-scan", key_symbols: ["AuthService", "login"]}]
|
||||
- **rationale** (required): Specific selection basis tied to ${angle} topic (>10 chars, not generic)
|
||||
- **role** (required): modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only
|
||||
- **discovery_source** (recommended): bash-scan|cli-analysis|ace-search|dependency-trace|manual
|
||||
- **key_symbols** (recommended): Key functions/classes/types in the file relevant to the task
|
||||
- Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low
|
||||
- patterns: ${angle}-related patterns to follow
|
||||
- dependencies: Dependencies relevant to ${angle}
|
||||
- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations)
|
||||
- constraints: ${angle}-specific limitations/conventions
|
||||
- clarification_needs: ${angle}-related ambiguities (options array + recommended index)
|
||||
- _metadata.exploration_angle: "${angle}"
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat explore-json-schema.json
|
||||
- [ ] get_modules_by_depth.sh executed
|
||||
- [ ] At least 3 relevant files identified with ${angle} rationale
|
||||
- [ ] Patterns are actionable (code examples, not generic advice)
|
||||
- [ ] Integration points include file:line locations
|
||||
- [ ] Constraints are project-specific to ${angle}
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] clarification_needs includes options + recommended
|
||||
|
||||
## Output
|
||||
Write: ${sessionFolder}/exploration-${angle}.json
|
||||
Return: 2-3 sentence summary of ${angle} findings
|
||||
`
|
||||
)
|
||||
);
|
||||
|
||||
// 2.2.3 Generate Manifest after all complete
|
||||
const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`).split('\n').filter(f => f.trim());
|
||||
const explorationManifest = {
|
||||
session_id: sessionId,
|
||||
task_description,
|
||||
timestamp: new Date().toISOString(),
|
||||
complexity,
|
||||
exploration_count: selectedAngles.length,
|
||||
angles_explored: selectedAngles,
|
||||
explorations: explorationFiles.map(file => {
|
||||
const data = JSON.parse(Read(file));
|
||||
return { angle: data._metadata.exploration_angle, file: file.split('/').pop(), path: file, index: data._metadata.exploration_index };
|
||||
})
|
||||
};
|
||||
Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2));
|
||||
```
|
||||
|
||||
### Step 2.3: Invoke Context-Search Agent
|
||||
|
||||
**Only execute after Step 2.2 completes**
|
||||
|
||||
```javascript
|
||||
// Load user intent from planning-notes.md (from Phase 1)
|
||||
const planningNotesPath = `.workflow/active/${sessionId}/planning-notes.md`;
|
||||
let userIntent = { goal: task_description, key_constraints: "None specified" };
|
||||
|
||||
if (file_exists(planningNotesPath)) {
|
||||
const notesContent = Read(planningNotesPath);
|
||||
const goalMatch = notesContent.match(/\*\*GOAL\*\*:\s*(.+)/);
|
||||
const constraintsMatch = notesContent.match(/\*\*KEY_CONSTRAINTS\*\*:\s*(.+)/);
|
||||
if (goalMatch) userIntent.goal = goalMatch[1].trim();
|
||||
if (constraintsMatch) userIntent.key_constraints = constraintsMatch[1].trim();
|
||||
}
|
||||
|
||||
Task(
|
||||
subagent_type="context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather comprehensive context for TDD plan",
|
||||
prompt=`
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution with priority sorting
|
||||
|
||||
## Session Information
|
||||
- **Session ID**: ${sessionId}
|
||||
- **Task Description**: ${task_description}
|
||||
- **Output Path**: .workflow/${sessionId}/.process/context-package.json
|
||||
|
||||
## User Intent (from Phase 1 - Planning Notes)
|
||||
**GOAL**: ${userIntent.goal}
|
||||
**KEY_CONSTRAINTS**: ${userIntent.key_constraints}
|
||||
|
||||
This is the PRIMARY context source - all subsequent analysis must align with user intent.
|
||||
|
||||
## Exploration Input (from Step 2.2)
|
||||
- **Manifest**: ${sessionFolder}/explorations-manifest.json
|
||||
- **Exploration Count**: ${explorationManifest.exploration_count}
|
||||
- **Angles**: ${explorationManifest.angles_explored.join(', ')}
|
||||
- **Complexity**: ${complexity}
|
||||
|
||||
## Mission
|
||||
Execute complete context-search-agent workflow for TDD implementation planning:
|
||||
|
||||
### Phase 1: Initialization & Pre-Analysis
|
||||
1. **Project State Loading**:
|
||||
- Run: \`ccw spec load --category execution\` to load project context, tech stack, and guidelines.
|
||||
- If files don't exist, proceed with fresh analysis.
|
||||
2. **Detection**: Check for existing context-package (early exit if valid)
|
||||
3. **Foundation**: Initialize CodexLens, get project structure, load docs
|
||||
4. **Analysis**: Extract keywords, determine scope, classify complexity
|
||||
|
||||
### Phase 2: Multi-Source Context Discovery
|
||||
Execute all discovery tracks (WITH USER INTENT INTEGRATION):
|
||||
- **Track -1**: User Intent & Priority Foundation (EXECUTE FIRST)
|
||||
- Load user intent (GOAL, KEY_CONSTRAINTS) from session input
|
||||
- Map user requirements to codebase entities (files, modules, patterns)
|
||||
- Establish baseline priority scores based on user goal alignment
|
||||
- Output: user_intent_mapping.json with preliminary priority scores
|
||||
|
||||
- **Track 0**: Exploration Synthesis (load explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points)
|
||||
- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
|
||||
- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
|
||||
- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
|
||||
- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
|
||||
|
||||
### Phase 3: Synthesis, Assessment & Packaging
|
||||
1. Apply relevance scoring and build dependency graph
|
||||
2. **Synthesize 5-source data**: Merge findings from all sources
|
||||
- Priority order: User Intent > Archive > Docs > Exploration > Code > Web
|
||||
- **Prioritize the context from project-tech.json** for architecture and tech stack
|
||||
3. **Context Priority Sorting**:
|
||||
a. Combine scores from Track -1 (user intent alignment) + relevance scores + exploration critical_files
|
||||
b. Classify files into priority tiers:
|
||||
- **Critical** (score >= 0.85): Directly mentioned in user goal OR exploration critical_files
|
||||
- **High** (0.70-0.84): Key dependencies, patterns required for goal
|
||||
- **Medium** (0.50-0.69): Supporting files, indirect dependencies
|
||||
- **Low** (< 0.50): Contextual awareness only
|
||||
c. Generate dependency_order: Based on dependency graph + user goal sequence
|
||||
d. Document sorting_rationale: Explain prioritization logic
|
||||
4. **Populate project_context**: Directly use the overview from project-tech.json
|
||||
5. **Populate project_guidelines**: Load from specs/*.md
|
||||
6. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
|
||||
7. Perform conflict detection with risk assessment
|
||||
8. **Inject historical conflicts** from archive analysis into conflict_detection
|
||||
9. **Generate prioritized_context section**:
|
||||
{
|
||||
"prioritized_context": {
|
||||
"user_intent": { "goal": "...", "scope": "...", "key_constraints": ["..."] },
|
||||
"priority_tiers": {
|
||||
"critical": [{ "path": "...", "relevance": 0.95, "rationale": "..." }],
|
||||
"high": [...], "medium": [...], "low": [...]
|
||||
},
|
||||
"dependency_order": ["module1", "module2", "module3"],
|
||||
"sorting_rationale": "Based on user goal alignment, exploration critical files, and dependency graph"
|
||||
}
|
||||
}
|
||||
10. Generate and validate context-package.json with prioritized_context field
|
||||
|
||||
## Output Requirements
|
||||
Complete context-package.json with:
|
||||
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
|
||||
- **project_context**: description, technology_stack, architecture, key_components (from project-tech.json)
|
||||
- **project_guidelines**: {conventions, constraints, quality_rules, learnings} (from specs/*.md)
|
||||
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
|
||||
- **dependencies**: {internal[], external[]} with dependency graph
|
||||
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
|
||||
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
|
||||
- **exploration_results**: {manifest_path, exploration_count, angles, explorations[], aggregated_insights}
|
||||
- **prioritized_context**: {user_intent, priority_tiers{critical, high, medium, low}, dependency_order[], sorting_rationale}
|
||||
|
||||
## Quality Validation
|
||||
Before completion verify:
|
||||
- [ ] Valid JSON format with all required fields
|
||||
- [ ] File relevance accuracy >80%
|
||||
- [ ] Dependency graph complete (max 2 transitive levels)
|
||||
- [ ] Conflict risk level calculated correctly
|
||||
- [ ] No sensitive data exposed
|
||||
- [ ] Total files <= 50 (prioritize high-relevance)
|
||||
|
||||
## Planning Notes Record (REQUIRED)
|
||||
After completing context-package.json, append to planning-notes.md:
|
||||
|
||||
**File**: .workflow/active/${sessionId}/planning-notes.md
|
||||
**Location**: Under "## Context Findings (Phase 2)" section
|
||||
**Format**:
|
||||
### [Context-Search Agent] YYYY-MM-DD
|
||||
- **Note**: [Brief summary of key findings]
|
||||
|
||||
Execute autonomously following agent documentation.
|
||||
Report completion with statistics.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Step 2.4: Output Verification
|
||||
|
||||
After agent completes, verify output:
|
||||
|
||||
```javascript
|
||||
// Verify file was created
|
||||
const outputPath = `.workflow/active/${sessionId}/.process/context-package.json`;
|
||||
if (!file_exists(outputPath)) {
|
||||
throw new Error("Agent failed to generate context-package.json");
|
||||
}
|
||||
|
||||
// Store variables for subsequent phases
|
||||
contextPath = outputPath;
|
||||
|
||||
// Verify exploration_results included
|
||||
const pkg = JSON.parse(Read(outputPath));
|
||||
if (pkg.exploration_results?.exploration_count > 0) {
|
||||
console.log(`Exploration results aggregated: ${pkg.exploration_results.exploration_count} angles`);
|
||||
}
|
||||
|
||||
conflictRisk = pkg.conflict_detection?.risk_level || 'low';
|
||||
```
|
||||
|
||||
### TodoWrite Update (Phase 2 in progress - tasks attached)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
|
||||
{"content": " -> Analyze codebase structure", "status": "in_progress", "activeForm": "Analyzing codebase structure"},
|
||||
{"content": " -> Identify integration points", "status": "pending", "activeForm": "Identifying integration points"},
|
||||
{"content": " -> Generate context package", "status": "pending", "activeForm": "Generating context package"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
### TodoWrite Update (Phase 2 completed - tasks collapsed)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
### Step 2.5: Update Planning Notes
|
||||
|
||||
After context gathering completes, update planning-notes.md with findings:
|
||||
|
||||
```javascript
|
||||
// Read context-package to extract key findings
|
||||
const contextPackage = JSON.parse(Read(contextPath))
|
||||
const conflictRisk = contextPackage.conflict_detection?.risk_level || 'low'
|
||||
const criticalFiles = (contextPackage.exploration_results?.aggregated_insights?.critical_files || [])
|
||||
.slice(0, 5).map(f => f.path)
|
||||
const archPatterns = contextPackage.project_context?.architecture_patterns || []
|
||||
const constraints = contextPackage.exploration_results?.aggregated_insights?.constraints || []
|
||||
|
||||
// Append Phase 2 findings to planning-notes.md
|
||||
Edit(planningNotesPath, {
|
||||
old: '## Context Findings (Phase 2)\n(To be filled by context-gather)',
|
||||
new: `## Context Findings (Phase 2)
|
||||
|
||||
- **CRITICAL_FILES**: ${criticalFiles.join(', ') || 'None identified'}
|
||||
- **ARCHITECTURE**: ${archPatterns.join(', ') || 'Not detected'}
|
||||
- **CONFLICT_RISK**: ${conflictRisk}
|
||||
- **CONSTRAINTS**: ${constraints.length > 0 ? constraints.join('; ') : 'None'}`
|
||||
})
|
||||
|
||||
// Append Phase 2 constraints to consolidated list
|
||||
Edit(planningNotesPath, {
|
||||
old: '## Consolidated Constraints (Phase 4 Input)',
|
||||
new: `## Consolidated Constraints (Phase 4 Input)
|
||||
${constraints.map((c, i) => `${i + 2}. [Context] ${c}`).join('\n')}`
|
||||
})
|
||||
```
|
||||
|
||||
**Auto-Continue**: Return to user showing Phase 2 results, then auto-continue to Phase 3.
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `contextPath` (path to context-package.json)
|
||||
- **Variable**: `conflictRisk` (none/low/medium/high)
|
||||
- **File**: `context-package.json`
|
||||
- **TodoWrite**: Mark Phase 2 completed, determine Phase 3 or Phase 4
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator. Orchestrator continues to [Phase 3: Test Coverage Analysis](03-test-coverage-analysis.md).
|
||||
@@ -0,0 +1,172 @@
|
||||
# Phase 3: Test Coverage Analysis
|
||||
|
||||
Analyze existing test coverage, detect test framework, and identify coverage gaps.
|
||||
|
||||
## Objective
|
||||
|
||||
- Analyze existing codebase for test patterns and conventions
|
||||
- Detect current test coverage and framework
|
||||
- Identify related components and integration points
|
||||
- Generate test-context-package.json
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution
|
||||
- **Detection-First**: Check for existing test-context-package before executing
|
||||
- **Coverage-First**: Analyze existing test coverage before planning new tests
|
||||
- **Source Context Loading**: Import implementation summaries from source session
|
||||
- **Standardized Output**: Generate `.workflow/active/{session}/.process/test-context-package.json`
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 3.1: Test-Context-Package Detection
|
||||
|
||||
**Execute First** - Check if valid package already exists:
|
||||
|
||||
```javascript
|
||||
const testContextPath = `.workflow/active/${sessionId}/.process/test-context-package.json`;
|
||||
|
||||
if (file_exists(testContextPath)) {
|
||||
const existing = Read(testContextPath);
|
||||
|
||||
// Validate package belongs to current session
|
||||
if (existing?.metadata?.test_session_id === sessionId) {
|
||||
console.log("Valid test-context-package found for session:", sessionId);
|
||||
console.log("Coverage Stats:", existing.test_coverage.coverage_stats);
|
||||
console.log("Framework:", existing.test_framework.framework);
|
||||
console.log("Missing Tests:", existing.test_coverage.missing_tests.length);
|
||||
// Skip execution, store variable and proceed
|
||||
testContextPath_var = testContextPath;
|
||||
return; // Early exit - skip Steps 3.2-3.3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3.2: Invoke Test-Context-Search Agent
|
||||
|
||||
**Only execute if Step 3.1 finds no valid package**
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="test-context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather test coverage context",
|
||||
prompt=`
|
||||
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
|
||||
|
||||
## Session Information
|
||||
- **Test Session ID**: ${sessionId}
|
||||
- **Output Path**: .workflow/active/${sessionId}/.process/test-context-package.json
|
||||
|
||||
## Mission
|
||||
Execute complete test-context-search-agent workflow for test generation planning:
|
||||
|
||||
### Phase 1: Session Validation & Source Context Loading
|
||||
1. **Detection**: Check for existing test-context-package (early exit if valid)
|
||||
2. **Test Session Validation**: Load test session metadata, extract source_session reference
|
||||
3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack
|
||||
|
||||
### Phase 2: Test Coverage Analysis
|
||||
Execute coverage discovery:
|
||||
- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files)
|
||||
- **Track 2**: Coverage gap analysis (match implementation files to test files)
|
||||
- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module)
|
||||
|
||||
### Phase 3: Framework Detection & Packaging
|
||||
1. Framework identification from package.json/requirements.txt
|
||||
2. Convention analysis from existing test patterns
|
||||
3. Generate and validate test-context-package.json
|
||||
|
||||
## Output Requirements
|
||||
Complete test-context-package.json with:
|
||||
- **metadata**: test_session_id, source_session_id, task_type, complexity
|
||||
- **source_context**: implementation_summaries, tech_stack, project_patterns
|
||||
- **test_coverage**: existing_tests[], missing_tests[], coverage_stats
|
||||
- **test_framework**: framework, version, test_pattern, conventions
|
||||
- **assets**: implementation_summary[], existing_test[], source_code[] with priorities
|
||||
- **focus_areas**: Test generation guidance based on coverage gaps
|
||||
|
||||
## Quality Validation
|
||||
Before completion verify:
|
||||
- [ ] Valid JSON format with all required fields
|
||||
- [ ] Source session context loaded successfully
|
||||
- [ ] Test coverage gaps identified
|
||||
- [ ] Test framework detected (or marked as 'unknown')
|
||||
- [ ] Coverage percentage calculated correctly
|
||||
- [ ] Missing tests catalogued with priority
|
||||
- [ ] Execution time < 30 seconds (< 60s for large codebases)
|
||||
|
||||
Execute autonomously following agent documentation.
|
||||
Report completion with coverage statistics.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3.3: Output Verification
|
||||
|
||||
After agent completes, verify output:
|
||||
|
||||
```javascript
|
||||
// Verify file was created
|
||||
const outputPath = `.workflow/active/${sessionId}/.process/test-context-package.json`;
|
||||
if (!file_exists(outputPath)) {
|
||||
throw new Error("Agent failed to generate test-context-package.json");
|
||||
}
|
||||
|
||||
// Load and display summary
|
||||
const testContext = JSON.parse(Read(outputPath));
|
||||
console.log("Test context package generated successfully");
|
||||
console.log("Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%");
|
||||
console.log("Tests to generate:", testContext.test_coverage.missing_tests.length);
|
||||
|
||||
// Store variable for subsequent phases
|
||||
testContextPath_var = outputPath;
|
||||
```
|
||||
|
||||
### TodoWrite Update (Phase 3 Skill executed - tasks attached)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "in_progress", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": " -> Detect test framework and conventions", "status": "in_progress", "activeForm": "Detecting test framework"},
|
||||
{"content": " -> Analyze existing test coverage", "status": "pending", "activeForm": "Analyzing test coverage"},
|
||||
{"content": " -> Identify coverage gaps", "status": "pending", "activeForm": "Identifying coverage gaps"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Agent execution **attaches** test-context-search's 3 tasks. Orchestrator **executes** these tasks.
|
||||
|
||||
**Next Action**: Tasks attached -> **Execute Phase 3.1-3.3** sequentially
|
||||
|
||||
### TodoWrite Update (Phase 3 completed - tasks collapsed)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Phase 3 tasks completed and collapsed to summary.
|
||||
|
||||
**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4/5 (depending on conflict_risk)
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `testContextPath` (path to test-context-package.json)
|
||||
- **TodoWrite**: Mark Phase 3 completed
|
||||
|
||||
## Next Phase
|
||||
|
||||
Based on `conflictRisk` from Phase 2:
|
||||
- If conflictRisk >= medium -> [Phase 4: Conflict Resolution](04-conflict-resolution.md)
|
||||
- If conflictRisk < medium -> Skip to [Phase 5: TDD Task Generation](05-tdd-task-generation.md)
|
||||
@@ -0,0 +1,426 @@
|
||||
# Phase 4: Conflict Resolution (Conditional)
|
||||
|
||||
Detect and resolve conflicts with CLI analysis. This phase is **conditional** - only executes when `conflict_risk >= medium`.
|
||||
|
||||
## Objective
|
||||
|
||||
- Detect conflicts between planned changes and existing codebase
|
||||
- Detect module scenario uniqueness (functional overlaps)
|
||||
- Present conflicts to user with resolution strategies
|
||||
- Apply selected resolution strategies
|
||||
- Update planning-notes.md with conflict decisions
|
||||
|
||||
## Trigger Condition
|
||||
|
||||
Only execute when context-package.json indicates `conflict_risk` is "medium" or "high".
|
||||
If `conflict_risk` is "none" or "low", skip directly to Phase 5.
|
||||
|
||||
## Conflict Categories
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| **Architecture** | Incompatible design patterns, module structure changes |
|
||||
| **API** | Breaking contract changes, signature modifications |
|
||||
| **Data Model** | Schema modifications, type breaking changes |
|
||||
| **Dependency** | Version incompatibilities, setup conflicts |
|
||||
| **ModuleOverlap** | Functional overlap, scenario boundary ambiguity, duplicate responsibility |
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 4.1: Validation
|
||||
|
||||
```javascript
|
||||
// 1. Verify session directory exists
|
||||
const sessionDir = `.workflow/active/${sessionId}`;
|
||||
if (!file_exists(sessionDir)) {
|
||||
throw new Error(`Session directory not found: ${sessionDir}`);
|
||||
}
|
||||
|
||||
// 2. Load context-package.json
|
||||
const contextPackage = JSON.parse(Read(contextPath));
|
||||
|
||||
// 3. Check conflict_risk (skip if none/low)
|
||||
const conflictRisk = contextPackage.conflict_detection?.risk_level || 'low';
|
||||
if (conflictRisk === 'none' || conflictRisk === 'low') {
|
||||
console.log("No significant conflicts detected, proceeding to TDD task generation");
|
||||
// Skip directly to Phase 5
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4.2: CLI-Powered Conflict Analysis
|
||||
|
||||
**Agent Delegation**:
|
||||
|
||||
```javascript
|
||||
Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
## Context
|
||||
- Session: ${sessionId}
|
||||
- Risk: ${conflictRisk}
|
||||
- Files: ${existing_files_list}
|
||||
|
||||
## Exploration Context (from context-package.exploration_results)
|
||||
- Exploration Count: ${contextPackage.exploration_results?.exploration_count || 0}
|
||||
- Angles Analyzed: ${JSON.stringify(contextPackage.exploration_results?.angles || [])}
|
||||
- Pre-identified Conflict Indicators: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.conflict_indicators || [])}
|
||||
- Critical Files: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.critical_files?.map(f => f.path) || [])}
|
||||
- All Patterns: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_patterns || [])}
|
||||
- All Integration Points: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_integration_points || [])}
|
||||
|
||||
## Analysis Steps
|
||||
|
||||
### 0. Load Output Schema (MANDATORY)
|
||||
Execute: cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json
|
||||
|
||||
### 1. Load Context
|
||||
- Read existing files from conflict_detection.existing_files
|
||||
- Load plan from .workflow/active/${sessionId}/.process/context-package.json
|
||||
- Load exploration_results and use aggregated_insights for enhanced analysis
|
||||
- Extract role analyses and requirements
|
||||
|
||||
### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness)
|
||||
|
||||
Primary (Gemini):
|
||||
ccw cli -p "
|
||||
PURPOSE: Detect conflicts between plan and codebase, using exploration insights
|
||||
TASK:
|
||||
* Review pre-identified conflict_indicators from exploration results
|
||||
* Compare architectures (use exploration key_patterns)
|
||||
* Identify breaking API changes
|
||||
* Detect data model incompatibilities
|
||||
* Assess dependency conflicts
|
||||
* Analyze module scenario uniqueness
|
||||
- Use exploration integration_points for precise locations
|
||||
- Cross-validate with exploration critical_files
|
||||
- Generate clarification questions for boundary definition
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/${sessionId}/**/*
|
||||
EXPECTED: Conflict list with severity ratings, including:
|
||||
- Validation of exploration conflict_indicators
|
||||
- ModuleOverlap conflicts with overlap_analysis
|
||||
- Targeted clarification questions
|
||||
CONSTRAINTS: Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY
|
||||
" --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root}
|
||||
|
||||
Fallback: Qwen (same prompt) -> Claude (manual analysis)
|
||||
|
||||
### 3. Generate Strategies (2-4 per conflict)
|
||||
|
||||
Template per conflict:
|
||||
- Severity: Critical/High/Medium
|
||||
- Category: Architecture/API/Data/Dependency/ModuleOverlap
|
||||
- Affected files + impact
|
||||
- For ModuleOverlap: Include overlap_analysis with existing modules and scenarios
|
||||
- Options with pros/cons, effort, risk
|
||||
- For ModuleOverlap strategies: Add clarification_needed questions for boundary definition
|
||||
- Recommended strategy + rationale
|
||||
|
||||
### 4. Return Structured Conflict Data
|
||||
|
||||
Output to conflict-resolution.json (generated in Phase 4)
|
||||
|
||||
**Schema Reference**: Execute cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json to get full schema
|
||||
|
||||
Return JSON following the schema. Key requirements:
|
||||
- Minimum 2 strategies per conflict, max 4
|
||||
- All text in Chinese for user-facing fields (brief, name, pros, cons, modification_suggestions)
|
||||
- modifications.old_content: 20-100 chars for unique Edit tool matching
|
||||
- modifications.new_content: preserves markdown formatting
|
||||
- modification_suggestions: 2-5 actionable suggestions for custom handling
|
||||
|
||||
### 5. Planning Notes Record (REQUIRED)
|
||||
After analysis complete, append to planning-notes.md:
|
||||
|
||||
**File**: .workflow/active/${sessionId}/planning-notes.md
|
||||
**Location**: Under "## Conflict Decisions (Phase 3)" section
|
||||
**Format**:
|
||||
### [Conflict-Resolution Agent] YYYY-MM-DD
|
||||
- **Note**: [Brief summary of conflict types, strategies, key decisions]
|
||||
`)
|
||||
```
|
||||
|
||||
### Step 4.3: Iterative User Interaction
|
||||
|
||||
```javascript
|
||||
const autoYes = workflowPreferences?.autoYes || false;
|
||||
|
||||
FOR each conflict:
|
||||
round = 0, clarified = false, userClarifications = []
|
||||
|
||||
WHILE (!clarified && round++ < 10):
|
||||
// 1. Display conflict info (text output for context)
|
||||
displayConflictSummary(conflict) // id, brief, severity, overlap_analysis if ModuleOverlap
|
||||
|
||||
// 2. Strategy selection
|
||||
if (autoYes) {
|
||||
console.log(`[autoYes] Auto-selecting recommended strategy`)
|
||||
selectedStrategy = conflict.strategies[conflict.recommended || 0]
|
||||
clarified = true // Skip clarification loop
|
||||
} else {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: formatStrategiesForDisplay(conflict.strategies),
|
||||
header: "Strategy",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
...conflict.strategies.map((s, i) => ({
|
||||
label: `${s.name}${i === conflict.recommended ? ' (Recommended)' : ''}`,
|
||||
description: `${s.complexity} complexity | ${s.risk} risk${s.clarification_needed?.length ? ' | Needs clarification' : ''}`
|
||||
})),
|
||||
{ label: "Custom modification", description: `Suggestions: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
// 3. Handle selection
|
||||
if (userChoice === "Custom modification") {
|
||||
customConflicts.push({ id, brief, category, suggestions, overlap_analysis })
|
||||
break
|
||||
}
|
||||
|
||||
selectedStrategy = findStrategyByName(userChoice)
|
||||
}
|
||||
|
||||
// 4. Clarification (if needed) - batched max 4 per call
|
||||
if (!autoYes && selectedStrategy.clarification_needed?.length > 0) {
|
||||
for (batch of chunk(selectedStrategy.clarification_needed, 4)) {
|
||||
AskUserQuestion({
|
||||
questions: batch.map((q, i) => ({
|
||||
question: q, header: `Clarify${i+1}`, multiSelect: false,
|
||||
options: [{ label: "Provide details", description: "Enter answer" }]
|
||||
}))
|
||||
})
|
||||
userClarifications.push(...collectAnswers(batch))
|
||||
}
|
||||
|
||||
// 5. Agent re-analysis
|
||||
reanalysisResult = Task({
|
||||
subagent_type: "cli-execution-agent",
|
||||
run_in_background: false,
|
||||
prompt: `Conflict: ${conflict.id}, Strategy: ${selectedStrategy.name}
|
||||
User Clarifications: ${JSON.stringify(userClarifications)}
|
||||
Output: { uniqueness_confirmed, rationale, updated_strategy, remaining_questions }`
|
||||
})
|
||||
|
||||
if (reanalysisResult.uniqueness_confirmed) {
|
||||
selectedStrategy = { ...reanalysisResult.updated_strategy, clarifications: userClarifications }
|
||||
clarified = true
|
||||
} else {
|
||||
selectedStrategy.clarification_needed = reanalysisResult.remaining_questions
|
||||
}
|
||||
} else {
|
||||
clarified = true
|
||||
}
|
||||
|
||||
if (clarified) resolvedConflicts.push({ conflict, strategy: selectedStrategy })
|
||||
END WHILE
|
||||
END FOR
|
||||
|
||||
selectedStrategies = resolvedConflicts.map(r => ({
|
||||
conflict_id: r.conflict.id, strategy: r.strategy, clarifications: r.strategy.clarifications || []
|
||||
}))
|
||||
```
|
||||
|
||||
### Step 4.4: Apply Modifications
|
||||
|
||||
```javascript
|
||||
// 1. Extract modifications from resolved strategies
|
||||
const modifications = [];
|
||||
selectedStrategies.forEach(item => {
|
||||
if (item.strategy && item.strategy.modifications) {
|
||||
modifications.push(...item.strategy.modifications.map(mod => ({
|
||||
...mod,
|
||||
conflict_id: item.conflict_id,
|
||||
clarifications: item.clarifications
|
||||
})));
|
||||
}
|
||||
});
|
||||
|
||||
console.log(`Applying ${modifications.length} modifications...`);
|
||||
|
||||
// 2. Apply each modification using Edit tool (with fallback to context-package.json)
|
||||
const appliedModifications = [];
|
||||
const failedModifications = [];
|
||||
const fallbackConstraints = []; // For files that don't exist
|
||||
|
||||
modifications.forEach((mod, idx) => {
|
||||
try {
|
||||
console.log(`[${idx + 1}/${modifications.length}] Modifying ${mod.file}...`);
|
||||
|
||||
// Check if target file exists (brainstorm files may not exist in lite workflow)
|
||||
if (!file_exists(mod.file)) {
|
||||
console.log(` File not found, writing to context-package.json as constraint`);
|
||||
fallbackConstraints.push({
|
||||
source: "conflict-resolution",
|
||||
conflict_id: mod.conflict_id,
|
||||
target_file: mod.file,
|
||||
section: mod.section,
|
||||
change_type: mod.change_type,
|
||||
content: mod.new_content,
|
||||
rationale: mod.rationale
|
||||
});
|
||||
return; // Skip to next modification
|
||||
}
|
||||
|
||||
if (mod.change_type === "update") {
|
||||
Edit({ file_path: mod.file, old_string: mod.old_content, new_string: mod.new_content });
|
||||
} else if (mod.change_type === "add") {
|
||||
const fileContent = Read(mod.file);
|
||||
const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content);
|
||||
Write(mod.file, updated);
|
||||
} else if (mod.change_type === "remove") {
|
||||
Edit({ file_path: mod.file, old_string: mod.old_content, new_string: "" });
|
||||
}
|
||||
|
||||
appliedModifications.push(mod);
|
||||
console.log(` Success`);
|
||||
} catch (error) {
|
||||
console.log(` Failed: ${error.message}`);
|
||||
failedModifications.push({ ...mod, error: error.message });
|
||||
}
|
||||
});
|
||||
|
||||
// 3. Generate conflict-resolution.json output file
|
||||
const resolutionOutput = {
|
||||
session_id: sessionId,
|
||||
resolved_at: new Date().toISOString(),
|
||||
summary: {
|
||||
total_conflicts: conflicts.length,
|
||||
resolved_with_strategy: selectedStrategies.length,
|
||||
custom_handling: customConflicts.length,
|
||||
fallback_constraints: fallbackConstraints.length
|
||||
},
|
||||
resolved_conflicts: selectedStrategies.map(s => ({
|
||||
conflict_id: s.conflict_id,
|
||||
strategy_name: s.strategy.name,
|
||||
strategy_approach: s.strategy.approach,
|
||||
clarifications: s.clarifications || [],
|
||||
modifications_applied: s.strategy.modifications?.filter(m =>
|
||||
appliedModifications.some(am => am.conflict_id === s.conflict_id)
|
||||
) || []
|
||||
})),
|
||||
custom_conflicts: customConflicts.map(c => ({
|
||||
id: c.id, brief: c.brief, category: c.category,
|
||||
suggestions: c.suggestions, overlap_analysis: c.overlap_analysis || null
|
||||
})),
|
||||
planning_constraints: fallbackConstraints,
|
||||
failed_modifications: failedModifications
|
||||
};
|
||||
|
||||
const resolutionPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
|
||||
Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2));
|
||||
|
||||
// 4. Update context-package.json with resolution details
|
||||
const contextPkg = JSON.parse(Read(contextPath));
|
||||
contextPkg.conflict_detection.conflict_risk = "resolved";
|
||||
contextPkg.conflict_detection.resolution_file = resolutionPath;
|
||||
contextPkg.conflict_detection.resolved_conflicts = selectedStrategies.map(s => s.conflict_id);
|
||||
contextPkg.conflict_detection.custom_conflicts = customConflicts.map(c => c.id);
|
||||
contextPkg.conflict_detection.resolved_at = new Date().toISOString();
|
||||
Write(contextPath, JSON.stringify(contextPkg, null, 2));
|
||||
|
||||
// 5. Output custom conflict summary with overlap analysis (if any)
|
||||
if (customConflicts.length > 0) {
|
||||
customConflicts.forEach(conflict => {
|
||||
console.log(`[${conflict.category}] ${conflict.id}: ${conflict.brief}`);
|
||||
if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) {
|
||||
console.log(`Overlap info: New module: ${conflict.overlap_analysis.new_module.name}`);
|
||||
}
|
||||
conflict.suggestions.forEach(s => console.log(` - ${s}`));
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### TodoWrite Update (Phase 4 in progress - tasks attached, if conflict_risk >= medium)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 4: Conflict Resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
|
||||
{"content": " -> Detect conflicts with CLI analysis", "status": "in_progress", "activeForm": "Detecting conflicts"},
|
||||
{"content": " -> Present conflicts to user", "status": "pending", "activeForm": "Presenting conflicts"},
|
||||
{"content": " -> Apply resolution strategies", "status": "pending", "activeForm": "Applying resolution strategies"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
### TodoWrite Update (Phase 4 completed - tasks collapsed)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 4: Conflict Resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
### Step 4.5: Update Planning Notes
|
||||
|
||||
After conflict resolution completes (if executed), update planning-notes.md:
|
||||
|
||||
```javascript
|
||||
if (conflictRisk === 'medium' || conflictRisk === 'high') {
|
||||
const conflictResPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
|
||||
|
||||
if (file_exists(conflictResPath)) {
|
||||
const conflictRes = JSON.parse(Read(conflictResPath));
|
||||
const resolved = conflictRes.resolved_conflicts || [];
|
||||
const modifiedArtifacts = conflictRes.modified_artifacts || [];
|
||||
const planningConstraints = conflictRes.planning_constraints || [];
|
||||
|
||||
// Update Phase 4 section
|
||||
Edit(planningNotesPath, {
|
||||
old: '## Conflict Decisions (Phase 4)\n(To be filled if conflicts detected)',
|
||||
new: `## Conflict Decisions (Phase 4)
|
||||
|
||||
- **RESOLVED**: ${resolved.map(r => `${r.type} -> ${r.strategy}`).join('; ') || 'None'}
|
||||
- **MODIFIED_ARTIFACTS**: ${modifiedArtifacts.join(', ') || 'None'}
|
||||
- **CONSTRAINTS**: ${planningConstraints.join('; ') || 'None'}`
|
||||
})
|
||||
|
||||
// Append Phase 4 constraints to consolidated list
|
||||
if (planningConstraints.length > 0) {
|
||||
const currentNotes = Read(planningNotesPath);
|
||||
const constraintCount = (currentNotes.match(/^\d+\./gm) || []).length;
|
||||
|
||||
Edit(planningNotesPath, {
|
||||
old: '## Consolidated Constraints (Phase 5 Input)',
|
||||
new: `## Consolidated Constraints (Phase 5 Input)
|
||||
${planningConstraints.map((c, i) => `${constraintCount + i + 1}. [Conflict] ${c}`).join('\n')}`
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Auto-Continue**: Return to user showing conflict resolution results and selected strategies, then auto-continue.
|
||||
|
||||
**Auto Mode**: When `workflowPreferences.autoYes` is true, conflict-resolution automatically applies recommended resolution strategies without user confirmation.
|
||||
|
||||
### Step 4.6: Memory State Check
|
||||
|
||||
Evaluate current context window usage and memory state:
|
||||
|
||||
- If memory usage is high (>110K tokens or approaching context limits):
|
||||
|
||||
```javascript
|
||||
Skill(skill="memory-capture")
|
||||
```
|
||||
|
||||
- Memory compaction is particularly important after analysis phase which may generate extensive documentation
|
||||
- Ensures optimal performance and prevents context overflow
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `conflict-resolution.json` (if conflicts resolved)
|
||||
- **TodoWrite**: Mark Phase 4 completed, Phase 5 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 5: TDD Task Generation](05-tdd-task-generation.md).
|
||||
@@ -0,0 +1,472 @@
|
||||
# Phase 5: TDD Task Generation
|
||||
|
||||
> **📌 COMPACT SENTINEL [Phase 5: TDD-Task-Generation]**
|
||||
> This phase contains 3 execution steps (Step 5.1 — 5.3).
|
||||
> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
|
||||
> Recovery: `Read("phases/05-tdd-task-generation.md")`
|
||||
|
||||
Generate TDD tasks with Red-Green-Refactor cycles via action-planning-agent.
|
||||
|
||||
## Objective
|
||||
|
||||
- Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md with TDD structure
|
||||
- Each task contains internal Red-Green-Refactor cycle
|
||||
- Include Phase 0 user configuration (execution method, CLI tool preference)
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
|
||||
- **Two-Phase Flow**: Discovery (context gathering) -> Output (document generation)
|
||||
- **Memory-First**: Reuse loaded documents from conversation memory
|
||||
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
|
||||
- **Semantic CLI Selection**: CLI tool usage determined from user's task description, not flags
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths or clear relative paths from project root
|
||||
- **TDD-First**: Every feature starts with a failing test (Red phase)
|
||||
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
|
||||
- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations
|
||||
|
||||
## Task Strategy
|
||||
|
||||
### Optimized Task Structure
|
||||
- **1 feature = 1 task** containing complete TDD cycle internally
|
||||
- Each task executes Red-Green-Refactor phases sequentially
|
||||
- Task count = Feature count (typically 5 features = 5 tasks)
|
||||
|
||||
### When to Use Subtasks
|
||||
- Feature complexity >2500 lines or >6 files per TDD cycle
|
||||
- Multiple independent sub-features needing parallel execution
|
||||
- Strong technical dependency blocking (e.g., API before UI)
|
||||
- Different tech stacks or domains within feature
|
||||
|
||||
### Task Limits
|
||||
- **Maximum 18 tasks** (hard limit for TDD workflows)
|
||||
- **Feature-based**: Complete functional units with internal TDD cycles
|
||||
- **Hierarchy**: Flat (<=5 simple features) | Two-level (6-10 for complex features with sub-features)
|
||||
- **Re-scope**: If >18 tasks needed, break project into multiple TDD workflow sessions
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 0: User Configuration (Interactive)
|
||||
|
||||
**Purpose**: Collect user preferences before TDD task generation.
|
||||
|
||||
```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") {
|
||||
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: [...],
|
||||
},
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true // Always enable resume for CLI executions
|
||||
}
|
||||
```
|
||||
|
||||
**Auto Mode**: When `workflowPreferences.autoYes` is true, skip user questions, use defaults (no materials, Agent executor).
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Context Preparation & Discovery
|
||||
|
||||
**Memory-First Rule**: Skip file loading if documents already in conversation memory
|
||||
|
||||
**Progressive Loading Strategy**: Load context incrementally:
|
||||
- **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
|
||||
|
||||
**Session Path Structure** (provided 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
|
||||
│ └── ...
|
||||
├── plan.json # Output: Structured plan overview (TDD variant)
|
||||
├── IMPL_PLAN.md # Output: TDD implementation plan
|
||||
└── TODO_LIST.md # Output: TODO list with TDD phases
|
||||
```
|
||||
|
||||
**Discovery Actions**:
|
||||
|
||||
1. **Load Session Context** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("workflow-session.json")) {
|
||||
Read(`.workflow/active/${sessionId}/workflow-session.json`)
|
||||
}
|
||||
```
|
||||
|
||||
2. **Load Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("context-package.json")) {
|
||||
Read(`.workflow/active/${sessionId}/.process/context-package.json`)
|
||||
}
|
||||
```
|
||||
|
||||
3. **Load Test Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("test-context-package.json")) {
|
||||
Read(`.workflow/active/${sessionId}/.process/test-context-package.json`)
|
||||
}
|
||||
```
|
||||
|
||||
4. **Extract & Load Role Analyses** (from context-package.json)
|
||||
```javascript
|
||||
const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files.map(f => f.path));
|
||||
roleAnalysisPaths.forEach(path => Read(path));
|
||||
```
|
||||
|
||||
5. **Load Conflict Resolution** (if exists)
|
||||
```javascript
|
||||
if (contextPackage.conflict_detection?.resolution_file) {
|
||||
Read(contextPackage.conflict_detection.resolution_file)
|
||||
} else if (contextPackage.brainstorm_artifacts?.conflict_resolution?.exists) {
|
||||
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
|
||||
}
|
||||
```
|
||||
|
||||
6. **Code Analysis with Native Tools** (optional)
|
||||
```bash
|
||||
find . -name "*test*" -type f
|
||||
rg "describe|it\(|test\(" -g "*.ts"
|
||||
```
|
||||
|
||||
7. **MCP External Research** (optional)
|
||||
```javascript
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript TDD best practices Red-Green-Refactor",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5.1: Execute TDD Task Generation (Agent Invocation)
|
||||
|
||||
**Design Note**: The agent specification (action-planning-agent.md) already defines schemas, CLI execution strategies, quantification standards, and loading algorithms. This prompt provides **instance-specific parameters** and **TDD-specific requirements** only.
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session ${sessionId}
|
||||
|
||||
## SESSION PATHS
|
||||
Session Root: .workflow/active/${sessionId}/
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/${sessionId}/workflow-session.json
|
||||
- Context Package: .workflow/active/${sessionId}/.process/context-package.json
|
||||
- Test Context: .workflow/active/${sessionId}/.process/test-context-package.json
|
||||
|
||||
Output:
|
||||
- Task Dir: .workflow/active/${sessionId}/.task/
|
||||
- IMPL_PLAN: .workflow/active/${sessionId}/IMPL_PLAN.md
|
||||
- TODO_LIST: .workflow/active/${sessionId}/TODO_LIST.md
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: ${sessionId}
|
||||
Workflow Type: TDD
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## PROJECT CONTEXT (MANDATORY - load before planning-notes)
|
||||
These files provide project-level constraints that apply to ALL tasks:
|
||||
|
||||
1. **ccw spec load --category execution** (project specs and tech analysis)
|
||||
- Contains: tech_stack, architecture_type, key_components, build_system, test_framework, coding_conventions, naming_rules, forbidden_patterns, quality_gates, custom_constraints
|
||||
- Usage: Populate plan.json shared_context, align task tech choices, set correct test commands
|
||||
- Apply as HARD CONSTRAINTS on all generated tasks — task implementation steps,
|
||||
acceptance criteria, and convergence.verification MUST respect these guidelines
|
||||
- If empty/missing: No additional constraints (proceed normally)
|
||||
|
||||
Loading order: \`ccw spec load --category execution\` → planning-notes.md → context-package.json
|
||||
|
||||
## 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}
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
|
||||
If prioritized_context is incomplete, fall back to exploration_results:
|
||||
- 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
|
||||
|
||||
## 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
|
||||
|
||||
### TDD-Specific Requirements Summary
|
||||
|
||||
#### Task Structure Philosophy
|
||||
- **1 feature = 1 task** containing complete TDD cycle internally
|
||||
- Each task executes Red-Green-Refactor phases sequentially
|
||||
- Task count = Feature count (typically 5 features = 5 tasks)
|
||||
- Subtasks only when complexity >2500 lines or >6 files per cycle
|
||||
- **Maximum 18 tasks** (hard limit for TDD workflows)
|
||||
|
||||
#### TDD Cycle Mapping
|
||||
- **Simple features**: IMPL-N with internal Red-Green-Refactor phases
|
||||
- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks)
|
||||
- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage
|
||||
|
||||
#### Required Outputs Summary
|
||||
|
||||
##### 1. TDD Task JSON Files (.task/IMPL-*.json)
|
||||
- **Location**: .workflow/active/${sessionId}/.task/
|
||||
- **Schema**: Unified flat schema (task-schema.json) with TDD-specific metadata
|
||||
- meta.tdd_workflow: true (REQUIRED)
|
||||
- meta.max_iterations: 3 (Green phase test-fix cycle limit)
|
||||
- tdd_cycles: Array with quantified test cases and coverage
|
||||
- focus_paths: Absolute or clear relative paths (enhanced with exploration critical_files)
|
||||
- implementation: 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
|
||||
- pre_analysis: Include exploration integration_points analysis
|
||||
|
||||
##### 2. IMPL_PLAN.md (TDD Variant)
|
||||
- **Location**: .workflow/active/${sessionId}/IMPL_PLAN.md
|
||||
- **Template**: ~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt
|
||||
- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
|
||||
|
||||
##### 3. TODO_LIST.md
|
||||
- **Location**: .workflow/active/${sessionId}/TODO_LIST.md
|
||||
- **Format**: Hierarchical task list with internal TDD phase indicators (Red -> Green -> Refactor)
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- All planning documents generated successfully:
|
||||
- Task JSONs valid and saved to .task/ directory
|
||||
- IMPL_PLAN.md created with complete TDD structure
|
||||
- TODO_LIST.md generated matching task JSONs
|
||||
- Return completion status with document count and task breakdown summary
|
||||
|
||||
## SESSION-SPECIFIC NOTES
|
||||
- Workflow Type: TDD — tasks use Red-Green-Refactor phases
|
||||
- Deliverables: Task JSONs + IMPL_PLAN.md + plan.json + TODO_LIST.md (all 4 required)
|
||||
- focus_paths: Derive from exploration critical_files and test context
|
||||
- All other schemas, CLI execution strategies, quantification standards: Follow agent specification
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
**CLI Tool Selection**: CLI tool usage is determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
|
||||
|
||||
### Step 5.2: Parse Output
|
||||
|
||||
Extract: feature count, task count, CLI execution IDs assigned
|
||||
|
||||
### Step 5.3: Validate Outputs
|
||||
|
||||
- `plan.json` exists (structured plan overview with `_metadata.plan_type: "tdd"`)
|
||||
- `IMPL_PLAN.md` exists (unified plan with TDD Implementation Tasks section)
|
||||
- `IMPL-*.json` files exist (one per feature, or container + subtasks for complex features)
|
||||
- `TODO_LIST.md` exists with internal TDD phase indicators
|
||||
- Each IMPL task includes:
|
||||
- `meta.tdd_workflow: true`
|
||||
- `cli_execution.id: {session_id}-{task_id}`
|
||||
- `cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
|
||||
- `implementation` with exactly 3 steps (red/green/refactor)
|
||||
- Green phase includes test-fix-cycle configuration
|
||||
- `focus_paths`: absolute or clear relative paths (enhanced with exploration critical_files)
|
||||
- `pre_analysis`: includes exploration integration_points analysis
|
||||
- `IMPL_PLAN.md` contains `workflow_type: "tdd"` in frontmatter
|
||||
- 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 >18: `WARNING: Task count exceeds hard limit - request re-scope`
|
||||
- Missing cli_execution.id: `WARNING: Task lacks CLI execution ID for resume support`
|
||||
- Missing test-fix-cycle: `WARNING: Green phase lacks auto-revert configuration`
|
||||
- Generic task names: `WARNING: Vague task names suggest unclear TDD cycles`
|
||||
- Missing focus_paths: `WARNING: Task lacks clear file scope for implementation`
|
||||
|
||||
**Action**: Log warnings to `.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking)
|
||||
|
||||
### TodoWrite Update (Phase 5 Skill executed - tasks attached)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
|
||||
{"content": " -> Discovery - analyze TDD requirements", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
|
||||
{"content": " -> Planning - design Red-Green-Refactor cycles", "status": "pending", "activeForm": "Designing TDD cycles"},
|
||||
{"content": " -> Output - generate IMPL tasks with internal TDD phases", "status": "pending", "activeForm": "Generating TDD tasks"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Agent execution **attaches** task-generate-tdd's 3 tasks. Orchestrator **executes** these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.
|
||||
|
||||
**Next Action**: Tasks attached -> **Execute Phase 5.1-5.3** sequentially
|
||||
|
||||
### TodoWrite Update (Phase 5 completed - tasks collapsed)
|
||||
|
||||
```json
|
||||
[
|
||||
{"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
|
||||
{"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
|
||||
{"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
|
||||
{"content": "Phase 5: TDD Task Generation", "status": "completed", "activeForm": "Executing TDD task generation"},
|
||||
{"content": "Phase 6: TDD Structure Validation", "status": "in_progress", "activeForm": "Validating TDD structure"}
|
||||
]
|
||||
```
|
||||
|
||||
**Note**: Phase 5 tasks completed and collapsed to summary. Each generated IMPL task contains complete Red-Green-Refactor cycle internally.
|
||||
|
||||
## TDD Task Structure Reference
|
||||
|
||||
**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`
|
||||
- `cli_execution.id: "{session_id}-{task_id}"`
|
||||
- `cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
|
||||
- `tdd_cycles` array with quantified test cases and coverage:
|
||||
```javascript
|
||||
tdd_cycles: [
|
||||
{
|
||||
test_count: 5,
|
||||
test_cases: ["case1", "case2"],
|
||||
implementation_scope: "...",
|
||||
expected_coverage: ">=85%"
|
||||
}
|
||||
]
|
||||
```
|
||||
- `focus_paths` use absolute or clear relative paths
|
||||
- `implementation`: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor")
|
||||
- `pre_analysis`: includes exploration integration_points analysis
|
||||
- **meta.execution_config**: Set per `userConfig.executionMethod` (agent/cli/hybrid)
|
||||
|
||||
## Output Files Structure
|
||||
|
||||
```
|
||||
.workflow/active/{session-id}/
|
||||
├── plan.json # Structured plan overview (TDD variant)
|
||||
├── IMPL_PLAN.md # Unified plan with TDD Implementation Tasks section
|
||||
├── TODO_LIST.md # Progress tracking with internal TDD phase indicators
|
||||
├── .task/
|
||||
│ ├── IMPL-1.json # Complete TDD task (Red-Green-Refactor internally)
|
||||
│ ├── IMPL-2.json # Complete TDD task
|
||||
│ ├── IMPL-3.json # Complex feature container (if needed)
|
||||
│ ├── IMPL-3.1.json # Complex feature subtask (if needed)
|
||||
│ ├── IMPL-3.2.json # Complex feature subtask (if needed)
|
||||
│ └── ...
|
||||
└── .process/
|
||||
├── conflict-resolution.json # Conflict resolution results (if conflict_risk >= medium)
|
||||
├── test-context-package.json # Test coverage analysis
|
||||
├── context-package.json # Input from context-gather
|
||||
└── tdd-warnings.log # Non-blocking warnings
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Task Completeness
|
||||
- Every IMPL-N must contain complete TDD workflow in `implementation`
|
||||
- Each task must have 3 steps with `tdd_phase`: "red", "green", "refactor"
|
||||
- Every task must have `meta.tdd_workflow: true`
|
||||
|
||||
### Dependency Enforcement
|
||||
- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
|
||||
- Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies
|
||||
- No circular dependencies allowed
|
||||
|
||||
### Task Limits
|
||||
- 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
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `plan.json` (structured plan overview)
|
||||
- **File**: `IMPL_PLAN.md` (unified plan with TDD Implementation Tasks section)
|
||||
- **File**: `IMPL-*.json` (task JSONs with internal TDD cycles)
|
||||
- **File**: `TODO_LIST.md` (task list with TDD phase indicators)
|
||||
- **File**: `.process/tdd-warnings.log` (non-blocking warnings)
|
||||
- **TodoWrite**: Mark Phase 5 completed, Phase 6 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase 6: TDD Structure Validation](06-tdd-structure-validation.md).
|
||||
@@ -0,0 +1,189 @@
|
||||
# Phase 6: TDD Structure Validation & Plan Confirmation
|
||||
|
||||
> **📌 COMPACT SENTINEL [Phase 6: TDD-Structure-Validation]**
|
||||
> This phase contains 4 execution steps (Step 6.1 — 6.4).
|
||||
> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
|
||||
> Recovery: `Read("phases/06-tdd-structure-validation.md")`
|
||||
|
||||
Internal validation of TDD task structure and user decision gate for next steps.
|
||||
|
||||
## Objective
|
||||
|
||||
- Validate Red-Green-Refactor structure in all generated tasks
|
||||
- Verify TDD compliance checkpoints
|
||||
- Gather evidence before claiming completion
|
||||
- Present Plan Confirmation Gate to user
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 6.1: Internal Validation
|
||||
|
||||
Validate each generated task contains complete TDD workflow:
|
||||
|
||||
1. **Task structure validation**:
|
||||
- `meta.tdd_workflow: true` in all IMPL tasks
|
||||
- `cli_execution.id` present (format: {session_id}-{task_id})
|
||||
- `cli_execution` strategy assigned (new/resume/fork/merge_fork)
|
||||
- `implementation` has exactly 3 steps
|
||||
- Each step has correct `tdd_phase`: "red", "green", "refactor"
|
||||
- `focus_paths` are absolute or clear relative paths
|
||||
- `pre_analysis` includes exploration integration analysis
|
||||
|
||||
2. **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
|
||||
|
||||
3. **Agent assignment**: All IMPL tasks use @code-developer
|
||||
|
||||
4. **Test-fix cycle**: Green phase step includes test-fix-cycle logic with max_iterations
|
||||
|
||||
5. **Task count**: Total tasks ≤18 (simple + subtasks hard limit)
|
||||
|
||||
6. **User configuration**:
|
||||
- Execution method choice reflected in task structure
|
||||
- CLI tool preference documented in implementation guidance (if CLI selected)
|
||||
|
||||
### Step 6.2: Red Flag Checklist
|
||||
|
||||
From TDD best practices:
|
||||
- [ ] No tasks skip Red phase (`tdd_phase: "red"` exists in step 1)
|
||||
- [ ] Test files referenced in Red phase (explicit paths, not placeholders)
|
||||
- [ ] Green phase has test-fix-cycle with `max_iterations` configured
|
||||
- [ ] Refactor phase has clear completion criteria
|
||||
|
||||
**Non-Compliance Warning Format**:
|
||||
```
|
||||
⚠️ TDD Red Flag: [issue description]
|
||||
Task: [IMPL-N]
|
||||
Recommendation: [action to fix]
|
||||
```
|
||||
|
||||
### Step 6.3: Evidence Gathering
|
||||
|
||||
Before claiming completion, verify artifacts exist:
|
||||
|
||||
```bash
|
||||
# Verify session artifacts exist
|
||||
ls -la .workflow/active/[sessionId]/{IMPL_PLAN.md,TODO_LIST.md}
|
||||
ls -la .workflow/active/[sessionId]/.task/IMPL-*.json
|
||||
|
||||
# Count generated artifacts
|
||||
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, cli_id: .cli_execution.id, phases: [.implementation[].tdd_phase]}' \
|
||||
"$(ls .workflow/active/[sessionId]/.task/IMPL-*.json | head -1)"
|
||||
```
|
||||
|
||||
**Evidence Required Before Summary**:
|
||||
|
||||
| Evidence Type | Verification Method | Pass Criteria |
|
||||
|---------------|---------------------|---------------|
|
||||
| File existence | `ls -la` artifacts | All files present |
|
||||
| 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) |
|
||||
|
||||
### Step 6.4: Plan Confirmation Gate
|
||||
|
||||
Present user with action choices:
|
||||
|
||||
```javascript
|
||||
console.log(`
|
||||
TDD Planning complete for session: ${sessionId}
|
||||
|
||||
Features analyzed: [N]
|
||||
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 18-task hard limit)
|
||||
|
||||
Structure:
|
||||
- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
|
||||
- IMPL-2: {Feature 2 Name} (Internal: Red → Green → Refactor)
|
||||
- IMPL-3: {Complex Feature} (Container)
|
||||
- IMPL-3.1: {Sub-feature A} (Internal: Red → Green → Refactor)
|
||||
- IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor)
|
||||
[...]
|
||||
|
||||
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 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.
|
||||
`);
|
||||
|
||||
// Ask user for next action
|
||||
const userChoice = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "TDD Planning complete. What would you like to do next?",
|
||||
header: "Next Action",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Verify TDD Compliance (Recommended)",
|
||||
description: "Run full TDD compliance verification to check task chain structure, coverage, and Red-Green-Refactor cycle quality."
|
||||
},
|
||||
{
|
||||
label: "Start Execution",
|
||||
description: "Begin implementing TDD tasks immediately with Red-Green-Refactor cycles."
|
||||
},
|
||||
{
|
||||
label: "Review Status Only",
|
||||
description: "View TDD task breakdown and session status without taking further action."
|
||||
}
|
||||
]
|
||||
}]
|
||||
});
|
||||
|
||||
// Execute based on user choice
|
||||
if (userChoice === "Verify TDD Compliance (Recommended)") {
|
||||
// Route to Phase 7 (tdd-verify) within this skill
|
||||
// Orchestrator reads phases/07-tdd-verify.md and executes
|
||||
} else if (userChoice === "Start Execution") {
|
||||
Skill(skill="workflow-execute", args="--session " + sessionId);
|
||||
} else if (userChoice === "Review Status Only") {
|
||||
// Display session status inline
|
||||
const sessionMeta = JSON.parse(Read(`.workflow/active/${sessionId}/workflow-session.json`));
|
||||
const todoList = Read(`.workflow/active/${sessionId}/TODO_LIST.md`);
|
||||
console.log(`\nSession: ${sessionId}`);
|
||||
console.log(`Status: ${sessionMeta.status}`);
|
||||
console.log(`\n--- TODO List ---\n${todoList}`);
|
||||
}
|
||||
```
|
||||
|
||||
**Auto Mode**: When `workflowPreferences.autoYes` is true, auto-select "Verify TDD Compliance", then auto-continue to execute if quality gate is APPROVED.
|
||||
|
||||
## Output
|
||||
|
||||
- **Validation**: TDD structure verified
|
||||
- **User Decision**: Route to Phase 7 / Execute / Review
|
||||
- **TodoWrite**: Mark Phase 6 completed
|
||||
|
||||
## Next Phase (Conditional)
|
||||
|
||||
Based on user's plan confirmation choice:
|
||||
- If "Verify" → [Phase 7: TDD Verification](07-tdd-verify.md)
|
||||
- If "Execute" → Skill(skill="workflow-execute")
|
||||
- If "Review" -> Display session status inline
|
||||
635
.claude/skills/workflow-tdd-plan/phases/07-tdd-verify.md
Normal file
635
.claude/skills/workflow-tdd-plan/phases/07-tdd-verify.md
Normal file
@@ -0,0 +1,635 @@
|
||||
# Phase 7: TDD Verification
|
||||
|
||||
Full TDD compliance verification with quality gate reporting. Generates comprehensive TDD_COMPLIANCE_REPORT.md.
|
||||
|
||||
## Objective
|
||||
|
||||
- Verify TDD task chain structure (TEST → IMPL → REFACTOR or internal Red-Green-Refactor)
|
||||
- Analyze test coverage metrics
|
||||
- Validate TDD cycle execution quality
|
||||
- Generate compliance report with quality gate recommendation
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
**ORCHESTRATOR MODE**:
|
||||
- This phase coordinates sub-steps and inline TDD coverage analysis
|
||||
- MAY write output files: TDD_COMPLIANCE_REPORT.md (primary report), .process/*.json (intermediate artifacts)
|
||||
- MUST NOT modify source task files or implementation code
|
||||
- MUST NOT create or delete tasks in the workflow
|
||||
|
||||
**Quality Gate Authority**: The compliance report provides a binding recommendation (BLOCK_MERGE / REQUIRE_FIXES / PROCEED_WITH_CAVEATS / APPROVED) based on objective compliance criteria.
|
||||
|
||||
## 4-Step Execution
|
||||
|
||||
### Step 7.1: Session Discovery & Validation
|
||||
|
||||
```bash
|
||||
IF --session parameter provided:
|
||||
session_id = provided session
|
||||
ELSE:
|
||||
# Auto-detect active session
|
||||
active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
|
||||
IF active_sessions is empty:
|
||||
ERROR: "No active workflow session found. Use --session <session-id>"
|
||||
EXIT
|
||||
ELSE IF active_sessions has multiple entries:
|
||||
# Use most recently modified session
|
||||
session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
|
||||
ELSE:
|
||||
session_id = basename(active_sessions[0])
|
||||
|
||||
# Derive paths
|
||||
session_dir = .workflow/active/WFS-{session_id}
|
||||
task_dir = session_dir/.task
|
||||
summaries_dir = session_dir/.summaries
|
||||
process_dir = session_dir/.process
|
||||
```
|
||||
|
||||
**Validate Required Artifacts**:
|
||||
```bash
|
||||
# Check task files exist
|
||||
task_files = Glob(task_dir/*.json)
|
||||
IF task_files.count == 0:
|
||||
ERROR: "No task JSON files found. Run /workflow-tdd-plan first"
|
||||
EXIT
|
||||
|
||||
# Check summaries exist (optional but recommended for full analysis)
|
||||
summaries_exist = EXISTS(summaries_dir)
|
||||
IF NOT summaries_exist:
|
||||
WARNING: "No .summaries/ directory found. Some analysis may be limited."
|
||||
```
|
||||
|
||||
**Output**: session_id, session_dir, task_files list
|
||||
|
||||
---
|
||||
|
||||
### Step 7.2: Task Chain Structure Validation
|
||||
|
||||
**Load and Parse Task JSONs**:
|
||||
```bash
|
||||
# Single-pass JSON extraction using jq
|
||||
cd '{session_dir}/.task'
|
||||
|
||||
# Extract all task IDs
|
||||
task_ids=$(jq -r '.id' *.json 2>/dev/null | sort)
|
||||
|
||||
# Extract dependencies for IMPL tasks
|
||||
impl_deps=$(jq -r 'select(.id | startswith("IMPL")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null)
|
||||
|
||||
# Extract dependencies for REFACTOR tasks
|
||||
refactor_deps=$(jq -r 'select(.id | startswith("REFACTOR")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null)
|
||||
|
||||
# Extract meta fields
|
||||
meta_tdd=$(jq -r '.id + ":" + (.meta.tdd_phase // "missing")' *.json 2>/dev/null)
|
||||
meta_agent=$(jq -r '.id + ":" + (.meta.agent // "missing")' *.json 2>/dev/null)
|
||||
|
||||
# Output as JSON
|
||||
jq -n --arg ids "$task_ids" \
|
||||
--arg impl "$impl_deps" \
|
||||
--arg refactor "$refactor_deps" \
|
||||
--arg tdd "$meta_tdd" \
|
||||
--arg agent "$meta_agent" \
|
||||
'{ids: $ids, impl_deps: $impl, refactor_deps: $refactor, tdd: $tdd, agent: $agent}'
|
||||
```
|
||||
|
||||
**Validate TDD Chain Structure**:
|
||||
```
|
||||
Parse validation_data JSON and validate:
|
||||
|
||||
For each feature N (extracted from task IDs):
|
||||
1. TEST-N.M exists?
|
||||
2. IMPL-N.M exists?
|
||||
3. REFACTOR-N.M exists? (optional but recommended)
|
||||
4. IMPL-N.M.context.depends_on contains TEST-N.M?
|
||||
5. REFACTOR-N.M.context.depends_on contains IMPL-N.M?
|
||||
6. TEST-N.M.meta.tdd_phase == "red"?
|
||||
7. TEST-N.M.meta.agent == "@code-review-test-agent"?
|
||||
8. IMPL-N.M.meta.tdd_phase == "green"?
|
||||
9. IMPL-N.M.meta.agent == "@code-developer"?
|
||||
10. REFACTOR-N.M.meta.tdd_phase == "refactor"?
|
||||
|
||||
Calculate:
|
||||
- chain_completeness_score = (complete_chains / total_chains) * 100
|
||||
- dependency_accuracy = (correct_deps / total_deps) * 100
|
||||
- meta_field_accuracy = (correct_meta / total_meta) * 100
|
||||
```
|
||||
|
||||
**Output**: chain_validation_report (JSON structure with validation results)
|
||||
|
||||
---
|
||||
|
||||
### Step 7.3: Coverage & Cycle Analysis
|
||||
|
||||
**Execute TDD Coverage Analysis**:
|
||||
|
||||
#### Phase 3a: Extract Test Tasks
|
||||
|
||||
```bash
|
||||
# Find TEST task files and extract focus_paths
|
||||
find .workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
|
||||
```
|
||||
|
||||
**Output**: List of test directories/files from all TEST tasks
|
||||
|
||||
#### Phase 3b: Run Test Suite
|
||||
|
||||
```bash
|
||||
# Auto-detect test framework from project
|
||||
if [ -f "package.json" ] && grep -q "jest\|mocha\|vitest" package.json; then
|
||||
TEST_CMD="npm test -- --coverage --json"
|
||||
elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
|
||||
TEST_CMD="pytest --cov --json-report"
|
||||
elif [ -f "Cargo.toml" ]; then
|
||||
TEST_CMD="cargo test -- --test-threads=1 --nocapture"
|
||||
elif [ -f "go.mod" ]; then
|
||||
TEST_CMD="go test -coverprofile=coverage.out -json ./..."
|
||||
else
|
||||
TEST_CMD="echo 'No supported test framework found'"
|
||||
fi
|
||||
|
||||
# Execute test suite with coverage
|
||||
$TEST_CMD > .workflow/active/{session_id}/.process/test-results.json
|
||||
```
|
||||
|
||||
**Output**: test-results.json with coverage data
|
||||
|
||||
#### Phase 3c: Parse Coverage Data
|
||||
|
||||
```bash
|
||||
jq '.coverage' .workflow/active/{session_id}/.process/test-results.json > .workflow/active/{session_id}/.process/coverage-report.json
|
||||
```
|
||||
|
||||
**Extract**:
|
||||
- Line coverage percentage
|
||||
- Branch coverage percentage
|
||||
- Function coverage percentage
|
||||
- Uncovered lines/branches
|
||||
|
||||
#### Phase 3d: Verify TDD Cycle
|
||||
|
||||
For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M):
|
||||
|
||||
**1. Red Phase Verification**
|
||||
```bash
|
||||
cat .workflow/active/{session_id}/.summaries/TEST-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Tests were created
|
||||
- Tests failed initially
|
||||
- Failure messages were clear
|
||||
|
||||
**2. Green Phase Verification**
|
||||
```bash
|
||||
cat .workflow/active/{session_id}/.summaries/IMPL-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Implementation was completed
|
||||
- Tests now pass
|
||||
- Implementation was minimal
|
||||
|
||||
**3. Refactor Phase Verification**
|
||||
```bash
|
||||
cat .workflow/active/{session_id}/.summaries/REFACTOR-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Refactoring was completed
|
||||
- Tests still pass
|
||||
- Code quality improved
|
||||
|
||||
#### TDD Cycle Verification Algorithm
|
||||
|
||||
```
|
||||
For each feature N:
|
||||
1. Load TEST-N.M-summary.md
|
||||
IF summary missing:
|
||||
Mark: "Red phase incomplete"
|
||||
SKIP to next feature
|
||||
|
||||
CHECK: Contains "test" AND "fail"
|
||||
IF NOT found:
|
||||
Mark: "Red phase verification failed"
|
||||
ELSE:
|
||||
Mark: "Red phase [PASS]"
|
||||
|
||||
2. Load IMPL-N.M-summary.md
|
||||
IF summary missing:
|
||||
Mark: "Green phase incomplete"
|
||||
SKIP to next feature
|
||||
|
||||
CHECK: Contains "pass" OR "green"
|
||||
IF NOT found:
|
||||
Mark: "Green phase verification failed"
|
||||
ELSE:
|
||||
Mark: "Green phase [PASS]"
|
||||
|
||||
3. Load REFACTOR-N.M-summary.md
|
||||
IF summary missing:
|
||||
Mark: "Refactor phase incomplete"
|
||||
CONTINUE (refactor is optional)
|
||||
|
||||
CHECK: Contains "refactor" AND "pass"
|
||||
IF NOT found:
|
||||
Mark: "Refactor phase verification failed"
|
||||
ELSE:
|
||||
Mark: "Refactor phase [PASS]"
|
||||
|
||||
4. Calculate chain score:
|
||||
- Red + Green + Refactor all [PASS] = 100%
|
||||
- Red + Green [PASS], Refactor missing = 80%
|
||||
- Red [PASS], Green missing = 40%
|
||||
- All missing = 0%
|
||||
```
|
||||
|
||||
#### Phase 3e: Generate Analysis Report
|
||||
|
||||
Create `.workflow/active/{session_id}/.process/tdd-cycle-report.md`:
|
||||
|
||||
```markdown
|
||||
# TDD Cycle Analysis - {Session ID}
|
||||
|
||||
## Coverage Metrics
|
||||
- **Line Coverage**: {percentage}%
|
||||
- **Branch Coverage**: {percentage}%
|
||||
- **Function Coverage**: {percentage}%
|
||||
|
||||
## Coverage Details
|
||||
### Covered
|
||||
- {covered_lines} lines
|
||||
- {covered_branches} branches
|
||||
- {covered_functions} functions
|
||||
|
||||
### Uncovered
|
||||
- Lines: {uncovered_line_numbers}
|
||||
- Branches: {uncovered_branch_locations}
|
||||
|
||||
## TDD Cycle Verification
|
||||
|
||||
### Feature 1: {Feature Name}
|
||||
**Chain**: TEST-1.1 -> IMPL-1.1 -> REFACTOR-1.1
|
||||
|
||||
- [PASS] **Red Phase**: Tests created and failed initially
|
||||
- [PASS] **Green Phase**: Implementation made tests pass
|
||||
- [PASS] **Refactor Phase**: Refactoring maintained green tests
|
||||
|
||||
[Repeat for all features]
|
||||
|
||||
## TDD Compliance Summary
|
||||
- **Total Chains**: {N}
|
||||
- **Complete Cycles**: {N}
|
||||
- **Incomplete Cycles**: {0}
|
||||
- **Compliance Score**: {score}/100
|
||||
|
||||
## Gaps Identified
|
||||
- {gap descriptions}
|
||||
|
||||
## Recommendations
|
||||
- {improvement suggestions}
|
||||
```
|
||||
|
||||
#### Coverage Metrics Calculation
|
||||
|
||||
```bash
|
||||
line_coverage=$(jq '.coverage.lineCoverage' test-results.json)
|
||||
branch_coverage=$(jq '.coverage.branchCoverage' test-results.json)
|
||||
function_coverage=$(jq '.coverage.functionCoverage' test-results.json)
|
||||
|
||||
overall_score=$(echo "($line_coverage + $branch_coverage + $function_coverage) / 3" | bc)
|
||||
```
|
||||
|
||||
**Parse Output Files**:
|
||||
```bash
|
||||
# Check required outputs exist
|
||||
IF NOT EXISTS(process_dir/test-results.json):
|
||||
WARNING: "test-results.json not found. Coverage analysis incomplete."
|
||||
coverage_data = null
|
||||
ELSE:
|
||||
coverage_data = Read(process_dir/test-results.json)
|
||||
|
||||
IF NOT EXISTS(process_dir/coverage-report.json):
|
||||
WARNING: "coverage-report.json not found. Coverage metrics incomplete."
|
||||
metrics = null
|
||||
ELSE:
|
||||
metrics = Read(process_dir/coverage-report.json)
|
||||
|
||||
IF NOT EXISTS(process_dir/tdd-cycle-report.md):
|
||||
WARNING: "tdd-cycle-report.md not found. Cycle validation incomplete."
|
||||
cycle_data = null
|
||||
ELSE:
|
||||
cycle_data = Read(process_dir/tdd-cycle-report.md)
|
||||
```
|
||||
|
||||
**Extract Coverage Metrics**:
|
||||
```
|
||||
If coverage_data exists:
|
||||
- line_coverage_percent
|
||||
- branch_coverage_percent
|
||||
- function_coverage_percent
|
||||
- uncovered_files (list)
|
||||
- uncovered_lines (map: file -> line ranges)
|
||||
|
||||
If cycle_data exists:
|
||||
- red_phase_compliance (tests failed initially?)
|
||||
- green_phase_compliance (tests pass after impl?)
|
||||
- refactor_phase_compliance (tests stay green during refactor?)
|
||||
- minimal_implementation_score (was impl minimal?)
|
||||
```
|
||||
|
||||
**Output**: coverage_analysis, cycle_analysis
|
||||
|
||||
---
|
||||
|
||||
### Step 7.4: Compliance Report Generation
|
||||
|
||||
**Calculate Compliance Score**:
|
||||
```
|
||||
Base Score: 100 points
|
||||
|
||||
Deductions:
|
||||
Chain Structure:
|
||||
- Missing TEST task: -30 points per feature
|
||||
- Missing IMPL task: -30 points per feature
|
||||
- Missing REFACTOR task: -10 points per feature
|
||||
- Wrong dependency: -15 points per error
|
||||
- Wrong agent: -5 points per error
|
||||
- Wrong tdd_phase: -5 points per error
|
||||
|
||||
TDD Cycle Compliance:
|
||||
- Test didn't fail initially: -10 points per feature
|
||||
- Tests didn't pass after IMPL: -20 points per feature
|
||||
- Tests broke during REFACTOR: -15 points per feature
|
||||
- Over-engineered IMPL: -10 points per feature
|
||||
|
||||
Coverage Quality:
|
||||
- Line coverage < 80%: -5 points
|
||||
- Branch coverage < 70%: -5 points
|
||||
- Function coverage < 80%: -5 points
|
||||
- Critical paths uncovered: -10 points
|
||||
|
||||
Final Score: Max(0, Base Score - Total Deductions)
|
||||
```
|
||||
|
||||
**Determine Quality Gate**:
|
||||
```
|
||||
IF score >= 90 AND no_critical_violations:
|
||||
recommendation = "APPROVED"
|
||||
ELSE IF score >= 70 AND critical_violations == 0:
|
||||
recommendation = "PROCEED_WITH_CAVEATS"
|
||||
ELSE IF score >= 50:
|
||||
recommendation = "REQUIRE_FIXES"
|
||||
ELSE:
|
||||
recommendation = "BLOCK_MERGE"
|
||||
```
|
||||
|
||||
**Quality Gate Criteria**:
|
||||
|
||||
| Recommendation | Score Range | Critical Violations | Action |
|
||||
|----------------|-------------|---------------------|--------|
|
||||
| **APPROVED** | ≥90 | 0 | Safe to merge |
|
||||
| **PROCEED_WITH_CAVEATS** | ≥70 | 0 | Can proceed, address minor issues |
|
||||
| **REQUIRE_FIXES** | ≥50 | Any | Must fix before merge |
|
||||
| **BLOCK_MERGE** | <50 | Any | Block merge until resolved |
|
||||
|
||||
**Critical Violations**:
|
||||
- Missing TEST or IMPL task for any feature
|
||||
- Tests didn't fail initially (Red phase violation)
|
||||
- Tests didn't pass after IMPL (Green phase violation)
|
||||
- Tests broke during REFACTOR (Refactor phase violation)
|
||||
|
||||
**Generate Report**:
|
||||
```javascript
|
||||
const report_content = generateComplianceReport(/* see template below */)
|
||||
const report_path = `${session_dir}/TDD_COMPLIANCE_REPORT.md`
|
||||
Write(report_path, report_content)
|
||||
```
|
||||
|
||||
**Display Summary to User**:
|
||||
```
|
||||
=== TDD Verification Complete ===
|
||||
Session: {session_id}
|
||||
Report: {report_path}
|
||||
|
||||
Quality Gate: {recommendation}
|
||||
Compliance Score: {score}/100
|
||||
|
||||
Chain Validation: {chain_completeness_score}%
|
||||
Line Coverage: {line_coverage}%
|
||||
Branch Coverage: {branch_coverage}%
|
||||
|
||||
Next: Review full report for detailed findings
|
||||
```
|
||||
|
||||
## TDD Compliance Report Template
|
||||
|
||||
```markdown
|
||||
# TDD Compliance Report - {Session ID}
|
||||
|
||||
**Generated**: {timestamp}
|
||||
**Session**: WFS-{sessionId}
|
||||
**Workflow Type**: TDD
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
### Quality Gate Decision
|
||||
|
||||
| Metric | Value | Status |
|
||||
|--------|-------|--------|
|
||||
| Compliance Score | {score}/100 | {status_emoji} |
|
||||
| Chain Completeness | {percentage}% | {status} |
|
||||
| Line Coverage | {percentage}% | {status} |
|
||||
| Branch Coverage | {percentage}% | {status} |
|
||||
| Function Coverage | {percentage}% | {status} |
|
||||
|
||||
### Recommendation
|
||||
|
||||
**{RECOMMENDATION}**
|
||||
|
||||
**Decision Rationale**:
|
||||
{brief explanation based on score and violations}
|
||||
|
||||
**Quality Gate Criteria**:
|
||||
- **APPROVED**: Score ≥90, no critical violations
|
||||
- **PROCEED_WITH_CAVEATS**: Score ≥70, no critical violations
|
||||
- **REQUIRE_FIXES**: Score ≥50 or critical violations exist
|
||||
- **BLOCK_MERGE**: Score <50
|
||||
|
||||
---
|
||||
|
||||
## Chain Analysis
|
||||
|
||||
### Feature 1: {Feature Name}
|
||||
**Status**: ✅ Complete
|
||||
**Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
|
||||
|
||||
| Phase | Task | Status | Details |
|
||||
|-------|------|--------|---------|
|
||||
| Red | TEST-1.1 | ✅ Pass | Test created and failed with clear message |
|
||||
| Green | IMPL-1.1 | ✅ Pass | Minimal implementation made test pass |
|
||||
| Refactor | REFACTOR-1.1 | ✅ Pass | Code improved, tests remained green |
|
||||
|
||||
### Chain Validation Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Features | {count} |
|
||||
| Complete Chains | {count} ({percent}%) |
|
||||
| Incomplete Chains | {count} |
|
||||
| Missing TEST | {count} |
|
||||
| Missing IMPL | {count} |
|
||||
| Missing REFACTOR | {count} |
|
||||
| Dependency Errors | {count} |
|
||||
| Meta Field Errors | {count} |
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage Analysis
|
||||
|
||||
### Coverage Metrics
|
||||
|
||||
| Metric | Coverage | Target | Status |
|
||||
|--------|----------|--------|--------|
|
||||
| Line Coverage | {percentage}% | ≥80% | {status} |
|
||||
| Branch Coverage | {percentage}% | ≥70% | {status} |
|
||||
| Function Coverage | {percentage}% | ≥80% | {status} |
|
||||
|
||||
### Coverage Gaps
|
||||
|
||||
| File | Lines | Issue | Priority |
|
||||
|------|-------|-------|----------|
|
||||
| {file} | {lines} | {issue} | {priority} |
|
||||
|
||||
---
|
||||
|
||||
## TDD Cycle Validation
|
||||
|
||||
### Red Phase (Write Failing Test)
|
||||
- {N}/{total} features had failing tests initially ({percent}%)
|
||||
- ✅ Compliant features: {list}
|
||||
- ❌ Non-compliant features: {list}
|
||||
|
||||
### Green Phase (Make Test Pass)
|
||||
- {N}/{total} implementations made tests pass ({percent}%)
|
||||
- ✅ Compliant features: {list}
|
||||
- ❌ Non-compliant features: {list}
|
||||
|
||||
### Refactor Phase (Improve Quality)
|
||||
- {N}/{total} features completed refactoring ({percent}%)
|
||||
- ✅ Compliant features: {list}
|
||||
- ❌ Non-compliant features: {list}
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Assessment
|
||||
|
||||
### Strengths
|
||||
- {strengths}
|
||||
|
||||
### Areas for Improvement
|
||||
- {improvements}
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings by Severity
|
||||
|
||||
### Critical Issues ({count})
|
||||
{List of critical issues with impact and remediation}
|
||||
|
||||
### High Priority Issues ({count})
|
||||
{List of high priority issues}
|
||||
|
||||
### Medium Priority Issues ({count})
|
||||
{List of medium priority issues}
|
||||
|
||||
### Low Priority Issues ({count})
|
||||
{List of low priority issues}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Required Fixes (Before Merge)
|
||||
1. {required fixes}
|
||||
|
||||
### Recommended Improvements
|
||||
1. {recommended improvements}
|
||||
|
||||
### Optional Enhancements
|
||||
1. {optional enhancements}
|
||||
|
||||
---
|
||||
|
||||
## Metrics Summary
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Total Features | {count} |
|
||||
| Complete Chains | {count} ({percent}%) |
|
||||
| Compliance Score | {score}/100 |
|
||||
| Critical Issues | {count} |
|
||||
| High Issues | {count} |
|
||||
| Medium Issues | {count} |
|
||||
| Low Issues | {count} |
|
||||
| Line Coverage | {percent}% |
|
||||
| Branch Coverage | {percent}% |
|
||||
| Function Coverage | {percent}% |
|
||||
|
||||
---
|
||||
|
||||
**Report End**
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Session Discovery Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| No active session | No WFS-* directories | Provide --session explicitly |
|
||||
| Multiple active sessions | Multiple WFS-* directories | Provide --session explicitly |
|
||||
| Session not found | Invalid session-id | Check available sessions |
|
||||
|
||||
### Validation Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Task files missing | Incomplete planning | Run /workflow-tdd-plan first |
|
||||
| Invalid JSON | Corrupted task files | Regenerate tasks |
|
||||
| Missing summaries | Tasks not executed | Execute tasks before verify |
|
||||
|
||||
### Analysis Errors
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Coverage tool missing | No test framework | Configure testing first |
|
||||
| Tests fail to run | Code errors | Fix errors before verify |
|
||||
| Coverage analysis fails | Test framework or coverage tool error | Check test framework configuration |
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `TDD_COMPLIANCE_REPORT.md` (comprehensive compliance report)
|
||||
- **Files**: `.process/test-results.json`, `.process/coverage-report.json`, `.process/tdd-cycle-report.md`
|
||||
|
||||
## Output Files Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── TDD_COMPLIANCE_REPORT.md # Comprehensive compliance report ⭐
|
||||
└── .process/
|
||||
├── test-results.json # From coverage analysis (Step 7.3)
|
||||
├── coverage-report.json # From coverage analysis (Step 7.3)
|
||||
└── tdd-cycle-report.md # From coverage analysis (Step 7.3)
|
||||
```
|
||||
|
||||
## Next Steps Decision Table
|
||||
|
||||
| Situation | Recommended Command | Purpose |
|
||||
|-----------|---------------------|---------|
|
||||
| APPROVED | `workflow-execute` skill | Start TDD implementation |
|
||||
| PROCEED_WITH_CAVEATS | `workflow-execute` skill | Start with noted caveats |
|
||||
| REQUIRE_FIXES | Review report, refine tasks | Address issues before proceed |
|
||||
| BLOCK_MERGE | `workflow-plan` skill (replan phase) | Significant restructuring needed |
|
||||
| After implementation | Re-run `workflow-tdd-plan` skill (tdd-verify phase) | Verify post-execution compliance |
|
||||
Reference in New Issue
Block a user