Compare commits

...

8 Commits

Author SHA1 Message Date
catlog22
b62b42e9f4 feat: migrate test-task-generate to agent-driven architecture
- Refactor test-task-generate.md to use action-planning-agent
- Add two-phase execution flow (Discovery → Agent Execution)
- Integrate Memory-First principle and MCP tool enhancements
- Support both agent-mode (default) and cli-execute-mode
- Add test-specific context package with TEST_ANALYSIS_RESULTS.md
- Align with task-generate-agent.md architecture
- Remove 556 lines of redundant old content (Phase 1-4 old structure)
- Update test-gen.md and test-fix-gen.md to reflect agent-driven changes

Changes include:
- Core Philosophy with agent-driven principles
- Agent Context Package structure for test sessions
- Discovery Actions for test context loading
- Agent Invocation with test-specific requirements
- Test Task Structure Reference
- Updated Integration & Usage sections
- Enhanced Related Commands documentation

Now test task generation uses autonomous agent planning with MCP enhancements for better test coverage analysis and generation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 17:23:55 +08:00
catlog22
52fce757f8 refactor: update tdd-plan to use --cli-execute parameter
- Change --agent flag to --cli-execute for consistency
- Make Agent Mode the default execution mode
- Update CLI Mode to use --cli-execute flag
- Align with agent-driven task generation architecture
- Update Phase 5 command documentation
- Update Related Commands section

This completes the migration to agent-driven architecture for both /workflow:plan and /workflow:tdd-plan commands.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 17:17:09 +08:00
catlog22
c12f6b888a feat: migrate task-generate-tdd to agent-driven architecture
- Refactor task-generate-tdd.md to use action-planning-agent
- Add two-phase execution flow (Discovery → Agent Execution)
- Integrate Memory-First principle and MCP tool enhancements
- Support both agent-mode (default) and cli-execute-mode
- Change --agent flag to --cli-execute for consistency
- Add TDD-specific context package with test coverage integration
- Align with task-generate-agent.md architecture

Now both /workflow:plan and /workflow:tdd-plan use agent-driven task generation for autonomous planning and execution.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 17:11:17 +08:00
catlog22
47667b8360 refactor: streamline task generation workflow architecture
- Remove 150+ lines of duplicate content from task-generate-agent.md
- Implement reference-based design following Content Uniqueness Rules
- Simplify plan.md to use task-generate-agent exclusively
- Remove --agent parameter (agent mode is now default)
- Improve separation of concerns between command and agent layers

Changes:
- task-generate-agent.md: Replace detailed specs with references to action-planning-agent.md
- plan.md: Remove task-generate command, unify on agent-driven approach

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 17:03:18 +08:00
catlog22
915eb396e7 feat: enhance quantification requirements across workflow tools
Enhanced task generation with mandatory quantification standards to eliminate ambiguity:

- Add Quantification Requirements section to all task generation commands
- Enforce explicit counts and enumerations in requirements, acceptance criteria, and modification points
- Standardize formats: "Implement N items: [list]" vs vague "implement features"
- Include verification commands for measurable acceptance criteria
- Simplify documentation by removing verbose examples while preserving all key information

Changes:
- task-generate.md: Add quantification section, streamline Task JSON schema, remove CLI examples
- task-generate-agent.md: Add quantification rules, improve template selection clarity
- task-generate-tdd.md: Add TDD-specific quantification formats for Red-Green-Refactor phases
- action-planning-agent.md: Add quantification requirements with validation checklist and updated examples

Impact:
- Reduces task documentation from ~900 lines to ~600 lines (33% reduction)
- All requirements now require explicit counts: "5 files", "15 test cases", ">=85% coverage"
- Acceptance criteria must include verification commands
- Modification points must specify exact targets with line numbers

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 15:02:07 +08:00
catlog22
1cb83c07e0 feat: 强化任务生成命令,新增量化要求以消除模糊性 2025-11-08 14:39:45 +08:00
catlog22
0404a7eb7c docs: 增强 conflict-resolution 核心规则,禁止使用 bash 命令输出
添加核心职责规则:直接文本输出,禁止使用 bash echo/printf 命令

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 12:07:45 +08:00
catlog22
b98d28df3d docs(command-guide): add Pattern 0 brainstorming workflow for 0-to-1 development
- Add Pattern 0: 头脑风暴 (Brainstorming) as first workflow pattern
- Distinguish FROM-ZERO-TO-ONE vs FEATURE-ADDITION scenarios
- Update decision tree to require brainstorming for new projects
- Enhance SKILL.md Mode 4 with project stage identification
- Remove duplicate Pattern 7 UI design workflow
- Add warning in best practices about not skipping brainstorming

Fixes issue where system incorrectly guided users to start with /workflow:plan
for new projects instead of /workflow:brainstorm:artifacts
2025-11-06 22:14:14 +08:00
12 changed files with 1133 additions and 1492 deletions

View File

@@ -151,9 +151,17 @@ Generate individual `.task/IMPL-*.json` files with:
"agent": "@code-developer"
},
"context": {
"requirements": ["from analysis_results"],
"focus_paths": ["src/paths"],
"acceptance": ["measurable criteria"],
"requirements": [
"Implement 3 features: [authentication, authorization, session management]",
"Create 5 files: [auth.service.ts, auth.controller.ts, auth.middleware.ts, auth.types.ts, auth.test.ts]",
"Modify 2 existing functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]"
],
"focus_paths": ["src/auth", "tests/auth"],
"acceptance": [
"3 features implemented: verify by npm test -- auth (exit code 0)",
"5 files created: verify by ls src/auth/*.ts | wc -l = 5",
"Test coverage >=80%: verify by npm test -- --coverage | grep auth"
],
"depends_on": ["IMPL-N"],
"artifacts": [
{
@@ -181,23 +189,50 @@ Generate individual `.task/IMPL-*.json` files with:
{
"step": 1,
"title": "Load and analyze role analyses",
"description": "Load role analyses from artifacts and extract requirements",
"modification_points": ["Load role analyses", "Extract requirements and design patterns"],
"logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
"description": "Load 3 role analysis files and extract quantified requirements",
"modification_points": [
"Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
"Extract 15 requirements from role analyses",
"Parse 8 architecture decisions from system-architect analysis"
],
"logic_flow": [
"Read 3 role analyses from artifacts inventory",
"Parse architecture decisions (8 total)",
"Extract implementation requirements (15 total)",
"Build consolidated requirements list"
],
"depends_on": [],
"output": "synthesis_requirements"
},
{
"step": 2,
"title": "Implement following specification",
"description": "Implement task requirements following consolidated role analyses",
"modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
"logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
"description": "Implement 3 features across 5 files following consolidated role analyses",
"modification_points": [
"Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
"Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
"Implement 3 core features: [JWT authentication, role-based authorization, session management]"
],
"logic_flow": [
"Apply 15 requirements from [synthesis_requirements]",
"Implement 3 features across 5 new files (600 total lines)",
"Modify 2 existing functions (30 lines total)",
"Write 25 test cases covering all features",
"Validate against 3 acceptance criteria"
],
"depends_on": [1],
"output": "implementation"
}
],
"target_files": ["file:function:lines", "path/to/NewFile.ts"]
"target_files": [
"src/auth/auth.service.ts",
"src/auth/auth.controller.ts",
"src/auth/auth.middleware.ts",
"src/auth/auth.types.ts",
"tests/auth/auth.test.ts",
"src/users/users.service.ts:validateUser:45-60",
"src/utils/utils.ts:hashPassword:120-135"
]
}
}
```
@@ -285,6 +320,35 @@ Use `analysis_results.complexity` or task count to determine structure:
- **Re-scope required**: Maximum 10 tasks hard limit
- If analysis_results contains >10 tasks, consolidate or request re-scoping
## Quantification Requirements (MANDATORY)
**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
**Core Rules**:
1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
**Standard Formats**:
- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
**Validation Checklist** (Apply to every generated task JSON):
- [ ] Every requirement contains explicit count or enumerated list
- [ ] Every acceptance criterion is measurable with verification command
- [ ] Every modification_point specifies exact targets (files/functions/lines)
- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
- [ ] Each implementation step has its own acceptance criteria
**Examples**:
- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"`
- ❌ BAD: `"Implement new commands"`
- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"`
- ❌ BAD: `"All commands implemented successfully"`
## Quality Standards
**Planning Principles:**
@@ -305,6 +369,7 @@ Use `analysis_results.complexity` or task count to determine structure:
## Key Reminders
**ALWAYS:**
- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations
- **Use provided context package**: Extract all information from structured context
- **Respect memory-first rule**: Use provided content (already loaded from memory/file)
- **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
@@ -313,6 +378,7 @@ Use `analysis_results.complexity` or task count to determine structure:
- **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
- **Use session paths**: Construct all paths using provided session_id
- **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
**NEVER:**
- Load files directly (use provided context package instead)

