catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update documentation for v5.9.6 with new commands and features

Browse Source 
- Update README_CN.md version badge to v5.9.6
- Update COMMAND_REFERENCE.md with new commands:
  - workflow:lite-fix (bug diagnosis workflow)
  - workflow:lite-execute (in-memory execution)
  - workflow:review-module-cycle (module code review)
  - workflow:review-session-cycle (session code review)
  - workflow:review-fix (automated fixing)
  - memory:docs-* CLI commands
  - memory:skill-memory, tech-research, workflow-skill-memory
- Update analyze_commands.py:
  - Add lite workflows relationships
  - Add review cycle workflows relationships
  - Update essential commands list
- Rebuild command-guide index with updated relationships

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-11-28 17:08:59 +08:00
parent 79b13f363b
commit e75cdf0b61
64 changed files with 6376 additions and 8127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
View File

@@ -59,6 +59,41 @@ Analyzes conflicts between implementation plans and existing codebase, **includi
- Module merge/split decisions
- **Requires iterative clarification until uniqueness confirmed**
## Execution Process
```
Input Parsing:
├─ Parse flags: --session, --context
└─ Validation: Both REQUIRED, conflict_risk >= medium
Phase 1: Validation
├─ Step 1: Verify session directory exists
├─ Step 2: Load context-package.json
├─ Step 3: Check conflict_risk (skip if none/low)
└─ Step 4: Prepare agent task prompt
Phase 2: CLI-Powered Analysis (Agent)
├─ Execute Gemini analysis (Qwen fallback)
├─ Detect conflicts including ModuleOverlap category
└─ Generate 2-4 strategies per conflict with modifications
Phase 3: Iterative User Interaction
└─ FOR each conflict (one by one):
├─ Display conflict with overlap_analysis (if ModuleOverlap)
├─ Display strategies (2-4 + custom option)
├─ User selects strategy
└─ IF clarification_needed:
├─ Collect answers
├─ Agent re-analysis
└─ Loop until uniqueness_confirmed (max 10 rounds)
Phase 4: Apply Modifications
├─ Step 1: Extract modifications from resolved strategies
├─ Step 2: Apply using Edit tool
├─ Step 3: Update context-package.json (mark resolved)
└─ Step 4: Output custom conflict summary (if any)
```
## Execution Flow
### Phase 1: Validation

32
.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
View File

@@ -24,6 +24,38 @@ Orchestrator command that invokes `context-search-agent` to gather comprehensive
- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
## Execution Process
```
Input Parsing:
├─ Parse flags: --session
└─ Parse: task_description (required)
Step 1: Context-Package Detection
└─ Decision (existing package):
├─ Valid package exists → Return existing (skip execution)
└─ No valid package → Continue to Step 2
Step 2: Invoke Context-Search Agent
├─ Phase 1: Initialization & Pre-Analysis
│ ├─ Load project.json as primary context
│ ├─ Initialize code-index
│ └─ Classify complexity
├─ Phase 2: Multi-Source Discovery
│ ├─ Track 1: Historical archive analysis
│ ├─ Track 2: Reference documentation
│ ├─ Track 3: Web examples (Exa MCP)
│ └─ Track 4: Codebase analysis (5-layer)
└─ Phase 3: Synthesis & Packaging
├─ Apply relevance scoring
├─ Integrate brainstorm artifacts
├─ Perform conflict detection
└─ Generate context-package.json
Step 3: Output Verification
└─ Verify context-package.json created
```
## Execution Flow
### Step 1: Context-Package Detection

150
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
View File

