mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-29 20:11:04 +08:00
feat: 增强 command-guide skill 支持深度命令分析和 CLI 辅助查询
新增 Mode 6: 深度命令分析 - 创建 reference 备份目录（80个文档：11 agents + 69 commands） - 支持简单查询（直接文件查找）和复杂查询（CLI 辅助分析） - 集成 gemini/qwen 进行跨命令对比、最佳实践、工作流分析 - 添加查询复杂度自动分类和降级策略 更新文档 - SKILL.md: 添加 Mode 6 说明和 Reference Documentation 章节 - implementation-details.md: 添加完整的 Mode 6 实现逻辑 - 版本更新至 v1.3.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -0,0 +1,471 @@
|
||||
---
|
||||
name: conflict-resolution
|
||||
description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
|
||||
argument-hint: "--session WFS-session-id --context path/to/context-package.json"
|
||||
examples:
|
||||
- /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
|
||||
- /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
|
||||
---
|
||||
|
||||
# Conflict Resolution Command
|
||||
|
||||
## Purpose
|
||||
Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
|
||||
|
||||
**Scope**: Detection and strategy generation only - NO code modification or task creation.
|
||||
|
||||
**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
| Responsibility | Description |
|
||||
|---------------|-------------|
|
||||
| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
|
||||
| **Generate Strategies** | Provide 2-4 resolution options per conflict |
|
||||
| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
|
||||
| **User Decision** | Present options, never auto-apply |
|
||||
| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
|
||||
|
||||
## Conflict Categories
|
||||
|
||||
### 1. Architecture Conflicts
|
||||
- Incompatible design patterns
|
||||
- Module structure changes
|
||||
- Pattern migration requirements
|
||||
|
||||
### 2. API Conflicts
|
||||
- Breaking contract changes
|
||||
- Signature modifications
|
||||
- Public interface impacts
|
||||
|
||||
### 3. Data Model Conflicts
|
||||
- Schema modifications
|
||||
- Type breaking changes
|
||||
- Data migration needs
|
||||
|
||||
### 4. Dependency Conflicts
|
||||
- Version incompatibilities
|
||||
- Setup conflicts
|
||||
- Breaking updates
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 1: Validation
|
||||
```
|
||||
1. Verify session directory exists
|
||||
2. Load context-package.json
|
||||
3. Check conflict_risk (skip if none/low)
|
||||
4. Prepare agent task prompt
|
||||
```
|
||||
|
||||
### Phase 2: CLI-Powered Analysis
|
||||
|
||||
**Agent Delegation**:
|
||||
```javascript
|
||||
Task(subagent_type="cli-execution-agent", prompt=`
|
||||
## Context
|
||||
- Session: {session_id}
|
||||
- Risk: {conflict_risk}
|
||||
- Files: {existing_files_list}
|
||||
|
||||
## Analysis Steps
|
||||
|
||||
### 1. Load Context
|
||||
- Read existing files from conflict_detection.existing_files
|
||||
- Load plan from .workflow/{session_id}/.process/context-package.json
|
||||
- Extract role analyses and requirements
|
||||
|
||||
### 2. Execute CLI Analysis
|
||||
|
||||
Primary (Gemini):
|
||||
cd {project_root} && gemini -p "
|
||||
PURPOSE: Detect conflicts between plan and codebase
|
||||
TASK:
|
||||
• Compare architectures
|
||||
• Identify breaking API changes
|
||||
• Detect data model incompatibilities
|
||||
• Assess dependency conflicts
|
||||
MODE: analysis
|
||||
CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
|
||||
EXPECTED: Conflict list with severity ratings
|
||||
RULES: Focus on breaking changes and migration needs
|
||||
"
|
||||
|
||||
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
|
||||
- Affected files + impact
|
||||
- Options with pros/cons, effort, risk
|
||||
- Recommended strategy + rationale
|
||||
|
||||
### 4. Return Structured Conflict Data
|
||||
|
||||
⚠️ DO NOT generate CONFLICT_RESOLUTION.md file
|
||||
|
||||
Return JSON format for programmatic processing:
|
||||
|
||||
\`\`\`json
|
||||
{
|
||||
"conflicts": [
|
||||
{
|
||||
"id": "CON-001",
|
||||
"brief": "一行中文冲突摘要",
|
||||
"severity": "Critical|High|Medium",
|
||||
"category": "Architecture|API|Data|Dependency",
|
||||
"affected_files": [
|
||||
".workflow/{session}/.brainstorm/guidance-specification.md",
|
||||
".workflow/{session}/.brainstorm/system-architect/analysis.md"
|
||||
],
|
||||
"description": "详细描述冲突 - 什么不兼容",
|
||||
"impact": {
|
||||
"scope": "影响的模块/组件",
|
||||
"compatibility": "Yes|No|Partial",
|
||||
"migration_required": true|false,
|
||||
"estimated_effort": "人天估计"
|
||||
},
|
||||
"strategies": [
|
||||
{
|
||||
"name": "策略名称（中文）",
|
||||
"approach": "实现方法简述",
|
||||
"complexity": "Low|Medium|High",
|
||||
"risk": "Low|Medium|High",
|
||||
"effort": "时间估计",
|
||||
"pros": ["优点1", "优点2"],
|
||||
"cons": ["缺点1", "缺点2"],
|
||||
"modifications": [
|
||||
{
|
||||
"file": ".workflow/{session}/.brainstorm/guidance-specification.md",
|
||||
"section": "## 2. System Architect Decisions",
|
||||
"change_type": "update",
|
||||
"old_content": "原始内容片段（用于定位）",
|
||||
"new_content": "修改后的内容",
|
||||
"rationale": "为什么这样改"
|
||||
},
|
||||
{
|
||||
"file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
|
||||
"section": "## Design Decisions",
|
||||
"change_type": "update",
|
||||
"old_content": "原始内容片段",
|
||||
"new_content": "修改后的内容",
|
||||
"rationale": "修改理由"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "策略2名称",
|
||||
"approach": "...",
|
||||
"complexity": "Medium",
|
||||
"risk": "Low",
|
||||
"effort": "1-2天",
|
||||
"pros": ["优点"],
|
||||
"cons": ["缺点"],
|
||||
"modifications": [...]
|
||||
}
|
||||
],
|
||||
"recommended": 0,
|
||||
"modification_suggestions": [
|
||||
"建议1：具体的修改方向或注意事项",
|
||||
"建议2：可能需要考虑的边界情况",
|
||||
"建议3：相关的最佳实践或模式"
|
||||
]
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"total": 2,
|
||||
"critical": 1,
|
||||
"high": 1,
|
||||
"medium": 0
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
⚠️ CRITICAL Requirements for modifications field:
|
||||
- old_content: Must be exact text from target file (20-100 chars for unique match)
|
||||
- new_content: Complete replacement text (maintains formatting)
|
||||
- change_type: "update" (replace), "add" (insert), "remove" (delete)
|
||||
- file: Full path relative to project root
|
||||
- section: Markdown heading for context (helps locate position)
|
||||
- Minimum 2 strategies per conflict, max 4
|
||||
- All text in Chinese for user-facing fields (brief, name, pros, cons)
|
||||
- modification_suggestions: 2-5 actionable suggestions for custom handling (Chinese)
|
||||
|
||||
Quality Standards:
|
||||
- Each strategy must have actionable modifications
|
||||
- old_content must be precise enough for Edit tool matching
|
||||
- new_content preserves markdown formatting and structure
|
||||
- Recommended strategy (index) based on lowest complexity + risk
|
||||
- modification_suggestions must be specific, actionable, and context-aware
|
||||
- Each suggestion should address a specific aspect (compatibility, migration, testing, etc.)
|
||||
`)
|
||||
```
|
||||
|
||||
**Agent Internal Flow**:
|
||||
```
|
||||
1. Load context package
|
||||
2. Check conflict_risk (exit if none/low)
|
||||
3. Read existing files + plan artifacts
|
||||
4. Run CLI analysis (Gemini→Qwen→Claude)
|
||||
5. Parse conflict findings
|
||||
6. Generate 2-4 strategies per conflict with modifications
|
||||
7. Return JSON to stdout (NOT file write)
|
||||
8. Return execution log path
|
||||
```
|
||||
|
||||
### Phase 3: User Confirmation via Text Interaction
|
||||
|
||||
**Command parses agent JSON output and presents conflicts to user via text**:
|
||||
|
||||
```javascript
|
||||
// 1. Parse agent JSON output
|
||||
const conflictData = JSON.parse(agentOutput);
|
||||
const conflicts = conflictData.conflicts; // No 4-conflict limit
|
||||
|
||||
// 2. Format conflicts as text output (max 10 per round)
|
||||
const batchSize = 10;
|
||||
const batches = chunkArray(conflicts, batchSize);
|
||||
|
||||
for (const [batchIdx, batch] of batches.entries()) {
|
||||
const totalBatches = batches.length;
|
||||
|
||||
// Output batch header
|
||||
console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
|
||||
|
||||
// Output each conflict in batch
|
||||
batch.forEach((conflict, idx) => {
|
||||
const questionNum = batchIdx * batchSize + idx + 1;
|
||||
console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
|
||||
|
||||
conflict.strategies.forEach((strategy, sIdx) => {
|
||||
const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
|
||||
console.log(`${optionLetter}) ${strategy.name}`);
|
||||
console.log(` 说明：${strategy.approach}`);
|
||||
console.log(` 复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
|
||||
});
|
||||
|
||||
// Add custom option
|
||||
const customLetter = String.fromCharCode(97 + conflict.strategies.length);
|
||||
console.log(`${customLetter}) 自定义修改`);
|
||||
console.log(` 说明：根据修改建议自行处理，不应用预设策略`);
|
||||
|
||||
// Show modification suggestions
|
||||
if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
|
||||
console.log(` 修改建议：`);
|
||||
conflict.modification_suggestions.forEach(suggestion => {
|
||||
console.log(` - ${suggestion}`);
|
||||
});
|
||||
}
|
||||
console.log();
|
||||
});
|
||||
|
||||
console.log(`请回答 (格式: 1a 2b 3c...)：`);
|
||||
|
||||
// Wait for user input
|
||||
const userInput = await readUserInput();
|
||||
|
||||
// Parse answers
|
||||
const answers = parseUserAnswers(userInput, batch);
|
||||
}
|
||||
|
||||
// 3. Build selected strategies (exclude custom selections)
|
||||
const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
|
||||
const customConflicts = answers.filter(a => a.isCustom).map(a => ({
|
||||
id: a.conflict.id,
|
||||
brief: a.conflict.brief,
|
||||
suggestions: a.conflict.modification_suggestions
|
||||
}));
|
||||
```
|
||||
|
||||
**Text Output Example**:
|
||||
```markdown
|
||||
===== 冲突解决 (第 1/1 轮) =====
|
||||
|
||||
【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
|
||||
a) 渐进式迁移
|
||||
说明：保留现有系统，逐步迁移到新方案
|
||||
复杂度: Medium | 风险: Low | 工作量: 3-5天
|
||||
b) 完全重写
|
||||
说明：废弃旧系统，从零实现新认证
|
||||
复杂度: High | 风险: Medium | 工作量: 7-10天
|
||||
c) 自定义修改
|
||||
说明：根据修改建议自行处理，不应用预设策略
|
||||
修改建议：
|
||||
- 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
|
||||
- 检查JWT token格式和验证逻辑是否需要调整
|
||||
- 确保用户会话管理与新架构保持一致
|
||||
|
||||
【问题2 - Data】CON-002: 数据库 schema 冲突
|
||||
a) 添加迁移脚本
|
||||
说明：创建数据库迁移脚本处理 schema 变更
|
||||
复杂度: Low | 风险: Low | 工作量: 1-2天
|
||||
b) 自定义修改
|
||||
说明：根据修改建议自行处理，不应用预设策略
|
||||
修改建议：
|
||||
- 检查现有表结构是否支持新增字段，避免破坏性变更
|
||||
- 考虑使用数据库版本控制工具（如Flyway或Liquibase）
|
||||
- 准备数据迁移和回滚策略
|
||||
|
||||
请回答 (格式: 1a 2b)：
|
||||
```
|
||||
|
||||
**User Input Examples**:
|
||||
- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
|
||||
- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
|
||||
- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
|
||||
|
||||
### Phase 4: Apply Modifications
|
||||
|
||||
```javascript
|
||||
// 1. Extract modifications from selected strategies
|
||||
const modifications = [];
|
||||
selectedStrategies.forEach(strategy => {
|
||||
if (strategy !== "skip") {
|
||||
modifications.push(...strategy.modifications);
|
||||
}
|
||||
});
|
||||
|
||||
// 2. Apply each modification using Edit tool
|
||||
modifications.forEach(mod => {
|
||||
if (mod.change_type === "update") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
old_string: mod.old_content,
|
||||
new_string: mod.new_content
|
||||
});
|
||||
}
|
||||
// Handle "add" and "remove" similarly
|
||||
});
|
||||
|
||||
// 3. Update context-package.json
|
||||
const contextPackage = JSON.parse(Read(contextPath));
|
||||
contextPackage.conflict_detection.conflict_risk = "resolved";
|
||||
contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
|
||||
contextPackage.conflict_detection.resolved_at = new Date().toISOString();
|
||||
Write(contextPath, JSON.stringify(contextPackage, null, 2));
|
||||
|
||||
// 4. Output custom conflict summary (if any)
|
||||
if (customConflicts.length > 0) {
|
||||
console.log("\n===== 需要自定义处理的冲突 =====\n");
|
||||
customConflicts.forEach(conflict => {
|
||||
console.log(`【${conflict.id}】${conflict.brief}`);
|
||||
console.log("修改建议：");
|
||||
conflict.suggestions.forEach(suggestion => {
|
||||
console.log(` - ${suggestion}`);
|
||||
});
|
||||
console.log();
|
||||
});
|
||||
}
|
||||
|
||||
// 5. Return summary
|
||||
return {
|
||||
resolved: modifications.length,
|
||||
custom: customConflicts.length,
|
||||
modified_files: [...new Set(modifications.map(m => m.file))],
|
||||
custom_conflicts: customConflicts
|
||||
};
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
```
|
||||
✓ Agent returns valid JSON structure
|
||||
✓ Text output displays all conflicts (max 10 per round)
|
||||
✓ User selections captured correctly
|
||||
✓ Edit tool successfully applies modifications
|
||||
✓ guidance-specification.md updated
|
||||
✓ Role analyses (*.md) updated
|
||||
✓ context-package.json marked as resolved
|
||||
✓ Agent log saved to .workflow/{session_id}/.chat/
|
||||
```
|
||||
|
||||
## Output Format: Agent JSON Response
|
||||
|
||||
**Focus**: Structured conflict data with actionable modifications for programmatic processing.
|
||||
|
||||
**Format**: JSON to stdout (NO file generation)
|
||||
|
||||
**Structure**: Defined in Phase 2, Step 4 (agent prompt)
|
||||
|
||||
### Key Requirements
|
||||
| Requirement | Details |
|
||||
|------------|---------|
|
||||
| **Conflict batching** | Max 10 conflicts per round (no total limit) |
|
||||
| **Strategy count** | 2-4 strategies per conflict |
|
||||
| **Modifications** | Each strategy includes file paths, old_content, new_content |
|
||||
| **User-facing text** | Chinese (brief, strategy names, pros/cons) |
|
||||
| **Technical fields** | English (severity, category, complexity, risk) |
|
||||
| **old_content precision** | 20-100 chars for unique Edit tool matching |
|
||||
| **File targets** | guidance-specification.md, role analyses (*.md) |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Recovery Strategy
|
||||
```
|
||||
1. Pre-check: Verify conflict_risk ≥ medium
|
||||
2. Monitor: Track agent via Task tool
|
||||
3. Validate: Parse agent JSON output
|
||||
4. Recover:
|
||||
- Agent failure → check logs + report error
|
||||
- Invalid JSON → retry once with Claude fallback
|
||||
- CLI failure → fallback to Claude analysis
|
||||
- Edit tool failure → report affected files + rollback option
|
||||
- User cancels → mark as "unresolved", continue to task-generate
|
||||
5. Degrade: If all fail, generate minimal conflict report and skip modifications
|
||||
```
|
||||
|
||||
### Rollback Handling
|
||||
```
|
||||
If Edit tool fails mid-application:
|
||||
1. Log all successfully applied modifications
|
||||
2. Output rollback option via text interaction
|
||||
3. If rollback selected: restore files from git or backups
|
||||
4. If continue: mark partial resolution in context-package.json
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
### Interface
|
||||
**Input**:
|
||||
- `--session` (required): WFS-{session-id}
|
||||
- `--context` (required): context-package.json path
|
||||
- Requires: `conflict_risk ≥ medium`
|
||||
|
||||
**Output**:
|
||||
- Modified files:
|
||||
- `.workflow/{session_id}/.brainstorm/guidance-specification.md`
|
||||
- `.workflow/{session_id}/.brainstorm/{role}/analysis.md`
|
||||
- `.workflow/{session_id}/.process/context-package.json` (conflict_risk → resolved)
|
||||
- NO report file generation
|
||||
|
||||
**User Interaction**:
|
||||
- Text-based strategy selection (max 10 conflicts per round)
|
||||
- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
|
||||
|
||||
### Success Criteria
|
||||
```
|
||||
✓ CLI analysis returns valid JSON structure
|
||||
✓ Conflicts presented in batches (max 10 per round)
|
||||
✓ Min 2 strategies per conflict with modifications
|
||||
✓ Each conflict includes 2-5 modification_suggestions
|
||||
✓ Text output displays all conflicts correctly with suggestions
|
||||
✓ User selections captured and processed
|
||||
✓ Edit tool applies modifications successfully
|
||||
✓ Custom conflicts displayed with suggestions for manual handling
|
||||
✓ guidance-specification.md updated with resolved conflicts
|
||||
✓ Role analyses (*.md) updated with resolved conflicts
|
||||
✓ context-package.json marked as "resolved"
|
||||
✓ No CONFLICT_RESOLUTION.md file generated
|
||||
✓ Modification summary includes custom conflict count
|
||||
✓ Agent log saved to .workflow/{session_id}/.chat/
|
||||
✓ Error handling robust (validate/retry/degrade)
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
| Command | Relationship |
|
||||
|---------|--------------|
|
||||
| `/workflow:tools:context-gather` | Generates input conflict_detection data |
|
||||
| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
|
||||
| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
|
||||
| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |
|
||||
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: gather
|
||||
description: Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON
|
||||
argument-hint: "--session WFS-session-id \"task description\""
|
||||
examples:
|
||||
- /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
|
||||
- /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
|
||||
- /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
|
||||
allowed-tools: Task(*), Read(*), Glob(*)
|
||||
---
|
||||
|
||||
# Context Gather Command (/workflow:tools:context-gather)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
|
||||
|
||||
**Agent**: `context-search-agent` (`.claude/agents/context-search-agent.md`)
|
||||
|
||||
## 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/{session}/.process/context-package.json`
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Step 1: Context-Package Detection
|
||||
|
||||
**Execute First** - Check if valid package already exists:
|
||||
|
||||
```javascript
|
||||
const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
|
||||
|
||||
if (file_exists(contextPackagePath)) {
|
||||
const existing = Read(contextPackagePath);
|
||||
|
||||
// Validate package belongs to current session
|
||||
if (existing?.metadata?.session_id === session_id) {
|
||||
console.log("✅ Valid context-package found for session:", session_id);
|
||||
console.log("📊 Stats:", existing.statistics);
|
||||
console.log("⚠️ Conflict Risk:", existing.conflict_detection.risk_level);
|
||||
return existing; // Skip execution, return existing
|
||||
} else {
|
||||
console.warn("⚠️ Invalid session_id in existing package, re-generating...");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Invoke Context-Search Agent
|
||||
|
||||
**Only execute if Step 1 finds no valid package**
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="context-search-agent",
|
||||
description="Gather comprehensive context for plan",
|
||||
prompt=`
|
||||
You are executing as context-search-agent (.claude/agents/context-search-agent.md).
|
||||
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
|
||||
|
||||
## Session Information
|
||||
- **Session ID**: ${session_id}
|
||||
- **Task Description**: ${task_description}
|
||||
- **Output Path**: .workflow/${session_id}/.process/context-package.json
|
||||
|
||||
## Mission
|
||||
Execute complete context-search-agent workflow for implementation planning:
|
||||
|
||||
### Phase 1: Initialization & Pre-Analysis
|
||||
1. **Detection**: Check for existing context-package (early exit if valid)
|
||||
2. **Foundation**: Initialize code-index, get project structure, load docs
|
||||
3. **Analysis**: Extract keywords, determine scope, classify complexity
|
||||
|
||||
### Phase 2: Multi-Source Context Discovery
|
||||
Execute all 4 discovery tracks:
|
||||
- **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 4-source data (archive > docs > code > web)
|
||||
3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
|
||||
4. Perform conflict detection with risk assessment
|
||||
5. **Inject historical conflicts** from archive analysis into conflict_detection
|
||||
6. Generate and validate context-package.json
|
||||
|
||||
## Output Requirements
|
||||
Complete context-package.json with:
|
||||
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
|
||||
- **project_context**: architecture_patterns, coding_conventions, tech_stack
|
||||
- **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[]}
|
||||
|
||||
## 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)
|
||||
|
||||
Execute autonomously following agent documentation.
|
||||
Report completion with statistics.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3: Output Verification
|
||||
|
||||
After agent completes, verify output:
|
||||
|
||||
```javascript
|
||||
// Verify file was created
|
||||
const outputPath = `.workflow/${session_id}/.process/context-package.json`;
|
||||
if (!file_exists(outputPath)) {
|
||||
throw new Error("❌ Agent failed to generate context-package.json");
|
||||
}
|
||||
```
|
||||
|
||||
## Parameter Reference
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) |
|
||||
| `task_description` | string | ✅ | Detailed task description for context extraction |
|
||||
|
||||
## Output Schema
|
||||
|
||||
Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema.
|
||||
|
||||
**Key Sections**:
|
||||
- **metadata**: Session info, keywords, complexity, tech stack
|
||||
- **project_context**: Architecture patterns, conventions, tech stack
|
||||
- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
|
||||
- **dependencies**: Internal and external dependency graphs
|
||||
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
|
||||
- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
|
||||
|
||||
## Historical Archive Analysis
|
||||
|
||||
### Track 1: Query Archive Manifest
|
||||
|
||||
The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
|
||||
|
||||
**Step 1: Check for Archive Manifest**
|
||||
```bash
|
||||
# Check if archive manifest exists
|
||||
if [[ -f .workflow/.archives/manifest.json ]]; then
|
||||
# Manifest available for querying
|
||||
fi
|
||||
```
|
||||
|
||||
**Step 2: Extract Task Keywords**
|
||||
```javascript
|
||||
// From current task description, extract key entities and operations
|
||||
const keywords = extractKeywords(task_description);
|
||||
// Examples: ["User", "model", "authentication", "JWT", "reporting"]
|
||||
```
|
||||
|
||||
**Step 3: Search Archive for Relevant Sessions**
|
||||
```javascript
|
||||
// Query manifest for sessions with matching tags or descriptions
|
||||
const relevantArchives = archives.filter(archive => {
|
||||
return archive.tags.some(tag => keywords.includes(tag)) ||
|
||||
keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
|
||||
});
|
||||
```
|
||||
|
||||
**Step 4: Extract Watch Patterns**
|
||||
```javascript
|
||||
// For each relevant archive, check watch_patterns for applicability
|
||||
const historicalConflicts = [];
|
||||
|
||||
relevantArchives.forEach(archive => {
|
||||
archive.lessons.watch_patterns?.forEach(pattern => {
|
||||
// Check if pattern trigger matches current task
|
||||
if (isPatternRelevant(pattern.pattern, task_description)) {
|
||||
historicalConflicts.push({
|
||||
source_session: archive.session_id,
|
||||
pattern: pattern.pattern,
|
||||
action: pattern.action,
|
||||
files_to_check: pattern.related_files,
|
||||
archived_at: archive.archived_at
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Step 5: Inject into Context Package**
|
||||
```json
|
||||
{
|
||||
"conflict_detection": {
|
||||
"risk_level": "medium",
|
||||
"risk_factors": ["..."],
|
||||
"affected_modules": ["..."],
|
||||
"mitigation_strategy": "...",
|
||||
"historical_conflicts": [
|
||||
{
|
||||
"source_session": "WFS-auth-feature",
|
||||
"pattern": "When modifying User model",
|
||||
"action": "Check reporting-service and auditing-service dependencies",
|
||||
"files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
|
||||
"archived_at": "2025-09-16T09:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Risk Level Escalation
|
||||
|
||||
If `historical_conflicts` array is not empty, minimum risk level should be "medium":
|
||||
|
||||
```javascript
|
||||
if (historicalConflicts.length > 0 && currentRisk === "low") {
|
||||
conflict_detection.risk_level = "medium";
|
||||
conflict_detection.risk_factors.push(
|
||||
`${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Archive Query Algorithm
|
||||
|
||||
```markdown
|
||||
1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
|
||||
2. IF manifest exists:
|
||||
a. Load manifest.json
|
||||
b. Extract keywords from task_description (nouns, verbs, technical terms)
|
||||
c. Filter archives where:
|
||||
- ANY tag matches keywords (case-insensitive) OR
|
||||
- description contains keywords (case-insensitive substring match)
|
||||
d. For each relevant archive:
|
||||
- Read lessons.watch_patterns array
|
||||
- Check if pattern.pattern keywords overlap with task_description
|
||||
- If relevant: Add to historical_conflicts array
|
||||
e. IF historical_conflicts.length > 0:
|
||||
- Set risk_level = max(current_risk, "medium")
|
||||
- Add to risk_factors
|
||||
3. Continue to Track 2 (reference documentation)
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
|
||||
```
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
|
||||
- ✅ Contains >80% relevant files based on task keywords
|
||||
- ✅ Execution completes within 2 minutes
|
||||
- ✅ All required schema fields present and valid
|
||||
- ✅ Conflict risk accurately assessed
|
||||
- ✅ Agent reports completion with statistics
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
|
||||
| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
|
||||
| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
|
||||
| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
|
||||
|
||||
## Notes
|
||||
|
||||
- **Detection-first**: Always check for existing package before invoking agent
|
||||
- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
|
||||
- **No redundancy**: This command is a thin orchestrator, all logic in agent
|
||||
- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
|
||||
@@ -0,0 +1,363 @@
|
||||
---
|
||||
name: task-generate-agent
|
||||
description: Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning
|
||||
argument-hint: "--session WFS-session-id [--cli-execute]"
|
||||
examples:
|
||||
- /workflow:tools:task-generate-agent --session WFS-auth
|
||||
- /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
|
||||
---
|
||||
|
||||
# Autonomous Task Generation Command
|
||||
|
||||
## Overview
|
||||
Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
|
||||
|
||||
## 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
|
||||
- **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
|
||||
- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Discovery & Context Loading
|
||||
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
|
||||
|
||||
**Agent Context Package**:
|
||||
```javascript
|
||||
{
|
||||
"session_id": "WFS-[session-id]",
|
||||
"execution_mode": "agent-mode" | "cli-execute-mode", // Determined by flag
|
||||
"task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
|
||||
| "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
|
||||
// Path selected by command based on --cli-execute flag, agent reads it
|
||||
"session_metadata": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from .workflow/{session-id}/workflow-session.json
|
||||
},
|
||||
"brainstorm_artifacts": {
|
||||
// Loaded from context-package.json → brainstorm_artifacts section
|
||||
"role_analyses": [
|
||||
{
|
||||
"role": "system-architect",
|
||||
"files": [{"path": "...", "type": "primary|supplementary"}]
|
||||
}
|
||||
],
|
||||
"guidance_specification": {"path": "...", "exists": true},
|
||||
"synthesis_output": {"path": "...", "exists": true},
|
||||
"conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium
|
||||
},
|
||||
"context_package_path": ".workflow/{session-id}/.process/context-package.json",
|
||||
"context_package": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from .workflow/{session-id}/.process/context-package.json
|
||||
},
|
||||
"mcp_capabilities": {
|
||||
"code_index": true,
|
||||
"exa_code": true,
|
||||
"exa_web": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Discovery Actions**:
|
||||
1. **Load Session Context** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("workflow-session.json")) {
|
||||
Read(.workflow/{session-id}/workflow-session.json)
|
||||
}
|
||||
```
|
||||
|
||||
2. **Load Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("context-package.json")) {
|
||||
Read(.workflow/{session-id}/.process/context-package.json)
|
||||
}
|
||||
```
|
||||
|
||||
3. **Extract & Load Role Analyses** (from context-package.json)
|
||||
```javascript
|
||||
// Extract role analysis paths from context package
|
||||
const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files.map(f => f.path));
|
||||
|
||||
// Load each role analysis file
|
||||
roleAnalysisPaths.forEach(path => Read(path));
|
||||
```
|
||||
|
||||
4. **Load Conflict Resolution** (from context-package.json, if exists)
|
||||
```javascript
|
||||
if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
|
||||
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
|
||||
}
|
||||
```
|
||||
|
||||
5. **Code Analysis with Native Tools** (optional - enhance understanding)
|
||||
```bash
|
||||
# Find relevant files for task context
|
||||
find . -name "*auth*" -type f
|
||||
rg "authentication|oauth" -g "*.ts"
|
||||
```
|
||||
|
||||
6. **MCP External Research** (optional - gather best practices)
|
||||
```javascript
|
||||
// Get external examples for implementation
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript JWT authentication best practices",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 2: Agent Execution (Document Generation)
|
||||
|
||||
**Pre-Agent Template Selection** (Command decides path before invoking agent):
|
||||
```javascript
|
||||
// Command checks flag and selects template PATH (not content)
|
||||
const templatePath = hasCliExecuteFlag
|
||||
? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
|
||||
: "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
|
||||
```
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
description="Generate task JSON and implementation plan",
|
||||
prompt=`
|
||||
## Execution Context
|
||||
|
||||
**Session ID**: WFS-{session-id}
|
||||
**Execution Mode**: {agent-mode | cli-execute-mode}
|
||||
**Task JSON Template Path**: {template_path}
|
||||
|
||||
## Phase 1: Discovery Results (Provided Context)
|
||||
|
||||
### Session Metadata
|
||||
{session_metadata_content}
|
||||
|
||||
### Role Analyses (Enhanced by Synthesis)
|
||||
{role_analyses_content}
|
||||
- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
|
||||
|
||||
### Artifacts Inventory
|
||||
- **Guidance Specification**: {guidance_spec_path}
|
||||
- **Role Analyses**: {role_analyses_list}
|
||||
|
||||
### Context Package
|
||||
{context_package_summary}
|
||||
- Includes conflict_risk assessment
|
||||
|
||||
### Conflict Resolution (Conditional)
|
||||
If conflict_risk was medium/high, modifications have been applied to:
|
||||
- **guidance-specification.md**: Design decisions updated to resolve conflicts
|
||||
- **Role analyses (*.md)**: Recommendations adjusted for compatibility
|
||||
- **context-package.json**: Marked as "resolved" with conflict IDs
|
||||
- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
|
||||
|
||||
### MCP Analysis Results (Optional)
|
||||
**Code Structure**: {mcp_code_index_results}
|
||||
**External Research**: {mcp_exa_research_results}
|
||||
|
||||
## Phase 2: Document Generation Task
|
||||
|
||||
### Task Decomposition Standards
|
||||
**Core Principle**: Task Merging Over Decomposition
|
||||
- **Merge Rule**: Execute together when possible
|
||||
- **Decompose Only When**:
|
||||
- Excessive workload (>2500 lines or >6 files)
|
||||
- Different tech stacks or domains
|
||||
- Sequential dependency blocking
|
||||
- Parallel execution needed
|
||||
|
||||
**Task Limits**:
|
||||
- **Maximum 10 tasks** (hard limit)
|
||||
- **Function-based**: Complete units (logic + UI + tests + config)
|
||||
- **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
|
||||
|
||||
### Required Outputs
|
||||
|
||||
#### 1. Task JSON Files (.task/IMPL-*.json)
|
||||
**Location**: .workflow/{session-id}/.task/
|
||||
**Template**: Read from the template path provided above
|
||||
|
||||
**Task JSON Template Loading**:
|
||||
\`\`\`
|
||||
Read({template_path})
|
||||
\`\`\`
|
||||
|
||||
**Important**:
|
||||
- Read the template from the path provided in context
|
||||
- Use the template structure exactly as written
|
||||
- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
|
||||
- Include MCP tool integration in pre_analysis steps
|
||||
- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
|
||||
|
||||
#### 2. IMPL_PLAN.md
|
||||
**Location**: .workflow/{session-id}/IMPL_PLAN.md
|
||||
|
||||
**IMPL_PLAN Template**:
|
||||
\`\`\`
|
||||
$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
|
||||
\`\`\`
|
||||
|
||||
**Important**:
|
||||
- Use the template above for IMPL_PLAN.md generation
|
||||
- Replace all {placeholder} variables with actual session-specific values
|
||||
- Populate CCW Workflow Context based on actual phase progression
|
||||
- Extract content from role analyses and context-package.json
|
||||
- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
|
||||
- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
|
||||
|
||||
#### 3. TODO_LIST.md
|
||||
**Location**: .workflow/{session-id}/TODO_LIST.md
|
||||
**Structure**:
|
||||
\`\`\`markdown
|
||||
# Tasks: {Session Topic}
|
||||
|
||||
## Task Progress
|
||||
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
|
||||
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
|
||||
- [ ] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json)
|
||||
|
||||
- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
|
||||
|
||||
## Status Legend
|
||||
- \`▸\` = Container task (has subtasks)
|
||||
- \`- [ ]\` = Pending leaf task
|
||||
- \`- [x]\` = Completed leaf task
|
||||
\`\`\`
|
||||
|
||||
### Execution Instructions for Agent
|
||||
|
||||
**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
|
||||
|
||||
**Note**: The correct task JSON template path has been pre-selected by the command based on the `--cli-execute` flag and is provided in the context as `{template_path}`.
|
||||
|
||||
**Step 1: Load Task JSON Template**
|
||||
- Read template from the provided path: `Read({template_path})`
|
||||
- This template is already the correct one based on execution mode
|
||||
|
||||
**Step 2: Extract and Decompose Tasks**
|
||||
- Parse role analysis.md files for requirements, design specs, and task recommendations
|
||||
- Review synthesis enhancements and clarifications in role analyses
|
||||
- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
|
||||
- Apply task merging rules (merge when possible, decompose only when necessary)
|
||||
- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
|
||||
- Ensure task count ≤10
|
||||
|
||||
**Step 3: Generate Task JSON Files**
|
||||
- Use the template structure from Step 1
|
||||
- Create .task/IMPL-*.json files with proper structure
|
||||
- Replace all {placeholder} variables with actual session paths
|
||||
- Embed artifacts array with brainstorming outputs
|
||||
- Include MCP tool integration in pre_analysis steps
|
||||
|
||||
**Step 4: Create IMPL_PLAN.md**
|
||||
- Use IMPL_PLAN template
|
||||
- Populate all sections with session-specific content
|
||||
- List artifacts with priorities and usage guidelines
|
||||
- Document execution strategy and dependencies
|
||||
|
||||
**Step 5: Generate TODO_LIST.md**
|
||||
- Create task progress checklist matching generated JSONs
|
||||
- Use proper status indicators (▸, [ ], [x])
|
||||
- Link to task JSON files
|
||||
|
||||
**Step 6: Update Session State**
|
||||
- Update workflow-session.json with task count and artifact inventory
|
||||
- Mark session ready for execution
|
||||
|
||||
### MCP Enhancement Examples
|
||||
|
||||
**Code Index Usage**:
|
||||
\`\`\`javascript
|
||||
// Discover authentication-related files
|
||||
bash(find . -name "*auth*" -type f)
|
||||
|
||||
// Search for OAuth patterns
|
||||
bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
|
||||
|
||||
// Get file summary for key components
|
||||
bash(rg "^(class|function|export|interface)" src/auth/index.ts)
|
||||
\`\`\`
|
||||
|
||||
**Exa Research Usage**:
|
||||
\`\`\`javascript
|
||||
// Get best practices for task implementation
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript OAuth2 implementation patterns",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
|
||||
// Research specific API usage
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="Express.js JWT middleware examples",
|
||||
tokensNum=5000
|
||||
)
|
||||
\`\`\`
|
||||
|
||||
### Quality Validation
|
||||
|
||||
Before completion, verify:
|
||||
- [ ] All task JSON files created in .task/ directory
|
||||
- [ ] Each task JSON has 5 required fields
|
||||
- [ ] Artifact references correctly mapped
|
||||
- [ ] Flow control includes artifact loading steps
|
||||
- [ ] MCP tool integration added where appropriate
|
||||
- [ ] IMPL_PLAN.md follows required structure
|
||||
- [ ] TODO_LIST.md matches task JSONs
|
||||
- [ ] Dependency graph is acyclic
|
||||
- [ ] Task count within limits (≤10)
|
||||
- [ ] Session state updated
|
||||
|
||||
## Output
|
||||
|
||||
Generate all three documents and report completion status:
|
||||
- Task JSON files created: N files
|
||||
- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
|
||||
- MCP enhancements: code-index, exa-research
|
||||
- Session ready for execution: /workflow:execute
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
### Agent Context Passing
|
||||
|
||||
**Memory-Aware Context Assembly**:
|
||||
```javascript
|
||||
// Assemble context package for agent
|
||||
const agentContext = {
|
||||
session_id: "WFS-[id]",
|
||||
|
||||
// Use memory if available, else load
|
||||
session_metadata: memory.has("workflow-session.json")
|
||||
? memory.get("workflow-session.json")
|
||||
: Read(.workflow/WFS-[id]/workflow-session.json),
|
||||
|
||||
context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
|
||||
|
||||
context_package: memory.has("context-package.json")
|
||||
? memory.get("context-package.json")
|
||||
: Read(".workflow/WFS-[id]/.process/context-package.json"),
|
||||
|
||||
// Extract brainstorm artifacts from context package
|
||||
brainstorm_artifacts: extractBrainstormArtifacts(context_package),
|
||||
|
||||
// Load role analyses using paths from context package
|
||||
role_analyses: brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files)
|
||||
.map(file => Read(file.path)),
|
||||
|
||||
// Load conflict resolution if exists (from context package)
|
||||
conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
|
||||
? Read(brainstorm_artifacts.conflict_resolution.path)
|
||||
: null,
|
||||
|
||||
// Optional MCP enhancements
|
||||
mcp_analysis: executeMcpDiscovery()
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,555 @@
|
||||
---
|
||||
name: task-generate-tdd
|
||||
description: Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation
|
||||
argument-hint: "--session WFS-session-id [--agent]"
|
||||
allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
|
||||
---
|
||||
|
||||
# TDD Task Generation Command
|
||||
|
||||
## Overview
|
||||
Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
|
||||
|
||||
## Task Strategy & Philosophy
|
||||
|
||||
### Optimized Task Structure (Current)
|
||||
- **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)
|
||||
- **Benefits**:
|
||||
- 70% reduction in task management overhead
|
||||
- Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
|
||||
- Simpler dependency management
|
||||
- Maintains TDD rigor through internal phase structure
|
||||
|
||||
**Previous Approach** (Deprecated):
|
||||
- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
|
||||
- 5 features = 15 tasks with complex dependency chains
|
||||
- High context switching cost between phases
|
||||
|
||||
### 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 10 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 >10 tasks needed, break project into multiple TDD workflow sessions
|
||||
|
||||
### TDD Cycle Mapping
|
||||
- **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
|
||||
- **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
|
||||
- **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary
|
||||
|
||||
### Core Principles
|
||||
- **TDD-First**: Every feature starts with a failing test (Red phase)
|
||||
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
|
||||
- **Phase-Explicit**: Internal phases clearly marked in flow_control.implementation_approach
|
||||
- **Task Merging**: Prefer single task per feature over decomposition
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
- **Artifact-Aware**: Integrates brainstorming outputs
|
||||
- **Memory-First**: Reuse loaded documents from memory
|
||||
- **Context-Aware**: Analyzes existing codebase and test patterns
|
||||
- **Iterative Green Phase**: Auto-diagnose and fix test failures with Gemini + optional Codex
|
||||
- **Safety-First**: Auto-revert on max iterations to prevent broken state
|
||||
|
||||
## Core Responsibilities
|
||||
- Parse analysis results and identify testable features
|
||||
- Generate feature-complete tasks with internal TDD cycles (1 task per simple feature)
|
||||
- Apply task merging strategy by default, create subtasks only when complexity requires
|
||||
- Generate IMPL_PLAN.md with TDD Implementation Tasks section
|
||||
- Generate TODO_LIST.md with internal TDD phase indicators
|
||||
- Update session state for TDD execution with task count compliance
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Input Validation & Discovery
|
||||
**Memory-First Rule**: Skip file loading if documents already in conversation memory
|
||||
|
||||
1. **Session Validation**
|
||||
- If session metadata in memory → Skip loading
|
||||
- Else: Load `.workflow/{session_id}/workflow-session.json`
|
||||
|
||||
2. **Conflict Resolution Check** (NEW - Priority Input)
|
||||
- If CONFLICT_RESOLUTION.md exists → Load selected strategies
|
||||
- Else: Skip to brainstorming artifacts
|
||||
- Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md`
|
||||
|
||||
3. **Artifact Discovery**
|
||||
- If artifact inventory in memory → Skip scanning
|
||||
- Else: Scan `.workflow/{session_id}/.brainstorming/` directory
|
||||
- Detect: role analysis documents, guidance-specification.md, role analyses
|
||||
|
||||
4. **Context Package Loading**
|
||||
- Load `.workflow/{session_id}/.process/context-package.json`
|
||||
- Load `.workflow/{session_id}/.process/test-context-package.json` (if exists)
|
||||
|
||||
### Phase 2: TDD Task JSON Generation
|
||||
|
||||
**Input Sources** (priority order):
|
||||
1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies
|
||||
2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.)
|
||||
3. **Context Package**: `.process/context-package.json` - Project structure and requirements
|
||||
4. **Test Context**: `.process/test-context-package.json` - Existing test patterns
|
||||
|
||||
**TDD Task Structure includes**:
|
||||
- Feature list with testable requirements
|
||||
- Test cases for Red phase
|
||||
- Implementation requirements for Green phase (with test-fix cycle)
|
||||
- Refactoring opportunities
|
||||
- Task dependencies and execution order
|
||||
- Conflict resolution decisions (if applicable)
|
||||
|
||||
### Phase 3: Task JSON & IMPL_PLAN.md Generation
|
||||
|
||||
#### Task Structure (Feature-Complete with Internal TDD)
|
||||
For each feature, generate task(s) with ID format:
|
||||
- **IMPL-N** - Single task containing complete TDD cycle (Red-Green-Refactor)
|
||||
- **IMPL-N.M** - Sub-tasks only when feature is complex (>2500 lines or technical blocking)
|
||||
|
||||
**Task Dependency Rules**:
|
||||
- **Sequential features**: IMPL-2 depends_on ["IMPL-1"] if Feature 2 needs Feature 1
|
||||
- **Independent features**: No dependencies, can execute in parallel
|
||||
- **Complex features**: IMPL-N.2 depends_on ["IMPL-N.1"] for subtask ordering
|
||||
|
||||
**Agent Assignment**:
|
||||
- **All IMPL tasks** → `@code-developer` (handles full TDD cycle)
|
||||
- Agent executes Red, Green, Refactor phases sequentially within task
|
||||
|
||||
**Meta Fields**:
|
||||
- `meta.type`: "feature" (TDD-driven feature implementation)
|
||||
- `meta.agent`: "@code-developer"
|
||||
- `meta.tdd_workflow`: true (enables TDD-specific flow)
|
||||
- `meta.tdd_phase`: Not used (phases are in flow_control.implementation_approach)
|
||||
- `meta.max_iterations`: 3 (for Green phase test-fix cycle)
|
||||
- `meta.use_codex`: false (manual fixes by default)
|
||||
|
||||
#### Task JSON Structure Reference
|
||||
|
||||
**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N", // Task identifier
|
||||
"title": "Feature description with TDD", // Human-readable title
|
||||
"status": "pending", // pending | in_progress | completed | container
|
||||
"context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
|
||||
"meta": {
|
||||
"type": "feature", // Task type
|
||||
"agent": "@code-developer", // Assigned agent
|
||||
"tdd_workflow": true, // REQUIRED: Enables TDD flow
|
||||
"max_iterations": 3, // Green phase test-fix cycle limit
|
||||
"use_codex": false // false=manual fixes, true=Codex automated fixes
|
||||
},
|
||||
"context": {
|
||||
"requirements": [ // Feature requirements with TDD phases
|
||||
"Feature description",
|
||||
"Red: Test scenarios to write",
|
||||
"Green: Implementation approach with test-fix cycle",
|
||||
"Refactor: Code quality improvements"
|
||||
],
|
||||
"tdd_cycles": [ // OPTIONAL: Detailed test cycles
|
||||
{
|
||||
"cycle": 1,
|
||||
"feature": "Specific functionality",
|
||||
"test_focus": "What to test",
|
||||
"expected_failure": "Why test should fail initially"
|
||||
}
|
||||
],
|
||||
"focus_paths": ["D:\\project\\src\\path", "./tests/path"], // Absolute or clear relative paths from project root
|
||||
"acceptance": [ // Success criteria
|
||||
"All tests pass (Red → Green)",
|
||||
"Code refactored (Refactor complete)",
|
||||
"Test coverage ≥80%"
|
||||
],
|
||||
"depends_on": [] // Task dependencies
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [ // OPTIONAL: Pre-execution checks
|
||||
{
|
||||
"step": "check_test_framework",
|
||||
"action": "Verify test framework",
|
||||
"command": "bash(npm list jest)",
|
||||
"output_to": "test_framework_info",
|
||||
"on_error": "warn"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [ // REQUIRED: 3 TDD phases
|
||||
{
|
||||
"step": 1,
|
||||
"title": "RED Phase: Write failing tests",
|
||||
"tdd_phase": "red", // REQUIRED: Phase identifier
|
||||
"description": "Write comprehensive failing tests",
|
||||
"modification_points": ["Files/changes to make"],
|
||||
"logic_flow": ["Step-by-step process"],
|
||||
"acceptance": ["Phase success criteria"],
|
||||
"depends_on": [],
|
||||
"output": "failing_tests"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "GREEN Phase: Implement to pass tests",
|
||||
"tdd_phase": "green", // REQUIRED: Phase identifier
|
||||
"description": "Minimal implementation with test-fix cycle",
|
||||
"modification_points": ["Implementation files"],
|
||||
"logic_flow": [
|
||||
"Implement minimal code",
|
||||
"Run tests",
|
||||
"If fail → Enter iteration loop (max 3):",
|
||||
" 1. Extract failure messages",
|
||||
" 2. Gemini bug-fix diagnosis",
|
||||
" 3. Apply fixes",
|
||||
" 4. Rerun tests",
|
||||
"If max_iterations → Auto-revert"
|
||||
],
|
||||
"acceptance": ["All tests pass"],
|
||||
"command": "bash(npm test -- tests/path/)",
|
||||
"depends_on": [1],
|
||||
"output": "passing_implementation"
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"title": "REFACTOR Phase: Improve code quality",
|
||||
"tdd_phase": "refactor", // REQUIRED: Phase identifier
|
||||
"description": "Refactor while keeping tests green",
|
||||
"modification_points": ["Quality improvements"],
|
||||
"logic_flow": ["Incremental refactoring with test verification"],
|
||||
"acceptance": ["Tests still pass", "Code quality improved"],
|
||||
"command": "bash(npm run lint && npm test)",
|
||||
"depends_on": [2],
|
||||
"output": "refactored_implementation"
|
||||
}
|
||||
],
|
||||
"post_completion": [ // OPTIONAL: Final verification
|
||||
{
|
||||
"step": "verify_full_tdd_cycle",
|
||||
"action": "Confirm complete TDD cycle",
|
||||
"command": "bash(npm test && echo 'TDD complete')",
|
||||
"output_to": "final_validation",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"error_handling": { // OPTIONAL: Error recovery
|
||||
"green_phase_max_iterations": {
|
||||
"action": "revert_all_changes",
|
||||
"commands": ["bash(git reset --hard HEAD)"],
|
||||
"report": "Generate failure report"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key JSON Fields Summary**:
|
||||
- `meta.tdd_workflow`: Must be `true`
|
||||
- `meta.max_iterations`: Green phase fix cycle limit (default: 3)
|
||||
- `meta.use_codex`: Automated fixes (false=manual, true=Codex)
|
||||
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor"
|
||||
- `context.tdd_cycles`: Optional detailed test cycle specifications
|
||||
- `context.parent`: Required for subtasks (IMPL-N.M)
|
||||
|
||||
#### IMPL_PLAN.md Structure
|
||||
|
||||
Generate IMPL_PLAN.md with 8-section structure:
|
||||
|
||||
**Frontmatter** (required fields):
|
||||
```yaml
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements" | "File: path"
|
||||
conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md # if exists
|
||||
context_package: .workflow/{session-id}/.process/context-package.json
|
||||
context_package_path: .workflow/{session-id}/.process/context-package.json
|
||||
test_context: .workflow/{session-id}/.process/test-context-package.json # if exists
|
||||
workflow_type: "tdd"
|
||||
verification_history:
|
||||
conflict_resolution: "executed | skipped" # based on conflict_risk
|
||||
action_plan_verify: "pending"
|
||||
phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
|
||||
feature_count: N
|
||||
task_count: N # ≤10 total
|
||||
task_breakdown:
|
||||
simple_features: K
|
||||
complex_features: L
|
||||
total_subtasks: M
|
||||
tdd_workflow: true
|
||||
---
|
||||
```
|
||||
|
||||
**8 Sections Structure**:
|
||||
|
||||
```markdown
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## 1. Summary
|
||||
- Core requirements and objectives (2-3 paragraphs)
|
||||
- TDD-specific technical approach
|
||||
|
||||
## 2. Context Analysis
|
||||
- CCW Workflow Context (Phase progression, Quality gates)
|
||||
- Context Package Summary (Focus paths, Test context)
|
||||
- Project Profile (Type, Scale, Tech Stack, Timeline)
|
||||
- Module Structure (Directory tree)
|
||||
- Dependencies (Primary, Testing, Development)
|
||||
- Patterns & Conventions
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
- Artifact Usage Strategy
|
||||
- CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
|
||||
- role analysis documents (primary reference)
|
||||
- test-context-package.json (test patterns)
|
||||
- context-package.json (smart context)
|
||||
- Artifact Priority in Development
|
||||
|
||||
## 4. Implementation Strategy
|
||||
- Execution Strategy (TDD Cycles: Red-Green-Refactor)
|
||||
- Architectural Approach
|
||||
- Key Dependencies (Task dependency graph)
|
||||
- Testing Strategy (Coverage targets, Quality gates)
|
||||
|
||||
## 5. TDD Implementation Tasks
|
||||
- Feature-by-Feature TDD Tasks
|
||||
- Each task: IMPL-N with internal Red → Green → Refactor
|
||||
- Dependencies and complexity metrics
|
||||
- Complex Feature Examples (when subtasks needed)
|
||||
- TDD Task Breakdown Summary
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
- Execution Strategy (feature-by-feature sequential)
|
||||
- Phase breakdown (Phase 1, Phase 2, etc.)
|
||||
- Resource Requirements (Team, Dependencies, Infrastructure)
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
- Risk table (Risk, Impact, Probability, Mitigation, Owner)
|
||||
- Critical Risks (TDD-specific)
|
||||
- Monitoring Strategy
|
||||
|
||||
## 8. Success Criteria
|
||||
- Functional Completeness
|
||||
- Technical Quality (Test coverage ≥80%)
|
||||
- Operational Readiness
|
||||
- TDD Compliance
|
||||
```
|
||||
|
||||
### Phase 4: TODO_LIST.md Generation
|
||||
|
||||
Generate task list with internal TDD phase indicators:
|
||||
|
||||
**For Simple Features (1 task per feature)**:
|
||||
```markdown
|
||||
## TDD Implementation Tasks
|
||||
|
||||
### Feature 1: {Feature Name}
|
||||
- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- Dependencies: None
|
||||
|
||||
### Feature 2: {Feature Name}
|
||||
- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- Dependencies: IMPL-1
|
||||
```
|
||||
|
||||
**For Complex Features (with subtasks)**:
|
||||
```markdown
|
||||
### Feature 3: {Complex Feature Name}
|
||||
▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
|
||||
- [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
|
||||
- Internal phases: Red → Green → Refactor
|
||||
- Dependencies: IMPL-3.1
|
||||
```
|
||||
|
||||
**Status Legend**:
|
||||
```markdown
|
||||
## Status Legend
|
||||
- ▸ = Container task (has subtasks)
|
||||
- [ ] = Pending task
|
||||
- [x] = Completed task
|
||||
- Red = Write failing tests
|
||||
- Green = Implement to pass tests (with test-fix cycle)
|
||||
- Refactor = Improve code quality
|
||||
```
|
||||
|
||||
### Phase 5: Session State Update
|
||||
|
||||
Update workflow-session.json with TDD metadata:
|
||||
```json
|
||||
{
|
||||
"workflow_type": "tdd",
|
||||
"feature_count": 5,
|
||||
"task_count": 5,
|
||||
"task_breakdown": {
|
||||
"simple_features": 4,
|
||||
"complex_features": 1,
|
||||
"total_subtasks": 2
|
||||
},
|
||||
"tdd_workflow": true,
|
||||
"task_limit_compliance": true
|
||||
}
|
||||
```
|
||||
|
||||
**Task Count Calculation**:
|
||||
- **Simple features**: 1 task each (IMPL-N with internal TDD cycle)
|
||||
- **Complex features**: 1 container + M subtasks (IMPL-N + IMPL-N.M)
|
||||
- **Total**: Simple feature count + Complex feature subtask count
|
||||
- **Example**: 4 simple + 1 complex (with 2 subtasks) = 6 total tasks (not 15)
|
||||
|
||||
## Output Files Structure
|
||||
```
|
||||
.workflow/{session-id}/
|
||||
├── 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.md # Conflict resolution strategies (if conflict_risk ≥ medium)
|
||||
├── test-context-package.json # Test coverage analysis
|
||||
├── context-package.json # Input from context-gather
|
||||
├── context_package_path # Path to smart context package
|
||||
└── green-fix-iteration-*.md # Fix logs from Green phase test-fix cycles
|
||||
```
|
||||
|
||||
**File Count**:
|
||||
- **Old approach**: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5)
|
||||
- **New approach**: 5 features = 5 task JSON files (IMPL-N × 5)
|
||||
- **Complex feature**: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M)
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Task Completeness
|
||||
- Every IMPL-N must contain complete TDD workflow in `flow_control.implementation_approach`
|
||||
- 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 10 total tasks (simple + subtasks)
|
||||
- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
|
||||
- Re-scope requirements if >10 tasks needed
|
||||
|
||||
### TDD Workflow Validation
|
||||
- `meta.tdd_workflow` must be true
|
||||
- `flow_control.implementation_approach` must have exactly 3 steps
|
||||
- Each step must have `tdd_phase` field ("red", "green", or "refactor")
|
||||
- Green phase step must include test-fix cycle logic
|
||||
- `meta.max_iterations` must be present (default: 3)
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Input Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Session not found | Invalid session ID | Verify session exists |
|
||||
| Context missing | Incomplete planning | Run context-gather first |
|
||||
|
||||
### TDD Generation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features |
|
||||
| Missing test framework | No test config | Configure testing first |
|
||||
| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
|
||||
| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:tdd-plan` (Phase 4)
|
||||
- **Calls**: Gemini CLI for TDD breakdown
|
||||
- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
# Manual mode (default)
|
||||
/workflow:tools:task-generate-tdd --session WFS-auth
|
||||
|
||||
# Agent mode (autonomous task generation)
|
||||
/workflow:tools:task-generate-tdd --session WFS-auth --agent
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
```
|
||||
TDD task generation complete for session: WFS-auth
|
||||
|
||||
Features analyzed: 5
|
||||
Total tasks: 5 (1 task per feature with internal TDD cycles)
|
||||
|
||||
Task breakdown:
|
||||
- Simple features: 4 tasks (IMPL-1 to IMPL-4)
|
||||
- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
|
||||
- Total task count: 6 (within 10-task limit)
|
||||
|
||||
Structure:
|
||||
- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
|
||||
- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
|
||||
- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
|
||||
- IMPL-4: Role Management (Internal: Red → Green → Refactor)
|
||||
- IMPL-5: Payment System (Container)
|
||||
- IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
|
||||
- IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
|
||||
|
||||
Plans generated:
|
||||
- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
|
||||
- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
|
||||
|
||||
TDD Configuration:
|
||||
- Each task contains complete Red-Green-Refactor cycle
|
||||
- Green phase includes test-fix cycle (max 3 iterations)
|
||||
- Auto-revert on max iterations reached
|
||||
|
||||
Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
|
||||
```
|
||||
|
||||
## Test Coverage Analysis Integration
|
||||
|
||||
The TDD workflow includes test coverage analysis (via `/workflow:tools:test-context-gather`) to:
|
||||
- Detect existing test patterns and conventions
|
||||
- Identify current test coverage gaps
|
||||
- Discover test framework and configuration
|
||||
- Enable integration with existing tests
|
||||
|
||||
This makes TDD workflow context-aware instead of assuming greenfield scenarios.
|
||||
|
||||
## Iterative Green Phase with Test-Fix Cycle
|
||||
|
||||
IMPL (Green phase) tasks include automatic test-fix cycle:
|
||||
|
||||
**Process Flow**:
|
||||
1. **Initial Implementation**: Write minimal code to pass tests
|
||||
2. **Test Execution**: Run test suite
|
||||
3. **Success Path**: Tests pass → Complete task
|
||||
4. **Failure Path**: Tests fail → Enter iterative fix cycle:
|
||||
- **Gemini Diagnosis**: Analyze failures with bug-fix template
|
||||
- **Fix Application**: Manual (default) or Codex (if meta.use_codex=true)
|
||||
- **Retest**: Verify fix resolves failures
|
||||
- **Repeat**: Up to max_iterations (default: 3)
|
||||
5. **Safety Net**: Auto-revert all changes if max iterations reached
|
||||
|
||||
**Key Benefits**:
|
||||
- Faster feedback loop within Green phase
|
||||
- Autonomous recovery from initial implementation errors
|
||||
- Systematic debugging with Gemini's bug-fix template
|
||||
- Safe rollback prevents broken TDD state
|
||||
|
||||
## Configuration Options
|
||||
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
|
||||
- **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:tdd-plan` - Orchestrates TDD workflow planning (6 phases)
|
||||
- `/workflow:tools:test-context-gather` - Analyzes test coverage
|
||||
- `/workflow:execute` - Executes TDD tasks in order
|
||||
- `/workflow:tdd-verify` - Verifies TDD compliance
|
||||
- `/workflow:test-gen` - Post-implementation test generation
|
||||
@@ -0,0 +1,815 @@
|
||||
---
|
||||
name: task-generate
|
||||
description: Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration
|
||||
argument-hint: "--session WFS-session-id [--cli-execute]"
|
||||
examples:
|
||||
- /workflow:tools:task-generate --session WFS-auth
|
||||
- /workflow:tools:task-generate --session WFS-auth --cli-execute
|
||||
---
|
||||
|
||||
# Task Generation Command
|
||||
|
||||
## 1. Overview
|
||||
This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
|
||||
|
||||
## 2. Execution Modes
|
||||
|
||||
This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
|
||||
|
||||
### Agent Mode (Default)
|
||||
In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
|
||||
- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
|
||||
- **Execution**: Agent reads these fields and performs the implementation autonomously
|
||||
- **Context Loading**: Agent loads context via `pre_analysis` steps
|
||||
- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
|
||||
- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
|
||||
- **Use Case**: Standard implementation tasks where agent capability is sufficient
|
||||
|
||||
### CLI Execute Mode (`--cli-execute`)
|
||||
When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
|
||||
- **Step Structure**: Includes all default fields PLUS a `command` field
|
||||
- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
|
||||
- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
|
||||
- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
|
||||
- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
|
||||
- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
|
||||
|
||||
## 3. Core Principles
|
||||
This command is built on a set of core principles to ensure efficient and reliable task generation.
|
||||
|
||||
- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
|
||||
- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
|
||||
- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
- **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
|
||||
- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
|
||||
- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
|
||||
- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
|
||||
- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
|
||||
|
||||
## 4. Execution Flow
|
||||
The command follows a streamlined, three-step process to convert analysis into executable tasks.
|
||||
|
||||
### Step 1: Input & Discovery
|
||||
The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
|
||||
1. **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`.
|
||||
2. **Context Package Loading** (primary source): Reads `.workflow/{session_id}/.process/context-package.json` for smart context and artifact catalog.
|
||||
3. **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
|
||||
4. **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
|
||||
|
||||
### Step 2: Task Decomposition & Grouping
|
||||
Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
|
||||
1. **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies.
|
||||
2. **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`.
|
||||
3. **Task Grouping**:
|
||||
* Tasks with the **same signature** are candidates for merging, as they operate on the same context.
|
||||
* Tasks with **different signatures** and no dependencies are grouped for parallel execution.
|
||||
* Tasks with `depends_on` relationships are marked for sequential execution.
|
||||
4. **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field.
|
||||
|
||||
### Step 3: Output Generation
|
||||
Finally, the command generates all the necessary output files.
|
||||
1. **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
|
||||
2. **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
|
||||
3. **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
|
||||
4. **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
|
||||
|
||||
## 5. Task Decomposition Strategy
|
||||
The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
|
||||
|
||||
### Core Principles
|
||||
- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
|
||||
- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
|
||||
|
||||
### Context Analysis for Task Grouping
|
||||
The decision to merge or decompose is based on analyzing context indicators:
|
||||
|
||||
1. **Shared Context Indicators (→ Merge)**:
|
||||
* Identical `focus_paths` (working on the same modules/files).
|
||||
* Same tech stack and dependencies.
|
||||
* Identical `context.artifacts` references.
|
||||
* A sequential logic flow within the same feature.
|
||||
* Shared test fixtures or setup.
|
||||
|
||||
2. **Independent Context Indicators (→ Decompose)**:
|
||||
* Different `focus_paths` (separate modules).
|
||||
* Different tech stacks (e.g., frontend vs. backend).
|
||||
* Different `context.artifacts` (using different brainstorming outputs).
|
||||
* No shared dependencies.
|
||||
* Can be tested independently.
|
||||
|
||||
**Decomposition is only performed when**:
|
||||
- Tasks have different contexts and no shared dependencies (enabling parallel execution).
|
||||
- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
|
||||
- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
|
||||
|
||||
### Context Signature Algorithm
|
||||
To automate grouping, a `context_signature` is computed for each task.
|
||||
|
||||
```javascript
|
||||
// Compute context signature for task grouping
|
||||
function computeContextSignature(task) {
|
||||
const focusPathsStr = task.context.focus_paths.sort().join('|');
|
||||
const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
|
||||
const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
|
||||
|
||||
return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
|
||||
}
|
||||
```
|
||||
|
||||
### Execution Group Assignment
|
||||
Tasks are assigned to execution groups based on their signatures and dependencies.
|
||||
|
||||
```javascript
|
||||
// Group tasks by context signature
|
||||
function groupTasksByContext(tasks) {
|
||||
const groups = {};
|
||||
|
||||
tasks.forEach(task => {
|
||||
const signature = computeContextSignature(task);
|
||||
if (!groups[signature]) {
|
||||
groups[signature] = [];
|
||||
}
|
||||
groups[signature].push(task);
|
||||
});
|
||||
|
||||
return groups;
|
||||
}
|
||||
|
||||
// Assign execution groups for parallel tasks
|
||||
function assignExecutionGroups(tasks) {
|
||||
const contextGroups = groupTasksByContext(tasks);
|
||||
|
||||
Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
|
||||
if (groupTasks.length === 1) {
|
||||
const task = groupTasks[0];
|
||||
// Single task with unique context
|
||||
if (!task.context.depends_on || task.context.depends_on.length === 0) {
|
||||
task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
|
||||
} else {
|
||||
task.meta.execution_group = null; // Sequential task
|
||||
}
|
||||
} else {
|
||||
// Multiple tasks with same context → Should be merged
|
||||
console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
|
||||
// Merge tasks into single task
|
||||
return mergeTasks(groupTasks);
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
**Task Limits**:
|
||||
- **Maximum 10 tasks** (hard limit).
|
||||
- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
|
||||
- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
|
||||
|
||||
## 6. Generated Outputs
|
||||
The command produces three key documents and a directory of task files.
|
||||
|
||||
### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
|
||||
This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N[.M]",
|
||||
"title": "Descriptive task name",
|
||||
"status": "pending|active|completed|blocked|container",
|
||||
"context_package_path": ".workflow/WFS-[session]/.process/context-package.json",
|
||||
"meta": {
|
||||
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
|
||||
"agent": "@code-developer|@test-fix-agent|@universal-executor",
|
||||
"execution_group": "group-id|null",
|
||||
"context_signature": "hash-of-focus_paths-and-artifacts"
|
||||
},
|
||||
"context": {
|
||||
"requirements": ["Clear requirement from analysis"],
|
||||
"focus_paths": ["D:\\project\\src\\module\\path", "./tests/module/path"],
|
||||
"acceptance": ["Measurable acceptance criterion"],
|
||||
"parent": "IMPL-N",
|
||||
"depends_on": ["IMPL-N.M"],
|
||||
"inherited": {"shared_patterns": [], "common_dependencies": []},
|
||||
"shared_context": {"tech_stack": [], "conventions": []},
|
||||
"artifacts": [
|
||||
{
|
||||
"path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
|
||||
"priority": "highest",
|
||||
"usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
|
||||
},
|
||||
{
|
||||
"path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
|
||||
"priority": "high",
|
||||
"usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place"
|
||||
}
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_context_package",
|
||||
"action": "Load context package for artifact paths",
|
||||
"note": "Context package path is now at top-level field: context_package_path",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})"
|
||||
],
|
||||
"output_to": "context_package",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_role_analysis_artifacts",
|
||||
"action": "Load role analyses from context-package.json (supports multiple files per role)",
|
||||
"note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "role_analysis_artifacts",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "load_planning_context",
|
||||
"action": "Load plan-generated context intelligence with resolved conflicts",
|
||||
"note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)"
|
||||
],
|
||||
"output_to": "planning_context",
|
||||
"on_error": "fail",
|
||||
"usage_guidance": {
|
||||
"context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)",
|
||||
"guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)"
|
||||
}
|
||||
},
|
||||
{
|
||||
"step": "codebase_exploration",
|
||||
"action": "Explore codebase using native tools",
|
||||
"command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")",
|
||||
"output_to": "codebase_structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_task_patterns",
|
||||
"action": "Analyze existing code patterns and identify modification targets",
|
||||
"commands": [
|
||||
"bash(cd \"[focus_paths]\")",
|
||||
"bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
|
||||
],
|
||||
"output_to": "task_context_with_targets",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement task following role analyses and context",
|
||||
"description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.",
|
||||
"modification_points": [
|
||||
"Apply requirements and design specs from role analysis documents",
|
||||
"Use enhancements and clarifications from synthesis phase",
|
||||
"Use finalized decisions from guidance-specification.md (includes resolved conflicts)",
|
||||
"Use context-package.json for focus paths and dependency resolution",
|
||||
"Consult specific role artifacts for implementation details when needed",
|
||||
"Integrate with existing patterns"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load role analyses (requirements, design, enhancements from synthesis)",
|
||||
"Load guidance-specification.md (finalized decisions with resolved conflicts if any)",
|
||||
"Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)",
|
||||
"Extract requirements and design decisions from role documents",
|
||||
"Review synthesis enhancements and clarifications",
|
||||
"Use finalized decisions (conflicts already resolved if applicable)",
|
||||
"Identify modification targets using context package",
|
||||
"Implement following role requirements and design specs",
|
||||
"Consult role artifacts for detailed specifications when needed",
|
||||
"Validate against acceptance criteria"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["file:function:lines"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2. IMPL_PLAN.md Structure
|
||||
This document provides a high-level overview of the entire implementation plan.
|
||||
|
||||
```markdown
|
||||
---
|
||||
identifier: WFS-{session-id}
|
||||
source: "User requirements" | "File: path" | "Issue: ISS-001"
|
||||
role_analyses: .workflow/{session-id}/.brainstorming/[role]/analysis*.md
|
||||
artifacts: .workflow/{session-id}/.brainstorming/
|
||||
context_package: .workflow/{session-id}/.process/context-package.json # CCW smart context
|
||||
guidance_specification: .workflow/{session-id}/.brainstorming/guidance-specification.md # Finalized decisions with resolved conflicts
|
||||
workflow_type: "standard | tdd | design" # Indicates execution model
|
||||
verification_history: # CCW quality gates
|
||||
synthesis_clarify: "passed | skipped | pending" # Brainstorm phase clarification
|
||||
action_plan_verify: "pending"
|
||||
conflict_resolution: "resolved | none | low" # Status from context-package.json
|
||||
phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning" # CCW workflow phases
|
||||
---
|
||||
|
||||
# Implementation Plan: {Project Title}
|
||||
|
||||
## 1. Summary
|
||||
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
|
||||
|
||||
**Core Objectives**:
|
||||
- [Key objective 1]
|
||||
- [Key objective 2]
|
||||
|
||||
**Technical Approach**:
|
||||
- [High-level approach]
|
||||
|
||||
## 2. Context Analysis
|
||||
|
||||
### CCW Workflow Context
|
||||
**Phase Progression**:
|
||||
- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
|
||||
- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
|
||||
- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
|
||||
- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
|
||||
- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
|
||||
|
||||
**Quality Gates**:
|
||||
- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
|
||||
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
|
||||
|
||||
**Context Package Summary**:
|
||||
- **Focus Paths**: {list key directories from context-package.json}
|
||||
- **Key Files**: {list primary files for modification}
|
||||
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
|
||||
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
|
||||
|
||||
### Project Profile
|
||||
- **Type**: Greenfield/Enhancement/Refactor
|
||||
- **Scale**: User count, data volume, complexity
|
||||
- **Tech Stack**: Primary technologies
|
||||
- **Timeline**: Duration and milestones
|
||||
|
||||
### Module Structure
|
||||
'''
|
||||
[Directory tree showing key modules]
|
||||
'''
|
||||
|
||||
### Dependencies
|
||||
**Primary**: [Core libraries and frameworks]
|
||||
**APIs**: [External services]
|
||||
**Development**: [Testing, linting, CI/CD tools]
|
||||
|
||||
### Patterns & Conventions
|
||||
- **Architecture**: [Key patterns like DI, Event-Driven]
|
||||
- **Component Design**: [Design patterns]
|
||||
- **State Management**: [State strategy]
|
||||
- **Code Style**: [Naming, TypeScript coverage]
|
||||
|
||||
## 3. Brainstorming Artifacts Reference
|
||||
|
||||
### Artifact Usage Strategy
|
||||
**Primary Reference (Role Analyses)**:
|
||||
- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
|
||||
- **When**: Every task references relevant role analyses for requirements and design decisions
|
||||
- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
|
||||
- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
|
||||
- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
|
||||
|
||||
**Context Intelligence (context-package.json)**:
|
||||
- **What**: Smart context gathered by CCW's context-gather phase
|
||||
- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
|
||||
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
|
||||
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
|
||||
|
||||
**Conflict Resolution Status**:
|
||||
- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
|
||||
- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
|
||||
- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
|
||||
- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
|
||||
- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
|
||||
|
||||
### Role Analysis Documents (Highest Priority)
|
||||
Role analyses provide specialized perspectives on the implementation:
|
||||
- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
|
||||
- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
|
||||
- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
|
||||
- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
|
||||
- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
|
||||
- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
|
||||
|
||||
### Supporting Artifacts (Reference)
|
||||
- **topic-framework.md**: Role-specific discussion points and analysis framework
|
||||
|
||||
**Artifact Priority in Development**:
|
||||
1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
|
||||
2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
|
||||
3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
|
||||
|
||||
## 4. Implementation Strategy
|
||||
|
||||
### Execution Strategy
|
||||
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
|
||||
|
||||
**Rationale**: [Why this execution model fits the project]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [List independent workstreams]
|
||||
|
||||
**Serialization Requirements**:
|
||||
- [List critical dependencies]
|
||||
|
||||
### Architectural Approach
|
||||
**Key Architecture Decisions**:
|
||||
- [ADR references from role analyses]
|
||||
- [Justification for architecture patterns]
|
||||
|
||||
**Integration Strategy**:
|
||||
- [How modules communicate]
|
||||
- [State management approach]
|
||||
|
||||
### Key Dependencies
|
||||
**Task Dependency Graph**:
|
||||
'''
|
||||
[High-level dependency visualization]
|
||||
'''
|
||||
|
||||
**Critical Path**: [Identify bottleneck tasks]
|
||||
|
||||
### Testing Strategy
|
||||
**Testing Approach**:
|
||||
- Unit testing: [Tools, scope]
|
||||
- Integration testing: [Key integration points]
|
||||
- E2E testing: [Critical user flows]
|
||||
|
||||
**Coverage Targets**:
|
||||
- Lines: ≥70%
|
||||
- Functions: ≥70%
|
||||
- Branches: ≥65%
|
||||
|
||||
**Quality Gates**:
|
||||
- [CI/CD gates]
|
||||
- [Performance budgets]
|
||||
|
||||
## 5. Task Breakdown Summary
|
||||
|
||||
### Task Count
|
||||
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
|
||||
|
||||
### Task Structure
|
||||
- **IMPL-1**: [Main task title]
|
||||
- **IMPL-2**: [Main task title]
|
||||
...
|
||||
|
||||
### Complexity Assessment
|
||||
- **High**: [List with rationale]
|
||||
- **Medium**: [List]
|
||||
- **Low**: [List]
|
||||
|
||||
### Dependencies
|
||||
[Reference Section 4.3 for dependency graph]
|
||||
|
||||
**Parallelization Opportunities**:
|
||||
- [Specific task groups that can run in parallel]
|
||||
|
||||
## 6. Implementation Plan (Detailed Phased Breakdown)
|
||||
|
||||
### Execution Strategy
|
||||
|
||||
**Phase 1 (Weeks 1-2): [Phase Name]**
|
||||
- **Tasks**: IMPL-1, IMPL-2
|
||||
- **Deliverables**:
|
||||
- [Specific deliverable 1]
|
||||
- [Specific deliverable 2]
|
||||
- **Success Criteria**:
|
||||
- [Measurable criterion]
|
||||
|
||||
**Phase 2 (Weeks 3-N): [Phase Name]**
|
||||
...
|
||||
|
||||
### Resource Requirements
|
||||
|
||||
**Development Team**:
|
||||
- [Team composition and skills]
|
||||
|
||||
**External Dependencies**:
|
||||
- [Third-party services, APIs]
|
||||
|
||||
**Infrastructure**:
|
||||
- [Development, staging, production environments]
|
||||
|
||||
## 7. Risk Assessment & Mitigation
|
||||
|
||||
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|
||||
|------|--------|-------------|---------------------|-------|
|
||||
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
|
||||
|
||||
**Critical Risks** (High impact + High probability):
|
||||
- [Risk 1]: [Detailed mitigation plan]
|
||||
|
||||
**Monitoring Strategy**:
|
||||
- [How risks will be monitored]
|
||||
|
||||
## 8. Success Criteria
|
||||
|
||||
**Functional Completeness**:
|
||||
- [ ] All requirements from role analysis documents implemented
|
||||
- [ ] All acceptance criteria from task.json files met
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] Test coverage ≥70%
|
||||
- [ ] Bundle size within budget
|
||||
- [ ] Performance targets met
|
||||
|
||||
**Operational Readiness**:
|
||||
- [ ] CI/CD pipeline operational
|
||||
- [ ] Monitoring and logging configured
|
||||
- [ ] Documentation complete
|
||||
|
||||
**Business Metrics**:
|
||||
- [ ] [Key business metrics from role analyses]
|
||||
```
|
||||
|
||||
### 6.3. TODO_LIST.md Structure
|
||||
A simple Markdown file for tracking the status of each task.
|
||||
|
||||
```markdown
|
||||
# Tasks: [Session Topic]
|
||||
|
||||
## Task Progress
|
||||
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
|
||||
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
|
||||
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
|
||||
|
||||
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
|
||||
|
||||
## Status Legend
|
||||
- `▸` = Container task (has subtasks)
|
||||
- `- [ ]` = Pending leaf task
|
||||
- `- [x]` = Completed leaf task
|
||||
- Maximum 2 levels: Main tasks and subtasks only
|
||||
```
|
||||
|
||||
### 6.4. Output Files Diagram
|
||||
The command organizes outputs into a standard directory structure.
|
||||
```
|
||||
.workflow/{session-id}/
|
||||
├── IMPL_PLAN.md # Implementation plan
|
||||
├── TODO_LIST.md # Progress tracking
|
||||
├── .task/
|
||||
│ ├── IMPL-1.json # Container task
|
||||
│ ├── IMPL-1.1.json # Leaf task with flow_control
|
||||
│ └── IMPL-1.2.json # Leaf task with flow_control
|
||||
├── .brainstorming # Input artifacts from brainstorm + synthesis
|
||||
│ ├── guidance-specification.md # Finalized decisions (with resolved conflicts if any)
|
||||
│ └── {role}/analysis*.md # Role analyses (enhanced by synthesis, with resolved conflicts if any)
|
||||
└── .process/
|
||||
└── context-package.json # Input from context-gather (smart context + conflict_risk status)
|
||||
```
|
||||
|
||||
## 7. Artifact Integration
|
||||
The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
|
||||
|
||||
#### Artifact Priority
|
||||
1. **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
|
||||
2. **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
|
||||
3. **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
|
||||
|
||||
#### Artifact-Task Mapping
|
||||
Artifacts are mapped to tasks based on their relevance to the task's domain.
|
||||
- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
|
||||
- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
|
||||
- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
|
||||
- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
|
||||
- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
|
||||
- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
|
||||
|
||||
This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
|
||||
|
||||
## 8. CLI Execute Mode Details
|
||||
When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
|
||||
|
||||
**Key Points**:
|
||||
- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
|
||||
- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
|
||||
- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
|
||||
|
||||
### Example 1: Agent Mode - Simple Task (Default, No Command)
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Implement user authentication module",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"context": {
|
||||
"depends_on": [],
|
||||
"focus_paths": ["src/auth"],
|
||||
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
|
||||
"acceptance": [
|
||||
"JWT token generation working",
|
||||
"Login and registration endpoints implemented",
|
||||
"Tests passing with >70% coverage"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_role_analyses",
|
||||
"action": "Load role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "role_analyses",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_context",
|
||||
"action": "Load context package for project structure",
|
||||
"commands": ["Read({{context_package_path}})"],
|
||||
"output_to": "context_pkg",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement JWT-based authentication",
|
||||
"description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns",
|
||||
"modification_points": [
|
||||
"Create auth service with JWT generation",
|
||||
"Implement login endpoint with credential validation",
|
||||
"Implement registration endpoint with user creation",
|
||||
"Add JWT middleware for route protection"
|
||||
],
|
||||
"logic_flow": [
|
||||
"User registers → validate input → hash password → create user",
|
||||
"User logs in → validate credentials → generate JWT → return token",
|
||||
"Protected routes → validate JWT → extract user → allow access"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "auth_implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: CLI Execute Mode - Single Codex Step
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Implement user authentication module",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"context": {
|
||||
"depends_on": [],
|
||||
"focus_paths": ["src/auth"],
|
||||
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
|
||||
"acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_role_analyses",
|
||||
"action": "Load role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "role_analyses",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Implement authentication with Codex",
|
||||
"description": "Create JWT-based authentication module",
|
||||
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
|
||||
"logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
|
||||
"depends_on": [],
|
||||
"output": "auth_implementation"
|
||||
}
|
||||
],
|
||||
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example 3: CLI Execute Mode - Multi-Step with Resume
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-003",
|
||||
"title": "Implement role-based access control",
|
||||
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
|
||||
"context": {
|
||||
"depends_on": ["IMPL-002"],
|
||||
"focus_paths": ["src/auth", "src/middleware"],
|
||||
"requirements": ["User roles and permissions", "Route protection middleware"],
|
||||
"acceptance": ["RBAC models created", "Middleware working", "Management API complete"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_context",
|
||||
"action": "Load context and role analyses from context-package.json",
|
||||
"commands": [
|
||||
"Read({{context_package_path}})",
|
||||
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
|
||||
"Read(each extracted path)"
|
||||
],
|
||||
"output_to": "full_context",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Create RBAC models",
|
||||
"description": "Define role and permission data models",
|
||||
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Define role model", "Define permission model", "Create migrations"],
|
||||
"logic_flow": ["Design schema", "Implement models", "Generate migrations"],
|
||||
"depends_on": [],
|
||||
"output": "rbac_models"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Implement RBAC middleware",
|
||||
"description": "Create route protection middleware using models from step 1",
|
||||
"command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
|
||||
"logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
|
||||
"depends_on": [1],
|
||||
"output": "rbac_middleware"
|
||||
},
|
||||
{
|
||||
"step": 3,
|
||||
"title": "Add role management API",
|
||||
"description": "Create CRUD endpoints for roles and permissions",
|
||||
"command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
|
||||
"modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
|
||||
"logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
|
||||
"depends_on": [2],
|
||||
"output": "role_management_api"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
"src/models/Role.ts",
|
||||
"src/models/Permission.ts",
|
||||
"src/middleware/rbac.ts",
|
||||
"src/routes/roles.ts"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Pattern Summary**:
|
||||
- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
|
||||
- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
|
||||
- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
|
||||
- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
|
||||
|
||||
## 9. Error Handling
|
||||
|
||||
### Input Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Session not found | Invalid session ID | Verify session exists |
|
||||
| Context missing | Incomplete planning | Run context-gather first |
|
||||
| Invalid format | Corrupted results | Regenerate analysis |
|
||||
|
||||
### Task Generation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Count exceeds limit | >10 tasks | Re-scope requirements |
|
||||
| Invalid structure | Missing fields | Fix analysis results |
|
||||
| Dependency cycle | Circular refs | Adjust dependencies |
|
||||
|
||||
### Artifact Integration Errors
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| Artifact not found | Missing output | Continue without artifacts |
|
||||
| Invalid format | Corrupted file | Skip artifact loading |
|
||||
| Path invalid | Moved/deleted | Update references |
|
||||
|
||||
## 10. Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:plan` (Phase 4)
|
||||
- **Calls**: None (terminal command)
|
||||
- **Followed By**: `/workflow:execute`, `/workflow:status`
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
/workflow:tools:task-generate --session WFS-auth
|
||||
```
|
||||
|
||||
## 11. Related Commands
|
||||
- `/workflow:plan` - Orchestrates entire planning
|
||||
- `/workflow:plan --cli-execute` - Planning with CLI execution mode
|
||||
- `/workflow:tools:context-gather` - Provides context package
|
||||
- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional)
|
||||
- `/workflow:execute` - Executes generated tasks
|
||||
@@ -0,0 +1,281 @@
|
||||
---
|
||||
name: tdd-coverage-analysis
|
||||
description: Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification
|
||||
argument-hint: "--session WFS-session-id"
|
||||
allowed-tools: Read(*), Write(*), Bash(*)
|
||||
---
|
||||
|
||||
# TDD Coverage Analysis Command
|
||||
|
||||
## Overview
|
||||
Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD workflow validation.
|
||||
|
||||
## Core Responsibilities
|
||||
- Extract test files from TEST tasks
|
||||
- Run test suite with coverage
|
||||
- Parse coverage metrics
|
||||
- Verify TDD cycle execution (Red -> Green -> Refactor)
|
||||
- Generate coverage and cycle reports
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Extract Test Tasks
|
||||
```bash
|
||||
find .workflow/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
|
||||
```
|
||||
|
||||
**Output**: List of test directories/files from all TEST tasks
|
||||
|
||||
### Phase 2: Run Test Suite
|
||||
```bash
|
||||
# Node.js/JavaScript
|
||||
npm test -- --coverage --json > .workflow/{session_id}/.process/test-results.json
|
||||
|
||||
# Python
|
||||
pytest --cov --json-report > .workflow/{session_id}/.process/test-results.json
|
||||
|
||||
# Other frameworks (detect from project)
|
||||
[test_command] --coverage --json-output .workflow/{session_id}/.process/test-results.json
|
||||
```
|
||||
|
||||
**Output**: test-results.json with coverage data
|
||||
|
||||
### Phase 3: Parse Coverage Data
|
||||
```bash
|
||||
jq '.coverage' .workflow/{session_id}/.process/test-results.json > .workflow/{session_id}/.process/coverage-report.json
|
||||
```
|
||||
|
||||
**Extract**:
|
||||
- Line coverage percentage
|
||||
- Branch coverage percentage
|
||||
- Function coverage percentage
|
||||
- Uncovered lines/branches
|
||||
|
||||
### Phase 4: Verify TDD Cycle
|
||||
|
||||
For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M):
|
||||
|
||||
**1. Red Phase Verification**
|
||||
```bash
|
||||
# Check TEST task summary
|
||||
cat .workflow/{session_id}/.summaries/TEST-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Tests were created
|
||||
- Tests failed initially
|
||||
- Failure messages were clear
|
||||
|
||||
**2. Green Phase Verification**
|
||||
```bash
|
||||
# Check IMPL task summary
|
||||
cat .workflow/{session_id}/.summaries/IMPL-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Implementation was completed
|
||||
- Tests now pass
|
||||
- Implementation was minimal
|
||||
|
||||
**3. Refactor Phase Verification**
|
||||
```bash
|
||||
# Check REFACTOR task summary
|
||||
cat .workflow/{session_id}/.summaries/REFACTOR-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Refactoring was completed
|
||||
- Tests still pass
|
||||
- Code quality improved
|
||||
|
||||
### Phase 5: Generate Analysis Report
|
||||
|
||||
Create `.workflow/{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
|
||||
|
||||
### Feature 2: {Feature Name}
|
||||
**Chain**: TEST-2.1 -> IMPL-2.1 -> REFACTOR-2.1
|
||||
|
||||
- [PASS] **Red Phase**: Tests created and failed initially
|
||||
- [WARN] **Green Phase**: Tests pass but implementation seems over-engineered
|
||||
- [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
|
||||
- Feature 3: Missing initial test failure verification
|
||||
- Feature 5: No refactoring step completed
|
||||
|
||||
## Recommendations
|
||||
- Complete missing refactoring steps
|
||||
- Add edge case tests for Feature 2
|
||||
- Verify test failure messages are descriptive
|
||||
```
|
||||
|
||||
## Output Files
|
||||
```
|
||||
.workflow/{session-id}/
|
||||
└── .process/
|
||||
├── test-results.json # Raw test execution results
|
||||
├── coverage-report.json # Parsed coverage data
|
||||
└── tdd-cycle-report.md # TDD cycle analysis
|
||||
```
|
||||
|
||||
## Test Framework Detection
|
||||
|
||||
Auto-detect test framework from project:
|
||||
|
||||
```bash
|
||||
# Check for test frameworks
|
||||
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
|
||||
```
|
||||
|
||||
## 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%
|
||||
```
|
||||
|
||||
## Coverage Metrics Calculation
|
||||
|
||||
```bash
|
||||
# Parse coverage from test-results.json
|
||||
line_coverage=$(jq '.coverage.lineCoverage' test-results.json)
|
||||
branch_coverage=$(jq '.coverage.branchCoverage' test-results.json)
|
||||
function_coverage=$(jq '.coverage.functionCoverage' test-results.json)
|
||||
|
||||
# Calculate overall score
|
||||
overall_score=$(echo "($line_coverage + $branch_coverage + $function_coverage) / 3" | bc)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Test Execution Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Test framework not found | No test config | Configure test framework first |
|
||||
| Tests fail to run | Syntax errors | Fix code before analysis |
|
||||
| Coverage not available | Missing coverage tool | Install coverage plugin |
|
||||
|
||||
### Cycle Verification Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Summary missing | Task not executed | Execute tasks before analysis |
|
||||
| Invalid summary format | Corrupted file | Re-run task to regenerate |
|
||||
| No test evidence | Tests not committed | Ensure tests are committed |
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:tdd-verify` (Phase 3)
|
||||
- **Calls**: Test framework commands (npm test, pytest, etc.)
|
||||
- **Followed By**: Compliance report generation
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
/workflow:tools:tdd-coverage-analysis --session WFS-auth
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
```
|
||||
TDD Coverage Analysis complete for session: WFS-auth
|
||||
|
||||
## Coverage Results
|
||||
Line Coverage: 87%
|
||||
Branch Coverage: 82%
|
||||
Function Coverage: 91%
|
||||
|
||||
## TDD Cycle Verification
|
||||
[PASS] Feature 1: Complete (Red -> Green -> Refactor)
|
||||
[PASS] Feature 2: Complete (Red -> Green -> Refactor)
|
||||
[WARN] Feature 3: Incomplete (Red -> Green, missing Refactor)
|
||||
|
||||
Overall Compliance: 93/100
|
||||
|
||||
Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:tdd-verify` - Uses this tool for verification
|
||||
- `/workflow:tools:task-generate-tdd` - Generates tasks this tool analyzes
|
||||
- `/workflow:execute` - Executes tasks before analysis
|
||||
@@ -0,0 +1,467 @@
|
||||
---
|
||||
name: test-concept-enhanced
|
||||
description: Analyze test requirements and generate test generation strategy using Gemini with test-context package
|
||||
argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
|
||||
examples:
|
||||
- /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
|
||||
---
|
||||
|
||||
# Test Concept Enhanced Command
|
||||
|
||||
## Overview
|
||||
Specialized analysis tool for test generation workflows that uses Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies.
|
||||
|
||||
## Core Philosophy
|
||||
- **Coverage-Driven**: Focus on identified test gaps from context analysis
|
||||
- **Pattern-Based**: Learn from existing tests and project conventions
|
||||
- **Gemini-Powered**: Use Gemini for test requirement analysis and strategy design
|
||||
- **Single-Round Analysis**: Comprehensive test analysis in one execution
|
||||
- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution
|
||||
|
||||
## Core Responsibilities
|
||||
- Parse test-context-package.json from test-context-gather
|
||||
- Analyze implementation summaries and coverage gaps
|
||||
- Study existing test patterns and conventions
|
||||
- Generate test generation strategy using Gemini
|
||||
- Produce TEST_ANALYSIS_RESULTS.md for task generation
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Validation & Preparation
|
||||
|
||||
1. **Session Validation**
|
||||
- Load `.workflow/{test_session_id}/workflow-session.json`
|
||||
- Verify test session type is "test-gen"
|
||||
- Extract source session reference
|
||||
|
||||
2. **Context Package Validation**
|
||||
- Read `test-context-package.json`
|
||||
- Validate required sections: metadata, source_context, test_coverage, test_framework
|
||||
- Extract coverage gaps and framework details
|
||||
|
||||
3. **Strategy Determination**
|
||||
- **Simple Test Generation** (1-3 files): Single Gemini analysis
|
||||
- **Medium Test Generation** (4-6 files): Gemini comprehensive analysis
|
||||
- **Complex Test Generation** (>6 files): Gemini analysis with modular approach
|
||||
|
||||
### Phase 2: Gemini Test Analysis
|
||||
|
||||
**Tool Configuration**:
|
||||
```bash
|
||||
cd .workflow/{test_session_id}/.process && gemini -p "
|
||||
PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
|
||||
TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
|
||||
MODE: analysis
|
||||
CONTEXT: @{.workflow/{test_session_id}/.process/test-context-package.json}
|
||||
|
||||
**MANDATORY FIRST STEP**: Read and analyze test-context-package.json to understand:
|
||||
- Test coverage gaps from test_coverage.missing_tests[]
|
||||
- Implementation context from source_context.implementation_summaries[]
|
||||
- Existing test patterns from test_framework.conventions
|
||||
- Changed files requiring tests from source_context.implementation_summaries[].changed_files
|
||||
|
||||
**ANALYSIS REQUIREMENTS**:
|
||||
|
||||
1. **Implementation Understanding**
|
||||
- Load all implementation summaries from source session
|
||||
- Understand implemented features, APIs, and business logic
|
||||
- Extract key functions, classes, and modules
|
||||
- Identify integration points and dependencies
|
||||
|
||||
2. **Existing Test Pattern Analysis**
|
||||
- Study existing test files for patterns and conventions
|
||||
- Identify test structure (describe/it, test suites, fixtures)
|
||||
- Analyze assertion patterns and mocking strategies
|
||||
- Extract test setup/teardown patterns
|
||||
|
||||
3. **Coverage Gap Assessment**
|
||||
- For each file in missing_tests[], analyze:
|
||||
- File purpose and functionality
|
||||
- Public APIs requiring test coverage
|
||||
- Critical paths and edge cases
|
||||
- Integration points requiring tests
|
||||
- Prioritize tests: high (core logic), medium (utilities), low (helpers)
|
||||
|
||||
4. **Test Requirements Specification**
|
||||
- For each missing test file, specify:
|
||||
- **Test scope**: What needs to be tested
|
||||
- **Test scenarios**: Happy path, error cases, edge cases, integration
|
||||
- **Test data**: Required fixtures, mocks, test data
|
||||
- **Dependencies**: External services, databases, APIs to mock
|
||||
- **Coverage targets**: Functions/methods requiring tests
|
||||
|
||||
5. **Test Generation Strategy**
|
||||
- Determine test generation approach for each file
|
||||
- Identify reusable test patterns from existing tests
|
||||
- Plan test data and fixture requirements
|
||||
- Define mocking strategy for dependencies
|
||||
- Specify expected test file structure
|
||||
|
||||
EXPECTED OUTPUT - Write to gemini-test-analysis.md:
|
||||
|
||||
# Test Generation Analysis
|
||||
|
||||
## 1. Implementation Context Summary
|
||||
- **Source Session**: {source_session_id}
|
||||
- **Implemented Features**: {feature_summary}
|
||||
- **Changed Files**: {list_of_implementation_files}
|
||||
- **Tech Stack**: {technologies_used}
|
||||
|
||||
## 2. Test Coverage Assessment
|
||||
- **Existing Tests**: {count} files
|
||||
- **Missing Tests**: {count} files
|
||||
- **Coverage Percentage**: {percentage}%
|
||||
- **Priority Breakdown**:
|
||||
- High Priority: {count} files (core business logic)
|
||||
- Medium Priority: {count} files (utilities, helpers)
|
||||
- Low Priority: {count} files (configuration, constants)
|
||||
|
||||
## 3. Existing Test Pattern Analysis
|
||||
- **Test Framework**: {framework_name_and_version}
|
||||
- **File Naming Convention**: {pattern}
|
||||
- **Test Structure**: {describe_it_or_other}
|
||||
- **Assertion Style**: {expect_assert_should}
|
||||
- **Mocking Strategy**: {mocking_framework_and_patterns}
|
||||
- **Setup/Teardown**: {beforeEach_afterEach_patterns}
|
||||
- **Test Data**: {fixtures_factories_builders}
|
||||
|
||||
## 4. Test Requirements by File
|
||||
|
||||
### File: {implementation_file_path}
|
||||
**Test File**: {suggested_test_file_path}
|
||||
**Priority**: {high|medium|low}
|
||||
|
||||
#### Scope
|
||||
- {description_of_what_needs_testing}
|
||||
|
||||
#### Test Scenarios
|
||||
1. **Happy Path Tests**
|
||||
- {scenario_1}
|
||||
- {scenario_2}
|
||||
|
||||
2. **Error Handling Tests**
|
||||
- {error_scenario_1}
|
||||
- {error_scenario_2}
|
||||
|
||||
3. **Edge Case Tests**
|
||||
- {edge_case_1}
|
||||
- {edge_case_2}
|
||||
|
||||
4. **Integration Tests** (if applicable)
|
||||
- {integration_scenario_1}
|
||||
- {integration_scenario_2}
|
||||
|
||||
#### Test Data & Fixtures
|
||||
- {required_test_data}
|
||||
- {required_mocks}
|
||||
- {required_fixtures}
|
||||
|
||||
#### Dependencies to Mock
|
||||
- {external_service_1}
|
||||
- {external_service_2}
|
||||
|
||||
#### Coverage Targets
|
||||
- Function: {function_name} - {test_requirements}
|
||||
- Function: {function_name} - {test_requirements}
|
||||
|
||||
---
|
||||
[Repeat for each missing test file]
|
||||
---
|
||||
|
||||
## 5. Test Generation Strategy
|
||||
|
||||
### Overall Approach
|
||||
- {strategy_description}
|
||||
|
||||
### Test Generation Order
|
||||
1. {file_1} - {rationale}
|
||||
2. {file_2} - {rationale}
|
||||
3. {file_3} - {rationale}
|
||||
|
||||
### Reusable Patterns
|
||||
- {pattern_1_from_existing_tests}
|
||||
- {pattern_2_from_existing_tests}
|
||||
|
||||
### Test Data Strategy
|
||||
- {approach_to_test_data_and_fixtures}
|
||||
|
||||
### Mocking Strategy
|
||||
- {approach_to_mocking_dependencies}
|
||||
|
||||
### Quality Criteria
|
||||
- Code coverage target: {percentage}%
|
||||
- Test scenarios per function: {count}
|
||||
- Integration test coverage: {approach}
|
||||
|
||||
## 6. Implementation Targets
|
||||
|
||||
**Purpose**: Identify new test files to create
|
||||
|
||||
**Format**: New test files only (no existing files to modify)
|
||||
|
||||
**Test Files to Create**:
|
||||
1. **Target**: `tests/auth/TokenValidator.test.ts`
|
||||
- **Type**: Create new test file
|
||||
- **Purpose**: Test TokenValidator class
|
||||
- **Scenarios**: 15 test cases covering validation logic, error handling, edge cases
|
||||
- **Dependencies**: Mock JWT library, test fixtures for tokens
|
||||
|
||||
2. **Target**: `tests/middleware/errorHandler.test.ts`
|
||||
- **Type**: Create new test file
|
||||
- **Purpose**: Test error handling middleware
|
||||
- **Scenarios**: 8 test cases for different error types and response formats
|
||||
- **Dependencies**: Mock Express req/res/next, error fixtures
|
||||
|
||||
[List all test files to create]
|
||||
|
||||
## 7. Success Metrics
|
||||
- **Test Coverage Goal**: {target_percentage}%
|
||||
- **Test Quality**: All scenarios covered (happy, error, edge, integration)
|
||||
- **Convention Compliance**: Follow existing test patterns
|
||||
- **Maintainability**: Clear test descriptions, reusable fixtures
|
||||
|
||||
RULES:
|
||||
- Focus on TEST REQUIREMENTS and GENERATION STRATEGY, NOT code generation
|
||||
- Study existing test patterns thoroughly for consistency
|
||||
- Prioritize critical business logic tests
|
||||
- Specify clear test scenarios and coverage targets
|
||||
- Identify all dependencies requiring mocks
|
||||
- **MUST write output to .workflow/{test_session_id}/.process/gemini-test-analysis.md**
|
||||
- Do NOT generate actual test code or implementation
|
||||
- Output ONLY test analysis and generation strategy
|
||||
" --approval-mode yolo
|
||||
```
|
||||
|
||||
**Output Location**: `.workflow/{test_session_id}/.process/gemini-test-analysis.md`
|
||||
|
||||
### Phase 3: Results Synthesis
|
||||
|
||||
1. **Output Validation**
|
||||
- Verify `gemini-test-analysis.md` exists and is complete
|
||||
- Validate all required sections present
|
||||
- Check test requirements are actionable
|
||||
|
||||
2. **Quality Assessment**
|
||||
- Test scenarios cover happy path, errors, edge cases
|
||||
- Dependencies and mocks clearly identified
|
||||
- Test generation strategy is practical
|
||||
- Coverage targets are reasonable
|
||||
|
||||
### Phase 4: TEST_ANALYSIS_RESULTS.md Generation
|
||||
|
||||
Synthesize Gemini analysis into standardized format:
|
||||
|
||||
```markdown
|
||||
# Test Generation Analysis Results
|
||||
|
||||
## Executive Summary
|
||||
- **Test Session**: {test_session_id}
|
||||
- **Source Session**: {source_session_id}
|
||||
- **Analysis Timestamp**: {timestamp}
|
||||
- **Coverage Gap**: {missing_test_count} files require tests
|
||||
- **Test Framework**: {framework}
|
||||
- **Overall Strategy**: {high_level_approach}
|
||||
|
||||
---
|
||||
|
||||
## 1. Coverage Assessment
|
||||
|
||||
### Current Coverage
|
||||
- **Existing Tests**: {count} files
|
||||
- **Implementation Files**: {count} files
|
||||
- **Coverage Percentage**: {percentage}%
|
||||
|
||||
### Missing Tests (Priority Order)
|
||||
1. **High Priority** ({count} files)
|
||||
- {file_1} - {reason}
|
||||
- {file_2} - {reason}
|
||||
|
||||
2. **Medium Priority** ({count} files)
|
||||
- {file_1} - {reason}
|
||||
|
||||
3. **Low Priority** ({count} files)
|
||||
- {file_1} - {reason}
|
||||
|
||||
---
|
||||
|
||||
## 2. Test Framework & Conventions
|
||||
|
||||
### Framework Configuration
|
||||
- **Framework**: {framework_name}
|
||||
- **Version**: {version}
|
||||
- **Test Pattern**: {file_pattern}
|
||||
- **Test Directory**: {directory_structure}
|
||||
|
||||
### Conventions
|
||||
- **File Naming**: {convention}
|
||||
- **Test Structure**: {describe_it_blocks}
|
||||
- **Assertions**: {assertion_library}
|
||||
- **Mocking**: {mocking_framework}
|
||||
- **Setup/Teardown**: {beforeEach_afterEach}
|
||||
|
||||
### Example Pattern (from existing tests)
|
||||
```
|
||||
{example_test_structure_from_analysis}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Test Requirements by File
|
||||
|
||||
[For each missing test, include:]
|
||||
|
||||
### Test File: {test_file_path}
|
||||
**Implementation**: {implementation_file}
|
||||
**Priority**: {high|medium|low}
|
||||
**Estimated Test Count**: {count}
|
||||
|
||||
#### Test Scenarios
|
||||
1. **Happy Path**: {scenarios}
|
||||
2. **Error Handling**: {scenarios}
|
||||
3. **Edge Cases**: {scenarios}
|
||||
4. **Integration**: {scenarios}
|
||||
|
||||
#### Dependencies & Mocks
|
||||
- {dependency_1_to_mock}
|
||||
- {dependency_2_to_mock}
|
||||
|
||||
#### Test Data Requirements
|
||||
- {fixture_1}
|
||||
- {fixture_2}
|
||||
|
||||
---
|
||||
|
||||
## 4. Test Generation Strategy
|
||||
|
||||
### Generation Approach
|
||||
{overall_strategy_description}
|
||||
|
||||
### Generation Order
|
||||
1. {test_file_1} - {rationale}
|
||||
2. {test_file_2} - {rationale}
|
||||
3. {test_file_3} - {rationale}
|
||||
|
||||
### Reusable Components
|
||||
- **Test Fixtures**: {common_fixtures}
|
||||
- **Mock Patterns**: {common_mocks}
|
||||
- **Helper Functions**: {test_helpers}
|
||||
|
||||
### Quality Targets
|
||||
- **Coverage Goal**: {percentage}%
|
||||
- **Scenarios per Function**: {min_count}
|
||||
- **Integration Coverage**: {approach}
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation Targets
|
||||
|
||||
**Purpose**: New test files to create (code-developer will generate these)
|
||||
|
||||
**Test Files to Create**:
|
||||
|
||||
1. **Target**: `tests/auth/TokenValidator.test.ts`
|
||||
- **Implementation Source**: `src/auth/TokenValidator.ts`
|
||||
- **Test Scenarios**: 15 (validation, error handling, edge cases)
|
||||
- **Dependencies**: Mock JWT library, token fixtures
|
||||
- **Priority**: High
|
||||
|
||||
2. **Target**: `tests/middleware/errorHandler.test.ts`
|
||||
- **Implementation Source**: `src/middleware/errorHandler.ts`
|
||||
- **Test Scenarios**: 8 (error types, response formats)
|
||||
- **Dependencies**: Mock Express, error fixtures
|
||||
- **Priority**: High
|
||||
|
||||
[List all test files with full specifications]
|
||||
|
||||
---
|
||||
|
||||
## 6. Success Criteria
|
||||
|
||||
### Coverage Metrics
|
||||
- Achieve {target_percentage}% code coverage
|
||||
- All public APIs have tests
|
||||
- Critical paths fully covered
|
||||
|
||||
### Quality Standards
|
||||
- All test scenarios covered (happy, error, edge, integration)
|
||||
- Follow existing test conventions
|
||||
- Clear test descriptions and assertions
|
||||
- Maintainable test structure
|
||||
|
||||
### Validation Approach
|
||||
- Run full test suite after generation
|
||||
- Verify coverage with coverage tool
|
||||
- Manual review of test quality
|
||||
- Integration test validation
|
||||
|
||||
---
|
||||
|
||||
## 7. Reference Information
|
||||
|
||||
### Source Context
|
||||
- **Implementation Summaries**: {paths}
|
||||
- **Existing Tests**: {example_tests}
|
||||
- **Documentation**: {relevant_docs}
|
||||
|
||||
### Analysis Tools
|
||||
- **Gemini Analysis**: gemini-test-analysis.md
|
||||
- **Coverage Tools**: {coverage_tool_if_detected}
|
||||
```
|
||||
|
||||
**Output Location**: `.workflow/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Missing context package | test-context-gather not run | Run test-context-gather first |
|
||||
| No coverage gaps | All files have tests | Skip test generation, proceed to test execution |
|
||||
| No test framework detected | Missing test dependencies | Request user to configure test framework |
|
||||
| Invalid source session | Source session incomplete | Complete implementation first |
|
||||
|
||||
### Gemini Execution Errors
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| Timeout | Large project analysis | Reduce scope, analyze by module |
|
||||
| Output incomplete | Token limit exceeded | Retry with focused analysis |
|
||||
| No output file | Write permission error | Check directory permissions |
|
||||
|
||||
### Fallback Strategy
|
||||
- If Gemini fails, generate basic TEST_ANALYSIS_RESULTS.md from context package
|
||||
- Use coverage gaps and framework info to create minimal requirements
|
||||
- Provide guidance for manual test planning
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
- **Focused Analysis**: Only analyze files with missing tests
|
||||
- **Pattern Reuse**: Study existing tests for quick pattern extraction
|
||||
- **Parallel Operations**: Load implementation summaries in parallel
|
||||
- **Timeout Management**: 20-minute limit for Gemini analysis
|
||||
|
||||
## Integration
|
||||
|
||||
### Called By
|
||||
- `/workflow:test-gen` (Phase 4: Analysis)
|
||||
|
||||
### Requires
|
||||
- `/workflow:tools:test-context-gather` output (test-context-package.json)
|
||||
|
||||
### Followed By
|
||||
- `/workflow:tools:test-task-generate` - Generates test task JSON with code-developer invocation
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Valid TEST_ANALYSIS_RESULTS.md generated
|
||||
- ✅ All missing tests documented with requirements
|
||||
- ✅ Test scenarios cover happy path, errors, edge cases
|
||||
- ✅ Dependencies and mocks identified
|
||||
- ✅ Test generation strategy is actionable
|
||||
- ✅ Execution time < 20 minutes
|
||||
- ✅ Output follows existing test conventions
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:tools:test-context-gather` - Provides input context
|
||||
- `/workflow:tools:test-task-generate` - Consumes analysis results
|
||||
- `/workflow:test-gen` - Main test generation workflow
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
name: test-context-gather
|
||||
description: Collect test coverage context using test-context-search-agent and package into standardized test-context JSON
|
||||
argument-hint: "--session WFS-test-session-id"
|
||||
examples:
|
||||
- /workflow:tools:test-context-gather --session WFS-test-auth
|
||||
- /workflow:tools:test-context-gather --session WFS-test-payment
|
||||
allowed-tools: Task(*), Read(*), Glob(*)
|
||||
---
|
||||
|
||||
# Test Context Gather Command (/workflow:tools:test-context-gather)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
|
||||
|
||||
**Agent**: `test-context-search-agent` (`.claude/agents/test-context-search-agent.md`)
|
||||
|
||||
## 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/{test_session_id}/.process/test-context-package.json`
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Step 1: Test-Context-Package Detection
|
||||
|
||||
**Execute First** - Check if valid package already exists:
|
||||
|
||||
```javascript
|
||||
const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
|
||||
|
||||
if (file_exists(testContextPath)) {
|
||||
const existing = Read(testContextPath);
|
||||
|
||||
// Validate package belongs to current test session
|
||||
if (existing?.metadata?.test_session_id === test_session_id) {
|
||||
console.log("✅ Valid test-context-package found for session:", test_session_id);
|
||||
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);
|
||||
return existing; // Skip execution, return existing
|
||||
} else {
|
||||
console.warn("⚠️ Invalid test_session_id in existing package, re-generating...");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Invoke Test-Context-Search Agent
|
||||
|
||||
**Only execute if Step 1 finds no valid package**
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="test-context-search-agent",
|
||||
description="Gather test coverage context",
|
||||
prompt=`
|
||||
You are executing as test-context-search-agent (.claude/agents/test-context-search-agent.md).
|
||||
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
|
||||
|
||||
## Session Information
|
||||
- **Test Session ID**: ${test_session_id}
|
||||
- **Output Path**: .workflow/${test_session_id}/.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: Output Verification
|
||||
|
||||
After agent completes, verify output:
|
||||
|
||||
```javascript
|
||||
// Verify file was created
|
||||
const outputPath = `.workflow/${test_session_id}/.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 = 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);
|
||||
```
|
||||
|
||||
## Parameter Reference
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) |
|
||||
|
||||
## Output Schema
|
||||
|
||||
Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema.
|
||||
|
||||
**Key Sections**:
|
||||
- **metadata**: Test session info, source session reference, complexity
|
||||
- **source_context**: Implementation summaries with changed files and tech stack
|
||||
- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics
|
||||
- **test_framework**: Framework name, version, patterns, conventions
|
||||
- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code)
|
||||
- **focus_areas**: Test generation guidance based on analysis
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
/workflow:tools:test-context-gather --session WFS-test-auth
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
```
|
||||
✅ Valid test-context-package found for session: WFS-test-auth
|
||||
📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 }
|
||||
🧪 Framework: jest
|
||||
⚠️ Missing Tests: 1
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Valid test-context-package.json generated in `.workflow/{test_session_id}/.process/`
|
||||
- ✅ Source session context loaded successfully
|
||||
- ✅ Test coverage gaps identified (>90% accuracy)
|
||||
- ✅ Test framework detected and documented
|
||||
- ✅ Execution completes within 30 seconds (60s for large codebases)
|
||||
- ✅ All required schema fields present and valid
|
||||
- ✅ Coverage statistics calculated correctly
|
||||
- ✅ Agent reports completion with statistics
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate |
|
||||
| Source session not found | Invalid source_session reference | Verify test session metadata |
|
||||
| No implementation summaries | Source session incomplete | Complete source session first |
|
||||
| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access |
|
||||
| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
|
||||
| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed |
|
||||
|
||||
## Integration
|
||||
|
||||
### Called By
|
||||
- `/workflow:test-gen` (Phase 3: Context Gathering)
|
||||
|
||||
### Calls
|
||||
- `test-context-search-agent` - Autonomous test coverage analysis
|
||||
|
||||
### Followed By
|
||||
- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning
|
||||
|
||||
## Notes
|
||||
|
||||
- **Detection-first**: Always check for existing test-context-package before invoking agent
|
||||
- **Agent autonomy**: Agent handles all coverage analysis logic per `.claude/agents/test-context-search-agent.md`
|
||||
- **No redundancy**: This command is a thin orchestrator, all logic in agent
|
||||
- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
|
||||
- **Coverage focus**: Primary goal is identifying implementation files without tests
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:test-gen` - Main test generation workflow
|
||||
- `/workflow:tools:test-concept-enhanced` - Test generation analysis
|
||||
- `/workflow:tools:test-task-generate` - Test task JSON generation
|
||||
@@ -0,0 +1,695 @@
|
||||
---
|
||||
name: test-task-generate
|
||||
description: Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex
|
||||
argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
|
||||
examples:
|
||||
- /workflow:tools:test-task-generate --session WFS-test-auth
|
||||
- /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
|
||||
- /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
|
||||
- /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
|
||||
---
|
||||
|
||||
# Test Task Generation Command
|
||||
|
||||
## Overview
|
||||
Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle specification, including Gemini diagnosis (using bug-fix template) and manual fix workflow (Codex automation only when explicitly requested).
|
||||
|
||||
## Execution Modes
|
||||
|
||||
### Test Generation (IMPL-001)
|
||||
- **Agent Mode (Default)**: @code-developer generates tests within agent context
|
||||
- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
|
||||
|
||||
### Test Fix (IMPL-002)
|
||||
- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
|
||||
- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
|
||||
|
||||
## Core Philosophy
|
||||
- **Analysis-Driven Test Generation**: Use TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
|
||||
- **Agent-Based Test Creation**: Call @code-developer agent for comprehensive test generation
|
||||
- **Coverage-First**: Generate all missing tests before execution
|
||||
- **Test Execution**: Execute complete test suite after generation
|
||||
- **Gemini Diagnosis**: Use Gemini for root cause analysis and fix suggestions (references bug-fix template)
|
||||
- **Manual Fixes First**: Apply fixes manually by default, codex only when explicitly needed
|
||||
- **Iterative Refinement**: Repeat test-analyze-fix-retest cycle until all tests pass
|
||||
- **Surgical Fixes**: Minimal code changes, no refactoring during test fixes
|
||||
- **Auto-Revert**: Rollback all changes if max iterations reached
|
||||
|
||||
## Core Responsibilities
|
||||
- Parse TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
|
||||
- Extract test requirements and generation strategy
|
||||
- Parse `--use-codex` flag to determine fix mode (manual vs automated)
|
||||
- Generate test generation subtask calling @code-developer
|
||||
- Generate test execution and fix cycle task JSON with appropriate fix mode
|
||||
- Configure Gemini diagnosis workflow (bug-fix template) and manual/Codex fix application
|
||||
- Create test-oriented IMPL_PLAN.md and TODO_LIST.md with test generation phase
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Input Validation & Discovery
|
||||
|
||||
1. **Parameter Parsing**
|
||||
- Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
|
||||
- Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
|
||||
- Store flag values for task JSON generation
|
||||
|
||||
2. **Test Session Validation**
|
||||
- Load `.workflow/{test-session-id}/workflow-session.json`
|
||||
- Verify `workflow_type: "test_session"`
|
||||
- Extract `source_session_id` from metadata
|
||||
|
||||
3. **Test Analysis Results Loading**
|
||||
- **REQUIRED**: Load `.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md`
|
||||
- Parse test requirements by file
|
||||
- Extract test generation strategy
|
||||
- Identify test files to create with specifications
|
||||
|
||||
4. **Test Context Package Loading**
|
||||
- Load `.workflow/{test-session-id}/.process/test-context-package.json`
|
||||
- Extract test framework configuration
|
||||
- Extract coverage gaps and priorities
|
||||
- Load source session implementation summaries
|
||||
|
||||
### Phase 2: Task JSON Generation
|
||||
|
||||
Generate **TWO task JSON files**:
|
||||
1. **IMPL-001.json** - Test Generation (calls @code-developer)
|
||||
2. **IMPL-002.json** - Test Execution and Fix Cycle (calls @test-fix-agent)
|
||||
|
||||
#### IMPL-001.json - Test Generation Task
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Generate comprehensive tests for [sourceSessionId]",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "test-gen",
|
||||
"agent": "@code-developer",
|
||||
"source_session": "[sourceSessionId]",
|
||||
"test_framework": "jest|pytest|cargo|detected"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Generate comprehensive test files based on TEST_ANALYSIS_RESULTS.md",
|
||||
"Follow existing test patterns and conventions from test framework",
|
||||
"Create tests for all missing coverage identified in analysis",
|
||||
"Include happy path, error handling, edge cases, and integration tests",
|
||||
"Use test data and mocks as specified in analysis",
|
||||
"Ensure tests follow project coding standards"
|
||||
],
|
||||
"focus_paths": [
|
||||
"tests/**/*",
|
||||
"src/**/*.test.*",
|
||||
"{paths_from_analysis}"
|
||||
],
|
||||
"acceptance": [
|
||||
"All test files from TEST_ANALYSIS_RESULTS.md section 5 are created",
|
||||
"Tests follow existing test patterns and conventions",
|
||||
"Test scenarios cover happy path, errors, edge cases, integration",
|
||||
"All dependencies are properly mocked",
|
||||
"Test files are syntactically valid and can be executed",
|
||||
"Test coverage meets analysis requirements"
|
||||
],
|
||||
"depends_on": [],
|
||||
"source_context": {
|
||||
"session_id": "[sourceSessionId]",
|
||||
"test_analysis": ".workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md",
|
||||
"test_context": ".workflow/[testSessionId]/.process/test-context-package.json",
|
||||
"implementation_summaries": [
|
||||
".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
|
||||
]
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_test_analysis",
|
||||
"action": "Load test generation requirements and strategy",
|
||||
"commands": [
|
||||
"Read(.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md)",
|
||||
"Read(.workflow/[testSessionId]/.process/test-context-package.json)"
|
||||
],
|
||||
"output_to": "test_generation_requirements",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "load_implementation_context",
|
||||
"action": "Load source implementation for test generation context",
|
||||
"commands": [
|
||||
"bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
|
||||
],
|
||||
"output_to": "implementation_context",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "load_existing_test_patterns",
|
||||
"action": "Study existing tests for pattern reference",
|
||||
"commands": [
|
||||
"bash(find . -name \"*.test.*\" -type f)",
|
||||
"bash(# Read first 2 existing test files as examples)",
|
||||
"bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
|
||||
"bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
|
||||
],
|
||||
"output_to": "existing_test_patterns",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
// Agent Mode (Default): Agent implements tests
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate comprehensive test suite",
|
||||
"description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
|
||||
"modification_points": [
|
||||
"Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
|
||||
"Study existing test patterns",
|
||||
"Create test files with all required scenarios",
|
||||
"Implement happy path, error handling, edge case, and integration tests",
|
||||
"Add required mocks and fixtures"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
|
||||
"Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
|
||||
"Study existing test patterns from test_context.test_framework.conventions",
|
||||
"For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
|
||||
"Follow test framework conventions and project standards",
|
||||
"Ensure all tests are executable and syntactically valid"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "test_suite"
|
||||
}
|
||||
],
|
||||
|
||||
// CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
|
||||
"implementation_approach": [{
|
||||
"step": 1,
|
||||
"title": "Generate tests using Codex",
|
||||
"description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
|
||||
"modification_points": [
|
||||
"Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
|
||||
"Codex generates all test files listed in analysis section 5",
|
||||
"Codex ensures tests follow framework conventions"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Start new Codex session",
|
||||
"Pass TEST_ANALYSIS_RESULTS.md to Codex",
|
||||
"Codex studies existing test patterns",
|
||||
"Codex generates comprehensive test suite",
|
||||
"Codex validates test syntax and executability"
|
||||
],
|
||||
"command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
|
||||
"depends_on": [],
|
||||
"output": "test_generation"
|
||||
}],
|
||||
"target_files": [
|
||||
"{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
|
||||
"{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
|
||||
"{test_file_N from TEST_ANALYSIS_RESULTS.md section 5}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### IMPL-002.json - Test Execution & Fix Cycle Task
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Execute and fix tests for [sourceSessionId]",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "test-fix",
|
||||
"agent": "@test-fix-agent",
|
||||
"source_session": "[sourceSessionId]",
|
||||
"test_framework": "jest|pytest|cargo|detected",
|
||||
"max_iterations": 5,
|
||||
"use_codex": false // Set to true if --use-codex flag present
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Execute complete test suite (generated in IMPL-001)",
|
||||
"Diagnose test failures using Gemini analysis with bug-fix template",
|
||||
"Present fixes to user for manual application (default)",
|
||||
"Use Codex ONLY if user explicitly requests automation",
|
||||
"Iterate until all tests pass or max iterations reached",
|
||||
"Revert changes if unable to fix within iteration limit"
|
||||
],
|
||||
"focus_paths": [
|
||||
"tests/**/*",
|
||||
"src/**/*.test.*",
|
||||
"{implementation_files_from_source_session}"
|
||||
],
|
||||
"acceptance": [
|
||||
"All tests pass successfully (100% pass rate)",
|
||||
"No test failures or errors in final run",
|
||||
"Code changes are minimal and surgical",
|
||||
"All fixes are verified through retest",
|
||||
"Iteration logs document fix progression"
|
||||
],
|
||||
"depends_on": ["IMPL-001"],
|
||||
"source_context": {
|
||||
"session_id": "[sourceSessionId]",
|
||||
"test_generation_summary": ".workflow/[testSessionId]/.summaries/IMPL-001-summary.md",
|
||||
"implementation_summaries": [
|
||||
".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
|
||||
]
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_source_session_summaries",
|
||||
"action": "Load implementation context from source session",
|
||||
"commands": [
|
||||
"bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
|
||||
"bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
|
||||
],
|
||||
"output_to": "implementation_context",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "discover_test_framework",
|
||||
"action": "Identify test framework and test command",
|
||||
"commands": [
|
||||
"bash(jq -r '.scripts.test // \"npm test\"' package.json 2>/dev/null || echo 'pytest' || echo 'cargo test')",
|
||||
"bash([ -f 'package.json' ] && echo 'jest/npm' || [ -f 'pytest.ini' ] && echo 'pytest' || [ -f 'Cargo.toml' ] && echo 'cargo' || echo 'unknown')"
|
||||
],
|
||||
"output_to": "test_command",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"step": "analyze_test_coverage",
|
||||
"action": "Analyze test coverage and identify missing tests",
|
||||
"commands": [
|
||||
"bash(find . -name \"*.test.*\" -type f)",
|
||||
"bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
|
||||
"bash(# Count implementation files vs test files)",
|
||||
"bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
|
||||
"bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))",
|
||||
"bash(echo \"Implementation files: $impl_count, Test files: $test_count\")"
|
||||
],
|
||||
"output_to": "test_coverage_analysis",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "identify_files_without_tests",
|
||||
"action": "List implementation files that lack corresponding test files",
|
||||
"commands": [
|
||||
"bash(# For each changed file from source session, check if test exists)",
|
||||
"bash(for file in [changed_files]; do test_file=$(echo $file | sed 's/\\(.*\\)\\.\\(ts\\|js\\|py\\)$/\\1.test.\\2/'); [ ! -f \"$test_file\" ] && echo \"$file\"; done)"
|
||||
],
|
||||
"output_to": "files_without_tests",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "prepare_test_environment",
|
||||
"action": "Ensure test environment is ready",
|
||||
"commands": [
|
||||
"bash([ -f 'package.json' ] && npm install 2>/dev/null || true)",
|
||||
"bash([ -f 'requirements.txt' ] && pip install -q -r requirements.txt 2>/dev/null || true)"
|
||||
],
|
||||
"output_to": "environment_status",
|
||||
"on_error": "skip_optional"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Execute iterative test-fix-retest cycle",
|
||||
"description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
|
||||
"test_fix_cycle": {
|
||||
"max_iterations": 5,
|
||||
"cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
|
||||
"tools": {
|
||||
"test_execution": "bash(test_command)",
|
||||
"diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
|
||||
"fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
|
||||
"verification": "bash(test_command) + regression_check"
|
||||
},
|
||||
"exit_conditions": {
|
||||
"success": "all_tests_pass",
|
||||
"failure": "max_iterations_reached",
|
||||
"error": "test_command_not_found"
|
||||
}
|
||||
},
|
||||
"modification_points": [
|
||||
"PHASE 1: Initial Test Execution",
|
||||
" 1.1. Discover test command from framework detection",
|
||||
" 1.2. Execute initial test run: bash([test_command])",
|
||||
" 1.3. Parse test output and count failures",
|
||||
" 1.4. If all pass → Skip to PHASE 3 (success)",
|
||||
" 1.5. If failures → Store failure output, proceed to PHASE 2",
|
||||
"",
|
||||
"PHASE 2: Iterative Test-Fix-Retest Cycle (max 5 iterations)",
|
||||
" Note: This phase handles test failures, NOT test generation failures",
|
||||
" Initialize: max_iterations=5, current_iteration=0",
|
||||
" ",
|
||||
" WHILE (tests failing AND current_iteration < max_iterations):",
|
||||
" current_iteration++",
|
||||
" ",
|
||||
" STEP 2.1: Gemini Diagnosis (using bug-fix template)",
|
||||
" - Prepare diagnosis context:",
|
||||
" * Test failure output from previous run",
|
||||
" * Source files from focus_paths",
|
||||
" * Implementation summaries from source session",
|
||||
" - Execute Gemini analysis with bug-fix template:",
|
||||
" bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
|
||||
" PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
|
||||
" TASK: Systematic bug analysis and fix recommendations for test failure",
|
||||
" MODE: analysis",
|
||||
" CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
|
||||
" Test output: [test_failures]",
|
||||
" Source files: [focus_paths]",
|
||||
" Implementation: [implementation_context]",
|
||||
" EXPECTED: Root cause analysis, code path tracing, targeted fixes",
|
||||
" RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Bug: [test_failure_description]",
|
||||
" Minimal surgical fixes only - no refactoring",
|
||||
" \" > fix-iteration-[N]-diagnosis.md)",
|
||||
" - Parse diagnosis → extract fix_suggestion and target_files",
|
||||
" - Present fix to user for manual application (default)",
|
||||
" ",
|
||||
" STEP 2.2: Apply Fix (Based on meta.use_codex Flag)",
|
||||
" ",
|
||||
" IF meta.use_codex = false (DEFAULT):",
|
||||
" - Present Gemini diagnosis to user for manual fix",
|
||||
" - User applies fix based on diagnosis recommendations",
|
||||
" - Stage changes: bash(git add -A)",
|
||||
" - Store fix log: .process/fix-iteration-[N]-changes.log",
|
||||
" ",
|
||||
" IF meta.use_codex = true (--use-codex flag present):",
|
||||
" - Stage current changes (if valid git repo): bash(git add -A)",
|
||||
" - First iteration: Start new Codex session",
|
||||
" codex -C [project_root] --full-auto exec \"",
|
||||
" PURPOSE: Fix test failure iteration 1",
|
||||
" TASK: [fix_suggestion from Gemini]",
|
||||
" MODE: write",
|
||||
" CONTEXT: Diagnosis: .workflow/.process/fix-iteration-1-diagnosis.md",
|
||||
" Target files: [target_files]",
|
||||
" Implementation context: [implementation_context]",
|
||||
" EXPECTED: Minimal code changes to resolve test failure",
|
||||
" RULES: Apply ONLY suggested changes, no refactoring",
|
||||
" Preserve existing code style",
|
||||
" \" --skip-git-repo-check -s danger-full-access",
|
||||
" - Subsequent iterations: Resume session for context continuity",
|
||||
" codex exec \"",
|
||||
" CONTINUE TO NEXT FIX:",
|
||||
" Iteration [N] of 5: Fix test failure",
|
||||
" ",
|
||||
" PURPOSE: Fix remaining test failures",
|
||||
" TASK: [fix_suggestion from Gemini iteration N]",
|
||||
" CONTEXT: Previous fixes applied, diagnosis: .process/fix-iteration-[N]-diagnosis.md",
|
||||
" EXPECTED: Surgical fix for current failure",
|
||||
" RULES: Build on previous fixes, maintain consistency",
|
||||
" \" resume --last --skip-git-repo-check -s danger-full-access",
|
||||
" - Store fix log: .process/fix-iteration-[N]-changes.log",
|
||||
" ",
|
||||
" STEP 2.3: Retest and Verification",
|
||||
" - Re-execute test suite: bash([test_command])",
|
||||
" - Capture output: .process/fix-iteration-[N]-retest.log",
|
||||
" - Count failures: bash(grep -c 'FAIL\\|ERROR' .process/fix-iteration-[N]-retest.log)",
|
||||
" - Check for regression:",
|
||||
" IF new_failures > previous_failures:",
|
||||
" WARN: Regression detected",
|
||||
" Include in next Gemini diagnosis context",
|
||||
" - Analyze results:",
|
||||
" IF all_tests_pass:",
|
||||
" BREAK loop → Proceed to PHASE 3",
|
||||
" ELSE:",
|
||||
" Update test_failures context",
|
||||
" CONTINUE loop",
|
||||
" ",
|
||||
" IF max_iterations reached AND tests still failing:",
|
||||
" EXECUTE: git reset --hard HEAD (revert all changes)",
|
||||
" MARK: Task status = blocked",
|
||||
" GENERATE: Detailed failure report with iteration logs",
|
||||
" EXIT: Require manual intervention",
|
||||
"",
|
||||
"PHASE 3: Final Validation and Certification",
|
||||
" 3.1. Execute final confirmation test run",
|
||||
" 3.2. Generate success summary:",
|
||||
" - Iterations required: [current_iteration]",
|
||||
" - Fixes applied: [summary from iteration logs]",
|
||||
" - Test results: All passing ✅",
|
||||
" 3.3. Mark task status: completed",
|
||||
" 3.4. Update TODO_LIST.md: Mark as ✅",
|
||||
" 3.5. Certify code: APPROVED for deployment"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Load source session implementation context",
|
||||
"Discover test framework and command",
|
||||
"PHASE 0: Test Coverage Check",
|
||||
" Analyze existing test files",
|
||||
" Identify files without tests",
|
||||
" IF tests missing:",
|
||||
" Report to user (no automatic generation)",
|
||||
" Wait for user to generate tests or request automation",
|
||||
" ELSE:",
|
||||
" Skip to Phase 1",
|
||||
"PHASE 1: Initial Test Execution",
|
||||
" Execute test suite",
|
||||
" IF all pass → Success (Phase 3)",
|
||||
" ELSE → Store failures, proceed to Phase 2",
|
||||
"PHASE 2: Iterative Fix Cycle (max 5 iterations)",
|
||||
" LOOP (max 5 times):",
|
||||
" 1. Gemini diagnoses failure with bug-fix template → fix suggestion",
|
||||
" 2. Check meta.use_codex flag:",
|
||||
" - IF false (default): Present fix to user for manual application",
|
||||
" - IF true (--use-codex): Codex applies fix with resume for continuity",
|
||||
" 3. Retest and check results",
|
||||
" 4. IF pass → Exit loop to Phase 3",
|
||||
" 5. ELSE → Continue with updated context",
|
||||
" IF max iterations → Revert + report failure",
|
||||
"PHASE 3: Final Validation",
|
||||
" Confirm all tests pass",
|
||||
" Generate summary (include test generation info)",
|
||||
" Certify code APPROVED"
|
||||
],
|
||||
"error_handling": {
|
||||
"max_iterations_reached": {
|
||||
"action": "revert_all_changes",
|
||||
"commands": [
|
||||
"bash(git reset --hard HEAD)",
|
||||
"bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
|
||||
],
|
||||
"report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
|
||||
},
|
||||
"test_command_fails": {
|
||||
"action": "treat_as_test_failure",
|
||||
"context": "Use stderr as failure context for Gemini diagnosis"
|
||||
},
|
||||
"codex_apply_fails": {
|
||||
"action": "retry_once_then_skip",
|
||||
"fallback": "Mark iteration as skipped, continue to next"
|
||||
},
|
||||
"gemini_diagnosis_fails": {
|
||||
"action": "retry_with_simplified_context",
|
||||
"fallback": "Use previous diagnosis, continue"
|
||||
},
|
||||
"regression_detected": {
|
||||
"action": "log_warning_continue",
|
||||
"context": "Include regression info in next Gemini diagnosis"
|
||||
}
|
||||
},
|
||||
"depends_on": [],
|
||||
"output": "test_fix_results"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
"Auto-discovered from test failures",
|
||||
"Extracted from Gemini diagnosis each iteration",
|
||||
"Format: file:function:lines or file (for new files)"
|
||||
],
|
||||
"codex_session": {
|
||||
"strategy": "resume_for_continuity",
|
||||
"first_iteration": "codex exec \"fix iteration 1\" --full-auto",
|
||||
"subsequent_iterations": "codex exec \"fix iteration N\" resume --last",
|
||||
"benefits": [
|
||||
"Maintains conversation context across fixes",
|
||||
"Remembers previous decisions and patterns",
|
||||
"Ensures consistency in fix approach",
|
||||
"Reduces redundant context injection"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: IMPL_PLAN.md Generation
|
||||
|
||||
#### Document Structure
|
||||
```markdown
|
||||
---
|
||||
identifier: WFS-test-[session-id]
|
||||
source_session: WFS-[source-session-id]
|
||||
workflow_type: test_session
|
||||
test_framework: jest|pytest|cargo|detected
|
||||
---
|
||||
|
||||
# Test Validation Plan: [Source Session Topic]
|
||||
|
||||
## Summary
|
||||
Execute comprehensive test suite for implementation from session WFS-[source-session-id].
|
||||
Diagnose and fix all test failures using iterative Gemini analysis and Codex execution.
|
||||
|
||||
## Source Session Context
|
||||
- **Implementation Session**: WFS-[source-session-id]
|
||||
- **Completed Tasks**: IMPL-001, IMPL-002, ...
|
||||
- **Changed Files**: [list from git log]
|
||||
- **Implementation Summaries**: [references to source session summaries]
|
||||
|
||||
## Test Framework
|
||||
- **Detected Framework**: jest|pytest|cargo|other
|
||||
- **Test Command**: npm test|pytest|cargo test
|
||||
- **Test Files**: [discovered test files]
|
||||
- **Coverage**: [estimated test coverage]
|
||||
|
||||
## Test-Fix-Retest Cycle
|
||||
- **Max Iterations**: 5
|
||||
- **Diagnosis Tool**: Gemini (analysis mode with bug-fix template from bug-index.md)
|
||||
- **Fix Tool**: Manual (default, meta.use_codex=false) or Codex (if --use-codex flag, meta.use_codex=true)
|
||||
- **Verification**: Bash test execution + regression check
|
||||
|
||||
### Cycle Workflow
|
||||
1. **Initial Test**: Execute full suite, capture failures
|
||||
2. **Iterative Fix Loop** (max 5 times):
|
||||
- Gemini diagnoses failure using bug-fix template → surgical fix suggestion
|
||||
- Check meta.use_codex flag:
|
||||
- If false (default): Present fix to user for manual application
|
||||
- If true (--use-codex): Codex applies fix with resume for context continuity
|
||||
- Retest and verify (check for regressions)
|
||||
- Continue until all pass or max iterations reached
|
||||
3. **Final Validation**: Confirm all tests pass, certify code
|
||||
|
||||
### Error Recovery
|
||||
- **Max iterations reached**: Revert all changes, report failure
|
||||
- **Test command fails**: Treat as test failure, diagnose with Gemini
|
||||
- **Codex fails**: Retry once, skip iteration if still failing
|
||||
- **Regression detected**: Log warning, include in next diagnosis
|
||||
|
||||
## Task Breakdown
|
||||
- **IMPL-001**: Execute and validate tests with iterative fix cycle
|
||||
|
||||
## Implementation Strategy
|
||||
- **Phase 1**: Initial test execution and failure capture
|
||||
- **Phase 2**: Iterative Gemini diagnosis + Codex fix + retest
|
||||
- **Phase 3**: Final validation and code certification
|
||||
|
||||
## Success Criteria
|
||||
- All tests pass (100% pass rate)
|
||||
- No test failures or errors in final run
|
||||
- Minimal, surgical code changes
|
||||
- Iteration logs document fix progression
|
||||
- Code certified APPROVED for deployment
|
||||
```
|
||||
|
||||
### Phase 4: TODO_LIST.md Generation
|
||||
|
||||
```markdown
|
||||
# Tasks: Test Validation for [Source Session]
|
||||
|
||||
## Task Progress
|
||||
- [ ] **IMPL-001**: Execute and validate tests with iterative fix cycle → [📋](./.task/IMPL-001.json)
|
||||
|
||||
## Execution Details
|
||||
- **Source Session**: WFS-[source-session-id]
|
||||
- **Test Framework**: jest|pytest|cargo
|
||||
- **Max Iterations**: 5
|
||||
- **Tools**: Gemini diagnosis + Codex resume fixes
|
||||
|
||||
## Status Legend
|
||||
- `- [ ]` = Pending
|
||||
- `- [x]` = Completed
|
||||
```
|
||||
|
||||
## Output Files Structure
|
||||
```
|
||||
.workflow/WFS-test-[session]/
|
||||
├── workflow-session.json # Test session metadata
|
||||
├── IMPL_PLAN.md # Test validation plan
|
||||
├── TODO_LIST.md # Progress tracking
|
||||
├── .task/
|
||||
│ └── IMPL-001.json # Test-fix task with cycle spec
|
||||
├── .process/
|
||||
│ ├── ANALYSIS_RESULTS.md # From concept-enhanced (optional)
|
||||
│ ├── context-package.json # From context-gather
|
||||
│ ├── initial-test.log # Phase 1: Initial test results
|
||||
│ ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
|
||||
│ ├── fix-iteration-1-changes.log # Codex changes iteration 1
|
||||
│ ├── fix-iteration-1-retest.log # Retest results iteration 1
|
||||
│ ├── fix-iteration-N-*.md/log # Subsequent iterations
|
||||
│ └── final-test.log # Phase 3: Final validation
|
||||
└── .summaries/
|
||||
└── IMPL-001-summary.md # Success report OR failure report
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Input Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Not a test session | Missing workflow_type: "test_session" | Verify session created by test-gen |
|
||||
| Source session not found | Invalid source_session_id | Check source session exists |
|
||||
| No implementation summaries | Source session incomplete | Ensure source session has completed tasks |
|
||||
|
||||
### Test Framework Discovery Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| No test command found | Unknown framework | Manual test command specification |
|
||||
| No test files found | Tests not written | Request user to write tests first |
|
||||
| Test dependencies missing | Incomplete setup | Run dependency installation |
|
||||
|
||||
### Generation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Invalid JSON structure | Template error | Fix task generation logic |
|
||||
| Missing required fields | Incomplete metadata | Validate session metadata |
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:test-gen` (Phase 4)
|
||||
- **Calls**: None (terminal command)
|
||||
- **Followed By**: `/workflow:execute` (user-triggered)
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
# Manual fix mode (default)
|
||||
/workflow:tools:test-task-generate --session WFS-test-auth
|
||||
|
||||
# Automated Codex fix mode
|
||||
/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
|
||||
```
|
||||
|
||||
### Flag Behavior
|
||||
- **No flag**: `meta.use_codex=false`, manual fixes presented to user
|
||||
- **--use-codex**: `meta.use_codex=true`, Codex automatically applies fixes with resume mechanism
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:test-gen` - Creates test session and calls this tool
|
||||
- `/workflow:tools:context-gather` - Provides cross-session context
|
||||
- `/workflow:tools:concept-enhanced` - Provides test strategy analysis
|
||||
- `/workflow:execute` - Executes the generated test-fix task
|
||||
- `@test-fix-agent` - Agent that executes the iterative test-fix cycle
|
||||
|
||||
## Agent Execution Notes
|
||||
|
||||
The `@test-fix-agent` will execute the task by following the `flow_control.implementation_approach` specification:
|
||||
|
||||
1. **Load task JSON**: Read complete test-fix task from `.task/IMPL-002.json`
|
||||
2. **Check meta.use_codex**: Determine fix mode (manual or automated)
|
||||
3. **Execute pre_analysis**: Load source context, discover framework, analyze tests
|
||||
4. **Phase 1**: Run initial test suite
|
||||
5. **Phase 2**: If failures, enter iterative loop:
|
||||
- Use Gemini for diagnosis (analysis mode with bug-fix template)
|
||||
- Check meta.use_codex flag:
|
||||
- If false (default): Present fix suggestions to user for manual application
|
||||
- If true (--use-codex): Use Codex resume for automated fixes (maintains context)
|
||||
- Retest and check for regressions
|
||||
- Repeat max 5 times
|
||||
6. **Phase 3**: Generate summary and certify code
|
||||
7. **Error Recovery**: Revert changes if max iterations reached
|
||||
|
||||
**Bug Diagnosis Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
|
||||
|
||||
**Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.
|
||||
Reference in New Issue
Block a user