View File

@@ -1,7 +1,7 @@
---
name: plan
description: 5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
argument-hint: "[--cli-execute] \"text description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -20,7 +20,7 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
2. **Phase 1 executes** → Session discovery → Auto-continues
3. **Phase 2 executes** → Context gathering → Auto-continues
4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
5. **Phase 4 executes** → Task generation (task-generate-agent) → Reports final summary
**Auto-Continue Mechanism**:
- TodoList tracks current phase status
@@ -28,11 +28,6 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
- All phases run autonomously without user interaction (clarification handled in brainstorm phase)
- Progress updates shown at each phase for visibility
**Execution Modes**:
- **Manual Mode** (default): Use `/workflow:tools:task-generate`
- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
## Core Rules
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
@@ -159,24 +154,18 @@ CONTEXT: Existing user database schema, REST API endpoints
- Task generation translates high-level role analyses into concrete, actionable work items
- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
**Command Selection**:
- Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
- Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
- CLI Execute: Add `--cli-execute` flag to either command
**Flag Combination**:
- `--cli-execute` alone: Manual task generation with CLI execution
- `--agent --cli-execute`: Agent task generation with CLI execution
**Command Examples**:
**Command**:
```bash
# Manual with CLI execution
/workflow:tools:task-generate --session WFS-auth --cli-execute
# Default (agent mode)
SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")
# Agent with CLI execution
/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
# With CLI execution
SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId] --cli-execute")
```
**Flag**:
- `--cli-execute`: Generate tasks with Codex execution commands
**Input**: `sessionId` from Phase 1
**Validation**:
@@ -296,7 +285,7 @@ Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
↓ Output: Modified brainstorm artifacts (NO report file)
↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
Phase 4: task-generate[--agent] --session sessionId
Phase 4: task-generate-agent --session sessionId [--cli-execute]
↓ Input: sessionId + resolved brainstorm artifacts + session memory
↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
@@ -333,9 +322,8 @@ Return summary to user
- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
- Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
- **Build Phase 4 command** based on flags:
- Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
- Add `--session [sessionId]`
- **Build Phase 4 command**:
- Base command: `/workflow:tools:task-generate-agent --session [sessionId]`
- Add `--cli-execute` if flag present
- Pass session ID to Phase 4 command
- Verify all Phase 4 outputs
@@ -380,8 +368,7 @@ CONSTRAINTS: [Limitations or boundaries]
- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
- `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
- `/compact` - Phase 3: Memory optimization (if context approaching limits)
- `/workflow:tools:task-generate` - Phase 4: Generate task JSON files with manual approach
- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach (when `--agent` flag used)
- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach
**Follow-up Commands**:
- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution

View File

@@ -1,7 +1,7 @@
---
name: tdd-plan
description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
argument-hint: "[--agent] \"feature description\"|file.md"
argument-hint: "[--cli-execute] \"feature description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -12,8 +12,8 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
**This command is a pure orchestrator**: Execute 5 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation.
**Execution Modes**:
- **Manual Mode** (default): Use `/workflow:tools:task-generate-tdd`
- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-tdd --agent`
- **Agent Mode** (default): Use `/workflow:tools:task-generate-tdd` (autonomous agent-driven)
- **CLI Mode** (`--cli-execute`): Use `/workflow:tools:task-generate-tdd --cli-execute` (Gemini/Qwen)
## Core Rules
@@ -129,8 +129,8 @@ TEST_FOCUS: [Test scenarios]
### Phase 5: TDD Task Generation
**Command**:
- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
- Agent Mode (default): `/workflow:tools:task-generate-tdd --session [sessionId]`
- CLI Mode (`--cli-execute`): `/workflow:tools:task-generate-tdd --session [sessionId] --cli-execute`
**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
@@ -373,8 +373,8 @@ Supports action-planning-agent for more autonomous TDD planning with:
- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
- `/compact` - Phase 4: Memory optimization (if context approaching limits)
- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD task chains with Red-Green-Refactor cycles
- `/workflow:tools:task-generate-tdd --agent` - Phase 5: Generate TDD tasks with agent-driven approach (when `--agent` flag used)
- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks with agent-driven approach (default, autonomous)
- `/workflow:tools:task-generate-tdd --cli-execute` - Phase 5: Generate TDD tasks with CLI tools (Gemini/Qwen, when `--cli-execute` flag used)
**Follow-up Commands**:
- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution

View File

@@ -473,9 +473,9 @@ WFS-test-[session]/
- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs with fix cycle specification
- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks

View File

@@ -337,9 +337,9 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
- `/workflow:session:start` - Phase 1: Create independent test workflow session
- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
- `/workflow:tools:test-task-generate` - Phase 4: Generate test generation and execution task JSONs
- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks

View File

@@ -24,6 +24,7 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
| **Generate Strategies** | Provide 2-4 resolution options per conflict |
| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
| **User Decision** | Present options, never auto-apply |
| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
## Conflict Categories

View File