@@ -1,29 +1,50 @@
---
name: task-generate-agent
description: Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning
description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation
argument-hint: "--session WFS-session-id [--cli-execute]"
examples:
- /workflow:tools:task-generate-agent --session WFS-auth
- /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
---
# Autonomous Task Generation Command
# Generate Implementation Plan Command
## Overview
Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent. This command produces **planning artifacts only** - it does NOT execute code implementation. Actual code implementation requires separate execution command (e.g., /workflow:execute).
## Core Philosophy
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
- **Planning Only**: Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT implement code
- **Agent-Driven Document Generation**: Delegate plan generation to action-planning-agent
- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size
- **Two-Phase Flow**: Discovery (context gathering) → Output (planning document generation)
- **Memory-First**: Reuse loaded documents from conversation memory
- **Smart Selection**: Load synthesis_output OR guidance + relevant role analyses, NOT all role analyses
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
## Execution Lifecycle
## Execution Process
```
Input Parsing:
├─ Parse flags: --session, --cli-execute
└─ Validation: session_id REQUIRED
Phase 1: Context Preparation (Command)
├─ Assemble session paths (metadata, context package, output dirs)
└─ Provide metadata (session_id, execution_mode, mcp_capabilities)
Phase 2: Planning Document Generation (Agent)
├─ Load context package (progressive loading strategy)
├─ Generate Task JSON Files (.task/IMPL-*.json)
├─ Create IMPL_PLAN.md
└─ Generate TODO_LIST.md
```
## Document Generation Lifecycle
### Phase 1: Context Preparation (Command Responsibility)
**Command prepares session paths and metadata, agent loads content autonomously.**
**Command prepares session paths and metadata for planning document generation.**
**Session Path Structure**:
```
@@ -47,110 +68,71 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
- `execution_mode` (agent-mode | cli-execute-mode)
- `mcp_capabilities` (available MCP tools)
**Note**: Agent autonomously loads files based on context package content (dynamic, not fixed template). Brainstorming artifacts only loaded if they exist in session.
### Phase 2: Planning Document Generation (Agent Responsibility)
### Phase 2: Agent Execution (Document Generation)
**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.
**Agent Invocation**:
```javascript
Task(
subagent_type="action-planning-agent",
description="Generate task JSON and implementation plan",
description="Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
prompt=`
## Task Objective
Generate implementation plan (IMPL_PLAN.md), task JSONs, and TODO list for workflow session
## TASK OBJECTIVE
Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
## MANDATORY FIRST STEPS
1. Read session metadata: {session.session_metadata_path}
2. Load context package: {session.context_package_path}
3. **Dynamically load files based on context package content** (see below)
IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.
## Dynamic Content Loading Strategy
CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
**Load files based on what exists in context package - NOT a fixed template**
## SESSION PATHS
Input:
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
- Context Package: .workflow/active/{session-id}/.process/context-package.json
### Step 1: Always Load (Required)
- **Session Metadata** → Extract user input
- User description: Original task requirements
- Project scope and boundaries
- Technical constraints
Output:
- Task Dir: .workflow/active/{session-id}/.task/
- IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
- TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
### Step 2: Check Context Package (Conditional Loading)
## CONTEXT METADATA
Session ID: {session-id}
Planning Mode: {agent-mode | cli-execute-mode}
MCP Capabilities: {exa_code, exa_web, code_index}
**If `brainstorm_artifacts` exists in context package:**
- Load artifacts **in priority order** as listed below
- **If `brainstorm_artifacts` does NOT exist**: Skip to Step 3
**Priority Loading (when artifacts exist):**
1. **guidance-specification.md** (if `guidance_specification.exists = true`)
- Overall design framework - use as primary reference
2. **Role Analyses** (if `role_analyses[]` array exists)
- Load ALL role analysis files listed in array
- Each file path: `role_analyses[i].files[j].path`
3. **Synthesis Output** (if `synthesis_output.exists = true`)
- Integrated view with clarifications
4. **Conflict Resolution** (if `conflict_risk` = "medium" or "high")
- Check `conflict_resolution.status`
- If "resolved": Use updated artifacts (conflicts pre-addressed)
### Step 3: Extract Project Context
- `focus_areas`: Target directories for implementation
- `assets`: Existing code patterns to reuse
## Session Paths
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
- Context Package: .workflow/active/{session-id}/.process/context-package.json
- Output Task Dir: .workflow/active/{session-id}/.task/
- Output IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
- Output TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
## Context Metadata
- Session ID: {session-id}
- Execution Mode: {agent-mode | cli-execute-mode}
- MCP Capabilities Available: {exa_code, exa_web, code_index}
**Note**: Content loading is **dynamic** based on actual files in session, not a fixed template
## Expected Deliverables
1. **Task JSON Files** (.task/IMPL-*.json)
## EXPECTED DELIVERABLES
1. Task JSON Files (.task/IMPL-*.json)
- 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
- Quantified requirements with explicit counts
- Artifacts integration from context package
- Flow control with pre_analysis steps
2. **Implementation Plan** (IMPL_PLAN.md)
2. Implementation Plan (IMPL_PLAN.md)
- Context analysis and artifact references
- Task breakdown and execution strategy
- Complete structure per agent definition
3. **TODO List** (TODO_LIST.md)
- Hierarchical structure with status indicators (▸, [ ], [x])
3. TODO List (TODO_LIST.md)
- Hierarchical structure (containers, pending, completed markers)
- Links to task JSONs and summaries
- Matches task JSON hierarchy
## Quality Standards
- Task count ≤12 (hard limit)
- All requirements quantified (explicit counts and lists)
- Acceptance criteria measurable (verification commands)
- Artifact references mapped from context package
- All documents follow agent-defined structure
## QUALITY STANDARDS
Hard Constraints:
- Task count <= 12 (hard limit - request re-scope if exceeded)
- All requirements quantified (explicit counts and enumerated lists)
- Acceptance criteria measurable (include verification commands)
- Artifact references mapped from context package
- All documents follow agent-defined structure
## Success Criteria
- All task JSONs valid and saved to .task/ directory
- IMPL_PLAN.md created with complete structure
- TODO_LIST.md generated matching task JSONs
- Return completion status with file count
## SUCCESS CRITERIA
- All planning documents generated successfully:
- Task JSONs valid and saved to .task/ directory
- IMPL_PLAN.md created with complete structure
- TODO_LIST.md generated matching task JSONs
- Return completion status with document count and task breakdown summary
`
)
```
**Key Changes from Previous Version**:
1. **Paths over Content**: Provide file paths for agent to read, not embedded content
2. **MANDATORY FIRST STEPS**: Explicit requirement to load session metadata and context package
3. **Complete Session Paths**: All file paths provided for agent operations
4. **Emphasized Deliverables**: Clear deliverable requirements with quality standards
5. **No Agent Self-Reference**: Removed "Refer to action-planning-agent.md" (agent knows its own definition)
6. **No Template Paths**: Removed all template references (agent has complete schema/structure definitions)
、

24
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
View File

@@ -53,6 +53,30 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
- **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
## Execution Process
```
Input Parsing:
├─ Parse flags: --session, --cli-execute
└─ Validation: session_id REQUIRED
Phase 1: Discovery & Context Loading (Memory-First)
├─ Load session context (if not in memory)
├─ Load context package (if not in memory)
├─ Load test context package (if not in memory)
├─ Extract & load role analyses from context package
├─ Load conflict resolution (if exists)
└─ Optional: MCP external research
Phase 2: Agent Execution (Document Generation)
├─ Pre-agent template selection (agent-mode OR cli-execute-mode)
├─ Invoke action-planning-agent
├─ Generate TDD Task JSON Files (.task/IMPL-*.json)
│ └─ Each task: complete Red-Green-Refactor cycle internally
├─ Create IMPL_PLAN.md (TDD variant)
└─ Generate TODO_LIST.md with TDD phase indicators
```
## Execution Lifecycle
### Phase 1: Discovery & Context Loading

680
.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md
View File

@@ -1,680 +0,0 @@
---
name: task-generate
description: Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration
argument-hint: "--session WFS-session-id [--cli-execute]"
examples:
- /workflow:tools:task-generate --session WFS-auth
- /workflow:tools:task-generate --session WFS-auth --cli-execute
---
# Task Generation Command
## 1. Overview
This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
## 2. Execution Modes
This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
### Agent Mode (Default)
In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
- **Execution**: Agent reads these fields and performs the implementation autonomously
- **Context Loading**: Agent loads context via `pre_analysis` steps
- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
- **Use Case**: Standard implementation tasks where agent capability is sufficient
### CLI Execute Mode (`--cli-execute`)
When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
- **Step Structure**: Includes all default fields PLUS a `command` field
- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
## 3. Core Principles
This command is built on a set of core principles to ensure efficient and reliable task generation.
- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
- **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
- **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.
### Step 1: Input & Discovery
The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
1. **Session Validation**: Loads and validates the session from `.workflow/active/{session_id}/workflow-session.json`.
2. **Context Package Loading** (primary source): Reads `.workflow/active/{session_id}/.process/context-package.json` for smart context and artifact catalog.
3. **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
4. **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
### Step 2: Task Decomposition & Grouping
Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
**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
### Step 3: Output Generation
Finally, the command generates all the necessary output files.
1. **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
2. **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
3. **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
4. **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
## 5. Task Decomposition Strategy
The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
### Core Principles
- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
### Context Analysis for Task Grouping
The decision to merge or decompose is based on analyzing context indicators:
1. **Shared Context Indicators (→ Merge)**:
* Identical `focus_paths` (working on the same modules/files).
* Same tech stack and dependencies.
* Identical `context.artifacts` references.
* A sequential logic flow within the same feature.
* Shared test fixtures or setup.
2. **Independent Context Indicators (→ Decompose)**:
* Different `focus_paths` (separate modules).
* Different tech stacks (e.g., frontend vs. backend).
* Different `context.artifacts` (using different brainstorming outputs).
* No shared dependencies.
* Can be tested independently.
**Decomposition is only performed when**:
- Tasks have different contexts and no shared dependencies (enabling parallel execution).
- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
### Context Signature Algorithm
To automate grouping, a `context_signature` is computed for each task.
```javascript
// Compute context signature for task grouping
function computeContextSignature(task) {
const focusPathsStr = task.context.focus_paths.sort().join('|');
const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
}
```
### Execution Group Assignment
Tasks are assigned to execution groups based on their signatures and dependencies.
```javascript
// Group tasks by context signature
function groupTasksByContext(tasks) {
const groups = {};
tasks.forEach(task => {
const signature = computeContextSignature(task);
if (!groups[signature]) {
groups[signature] = [];
}
groups[signature].push(task);
});
return groups;
}
// Assign execution groups for parallel tasks
function assignExecutionGroups(tasks) {
const contextGroups = groupTasksByContext(tasks);
Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
if (groupTasks.length === 1) {
const task = groupTasks[0];
// Single task with unique context
if (!task.context.depends_on || task.context.depends_on.length === 0) {
task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
} else {
task.meta.execution_group = null; // Sequential task
}
} else {
// Multiple tasks with same context → Should be merged
console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
// Merge tasks into single task
return mergeTasks(groupTasks);
}
});
}
```
**Task Limits**:
- **Maximum 10 tasks** (hard limit).
- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
## 6. Generated Outputs
The command produces three key documents and a directory of task files.
### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
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/active/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-1",
"title": "Implement feature X with Y components",
"status": "pending",
"context_package_path": ".workflow/active/WFS-session/.process/context-package.json",
"meta": {
"type": "feature",
"agent": "@code-developer",
"execution_group": "parallel-abc123",
"context_signature": "hash-value"
},
"context": {
"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": ".workflow/active/WFS-session/.brainstorming/system-architect/analysis.md",
"priority": "highest",
"usage": "Architecture decisions and API specifications"
}
]
},
"flow_control": {
"pre_analysis": [
{
"step": "load_context_package",
"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",
"commands": [
"Read({{context_package_path}})",
"Extract(brainstorm_artifacts.role_analyses[].files[].path)",
"Read(each extracted path)"
],
"output_to": "role_analysis_artifacts",
"on_error": "skip_optional"
}
],
"implementation_approach": [
{
"step": 1,
"title": "Implement feature following role analyses",
"description": "Implement feature X using requirements from role analyses and context package",
"modification_points": [
"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 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": ["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.
```markdown
---
identifier: WFS-{session-id}
source: "User requirements" | "File: path" | "Issue: ISS-001"
role_analyses: .workflow/active//{session-id}/.brainstorming/[role]/analysis*.md
artifacts: .workflow/active//{session-id}/.brainstorming/
context_package: .workflow/active//{session-id}/.process/context-package.json # CCW smart context
guidance_specification: .workflow/active//{session-id}/.brainstorming/guidance-specification.md # Finalized decisions with resolved conflicts
workflow_type: "standard | tdd | design" # Indicates execution model
verification_history: # CCW quality gates
synthesis_clarify: "passed | skipped | pending" # Brainstorm phase clarification
action_plan_verify: "pending"
conflict_resolution: "resolved | none | low" # Status from context-package.json
phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning" # CCW workflow phases
---
# Implementation Plan: {Project Title}
## 1. Summary
Core requirements, objectives, technical approach summary (2-3 paragraphs max).
**Core Objectives**:
- [Key objective 1]
- [Key objective 2]
**Technical Approach**:
- [High-level approach]
## 2. Context Analysis
### CCW Workflow Context
**Phase Progression**:
- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
**Quality Gates**:
- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
**Context Package Summary**:
- **Focus Paths**: {list key directories from context-package.json}
- **Key Files**: {list primary files for modification}
- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
### Project Profile
- **Type**: Greenfield/Enhancement/Refactor
- **Scale**: User count, data volume, complexity
- **Tech Stack**: Primary technologies
- **Timeline**: Duration and milestones
### Module Structure
'''
[Directory tree showing key modules]
'''
### Dependencies
**Primary**: [Core libraries and frameworks]
**APIs**: [External services]
**Development**: [Testing, linting, CI/CD tools]
### Patterns & Conventions
- **Architecture**: [Key patterns like DI, Event-Driven]
- **Component Design**: [Design patterns]
- **State Management**: [State strategy]
- **Code Style**: [Naming, TypeScript coverage]
## 3. Brainstorming Artifacts Reference
### Artifact Usage Strategy
**Primary Reference (Role Analyses)**:
- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
- **When**: Every task references relevant role analyses for requirements and design decisions
- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
**Context Intelligence (context-package.json)**:
- **What**: Smart context gathered by CCW's context-gather phase
- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
**Conflict Resolution Status**:
- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
### Role Analysis Documents (Highest Priority)
Role analyses provide specialized perspectives on the implementation:
- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
### Supporting Artifacts (Reference)
- **topic-framework.md**: Role-specific discussion points and analysis framework
**Artifact Priority in Development**:
1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
## 4. Implementation Strategy
### Execution Strategy
**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
**Rationale**: [Why this execution model fits the project]
**Parallelization Opportunities**:
- [List independent workstreams]
**Serialization Requirements**:
- [List critical dependencies]
### Architectural Approach
**Key Architecture Decisions**:
- [ADR references from role analyses]
- [Justification for architecture patterns]
**Integration Strategy**:
- [How modules communicate]
- [State management approach]
### Key Dependencies
**Task Dependency Graph**:
'''
[High-level dependency visualization]
'''
**Critical Path**: [Identify bottleneck tasks]
### Testing Strategy
**Testing Approach**:
- Unit testing: [Tools, scope]
- Integration testing: [Key integration points]
- E2E testing: [Critical user flows]
**Coverage Targets**:
- Lines: ≥70%
- Functions: ≥70%
- Branches: ≥65%
**Quality Gates**:
- [CI/CD gates]
- [Performance budgets]
## 5. Task Breakdown Summary
### Task Count
**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
### Task Structure
- **IMPL-1**: [Main task title]
- **IMPL-2**: [Main task title]
...
### Complexity Assessment
- **High**: [List with rationale]
- **Medium**: [List]
- **Low**: [List]
### Dependencies
[Reference Section 4.3 for dependency graph]
**Parallelization Opportunities**:
- [Specific task groups that can run in parallel]
## 6. Implementation Plan (Detailed Phased Breakdown)
### Execution Strategy
**Phase 1 (Weeks 1-2): [Phase Name]**
- **Tasks**: IMPL-1, IMPL-2
- **Deliverables**:
- [Specific deliverable 1]
- [Specific deliverable 2]
- **Success Criteria**:
- [Measurable criterion]
**Phase 2 (Weeks 3-N): [Phase Name]**
...
### Resource Requirements
**Development Team**:
- [Team composition and skills]
**External Dependencies**:
- [Third-party services, APIs]
**Infrastructure**:
- [Development, staging, production environments]
## 7. Risk Assessment & Mitigation
| Risk | Impact | Probability | Mitigation Strategy | Owner |
|------|--------|-------------|---------------------|-------|
| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
**Critical Risks** (High impact + High probability):
- [Risk 1]: [Detailed mitigation plan]
**Monitoring Strategy**:
- [How risks will be monitored]
## 8. Success Criteria
**Functional Completeness**:
- [ ] All requirements from role analysis documents implemented
- [ ] All acceptance criteria from task.json files met
**Technical Quality**:
- [ ] Test coverage ≥70%
- [ ] Bundle size within budget
- [ ] Performance targets met
**Operational Readiness**:
- [ ] CI/CD pipeline operational
- [ ] Monitoring and logging configured
- [ ] Documentation complete
**Business Metrics**:
- [ ] [Key business metrics from role analyses]
```
### 6.3. TODO_LIST.md Structure
A simple Markdown file for tracking the status of each task.
```markdown
# Tasks: [Session Topic]
## Task Progress
▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
- [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
- [x] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json) | [✅](./.summaries/IMPL-001.2-summary.md)
- [x] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json) | [✅](./.summaries/IMPL-002-summary.md)
## Status Legend
- `▸` = Container task (has subtasks)
- `- [ ]` = Pending leaf task
- `- [x]` = Completed leaf task
- Maximum 2 levels: Main tasks and subtasks only
```
### 6.4. Output Files Diagram
The command organizes outputs into a standard directory structure.
```
.workflow/active//{session-id}/
├── IMPL_PLAN.md # Implementation plan
├── TODO_LIST.md # Progress tracking
├── .task/
│ ├── IMPL-1.json # Container task
│ ├── IMPL-1.1.json # Leaf task with flow_control
│ └── IMPL-1.2.json # Leaf task with flow_control
├── .brainstorming # Input artifacts from brainstorm + synthesis
│ ├── guidance-specification.md # Finalized decisions (with resolved conflicts if any)
│ └── {role}/analysis*.md # Role analyses (enhanced by synthesis, with resolved conflicts if any)
└── .process/
└── context-package.json # Input from context-gather (smart context + conflict_risk status)
```
## 7. Artifact Integration
The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
#### Artifact Priority
1. **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
2. **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
3. **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
#### Artifact-Task Mapping
Artifacts are mapped to tasks based on their relevance to the task's domain.
- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
## 8. Error Handling
### Input Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Session not found | Invalid session ID | Verify session exists |
| Context missing | Incomplete planning | Run context-gather first |
| Invalid format | Corrupted results | Regenerate analysis |
### Task Generation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Count exceeds limit | >10 tasks | Re-scope requirements |
| Invalid structure | Missing fields | Fix analysis results |
| Dependency cycle | Circular refs | Adjust dependencies |
### Artifact Integration Errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Artifact not found | Missing output | Continue without artifacts |
| Invalid format | Corrupted file | Skip artifact loading |
| Path invalid | Moved/deleted | Update references |
## 10. Usage & Related Commands
**Basic Usage**:
```bash
/workflow:tools:task-generate --session WFS-auth [--cli-execute]
```
**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

32
.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md
View File

@@ -17,6 +17,38 @@ Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD work
- Verify TDD cycle execution (Red -> Green -> Refactor)
- Generate coverage and cycle reports
## Execution Process
```
Input Parsing:
├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Extract Test Tasks
└─ Find TEST-*.json files and extract focus_paths
Phase 2: Run Test Suite
└─ Decision (test framework):
├─ Node.js → npm test --coverage --json
├─ Python → pytest --cov --json-report
└─ Other → [test_command] --coverage --json
Phase 3: Parse Coverage Data
├─ Extract line coverage percentage
├─ Extract branch coverage percentage
├─ Extract function coverage percentage
└─ Identify uncovered lines/branches
Phase 4: Verify TDD Cycle
└─ FOR each TDD chain (TEST-N.M → IMPL-N.M → REFACTOR-N.M):
├─ Red Phase: Verify tests created and failed initially
├─ Green Phase: Verify tests now pass
└─ Refactor Phase: Verify code quality improved
Phase 5: Generate Analysis Report
└─ Create tdd-cycle-report.md with coverage metrics and cycle verification
```
## Execution Lifecycle
### Phase 1: Extract Test Tasks

509
.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md
View File

@@ -1,6 +1,6 @@
---
name: test-concept-enhanced
description: Analyze test requirements and generate test generation strategy using Gemini with test-context package
description: Coordinate test analysis workflow using cli-execution-agent to generate test strategy via Gemini
argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
examples:
- /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/active/WFS-test-auth/.process/test-context-package.json
@@ -9,7 +9,7 @@ examples:
# Test Concept Enhanced Command
## Overview
Specialized analysis tool for test generation workflows that uses Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies.
Workflow coordinator that delegates test analysis to cli-execution-agent. Agent executes Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies.
## Core Philosophy
- **Coverage-Driven**: Focus on identified test gaps from context analysis
@@ -19,15 +19,39 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution
## Core Responsibilities
- Parse test-context-package.json from test-context-gather
- Analyze implementation summaries and coverage gaps
- Study existing test patterns and conventions
- Generate test generation strategy using Gemini
- Produce TEST_ANALYSIS_RESULTS.md for task generation
- Coordinate test analysis workflow using cli-execution-agent
- Validate test-context-package.json prerequisites
- Execute Gemini analysis via agent for test strategy generation
- Validate agent outputs (gemini-test-analysis.md, TEST_ANALYSIS_RESULTS.md)
## Execution Process
```
Input Parsing:
├─ Parse flags: --session, --context
└─ Validation: Both REQUIRED
Phase 1: Context Preparation (Command)
├─ Load workflow-session.json
├─ Verify test session type is "test-gen"
├─ Validate test-context-package.json
└─ Determine strategy (Simple: 1-3 files | Medium: 4-6 | Complex: >6)
Phase 2: Test Analysis Execution (Agent)
├─ Execute Gemini analysis via cli-execution-agent
└─ Generate TEST_ANALYSIS_RESULTS.md
Phase 3: Output Validation (Command)
├─ Verify gemini-test-analysis.md exists
├─ Validate TEST_ANALYSIS_RESULTS.md
└─ Confirm test requirements are actionable
```
## Execution Lifecycle
### Phase 1: Validation & Preparation
### Phase 1: Context Preparation (Command Responsibility)
**Command prepares session context and validates prerequisites.**
1. **Session Validation**
- Load `.workflow/active/{test_session_id}/workflow-session.json`
@@ -40,423 +64,100 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
- Extract coverage gaps and framework details
3. **Strategy Determination**
- **Simple Test Generation** (1-3 files): Single Gemini analysis
- **Medium Test Generation** (4-6 files): Gemini comprehensive analysis
- **Complex Test Generation** (>6 files): Gemini analysis with modular approach
- **Simple** (1-3 files): Single Gemini analysis
- **Medium** (4-6 files): Comprehensive analysis
- **Complex** (>6 files): Modular analysis approach
### Phase 2: Gemini Test Analysis
### Phase 2: Test Analysis Execution (Agent Responsibility)
**Tool Configuration**:
```bash
cd .workflow/active/{test_session_id}/.process && gemini -p "
PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
MODE: analysis
CONTEXT: @{.workflow/active/{test_session_id}/.process/test-context-package.json}
**Purpose**: Analyze test coverage gaps and generate comprehensive test strategy.
**MANDATORY FIRST STEP**: Read and analyze test-context-package.json to understand:
- Test coverage gaps from test_coverage.missing_tests[]
- Implementation context from source_context.implementation_summaries[]
- Existing test patterns from test_framework.conventions
- Changed files requiring tests from source_context.implementation_summaries[].changed_files
**Agent Invocation**:
```javascript
Task(
subagent_type="cli-execution-agent",
description="Analyze test coverage gaps and generate test strategy",
prompt=`
## TASK OBJECTIVE
Analyze test requirements and generate comprehensive test generation strategy using Gemini CLI
**ANALYSIS REQUIREMENTS**:
## EXECUTION CONTEXT
Session: {test_session_id}
Source Session: {source_session_id}
Working Dir: .workflow/active/{test_session_id}/.process
Template: ~/.claude/workflows/cli-templates/prompts/test/test-concept-analysis.txt
1. **Implementation Understanding**
- Load all implementation summaries from source session
- Understand implemented features, APIs, and business logic
- Extract key functions, classes, and modules
- Identify integration points and dependencies
## EXECUTION STEPS
1. Execute Gemini analysis:
cd .workflow/active/{test_session_id}/.process && gemini -p "$(cat ~/.claude/workflows/cli-templates/prompts/test/test-concept-analysis.txt)" --approval-mode yolo
2. **Existing Test Pattern Analysis**
- Study existing test files for patterns and conventions
- Identify test structure (describe/it, test suites, fixtures)
- Analyze assertion patterns and mocking strategies
- Extract test setup/teardown patterns
2. Generate TEST_ANALYSIS_RESULTS.md:
Synthesize gemini-test-analysis.md into standardized format for task generation
Include: coverage assessment, test framework, test requirements, generation strategy, implementation targets
3. **Coverage Gap Assessment**
- For each file in missing_tests[], analyze:
- File purpose and functionality
- Public APIs requiring test coverage
- Critical paths and edge cases
- Integration points requiring tests
- Prioritize tests: high (core logic), medium (utilities), low (helpers)
## EXPECTED OUTPUTS
1. gemini-test-analysis.md - Raw Gemini analysis
2. TEST_ANALYSIS_RESULTS.md - Standardized test requirements document
4. **Test Requirements Specification**
- For each missing test file, specify:
- **Test scope**: What needs to be tested
- **Test scenarios**: Happy path, error cases, edge cases, integration
- **Test data**: Required fixtures, mocks, test data
- **Dependencies**: External services, databases, APIs to mock
- **Coverage targets**: Functions/methods requiring tests
5. **Test Generation Strategy**
- Determine test generation approach for each file
- Identify reusable test patterns from existing tests
- Plan test data and fixture requirements
- Define mocking strategy for dependencies
- Specify expected test file structure
EXPECTED OUTPUT - Write to gemini-test-analysis.md:
# Test Generation Analysis
## 1. Implementation Context Summary
- **Source Session**: {source_session_id}
- **Implemented Features**: {feature_summary}
- **Changed Files**: {list_of_implementation_files}
- **Tech Stack**: {technologies_used}
## 2. Test Coverage Assessment
- **Existing Tests**: {count} files
- **Missing Tests**: {count} files
- **Coverage Percentage**: {percentage}%
- **Priority Breakdown**:
- High Priority: {count} files (core business logic)
- Medium Priority: {count} files (utilities, helpers)
- Low Priority: {count} files (configuration, constants)
## 3. Existing Test Pattern Analysis
- **Test Framework**: {framework_name_and_version}
- **File Naming Convention**: {pattern}
- **Test Structure**: {describe_it_or_other}
- **Assertion Style**: {expect_assert_should}
- **Mocking Strategy**: {mocking_framework_and_patterns}
- **Setup/Teardown**: {beforeEach_afterEach_patterns}
- **Test Data**: {fixtures_factories_builders}
## 4. Test Requirements by File
### File: {implementation_file_path}
**Test File**: {suggested_test_file_path}
**Priority**: {high|medium|low}
#### Scope
- {description_of_what_needs_testing}
#### Test Scenarios
1. **Happy Path Tests**
- {scenario_1}
- {scenario_2}
2. **Error Handling Tests**
- {error_scenario_1}
- {error_scenario_2}
3. **Edge Case Tests**
- {edge_case_1}
- {edge_case_2}
4. **Integration Tests** (if applicable)
- {integration_scenario_1}
- {integration_scenario_2}
#### Test Data & Fixtures
- {required_test_data}
- {required_mocks}
- {required_fixtures}
#### Dependencies to Mock
- {external_service_1}
- {external_service_2}
#### Coverage Targets
- Function: {function_name} - {test_requirements}
- Function: {function_name} - {test_requirements}
---
[Repeat for each missing test file]
---
## 5. Test Generation Strategy
### Overall Approach
- {strategy_description}
### Test Generation Order
1. {file_1} - {rationale}
2. {file_2} - {rationale}
3. {file_3} - {rationale}
### Reusable Patterns
- {pattern_1_from_existing_tests}
- {pattern_2_from_existing_tests}
### Test Data Strategy
- {approach_to_test_data_and_fixtures}
### Mocking Strategy
- {approach_to_mocking_dependencies}
### Quality Criteria
- Code coverage target: {percentage}%
- Test scenarios per function: {count}
- Integration test coverage: {approach}
## 6. Implementation Targets
**Purpose**: Identify new test files to create
**Format**: New test files only (no existing files to modify)
**Test Files to Create**:
1. **Target**: `tests/auth/TokenValidator.test.ts`
- **Type**: Create new test file
- **Purpose**: Test TokenValidator class
- **Scenarios**: 15 test cases covering validation logic, error handling, edge cases
- **Dependencies**: Mock JWT library, test fixtures for tokens
2. **Target**: `tests/middleware/errorHandler.test.ts`
- **Type**: Create new test file
- **Purpose**: Test error handling middleware
- **Scenarios**: 8 test cases for different error types and response formats
- **Dependencies**: Mock Express req/res/next, error fixtures
[List all test files to create]
## 7. Success Metrics
- **Test Coverage Goal**: {target_percentage}%
- **Test Quality**: All scenarios covered (happy, error, edge, integration)
- **Convention Compliance**: Follow existing test patterns
- **Maintainability**: Clear test descriptions, reusable fixtures
RULES:
- Focus on TEST REQUIREMENTS and GENERATION STRATEGY, NOT code generation
- Study existing test patterns thoroughly for consistency
- Prioritize critical business logic tests
- Specify clear test scenarios and coverage targets
- Identify all dependencies requiring mocks
- **MUST write output to .workflow/active/{test_session_id}/.process/gemini-test-analysis.md**
- Do NOT generate actual test code or implementation
- Output ONLY test analysis and generation strategy
" --approval-mode yolo
## QUALITY VALIDATION
- Both output files exist and are complete
- All required sections present in TEST_ANALYSIS_RESULTS.md
- Test requirements are actionable and quantified
- Test scenarios cover happy path, errors, edge cases
- Dependencies and mocks clearly identified
`
)
```
**Output Location**: `.workflow/active/{test_session_id}/.process/gemini-test-analysis.md`
**Output Files**:
- `.workflow/active/{test_session_id}/.process/gemini-test-analysis.md`
- `.workflow/active/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
### Phase 3: Results Synthesis
### Phase 3: Output Validation (Command Responsibility)
1. **Output Validation**
- Verify `gemini-test-analysis.md` exists and is complete
- Validate all required sections present
- Check test requirements are actionable
**Command validates agent outputs.**
2. **Quality Assessment**
- Test scenarios cover happy path, errors, edge cases
- Dependencies and mocks clearly identified
- Test generation strategy is practical
- Coverage targets are reasonable
### Phase 4: TEST_ANALYSIS_RESULTS.md Generation
Synthesize Gemini analysis into standardized format:
```markdown
# Test Generation Analysis Results
## Executive Summary
- **Test Session**: {test_session_id}
- **Source Session**: {source_session_id}
- **Analysis Timestamp**: {timestamp}
- **Coverage Gap**: {missing_test_count} files require tests
- **Test Framework**: {framework}
- **Overall Strategy**: {high_level_approach}
---
## 1. Coverage Assessment
### Current Coverage
- **Existing Tests**: {count} files
- **Implementation Files**: {count} files
- **Coverage Percentage**: {percentage}%
### Missing Tests (Priority Order)
1. **High Priority** ({count} files)
- {file_1} - {reason}
- {file_2} - {reason}
2. **Medium Priority** ({count} files)
- {file_1} - {reason}
3. **Low Priority** ({count} files)
- {file_1} - {reason}
---
## 2. Test Framework & Conventions
### Framework Configuration
- **Framework**: {framework_name}
- **Version**: {version}
- **Test Pattern**: {file_pattern}
- **Test Directory**: {directory_structure}
### Conventions
- **File Naming**: {convention}
- **Test Structure**: {describe_it_blocks}
- **Assertions**: {assertion_library}
- **Mocking**: {mocking_framework}
- **Setup/Teardown**: {beforeEach_afterEach}
### Example Pattern (from existing tests)
```
{example_test_structure_from_analysis}
```
---
## 3. Test Requirements by File
[For each missing test, include:]
### Test File: {test_file_path}
**Implementation**: {implementation_file}
**Priority**: {high|medium|low}
**Estimated Test Count**: {count}
#### Test Scenarios
1. **Happy Path**: {scenarios}
2. **Error Handling**: {scenarios}
3. **Edge Cases**: {scenarios}
4. **Integration**: {scenarios}
#### Dependencies & Mocks
- {dependency_1_to_mock}
- {dependency_2_to_mock}
#### Test Data Requirements
- {fixture_1}
- {fixture_2}
---
## 4. Test Generation Strategy
### Generation Approach
{overall_strategy_description}
### Generation Order
1. {test_file_1} - {rationale}
2. {test_file_2} - {rationale}
3. {test_file_3} - {rationale}
### Reusable Components
- **Test Fixtures**: {common_fixtures}
- **Mock Patterns**: {common_mocks}
- **Helper Functions**: {test_helpers}
### Quality Targets
- **Coverage Goal**: {percentage}%
- **Scenarios per Function**: {min_count}
- **Integration Coverage**: {approach}
---
## 5. Implementation Targets
**Purpose**: New test files to create (code-developer will generate these)
**Test Files to Create**:
1. **Target**: `tests/auth/TokenValidator.test.ts`
- **Implementation Source**: `src/auth/TokenValidator.ts`
- **Test Scenarios**: 15 (validation, error handling, edge cases)
- **Dependencies**: Mock JWT library, token fixtures
- **Priority**: High
2. **Target**: `tests/middleware/errorHandler.test.ts`
- **Implementation Source**: `src/middleware/errorHandler.ts`
- **Test Scenarios**: 8 (error types, response formats)
- **Dependencies**: Mock Express, error fixtures
- **Priority**: High
[List all test files with full specifications]
---
## 6. Success Criteria
### Coverage Metrics
- Achieve {target_percentage}% code coverage
- All public APIs have tests
- Critical paths fully covered
### Quality Standards
- All test scenarios covered (happy, error, edge, integration)
- Follow existing test conventions
- Clear test descriptions and assertions
- Maintainable test structure
### Validation Approach
- Run full test suite after generation
- Verify coverage with coverage tool
- Manual review of test quality
- Integration test validation
---
## 7. Reference Information
### Source Context
- **Implementation Summaries**: {paths}
- **Existing Tests**: {example_tests}
- **Documentation**: {relevant_docs}
### Analysis Tools
- **Gemini Analysis**: gemini-test-analysis.md
- **Coverage Tools**: {coverage_tool_if_detected}
```
**Output Location**: `.workflow/active/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
- Verify `gemini-test-analysis.md` exists and is complete
- Validate `TEST_ANALYSIS_RESULTS.md` generated by agent
- Check required sections present
- Confirm test requirements are actionable
## Error Handling
### Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Missing context package | test-context-gather not run | Run test-context-gather first |
| No coverage gaps | All files have tests | Skip test generation, proceed to test execution |
| No test framework detected | Missing test dependencies | Request user to configure test framework |
| Invalid source session | Source session incomplete | Complete implementation first |
| Error | Resolution |
|-------|------------|
| Missing context package | Run test-context-gather first |
| No coverage gaps | Skip test generation, proceed to execution |
| No test framework detected | Configure test framework |
| Invalid source session | Complete implementation first |
### Gemini Execution Errors
| Error | Cause | Recovery |
|-------|-------|----------|
| Timeout | Large project analysis | Reduce scope, analyze by module |
| Output incomplete | Token limit exceeded | Retry with focused analysis |
| No output file | Write permission error | Check directory permissions |
### Execution Errors
| Error | Recovery |
|-------|----------|
| Gemini timeout | Reduce scope, analyze by module |
| Output incomplete | Retry with focused analysis |
| No output file | Check directory permissions |
### Fallback Strategy
- If Gemini fails, generate basic TEST_ANALYSIS_RESULTS.md from context package
- Use coverage gaps and framework info to create minimal requirements
- Provide guidance for manual test planning
**Fallback Strategy**: Generate basic TEST_ANALYSIS_RESULTS.md from context package if Gemini fails
## Performance Optimization
## Integration & Usage
- **Focused Analysis**: Only analyze files with missing tests
- **Pattern Reuse**: Study existing tests for quick pattern extraction
- **Parallel Operations**: Load implementation summaries in parallel
- **Timeout Management**: 20-minute limit for Gemini analysis
### Command Chain
- **Called By**: `/workflow:test-gen` (Phase 4: Analysis)
- **Requires**: `test-context-package.json` from `/workflow:tools:test-context-gather`
- **Followed By**: `/workflow:tools:test-task-generate`
## Integration
### Performance
- Focused analysis: Only analyze files with missing tests
- Pattern reuse: Study existing tests for quick extraction
- Timeout: 20-minute limit for analysis
### Called By
- `/workflow:test-gen` (Phase 4: Analysis)
### Requires
- `/workflow:tools:test-context-gather` output (test-context-package.json)
### Followed By
- `/workflow:tools:test-task-generate` - Generates test task JSON with code-developer invocation
## Success Criteria
- ✅ Valid TEST_ANALYSIS_RESULTS.md generated
- ✅ All missing tests documented with requirements
- ✅ Test scenarios cover happy path, errors, edge cases
- ✅ Dependencies and mocks identified
- ✅ Test generation strategy is actionable
- ✅ Execution time < 20 minutes
- ✅ Output follows existing test conventions
### Success Criteria
- Valid TEST_ANALYSIS_RESULTS.md generated
- All missing tests documented with actionable requirements
- Test scenarios cover happy path, errors, edge cases, integration
- Dependencies and mocks clearly identified
- Test generation strategy is practical
- Output follows existing test conventions