@@ -163,155 +163,50 @@ If conflict_risk was medium/high, modifications have been applied to:
## 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
**Agent Configuration Reference**: All task generation rules, quantification requirements, quality standards, and execution details are defined in action-planning-agent.
**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)
Refer to: @.claude/agents/action-planning-agent.md for:
- Task Decomposition Standards
- Quantification Requirements (MANDATORY)
- 5-Field Task JSON Schema
- IMPL_PLAN.md Structure
- TODO_LIST.md Format
- Execution Flow & Quality Validation
### Required Outputs
### Required Outputs Summary
#### 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)
- **Location**: `.workflow/{session-id}/.task/`
- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
- **Schema**: 5-field structure (id, title, status, meta, context, flow_control) with artifacts integration
- **Details**: See action-planning-agent.md § Task JSON Generation
#### 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
- **Location**: `.workflow/{session-id}/IMPL_PLAN.md`
- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
- **Details**: See action-planning-agent.md § Implementation Plan Creation
#### 3. TODO_LIST.md
**Location**: .workflow/{session-id}/TODO_LIST.md
**Structure**:
\`\`\`markdown
# Tasks: {Session Topic}
- **Location**: `.workflow/{session-id}/TODO_LIST.md`
- **Format**: Hierarchical task list with status indicators (▸, [ ], [x]) and JSON links
- **Details**: See action-planning-agent.md § TODO List Generation
## 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)
### Agent Execution Summary
- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
**Key Steps** (Detailed instructions in action-planning-agent.md):
1. Load task JSON template from provided path
2. Extract and decompose tasks with quantification
3. Generate task JSON files enforcing quantification requirements
4. Create IMPL_PLAN.md using template
5. Generate TODO_LIST.md matching task JSONs
6. Update session state
## 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
**Quality Gates** (Full checklist in action-planning-agent.md):
- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
- ✓ Task count ≤10 (hard limit)
- ✓ Artifact references mapped correctly
- ✓ MCP tool integration added
- ✓ Documents follow template structure
## Output

View File

@@ -1,14 +1,28 @@
---
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(*)
description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
argument-hint: "--session WFS-session-id [--cli-execute]"
examples:
- /workflow:tools:task-generate-tdd --session WFS-auth
- /workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
---
# TDD Task Generation Command
# Autonomous TDD Task Generation Command
## Overview
Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
Autonomous TDD 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. Generates complete Red-Green-Refactor cycles contained within each task.
## 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 TDD 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`)
- **TDD-First**: Every feature starts with a failing test (Red phase)
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations
## Task Strategy & Philosophy
@@ -44,359 +58,329 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
- **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
### Phase 1: Discovery & Context Loading
**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
**Agent Context Package**:
```javascript
{
"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
"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
"workflow_type": "tdd",
"session_metadata": {
// If in memory: use cached content
// Else: Load from .workflow/{session-id}/workflow-session.json
},
"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
"brainstorm_artifacts": {
// Loaded from context-package.json → brainstorm_artifacts section
"role_analyses": [
{
"cycle": 1,
"feature": "Specific functionality",
"test_focus": "What to test",
"expected_failure": "Why test should fail initially"
"role": "system-architect",
"files": [{"path": "...", "type": "primary|supplementary"}]
}
],
"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
"guidance_specification": {"path": "...", "exists": true},
"synthesis_output": {"path": "...", "exists": true},
"conflict_resolution": {"path": "...", "exists": true} // if conflict_risk >= medium
},
"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"
}
}
"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
},
"test_context_package_path": ".workflow/{session-id}/.process/test-context-package.json",
"test_context_package": {
// Existing test patterns and coverage analysis
},
"mcp_capabilities": {
"code_index": true,
"exa_code": true,
"exa_web": true
}
}
```
**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)
**Discovery Actions**:
1. **Load Session Context** (if not in memory)
```javascript
if (!memory.has("workflow-session.json")) {
Read(.workflow/{session-id}/workflow-session.json)
}
```
#### IMPL_PLAN.md Structure
2. **Load Context Package** (if not in memory)
```javascript
if (!memory.has("context-package.json")) {
Read(.workflow/{session-id}/.process/context-package.json)
}
```
Generate IMPL_PLAN.md with 8-section structure:
3. **Load Test Context Package** (if not in memory)
```javascript
if (!memory.has("test-context-package.json")) {
Read(.workflow/{session-id}/.process/test-context-package.json)
}
```
**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
---
4. **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));
```
5. **Load Conflict Resolution** (from context-package.json, if exists)
```javascript
if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
}
```
6. **Code Analysis with Native Tools** (optional - enhance understanding)
```bash
# Find relevant test files and patterns
find . -name "*test*" -type f
rg "describe|it\(|test\(" -g "*.ts"
```
7. **MCP External Research** (optional - gather TDD best practices)
```javascript
// Get external TDD examples and patterns
mcp__exa__get_code_context_exa(
query="TypeScript TDD best practices Red-Green-Refactor",
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";
```
**8 Sections Structure**:
**Agent Invocation**:
```javascript
Task(
subagent_type="action-planning-agent",
description="Generate TDD task JSON and implementation plan",
prompt=`
## Execution Context
```markdown
# Implementation Plan: {Project Title}
**Session ID**: WFS-{session-id}
**Workflow Type**: TDD
**Execution Mode**: {agent-mode | cli-execute-mode}
**Task JSON Template Path**: {template_path}
## 1. Summary
- Core requirements and objectives (2-3 paragraphs)
- TDD-specific technical approach
## Phase 1: Discovery Results (Provided Context)
## 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
### Session Metadata
{session_metadata_content}
## 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
### Role Analyses (Enhanced by Synthesis)
{role_analyses_content}
- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
## 4. Implementation Strategy
- Execution Strategy (TDD Cycles: Red-Green-Refactor)
- Architectural Approach
- Key Dependencies (Task dependency graph)
- Testing Strategy (Coverage targets, Quality gates)
### Artifacts Inventory
- **Guidance Specification**: {guidance_spec_path}
- **Role Analyses**: {role_analyses_list}
## 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
### Context Package
{context_package_summary}
- Includes conflict_risk assessment
## 6. Implementation Plan (Detailed Phased Breakdown)
- Execution Strategy (feature-by-feature sequential)
- Phase breakdown (Phase 1, Phase 2, etc.)
- Resource Requirements (Team, Dependencies, Infrastructure)
### Test Context Package
{test_context_package_summary}
- Existing test patterns, framework config, coverage analysis
## 7. Risk Assessment & Mitigation
- Risk table (Risk, Impact, Probability, Mitigation, Owner)
- Critical Risks (TDD-specific)
- Monitoring Strategy
### 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)
## 8. Success Criteria
- Functional Completeness
- Technical Quality (Test coverage ≥80%)
- Operational Readiness
- TDD Compliance
### MCP Analysis Results (Optional)
**Code Structure**: {mcp_code_index_results}
**External Research**: {mcp_exa_research_results}
## Phase 2: TDD Document Generation Task
**Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent.
Refer to: @.claude/agents/action-planning-agent.md for:
- TDD Task Decomposition Standards
- Red-Green-Refactor Cycle Requirements
- Quantification Requirements (MANDATORY)
- 5-Field Task JSON Schema
- IMPL_PLAN.md Structure (TDD variant)
- TODO_LIST.md Format
- TDD Execution Flow & Quality Validation
### TDD-Specific Requirements Summary
#### Task Structure Philosophy
- **1 feature = 1 task** containing complete TDD cycle internally
- Each task executes Red-Green-Refactor phases sequentially
- Task count = Feature count (typically 5 features = 5 tasks)
- Subtasks only when complexity >2500 lines or >6 files per cycle
- **Maximum 10 tasks** (hard limit for TDD workflows)
#### TDD Cycle Mapping
- **Simple features**: IMPL-N with internal Red-Green-Refactor phases
- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks)
- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage
#### Required Outputs Summary
##### 1. TDD Task JSON Files (.task/IMPL-*.json)
- **Location**: `.workflow/{session-id}/.task/`
- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
- **Schema**: 5-field structure with TDD-specific metadata
- `meta.tdd_workflow`: true (REQUIRED)
- `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
- `meta.use_codex`: false (manual fixes by default)
- `context.tdd_cycles`: Array with quantified test cases and coverage
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
1. Red Phase (`tdd_phase: "red"`): Write failing tests
2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
- **Details**: See action-planning-agent.md § TDD Task JSON Generation
##### 2. IMPL_PLAN.md (TDD Variant)
- **Location**: `.workflow/{session-id}/IMPL_PLAN.md`
- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
##### 3. TODO_LIST.md
- **Location**: `.workflow/{session-id}/TODO_LIST.md`
- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
- **Status**: ▸ (container), [ ] (pending), [x] (completed)
- **Details**: See action-planning-agent.md § TODO List Generation
### Quantification Requirements (MANDATORY)
**Core Rules**:
1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list
2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%")
3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts
4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts
**TDD Phase Formats**:
- **Red Phase**: "Write N test cases: [test1, test2, ...]"
- **Green Phase**: "Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"
- **Refactor Phase**: "Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"
- **Acceptance**: "All N tests pass with >=X% coverage: verify by [test command]"
**Validation Checklist**:
- [ ] Every Red phase specifies exact test case count with enumerated list
- [ ] Every Green phase enumerates files, functions, and estimated line counts
- [ ] Every Refactor phase lists specific improvements with counts
- [ ] Every acceptance criterion includes measurable coverage percentage
- [ ] tdd_cycles array contains test_count and test_cases for each cycle
- [ ] No vague language ("comprehensive", "complete", "thorough")
### Agent Execution Summary
**Key Steps** (Detailed instructions in action-planning-agent.md):
1. Load task JSON template from provided path
2. Extract and decompose features with TDD cycles
3. Generate TDD task JSON files enforcing quantification requirements
4. Create IMPL_PLAN.md using TDD template variant
5. Generate TODO_LIST.md with TDD phase indicators
6. Update session state with TDD metadata
**Quality Gates** (Full checklist in action-planning-agent.md):
- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
- ✓ Task count ≤10 (hard limit)
- ✓ Each task has meta.tdd_workflow: true
- ✓ Each task has exactly 3 implementation steps with tdd_phase field
- ✓ Green phase includes test-fix cycle logic
- ✓ Artifact references mapped correctly
- ✓ MCP tool integration added
- ✓ Documents follow TDD template structure
## Output
Generate all three documents and report completion status:
- TDD task JSON files created: N files (IMPL-*.json)
- TDD cycles configured: N cycles with quantified test cases
- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
- Test context integrated: existing patterns and coverage
- MCP enhancements: code-index, exa-research
- Session ready for TDD execution: /workflow:execute
`
)
```
### Phase 4: TODO_LIST.md Generation
### Agent Context Passing
Generate task list with internal TDD phase indicators:
**Memory-Aware Context Assembly**:
```javascript
// Assemble context package for agent
const agentContext = {
session_id: "WFS-[id]",
workflow_type: "tdd",
**For Simple Features (1 task per feature)**:
```markdown
## TDD Implementation Tasks
// 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),
### Feature 1: {Feature Name}
- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
- Internal phases: Red → Green → Refactor
- Dependencies: None
context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
### Feature 2: {Feature Name}
- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
- Internal phases: Red → Green → Refactor
- Dependencies: IMPL-1
```
context_package: memory.has("context-package.json")
? memory.get("context-package.json")
: Read(".workflow/WFS-[id]/.process/context-package.json"),
**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
```
test_context_package_path: ".workflow/WFS-[id]/.process/test-context-package.json",
**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
```
test_context_package: memory.has("test-context-package.json")
? memory.get("test-context-package.json")
: Read(".workflow/WFS-[id]/.process/test-context-package.json"),
### Phase 5: Session State Update
// Extract brainstorm artifacts from context package
brainstorm_artifacts: extractBrainstormArtifacts(context_package),
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
// 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()
}
```
**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)
## TDD Task Structure Reference
This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
**Quick Reference**:
- Each TDD task contains complete Red-Green-Refactor cycle
- Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks)
- Required metadata: `meta.tdd_workflow: true`, `meta.max_iterations: 3`
- Flow control: Exactly 3 steps with `tdd_phase` field (red, green, refactor)
- Context: `tdd_cycles` array with quantified test cases and coverage
- See Phase 2 agent prompt for full schema and requirements
## Output Files Structure
```
@@ -465,52 +449,30 @@ Update workflow-session.json with TDD metadata:
## Integration & Usage
### Command Chain
- **Called By**: `/workflow:tdd-plan` (Phase 4)
- **Calls**: Gemini CLI for TDD breakdown
- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
**Command Chain**:
- Called by: `/workflow:tdd-plan` (Phase 4)
- Invokes: `action-planning-agent` for autonomous task generation
- Followed by: `/workflow:execute`, `/workflow:tdd-verify`
### Basic Usage
**Basic Usage**:
```bash
# Manual mode (default)
# Agent mode (default, autonomous execution)
/workflow:tools:task-generate-tdd --session WFS-auth
# Agent mode (autonomous task generation)
/workflow:tools:task-generate-tdd --session WFS-auth --agent
# CLI tool mode (use Gemini/Qwen for generation)
/workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
```
### Expected Output
```
TDD task generation complete for session: WFS-auth
**Execution Modes**:
- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen with cli-mode task template
Features analyzed: 5
Total tasks: 5 (1 task per feature with internal TDD cycles)
Task breakdown:
- Simple features: 4 tasks (IMPL-1 to IMPL-4)
- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
- Total task count: 6 (within 10-task limit)
Structure:
- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
- IMPL-4: Role Management (Internal: Red → Green → Refactor)
- IMPL-5: Payment System (Container)
- IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
- IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
Plans generated:
- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
TDD Configuration:
- Each task contains complete Red-Green-Refactor cycle
- Green phase includes test-fix cycle (max 3 iterations)
- Auto-revert on max iterations reached
Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
```
**Output**:
- TDD task JSON files in `.task/` directory (IMPL-N.json format)
- IMPL_PLAN.md with TDD Implementation Tasks section
- TODO_LIST.md with internal TDD phase indicators
- Session state updated with task count and TDD metadata
- MCP enhancements integrated (if available)
## Test Coverage Analysis Integration

View File

@@ -45,8 +45,33 @@ This command is built on a set of core principles to ensure efficient and reliab
- **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
- **Quantification-Enforced**: **NEW** - All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations to prevent ambiguity (e.g., "17 commands: [list]" not "implement commands")
- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
## 3.5. Quantification Requirements (MANDATORY)
**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
**Core Rules**:
1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
**Standard Formats**:
- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
**Validation Checklist**:
- [ ] Every requirement contains explicit count or enumerated list
- [ ] Every acceptance criterion is measurable with verification command
- [ ] Every modification_point specifies exact targets (files/functions/lines)
- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
- [ ] Each implementation step has its own acceptance criteria
## 4. Execution Flow
The command follows a streamlined, three-step process to convert analysis into executable tasks.
@@ -59,13 +84,39 @@ The process begins by gathering all necessary inputs. It follows a **Memory-Firs
### 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`.
**Phase 2.1: Quantification Extraction (NEW - CRITICAL)**
1. **Count Extraction**: Scan analysis documents for quantifiable information:
- Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features")
- Identify enumerated lists (bullet points, numbered lists, comma-separated items)
- Extract explicit counts from tables, diagrams, or structured data
- Store extracted counts with their context (what is being counted)
2. **List Enumeration**: Build explicit lists for each deliverable:
- If analysis says "implement session commands", enumerate ALL commands: [start, resume, list, complete, archive]
- If analysis mentions "create categories", list ALL categories: [literature, experiment, data-analysis, visualization, context]
- If analysis describes "modify functions", list ALL functions with line numbers
- Maintain full enumerations (no "..." unless list exceeds 20 items)
3. **Verification Method Assignment**: For each deliverable, determine verification approach:
- File count: `ls {path}/*.{ext} | wc -l = {count}`
- Directory existence: `ls {parent}/ | grep -E '(name1|name2|...)' | wc -l = {count}`
- Test coverage: `pytest --cov={module} --cov-report=term | grep TOTAL | awk '{print $4}' >= {percentage}`
- Function existence: `grep -E '(func1|func2|...)' {file} | wc -l = {count}`
4. **Ambiguity Detection**: Flag vague language for replacement:
- Detect words: "complete", "comprehensive", "reorganize", "refactor", "implement", "create" without counts
- Require quantification: "implement" → "implement {N} {items}: [{list}]"
- Reject unquantified deliverables
**Phase 2.2: Task Definition & Grouping**
1. **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies from quantified analysis
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.
* 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.
@@ -167,38 +218,82 @@ function assignExecutionGroups(tasks) {
The command produces three key documents and a directory of task files.
### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
Each task JSON embeds all necessary context, artifacts, and execution steps using this schema:
**Top-Level Fields**:
- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
- `title`: Descriptive task name
- `status`: Task state (`pending|active|completed|blocked|container`)
- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
- `meta`: Task metadata
- `context`: Task-specific context and requirements
- `flow_control`: Execution steps and workflow
**Meta Object**:
- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`)
- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`)
- `execution_group`: Parallelization group ID or null
- `context_signature`: Hash for context-based grouping
**Context Object**:
- `requirements`: Quantified implementation requirements (with counts and explicit lists)
- `focus_paths`: Target directories/files (absolute or relative paths)
- `acceptance`: Measurable acceptance criteria (with verification commands)
- `parent`: Parent task ID for subtasks
- `depends_on`: Prerequisite task IDs
- `inherited`: Shared patterns and dependencies from parent
- `shared_context`: Tech stack and conventions
- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage
**Flow Control Object**:
- `pre_analysis`: Context loading and preparation steps
- `load_context_package`: Load smart context and artifact catalog
- `load_role_analysis_artifacts`: Load role analyses dynamically from context package
- `load_planning_context`: Load finalized decisions with resolved conflicts
- `codebase_exploration`: Discover existing patterns
- `analyze_task_patterns`: Identify modification targets
- `implementation_approach`: Execution steps
- **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously)
- **CLI Mode**: Steps include `command` field with CLI tool invocation
- `target_files`: Specific files/functions/lines to modify
**Key Characteristics**:
- **Quantification**: All requirements/acceptance use explicit counts and enumerations
- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`)
- **Context Intelligence**: References context-package.json for smart context and artifact paths
- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts
**Example Task JSON**:
```json
{
"id": "IMPL-N[.M]",
"title": "Descriptive task name",
"status": "pending|active|completed|blocked|container",
"context_package_path": ".workflow/WFS-[session]/.process/context-package.json",
"id": "IMPL-1",
"title": "Implement feature X with Y components",
"status": "pending",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"meta": {
"type": "feature|bugfix|refactor|test-gen|test-fix|docs",
"agent": "@code-developer|@test-fix-agent|@universal-executor",
"execution_group": "group-id|null",
"context_signature": "hash-of-focus_paths-and-artifacts"
"type": "feature",
"agent": "@code-developer",
"execution_group": "parallel-abc123",
"context_signature": "hash-value"
},
"context": {
"requirements": ["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": []},
"requirements": [
"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]",
"Create 3 directories: [dir1/, dir2/, dir3/]",
"Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]"
],
"focus_paths": ["D:\\project\\src\\module", "./tests/module"],
"acceptance": [
"5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5",
"3 directories exist: verify by ls -d dir*/ | wc -l = 3",
"All tests pass: pytest tests/ --cov=src/module (>=80% coverage)"
],
"depends_on": [],
"artifacts": [
{
"path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
"path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
"priority": "highest",
"usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
},
{
"path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
"priority": "high",
"usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place"
"usage": "Architecture decisions and API specifications"
}
]
},
@@ -206,18 +301,14 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
"pre_analysis": [
{
"step": "load_context_package",
"action": "Load context package for artifact paths",
"note": "Context package path is now at top-level field: context_package_path",
"commands": [
"Read({{context_package_path}})"
],
"action": "Load context package for artifact paths and smart context",
"commands": ["Read({{context_package_path}})"],
"output_to": "context_package",
"on_error": "fail"
},
{
"step": "load_role_analysis_artifacts",
"action": "Load role analyses from context-package.json (supports multiple files per role)",
"note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
"action": "Load role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
@@ -225,73 +316,36 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
],
"output_to": "role_analysis_artifacts",
"on_error": "skip_optional"
},
{
"step": "load_planning_context",
"action": "Load plan-generated context intelligence with resolved conflicts",
"note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.",
"commands": [
"Read({{context_package_path}})",
"Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)"
],
"output_to": "planning_context",
"on_error": "fail",
"usage_guidance": {
"context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)",
"guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)"
}
},
{
"step": "codebase_exploration",
"action": "Explore codebase using native tools",
"command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")",
"output_to": "codebase_structure"
},
{
"step": "analyze_task_patterns",
"action": "Analyze existing code patterns and identify modification targets",
"commands": [
"bash(cd \"[focus_paths]\")",
"bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
],
"output_to": "task_context_with_targets",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement task following role analyses and context",
"description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.",
"title": "Implement feature following role analyses",
"description": "Implement feature X using requirements from role analyses and context package",
"modification_points": [
"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"
"Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]",
"Modify funcA() in file1.ts lines 10-25: add validation logic",
"Modify funcB() in file2.ts lines 40-60: integrate with new API"
],
"logic_flow": [
"Load role analyses (requirements, design, enhancements from synthesis)",
"Load guidance-specification.md (finalized decisions with resolved conflicts if any)",
"Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)",
"Extract requirements and design decisions from role documents",
"Review synthesis enhancements and clarifications",
"Use finalized decisions (conflicts already resolved if applicable)",
"Identify modification targets using context package",
"Implement following role requirements and design specs",
"Consult role artifacts for detailed specifications when needed",
"Load role analyses and context package",
"Extract requirements and design decisions",
"Implement commands following existing patterns",
"Update functions with new logic",
"Validate against acceptance criteria"
],
"depends_on": [],
"output": "implementation"
}
],
"target_files": ["file:function:lines"]
"target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"]
}
}
```
**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`).
### 6.2. IMPL_PLAN.md Structure
This document provides a high-level overview of the entire implementation plan.
@@ -585,194 +639,7 @@ Artifacts are mapped to tasks based on their relevance to the task's domain.
This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
## 8. CLI Execute Mode Details
When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
**Key Points**:
- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
### Example 1: Agent Mode - Simple Task (Default, No Command)
```json
{
"id": "IMPL-001",
"title": "Implement user authentication module",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context": {
"depends_on": [],
"focus_paths": ["src/auth"],
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
"acceptance": [
"JWT token generation working",
"Login and registration endpoints implemented",
"Tests passing with >70% coverage"
]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_role_analyses",
"action": "Load role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analyses",
"on_error": "fail"
},
{
"step": "load_context",
"action": "Load context package for project structure",
"commands": ["Read({{context_package_path}})"],
"output_to": "context_pkg",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement JWT-based authentication",
"description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns",
"modification_points": [
"Create auth service with JWT generation",
"Implement login endpoint with credential validation",
"Implement registration endpoint with user creation",
"Add JWT middleware for route protection"
],
"logic_flow": [
"User registers → validate input → hash password → create user",
"User logs in → validate credentials → generate JWT → return token",
"Protected routes → validate JWT → extract user → allow access"
],
"depends_on": [],
"output": "auth_implementation"
}
],
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"]
}
}
```
### Example 2: CLI Execute Mode - Single Codex Step
```json
{
"id": "IMPL-002",
"title": "Implement user authentication module",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context": {
"depends_on": [],
"focus_paths": ["src/auth"],
"requirements": ["JWT-based authentication", "Login and registration endpoints"],
"acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_role_analyses",
"action": "Load role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analyses",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement authentication with Codex",
"description": "Create JWT-based authentication module",
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
"logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
"depends_on": [],
"output": "auth_implementation"
}
],
"target_files": ["src/auth/service.ts", "src/auth/middleware.ts"]
}
}
```
### Example 3: CLI Execute Mode - Multi-Step with Resume
```json
{
"id": "IMPL-003",
"title": "Implement role-based access control",
"context_package_path": ".workflow/WFS-session/.process/context-package.json",
"context": {
"depends_on": ["IMPL-002"],
"focus_paths": ["src/auth", "src/middleware"],
"requirements": ["User roles and permissions", "Route protection middleware"],
"acceptance": ["RBAC models created", "Middleware working", "Management API complete"]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_context",
"action": "Load context and role analyses from context-package.json",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "full_context",
"on_error": "fail"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Create RBAC models",
"description": "Define role and permission data models",
"command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Define role model", "Define permission model", "Create migrations"],
"logic_flow": ["Design schema", "Implement models", "Generate migrations"],
"depends_on": [],
"output": "rbac_models"
},
{
"step": 2,
"title": "Implement RBAC middleware",
"description": "Create route protection middleware using models from step 1",
"command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
"logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
"depends_on": [1],
"output": "rbac_middleware"
},
{
"step": 3,
"title": "Add role management API",
"description": "Create CRUD endpoints for roles and permissions",
"command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
"modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
"logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
"depends_on": [2],
"output": "role_management_api"
}
],
"target_files": [
"src/models/Role.ts",
"src/models/Permission.ts",
"src/middleware/rbac.ts",
"src/routes/roles.ts"
]
}
}
```
**Pattern Summary**:
- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
## 9. Error Handling
## 8. Error Handling
### Input Validation Errors
| Error | Cause | Resolution |
@@ -795,21 +662,19 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
| Invalid format | Corrupted file | Skip artifact loading |
| Path invalid | Moved/deleted | Update references |
## 10. Integration & Usage
## 10. Usage & Related Commands
### Command Chain
- **Called By**: `/workflow:plan` (Phase 4)
- **Calls**: None (terminal command)
- **Followed By**: `/workflow:execute`, `/workflow:status`
### Basic Usage
**Basic Usage**:
```bash
/workflow:tools:task-generate --session WFS-auth
/workflow:tools:task-generate --session WFS-auth [--cli-execute]
```
## 11. Related Commands
- `/workflow:plan` - Orchestrates entire planning
- `/workflow:plan --cli-execute` - Planning with CLI execution mode
- `/workflow:tools:context-gather` - Provides context package
- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional)
**Workflow Integration**:
- Called by: `/workflow:plan` (task generation phase)
- Followed by: `/workflow:execute`, `/workflow:status`
**Related Commands**:
- `/workflow:plan` - Orchestrates entire planning workflow
- `/workflow:tools:context-gather` - Provides context package input
- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed)
- `/workflow:execute` - Executes generated tasks