30
.claude/skills/command-guide/reference/commands/workflow/tools/test-context-gather.md
View File

@@ -24,6 +24,36 @@ Orchestrator command that invokes `test-context-search-agent` to gather comprehe
- **Source Context Loading**: Import implementation summaries from source session
- **Standardized Output**: Generate `.workflow/active/{test_session_id}/.process/test-context-package.json`
## Execution Process
```
Input Parsing:
├─ Parse flags: --session
└─ Validation: test_session_id REQUIRED
Step 1: Test-Context-Package Detection
└─ Decision (existing package):
├─ Valid package exists → Return existing (skip execution)
└─ No valid package → Continue to Step 2
Step 2: Invoke Test-Context-Search Agent
├─ Phase 1: Session Validation & Source Context Loading
│ ├─ Detection: Check for existing test-context-package
│ ├─ Test session validation
│ └─ Source context loading (summaries, changed files)
├─ Phase 2: Test Coverage Analysis
│ ├─ Track 1: Existing test discovery
│ ├─ Track 2: Coverage gap analysis
│ └─ Track 3: Coverage statistics
└─ Phase 3: Framework Detection & Packaging
├─ Framework identification
├─ Convention analysis
└─ Generate test-context-package.json
Step 3: Output Verification
└─ Verify test-context-package.json created
```
## Execution Flow
### Step 1: Test-Context-Package Detection