View File

@@ -1,6 +1,6 @@
---
name: test-task-generate
description: Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex
description: Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase
argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
examples:
- /workflow:tools:test-task-generate --session WFS-test-auth
@@ -9,10 +9,23 @@ examples:
- /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
---
# Test Task Generation Command
# Autonomous 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).
Autonomous test-fix task JSON generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes. Generates specialized test-fix tasks with comprehensive test-fix-retest cycle specification.
## 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 test research
- **Pre-Selected Templates**: Command selects correct test 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
- **Test-First**: Generate comprehensive test coverage before execution
- **Iterative Refinement**: Test-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
## Execution Modes
@@ -24,583 +37,278 @@ Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle
- **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
### Phase 1: Discovery & Context Loading
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
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
**Agent Context Package**:
```javascript
{
"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"
"session_id": "WFS-test-[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
"workflow_type": "test_session",
"use_codex": true | false, // Determined by --use-codex flag
"session_metadata": {
// If in memory: use cached content
// Else: Load from .workflow/{test-session-id}/workflow-session.json
},
"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"
]
}
"test_analysis_results_path": ".workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md",
"test_analysis_results": {
// If in memory: use cached content
// Else: Load from TEST_ANALYSIS_RESULTS.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}"
]
"test_context_package_path": ".workflow/{test-session-id}/.process/test-context-package.json",
"test_context_package": {
// Existing test patterns and coverage analysis
},
"source_session_id": "[source-session-id]", // if exists
"source_session_summaries": {
// Implementation context from source session
},
"mcp_capabilities": {
"code_index": true,
"exa_code": true,
"exa_web": true
}
}
```
#### IMPL-002.json - Test Execution & Fix Cycle Task
**Discovery Actions**:
1. **Load Test Session Context** (if not in memory)
```javascript
if (!memory.has("workflow-session.json")) {
Read(.workflow/{test-session-id}/workflow-session.json)
}
```
```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"
]
}
}
2. **Load TEST_ANALYSIS_RESULTS.md** (if not in memory, REQUIRED)
```javascript
if (!memory.has("TEST_ANALYSIS_RESULTS.md")) {
Read(.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md)
}
```
3. **Load Test Context Package** (if not in memory)
```javascript
if (!memory.has("test-context-package.json")) {
Read(.workflow/{test-session-id}/.process/test-context-package.json)
}
```
4. **Load Source Session Summaries** (if source_session_id exists)
```javascript
if (sessionMetadata.source_session_id) {
const summaryFiles = Bash("find .workflow/{source-session-id}/.summaries/ -name 'IMPL-*-summary.md'")
summaryFiles.forEach(file => Read(file))
}
```
5. **Code Analysis with Native Tools** (optional - enhance understanding)
```bash
# Find test files and patterns
find . -name "*test*" -type f
rg "describe|it\(|test\(" -g "*.ts"
```
6. **MCP External Research** (optional - gather test best practices)
```javascript
// Get external test examples and patterns
mcp__exa__get_code_context_exa(
query="TypeScript test generation best practices jest",
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 test-fix task JSON and implementation plan",
prompt=`
## Execution Context
**Session ID**: WFS-test-{session-id}
**Workflow Type**: Test Session
**Execution Mode**: {agent-mode | cli-execute-mode}
**Task JSON Template Path**: {template_path}
**Use Codex**: {true | false}
## Phase 1: Discovery Results (Provided Context)
### Test Session Metadata
{session_metadata_content}
- source_session_id: {source_session_id} (if exists)
- workflow_type: "test_session"
### TEST_ANALYSIS_RESULTS.md (REQUIRED)
{test_analysis_results_content}
- Coverage Assessment
- Test Framework & Conventions
- Test Requirements by File
- Test Generation Strategy
- Implementation Targets
- Success Criteria
### Test Context Package
{test_context_package_summary}
- Existing test patterns, framework config, coverage analysis
### Source Session Implementation Context (Optional)
{source_session_summaries}
- Implementation context from completed session
### MCP Analysis Results (Optional)
**Code Structure**: {mcp_code_index_results}
**External Research**: {mcp_exa_research_results}
## Phase 2: Test Task Document Generation
**Agent Configuration Reference**: All test task generation rules, test-fix cycle structure, quality standards, and execution details are defined in action-planning-agent.
Refer to: @.claude/agents/action-planning-agent.md for:
- Test Task Decomposition Standards
- Test-Fix-Retest Cycle Requirements
- 5-Field Task JSON Schema
- IMPL_PLAN.md Structure (Test variant)
- TODO_LIST.md Format
- Test Execution Flow & Quality Validation
### Test-Specific Requirements Summary
#### Task Structure Philosophy
- **Minimum 2 tasks**: IMPL-001 (test generation) + IMPL-002 (test execution & fix)
- **Expandable**: Add IMPL-003+ for complex projects (per-module, integration, etc.)
- IMPL-001: Uses @code-developer or CLI execution
- IMPL-002: Uses @test-fix-agent with iterative fix cycle
#### Test-Fix Cycle Configuration
- **Max Iterations**: 5 (for IMPL-002)
- **Diagnosis Tool**: Gemini with bug-fix template
- **Fix Application**: Manual (default) or Codex (if --use-codex flag)
- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
- **Exit Conditions**: All tests pass OR max iterations reached (auto-revert)
#### Required Outputs Summary
##### 1. Test Task JSON Files (.task/IMPL-*.json)
- **Location**: `.workflow/{test-session-id}/.task/`
- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
- **Schema**: 5-field structure with test-specific metadata
- IMPL-001: `meta.type: "test-gen"`, `meta.agent: "@code-developer"`
- IMPL-002: `meta.type: "test-fix"`, `meta.agent: "@test-fix-agent"`, `meta.use_codex: {use_codex}`
- `flow_control`: Test generation approach (IMPL-001) or test-fix cycle (IMPL-002)
- **Details**: See action-planning-agent.md § Test Task JSON Generation
##### 2. IMPL_PLAN.md (Test Variant)
- **Location**: `.workflow/{test-session-id}/IMPL_PLAN.md`
- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
- **Test-Specific Frontmatter**: workflow_type="test_session", test_framework, source_session_id
- **Test-Fix-Retest Cycle Section**: Iterative fix cycle with Gemini diagnosis
- **Details**: See action-planning-agent.md § Test Implementation Plan Creation
##### 3. TODO_LIST.md
- **Location**: `.workflow/{test-session-id}/TODO_LIST.md`
- **Format**: Task list with test generation and execution phases
- **Status**: [ ] (pending), [x] (completed)
- **Details**: See action-planning-agent.md § TODO List Generation
### Agent Execution Summary
**Key Steps** (Detailed instructions in action-planning-agent.md):
1. Load task JSON template from provided path
2. Parse TEST_ANALYSIS_RESULTS.md for test requirements
3. Generate IMPL-001 (test generation) task JSON
4. Generate IMPL-002 (test execution & fix) task JSON with use_codex flag
5. Generate additional IMPL-*.json if project complexity requires
6. Create IMPL_PLAN.md using test template variant
7. Generate TODO_LIST.md with test task indicators
8. Update session state with test metadata
**Quality Gates** (Full checklist in action-planning-agent.md):
- ✓ Minimum 2 tasks created (IMPL-001 + IMPL-002)
- ✓ IMPL-001 has test generation approach from TEST_ANALYSIS_RESULTS.md
- ✓ IMPL-002 has test-fix cycle with correct use_codex flag
- ✓ Test framework configuration integrated
- ✓ Source session context referenced (if exists)
- ✓ MCP tool integration added
- ✓ Documents follow test template structure
## Output
Generate all three documents and report completion status:
- Test task JSON files created: N files (minimum 2)
- Test requirements integrated: TEST_ANALYSIS_RESULTS.md
- Test context integrated: existing patterns and coverage
- Source session context: {source_session_id} summaries (if exists)
- MCP enhancements: code-index, exa-research
- Session ready for test execution: /workflow:execute or /workflow:test-cycle-execute
`
)
```
### Agent Context Passing
**Memory-Aware Context Assembly**:
```javascript
// Assemble context package for agent
const agentContext = {
session_id: "WFS-test-[id]",
workflow_type: "test_session",
use_codex: hasUseCodexFlag,
// Use memory if available, else load
session_metadata: memory.has("workflow-session.json")
? memory.get("workflow-session.json")
: Read(.workflow/WFS-test-[id]/workflow-session.json),
test_analysis_results_path: ".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",
test_analysis_results: memory.has("TEST_ANALYSIS_RESULTS.md")
? memory.get("TEST_ANALYSIS_RESULTS.md")
: Read(".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
test_context_package_path: ".workflow/WFS-test-[id]/.process/test-context-package.json",
test_context_package: memory.has("test-context-package.json")
? memory.get("test-context-package.json")
: Read(".workflow/WFS-test-[id]/.process/test-context-package.json"),
// Load source session summaries if exists
source_session_id: session_metadata.source_session_id || null,
source_session_summaries: session_metadata.source_session_id
? loadSourceSummaries(session_metadata.source_session_id)
: null,
// Optional MCP enhancements
mcp_analysis: executeMcpDiscovery()
}
```
### Phase 3: IMPL_PLAN.md Generation
## Test Task Structure Reference
#### Document Structure
```markdown
---
identifier: WFS-test-[session-id]
source_session: WFS-[source-session-id]
workflow_type: test_session
test_framework: jest|pytest|cargo|detected
---
This section provides quick reference for test task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
# 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
```
**Quick Reference**:
- Minimum 2 tasks: IMPL-001 (test-gen) + IMPL-002 (test-fix)
- Expandable for complex projects (IMPL-003+)
- IMPL-001: `meta.agent: "@code-developer"`, test generation approach
- IMPL-002: `meta.agent: "@test-fix-agent"`, `meta.use_codex: {flag}`, test-fix cycle
- See Phase 2 agent prompt for full schema and requirements
## Output Files Structure
```
@@ -648,29 +356,52 @@ Diagnose and fix all test failures using iterative Gemini analysis and Codex exe
## Integration & Usage
### Command Chain
- **Called By**: `/workflow:test-gen` (Phase 4)
- **Calls**: None (terminal command)
- **Followed By**: `/workflow:execute` (user-triggered)
- **Called By**: `/workflow:test-gen` (Phase 4), `/workflow:test-fix-gen` (Phase 4)
- **Invokes**: `action-planning-agent` for autonomous task generation
- **Followed By**: `/workflow:execute` or `/workflow:test-cycle-execute` (user-triggered)
### Basic Usage
```bash
# Manual fix mode (default)
# Agent mode (default, autonomous execution)
/workflow:tools:test-task-generate --session WFS-test-auth
# Automated Codex fix mode
# With automated Codex fixes for IMPL-002
/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
# CLI execution mode for IMPL-001 test generation
/workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
# Both flags combined
/workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
```
### Execution Modes
- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen/Codex with cli-mode task template for IMPL-001
- **Codex fixes** (`--use-codex`): Enables automated fixes in IMPL-002 task
### 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
- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode generation
- **--use-codex**: `meta.use_codex=true` (Codex automated fixes with resume mechanism in IMPL-002)
- **--cli-execute**: Uses CLI tool execution mode for IMPL-001 test generation
- **Both flags**: CLI generation + automated Codex fixes
### Output
- Test task JSON files in `.task/` directory (minimum 2: IMPL-001.json + IMPL-002.json)
- IMPL_PLAN.md with test generation and fix cycle strategy
- TODO_LIST.md with test task indicators
- Session state updated with test metadata
- MCP enhancements integrated (if available)
## 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
- `/workflow:test-gen` - Creates test session and calls this tool (Phase 4)
- `/workflow:test-fix-gen` - Creates test-fix session and calls this tool (Phase 4)
- `/workflow:tools:test-context-gather` - Gathers test coverage context
- `/workflow:tools:test-concept-enhanced` - Generates test strategy analysis (TEST_ANALYSIS_RESULTS.md)
- `/workflow:execute` - Executes the generated test-fix tasks
- `/workflow:test-cycle-execute` - Executes test-fix cycle with iteration management
- `@code-developer` - Agent that executes IMPL-001 (test generation)
- `@test-fix-agent` - Agent that executes IMPL-002 (test execution & fix)
## Agent Execution Notes

View File

@@ -91,16 +91,23 @@ Comprehensive command guide for Claude DMS3 workflow system covering 69 commands
**When**: New user needs guidance
**Triggers**: "新手", "getting started", "如何开始", "常用命令"
**Triggers**: "新手", "getting started", "如何开始", "常用命令", **"从0到1"**, **"全新项目"**
**Process**:
1. **Assess user background** - Ask clarifying questions if needed (coding experience? project type?)
2. **Design personalized learning path** based on their goals
3. **Curate essential commands** from `index/essential-commands.json` - Select 3-5 most relevant for their use case
4. **Provide guided first example** - Walk through ONE complete workflow with explanation
5. **Set clear next steps** - What to try next, where to get help
2. **⚠️ Identify project stage** - FROM-ZERO-TO-ONE vs FEATURE-ADDITION:
- **从0到1场景** (全新项目/产品/架构决策) → **MUST START with brainstorming workflow**
- **功能新增场景** (已有项目中添加功能) → Start with planning workflow
3. **Design personalized learning path** based on their goals and stage
4. **Curate essential commands** from `index/essential-commands.json` - Select 3-5 most relevant for their use case
5. **Provide guided first example** - Walk through ONE complete workflow with explanation, **emphasizing brainstorming for 0-to-1 scenarios**
6. **Set clear next steps** - What to try next, where to get help
**Example**: "我是新手,如何开始?" → Detect if they have a specific task OR just exploring → For specific task: provide laser-focused 3-step guide; For exploring: progressive learning path starting with simplest workflow, NOT overwhelming 14-command list
**Example 1 (从0到1)**: "我是新手,如何开始全新项目" → Identify as FROM-ZERO-TO-ONE → Emphasize brainstorming workflow (`/workflow:brainstorm:artifacts`) as mandatory first step → Explain brainstorm → plan → execute flow
**Example 2 (功能新增)**: "我是新手,如何在已有项目中添加功能?" → Identify as FEATURE-ADDITION → Guide to planning workflow (`/workflow:plan`) → Explain plan → execute → test flow
**Example 3 (探索)**: "我是新手,如何开始?" → Ask clarifying question: "是全新项目启动从0到1还是在已有项目中添加功能" → Based on answer, route to appropriate workflow
---

View File

@@ -14,6 +14,173 @@
---
## 💡 Pattern 0: 头脑风暴从0到1的第一步
**⚠️ 重要**:这是**从0到1开发的起点**!在开始编码之前,通过多角色头脑风暴明确需求、技术选型和架构决策。
**适用场景**
- 全新项目启动,需求和技术方案不明确
- 重大功能开发,涉及多个技术领域和权衡
- 架构决策,需要多角色视角分析
**流程**:话题分析 → 角色选择 → 角色问答 → 冲突解决 → 生成指导文档
### 模式 A交互式头脑风暴推荐
**特点**:通过问答交互,逐步明确需求和决策
```bash
# 步骤 1启动头脑风暴
/workflow:brainstorm:artifacts "
GOAL: 实现实时协作编辑平台
SCOPE: 支持100+用户同时在线,低延迟(<100ms),冲突自动解决
CONTEXT: MVP阶段3个月上线团队5人2前端+2后端+1全栈
" --count 3
# 系统输出 Phase 0自动收集项目上下文
# ✅ 分析现有代码库结构
# ✅ 加载相关文档
# ✅ 识别技术栈和依赖
# 系统输出 Phase 1意图分析2-4个问题
# 【问题1 - 核心挑战】实时协作的主要技术挑战?
# a) 实时数据同步
# b) 可扩展性架构
# c) 冲突解决机制
# 【问题2 - 优先级】MVP阶段最关注
# a) 功能完整性
# b) 用户体验
# c) 系统稳定性
# 请回答 (格式: 1a 2c)
# 用户输入1c 2b
# 系统输出 Phase 2角色选择推荐 count+2 个角色)
# 【角色选择】请选择 3 个角色参与头脑风暴
# a) system-architect (系统架构师) - 实时同步架构设计
# b) ui-designer (UI设计师) - 协作界面用户体验
# c) product-manager (产品经理) - 功能优先级决策
# d) data-architect (数据架构师) - 数据同步模型设计
# e) ux-expert (UX专家) - 多用户协作交互流程
# 请输入选择 (格式: 2acd 或 2a 2c 2d)
# 用户输入2acd
# 系统输出 Phase 3角色问题每个角色 3-4 个问题)
# ===== system-architect 问题 =====
# 【问题1】100+ 用户实时状态同步方案?
# a) Event Sourcing - 完整事件历史,易于回溯
# b) 集中式状态管理 - 简单直接适合MVP
# c) CRDT - 自动冲突解决,分布式友好
# 【问题2】低延迟通信协议选择
# ...
# 请回答:
# 用户输入1c 2a 3b 4c
# 系统输出 Phase 4冲突检测和解决
# 【冲突1】CRDT 与 UI 回滚期望冲突
# Background: system-architect 选择 CRDT但 ui-designer 期望回滚UI
# a) 采用 CRDT显示合并状态
# b) 切换到 OT 算法支持回滚
# c) 混合方案CRDT + 本地撤销栈
# ...
# 系统输出 Phase 5生成指导文档
# ✅ 生成 guidance-specification.md
# ✅ 记录所有决策和理由
# ✅ 标注冲突解决方案
# 📁 文件位置:.workflow/WFS-realtime-collab/.brainstorming/guidance-specification.md
# 步骤 2查看生成的指导文档
cat .workflow/WFS-*//.brainstorming/guidance-specification.md
```
### 模式 B自动并行头脑风暴快速
**特点**:自动选择角色,并行执行,快速生成多角色分析
```bash
# 步骤 1一键启动并行头脑风暴
/workflow:brainstorm:auto-parallel "
GOAL: 实现支付处理模块
SCOPE: 支持微信/支付宝/银行卡日交易10万笔99.99%可用性
CONTEXT: 金融合规要求PCI DSS认证风控系统集成
" --count 4
# 系统输出:
# ✅ Phase 0: 收集项目上下文
# ✅ Phase 1-2: artifacts 交互式框架生成
# ⏳ Phase 3: 4个角色并行分析
# - system-architect → 分析中...
# - data-architect → 分析中...
# - product-manager → 分析中...
# - subject-matter-expert → 分析中...
# ✅ Phase 4: synthesis 综合分析
# 📁 输出文件:
# - .brainstorming/guidance-specification.md (框架)
# - system-architect/analysis.md
# - data-architect/analysis.md
# - product-manager/analysis.md
# - subject-matter-expert/analysis.md
# - synthesis/final-recommendations.md
# 步骤 2查看综合建议
cat .workflow/WFS-*//.brainstorming/synthesis/final-recommendations.md
```
### 模式 C单角色深度分析特定领域
**特点**:针对特定领域问题,调用单个角色深度分析
```bash
# 系统架构分析
/workflow:brainstorm:system-architect "API 网关架构设计支持10万QPS微服务集成"
# UI 设计分析
/workflow:brainstorm:ui-designer "管理后台界面设计,复杂数据展示,操作效率优先"
# 数据架构分析
/workflow:brainstorm:data-architect "分布式数据存储方案MySQL+Redis+ES 组合"
```
### 关键点
1. **Phase 0 自动上下文收集**
- 自动分析现有代码库、文档、技术栈
- 识别潜在冲突和集成点
- 为后续问题生成提供上下文
2. **动态问题生成**
- 基于话题关键词和项目上下文生成问题
- 不使用预定义模板
- 问题直接针对你的具体场景
3. **智能角色推荐**
- 基于话题分析推荐最相关的角色
- 推荐 count+2 个角色供选择
- 每个角色都有基于话题的推荐理由
4. **输出物**
- `guidance-specification.md` - 确认的指导规范(决策、理由、集成点)
- `{role}/analysis.md` - 各角色详细分析(仅 auto-parallel 模式)
- `synthesis/final-recommendations.md` - 综合建议(仅 auto-parallel 模式)
5. **下一步**
- 头脑风暴完成后,使用 `/workflow:plan` 基于指导文档生成实施计划
- 指导文档作为规划和实现的权威参考
### 使用场景对比
| 场景 | 推荐模式 | 原因 |
|------|---------|------|
| 全新项目启动 | 交互式 (artifacts) | 需要充分澄清需求和约束 |
| 重大架构决策 | 交互式 (artifacts) | 需要深入讨论权衡 |
| 快速原型验证 | 自动并行 (auto-parallel) | 快速获得多角色建议 |
| 特定技术问题 | 单角色 (specific role) | 专注某个领域深度分析 |
---
## 📋 Pattern 1: 规划→执行(最常用)
**适用场景**:实现新功能、新模块
@@ -389,29 +556,44 @@
## 📊 工作流选择指南
**核心区分**从0到1 vs 功能新增
- **从0到1**:全新项目、新产品、重大架构决策 → **必须头脑风暴**
- **功能新增**:已有项目中添加功能 → **可直接规划**
```mermaid
graph TD
A[我要做什么?] --> B{任务类型?}
A[我要做什么?] --> B{项目阶段?}
B -->|新功能| C[规划→执行]
B -->|需要测试| D{代码是否存在?}
B -->|UI开发| E[UI设计工作流]
B -->|代码优化| F[分析→重构]
B -->|生成文档| G[文档生成]
B -->|快速实现| H[Codex YOLO]
B -->|从0到1<br/>全新项目/产品| Z[💡头脑风暴<br/>必经阶段]
B -->|功能新增<br/>已有项目| C{任务类型?}
D -->|不存在| I[TDD工作流]
D -->|已存在| J[测试生成]
Z --> Z1[/workflow:brainstorm:artifacts<br/>或<br/>/workflow:brainstorm:auto-parallel]
Z1 --> Z2[⬇️ 生成指导文档]
Z2 --> C
C --> K[/workflow:plan<br/>↓<br/>/workflow:execute]
I --> L[/workflow:tdd-plan<br/>↓<br/>/workflow:execute]
J --> M[/workflow:test-gen<br/>↓<br/>/workflow:test-cycle-execute]
E --> N[/workflow:ui-design:*]
F --> O[/cli:analyze<br/>↓<br/>/cli:mode:plan<br/>↓<br/>/cli:execute]
G --> P[/memory:docs]
H --> Q[/cli:codex-execute]
C -->|新功能| D[规划→执行]
C -->|需要测试| E{代码是否存在?}
C -->|UI开发| F[UI设计工作流]
C -->|代码优化| G[分析→重构]
C -->|生成文档| H[文档生成]
C -->|快速实现| I[Codex YOLO]
E -->|不存在| J[TDD工作流]
E -->|已存在| K[测试生成]
D --> L[/workflow:plan<br/>↓<br/>/workflow:execute]
J --> M[/workflow:tdd-plan<br/>↓<br/>/workflow:execute]
K --> N[/workflow:test-gen<br/>↓<br/>/workflow:test-cycle-execute]
F --> O[/workflow:ui-design:*]
G --> P[/cli:analyze<br/>↓<br/>/cli:mode:plan<br/>↓<br/>/cli:execute]
H --> Q[/memory:docs]
I --> R[/cli:codex-execute]
```
**说明**
- **从0到1场景**:创业项目、新产品线、系统重构 → 头脑风暴明确方向后再规划
- **功能新增场景**:现有系统添加模块、优化现有功能 → 直接进入规划或分析
---
## 💡 最佳实践
@@ -447,79 +629,24 @@ graph TD
### ❌ 避免做法
1. **不要跳过规划直接执行复杂任务**
1. **⚠️ 不要在从0到1场景跳过头脑风暴**
- ❌ 全新项目直接 `/workflow:plan`
- ✅ 先 `/workflow:brainstorm:artifacts` 明确方向再规划
2. **不要跳过规划直接执行复杂任务**
- ❌ 直接 `/cli:execute` 实现复杂功能
- ✅ 先 `/workflow:plan` 再 `/workflow:execute`
2. **不要忽略测试**
3. **不要忽略测试**
- ❌ 实现完成后不生成测试
- ✅ 使用 `/workflow:test-gen` 生成测试
3. **不要遗忘文档**
4. **不要遗忘文档**
- ❌ 代码实现后忘记更新文档
- ✅ 使用 `/memory:update-related` 自动更新
---
## 🎨 Pattern 7: UI设计工作流
**适用场景**前端UI设计和原型开发
**流程**:探索设计 / 模仿设计 / 代码导入 → 生成原型 → 集成
### 三种子模式
#### 7.1 探索式设计(新概念)
```bash
# 从提示词创建多个设计方案
/workflow:ui-design:explore-auto \
--prompt "现代化SaaS着陆页包含英雄区、特性、定价" \
--style-variants 3 \
--layout-variants 2
# 输出:
# - 3个风格变体 × 2个布局变体 = 6个原型
# - design-tokens-v1/v2/v3.json
# - layout-templates-v1/v2.json
# - compare.html对比页面
```
#### 7.2 模仿式设计(复制现有网站)
```bash
# 高保真克隆目标网站
/workflow:ui-design:imitate-auto \
--url-map "首页:https://example.com, 定价:https://example.com/pricing"
# 输出:
# - 统一的设计系统design-tokens.json
# - 页面结构layout-templates.json
# - 重建的HTML原型
```
#### 7.3 代码优先导入
```bash
# 从现有代码库提取设计系统
/workflow:ui-design:import-from-code \
--base-path ./src/components
# 输出:
# - 提取的设计令牌
# - 完整性报告
# - 改进建议
```
**关键概念**
- **关注点分离**样式design-tokens、结构layout-templates、动画animation-tokens独立
- **令牌优先**使用CSS变量而非硬编码
- **可重用性**:设计系统可跨项目复用
**详细指南**:参见 [UI Design Workflow Guide](ui-design-workflow-guide.md)
---
## 🔗 相关资源
- **快速入门**[Getting Started](getting-started.md) - 5分钟上手