522
.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
View File

@@ -1,416 +1,256 @@
---
name: test-task-generate
description: Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase
description: Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests
argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
examples:
- /workflow:tools:test-task-generate --session WFS-test-auth
- /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
- /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
- /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
---
# Autonomous Test Task Generation Command
# Generate Test Planning Documents Command
## Overview
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.
Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent. This command produces **test planning artifacts only** - it does NOT execute tests or implement code. Actual test execution requires separate execution command (e.g., /workflow:test-cycle-execute).
## Core Philosophy
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
- **Planning Only**: Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT execute tests
- **Agent-Driven Document Generation**: Delegate test plan generation to action-planning-agent
- **Two-Phase Flow**: Context Preparation (command) → Test Document Generation (agent)
- **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
- **MCP-Enhanced**: Use MCP tools for test pattern research and analysis
- **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
- **Leverage Existing Test Infrastructure**: Prioritize using established testing frameworks and tools present in the project
## Execution Modes
## Test-Specific Execution Modes
### Test Generation (IMPL-001)
- **Agent Mode (Default)**: @code-developer generates tests within agent context
- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
- **Agent Mode** (default): @code-developer generates tests within agent context
- **CLI Execute Mode** (`--cli-execute`): Use Codex CLI for autonomous test generation
### Test Fix (IMPL-002)
- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
### Test Execution & Fix (IMPL-002+)
- **Manual Mode** (default): Gemini diagnosis → user applies fixes
- **Codex Mode** (`--use-codex`): Gemini diagnosis → Codex applies fixes with resume mechanism
## Execution Lifecycle
## Execution Process
### Phase 1: Discovery & Context Loading
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
```
Input Parsing:
├─ Parse flags: --session, --use-codex, --cli-execute
└─ Validation: session_id REQUIRED
**Agent Context Package**:
```javascript
{
"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/active/{test-session-id}/workflow-session.json
},
"test_analysis_results_path": ".workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md",
"test_analysis_results": {
// If in memory: use cached content
// Else: Load from TEST_ANALYSIS_RESULTS.md
},
"test_context_package_path": ".workflow/active/{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
}
}
Phase 1: Context Preparation (Command)
├─ Assemble test session paths
│ ├─ session_metadata_path
│ ├─ test_analysis_results_path (REQUIRED)
│ └─ test_context_package_path
└─ Provide metadata (session_id, execution_mode, use_codex, source_session_id)
Phase 2: Test Document Generation (Agent)
├─ Load TEST_ANALYSIS_RESULTS.md as primary requirements source
├─ Generate Test Task JSON Files (.task/IMPL-*.json)
│ ├─ IMPL-001: Test generation (meta.type: "test-gen")
│ └─ IMPL-002+: Test execution & fix (meta.type: "test-fix")
├─ Create IMPL_PLAN.md (test_session variant)
└─ Generate TODO_LIST.md with test phase indicators
```
**Discovery Actions**:
1. **Load Test Session Context** (if not in memory)
```javascript
if (!memory.has("workflow-session.json")) {
Read(.workflow/active/{test-session-id}/workflow-session.json)
}
```
## Document Generation Lifecycle
2. **Load TEST_ANALYSIS_RESULTS.md** (if not in memory, REQUIRED)
```javascript
if (!memory.has("TEST_ANALYSIS_RESULTS.md")) {
Read(.workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md)
}
```
### Phase 1: Context Preparation (Command Responsibility)
3. **Load Test Context Package** (if not in memory)
```javascript
if (!memory.has("test-context-package.json")) {
Read(.workflow/active/{test-session-id}/.process/test-context-package.json)
}
```
**Command prepares test session paths and metadata for planning document generation.**
4. **Load Source Session Summaries** (if source_session_id exists)
```javascript
if (sessionMetadata.source_session_id) {
const summaryFiles = Bash("find .workflow/active/{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";
**Test Session Path Structure**:
```
.workflow/active/WFS-test-{session-id}/
├── workflow-session.json # Test session metadata
├── .process/
│ ├── TEST_ANALYSIS_RESULTS.md # Test requirements and strategy
│ ├── test-context-package.json # Test patterns and coverage
│ └── context-package.json # General context artifacts
├── .task/ # Output: Test task JSON files
├── IMPL_PLAN.md # Output: Test implementation plan
└── TODO_LIST.md # Output: Test TODO list
```
**Command Preparation**:
1. **Assemble Test Session Paths** for agent prompt:
- `session_metadata_path`
- `test_analysis_results_path` (REQUIRED)
- `test_context_package_path`
- Output directory paths
2. **Provide Metadata** (simple values):
- `session_id`
- `execution_mode` (agent-mode | cli-execute-mode)
- `use_codex` flag (true | false)
- `source_session_id` (if exists)
- `mcp_capabilities` (available MCP tools)
### Phase 2: Test Document Generation (Agent Responsibility)
**Purpose**: Generate test-specific IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT test execution.
**Agent Invocation**:
```javascript
Task(
subagent_type="action-planning-agent",
description="Generate test-fix task JSON and implementation plan",
description="Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
prompt=`
## Execution Context
## TASK OBJECTIVE
Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for test workflow session
**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}
IMPORTANT: This is TEST PLANNING ONLY - you are generating planning documents, NOT executing tests.
## Phase 1: Discovery Results (Provided Context)
CRITICAL:
- Use existing test frameworks and utilities from the project
- Follow the progressive loading strategy defined in your agent specification (load context incrementally from memory-first approach)
### Test Session Metadata
{session_metadata_content}
- source_session_id: {source_session_id} (if exists)
- workflow_type: "test_session"
## AGENT CONFIGURATION REFERENCE
All test task generation rules, schemas, and quality standards are defined in your agent specification:
@.claude/agents/action-planning-agent.md
### 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
Refer to your specification for:
- Test Task JSON Schema (6-field structure with test-specific metadata)
- Test IMPL_PLAN.md Structure (test_session variant with test-fix cycle)
- TODO_LIST.md Format (with test phase indicators)
- Progressive Loading Strategy (memory-first, load TEST_ANALYSIS_RESULTS.md as primary source)
- Quality Validation Rules (task count limits, requirement quantification)
### Test Context Package
{test_context_package_summary}
- Existing test patterns, framework config, coverage analysis
## SESSION PATHS
Input:
- Session Metadata: .workflow/active/{test-session-id}/workflow-session.json
- TEST_ANALYSIS_RESULTS: .workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md (REQUIRED - primary requirements source)
- Test Context Package: .workflow/active/{test-session-id}/.process/test-context-package.json
- Context Package: .workflow/active/{test-session-id}/.process/context-package.json
- Source Session Summaries: .workflow/active/{source-session-id}/.summaries/IMPL-*.md (if exists)
### Source Session Implementation Context (Optional)
{source_session_summaries}
- Implementation context from completed session
Output:
- Task Dir: .workflow/active/{test-session-id}/.task/
- IMPL_PLAN: .workflow/active/{test-session-id}/IMPL_PLAN.md
- TODO_LIST: .workflow/active/{test-session-id}/TODO_LIST.md
### MCP Analysis Results (Optional)
**Code Structure**: {mcp_code_index_results}
**External Research**: {mcp_exa_research_results}
## CONTEXT METADATA
Session ID: {test-session-id}
Workflow Type: test_session
Planning Mode: {agent-mode | cli-execute-mode}
Use Codex: {true | false}
Source Session: {source-session-id} (if exists)
MCP Capabilities: {exa_code, exa_web, code_index}
## Phase 2: Test Task Document Generation
## TEST-SPECIFIC REQUIREMENTS SUMMARY
(Detailed specifications in your agent definition)
**Agent Configuration Reference**: All test task generation rules, test-fix cycle structure, quality standards, and execution details are defined in action-planning-agent.
### Task Structure Requirements
- Minimum 2 tasks: IMPL-001 (test generation) + IMPL-002 (test execution & fix)
- Expandable for complex projects: Add IMPL-003+ (per-module, integration, E2E tests)
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
Task Configuration:
IMPL-001 (Test Generation):
- meta.type: "test-gen"
- meta.agent: "@code-developer" (agent-mode) OR CLI execution (cli-execute-mode)
- meta.test_framework: Specify existing framework (e.g., "jest", "vitest", "pytest")
- flow_control: Test generation strategy from TEST_ANALYSIS_RESULTS.md
### Test-Specific Requirements Summary
IMPL-002+ (Test Execution & Fix):
- meta.type: "test-fix"
- meta.agent: "@test-fix-agent"
- meta.use_codex: true/false (based on flag)
- flow_control: Test-fix cycle with iteration limits and diagnosis configuration
#### 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 Specification (IMPL-002+)
Required flow_control fields:
- max_iterations: 5
- diagnosis_tool: "gemini"
- diagnosis_template: "~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt"
- fix_mode: "manual" OR "codex" (based on use_codex flag)
- cycle_pattern: "test → gemini_diagnose → fix → retest"
- exit_conditions: ["all_tests_pass", "max_iterations_reached"]
- auto_revert_on_failure: true
#### 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)
### Automation Framework Configuration
Select automation tools based on test requirements from TEST_ANALYSIS_RESULTS.md:
- UI interaction testing → E2E browser automation (meta.e2e_framework)
- API/database integration → integration test tools (meta.test_tools)
- Performance metrics → load testing tools (meta.perf_framework)
- Logic verification → unit test framework (meta.test_framework)
#### Required Outputs Summary
**Tool Selection**: Detect from project config > suggest based on requirements
##### 1. Test Task JSON Files (.task/IMPL-*.json)
- **Location**: `.workflow/active/{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
### TEST_ANALYSIS_RESULTS.md Mapping
PRIMARY requirements source - extract and map to task JSONs:
- Test framework config → meta.test_framework (use existing framework from project)
- Existing test utilities → flow_control.reusable_test_tools (discovered test helpers, fixtures, mocks)
- Test runner commands → flow_control.test_commands (from package.json or pytest config)
- Coverage targets → meta.coverage_target
- Test requirements → context.requirements (quantified with explicit counts)
- Test generation strategy → IMPL-001 flow_control.implementation_approach
- Implementation targets → context.files_to_test (absolute paths)
##### 2. IMPL_PLAN.md (Test Variant)
- **Location**: `.workflow/active/{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
## EXPECTED DELIVERABLES
1. Test Task JSON Files (.task/IMPL-*.json)
- 6-field schema with quantified requirements from TEST_ANALYSIS_RESULTS.md
- Test-specific metadata: type, agent, use_codex, test_framework, coverage_target
- flow_control includes: reusable_test_tools, test_commands (from project config)
- Artifact references from test-context-package.json
- Absolute paths in context.files_to_test
##### 3. TODO_LIST.md
- **Location**: `.workflow/active/{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
2. Test Implementation Plan (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 with diagnosis configuration
- Source session context integration (if applicable)
### Agent Execution Summary
3. TODO List (TODO_LIST.md)
- Hierarchical structure with test phase containers
- Links to task JSONs with status markers
- Matches task JSON hierarchy
**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 STANDARDS
Hard Constraints:
- Task count: minimum 2, maximum 12
- All requirements quantified from TEST_ANALYSIS_RESULTS.md
- Test framework matches existing project framework
- flow_control includes reusable_test_tools and test_commands from project
- use_codex flag correctly set in IMPL-002+ tasks
- Absolute paths for all focus_paths
- Acceptance criteria include verification commands
**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
## SUCCESS CRITERIA
- All test planning documents generated successfully
- Return completion status: task count, test framework, coverage targets, source session status
`
)
```
### 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/active/WFS-test-[id]/workflow-session.json),
test_analysis_results_path: ".workflow/active/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/active/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
test_context_package_path: ".workflow/active/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/active/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()
}
```
## Test Task Structure Reference
This section provides quick reference for test task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
**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
```
.workflow/active/WFS-test-[session]/
├── workflow-session.json # Test session metadata
├── IMPL_PLAN.md # Test validation plan
├── TODO_LIST.md # Progress tracking
├── .task/
│ └── IMPL-001.json # Test-fix task with cycle spec
├── .process/
│ ├── ANALYSIS_RESULTS.md # From concept-enhanced (optional)
│ ├── context-package.json # From context-gather
│ ├── initial-test.log # Phase 1: Initial test results
│ ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
│ ├── fix-iteration-1-changes.log # Codex changes iteration 1
│ ├── fix-iteration-1-retest.log # Retest results iteration 1
│ ├── fix-iteration-N-*.md/log # Subsequent iterations
│ └── final-test.log # Phase 3: Final validation
└── .summaries/
└── IMPL-001-summary.md # Success report OR failure report
```
## Error Handling
### Input Validation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Not a test session | Missing workflow_type: "test_session" | Verify session created by test-gen |
| Source session not found | Invalid source_session_id | Check source session exists |
| No implementation summaries | Source session incomplete | Ensure source session has completed tasks |
### Test Framework Discovery Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| No test command found | Unknown framework | Manual test command specification |
| No test files found | Tests not written | Request user to write tests first |
| Test dependencies missing | Incomplete setup | Run dependency installation |
### Generation Errors
| Error | Cause | Resolution |
|-------|-------|------------|
| Invalid JSON structure | Template error | Fix task generation logic |
| Missing required fields | Incomplete metadata | Validate session metadata |
## Integration & Usage
### Command Chain
- **Called By**: `/workflow:test-gen` (Phase 4), `/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)
- **Invokes**: `action-planning-agent` for test planning document generation
- **Followed By**: `/workflow:test-cycle-execute` or `/workflow:execute` (user-triggered)
### Basic Usage
### Usage Examples
```bash
# Agent mode (default, autonomous execution)
# Agent mode (default)
/workflow:tools:test-task-generate --session WFS-test-auth
# With automated Codex fixes for IMPL-002
# With automated Codex fixes
/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
# CLI execution mode for IMPL-001 test generation
# CLI execution mode for 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 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
- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode test generation
- **--use-codex**: `meta.use_codex=true` (Codex automated fixes in IMPL-002+)
- **--cli-execute**: 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)
## Agent Execution Notes
The `@test-fix-agent` will execute the task by following the `flow_control.implementation_approach` specification:
1. **Load task JSON**: Read complete test-fix task from `.task/IMPL-002.json`
2. **Check meta.use_codex**: Determine fix mode (manual or automated)
3. **Execute pre_analysis**: Load source context, discover framework, analyze tests
4. **Phase 1**: Run initial test suite
5. **Phase 2**: If failures, enter iterative loop:
- Use Gemini for diagnosis (analysis mode with bug-fix template)
- Check meta.use_codex flag:
- If false (default): Present fix suggestions to user for manual application
- If true (--use-codex): Use Codex resume for automated fixes (maintains context)
- Retest and check for regressions
- Repeat max 5 times
6. **Phase 3**: Generate summary and certify code
7. **Error Recovery**: Revert changes if max iterations reached
**Bug Diagnosis Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
**Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.
- Test task JSON files in `.task/` directory (minimum 2)
- IMPL_PLAN.md with test strategy and fix cycle specification
- TODO_LIST.md with test phase indicators
- Session ready for test execution