mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-15 02:42:45 +08:00
Refactor: Remove obsolete TDD coverage analysis, test concept enhancement, context gathering, and task generation commands
- Deleted the following command files: - tdd-coverage-analysis.md - test-concept-enhanced.md - test-context-gather.md - test-task-generate.md Enhancement: Update FloatingPanel component styles - Adjusted FloatingPanel backdrop styles for improved layout - Modified height calculation to utilize full viewport height below the toolbar
This commit is contained in:
catlog22
@@ -1,765 +0,0 @@
|
||||
---
|
||||
name: review-cycle-fix
|
||||
description: Automated fixing of code review findings with AI-powered planning and coordinated execution. Uses intelligent grouping, multi-stage timeline coordination, and test-driven verification.
|
||||
argument-hint: "<export-file|review-dir> [--resume] [--max-iterations=N] [--batch-size=N]"
|
||||
allowed-tools: Skill(*), TodoWrite(*), Read(*), Bash(*), Task(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
# Workflow Review-Cycle-Fix Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Fix from exported findings file (session-based path)
|
||||
/workflow:review-cycle-fix .workflow/active/WFS-123/.review/fix-export-1706184622000.json
|
||||
|
||||
# Fix from review directory (auto-discovers latest export)
|
||||
/workflow:review-cycle-fix .workflow/active/WFS-123/.review/
|
||||
|
||||
# Resume interrupted fix session
|
||||
/workflow:review-cycle-fix --resume
|
||||
|
||||
# Custom max retry attempts per finding
|
||||
/workflow:review-cycle-fix .workflow/active/WFS-123/.review/ --max-iterations=5
|
||||
|
||||
# Custom batch size for parallel planning (default: 5 findings per batch)
|
||||
/workflow:review-cycle-fix .workflow/active/WFS-123/.review/ --batch-size=3
|
||||
```
|
||||
|
||||
**Fix Source**: Exported findings from review cycle dashboard
|
||||
**Output Directory**: `{review-dir}/fixes/{fix-session-id}/` (within session .review/)
|
||||
**Default Max Iterations**: 3 (per finding, adjustable)
|
||||
**Default Batch Size**: 5 (findings per planning batch, adjustable)
|
||||
**Max Parallel Agents**: 10 (concurrent planning agents)
|
||||
**CLI Tools**: @cli-planning-agent (planning), @cli-execute-agent (fixing)
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
Automated fix orchestrator with **parallel planning architecture**: Multiple AI agents analyze findings concurrently in batches, then coordinate parallel/serial execution. Generates fix timeline with intelligent grouping and dependency analysis, executes fixes with conservative test verification.
|
||||
|
||||
**Fix Process**:
|
||||
- **Batching Phase (1.5)**: Orchestrator groups findings by file+dimension similarity, creates batches
|
||||
- **Planning Phase (2)**: Up to 10 agents plan batches in parallel, generate partial plans, orchestrator aggregates
|
||||
- **Execution Phase (3)**: Main orchestrator coordinates agents per aggregated timeline stages
|
||||
- **Parallel Efficiency**: Customizable batch size (default: 5), MAX_PARALLEL=10 agents
|
||||
- **No rigid structure**: Adapts to task requirements, not bound to fixed JSON format
|
||||
|
||||
**vs Manual Fixing**:
|
||||
- **Manual**: Developer reviews findings one-by-one, fixes sequentially
|
||||
- **Automated**: AI groups related issues, multiple agents plan in parallel, executes in optimal parallel/serial order with automatic test verification
|
||||
|
||||
### Value Proposition
|
||||
1. **Parallel Planning**: Multiple agents analyze findings concurrently, reducing planning time for large batches (10+ findings)
|
||||
2. **Intelligent Batching**: Semantic similarity grouping ensures related findings are analyzed together
|
||||
3. **Multi-stage Coordination**: Supports complex parallel + serial execution with cross-batch dependency management
|
||||
4. **Conservative Safety**: Mandatory test verification with automatic rollback on failure
|
||||
5. **Resume Support**: Checkpoint-based recovery for interrupted sessions
|
||||
|
||||
### Orchestrator Boundary (CRITICAL)
|
||||
- **ONLY command** for automated review finding fixes
|
||||
- Manages: Intelligent batching (Phase 1.5), parallel planning coordination (launch N agents), plan aggregation, stage-based execution, agent scheduling, progress tracking
|
||||
- Delegates: Batch planning to @cli-planning-agent, fix execution to @cli-execute-agent
|
||||
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization
|
||||
└─ Validate export file, create fix session structure, initialize state files
|
||||
|
||||
Phase 1.5: Intelligent Grouping & Batching
|
||||
├─ Analyze findings metadata (file, dimension, severity)
|
||||
├─ Group by semantic similarity (file proximity + dimension affinity)
|
||||
├─ Create batches respecting --batch-size (default: 5)
|
||||
└─ Output: Finding batches for parallel planning
|
||||
|
||||
Phase 2: Parallel Planning Coordination (@cli-planning-agent × N)
|
||||
├─ Launch MAX_PARALLEL planning agents concurrently (default: 10)
|
||||
├─ Each agent processes one batch:
|
||||
│ ├─ Analyze findings for patterns and dependencies
|
||||
│ ├─ Group by file + dimension + root cause similarity
|
||||
│ ├─ Determine execution strategy (parallel/serial/hybrid)
|
||||
│ ├─ Generate fix timeline with stages
|
||||
│ └─ Output: partial-plan-{batch-id}.json
|
||||
├─ Collect results from all agents
|
||||
└─ Aggregate: Merge partial plans → fix-plan.json (resolve cross-batch dependencies)
|
||||
|
||||
Phase 3: Execution Orchestration (Stage-based)
|
||||
For each timeline stage:
|
||||
├─ Load groups for this stage
|
||||
├─ If parallel: Launch all group agents simultaneously
|
||||
├─ If serial: Execute groups sequentially
|
||||
├─ Each agent:
|
||||
│ ├─ Analyze code context
|
||||
│ ├─ Apply fix per strategy
|
||||
│ ├─ Run affected tests
|
||||
│ ├─ On test failure: Rollback, retry up to max_iterations
|
||||
│ └─ On success: Commit, update fix-progress-{N}.json
|
||||
└─ Advance to next stage
|
||||
|
||||
Phase 4: Completion & Aggregation
|
||||
└─ Aggregate results → Generate fix-summary.md → Update history → Output summary
|
||||
|
||||
Phase 5: Session Completion (Optional)
|
||||
└─ If all fixes successful → Prompt to complete workflow session
|
||||
```
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Orchestrator** | Input validation, session management, intelligent batching (Phase 1.5), parallel planning coordination (launch N agents), plan aggregation (merge partial plans, resolve cross-batch dependencies), stage-based execution scheduling, progress tracking, result aggregation |
|
||||
| **@cli-planning-agent** | Batch findings analysis, intelligent grouping (file+dimension+root cause), execution strategy determination (parallel/serial/hybrid), timeline generation with dependency mapping, partial plan output |
|
||||
| **@cli-execute-agent** | Fix execution per group, code context analysis, Edit tool operations, test verification, git rollback on failure, completion JSON generation |
|
||||
|
||||
## Enhanced Features
|
||||
|
||||
### 1. Parallel Planning Architecture
|
||||
|
||||
**Batch Processing Strategy**:
|
||||
|
||||
| Phase | Agent Count | Input | Output | Purpose |
|
||||
|-------|-------------|-------|--------|---------|
|
||||
| **Batching (1.5)** | Orchestrator | All findings | Finding batches | Semantic grouping by file+dimension, respecting --batch-size |
|
||||
| **Planning (2)** | N agents (≤10) | 1 batch each | partial-plan-{batch-id}.json | Analyze batch in parallel, generate execution groups and timeline |
|
||||
| **Aggregation (2)** | Orchestrator | All partial plans | fix-plan.json | Merge timelines, resolve cross-batch dependencies |
|
||||
| **Execution (3)** | M agents (dynamic) | 1 group each | fix-progress-{N}.json | Execute fixes per aggregated plan with test verification |
|
||||
|
||||
**Benefits**:
|
||||
- **Speed**: N agents plan concurrently, reducing planning time for large batches
|
||||
- **Scalability**: MAX_PARALLEL=10 prevents resource exhaustion
|
||||
- **Flexibility**: Batch size customizable via --batch-size (default: 5)
|
||||
- **Isolation**: Each planning agent focuses on related findings (semantic grouping)
|
||||
- **Reusable**: Aggregated plan can be re-executed without re-planning
|
||||
|
||||
### 2. Intelligent Grouping Strategy
|
||||
|
||||
**Three-Level Grouping**:
|
||||
|
||||
```javascript
|
||||
// Level 1: Primary grouping by file + dimension
|
||||
{file: "auth.ts", dimension: "security"} → Group A
|
||||
{file: "auth.ts", dimension: "quality"} → Group B
|
||||
{file: "query-builder.ts", dimension: "security"} → Group C
|
||||
|
||||
// Level 2: Secondary grouping by root cause similarity
|
||||
Group A findings → Semantic similarity analysis (threshold 0.7)
|
||||
→ Sub-group A1: "missing-input-validation" (findings 1, 2)
|
||||
→ Sub-group A2: "insecure-crypto" (finding 3)
|
||||
|
||||
// Level 3: Dependency analysis
|
||||
Sub-group A1 creates validation utilities
|
||||
Sub-group C4 depends on those utilities
|
||||
→ A1 must execute before C4 (serial stage dependency)
|
||||
```
|
||||
|
||||
**Similarity Computation**:
|
||||
- Combine: `description + recommendation + category`
|
||||
- Vectorize: TF-IDF or LLM embedding
|
||||
- Cluster: Greedy algorithm with cosine similarity > 0.7
|
||||
|
||||
### 3. Execution Strategy Determination
|
||||
|
||||
**Strategy Types**:
|
||||
|
||||
| Strategy | When to Use | Stage Structure |
|
||||
|----------|-------------|-----------------|
|
||||
| **Parallel** | All groups independent, different files | Single stage, all groups in parallel |
|
||||
| **Serial** | Strong dependencies, shared resources | Multiple stages, one group per stage |
|
||||
| **Hybrid** | Mixed dependencies | Multiple stages, parallel within stages |
|
||||
|
||||
**Dependency Detection**:
|
||||
- Shared file modifications
|
||||
- Utility creation + usage patterns
|
||||
- Test dependency chains
|
||||
- Risk level clustering (high-risk groups isolated)
|
||||
|
||||
### 4. Conservative Test Verification
|
||||
|
||||
**Test Strategy** (per fix):
|
||||
|
||||
```javascript
|
||||
// 1. Identify affected tests
|
||||
const testPattern = identifyTestPattern(finding.file);
|
||||
// e.g., "tests/auth/**/*.test.*" for src/auth/service.ts
|
||||
|
||||
// 2. Run tests
|
||||
const result = await runTests(testPattern);
|
||||
|
||||
// 3. Evaluate
|
||||
if (result.passRate < 100%) {
|
||||
// Rollback
|
||||
await gitCheckout(finding.file);
|
||||
|
||||
// Retry with failure context
|
||||
if (attempts < maxIterations) {
|
||||
const fixContext = analyzeFailure(result.stderr);
|
||||
regenerateFix(finding, fixContext);
|
||||
retry();
|
||||
} else {
|
||||
markFailed(finding.id);
|
||||
}
|
||||
} else {
|
||||
// Commit
|
||||
await gitCommit(`Fix: ${finding.title} [${finding.id}]`);
|
||||
markFixed(finding.id);
|
||||
}
|
||||
```
|
||||
|
||||
**Pass Criteria**: 100% test pass rate (no partial fixes)
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Orchestrator
|
||||
|
||||
**Phase 1: Discovery & Initialization**
|
||||
- Input validation: Check export file exists and is valid JSON
|
||||
- Auto-discovery: If review-dir provided, find latest `*-fix-export.json`
|
||||
- Session creation: Generate fix-session-id (`fix-{timestamp}`)
|
||||
- Directory structure: Create `{review-dir}/fixes/{fix-session-id}/` with subdirectories
|
||||
- State files: Initialize active-fix-session.json (session marker)
|
||||
- TodoWrite initialization: Set up 5-phase tracking (including Phase 1.5)
|
||||
|
||||
**Phase 1.5: Intelligent Grouping & Batching**
|
||||
- Load all findings metadata (id, file, dimension, severity, title)
|
||||
- Semantic similarity analysis:
|
||||
- Primary: Group by file proximity (same file or related modules)
|
||||
- Secondary: Group by dimension affinity (same review dimension)
|
||||
- Tertiary: Analyze title/description similarity (root cause clustering)
|
||||
- Create batches respecting --batch-size (default: 5 findings per batch)
|
||||
- Balance workload: Distribute high-severity findings across batches
|
||||
- Output: Array of finding batches for parallel planning
|
||||
|
||||
**Phase 2: Parallel Planning Coordination**
|
||||
- Determine concurrency: MIN(batch_count, MAX_PARALLEL=10)
|
||||
- For each batch chunk (≤10 batches):
|
||||
- Launch all agents in parallel with run_in_background=true
|
||||
- Pass batch findings + project context + batch_id to each agent
|
||||
- Each agent outputs: partial-plan-{batch-id}.json
|
||||
- Collect results via TaskOutput (blocking until all complete)
|
||||
- Aggregate partial plans:
|
||||
- Merge execution groups (renumber group_ids sequentially: G1, G2, ...)
|
||||
- Merge timelines (detect cross-batch dependencies, adjust stages)
|
||||
- Resolve conflicts (same file in multiple batches → serialize)
|
||||
- Generate final fix-plan.json with aggregated metadata
|
||||
- TodoWrite update: Mark planning complete, start execution
|
||||
|
||||
**Phase 3: Execution Orchestration**
|
||||
- Load fix-plan.json timeline stages
|
||||
- For each stage:
|
||||
- If parallel mode: Launch all group agents via `Promise.all()`
|
||||
- If serial mode: Execute groups sequentially with `await`
|
||||
- Assign agent IDs (agents update their fix-progress-{N}.json)
|
||||
- Handle agent failures gracefully (mark group as failed, continue)
|
||||
- Advance to next stage only when current stage complete
|
||||
|
||||
**Phase 4: Completion & Aggregation**
|
||||
- Collect final status from all fix-progress-{N}.json files
|
||||
- Generate fix-summary.md with timeline and results
|
||||
- Update fix-history.json with new session entry
|
||||
- Remove active-fix-session.json
|
||||
- TodoWrite completion: Mark all phases done
|
||||
- Output summary to user
|
||||
|
||||
**Phase 5: Session Completion (Optional)**
|
||||
- If all findings fixed successfully (no failures):
|
||||
- Prompt user: "All fixes complete. Complete workflow session? [Y/n]"
|
||||
- If confirmed: Execute `/workflow:session:complete` to archive session with lessons learned
|
||||
- If partial success (some failures):
|
||||
- Output: "Some findings failed. Review fix-summary.md before completing session."
|
||||
- Do NOT auto-complete session
|
||||
|
||||
### Output File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── fix-export-{timestamp}.json # Exported findings (input)
|
||||
└── fixes/{fix-session-id}/
|
||||
├── partial-plan-1.json # Batch 1 partial plan (planning agent 1 output)
|
||||
├── partial-plan-2.json # Batch 2 partial plan (planning agent 2 output)
|
||||
├── partial-plan-N.json # Batch N partial plan (planning agent N output)
|
||||
├── fix-plan.json # Aggregated execution plan (orchestrator merges partials)
|
||||
├── fix-progress-1.json # Group 1 progress (planning agent init → agent updates)
|
||||
├── fix-progress-2.json # Group 2 progress (planning agent init → agent updates)
|
||||
├── fix-progress-3.json # Group 3 progress (planning agent init → agent updates)
|
||||
├── fix-summary.md # Final report (orchestrator generates)
|
||||
├── active-fix-session.json # Active session marker
|
||||
└── fix-history.json # All sessions history
|
||||
```
|
||||
|
||||
**File Producers**:
|
||||
- **Orchestrator**: Batches findings (Phase 1.5), aggregates partial plans → `fix-plan.json` (Phase 2), launches parallel planning agents
|
||||
- **Planning Agents (N)**: Each outputs `partial-plan-{batch-id}.json` + initializes `fix-progress-*.json` for assigned groups
|
||||
- **Execution Agents (M)**: Update assigned `fix-progress-{N}.json` in real-time
|
||||
|
||||
|
||||
### Agent Invocation Template
|
||||
|
||||
**Phase 1.5: Intelligent Batching** (Orchestrator):
|
||||
```javascript
|
||||
// Load findings
|
||||
const findings = JSON.parse(Read(exportFile));
|
||||
const batchSize = flags.batchSize || 5;
|
||||
|
||||
// Semantic similarity analysis: group by file+dimension
|
||||
const batches = [];
|
||||
const grouped = new Map(); // key: "${file}:${dimension}"
|
||||
|
||||
for (const finding of findings) {
|
||||
const key = `${finding.file || 'unknown'}:${finding.dimension || 'general'}`;
|
||||
if (!grouped.has(key)) grouped.set(key, []);
|
||||
grouped.get(key).push(finding);
|
||||
}
|
||||
|
||||
// Create batches respecting batchSize
|
||||
for (const [key, group] of grouped) {
|
||||
while (group.length > 0) {
|
||||
const batch = group.splice(0, batchSize);
|
||||
batches.push({
|
||||
batch_id: batches.length + 1,
|
||||
findings: batch,
|
||||
metadata: { primary_file: batch[0].file, primary_dimension: batch[0].dimension }
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
console.log(`Created ${batches.length} batches (${batchSize} findings per batch)`);
|
||||
```
|
||||
|
||||
**Phase 2: Parallel Planning** (Orchestrator launches N agents):
|
||||
```javascript
|
||||
const MAX_PARALLEL = 10;
|
||||
const partialPlans = [];
|
||||
|
||||
// Process batches in chunks of MAX_PARALLEL
|
||||
for (let i = 0; i < batches.length; i += MAX_PARALLEL) {
|
||||
const chunk = batches.slice(i, i + MAX_PARALLEL);
|
||||
const taskIds = [];
|
||||
|
||||
// Launch agents in parallel (run_in_background=true)
|
||||
for (const batch of chunk) {
|
||||
const taskId = Task({
|
||||
subagent_type: "cli-planning-agent",
|
||||
run_in_background: true,
|
||||
description: `Plan batch ${batch.batch_id}: ${batch.findings.length} findings`,
|
||||
prompt: planningPrompt(batch) // See Planning Agent template below
|
||||
});
|
||||
taskIds.push({ taskId, batch });
|
||||
}
|
||||
|
||||
console.log(`Launched ${taskIds.length} planning agents...`);
|
||||
|
||||
// Collect results from this chunk (blocking)
|
||||
for (const { taskId, batch } of taskIds) {
|
||||
const result = TaskOutput({ task_id: taskId, block: true });
|
||||
const partialPlan = JSON.parse(Read(`${sessionDir}/partial-plan-${batch.batch_id}.json`));
|
||||
partialPlans.push(partialPlan);
|
||||
updateTodo(`Batch ${batch.batch_id}`, 'completed');
|
||||
}
|
||||
}
|
||||
|
||||
// Aggregate partial plans → fix-plan.json
|
||||
let groupCounter = 1;
|
||||
const groupIdMap = new Map();
|
||||
|
||||
for (const partial of partialPlans) {
|
||||
for (const group of partial.groups) {
|
||||
const newGroupId = `G${groupCounter}`;
|
||||
groupIdMap.set(`${partial.batch_id}:${group.group_id}`, newGroupId);
|
||||
aggregatedPlan.groups.push({ ...group, group_id: newGroupId, progress_file: `fix-progress-${groupCounter}.json` });
|
||||
groupCounter++;
|
||||
}
|
||||
}
|
||||
|
||||
// Merge timelines, resolve cross-batch conflicts (shared files → serialize)
|
||||
let stageCounter = 1;
|
||||
for (const partial of partialPlans) {
|
||||
for (const stage of partial.timeline) {
|
||||
aggregatedPlan.timeline.push({
|
||||
...stage, stage_id: stageCounter,
|
||||
groups: stage.groups.map(gid => groupIdMap.get(`${partial.batch_id}:${gid}`))
|
||||
});
|
||||
stageCounter++;
|
||||
}
|
||||
}
|
||||
|
||||
// Write aggregated plan + initialize progress files
|
||||
Write(`${sessionDir}/fix-plan.json`, JSON.stringify(aggregatedPlan, null, 2));
|
||||
for (let i = 1; i <= aggregatedPlan.groups.length; i++) {
|
||||
Write(`${sessionDir}/fix-progress-${i}.json`, JSON.stringify(initProgressFile(aggregatedPlan.groups[i-1]), null, 2));
|
||||
}
|
||||
```
|
||||
|
||||
**Planning Agent (Batch Mode - Partial Plan Only)**:
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-planning-agent",
|
||||
run_in_background: true,
|
||||
description: `Plan batch ${batch.batch_id}: ${batch.findings.length} findings`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Analyze code review findings in batch ${batch.batch_id} and generate **partial** execution plan.
|
||||
|
||||
## Input Data
|
||||
Review Session: ${reviewId}
|
||||
Fix Session ID: ${fixSessionId}
|
||||
Batch ID: ${batch.batch_id}
|
||||
Batch Findings: ${batch.findings.length}
|
||||
|
||||
Findings:
|
||||
${JSON.stringify(batch.findings, null, 2)}
|
||||
|
||||
Project Context:
|
||||
- Structure: ${projectStructure}
|
||||
- Test Framework: ${testFramework}
|
||||
- Git Status: ${gitStatus}
|
||||
|
||||
## Output Requirements
|
||||
|
||||
### 1. partial-plan-${batch.batch_id}.json
|
||||
Generate partial execution plan with structure:
|
||||
{
|
||||
"batch_id": ${batch.batch_id},
|
||||
"groups": [...], // Groups created from batch findings (use local IDs: G1, G2, ...)
|
||||
"timeline": [...], // Local timeline for this batch only
|
||||
"metadata": {
|
||||
"findings_count": ${batch.findings.length},
|
||||
"groups_count": N,
|
||||
"created_at": "ISO-8601-timestamp"
|
||||
}
|
||||
}
|
||||
|
||||
**Key Generation Rules**:
|
||||
- **Groups**: Create groups with local IDs (G1, G2, ...) using intelligent grouping (file+dimension+root cause)
|
||||
- **Timeline**: Define stages for this batch only (local dependencies within batch)
|
||||
- **Progress Files**: DO NOT generate fix-progress-*.json here (orchestrator handles after aggregation)
|
||||
|
||||
## Analysis Requirements
|
||||
|
||||
### Intelligent Grouping Strategy
|
||||
Group findings using these criteria (in priority order):
|
||||
|
||||
1. **File Proximity**: Findings in same file or related files
|
||||
2. **Dimension Affinity**: Same dimension (security, performance, etc.)
|
||||
3. **Root Cause Similarity**: Similar underlying issues
|
||||
4. **Fix Approach Commonality**: Can be fixed with similar approach
|
||||
|
||||
**Grouping Guidelines**:
|
||||
- Optimal group size: 2-5 findings per group
|
||||
- Avoid cross-cutting concerns in same group
|
||||
- Consider test isolation (different test suites → different groups)
|
||||
- Balance workload across groups for parallel execution
|
||||
|
||||
### Execution Strategy Determination (Local Only)
|
||||
|
||||
**Parallel Mode**: Use when groups are independent, no shared files
|
||||
**Serial Mode**: Use when groups have dependencies or shared resources
|
||||
**Hybrid Mode**: Use for mixed dependency graphs (recommended for most cases)
|
||||
|
||||
**Dependency Analysis**:
|
||||
- Identify shared files between groups
|
||||
- Detect test dependency chains
|
||||
- Evaluate risk of concurrent modifications
|
||||
|
||||
### Risk Assessment
|
||||
|
||||
For each group, evaluate:
|
||||
- **Complexity**: Based on code structure, file size, existing tests
|
||||
- **Impact Scope**: Number of files affected, API surface changes
|
||||
- **Rollback Feasibility**: Ease of reverting changes if tests fail
|
||||
|
||||
### Test Strategy
|
||||
|
||||
For each group, determine:
|
||||
- **Test Pattern**: Glob pattern matching affected tests
|
||||
- **Pass Criteria**: All tests must pass (100% pass rate)
|
||||
- **Test Command**: Infer from project (package.json, pytest.ini, etc.)
|
||||
|
||||
## Output Files
|
||||
|
||||
Write to ${sessionDir}:
|
||||
- ./partial-plan-${batch.batch_id}.json
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finalizing outputs:
|
||||
- ✅ All batch findings assigned to exactly one group
|
||||
- ✅ Group dependencies (within batch) correctly identified
|
||||
- ✅ Timeline stages respect local dependencies
|
||||
- ✅ Test patterns are valid and specific
|
||||
- ✅ Risk assessments are realistic
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Execution Agent** (per group):
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-execute-agent",
|
||||
description: `Fix ${group.findings.length} issues: ${group.group_name}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Execute fixes for code review findings in group ${group.group_id}. Update progress file in real-time with flow control tracking.
|
||||
|
||||
## Assignment
|
||||
- Group ID: ${group.group_id}
|
||||
- Group Name: ${group.group_name}
|
||||
- Progress File: ${sessionDir}/${group.progress_file}
|
||||
- Findings Count: ${group.findings.length}
|
||||
- Max Iterations: ${maxIterations} (per finding)
|
||||
|
||||
## Fix Strategy
|
||||
${JSON.stringify(group.fix_strategy, null, 2)}
|
||||
|
||||
## Risk Assessment
|
||||
${JSON.stringify(group.risk_assessment, null, 2)}
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Initialization (Before Starting)
|
||||
|
||||
1. Read ${group.progress_file} to load initial state
|
||||
2. Update progress file:
|
||||
- assigned_agent: "${agentId}"
|
||||
- status: "in-progress"
|
||||
- started_at: Current ISO 8601 timestamp
|
||||
- last_update: Current ISO 8601 timestamp
|
||||
3. Write updated state back to ${group.progress_file}
|
||||
|
||||
### Main Execution Loop
|
||||
|
||||
For EACH finding in ${group.progress_file}.findings:
|
||||
|
||||
#### Step 1: Analyze Context
|
||||
|
||||
**Before Step**:
|
||||
- Update finding: status→"in-progress", started_at→now()
|
||||
- Update current_finding: Populate with finding details, status→"analyzing", action→"Reading file and understanding code structure"
|
||||
- Update phase→"analyzing"
|
||||
- Update flow_control: Add "analyze_context" step to implementation_approach (status→"in-progress"), set current_step→"analyze_context"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Read file: finding.file
|
||||
- Understand code structure around line: finding.line
|
||||
- Analyze surrounding context (imports, dependencies, related functions)
|
||||
- Review recommendations: finding.recommendations
|
||||
|
||||
**After Step**:
|
||||
- Update flow_control: Mark "analyze_context" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
#### Step 2: Apply Fix
|
||||
|
||||
**Before Step**:
|
||||
- Update current_finding: status→"fixing", action→"Applying code changes per recommendations"
|
||||
- Update phase→"fixing"
|
||||
- Update flow_control: Add "apply_fix" step to implementation_approach (status→"in-progress"), set current_step→"apply_fix"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Use Edit tool to implement code changes per finding.recommendations
|
||||
- Follow fix_strategy.approach
|
||||
- Maintain code style and existing patterns
|
||||
|
||||
**After Step**:
|
||||
- Update flow_control: Mark "apply_fix" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
#### Step 3: Test Verification
|
||||
|
||||
**Before Step**:
|
||||
- Update current_finding: status→"testing", action→"Running test suite to verify fix"
|
||||
- Update phase→"testing"
|
||||
- Update flow_control: Add "run_tests" step to implementation_approach (status→"in-progress"), set current_step→"run_tests"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Run tests using fix_strategy.test_pattern
|
||||
- Require 100% pass rate
|
||||
- Capture test output
|
||||
|
||||
**On Test Failure**:
|
||||
- Git rollback: \`git checkout -- \${finding.file}\`
|
||||
- Increment finding.attempts
|
||||
- Update flow_control: Mark "run_tests" step as "failed" with completed_at→now()
|
||||
- Update errors: Add entry (finding_id, error_type→"test_failure", message, timestamp)
|
||||
- If finding.attempts < ${maxIterations}:
|
||||
- Reset flow_control: implementation_approach→[], current_step→null
|
||||
- Retry from Step 1
|
||||
- Else:
|
||||
- Update finding: status→"completed", result→"failed", error_message→"Max iterations reached", completed_at→now()
|
||||
- Update summary counts, move to next finding
|
||||
|
||||
**On Test Success**:
|
||||
- Update flow_control: Mark "run_tests" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
- Proceed to Step 4
|
||||
|
||||
#### Step 4: Commit Changes
|
||||
|
||||
**Before Step**:
|
||||
- Update current_finding: status→"committing", action→"Creating git commit for successful fix"
|
||||
- Update phase→"committing"
|
||||
- Update flow_control: Add "commit_changes" step to implementation_approach (status→"in-progress"), set current_step→"commit_changes"
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
**Action**:
|
||||
- Git commit: \`git commit -m "fix(${finding.dimension}): ${finding.title} [${finding.id}]"\`
|
||||
- Capture commit hash
|
||||
|
||||
**After Step**:
|
||||
- Update finding: status→"completed", result→"fixed", commit_hash→<captured>, test_passed→true, completed_at→now()
|
||||
- Update flow_control: Mark "commit_changes" step as "completed" with completed_at→now()
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
#### After Each Finding
|
||||
|
||||
- Update summary: Recalculate counts (pending/in_progress/fixed/failed) and percent_complete
|
||||
- If all findings completed: Clear current_finding, reset flow_control
|
||||
- Update last_update→now(), write to ${group.progress_file}
|
||||
|
||||
### Final Completion
|
||||
|
||||
When all findings processed:
|
||||
- Update status→"completed", phase→"done", summary.percent_complete→100.0
|
||||
- Update last_update→now(), write final state to ${group.progress_file}
|
||||
|
||||
## Critical Requirements
|
||||
|
||||
### Progress File Updates
|
||||
- **MUST update after every significant action** (before/after each step)
|
||||
- **Always maintain complete structure** - never write partial updates
|
||||
- **Use ISO 8601 timestamps** - e.g., "2025-01-25T14:36:00Z"
|
||||
|
||||
### Flow Control Format
|
||||
Follow action-planning-agent flow_control.implementation_approach format:
|
||||
- step: Identifier (e.g., "analyze_context", "apply_fix")
|
||||
- action: Human-readable description
|
||||
- status: "pending" | "in-progress" | "completed" | "failed"
|
||||
- started_at: ISO 8601 timestamp or null
|
||||
- completed_at: ISO 8601 timestamp or null
|
||||
|
||||
### Error Handling
|
||||
- Capture all errors in errors[] array
|
||||
- Never leave progress file in invalid state
|
||||
- Always write complete updates, never partial
|
||||
- On unrecoverable error: Mark group as failed, preserve state
|
||||
|
||||
## Test Patterns
|
||||
Use fix_strategy.test_pattern to run affected tests:
|
||||
- Pattern: ${group.fix_strategy.test_pattern}
|
||||
- Command: Infer from project (npm test, pytest, etc.)
|
||||
- Pass Criteria: 100% pass rate required
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Batching Failures (Phase 1.5)**:
|
||||
- Invalid findings data → Abort with error message
|
||||
- Empty batches after grouping → Warn and skip empty batches
|
||||
|
||||
**Planning Failures (Phase 2)**:
|
||||
- Planning agent timeout → Mark batch as failed, continue with other batches
|
||||
- Partial plan missing → Skip batch, warn user
|
||||
- Agent crash → Collect available partial plans, proceed with aggregation
|
||||
- All agents fail → Abort entire fix session with error
|
||||
- Aggregation conflicts → Apply conflict resolution (serialize conflicting groups)
|
||||
|
||||
**Execution Failures (Phase 3)**:
|
||||
- Agent crash → Mark group as failed, continue with other groups
|
||||
- Test command not found → Skip test verification, warn user
|
||||
- Git operations fail → Abort with error, preserve state
|
||||
|
||||
**Rollback Scenarios**:
|
||||
- Test failure after fix → Automatic `git checkout` rollback
|
||||
- Max iterations reached → Leave file unchanged, mark as failed
|
||||
- Unrecoverable error → Rollback entire group, save checkpoint
|
||||
|
||||
### TodoWrite Structure
|
||||
|
||||
**Initialization (after Phase 1.5 batching)**:
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Discovering"},
|
||||
{content: "Phase 1.5: Intelligent Batching", status: "completed", activeForm: "Batching"},
|
||||
{content: "Phase 2: Parallel Planning", status: "in_progress", activeForm: "Planning"},
|
||||
{content: " → Batch 1: 4 findings (auth.ts:security)", status: "pending", activeForm: "Planning batch 1"},
|
||||
{content: " → Batch 2: 3 findings (query.ts:security)", status: "pending", activeForm: "Planning batch 2"},
|
||||
{content: " → Batch 3: 2 findings (config.ts:quality)", status: "pending", activeForm: "Planning batch 3"},
|
||||
{content: "Phase 3: Execution", status: "pending", activeForm: "Executing"},
|
||||
{content: "Phase 4: Completion", status: "pending", activeForm: "Completing"}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
**During Planning (parallel agents running)**:
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Discovering"},
|
||||
{content: "Phase 1.5: Intelligent Batching", status: "completed", activeForm: "Batching"},
|
||||
{content: "Phase 2: Parallel Planning", status: "in_progress", activeForm: "Planning"},
|
||||
{content: " → Batch 1: 4 findings (auth.ts:security)", status: "completed", activeForm: "Planning batch 1"},
|
||||
{content: " → Batch 2: 3 findings (query.ts:security)", status: "in_progress", activeForm: "Planning batch 2"},
|
||||
{content: " → Batch 3: 2 findings (config.ts:quality)", status: "in_progress", activeForm: "Planning batch 3"},
|
||||
{content: "Phase 3: Execution", status: "pending", activeForm: "Executing"},
|
||||
{content: "Phase 4: Completion", status: "pending", activeForm: "Completing"}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
**During Execution**:
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Discovering"},
|
||||
{content: "Phase 1.5: Intelligent Batching", status: "completed", activeForm: "Batching"},
|
||||
{content: "Phase 2: Parallel Planning (3 batches → 5 groups)", status: "completed", activeForm: "Planning"},
|
||||
{content: "Phase 3: Execution", status: "in_progress", activeForm: "Executing"},
|
||||
{content: " → Stage 1: Parallel execution (3 groups)", status: "completed", activeForm: "Executing stage 1"},
|
||||
{content: " • Group G1: Auth validation (2 findings)", status: "completed", activeForm: "Fixing G1"},
|
||||
{content: " • Group G2: Query security (3 findings)", status: "completed", activeForm: "Fixing G2"},
|
||||
{content: " • Group G3: Config quality (1 finding)", status: "completed", activeForm: "Fixing G3"},
|
||||
{content: " → Stage 2: Serial execution (1 group)", status: "in_progress", activeForm: "Executing stage 2"},
|
||||
{content: " • Group G4: Dependent fixes (2 findings)", status: "in_progress", activeForm: "Fixing G4"},
|
||||
{content: "Phase 4: Completion", status: "pending", activeForm: "Completing"}
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
**Update Rules**:
|
||||
- Add batch items dynamically during Phase 1.5
|
||||
- Mark batch items completed as parallel agents return results
|
||||
- Add stage/group items dynamically after Phase 2 plan aggregation
|
||||
- Mark completed immediately after each group finishes
|
||||
- Update parent phase status when all child items complete
|
||||
|
||||
## Post-Completion Expansion
|
||||
|
||||
完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Leverage Parallel Planning**: For 10+ findings, parallel batching significantly reduces planning time
|
||||
2. **Tune Batch Size**: Use `--batch-size` to control granularity (smaller batches = more parallelism, larger = better grouping context)
|
||||
3. **Conservative Approach**: Test verification is mandatory - no fixes kept without passing tests
|
||||
4. **Parallel Efficiency**: MAX_PARALLEL=10 for planning agents, 3 concurrent execution agents per stage
|
||||
5. **Resume Support**: Fix sessions can resume from checkpoints after interruption
|
||||
6. **Manual Review**: Always review failed fixes manually - may require architectural changes
|
||||
7. **Incremental Fixing**: Start with small batches (5-10 findings) before large-scale fixes
|
||||
|
||||
## Related Commands
|
||||
|
||||
### View Fix Progress
|
||||
Use `ccw view` to open the workflow dashboard in browser:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
@@ -1,771 +0,0 @@
|
||||
---
|
||||
name: review-module-cycle
|
||||
description: Independent multi-dimensional code review for specified modules/files. Analyzes specific code paths across 7 dimensions with hybrid parallel-iterative execution, independent of workflow sessions.
|
||||
argument-hint: "<path-pattern> [--dimensions=security,architecture,...] [--max-iterations=N]"
|
||||
allowed-tools: Skill(*), TodoWrite(*), Read(*), Bash(*), Task(*)
|
||||
---
|
||||
|
||||
# Workflow Review-Module-Cycle Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Review specific module (all 7 dimensions)
|
||||
/workflow:review-module-cycle src/auth/**
|
||||
|
||||
# Review multiple modules
|
||||
/workflow:review-module-cycle src/auth/**,src/payment/**
|
||||
|
||||
# Review with custom dimensions
|
||||
/workflow:review-module-cycle src/payment/** --dimensions=security,architecture,quality
|
||||
|
||||
# Review specific files
|
||||
/workflow:review-module-cycle src/payment/processor.ts,src/payment/validator.ts
|
||||
```
|
||||
|
||||
**Review Scope**: Specified modules/files only (independent of git history)
|
||||
**Session Requirement**: Auto-creates workflow session via `/workflow:session:start`
|
||||
**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based)
|
||||
**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
|
||||
**Max Iterations**: 3 (adjustable via --max-iterations)
|
||||
**Default Iterations**: 1 (deep-dive runs once; use --max-iterations=0 to skip)
|
||||
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
Independent multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **specific modules or files**.
|
||||
|
||||
**Review Scope**:
|
||||
- **Module-based**: Reviews specified file patterns (e.g., `src/auth/**`, `*.ts`)
|
||||
- **Session-integrated**: Runs within workflow session context for unified tracking
|
||||
- **Output location**: `.review/` subdirectory within active session
|
||||
|
||||
**vs Session Review**:
|
||||
- **Session Review** (`review-session-cycle`): Reviews git changes within a workflow session
|
||||
- **Module Review** (`review-module-cycle`): Reviews any specified code paths, regardless of git history
|
||||
- **Common output**: Both use same `.review/` directory structure within session
|
||||
|
||||
### Value Proposition
|
||||
1. **Module-Focused Review**: Target specific code areas independent of git history
|
||||
2. **Session-Integrated**: Review results tracked within workflow session for unified management
|
||||
3. **Comprehensive Coverage**: Same 7 specialized dimensions as session review
|
||||
4. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns
|
||||
5. **Unified Archive**: Review results archived with session for historical reference
|
||||
|
||||
### Orchestrator Boundary (CRITICAL)
|
||||
- **ONLY command** for independent multi-dimensional module review
|
||||
- Manages: dimension coordination, aggregation, iteration control, progress tracking
|
||||
- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode
|
||||
|
||||
## How It Works
|
||||
|
||||
### Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization
|
||||
└─ Resolve file patterns, validate paths, initialize state, create output structure
|
||||
|
||||
Phase 2: Parallel Reviews (for each dimension)
|
||||
├─ Launch 7 review agents simultaneously
|
||||
├─ Each executes CLI analysis via Gemini/Qwen on specified files
|
||||
├─ Generate dimension JSON + markdown reports
|
||||
└─ Update review-progress.json
|
||||
|
||||
Phase 3: Aggregation
|
||||
├─ Load all dimension JSON files
|
||||
├─ Calculate severity distribution (critical/high/medium/low)
|
||||
├─ Identify cross-cutting concerns (files in 3+ dimensions)
|
||||
└─ Decision:
|
||||
├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate)
|
||||
└─ Else → Phase 5 (Complete)
|
||||
|
||||
Phase 4: Iterative Deep-Dive (optional)
|
||||
├─ Select critical findings (max 5 per iteration)
|
||||
├─ Launch deep-dive agents for root cause analysis
|
||||
├─ Generate remediation plans with impact assessment
|
||||
├─ Re-assess severity based on analysis
|
||||
└─ Loop until no critical findings OR max iterations
|
||||
|
||||
Phase 5: Completion
|
||||
└─ Finalize review-progress.json
|
||||
```
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Orchestrator** | Phase control, path resolution, state management, aggregation logic, iteration control |
|
||||
| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports |
|
||||
| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment |
|
||||
|
||||
## Enhanced Features
|
||||
|
||||
### 1. Review Dimensions Configuration
|
||||
|
||||
**7 Specialized Dimensions** with priority-based allocation:
|
||||
|
||||
| Dimension | Template | Priority | Timeout |
|
||||
|-----------|----------|----------|---------|
|
||||
| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min |
|
||||
| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min |
|
||||
| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min |
|
||||
| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min |
|
||||
| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min |
|
||||
| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min |
|
||||
| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min |
|
||||
|
||||
*Custom focus: "Assess technical debt and maintainability"
|
||||
|
||||
**Category Definitions by Dimension**:
|
||||
|
||||
```javascript
|
||||
const CATEGORIES = {
|
||||
security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'],
|
||||
architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'],
|
||||
quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'],
|
||||
'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'],
|
||||
performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'],
|
||||
maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'],
|
||||
'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style']
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Path Pattern Resolution
|
||||
|
||||
**Syntax Rules**:
|
||||
- All paths are **relative** from project root (e.g., `src/auth/**` not `/src/auth/**`)
|
||||
- Multiple patterns: comma-separated, **no spaces** (e.g., `src/auth/**,src/payment/**`)
|
||||
- Glob and specific files can be mixed (e.g., `src/auth/**,src/config.ts`)
|
||||
|
||||
**Supported Patterns**:
|
||||
| Pattern Type | Example | Description |
|
||||
|--------------|---------|-------------|
|
||||
| Glob directory | `src/auth/**` | All files under src/auth/ |
|
||||
| Glob with extension | `src/**/*.ts` | All .ts files under src/ |
|
||||
| Specific file | `src/payment/processor.ts` | Single file |
|
||||
| Multiple patterns | `src/auth/**,src/payment/**` | Comma-separated (no spaces) |
|
||||
|
||||
**Resolution Process**:
|
||||
1. Parse input pattern (split by comma, trim whitespace)
|
||||
2. Expand glob patterns to file list via `find` command
|
||||
3. Validate all files exist and are readable
|
||||
4. Error if pattern matches 0 files
|
||||
5. Store resolved file list in review-state.json
|
||||
|
||||
### 3. Aggregation Logic
|
||||
|
||||
**Cross-Cutting Concern Detection**:
|
||||
1. Files appearing in 3+ dimensions = **Critical Files**
|
||||
2. Same issue pattern across dimensions = **Systemic Issue**
|
||||
3. Severity clustering in specific files = **Hotspots**
|
||||
|
||||
**Deep-Dive Selection Criteria**:
|
||||
- All critical severity findings (priority 1)
|
||||
- Top 3 high-severity findings in critical files (priority 2)
|
||||
- Max 5 findings per iteration (prevent overwhelm)
|
||||
|
||||
### 4. Severity Assessment
|
||||
|
||||
**Severity Levels**:
|
||||
- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass
|
||||
- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt
|
||||
- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns
|
||||
- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues
|
||||
|
||||
**Iteration Trigger**:
|
||||
- Critical findings > 0 OR
|
||||
- High findings > 5 OR
|
||||
- Critical files count > 0
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Orchestrator
|
||||
|
||||
**Phase 1: Discovery & Initialization**
|
||||
|
||||
**Step 1: Session Creation**
|
||||
```javascript
|
||||
// Create workflow session for this review (type: review)
|
||||
Skill(skill="workflow:session:start", args="--type review \"Code review for [target_pattern]\"")
|
||||
|
||||
// Parse output
|
||||
const sessionId = output.match(/SESSION_ID: (WFS-[^\s]+)/)[1];
|
||||
```
|
||||
|
||||
**Step 2: Path Resolution & Validation**
|
||||
```bash
|
||||
# Expand glob pattern to file list (relative paths from project root)
|
||||
find . -path "./src/auth/**" -type f | sed 's|^\./||'
|
||||
|
||||
# Validate files exist and are readable
|
||||
for file in ${resolvedFiles[@]}; do
|
||||
test -r "$file" || error "File not readable: $file"
|
||||
done
|
||||
```
|
||||
- Parse and expand file patterns (glob support): `src/auth/**` → actual file list
|
||||
- Validation: Ensure all specified files exist and are readable
|
||||
- Store as **relative paths** from project root (e.g., `src/auth/service.ts`)
|
||||
- Agents construct absolute paths dynamically during execution
|
||||
|
||||
**Step 3: Output Directory Setup**
|
||||
- Output directory: `.workflow/active/${sessionId}/.review/`
|
||||
- Create directory structure:
|
||||
```bash
|
||||
mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
|
||||
```
|
||||
|
||||
**Step 4: Initialize Review State**
|
||||
- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations, resolved_files (merged metadata + state)
|
||||
- Progress tracking: Create `review-progress.json` for progress tracking
|
||||
|
||||
**Step 5: TodoWrite Initialization**
|
||||
- Set up progress tracking with hierarchical structure
|
||||
- Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
**Phase 2: Parallel Review Coordination**
|
||||
- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
|
||||
- Pass dimension-specific context (template, timeout, custom focus, **target files**)
|
||||
- Monitor completion via review-progress.json updates
|
||||
- TodoWrite updates: Mark dimensions as completed
|
||||
- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout)
|
||||
|
||||
**Phase 3: Aggregation**
|
||||
- Load all dimension JSON files from dimensions/
|
||||
- Calculate severity distribution: Count by critical/high/medium/low
|
||||
- Identify cross-cutting concerns: Files in 3+ dimensions
|
||||
- Select deep-dive findings: Critical + high in critical files (max 5)
|
||||
- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist
|
||||
- Update review-state.json with aggregation results
|
||||
|
||||
**Phase 4: Iteration Control**
|
||||
- Check iteration count < max_iterations (default 3)
|
||||
- Launch deep-dive agents for selected findings
|
||||
- Collect remediation plans and re-assessed severities
|
||||
- Update severity distribution based on re-assessments
|
||||
- Record iteration in review-state.json
|
||||
- Loop back to aggregation if still have critical/high findings
|
||||
|
||||
**Phase 5: Completion**
|
||||
- Finalize review-progress.json with completion statistics
|
||||
- Update review-state.json with completion_time and phase=complete
|
||||
- TodoWrite completion: Mark all tasks done
|
||||
|
||||
|
||||
|
||||
### Output File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── review-state.json # Orchestrator state machine (includes metadata)
|
||||
├── review-progress.json # Real-time progress for dashboard
|
||||
├── dimensions/ # Per-dimension results
|
||||
│ ├── security.json
|
||||
│ ├── architecture.json
|
||||
│ ├── quality.json
|
||||
│ ├── action-items.json
|
||||
│ ├── performance.json
|
||||
│ ├── maintainability.json
|
||||
│ └── best-practices.json
|
||||
├── iterations/ # Deep-dive results
|
||||
│ ├── iteration-1-finding-{uuid}.json
|
||||
│ └── iteration-2-finding-{uuid}.json
|
||||
└── reports/ # Human-readable reports
|
||||
├── security-analysis.md
|
||||
├── security-cli-output.txt
|
||||
├── deep-dive-1-{uuid}.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Session Context**:
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .task/
|
||||
├── .summaries/
|
||||
└── .review/ # Review results (this command)
|
||||
└── (structure above)
|
||||
```
|
||||
|
||||
### Review State JSON
|
||||
|
||||
**Purpose**: Unified state machine and metadata (merged from metadata + state)
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"review_type": "module",
|
||||
"session_id": "WFS-auth-system",
|
||||
"metadata": {
|
||||
"created_at": "2025-01-25T14:30:22Z",
|
||||
"target_pattern": "src/auth/**",
|
||||
"resolved_files": [
|
||||
"src/auth/service.ts",
|
||||
"src/auth/validator.ts",
|
||||
"src/auth/middleware.ts"
|
||||
],
|
||||
"dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"max_iterations": 3
|
||||
},
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"selected_strategy": "comprehensive",
|
||||
"next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",
|
||||
"severity_distribution": {
|
||||
"critical": 2,
|
||||
"high": 5,
|
||||
"medium": 12,
|
||||
"low": 8
|
||||
},
|
||||
"critical_files": [...],
|
||||
"iterations": [...],
|
||||
"completion_criteria": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Review Progress JSON
|
||||
|
||||
**Purpose**: Real-time dashboard updates via polling
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"last_update": "2025-01-25T14:35:10Z",
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"progress": {
|
||||
"parallel_review": {
|
||||
"total_dimensions": 7,
|
||||
"completed": 5,
|
||||
"in_progress": 2,
|
||||
"percent_complete": 71
|
||||
},
|
||||
"deep_dive": {
|
||||
"total_findings": 6,
|
||||
"analyzed": 2,
|
||||
"in_progress": 1,
|
||||
"percent_complete": 33
|
||||
}
|
||||
},
|
||||
"agent_status": [
|
||||
{
|
||||
"agent_type": "review-agent",
|
||||
"dimension": "security",
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-25T14:30:00Z",
|
||||
"completed_at": "2025-01-25T15:15:00Z",
|
||||
"duration_ms": 2700000
|
||||
},
|
||||
{
|
||||
"agent_type": "deep-dive-agent",
|
||||
"finding_id": "sec-001-uuid",
|
||||
"status": "in_progress",
|
||||
"started_at": "2025-01-25T14:32:00Z"
|
||||
}
|
||||
],
|
||||
"estimated_completion": "2025-01-25T16:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Agent Output Schemas
|
||||
|
||||
**Agent-produced JSON files follow standardized schemas**:
|
||||
|
||||
1. **Dimension Results** (cli-explore-agent output from parallel reviews)
|
||||
- Schema: `~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json`
|
||||
- Output: `{output-dir}/dimensions/{dimension}.json`
|
||||
- Contains: findings array, summary statistics, cross_references
|
||||
|
||||
2. **Deep-Dive Results** (cli-explore-agent output from iterations)
|
||||
- Schema: `~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json`
|
||||
- Output: `{output-dir}/iterations/iteration-{N}-finding-{uuid}.json`
|
||||
- Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity
|
||||
|
||||
### Agent Invocation Template
|
||||
|
||||
**Review Agent** (parallel execution, 7 instances):
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Execute ${dimension} review analysis via Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for specified module files
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Deep Scan mode** for this review:
|
||||
- Phase 1: Bash structural scan for standard patterns (classes, functions, imports)
|
||||
- Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
|
||||
- Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Read review state: ${reviewStateJsonPath}
|
||||
2. Get target files: Read resolved_files from review-state.json
|
||||
3. Validate file access: bash(ls -la ${targetFiles.join(' ')})
|
||||
4. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
|
||||
5. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
6. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
|
||||
|
||||
## Review Context
|
||||
- Review Type: module (independent)
|
||||
- Review Dimension: ${dimension}
|
||||
- Review ID: ${reviewId}
|
||||
- Target Pattern: ${targetPattern}
|
||||
- Resolved Files: ${resolvedFiles.length} files
|
||||
- Output Directory: ${outputDir}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex (fallback chain)
|
||||
- Custom Focus: ${customFocus || 'Standard dimension analysis'}
|
||||
- Mode: analysis (READ-ONLY)
|
||||
- Context Pattern: ${targetFiles.map(f => `@${f}`).join(' ')}
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 4, follow schema exactly
|
||||
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at)
|
||||
- cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms
|
||||
- summary (FLAT structure), findings, cross_references
|
||||
|
||||
Summary MUST be FLAT (NOT nested by_severity):
|
||||
\`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\`
|
||||
|
||||
Finding required fields:
|
||||
- id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase)
|
||||
- severity: lowercase only (critical|high|medium|low)
|
||||
- snippet (NOT code_snippet), impact (NOT exploit_scenario)
|
||||
- metadata, iteration (0), status (pending_remediation), cross_references
|
||||
|
||||
2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md
|
||||
- Human-readable summary with recommendations
|
||||
- Grouped by severity: critical → high → medium → low
|
||||
- Include file:line references for all findings
|
||||
|
||||
3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt
|
||||
- Raw CLI tool output for debugging
|
||||
- Include full analysis text
|
||||
|
||||
## Dimension-Specific Guidance
|
||||
${getDimensionGuidance(dimension)}
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat review-dimension-results-schema.json
|
||||
- [ ] All target files analyzed for ${dimension} concerns
|
||||
- [ ] All findings include file:line references with code snippets
|
||||
- [ ] Severity assessment follows established criteria (see reference)
|
||||
- [ ] Recommendations are actionable with code examples
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] Report is comprehensive and well-organized
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Deep-Dive Agent** (iteration execution):
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Dependency Map mode** first to understand dependencies:
|
||||
- Build dependency graph around ${file} to identify affected components
|
||||
- Detect circular dependencies or tight coupling related to this finding
|
||||
- Calculate change risk scores for remediation impact
|
||||
|
||||
Then apply **Deep Scan mode** for semantic analysis:
|
||||
- Understand design intent and architectural context
|
||||
- Identify non-standard patterns or implicit dependencies
|
||||
- Extract remediation insights from code structure
|
||||
|
||||
## Finding Context
|
||||
- Finding ID: ${findingId}
|
||||
- Original Dimension: ${dimension}
|
||||
- Title: ${findingTitle}
|
||||
- File: ${file}:${line}
|
||||
- Severity: ${severity}
|
||||
- Category: ${category}
|
||||
- Original Description: ${description}
|
||||
- Iteration: ${iteration}
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Read original finding: ${dimensionJsonPath}
|
||||
2. Read affected file: ${file}
|
||||
3. Identify related code: bash(grep -r "import.*${basename(file)}" ${projectDir}/src --include="*.ts")
|
||||
4. Read test files: bash(find ${projectDir}/tests -name "*${basename(file, '.ts')}*" -type f)
|
||||
5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
- Template: ~/.ccw/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
|
||||
|
||||
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- finding_id, dimension, iteration, analysis_timestamp
|
||||
- cli_tool_used, model, analysis_duration_ms
|
||||
- original_finding, root_cause, remediation_plan
|
||||
- impact_assessment, reassessed_severity, confidence_score, cross_references
|
||||
|
||||
All nested objects must follow schema exactly - read schema for field names
|
||||
|
||||
2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md
|
||||
- Detailed root cause analysis
|
||||
- Step-by-step remediation plan
|
||||
- Impact assessment and rollback strategy
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat review-deep-dive-results-schema.json
|
||||
- [ ] Root cause clearly identified with supporting evidence
|
||||
- [ ] Remediation plan is step-by-step actionable with exact file:line references
|
||||
- [ ] Each step includes specific commands and validation tests
|
||||
- [ ] Impact fully assessed (files, tests, breaking changes, dependencies)
|
||||
- [ ] Severity re-evaluation justified with evidence
|
||||
- [ ] Confidence score accurately reflects certainty of analysis
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] References include project-specific and external documentation
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Dimension Guidance Reference
|
||||
|
||||
```javascript
|
||||
function getDimensionGuidance(dimension) {
|
||||
const guidance = {
|
||||
security: `
|
||||
Focus Areas:
|
||||
- Input validation and sanitization
|
||||
- Authentication and authorization mechanisms
|
||||
- Data encryption (at-rest and in-transit)
|
||||
- SQL/NoSQL injection vulnerabilities
|
||||
- XSS, CSRF, and other web vulnerabilities
|
||||
- Sensitive data exposure
|
||||
- Access control and privilege escalation
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure
|
||||
- High: Missing authorization checks, weak encryption, exposed secrets
|
||||
- Medium: Missing input validation, insecure defaults, weak password policies
|
||||
- Low: Security headers missing, verbose error messages, outdated dependencies
|
||||
`,
|
||||
architecture: `
|
||||
Focus Areas:
|
||||
- Layering and separation of concerns
|
||||
- Coupling and cohesion
|
||||
- Design pattern adherence
|
||||
- Dependency management
|
||||
- Scalability and extensibility
|
||||
- Module boundaries
|
||||
- API design consistency
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Circular dependencies, god objects, tight coupling across layers
|
||||
- High: Violated architectural principles, scalability bottlenecks
|
||||
- Medium: Missing abstractions, inconsistent patterns, suboptimal design
|
||||
- Low: Minor coupling issues, documentation gaps, naming inconsistencies
|
||||
`,
|
||||
quality: `
|
||||
Focus Areas:
|
||||
- Code duplication
|
||||
- Complexity (cyclomatic, cognitive)
|
||||
- Naming conventions
|
||||
- Error handling patterns
|
||||
- Code readability
|
||||
- Comment quality
|
||||
- Dead code
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Severe complexity (CC > 20), massive duplication (>50 lines)
|
||||
- High: High complexity (CC > 10), significant duplication, poor error handling
|
||||
- Medium: Moderate complexity (CC > 5), naming issues, code smells
|
||||
- Low: Minor duplication, documentation gaps, cosmetic issues
|
||||
`,
|
||||
'action-items': `
|
||||
Focus Areas:
|
||||
- Requirements coverage verification
|
||||
- Acceptance criteria met
|
||||
- Documentation completeness
|
||||
- Deployment readiness
|
||||
- Missing functionality
|
||||
- Test coverage gaps
|
||||
- Configuration management
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Core requirements not met, deployment blockers
|
||||
- High: Significant functionality missing, acceptance criteria not met
|
||||
- Medium: Minor requirements gaps, documentation incomplete
|
||||
- Low: Nice-to-have features missing, minor documentation gaps
|
||||
`,
|
||||
performance: `
|
||||
Focus Areas:
|
||||
- N+1 query problems
|
||||
- Inefficient algorithms (O(n²) where O(n log n) possible)
|
||||
- Memory leaks
|
||||
- Blocking operations on main thread
|
||||
- Missing caching opportunities
|
||||
- Resource usage (CPU, memory, network)
|
||||
- Database query optimization
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Memory leaks, O(n²) in hot path, blocking main thread
|
||||
- High: N+1 queries, missing indexes, inefficient algorithms
|
||||
- Medium: Suboptimal caching, unnecessary computations, lazy loading issues
|
||||
- Low: Minor optimization opportunities, redundant operations
|
||||
`,
|
||||
maintainability: `
|
||||
Focus Areas:
|
||||
- Technical debt indicators
|
||||
- Magic numbers and hardcoded values
|
||||
- Long methods (>50 lines)
|
||||
- Large classes (>500 lines)
|
||||
- Dead code and commented code
|
||||
- Code documentation
|
||||
- Test coverage
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Massive methods (>200 lines), severe technical debt blocking changes
|
||||
- High: Large methods (>100 lines), significant dead code, undocumented complex logic
|
||||
- Medium: Magic numbers, moderate technical debt, missing tests
|
||||
- Low: Minor refactoring opportunities, cosmetic improvements
|
||||
`,
|
||||
'best-practices': `
|
||||
Focus Areas:
|
||||
- Framework conventions adherence
|
||||
- Language idioms
|
||||
- Anti-patterns
|
||||
- Deprecated API usage
|
||||
- Coding standards compliance
|
||||
- Error handling patterns
|
||||
- Logging and monitoring
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Severe anti-patterns, deprecated APIs with security risks
|
||||
- High: Major convention violations, poor error handling, missing logging
|
||||
- Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns
|
||||
- Low: Cosmetic style issues, minor convention deviations
|
||||
`
|
||||
};
|
||||
|
||||
return guidance[dimension] || 'Standard code review analysis';
|
||||
}
|
||||
```
|
||||
|
||||
### Completion Conditions
|
||||
|
||||
**Full Success**:
|
||||
- All dimensions reviewed
|
||||
- Critical findings = 0
|
||||
- High findings ≤ 5
|
||||
- Action: Generate final report, mark phase=complete
|
||||
|
||||
**Partial Success**:
|
||||
- All dimensions reviewed
|
||||
- Max iterations reached
|
||||
- Still have critical/high findings
|
||||
- Action: Generate report with warnings, recommend follow-up
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase-Level Error Matrix**:
|
||||
|
||||
| Phase | Error | Blocking? | Action |
|
||||
|-------|-------|-----------|--------|
|
||||
| Phase 1 | Invalid path pattern | Yes | Error and exit |
|
||||
| Phase 1 | No files matched | Yes | Error and exit |
|
||||
| Phase 1 | Files not readable | Yes | Error and exit |
|
||||
| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
|
||||
| Phase 2 | All dimensions fail | Yes | Error and exit |
|
||||
| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
|
||||
| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
|
||||
| Phase 4 | Max iterations reached | No | Generate partial report |
|
||||
|
||||
**CLI Fallback Chain**: Gemini → Qwen → Codex → degraded mode
|
||||
|
||||
**Fallback Triggers**:
|
||||
1. HTTP 429, 5xx errors, connection timeout
|
||||
2. Invalid JSON output (parse error, missing required fields)
|
||||
3. Low confidence score < 0.4
|
||||
4. Analysis too brief (< 100 words in report)
|
||||
|
||||
**Fallback Behavior**:
|
||||
- On trigger: Retry with next tool in chain
|
||||
- After Codex fails: Enter degraded mode (skip analysis, log error)
|
||||
- Degraded mode: Continue workflow with available results
|
||||
|
||||
### TodoWrite Structure
|
||||
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Initializing" },
|
||||
{ content: "Phase 2: Parallel Reviews (7 dimensions)", status: "in_progress", activeForm: "Reviewing" },
|
||||
{ content: " → Security review", status: "in_progress", activeForm: "Analyzing security" },
|
||||
// ... other dimensions as sub-items
|
||||
{ content: "Phase 3: Aggregation", status: "pending", activeForm: "Aggregating" },
|
||||
{ content: "Phase 4: Deep-dive", status: "pending", activeForm: "Deep-diving" },
|
||||
{ content: "Phase 5: Completion", status: "pending", activeForm: "Completing" }
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start Specific**: Begin with focused module patterns for faster results
|
||||
2. **Expand Gradually**: Add more modules based on initial findings
|
||||
3. **Use Glob Wisely**: `src/auth/**` is more efficient than `src/**` with lots of irrelevant files
|
||||
4. **Trust Aggregation Logic**: Auto-selection based on proven heuristics
|
||||
5. **Monitor Logs**: Check reports/ directory for CLI analysis insights
|
||||
|
||||
## Related Commands
|
||||
|
||||
### View Review Progress
|
||||
Use `ccw view` to open the review dashboard in browser:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
|
||||
### Automated Fix Workflow
|
||||
After completing a module review, use the generated findings JSON for automated fixing:
|
||||
|
||||
```bash
|
||||
# Step 1: Complete review (this command)
|
||||
/workflow:review-module-cycle src/auth/**
|
||||
|
||||
# Step 2: Run automated fixes using dimension findings
|
||||
/workflow:review-cycle-fix .workflow/active/WFS-{session-id}/.review/
|
||||
```
|
||||
|
||||
See `/workflow:review-cycle-fix` for automated fixing with smart grouping, parallel execution, and test verification.
|
||||
|
||||
@@ -1,782 +0,0 @@
|
||||
---
|
||||
name: review-session-cycle
|
||||
description: Session-based comprehensive multi-dimensional code review. Analyzes git changes from workflow session across 7 dimensions with hybrid parallel-iterative execution, aggregates findings, and performs focused deep-dives on critical issues until quality gates met.
|
||||
argument-hint: "[session-id] [--dimensions=security,architecture,...] [--max-iterations=N]"
|
||||
allowed-tools: Skill(*), TodoWrite(*), Read(*), Bash(*), Task(*)
|
||||
---
|
||||
|
||||
# Workflow Review-Session-Cycle Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Execute comprehensive session review (all 7 dimensions)
|
||||
/workflow:review-session-cycle
|
||||
|
||||
# Review specific session with custom dimensions
|
||||
/workflow:review-session-cycle WFS-payment-integration --dimensions=security,architecture,quality
|
||||
|
||||
# Specify session and iteration limit
|
||||
/workflow:review-session-cycle WFS-payment-integration --max-iterations=5
|
||||
```
|
||||
|
||||
**Review Scope**: Git changes from session creation to present (via `git log --since`)
|
||||
**Session Requirement**: Requires active or completed workflow session
|
||||
**Output Directory**: `.workflow/active/WFS-{session-id}/.review/` (session-based)
|
||||
**Default Dimensions**: Security, Architecture, Quality, Action-Items, Performance, Maintainability, Best-Practices
|
||||
**Max Iterations**: 3 (adjustable via --max-iterations)
|
||||
**Default Iterations**: 1 (deep-dive runs once; use --max-iterations=0 to skip)
|
||||
**CLI Tools**: Gemini → Qwen → Codex (fallback chain)
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
Session-based multi-dimensional code review orchestrator with **hybrid parallel-iterative execution** for comprehensive quality assessment of **git changes within a workflow session**.
|
||||
|
||||
**Review Scope**:
|
||||
- **Session-based**: Reviews only files changed during the workflow session (via `git log --since="${sessionCreatedAt}"`)
|
||||
- **For independent module review**: Use `/workflow:review-module-cycle` command instead
|
||||
|
||||
**vs Standard Review**:
|
||||
- **Standard**: Sequential manual reviews → Inconsistent coverage → Missed cross-cutting concerns
|
||||
- **Review-Session-Cycle**: **Parallel automated analysis → Aggregate findings → Deep-dive critical issues** → Comprehensive coverage
|
||||
|
||||
### Value Proposition
|
||||
1. **Comprehensive Coverage**: 7 specialized dimensions analyze all quality aspects simultaneously
|
||||
2. **Intelligent Prioritization**: Automatic identification of critical issues and cross-cutting concerns
|
||||
3. **Actionable Insights**: Deep-dive iterations provide step-by-step remediation plans
|
||||
|
||||
### Orchestrator Boundary (CRITICAL)
|
||||
- **ONLY command** for comprehensive multi-dimensional review
|
||||
- Manages: dimension coordination, aggregation, iteration control, progress tracking
|
||||
- Delegates: Code exploration and analysis to @cli-explore-agent, dimension-specific reviews via Deep Scan mode
|
||||
|
||||
## How It Works
|
||||
|
||||
### Execution Flow (Simplified)
|
||||
|
||||
```
|
||||
Phase 1: Discovery & Initialization
|
||||
└─ Validate session, initialize state, create output structure
|
||||
|
||||
Phase 2: Parallel Reviews (for each dimension)
|
||||
├─ Launch 7 review agents simultaneously
|
||||
├─ Each executes CLI analysis via Gemini/Qwen
|
||||
├─ Generate dimension JSON + markdown reports
|
||||
└─ Update review-progress.json
|
||||
|
||||
Phase 3: Aggregation
|
||||
├─ Load all dimension JSON files
|
||||
├─ Calculate severity distribution (critical/high/medium/low)
|
||||
├─ Identify cross-cutting concerns (files in 3+ dimensions)
|
||||
└─ Decision:
|
||||
├─ Critical findings OR high > 5 OR critical files → Phase 4 (Iterate)
|
||||
└─ Else → Phase 5 (Complete)
|
||||
|
||||
Phase 4: Iterative Deep-Dive (optional)
|
||||
├─ Select critical findings (max 5 per iteration)
|
||||
├─ Launch deep-dive agents for root cause analysis
|
||||
├─ Generate remediation plans with impact assessment
|
||||
├─ Re-assess severity based on analysis
|
||||
└─ Loop until no critical findings OR max iterations
|
||||
|
||||
Phase 5: Completion
|
||||
└─ Finalize review-progress.json
|
||||
```
|
||||
|
||||
### Agent Roles
|
||||
|
||||
| Agent | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Orchestrator** | Phase control, session discovery, state management, aggregation logic, iteration control |
|
||||
| **@cli-explore-agent** (Review) | Execute dimension-specific code analysis via Deep Scan mode, generate findings JSON with dual-source strategy (Bash + Gemini), create structured analysis reports |
|
||||
| **@cli-explore-agent** (Deep-dive) | Focused root cause analysis using dependency mapping, remediation planning with architectural insights, impact assessment, severity re-assessment |
|
||||
|
||||
## Enhanced Features
|
||||
|
||||
### 1. Review Dimensions Configuration
|
||||
|
||||
**7 Specialized Dimensions** with priority-based allocation:
|
||||
|
||||
| Dimension | Template | Priority | Timeout |
|
||||
|-----------|----------|----------|---------|
|
||||
| **Security** | 03-assess-security-risks.txt | 1 (Critical) | 60min |
|
||||
| **Architecture** | 02-review-architecture.txt | 2 (High) | 60min |
|
||||
| **Quality** | 02-review-code-quality.txt | 3 (Medium) | 40min |
|
||||
| **Action-Items** | 02-analyze-code-patterns.txt | 2 (High) | 40min |
|
||||
| **Performance** | 03-analyze-performance.txt | 3 (Medium) | 60min |
|
||||
| **Maintainability** | 02-review-code-quality.txt* | 3 (Medium) | 40min |
|
||||
| **Best-Practices** | 03-review-quality-standards.txt | 3 (Medium) | 40min |
|
||||
|
||||
*Custom focus: "Assess technical debt and maintainability"
|
||||
|
||||
**Category Definitions by Dimension**:
|
||||
|
||||
```javascript
|
||||
const CATEGORIES = {
|
||||
security: ['injection', 'authentication', 'authorization', 'encryption', 'input-validation', 'access-control', 'data-exposure'],
|
||||
architecture: ['coupling', 'cohesion', 'layering', 'dependency', 'pattern-violation', 'scalability', 'separation-of-concerns'],
|
||||
quality: ['code-smell', 'duplication', 'complexity', 'naming', 'error-handling', 'testability', 'readability'],
|
||||
'action-items': ['requirement-coverage', 'acceptance-criteria', 'documentation', 'deployment-readiness', 'missing-functionality'],
|
||||
performance: ['n-plus-one', 'inefficient-query', 'memory-leak', 'blocking-operation', 'caching', 'resource-usage'],
|
||||
maintainability: ['technical-debt', 'magic-number', 'long-method', 'large-class', 'dead-code', 'commented-code'],
|
||||
'best-practices': ['convention-violation', 'anti-pattern', 'deprecated-api', 'missing-validation', 'inconsistent-style']
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Aggregation Logic
|
||||
|
||||
**Cross-Cutting Concern Detection**:
|
||||
1. Files appearing in 3+ dimensions = **Critical Files**
|
||||
2. Same issue pattern across dimensions = **Systemic Issue**
|
||||
3. Severity clustering in specific files = **Hotspots**
|
||||
|
||||
**Deep-Dive Selection Criteria**:
|
||||
- All critical severity findings (priority 1)
|
||||
- Top 3 high-severity findings in critical files (priority 2)
|
||||
- Max 5 findings per iteration (prevent overwhelm)
|
||||
|
||||
### 3. Severity Assessment
|
||||
|
||||
**Severity Levels**:
|
||||
- **Critical**: Security vulnerabilities, data corruption risks, system-wide failures, authentication/authorization bypass
|
||||
- **High**: Feature degradation, performance bottlenecks, architecture violations, significant technical debt
|
||||
- **Medium**: Code smells, minor performance issues, style inconsistencies, maintainability concerns
|
||||
- **Low**: Documentation gaps, minor refactoring opportunities, cosmetic issues
|
||||
|
||||
**Iteration Trigger**:
|
||||
- Critical findings > 0 OR
|
||||
- High findings > 5 OR
|
||||
- Critical files count > 0
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
### Orchestrator
|
||||
|
||||
**Phase 1: Discovery & Initialization**
|
||||
|
||||
**Step 1: Session Discovery**
|
||||
```javascript
|
||||
// If session ID not provided, auto-detect
|
||||
if (!providedSessionId) {
|
||||
// Check for active sessions
|
||||
const activeSessions = Glob('.workflow/active/WFS-*');
|
||||
if (activeSessions.length === 1) {
|
||||
sessionId = activeSessions[0].match(/WFS-[^/]+/)[0];
|
||||
} else if (activeSessions.length > 1) {
|
||||
// List sessions and prompt user
|
||||
error("Multiple active sessions found. Please specify session ID.");
|
||||
} else {
|
||||
error("No active session found. Create session first with /workflow:session:start");
|
||||
}
|
||||
} else {
|
||||
sessionId = providedSessionId;
|
||||
}
|
||||
|
||||
// Validate session exists
|
||||
Bash(`test -d .workflow/active/${sessionId} && echo "EXISTS"`);
|
||||
```
|
||||
|
||||
**Step 2: Session Validation**
|
||||
- Ensure session has implementation artifacts (check `.summaries/` or `.task/` directory)
|
||||
- Extract session creation timestamp from `workflow-session.json`
|
||||
- Use timestamp for git log filtering: `git log --since="${sessionCreatedAt}"`
|
||||
|
||||
**Step 3: Changed Files Detection**
|
||||
```bash
|
||||
# Get files changed since session creation
|
||||
git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u
|
||||
```
|
||||
|
||||
**Step 4: Output Directory Setup**
|
||||
- Output directory: `.workflow/active/${sessionId}/.review/`
|
||||
- Create directory structure:
|
||||
```bash
|
||||
mkdir -p ${sessionDir}/.review/{dimensions,iterations,reports}
|
||||
```
|
||||
|
||||
**Step 5: Initialize Review State**
|
||||
- State initialization: Create `review-state.json` with metadata, dimensions, max_iterations (merged metadata + state)
|
||||
- Progress tracking: Create `review-progress.json` for progress tracking
|
||||
|
||||
**Step 6: TodoWrite Initialization**
|
||||
- Set up progress tracking with hierarchical structure
|
||||
- Mark Phase 1 completed, Phase 2 in_progress
|
||||
|
||||
**Phase 2: Parallel Review Coordination**
|
||||
- Launch 7 @cli-explore-agent instances simultaneously (Deep Scan mode)
|
||||
- Pass dimension-specific context (template, timeout, custom focus)
|
||||
- Monitor completion via review-progress.json updates
|
||||
- TodoWrite updates: Mark dimensions as completed
|
||||
- CLI tool fallback: Gemini → Qwen → Codex (on error/timeout)
|
||||
|
||||
**Phase 3: Aggregation**
|
||||
- Load all dimension JSON files from dimensions/
|
||||
- Calculate severity distribution: Count by critical/high/medium/low
|
||||
- Identify cross-cutting concerns: Files in 3+ dimensions
|
||||
- Select deep-dive findings: Critical + high in critical files (max 5)
|
||||
- Decision logic: Iterate if critical > 0 OR high > 5 OR critical files exist
|
||||
- Update review-state.json with aggregation results
|
||||
|
||||
**Phase 4: Iteration Control**
|
||||
- Check iteration count < max_iterations (default 3)
|
||||
- Launch deep-dive agents for selected findings
|
||||
- Collect remediation plans and re-assessed severities
|
||||
- Update severity distribution based on re-assessments
|
||||
- Record iteration in review-state.json
|
||||
- Loop back to aggregation if still have critical/high findings
|
||||
|
||||
**Phase 5: Completion**
|
||||
- Finalize review-progress.json with completion statistics
|
||||
- Update review-state.json with completion_time and phase=complete
|
||||
- TodoWrite completion: Mark all tasks done
|
||||
|
||||
|
||||
|
||||
### Session File Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/.review/
|
||||
├── review-state.json # Orchestrator state machine (includes metadata)
|
||||
├── review-progress.json # Real-time progress for dashboard
|
||||
├── dimensions/ # Per-dimension results
|
||||
│ ├── security.json
|
||||
│ ├── architecture.json
|
||||
│ ├── quality.json
|
||||
│ ├── action-items.json
|
||||
│ ├── performance.json
|
||||
│ ├── maintainability.json
|
||||
│ └── best-practices.json
|
||||
├── iterations/ # Deep-dive results
|
||||
│ ├── iteration-1-finding-{uuid}.json
|
||||
│ └── iteration-2-finding-{uuid}.json
|
||||
└── reports/ # Human-readable reports
|
||||
├── security-analysis.md
|
||||
├── security-cli-output.txt
|
||||
├── deep-dive-1-{uuid}.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Session Context**:
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .task/
|
||||
├── .summaries/
|
||||
└── .review/ # Review results (this command)
|
||||
└── (structure above)
|
||||
```
|
||||
|
||||
### Review State JSON
|
||||
|
||||
**Purpose**: Unified state machine and metadata (merged from metadata + state)
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-payment-integration",
|
||||
"review_id": "review-20250125-143022",
|
||||
"review_type": "session",
|
||||
"metadata": {
|
||||
"created_at": "2025-01-25T14:30:22Z",
|
||||
"git_changes": {
|
||||
"commit_range": "abc123..def456",
|
||||
"files_changed": 15,
|
||||
"insertions": 342,
|
||||
"deletions": 128
|
||||
},
|
||||
"dimensions": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"max_iterations": 3
|
||||
},
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"dimensions_reviewed": ["security", "architecture", "quality", "action-items", "performance", "maintainability", "best-practices"],
|
||||
"selected_strategy": "comprehensive",
|
||||
"next_action": "execute_parallel_reviews|aggregate_findings|execute_deep_dive|generate_final_report|complete",
|
||||
"severity_distribution": {
|
||||
"critical": 2,
|
||||
"high": 5,
|
||||
"medium": 12,
|
||||
"low": 8
|
||||
},
|
||||
"critical_files": [
|
||||
{
|
||||
"file": "src/payment/processor.ts",
|
||||
"finding_count": 5,
|
||||
"dimensions": ["security", "architecture", "quality"]
|
||||
}
|
||||
],
|
||||
"iterations": [
|
||||
{
|
||||
"iteration": 1,
|
||||
"findings_analyzed": ["uuid-1", "uuid-2"],
|
||||
"findings_resolved": 1,
|
||||
"findings_escalated": 1,
|
||||
"severity_change": {
|
||||
"before": {"critical": 2, "high": 5, "medium": 12, "low": 8},
|
||||
"after": {"critical": 1, "high": 6, "medium": 12, "low": 8}
|
||||
},
|
||||
"timestamp": "2025-01-25T14:30:00Z"
|
||||
}
|
||||
],
|
||||
"completion_criteria": {
|
||||
"target": "no_critical_findings_and_high_under_5",
|
||||
"current_status": "in_progress",
|
||||
"estimated_completion": "2 iterations remaining"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Field Descriptions**:
|
||||
- `phase`: Current execution phase (state machine pointer)
|
||||
- `current_iteration`: Iteration counter (used for max check)
|
||||
- `next_action`: Next step orchestrator should execute
|
||||
- `severity_distribution`: Aggregated counts across all dimensions
|
||||
- `critical_files`: Files appearing in 3+ dimensions with metadata
|
||||
- `iterations[]`: Historical log for trend analysis
|
||||
|
||||
### Review Progress JSON
|
||||
|
||||
**Purpose**: Real-time dashboard updates via polling
|
||||
|
||||
```json
|
||||
{
|
||||
"review_id": "review-20250125-143022",
|
||||
"last_update": "2025-01-25T14:35:10Z",
|
||||
"phase": "parallel|aggregate|iterate|complete",
|
||||
"current_iteration": 1,
|
||||
"progress": {
|
||||
"parallel_review": {
|
||||
"total_dimensions": 7,
|
||||
"completed": 5,
|
||||
"in_progress": 2,
|
||||
"percent_complete": 71
|
||||
},
|
||||
"deep_dive": {
|
||||
"total_findings": 6,
|
||||
"analyzed": 2,
|
||||
"in_progress": 1,
|
||||
"percent_complete": 33
|
||||
}
|
||||
},
|
||||
"agent_status": [
|
||||
{
|
||||
"agent_type": "review-agent",
|
||||
"dimension": "security",
|
||||
"status": "completed",
|
||||
"started_at": "2025-01-25T14:30:00Z",
|
||||
"completed_at": "2025-01-25T15:15:00Z",
|
||||
"duration_ms": 2700000
|
||||
},
|
||||
{
|
||||
"agent_type": "deep-dive-agent",
|
||||
"finding_id": "sec-001-uuid",
|
||||
"status": "in_progress",
|
||||
"started_at": "2025-01-25T14:32:00Z"
|
||||
}
|
||||
],
|
||||
"estimated_completion": "2025-01-25T16:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Agent Output Schemas
|
||||
|
||||
**Agent-produced JSON files follow standardized schemas**:
|
||||
|
||||
1. **Dimension Results** (cli-explore-agent output from parallel reviews)
|
||||
- Schema: `~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json`
|
||||
- Output: `.review-cycle/dimensions/{dimension}.json`
|
||||
- Contains: findings array, summary statistics, cross_references
|
||||
|
||||
2. **Deep-Dive Results** (cli-explore-agent output from iterations)
|
||||
- Schema: `~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json`
|
||||
- Output: `.review-cycle/iterations/iteration-{N}-finding-{uuid}.json`
|
||||
- Contains: root_cause, remediation_plan, impact_assessment, reassessed_severity
|
||||
|
||||
### Agent Invocation Template
|
||||
|
||||
**Review Agent** (parallel execution, 7 instances):
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Execute ${dimension} review analysis via Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Conduct comprehensive ${dimension} code exploration and analysis using Deep Scan mode (Bash + Gemini dual-source strategy) for completed implementation in session ${sessionId}
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Deep Scan mode** for this review:
|
||||
- Phase 1: Bash structural scan for standard patterns (classes, functions, imports)
|
||||
- Phase 2: Gemini semantic analysis for design intent, non-standard patterns, ${dimension}-specific concerns
|
||||
- Phase 3: Synthesis with attribution (bash-discovered vs gemini-discovered findings)
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Read session metadata: ${sessionMetadataPath}
|
||||
2. Read completed task summaries: bash(find ${summariesDir} -name "IMPL-*.md" -type f)
|
||||
3. Get changed files: bash(cd ${workflowDir} && git log --since="${sessionCreatedAt}" --name-only --pretty=format: | sort -u)
|
||||
4. Read review state: ${reviewStateJsonPath}
|
||||
5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-dimension-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints and conventions to validate against)
|
||||
|
||||
## Session Context
|
||||
- Session ID: ${sessionId}
|
||||
- Review Dimension: ${dimension}
|
||||
- Review ID: ${reviewId}
|
||||
- Implementation Phase: Complete (all tests passing)
|
||||
- Output Directory: ${outputDir}
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex (fallback chain)
|
||||
- Template: ~/.ccw/workflows/cli-templates/prompts/analysis/${dimensionTemplate}
|
||||
- Custom Focus: ${customFocus || 'Standard dimension analysis'}
|
||||
- Timeout: ${timeout}ms
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
|
||||
|
||||
1. Dimension Results JSON: ${outputDir}/dimensions/${dimension}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- dimension, review_id, analysis_timestamp (NOT timestamp/analyzed_at)
|
||||
- cli_tool_used (gemini|qwen|codex), model, analysis_duration_ms
|
||||
- summary (FLAT structure), findings, cross_references
|
||||
|
||||
Summary MUST be FLAT (NOT nested by_severity):
|
||||
\`{ "total_findings": N, "critical": N, "high": N, "medium": N, "low": N, "files_analyzed": N, "lines_reviewed": N }\`
|
||||
|
||||
Finding required fields:
|
||||
- id: format \`{dim}-{seq}-{uuid8}\` e.g., \`sec-001-a1b2c3d4\` (lowercase)
|
||||
- severity: lowercase only (critical|high|medium|low)
|
||||
- snippet (NOT code_snippet), impact (NOT exploit_scenario)
|
||||
- metadata, iteration (0), status (pending_remediation), cross_references
|
||||
|
||||
2. Analysis Report: ${outputDir}/reports/${dimension}-analysis.md
|
||||
- Human-readable summary with recommendations
|
||||
- Grouped by severity: critical → high → medium → low
|
||||
- Include file:line references for all findings
|
||||
|
||||
3. CLI Output Log: ${outputDir}/reports/${dimension}-cli-output.txt
|
||||
- Raw CLI tool output for debugging
|
||||
- Include full analysis text
|
||||
|
||||
## Dimension-Specific Guidance
|
||||
${getDimensionGuidance(dimension)}
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat review-dimension-results-schema.json
|
||||
- [ ] All changed files analyzed for ${dimension} concerns
|
||||
- [ ] All findings include file:line references with code snippets
|
||||
- [ ] Severity assessment follows established criteria (see reference)
|
||||
- [ ] Recommendations are actionable with code examples
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] Report is comprehensive and well-organized
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Deep-Dive Agent** (iteration execution):
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Deep-dive analysis for critical finding: ${findingTitle} via Dependency Map + Deep Scan`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Perform focused root cause analysis using Dependency Map mode (for impact analysis) + Deep Scan mode (for semantic understanding) to generate comprehensive remediation plan for critical ${dimension} issue
|
||||
|
||||
## Analysis Mode Selection
|
||||
Use **Dependency Map mode** first to understand dependencies:
|
||||
- Build dependency graph around ${file} to identify affected components
|
||||
- Detect circular dependencies or tight coupling related to this finding
|
||||
- Calculate change risk scores for remediation impact
|
||||
|
||||
Then apply **Deep Scan mode** for semantic analysis:
|
||||
- Understand design intent and architectural context
|
||||
- Identify non-standard patterns or implicit dependencies
|
||||
- Extract remediation insights from code structure
|
||||
|
||||
## Finding Context
|
||||
- Finding ID: ${findingId}
|
||||
- Original Dimension: ${dimension}
|
||||
- Title: ${findingTitle}
|
||||
- File: ${file}:${line}
|
||||
- Severity: ${severity}
|
||||
- Category: ${category}
|
||||
- Original Description: ${description}
|
||||
- Iteration: ${iteration}
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Read original finding: ${dimensionJsonPath}
|
||||
2. Read affected file: ${file}
|
||||
3. Identify related code: bash(grep -r "import.*${basename(file)}" ${workflowDir}/src --include="*.ts")
|
||||
4. Read test files: bash(find ${workflowDir}/tests -name "*${basename(file, '.ts')}*" -type f)
|
||||
5. Execute: cat ~/.ccw/workflows/cli-templates/schemas/review-deep-dive-results-schema.json (get output schema reference)
|
||||
6. Read: .workflow/project-tech.json (technology stack and architecture context)
|
||||
7. Read: .workflow/project-guidelines.json (user-defined constraints for remediation compliance)
|
||||
|
||||
## CLI Configuration
|
||||
- Tool Priority: gemini → qwen → codex
|
||||
- Template: ~/.ccw/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
|
||||
- Timeout: 2400000ms (40 minutes)
|
||||
- Mode: analysis (READ-ONLY)
|
||||
|
||||
## Expected Deliverables
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 5, follow schema exactly
|
||||
|
||||
1. Deep-Dive Results JSON: ${outputDir}/iterations/iteration-${iteration}-finding-${findingId}.json
|
||||
|
||||
**⚠️ CRITICAL JSON STRUCTURE REQUIREMENTS**:
|
||||
|
||||
Root structure MUST be array: \`[{ ... }]\` NOT \`{ ... }\`
|
||||
|
||||
Required top-level fields:
|
||||
- finding_id, dimension, iteration, analysis_timestamp
|
||||
- cli_tool_used, model, analysis_duration_ms
|
||||
- original_finding, root_cause, remediation_plan
|
||||
- impact_assessment, reassessed_severity, confidence_score, cross_references
|
||||
|
||||
All nested objects must follow schema exactly - read schema for field names
|
||||
|
||||
2. Analysis Report: ${outputDir}/reports/deep-dive-${iteration}-${findingId}.md
|
||||
- Detailed root cause analysis
|
||||
- Step-by-step remediation plan
|
||||
- Impact assessment and rollback strategy
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat review-deep-dive-results-schema.json
|
||||
- [ ] Root cause clearly identified with supporting evidence
|
||||
- [ ] Remediation plan is step-by-step actionable with exact file:line references
|
||||
- [ ] Each step includes specific commands and validation tests
|
||||
- [ ] Impact fully assessed (files, tests, breaking changes, dependencies)
|
||||
- [ ] Severity re-evaluation justified with evidence
|
||||
- [ ] Confidence score accurately reflects certainty of analysis
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] References include project-specific and external documentation
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Dimension Guidance Reference
|
||||
|
||||
```javascript
|
||||
function getDimensionGuidance(dimension) {
|
||||
const guidance = {
|
||||
security: `
|
||||
Focus Areas:
|
||||
- Input validation and sanitization
|
||||
- Authentication and authorization mechanisms
|
||||
- Data encryption (at-rest and in-transit)
|
||||
- SQL/NoSQL injection vulnerabilities
|
||||
- XSS, CSRF, and other web vulnerabilities
|
||||
- Sensitive data exposure
|
||||
- Access control and privilege escalation
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Authentication bypass, SQL injection, RCE, sensitive data exposure
|
||||
- High: Missing authorization checks, weak encryption, exposed secrets
|
||||
- Medium: Missing input validation, insecure defaults, weak password policies
|
||||
- Low: Security headers missing, verbose error messages, outdated dependencies
|
||||
`,
|
||||
architecture: `
|
||||
Focus Areas:
|
||||
- Layering and separation of concerns
|
||||
- Coupling and cohesion
|
||||
- Design pattern adherence
|
||||
- Dependency management
|
||||
- Scalability and extensibility
|
||||
- Module boundaries
|
||||
- API design consistency
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Circular dependencies, god objects, tight coupling across layers
|
||||
- High: Violated architectural principles, scalability bottlenecks
|
||||
- Medium: Missing abstractions, inconsistent patterns, suboptimal design
|
||||
- Low: Minor coupling issues, documentation gaps, naming inconsistencies
|
||||
`,
|
||||
quality: `
|
||||
Focus Areas:
|
||||
- Code duplication
|
||||
- Complexity (cyclomatic, cognitive)
|
||||
- Naming conventions
|
||||
- Error handling patterns
|
||||
- Code readability
|
||||
- Comment quality
|
||||
- Dead code
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Severe complexity (CC > 20), massive duplication (>50 lines)
|
||||
- High: High complexity (CC > 10), significant duplication, poor error handling
|
||||
- Medium: Moderate complexity (CC > 5), naming issues, code smells
|
||||
- Low: Minor duplication, documentation gaps, cosmetic issues
|
||||
`,
|
||||
'action-items': `
|
||||
Focus Areas:
|
||||
- Requirements coverage verification
|
||||
- Acceptance criteria met
|
||||
- Documentation completeness
|
||||
- Deployment readiness
|
||||
- Missing functionality
|
||||
- Test coverage gaps
|
||||
- Configuration management
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Core requirements not met, deployment blockers
|
||||
- High: Significant functionality missing, acceptance criteria not met
|
||||
- Medium: Minor requirements gaps, documentation incomplete
|
||||
- Low: Nice-to-have features missing, minor documentation gaps
|
||||
`,
|
||||
performance: `
|
||||
Focus Areas:
|
||||
- N+1 query problems
|
||||
- Inefficient algorithms (O(n²) where O(n log n) possible)
|
||||
- Memory leaks
|
||||
- Blocking operations on main thread
|
||||
- Missing caching opportunities
|
||||
- Resource usage (CPU, memory, network)
|
||||
- Database query optimization
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Memory leaks, O(n²) in hot path, blocking main thread
|
||||
- High: N+1 queries, missing indexes, inefficient algorithms
|
||||
- Medium: Suboptimal caching, unnecessary computations, lazy loading issues
|
||||
- Low: Minor optimization opportunities, redundant operations
|
||||
`,
|
||||
maintainability: `
|
||||
Focus Areas:
|
||||
- Technical debt indicators
|
||||
- Magic numbers and hardcoded values
|
||||
- Long methods (>50 lines)
|
||||
- Large classes (>500 lines)
|
||||
- Dead code and commented code
|
||||
- Code documentation
|
||||
- Test coverage
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Massive methods (>200 lines), severe technical debt blocking changes
|
||||
- High: Large methods (>100 lines), significant dead code, undocumented complex logic
|
||||
- Medium: Magic numbers, moderate technical debt, missing tests
|
||||
- Low: Minor refactoring opportunities, cosmetic improvements
|
||||
`,
|
||||
'best-practices': `
|
||||
Focus Areas:
|
||||
- Framework conventions adherence
|
||||
- Language idioms
|
||||
- Anti-patterns
|
||||
- Deprecated API usage
|
||||
- Coding standards compliance
|
||||
- Error handling patterns
|
||||
- Logging and monitoring
|
||||
|
||||
Severity Criteria:
|
||||
- Critical: Severe anti-patterns, deprecated APIs with security risks
|
||||
- High: Major convention violations, poor error handling, missing logging
|
||||
- Medium: Minor anti-patterns, style inconsistencies, suboptimal patterns
|
||||
- Low: Cosmetic style issues, minor convention deviations
|
||||
`
|
||||
};
|
||||
|
||||
return guidance[dimension] || 'Standard code review analysis';
|
||||
}
|
||||
```
|
||||
|
||||
### Completion Conditions
|
||||
|
||||
**Full Success**:
|
||||
- All dimensions reviewed
|
||||
- Critical findings = 0
|
||||
- High findings ≤ 5
|
||||
- Action: Generate final report, mark phase=complete
|
||||
|
||||
**Partial Success**:
|
||||
- All dimensions reviewed
|
||||
- Max iterations reached
|
||||
- Still have critical/high findings
|
||||
- Action: Generate report with warnings, recommend follow-up
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase-Level Error Matrix**:
|
||||
|
||||
| Phase | Error | Blocking? | Action |
|
||||
|-------|-------|-----------|--------|
|
||||
| Phase 1 | Session not found | Yes | Error and exit |
|
||||
| Phase 1 | No completed tasks | Yes | Error and exit |
|
||||
| Phase 1 | No changed files | Yes | Error and exit |
|
||||
| Phase 2 | Single dimension fails | No | Log warning, continue other dimensions |
|
||||
| Phase 2 | All dimensions fail | Yes | Error and exit |
|
||||
| Phase 3 | Missing dimension JSON | No | Skip in aggregation, log warning |
|
||||
| Phase 4 | Deep-dive agent fails | No | Skip finding, continue others |
|
||||
| Phase 4 | Max iterations reached | No | Generate partial report |
|
||||
|
||||
**CLI Fallback Chain**: Gemini → Qwen → Codex → degraded mode
|
||||
|
||||
**Fallback Triggers**:
|
||||
1. HTTP 429, 5xx errors, connection timeout
|
||||
2. Invalid JSON output (parse error, missing required fields)
|
||||
3. Low confidence score < 0.4
|
||||
4. Analysis too brief (< 100 words in report)
|
||||
|
||||
**Fallback Behavior**:
|
||||
- On trigger: Retry with next tool in chain
|
||||
- After Codex fails: Enter degraded mode (skip analysis, log error)
|
||||
- Degraded mode: Continue workflow with available results
|
||||
|
||||
### TodoWrite Structure
|
||||
|
||||
```javascript
|
||||
TodoWrite({
|
||||
todos: [
|
||||
{ content: "Phase 1: Discovery & Initialization", status: "completed", activeForm: "Initializing" },
|
||||
{ content: "Phase 2: Parallel Reviews (7 dimensions)", status: "in_progress", activeForm: "Reviewing" },
|
||||
{ content: " → Security review", status: "in_progress", activeForm: "Analyzing security" },
|
||||
// ... other dimensions as sub-items
|
||||
{ content: "Phase 3: Aggregation", status: "pending", activeForm: "Aggregating" },
|
||||
{ content: "Phase 4: Deep-dive", status: "pending", activeForm: "Deep-diving" },
|
||||
{ content: "Phase 5: Completion", status: "pending", activeForm: "Completing" }
|
||||
]
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Default Settings Work**: 7 dimensions + 3 iterations sufficient for most cases
|
||||
2. **Parallel Execution**: ~60 minutes for full initial review (7 dimensions)
|
||||
3. **Trust Aggregation Logic**: Auto-selection based on proven heuristics
|
||||
4. **Monitor Logs**: Check reports/ directory for CLI analysis insights
|
||||
|
||||
## Related Commands
|
||||
|
||||
### View Review Progress
|
||||
Use `ccw view` to open the review dashboard in browser:
|
||||
|
||||
```bash
|
||||
ccw view
|
||||
```
|
||||
|
||||
### Automated Fix Workflow
|
||||
After completing a review, use the generated findings JSON for automated fixing:
|
||||
|
||||
```bash
|
||||
# Step 1: Complete review (this command)
|
||||
/workflow:review-session-cycle
|
||||
|
||||
# Step 2: Run automated fixes using dimension findings
|
||||
/workflow:review-cycle-fix .workflow/active/WFS-{session-id}/.review/
|
||||
```
|
||||
|
||||
See `/workflow:review-cycle-fix` for automated fixing with smart grouping, parallel execution, and test verification.
|
||||
|
||||
@@ -1,391 +0,0 @@
|
||||
---
|
||||
name: code-validation-gate
|
||||
description: Validate AI-generated code for common errors (imports, variables, types) before test execution
|
||||
argument-hint: "--session WFS-test-session-id [--fix] [--strict]"
|
||||
examples:
|
||||
- /workflow:tools:code-validation-gate --session WFS-test-auth
|
||||
- /workflow:tools:code-validation-gate --session WFS-test-auth --fix
|
||||
- /workflow:tools:code-validation-gate --session WFS-test-auth --strict
|
||||
---
|
||||
|
||||
# Code Validation Gate Command
|
||||
|
||||
## Overview
|
||||
|
||||
Pre-test validation gate that checks AI-generated code for common errors before test execution. This prevents wasted test cycles on code with fundamental issues like import errors, variable conflicts, and type mismatches.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Fail Fast**: Catch fundamental errors before expensive test execution
|
||||
- **AI-Aware**: Specifically targets common AI code generation mistakes
|
||||
- **Auto-Remediation**: Attempt safe fixes before failing
|
||||
- **Clear Feedback**: Provide actionable fix suggestions for manual intervention
|
||||
|
||||
## Target Error Categories
|
||||
|
||||
### L0.1: Compilation Errors
|
||||
- TypeScript compilation failures
|
||||
- Syntax errors
|
||||
- Module resolution failures
|
||||
|
||||
### L0.2: Import Errors
|
||||
- Unresolved module imports (hallucinated packages)
|
||||
- Circular dependencies
|
||||
- Duplicate imports
|
||||
- Unused imports
|
||||
|
||||
### L0.3: Variable Errors
|
||||
- Variable redeclaration
|
||||
- Scope conflicts (shadowing)
|
||||
- Undefined variable usage
|
||||
- Unused variables
|
||||
|
||||
### L0.4: Type Errors (TypeScript)
|
||||
- Type mismatches
|
||||
- Missing type definitions
|
||||
- Excessive `any` usage
|
||||
- Implicit `any` types
|
||||
|
||||
### L0.5: AI-Specific Patterns
|
||||
- Placeholder code (`// TODO: implement`)
|
||||
- Hallucinated package imports
|
||||
- Mock code in production files
|
||||
- Inconsistent naming patterns
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
├─ Parse flags: --session (required), --fix, --strict
|
||||
└─ Load test-quality-config.json
|
||||
|
||||
Phase 1: Context Loading
|
||||
├─ Load session metadata
|
||||
├─ Identify target files (from IMPL-001 output or context-package)
|
||||
└─ Detect project configuration (tsconfig, eslint, etc.)
|
||||
|
||||
Phase 2: Validation Execution
|
||||
├─ L0.1: Run TypeScript compilation check
|
||||
├─ L0.2: Run import validation
|
||||
├─ L0.3: Run variable validation
|
||||
├─ L0.4: Run type validation
|
||||
└─ L0.5: Run AI-specific checks
|
||||
|
||||
Phase 3: Result Analysis
|
||||
├─ Aggregate all findings by severity
|
||||
├─ Calculate pass/fail status
|
||||
└─ Generate fix suggestions
|
||||
|
||||
Phase 4: Auto-Fix (if --fix enabled)
|
||||
├─ Apply safe auto-fixes (imports, formatting)
|
||||
├─ Re-run validation
|
||||
└─ Report remaining issues
|
||||
|
||||
Phase 5: Gate Decision
|
||||
├─ PASS: Proceed to IMPL-001.5
|
||||
├─ SOFT_FAIL: Auto-fix applied, needs re-validation
|
||||
└─ HARD_FAIL: Block with detailed report
|
||||
```
|
||||
|
||||
## Execution Lifecycle
|
||||
|
||||
### Phase 1: Context Loading
|
||||
|
||||
**Load session and identify validation targets.**
|
||||
|
||||
```javascript
|
||||
// Load session metadata
|
||||
Read(".workflow/active/{session_id}/workflow-session.json")
|
||||
|
||||
// Load context package for target files
|
||||
Read(".workflow/active/{session_id}/.process/context-package.json")
|
||||
// OR
|
||||
Read(".workflow/active/{session_id}/.process/test-context-package.json")
|
||||
|
||||
// Identify files to validate:
|
||||
// 1. Source files from context.implementation_files
|
||||
// 2. Test files from IMPL-001 output (if exists)
|
||||
// 3. All modified files since session start
|
||||
```
|
||||
|
||||
**Target File Discovery**:
|
||||
- Source files: `context.focus_paths` from context-package
|
||||
- Generated tests: `.workflow/active/{session_id}/.task/IMPL-001-output/`
|
||||
- All TypeScript/JavaScript in target directories
|
||||
|
||||
### Phase 2: Validation Execution
|
||||
|
||||
**Execute validation checks in order of dependency.**
|
||||
|
||||
#### L0.1: TypeScript Compilation
|
||||
|
||||
```bash
|
||||
# Primary check - catches most fundamental errors
|
||||
npx tsc --noEmit --skipLibCheck --project tsconfig.json 2>&1
|
||||
|
||||
# Parse output for errors
|
||||
# Critical: Any compilation error blocks further validation
|
||||
```
|
||||
|
||||
**Error Patterns**:
|
||||
```
|
||||
error TS2307: Cannot find module 'xxx'
|
||||
error TS2451: Cannot redeclare block-scoped variable 'xxx'
|
||||
error TS2322: Type 'xxx' is not assignable to type 'yyy'
|
||||
```
|
||||
|
||||
#### L0.2: Import Validation
|
||||
|
||||
```bash
|
||||
# Check for circular dependencies
|
||||
npx madge --circular --extensions ts,tsx,js,jsx {target_dirs}
|
||||
|
||||
# ESLint import rules
|
||||
npx eslint --rule 'import/no-duplicates: error' --rule 'import/no-unresolved: error' {files}
|
||||
```
|
||||
|
||||
**Hallucinated Package Check**:
|
||||
```javascript
|
||||
// Extract all imports from files
|
||||
// Verify each package exists in package.json or node_modules
|
||||
// Flag any unresolvable imports as "hallucinated"
|
||||
```
|
||||
|
||||
#### L0.3: Variable Validation
|
||||
|
||||
```bash
|
||||
# ESLint variable rules
|
||||
npx eslint --rule 'no-shadow: error' --rule 'no-undef: error' --rule 'no-redeclare: error' {files}
|
||||
```
|
||||
|
||||
#### L0.4: Type Validation
|
||||
|
||||
```bash
|
||||
# TypeScript strict checks
|
||||
npx tsc --noEmit --strict {files}
|
||||
|
||||
# Check for any abuse
|
||||
npx eslint --rule '@typescript-eslint/no-explicit-any: warn' {files}
|
||||
```
|
||||
|
||||
#### L0.5: AI-Specific Checks
|
||||
|
||||
```bash
|
||||
# Check for placeholder code
|
||||
grep -rn "// TODO: implement\|// Add your code here\|throw new Error.*Not implemented" {files}
|
||||
|
||||
# Check for mock code in production files
|
||||
grep -rn "jest\.mock\|sinon\.\|vi\.mock" {source_files_only}
|
||||
```
|
||||
|
||||
### Phase 3: Result Analysis
|
||||
|
||||
**Aggregate and categorize findings.**
|
||||
|
||||
```javascript
|
||||
const findings = {
|
||||
critical: [], // Blocks all progress
|
||||
error: [], // Blocks with threshold
|
||||
warning: [] // Advisory only
|
||||
};
|
||||
|
||||
// Apply thresholds from config
|
||||
const config = loadConfig("test-quality-config.json");
|
||||
const thresholds = config.code_validation.severity_thresholds;
|
||||
|
||||
// Gate decision
|
||||
if (findings.critical.length > thresholds.critical) {
|
||||
decision = "HARD_FAIL";
|
||||
} else if (findings.error.length > thresholds.error) {
|
||||
decision = "SOFT_FAIL"; // Try auto-fix
|
||||
} else {
|
||||
decision = "PASS";
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Auto-Fix (Optional)
|
||||
|
||||
**Apply safe automatic fixes when --fix flag provided.**
|
||||
|
||||
```bash
|
||||
# Safe fixes only
|
||||
npx eslint --fix --rule 'import/no-duplicates: error' --rule 'unused-imports/no-unused-imports: error' {files}
|
||||
|
||||
# Re-run validation after fixes
|
||||
# Report what was fixed vs what remains
|
||||
```
|
||||
|
||||
**Safe Fix Categories**:
|
||||
- Remove unused imports
|
||||
- Remove duplicate imports
|
||||
- Fix import ordering
|
||||
- Remove unused variables (with caution)
|
||||
- Formatting fixes
|
||||
|
||||
**Unsafe (Manual Only)**:
|
||||
- Missing imports (need to determine correct package)
|
||||
- Type errors (need to understand intent)
|
||||
- Variable shadowing (need to understand scope intent)
|
||||
|
||||
### Phase 5: Gate Decision
|
||||
|
||||
**Determine next action based on results.**
|
||||
|
||||
| Decision | Condition | Action |
|
||||
|----------|-----------|--------|
|
||||
| **PASS** | critical=0, error<=3, warning<=10 | Proceed to IMPL-001.5 |
|
||||
| **SOFT_FAIL** | critical=0, error>3 OR fixable issues | Auto-fix and retry (max 2) |
|
||||
| **HARD_FAIL** | critical>0 OR max retries exceeded | Block with report |
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
### Validation Report
|
||||
|
||||
**File**: `.workflow/active/{session_id}/.process/code-validation-report.md`
|
||||
|
||||
```markdown
|
||||
# Code Validation Report
|
||||
|
||||
**Session**: {session_id}
|
||||
**Timestamp**: {timestamp}
|
||||
**Status**: PASS | SOFT_FAIL | HARD_FAIL
|
||||
|
||||
## Summary
|
||||
- Files Validated: {count}
|
||||
- Critical Issues: {count}
|
||||
- Errors: {count}
|
||||
- Warnings: {count}
|
||||
|
||||
## Critical Issues (Must Fix)
|
||||
### Import Errors
|
||||
- `src/auth/service.ts:5` - Cannot find module 'non-existent-package'
|
||||
- **Suggestion**: Check if package exists, may be hallucinated by AI
|
||||
|
||||
### Variable Conflicts
|
||||
- `src/utils/helper.ts:12` - Cannot redeclare block-scoped variable 'config'
|
||||
- **Suggestion**: Rename one of the variables or merge declarations
|
||||
|
||||
## Errors (Should Fix)
|
||||
...
|
||||
|
||||
## Warnings (Consider Fixing)
|
||||
...
|
||||
|
||||
## Auto-Fix Applied
|
||||
- Removed 3 unused imports in `src/auth/service.ts`
|
||||
- Fixed import ordering in `src/utils/index.ts`
|
||||
|
||||
## Remaining Issues Requiring Manual Fix
|
||||
...
|
||||
|
||||
## Next Steps
|
||||
- [ ] Fix critical issues before proceeding
|
||||
- [ ] Review error suggestions
|
||||
- [ ] Re-run validation: `/workflow:tools:code-validation-gate --session {session_id}`
|
||||
```
|
||||
|
||||
### JSON Report (Machine-Readable)
|
||||
|
||||
**File**: `.workflow/active/{session_id}/.process/code-validation-report.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-test-xxx",
|
||||
"timestamp": "2025-01-30T10:00:00Z",
|
||||
"status": "HARD_FAIL",
|
||||
"summary": {
|
||||
"files_validated": 15,
|
||||
"critical": 2,
|
||||
"error": 5,
|
||||
"warning": 8
|
||||
},
|
||||
"findings": {
|
||||
"critical": [
|
||||
{
|
||||
"category": "import",
|
||||
"file": "src/auth/service.ts",
|
||||
"line": 5,
|
||||
"message": "Cannot find module 'non-existent-package'",
|
||||
"suggestion": "Check if package exists in package.json",
|
||||
"auto_fixable": false
|
||||
}
|
||||
],
|
||||
"error": [...],
|
||||
"warning": [...]
|
||||
},
|
||||
"auto_fixes_applied": [...],
|
||||
"gate_decision": "HARD_FAIL",
|
||||
"retry_count": 0,
|
||||
"max_retries": 2
|
||||
}
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--session` | Test session ID (required) | - |
|
||||
| `--fix` | Enable auto-fix for safe issues | false |
|
||||
| `--strict` | Use strict thresholds (0 errors allowed) | false |
|
||||
| `--files` | Specific files to validate (comma-separated) | All target files |
|
||||
| `--skip-types` | Skip TypeScript type checks | false |
|
||||
|
||||
## Integration
|
||||
|
||||
### Command Chain
|
||||
|
||||
- **Called By**: `/workflow:test-fix-gen` (after IMPL-001)
|
||||
- **Requires**: IMPL-001 output OR context-package.json
|
||||
- **Followed By**: IMPL-001.5 (Test Quality Gate) on PASS
|
||||
|
||||
### Task JSON Integration
|
||||
|
||||
When used in test-fix workflow, generates task:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001.3-validation",
|
||||
"meta": {
|
||||
"type": "code-validation",
|
||||
"agent": "@test-fix-agent"
|
||||
},
|
||||
"context": {
|
||||
"depends_on": ["IMPL-001"],
|
||||
"requirements": "Validate generated code for AI common errors"
|
||||
},
|
||||
"flow_control": {
|
||||
"validation_config": "~/.ccw/workflows/test-quality-config.json",
|
||||
"max_retries": 2,
|
||||
"auto_fix_enabled": true
|
||||
},
|
||||
"acceptance_criteria": [
|
||||
"Zero critical issues",
|
||||
"Maximum 3 error issues",
|
||||
"All imports resolvable",
|
||||
"No variable redeclarations"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| tsconfig.json not found | Use default compiler options |
|
||||
| ESLint not installed | Skip ESLint checks, use tsc only |
|
||||
| madge not installed | Skip circular dependency check |
|
||||
| No files to validate | Return PASS (nothing to check) |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Run Early**: Execute validation immediately after code generation
|
||||
2. **Use --fix First**: Let auto-fix resolve trivial issues
|
||||
3. **Review Suggestions**: AI fix suggestions may need human judgment
|
||||
4. **Don't Skip Critical**: Never proceed with critical errors
|
||||
5. **Track Patterns**: Common failures indicate prompt improvement opportunities
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:test-fix-gen` - Parent workflow that invokes this command
|
||||
- `/workflow:tools:test-quality-gate` - Next phase (IMPL-001.5) for test quality
|
||||
- `/workflow:test-cycle-execute` - Execute tests after validation passes
|
||||
@@ -1,604 +0,0 @@
|
||||
---
|
||||
name: conflict-resolution
|
||||
description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
|
||||
argument-hint: "[-y|--yes] --session WFS-session-id --context path/to/context-package.json"
|
||||
examples:
|
||||
- /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/active/WFS-auth/.process/context-package.json
|
||||
- /workflow:tools:conflict-resolution -y --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-select recommended strategy for each conflict, skip clarification questions.
|
||||
|
||||
# Conflict Resolution Command
|
||||
|
||||
## Purpose
|
||||
Analyzes conflicts between implementation plans and existing codebase, **including module scenario uniqueness detection**, generating multiple resolution strategies with **iterative clarification until boundaries are clear**.
|
||||
|
||||
**Scope**: Detection and strategy generation only - NO code modification or task creation.
|
||||
|
||||
**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
| Responsibility | Description |
|
||||
|---------------|-------------|
|
||||
| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
|
||||
| **Scenario Uniqueness** | Search and compare new modules with existing modules for functional overlaps |
|
||||
| **Generate Strategies** | Provide 2-4 resolution options per conflict |
|
||||
| **Iterative Clarification** | Ask unlimited questions until scenario boundaries are clear and unique |
|
||||
| **Agent Re-analysis** | Dynamically update strategies based on user clarifications |
|
||||
| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
|
||||
| **User Decision** | Present options ONE BY ONE, never auto-apply |
|
||||
| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
|
||||
| **Structured Data** | JSON output for programmatic processing, NO file generation |
|
||||
|
||||
## Conflict Categories
|
||||
|
||||
### 1. Architecture Conflicts
|
||||
- Incompatible design patterns
|
||||
- Module structure changes
|
||||
- Pattern migration requirements
|
||||
|
||||
### 2. API Conflicts
|
||||
- Breaking contract changes
|
||||
- Signature modifications
|
||||
- Public interface impacts
|
||||
|
||||
### 3. Data Model Conflicts
|
||||
- Schema modifications
|
||||
- Type breaking changes
|
||||
- Data migration needs
|
||||
|
||||
### 4. Dependency Conflicts
|
||||
- Version incompatibilities
|
||||
- Setup conflicts
|
||||
- Breaking updates
|
||||
|
||||
### 5. Module Scenario Overlap
|
||||
- Functional overlap between new and existing modules
|
||||
- Scenario boundary ambiguity
|
||||
- Duplicate responsibility detection
|
||||
- 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
|
||||
```
|
||||
1. Verify session directory exists
|
||||
2. Load context-package.json
|
||||
3. Check conflict_risk (skip if none/low)
|
||||
4. Prepare agent task prompt
|
||||
```
|
||||
|
||||
### Phase 2: CLI-Powered Analysis
|
||||
|
||||
**Agent Delegation**:
|
||||
```javascript
|
||||
Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
|
||||
## Context
|
||||
- Session: {session_id}
|
||||
- Risk: {conflict_risk}
|
||||
- Files: {existing_files_list}
|
||||
|
||||
## Exploration Context (from context-package.exploration_results)
|
||||
- Exploration Count: ${contextPackage.exploration_results?.exploration_count || 0}
|
||||
- Angles Analyzed: ${JSON.stringify(contextPackage.exploration_results?.angles || [])}
|
||||
- Pre-identified Conflict Indicators: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.conflict_indicators || [])}
|
||||
- Critical Files: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.critical_files?.map(f => f.path) || [])}
|
||||
- All Patterns: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_patterns || [])}
|
||||
- All Integration Points: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_integration_points || [])}
|
||||
|
||||
## Analysis Steps
|
||||
|
||||
### 0. Load Output Schema (MANDATORY)
|
||||
Execute: cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json
|
||||
|
||||
### 1. Load Context
|
||||
- Read existing files from conflict_detection.existing_files
|
||||
- Load plan from .workflow/active/{session_id}/.process/context-package.json
|
||||
- Load exploration_results and use aggregated_insights for enhanced analysis
|
||||
- Extract role analyses and requirements
|
||||
|
||||
### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness)
|
||||
|
||||
Primary (Gemini):
|
||||
ccw cli -p "
|
||||
PURPOSE: Detect conflicts between plan and codebase, using exploration insights
|
||||
TASK:
|
||||
• **Review pre-identified conflict_indicators from exploration results**
|
||||
• Compare architectures (use exploration key_patterns)
|
||||
• Identify breaking API changes
|
||||
• Detect data model incompatibilities
|
||||
• Assess dependency conflicts
|
||||
• **Analyze module scenario uniqueness**
|
||||
- Use exploration integration_points for precise locations
|
||||
- Cross-validate with exploration critical_files
|
||||
- Generate clarification questions for boundary definition
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/{session_id}/**/*
|
||||
EXPECTED: Conflict list with severity ratings, including:
|
||||
- Validation of exploration conflict_indicators
|
||||
- ModuleOverlap conflicts with overlap_analysis
|
||||
- Targeted clarification questions
|
||||
CONSTRAINTS: Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY
|
||||
" --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root}
|
||||
|
||||
Fallback: Qwen (same prompt) → Claude (manual analysis)
|
||||
|
||||
### 3. Generate Strategies (2-4 per conflict)
|
||||
|
||||
Template per conflict:
|
||||
- Severity: Critical/High/Medium
|
||||
- Category: Architecture/API/Data/Dependency/ModuleOverlap
|
||||
- Affected files + impact
|
||||
- **For ModuleOverlap**: Include overlap_analysis with existing modules and scenarios
|
||||
- Options with pros/cons, effort, risk
|
||||
- **For ModuleOverlap strategies**: Add clarification_needed questions for boundary definition
|
||||
- Recommended strategy + rationale
|
||||
|
||||
### 4. Return Structured Conflict Data
|
||||
|
||||
⚠️ Output to conflict-resolution.json (generated in Phase 4)
|
||||
|
||||
**Schema Reference**: Execute \`cat ~/.ccw/workflows/cli-templates/schemas/conflict-resolution-schema.json\` to get full schema
|
||||
|
||||
Return JSON following the schema above. Key requirements:
|
||||
- Minimum 2 strategies per conflict, max 4
|
||||
- All text in Chinese for user-facing fields (brief, name, pros, cons, modification_suggestions)
|
||||
- modifications.old_content: 20-100 chars for unique Edit tool matching
|
||||
- modifications.new_content: preserves markdown formatting
|
||||
- modification_suggestions: 2-5 actionable suggestions for custom handling
|
||||
|
||||
### 5. Planning Notes Record (REQUIRED)
|
||||
After analysis complete, append a brief execution record to planning-notes.md:
|
||||
|
||||
**File**: .workflow/active/{session_id}/planning-notes.md
|
||||
**Location**: Under "## Conflict Decisions (Phase 3)" section
|
||||
**Format**:
|
||||
\`\`\`
|
||||
### [Conflict-Resolution Agent] YYYY-MM-DD
|
||||
- **Note**: [智能补充：简短总结冲突类型、解决策略、关键决策等]
|
||||
\`\`\`
|
||||
`)
|
||||
```
|
||||
|
||||
### Phase 3: User Interaction Loop
|
||||
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
FOR each conflict:
|
||||
round = 0, clarified = false, userClarifications = []
|
||||
|
||||
WHILE (!clarified && round++ < 10):
|
||||
// 1. Display conflict info (text output for context)
|
||||
displayConflictSummary(conflict) // id, brief, severity, overlap_analysis if ModuleOverlap
|
||||
|
||||
// 2. Strategy selection
|
||||
if (autoYes) {
|
||||
console.log(`[--yes] Auto-selecting recommended strategy`)
|
||||
selectedStrategy = conflict.strategies[conflict.recommended || 0]
|
||||
clarified = true // Skip clarification loop
|
||||
} else {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: formatStrategiesForDisplay(conflict.strategies),
|
||||
header: "策略选择",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
...conflict.strategies.map((s, i) => ({
|
||||
label: `${s.name}${i === conflict.recommended ? ' (推荐)' : ''}`,
|
||||
description: `${s.complexity}复杂度 | ${s.risk}风险${s.clarification_needed?.length ? ' | ⚠️需澄清' : ''}`
|
||||
})),
|
||||
{ label: "自定义修改", description: `建议: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
// 3. Handle selection
|
||||
if (userChoice === "自定义修改") {
|
||||
customConflicts.push({ id, brief, category, suggestions, overlap_analysis })
|
||||
break
|
||||
}
|
||||
|
||||
selectedStrategy = findStrategyByName(userChoice)
|
||||
}
|
||||
|
||||
// 4. Clarification (if needed) - batched max 4 per call
|
||||
if (!autoYes && selectedStrategy.clarification_needed?.length > 0) {
|
||||
for (batch of chunk(selectedStrategy.clarification_needed, 4)) {
|
||||
AskUserQuestion({
|
||||
questions: batch.map((q, i) => ({
|
||||
question: q, header: `澄清${i+1}`, multiSelect: false,
|
||||
options: [{ label: "详细说明", description: "提供答案" }]
|
||||
}))
|
||||
})
|
||||
userClarifications.push(...collectAnswers(batch))
|
||||
}
|
||||
|
||||
// 5. Agent re-analysis
|
||||
reanalysisResult = Task({
|
||||
subagent_type: "cli-execution-agent",
|
||||
run_in_background: false,
|
||||
prompt: `Conflict: ${conflict.id}, Strategy: ${selectedStrategy.name}
|
||||
User Clarifications: ${JSON.stringify(userClarifications)}
|
||||
Output: { uniqueness_confirmed, rationale, updated_strategy, remaining_questions }`
|
||||
})
|
||||
|
||||
if (reanalysisResult.uniqueness_confirmed) {
|
||||
selectedStrategy = { ...reanalysisResult.updated_strategy, clarifications: userClarifications }
|
||||
clarified = true
|
||||
} else {
|
||||
selectedStrategy.clarification_needed = reanalysisResult.remaining_questions
|
||||
}
|
||||
} else {
|
||||
clarified = true
|
||||
}
|
||||
|
||||
if (clarified) resolvedConflicts.push({ conflict, strategy: selectedStrategy })
|
||||
END WHILE
|
||||
END FOR
|
||||
|
||||
selectedStrategies = resolvedConflicts.map(r => ({
|
||||
conflict_id: r.conflict.id, strategy: r.strategy, clarifications: r.strategy.clarifications || []
|
||||
}))
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- AskUserQuestion: max 4 questions/call, batch if more
|
||||
- Strategy options: 2-4 strategies + "自定义修改"
|
||||
- Clarification loop: max 10 rounds, agent判断 uniqueness_confirmed
|
||||
- Custom conflicts: 记录 overlap_analysis 供后续手动处理
|
||||
|
||||
### Phase 4: Apply Modifications
|
||||
|
||||
```javascript
|
||||
// 1. Extract modifications from resolved strategies
|
||||
const modifications = [];
|
||||
selectedStrategies.forEach(item => {
|
||||
if (item.strategy && item.strategy.modifications) {
|
||||
modifications.push(...item.strategy.modifications.map(mod => ({
|
||||
...mod,
|
||||
conflict_id: item.conflict_id,
|
||||
clarifications: item.clarifications
|
||||
})));
|
||||
}
|
||||
});
|
||||
|
||||
console.log(`\n正在应用 ${modifications.length} 个修改...`);
|
||||
|
||||
// 2. Apply each modification using Edit tool (with fallback to context-package.json)
|
||||
const appliedModifications = [];
|
||||
const failedModifications = [];
|
||||
const fallbackConstraints = []; // For files that don't exist
|
||||
|
||||
modifications.forEach((mod, idx) => {
|
||||
try {
|
||||
console.log(`[${idx + 1}/${modifications.length}] 修改 ${mod.file}...`);
|
||||
|
||||
// Check if target file exists (brainstorm files may not exist in lite workflow)
|
||||
if (!file_exists(mod.file)) {
|
||||
console.log(` ⚠️ 文件不存在，写入 context-package.json 作为约束`);
|
||||
fallbackConstraints.push({
|
||||
source: "conflict-resolution",
|
||||
conflict_id: mod.conflict_id,
|
||||
target_file: mod.file,
|
||||
section: mod.section,
|
||||
change_type: mod.change_type,
|
||||
content: mod.new_content,
|
||||
rationale: mod.rationale
|
||||
});
|
||||
return; // Skip to next modification
|
||||
}
|
||||
|
||||
if (mod.change_type === "update") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
old_string: mod.old_content,
|
||||
new_string: mod.new_content
|
||||
});
|
||||
} else if (mod.change_type === "add") {
|
||||
// Handle addition - append or insert based on section
|
||||
const fileContent = Read(mod.file);
|
||||
const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content);
|
||||
Write(mod.file, updated);
|
||||
} else if (mod.change_type === "remove") {
|
||||
Edit({
|
||||
file_path: mod.file,
|
||||
old_string: mod.old_content,
|
||||
new_string: ""
|
||||
});
|
||||
}
|
||||
|
||||
appliedModifications.push(mod);
|
||||
console.log(` ✓ 成功`);
|
||||
} catch (error) {
|
||||
console.log(` ✗ 失败: ${error.message}`);
|
||||
failedModifications.push({ ...mod, error: error.message });
|
||||
}
|
||||
});
|
||||
|
||||
// 2b. Generate conflict-resolution.json output file
|
||||
const resolutionOutput = {
|
||||
session_id: sessionId,
|
||||
resolved_at: new Date().toISOString(),
|
||||
summary: {
|
||||
total_conflicts: conflicts.length,
|
||||
resolved_with_strategy: selectedStrategies.length,
|
||||
custom_handling: customConflicts.length,
|
||||
fallback_constraints: fallbackConstraints.length
|
||||
},
|
||||
resolved_conflicts: selectedStrategies.map(s => ({
|
||||
conflict_id: s.conflict_id,
|
||||
strategy_name: s.strategy.name,
|
||||
strategy_approach: s.strategy.approach,
|
||||
clarifications: s.clarifications || [],
|
||||
modifications_applied: s.strategy.modifications?.filter(m =>
|
||||
appliedModifications.some(am => am.conflict_id === s.conflict_id)
|
||||
) || []
|
||||
})),
|
||||
custom_conflicts: customConflicts.map(c => ({
|
||||
id: c.id,
|
||||
brief: c.brief,
|
||||
category: c.category,
|
||||
suggestions: c.suggestions,
|
||||
overlap_analysis: c.overlap_analysis || null
|
||||
})),
|
||||
planning_constraints: fallbackConstraints, // Constraints for files that don't exist
|
||||
failed_modifications: failedModifications
|
||||
};
|
||||
|
||||
const resolutionPath = `.workflow/active/${sessionId}/.process/conflict-resolution.json`;
|
||||
Write(resolutionPath, JSON.stringify(resolutionOutput, null, 2));
|
||||
console.log(`\n📄 冲突解决结果已保存: ${resolutionPath}`);
|
||||
|
||||
// 3. Update context-package.json with resolution details (reference to JSON file)
|
||||
const contextPackage = JSON.parse(Read(contextPath));
|
||||
contextPackage.conflict_detection.conflict_risk = "resolved";
|
||||
contextPackage.conflict_detection.resolution_file = resolutionPath; // Reference to detailed JSON
|
||||
contextPackage.conflict_detection.resolved_conflicts = selectedStrategies.map(s => s.conflict_id);
|
||||
contextPackage.conflict_detection.custom_conflicts = customConflicts.map(c => c.id);
|
||||
contextPackage.conflict_detection.resolved_at = new Date().toISOString();
|
||||
Write(contextPath, JSON.stringify(contextPackage, null, 2));
|
||||
|
||||
// 4. Output custom conflict summary with overlap analysis (if any)
|
||||
if (customConflicts.length > 0) {
|
||||
console.log(`\n${'='.repeat(60)}`);
|
||||
console.log(`需要自定义处理的冲突 (${customConflicts.length})`);
|
||||
console.log(`${'='.repeat(60)}\n`);
|
||||
|
||||
customConflicts.forEach(conflict => {
|
||||
console.log(`【${conflict.category}】${conflict.id}: ${conflict.brief}`);
|
||||
|
||||
// Show overlap analysis for ModuleOverlap conflicts
|
||||
if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) {
|
||||
console.log(`\n场景重叠信息:`);
|
||||
console.log(` 新模块: ${conflict.overlap_analysis.new_module.name}`);
|
||||
console.log(` 场景: ${conflict.overlap_analysis.new_module.scenarios.join(', ')}`);
|
||||
console.log(`\n 与以下模块重叠:`);
|
||||
conflict.overlap_analysis.existing_modules.forEach(mod => {
|
||||
console.log(` - ${mod.name} (${mod.file})`);
|
||||
console.log(` 重叠场景: ${mod.overlap_scenarios.join(', ')}`);
|
||||
});
|
||||
}
|
||||
|
||||
console.log(`\n修改建议:`);
|
||||
conflict.suggestions.forEach(suggestion => {
|
||||
console.log(` - ${suggestion}`);
|
||||
});
|
||||
console.log();
|
||||
});
|
||||
}
|
||||
|
||||
// 5. Output failure summary (if any)
|
||||
if (failedModifications.length > 0) {
|
||||
console.log(`\n⚠️ 部分修改失败 (${failedModifications.length}):`);
|
||||
failedModifications.forEach(mod => {
|
||||
console.log(` - ${mod.file}: ${mod.error}`);
|
||||
});
|
||||
}
|
||||
|
||||
// 6. Return summary
|
||||
return {
|
||||
total_conflicts: conflicts.length,
|
||||
resolved_with_strategy: selectedStrategies.length,
|
||||
custom_handling: customConflicts.length,
|
||||
modifications_applied: appliedModifications.length,
|
||||
modifications_failed: failedModifications.length,
|
||||
modified_files: [...new Set(appliedModifications.map(m => m.file))],
|
||||
custom_conflicts: customConflicts,
|
||||
clarification_records: selectedStrategies.filter(s => s.clarifications.length > 0)
|
||||
};
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
```
|
||||
✓ Agent returns valid JSON structure with ModuleOverlap conflicts
|
||||
✓ Conflicts processed ONE BY ONE (not in batches)
|
||||
✓ ModuleOverlap conflicts include overlap_analysis field
|
||||
✓ Strategies with clarification_needed display questions
|
||||
✓ User selections captured correctly per conflict
|
||||
✓ Clarification loop continues until uniqueness confirmed
|
||||
✓ Agent re-analysis returns uniqueness_confirmed and updated_strategy
|
||||
✓ Maximum 10 rounds per conflict safety limit enforced
|
||||
✓ Edit tool successfully applies modifications
|
||||
✓ guidance-specification.md updated
|
||||
✓ Role analyses (*.md) updated
|
||||
✓ context-package.json marked as resolved with clarification records
|
||||
✓ Custom conflicts display overlap_analysis for manual handling
|
||||
✓ Agent log saved to .workflow/active/{session_id}/.chat/
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Primary Output: conflict-resolution.json
|
||||
|
||||
**Path**: `.workflow/active/{session_id}/.process/conflict-resolution.json`
|
||||
|
||||
**Schema**:
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-xxx",
|
||||
"resolved_at": "ISO timestamp",
|
||||
"summary": {
|
||||
"total_conflicts": 3,
|
||||
"resolved_with_strategy": 2,
|
||||
"custom_handling": 1,
|
||||
"fallback_constraints": 0
|
||||
},
|
||||
"resolved_conflicts": [
|
||||
{
|
||||
"conflict_id": "CON-001",
|
||||
"strategy_name": "策略名称",
|
||||
"strategy_approach": "实现方法",
|
||||
"clarifications": [],
|
||||
"modifications_applied": []
|
||||
}
|
||||
],
|
||||
"custom_conflicts": [
|
||||
{
|
||||
"id": "CON-002",
|
||||
"brief": "冲突摘要",
|
||||
"category": "ModuleOverlap",
|
||||
"suggestions": ["建议1", "建议2"],
|
||||
"overlap_analysis": null
|
||||
}
|
||||
],
|
||||
"planning_constraints": [],
|
||||
"failed_modifications": []
|
||||
}
|
||||
```
|
||||
|
||||
### Secondary: Agent JSON Response (stdout)
|
||||
|
||||
**Focus**: Structured conflict data with actionable modifications for programmatic processing.
|
||||
|
||||
**Structure**: Defined in Phase 2, Step 4 (agent prompt)
|
||||
|
||||
### Key Requirements
|
||||
| Requirement | Details |
|
||||
|------------|---------|
|
||||
| **Conflict batching** | Max 10 conflicts per round (no total limit) |
|
||||
| **Strategy count** | 2-4 strategies per conflict |
|
||||
| **Modifications** | Each strategy includes file paths, old_content, new_content |
|
||||
| **User-facing text** | Chinese (brief, strategy names, pros/cons) |
|
||||
| **Technical fields** | English (severity, category, complexity, risk) |
|
||||
| **old_content precision** | 20-100 chars for unique Edit tool matching |
|
||||
| **File targets** | guidance-specification.md, role analyses (*.md) |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Recovery Strategy
|
||||
```
|
||||
1. Pre-check: Verify conflict_risk ≥ medium
|
||||
2. Monitor: Track agent via Task tool
|
||||
3. Validate: Parse agent JSON output
|
||||
4. Recover:
|
||||
- Agent failure → check logs + report error
|
||||
- Invalid JSON → retry once with Claude fallback
|
||||
- CLI failure → fallback to Claude analysis
|
||||
- Edit tool failure → report affected files + rollback option
|
||||
- User cancels → mark as "unresolved", continue to task-generate
|
||||
5. Degrade: If all fail, generate minimal conflict report and skip modifications
|
||||
```
|
||||
|
||||
### Rollback Handling
|
||||
```
|
||||
If Edit tool fails mid-application:
|
||||
1. Log all successfully applied modifications
|
||||
2. Output rollback option via text interaction
|
||||
3. If rollback selected: restore files from git or backups
|
||||
4. If continue: mark partial resolution in context-package.json
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
### Interface
|
||||
**Input**:
|
||||
- `--session` (required): WFS-{session-id}
|
||||
- `--context` (required): context-package.json path
|
||||
- Requires: `conflict_risk ≥ medium`
|
||||
|
||||
**Output**:
|
||||
- Generated file:
|
||||
- `.workflow/active/{session_id}/.process/conflict-resolution.json` (primary output)
|
||||
- Modified files (if exist):
|
||||
- `.workflow/active/{session_id}/.brainstorm/guidance-specification.md`
|
||||
- `.workflow/active/{session_id}/.brainstorm/{role}/analysis.md`
|
||||
- `.workflow/active/{session_id}/.process/context-package.json` (conflict_risk → resolved, resolution_file reference)
|
||||
|
||||
**User Interaction**:
|
||||
- **Iterative conflict processing**: One conflict at a time, not in batches
|
||||
- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
|
||||
- **Clarification loop**: Unlimited questions per conflict until uniqueness confirmed (max 10 rounds)
|
||||
- **ModuleOverlap conflicts**: Display overlap_analysis with existing modules
|
||||
- **Agent re-analysis**: Dynamic strategy updates based on user clarifications
|
||||
|
||||
### Success Criteria
|
||||
```
|
||||
✓ CLI analysis returns valid JSON structure with ModuleOverlap category
|
||||
✓ Agent performs scenario uniqueness detection (searches existing modules)
|
||||
✓ Conflicts processed ONE BY ONE with iterative clarification
|
||||
✓ Min 2 strategies per conflict with modifications
|
||||
✓ ModuleOverlap conflicts include overlap_analysis with existing modules
|
||||
✓ Strategies requiring clarification include clarification_needed questions
|
||||
✓ Each conflict includes 2-5 modification_suggestions
|
||||
✓ Text output displays conflict with overlap analysis (if ModuleOverlap)
|
||||
✓ User selections captured per conflict
|
||||
✓ Clarification loop continues until uniqueness confirmed (unlimited rounds, max 10)
|
||||
✓ Agent re-analysis with user clarifications updates strategy
|
||||
✓ Uniqueness confirmation based on clear scenario boundaries
|
||||
✓ Edit tool applies modifications successfully
|
||||
✓ Custom conflicts displayed with overlap_analysis for manual handling
|
||||
✓ guidance-specification.md updated with resolved conflicts
|
||||
✓ Role analyses (*.md) updated with resolved conflicts
|
||||
✓ context-package.json marked as "resolved" with clarification records
|
||||
✓ conflict-resolution.json generated with full resolution details
|
||||
✓ Modification summary includes:
|
||||
- Total conflicts
|
||||
- Resolved with strategy (count)
|
||||
- Custom handling (count)
|
||||
- Clarification records
|
||||
- Overlap analysis for custom ModuleOverlap conflicts
|
||||
✓ Agent log saved to .workflow/active/{session_id}/.chat/
|
||||
✓ Error handling robust (validate/retry/degrade)
|
||||
```
|
||||
|
||||
@@ -1,408 +0,0 @@
|
||||
---
|
||||
name: gather
|
||||
description: Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON
|
||||
argument-hint: "--session WFS-session-id \"task description\""
|
||||
examples:
|
||||
- /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
|
||||
- /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
|
||||
- /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
|
||||
allowed-tools: Task(*), Read(*), Glob(*)
|
||||
---
|
||||
|
||||
# Context Gather Command (/workflow:tools:context-gather)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
|
||||
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
|
||||
- **Detection-First**: Check for existing context-package before executing
|
||||
- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
|
||||
- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
|
||||
|
||||
## Execution 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: Complexity Assessment & Parallel Explore
|
||||
├─ Analyze task_description → classify Low/Medium/High
|
||||
├─ Select exploration angles (1-4 based on complexity)
|
||||
├─ Launch N cli-explore-agents in parallel
|
||||
│ └─ Each outputs: exploration-{angle}.json
|
||||
└─ Generate explorations-manifest.json
|
||||
|
||||
Step 3: Invoke Context-Search Agent (with exploration input)
|
||||
├─ Phase 1: Initialization & Pre-Analysis
|
||||
├─ Phase 2: Multi-Source Discovery
|
||||
│ ├─ Track 0: Exploration Synthesis (prioritize & deduplicate)
|
||||
│ ├─ Track 1-4: Existing tracks
|
||||
└─ Phase 3: Synthesis & Packaging
|
||||
└─ Generate context-package.json with exploration_results
|
||||
|
||||
Step 4: Output Verification
|
||||
└─ Verify context-package.json contains exploration_results
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Step 1: Context-Package Detection
|
||||
|
||||
**Execute First** - Check if valid package already exists:
|
||||
|
||||
```javascript
|
||||
const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
|
||||
|
||||
if (file_exists(contextPackagePath)) {
|
||||
const existing = Read(contextPackagePath);
|
||||
|
||||
// Validate package belongs to current session
|
||||
if (existing?.metadata?.session_id === session_id) {
|
||||
console.log("✅ Valid context-package found for session:", session_id);
|
||||
console.log("📊 Stats:", existing.statistics);
|
||||
console.log("⚠️ Conflict Risk:", existing.conflict_detection.risk_level);
|
||||
return existing; // Skip execution, return existing
|
||||
} else {
|
||||
console.warn("⚠️ Invalid session_id in existing package, re-generating...");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Complexity Assessment & Parallel Explore
|
||||
|
||||
**Only execute if Step 1 finds no valid package**
|
||||
|
||||
```javascript
|
||||
// 2.1 Complexity Assessment
|
||||
function analyzeTaskComplexity(taskDescription) {
|
||||
const text = taskDescription.toLowerCase();
|
||||
if (/architect|refactor|restructure|modular|cross-module/.test(text)) return 'High';
|
||||
if (/multiple|several|integrate|migrate|extend/.test(text)) return 'Medium';
|
||||
return 'Low';
|
||||
}
|
||||
|
||||
const ANGLE_PRESETS = {
|
||||
architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'],
|
||||
security: ['security', 'auth-patterns', 'dataflow', 'validation'],
|
||||
performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
|
||||
bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
|
||||
feature: ['patterns', 'integration-points', 'testing', 'dependencies'],
|
||||
refactor: ['architecture', 'patterns', 'dependencies', 'testing']
|
||||
};
|
||||
|
||||
function selectAngles(taskDescription, complexity) {
|
||||
const text = taskDescription.toLowerCase();
|
||||
let preset = 'feature';
|
||||
if (/refactor|architect|restructure/.test(text)) preset = 'architecture';
|
||||
else if (/security|auth|permission/.test(text)) preset = 'security';
|
||||
else if (/performance|slow|optimi/.test(text)) preset = 'performance';
|
||||
else if (/fix|bug|error|issue/.test(text)) preset = 'bugfix';
|
||||
|
||||
const count = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1);
|
||||
return ANGLE_PRESETS[preset].slice(0, count);
|
||||
}
|
||||
|
||||
const complexity = analyzeTaskComplexity(task_description);
|
||||
const selectedAngles = selectAngles(task_description, complexity);
|
||||
const sessionFolder = `.workflow/active/${session_id}/.process`;
|
||||
|
||||
// 2.2 Launch Parallel Explore Agents
|
||||
const explorationTasks = selectedAngles.map((angle, index) =>
|
||||
Task(
|
||||
subagent_type="cli-explore-agent",
|
||||
run_in_background=false,
|
||||
description=`Explore: ${angle}`,
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints.
|
||||
|
||||
## Assigned Context
|
||||
- **Exploration Angle**: ${angle}
|
||||
- **Task Description**: ${task_description}
|
||||
- **Session ID**: ${session_id}
|
||||
- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
|
||||
- **Output File**: ${sessionFolder}/exploration-${angle}.json
|
||||
|
||||
## MANDATORY FIRST STEPS (Execute by Agent)
|
||||
**You (cli-explore-agent) MUST execute these steps in order:**
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}' (project structure)
|
||||
2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
|
||||
3. Execute: cat ~/.ccw/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
|
||||
|
||||
## Exploration Strategy (${angle} focus)
|
||||
|
||||
**Step 1: Structural Scan** (Bash)
|
||||
- get_modules_by_depth.sh → identify modules related to ${angle}
|
||||
- find/rg → locate files relevant to ${angle} aspect
|
||||
- Analyze imports/dependencies from ${angle} perspective
|
||||
|
||||
**Step 2: Semantic Analysis** (Gemini CLI)
|
||||
- How does existing code handle ${angle} concerns?
|
||||
- What patterns are used for ${angle}?
|
||||
- Where would new code integrate from ${angle} viewpoint?
|
||||
|
||||
**Step 3: Write Output**
|
||||
- Consolidate ${angle} findings into JSON
|
||||
- Identify ${angle}-specific clarification needs
|
||||
|
||||
## Expected Output
|
||||
|
||||
**File**: ${sessionFolder}/exploration-${angle}.json
|
||||
|
||||
**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
|
||||
|
||||
**Required Fields** (all ${angle} focused):
|
||||
- project_structure: Modules/architecture relevant to ${angle}
|
||||
- relevant_files: Files affected from ${angle} perspective
|
||||
**MANDATORY**: Every file MUST use structured object format with ALL required fields:
|
||||
\`[{path: "src/file.ts", relevance: 0.85, rationale: "Contains AuthService.login() - entry point for JWT token generation", role: "modify_target", discovery_source: "bash-scan", key_symbols: ["AuthService", "login"]}]\`
|
||||
- **rationale** (required): Specific selection basis tied to ${angle} topic (>10 chars, not generic)
|
||||
- **role** (required): modify_target|dependency|pattern_reference|test_target|type_definition|integration_point|config|context_only
|
||||
- **discovery_source** (recommended): bash-scan|cli-analysis|ace-search|dependency-trace|manual
|
||||
- **key_symbols** (recommended): Key functions/classes/types in the file relevant to the task
|
||||
- Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low
|
||||
- patterns: ${angle}-related patterns to follow
|
||||
- dependencies: Dependencies relevant to ${angle}
|
||||
- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations)
|
||||
- constraints: ${angle}-specific limitations/conventions
|
||||
- clarification_needs: ${angle}-related ambiguities (options array + recommended index)
|
||||
- _metadata.exploration_angle: "${angle}"
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Schema obtained via cat explore-json-schema.json
|
||||
- [ ] get_modules_by_depth.sh executed
|
||||
- [ ] At least 3 relevant files identified with ${angle} rationale
|
||||
- [ ] Patterns are actionable (code examples, not generic advice)
|
||||
- [ ] Integration points include file:line locations
|
||||
- [ ] Constraints are project-specific to ${angle}
|
||||
- [ ] JSON output follows schema exactly
|
||||
- [ ] clarification_needs includes options + recommended
|
||||
|
||||
## Output
|
||||
Write: ${sessionFolder}/exploration-${angle}.json
|
||||
Return: 2-3 sentence summary of ${angle} findings
|
||||
`
|
||||
)
|
||||
);
|
||||
|
||||
// 2.3 Generate Manifest after all complete
|
||||
const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`).split('\n').filter(f => f.trim());
|
||||
const explorationManifest = {
|
||||
session_id,
|
||||
task_description,
|
||||
timestamp: new Date().toISOString(),
|
||||
complexity,
|
||||
exploration_count: selectedAngles.length,
|
||||
angles_explored: selectedAngles,
|
||||
explorations: explorationFiles.map(file => {
|
||||
const data = JSON.parse(Read(file));
|
||||
return { angle: data._metadata.exploration_angle, file: file.split('/').pop(), path: file, index: data._metadata.exploration_index };
|
||||
})
|
||||
};
|
||||
Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2));
|
||||
```
|
||||
|
||||
### Step 3: Invoke Context-Search Agent
|
||||
|
||||
**Only execute after Step 2 completes**
|
||||
|
||||
```javascript
|
||||
// Load user intent from planning-notes.md (from Phase 1)
|
||||
const planningNotesPath = `.workflow/active/${session_id}/planning-notes.md`;
|
||||
let userIntent = { goal: task_description, key_constraints: "None specified" };
|
||||
|
||||
if (file_exists(planningNotesPath)) {
|
||||
const notesContent = Read(planningNotesPath);
|
||||
const goalMatch = notesContent.match(/\*\*GOAL\*\*:\s*(.+)/);
|
||||
const constraintsMatch = notesContent.match(/\*\*KEY_CONSTRAINTS\*\*:\s*(.+)/);
|
||||
if (goalMatch) userIntent.goal = goalMatch[1].trim();
|
||||
if (constraintsMatch) userIntent.key_constraints = constraintsMatch[1].trim();
|
||||
}
|
||||
|
||||
Task(
|
||||
subagent_type="context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather comprehensive context for plan",
|
||||
prompt=`
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution with priority sorting
|
||||
|
||||
## Session Information
|
||||
- **Session ID**: ${session_id}
|
||||
- **Task Description**: ${task_description}
|
||||
- **Output Path**: .workflow/${session_id}/.process/context-package.json
|
||||
|
||||
## User Intent (from Phase 1 - Planning Notes)
|
||||
**GOAL**: ${userIntent.goal}
|
||||
**KEY_CONSTRAINTS**: ${userIntent.key_constraints}
|
||||
|
||||
This is the PRIMARY context source - all subsequent analysis must align with user intent.
|
||||
|
||||
## Exploration Input (from Step 2)
|
||||
- **Manifest**: ${sessionFolder}/explorations-manifest.json
|
||||
- **Exploration Count**: ${explorationManifest.exploration_count}
|
||||
- **Angles**: ${explorationManifest.angles_explored.join(', ')}
|
||||
- **Complexity**: ${complexity}
|
||||
|
||||
## Mission
|
||||
Execute complete context-search-agent workflow for implementation planning:
|
||||
|
||||
### Phase 1: Initialization & Pre-Analysis
|
||||
1. **Project State Loading**:
|
||||
- Read and parse `.workflow/project-tech.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components.
|
||||
- Read and parse `.workflow/project-guidelines.json`. Load `conventions`, `constraints`, and `learnings` into a `project_guidelines` section.
|
||||
- If files don't exist, proceed with fresh analysis.
|
||||
2. **Detection**: Check for existing context-package (early exit if valid)
|
||||
3. **Foundation**: Initialize CodexLens, get project structure, load docs
|
||||
4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state
|
||||
|
||||
### Phase 2: Multi-Source Context Discovery
|
||||
Execute all discovery tracks (WITH USER INTENT INTEGRATION):
|
||||
- **Track -1**: User Intent & Priority Foundation (EXECUTE FIRST)
|
||||
- Load user intent (GOAL, KEY_CONSTRAINTS) from session input
|
||||
- Map user requirements to codebase entities (files, modules, patterns)
|
||||
- Establish baseline priority scores based on user goal alignment
|
||||
- Output: user_intent_mapping.json with preliminary priority scores
|
||||
|
||||
- **Track 0**: Exploration Synthesis (load ${sessionFolder}/explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points)
|
||||
- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
|
||||
- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
|
||||
- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
|
||||
- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
|
||||
|
||||
### Phase 3: Synthesis, Assessment & Packaging
|
||||
1. Apply relevance scoring and build dependency graph
|
||||
2. **Synthesize 5-source data** (including Track -1): Merge findings from all sources
|
||||
- Priority order: User Intent > Archive > Docs > Exploration > Code > Web
|
||||
- **Prioritize the context from `project-tech.json`** for architecture and tech stack unless code analysis reveals it's outdated
|
||||
3. **Context Priority Sorting**:
|
||||
a. Combine scores from Track -1 (user intent alignment) + relevance scores + exploration critical_files
|
||||
b. Classify files into priority tiers:
|
||||
- **Critical** (score ≥ 0.85): Directly mentioned in user goal OR exploration critical_files
|
||||
- **High** (0.70-0.84): Key dependencies, patterns required for goal
|
||||
- **Medium** (0.50-0.69): Supporting files, indirect dependencies
|
||||
- **Low** (< 0.50): Contextual awareness only
|
||||
c. Generate dependency_order: Based on dependency graph + user goal sequence
|
||||
d. Document sorting_rationale: Explain prioritization logic
|
||||
|
||||
4. **Populate `project_context`**: Directly use the `overview` from `project-tech.json` to fill the `project_context` section. Include description, technology_stack, architecture, and key_components.
|
||||
5. **Populate `project_guidelines`**: Load conventions, constraints, and learnings from `project-guidelines.json` into a dedicated section.
|
||||
6. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
|
||||
7. Perform conflict detection with risk assessment
|
||||
8. **Inject historical conflicts** from archive analysis into conflict_detection
|
||||
9. **Generate prioritized_context section**:
|
||||
```json
|
||||
{
|
||||
"prioritized_context": {
|
||||
"user_intent": {
|
||||
"goal": "...",
|
||||
"scope": "...",
|
||||
"key_constraints": ["..."]
|
||||
},
|
||||
"priority_tiers": {
|
||||
"critical": [{ "path": "...", "relevance": 0.95, "rationale": "..." }],
|
||||
"high": [...],
|
||||
"medium": [...],
|
||||
"low": [...]
|
||||
},
|
||||
"dependency_order": ["module1", "module2", "module3"],
|
||||
"sorting_rationale": "Based on user goal alignment (Track -1), exploration critical files, and dependency graph analysis"
|
||||
}
|
||||
}
|
||||
```
|
||||
10. Generate and validate context-package.json with prioritized_context field
|
||||
|
||||
## Output Requirements
|
||||
Complete context-package.json with:
|
||||
- **metadata**: task_description, keywords, complexity, tech_stack, session_id
|
||||
- **project_context**: description, technology_stack, architecture, key_components (sourced from `project-tech.json`)
|
||||
- **project_guidelines**: {conventions, constraints, quality_rules, learnings} (sourced from `project-guidelines.json`)
|
||||
- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
|
||||
- **dependencies**: {internal[], external[]} with dependency graph
|
||||
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
|
||||
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
|
||||
- **exploration_results**: {manifest_path, exploration_count, angles, explorations[], aggregated_insights} (from Track 0)
|
||||
- **prioritized_context**: {user_intent, priority_tiers{critical, high, medium, low}, dependency_order[], sorting_rationale}
|
||||
|
||||
## Quality Validation
|
||||
Before completion verify:
|
||||
- [ ] Valid JSON format with all required fields
|
||||
- [ ] File relevance accuracy >80%
|
||||
- [ ] Dependency graph complete (max 2 transitive levels)
|
||||
- [ ] Conflict risk level calculated correctly
|
||||
- [ ] No sensitive data exposed
|
||||
- [ ] Total files ≤50 (prioritize high-relevance)
|
||||
|
||||
## Planning Notes Record (REQUIRED)
|
||||
After completing context-package.json, append a brief execution record to planning-notes.md:
|
||||
|
||||
**File**: .workflow/active/${session_id}/planning-notes.md
|
||||
**Location**: Under "## Context Findings (Phase 2)" section
|
||||
**Format**:
|
||||
\`\`\`
|
||||
### [Context-Search Agent] YYYY-MM-DD
|
||||
- **Note**: [智能补充：简短总结关键发现，如探索角度、关键文件、冲突风险等]
|
||||
\`\`\`
|
||||
|
||||
Execute autonomously following agent documentation.
|
||||
Report completion with statistics.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Step 4: Output Verification
|
||||
|
||||
After agent completes, verify output:
|
||||
|
||||
```javascript
|
||||
// Verify file was created
|
||||
const outputPath = `.workflow/${session_id}/.process/context-package.json`;
|
||||
if (!file_exists(outputPath)) {
|
||||
throw new Error("❌ Agent failed to generate context-package.json");
|
||||
}
|
||||
|
||||
// Verify exploration_results included
|
||||
const pkg = JSON.parse(Read(outputPath));
|
||||
if (pkg.exploration_results?.exploration_count > 0) {
|
||||
console.log(`✅ Exploration results aggregated: ${pkg.exploration_results.exploration_count} angles`);
|
||||
}
|
||||
```
|
||||
|
||||
## Parameter Reference
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) |
|
||||
| `task_description` | string | ✅ | Detailed task description for context extraction |
|
||||
|
||||
## Output Schema
|
||||
|
||||
Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema.
|
||||
|
||||
**Key Sections**:
|
||||
- **metadata**: Session info, keywords, complexity, tech stack
|
||||
- **project_context**: Architecture patterns, conventions, tech stack (populated from `project-tech.json`)
|
||||
- **project_guidelines**: Conventions, constraints, quality rules, learnings (populated from `project-guidelines.json`)
|
||||
- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
|
||||
- **dependencies**: Internal and external dependency graphs
|
||||
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
|
||||
- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
|
||||
- **exploration_results**: Aggregated exploration insights (from parallel explore phase)
|
||||
- **prioritized_context**: Pre-sorted context with user intent and priority tiers (critical/high/medium/low)
|
||||
|
||||
## Notes
|
||||
|
||||
- **Detection-first**: Always check for existing package before invoking agent
|
||||
- **User intent integration**: Load user intent from planning-notes.md (Phase 1 output)
|
||||
- **Output**: Generates `context-package.json` with `prioritized_context` field
|
||||
- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call
|
||||
@@ -1,731 +0,0 @@
|
||||
---
|
||||
name: task-generate-agent
|
||||
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: "[-y|--yes] --session WFS-session-id"
|
||||
examples:
|
||||
- /workflow:tools:task-generate-agent --session WFS-auth
|
||||
- /workflow:tools:task-generate-agent -y --session WFS-auth
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor, Codex CLI tool).
|
||||
|
||||
# Generate Implementation Plan Command
|
||||
|
||||
## Overview
|
||||
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
|
||||
- **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
|
||||
- **NO Redundant Context Sorting**: Context priority sorting is ALREADY completed in context-gather Phase 2/3
|
||||
- Use `context-package.json.prioritized_context` directly
|
||||
- DO NOT re-sort files or re-compute priorities
|
||||
- `priority_tiers` and `dependency_order` are pre-computed and ready-to-use
|
||||
- **N+1 Parallel Planning**: Auto-detect multi-module projects, enable parallel planning (2+1 or 3+1 mode)
|
||||
- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size
|
||||
- **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 Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
├─ Parse flags: --session
|
||||
└─ Validation: session_id REQUIRED
|
||||
|
||||
Phase 0: User Configuration (Interactive)
|
||||
├─ Question 1: Supplementary materials/guidelines?
|
||||
├─ Question 2: Execution method preference (Agent/CLI/Hybrid)
|
||||
├─ Question 3: CLI tool preference (if CLI selected)
|
||||
└─ Store: userConfig for agent prompt
|
||||
|
||||
Phase 1: Context Preparation & Module Detection (Command)
|
||||
├─ Assemble session paths (metadata, context package, output dirs)
|
||||
├─ Provide metadata (session_id, execution_mode, mcp_capabilities)
|
||||
├─ Auto-detect modules from context-package + directory structure
|
||||
└─ Decision:
|
||||
├─ modules.length == 1 → Single Agent Mode (Phase 2A)
|
||||
└─ modules.length >= 2 → Parallel Mode (Phase 2B + Phase 3)
|
||||
|
||||
Phase 2A: Single Agent Planning (Original Flow)
|
||||
├─ Load context package (progressive loading strategy)
|
||||
├─ Generate Task JSON Files (.task/IMPL-*.json)
|
||||
├─ Create IMPL_PLAN.md
|
||||
└─ Generate TODO_LIST.md
|
||||
|
||||
Phase 2B: N Parallel Planning (Multi-Module)
|
||||
├─ Launch N action-planning-agents simultaneously (one per module)
|
||||
├─ Each agent generates module-scoped tasks (IMPL-{prefix}{seq}.json)
|
||||
├─ Task ID format: IMPL-A1, IMPL-A2... / IMPL-B1, IMPL-B2...
|
||||
└─ Each module limited to ≤9 tasks
|
||||
|
||||
Phase 3: Integration (+1 Coordinator, Multi-Module Only)
|
||||
├─ Collect all module task JSONs
|
||||
├─ Resolve cross-module dependencies (CROSS::{module}::{pattern} → actual ID)
|
||||
├─ Generate unified IMPL_PLAN.md (grouped by module)
|
||||
└─ Generate TODO_LIST.md (hierarchical: module → tasks)
|
||||
```
|
||||
|
||||
## Document Generation Lifecycle
|
||||
|
||||
### Phase 0: User Configuration (Interactive)
|
||||
|
||||
**Purpose**: Collect user preferences before task generation to ensure generated tasks match execution expectations.
|
||||
|
||||
**Auto Mode Check**:
|
||||
```javascript
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
|
||||
if (autoYes) {
|
||||
console.log(`[--yes] Using defaults: No materials, Agent executor, Codex CLI`)
|
||||
userConfig = {
|
||||
supplementaryMaterials: { type: "none", content: [] },
|
||||
executionMethod: "agent",
|
||||
preferredCliTool: "codex",
|
||||
enableResume: true
|
||||
}
|
||||
// Skip to Phase 1
|
||||
}
|
||||
```
|
||||
|
||||
**User Questions** (skipped if autoYes):
|
||||
```javascript
|
||||
if (!autoYes) AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Do you have supplementary materials or guidelines to include?",
|
||||
header: "Materials",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No additional materials", description: "Use existing context only" },
|
||||
{ label: "Provide file paths", description: "I'll specify paths to include" },
|
||||
{ label: "Provide inline content", description: "I'll paste content directly" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Select execution method for generated tasks:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent (Recommended)", description: "Claude agent executes tasks directly" },
|
||||
{ label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps" },
|
||||
{ label: "CLI Only", description: "All execution via CLI tools (codex/gemini/qwen)" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "If using CLI, which tool do you prefer?",
|
||||
header: "CLI Tool",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Codex (Recommended)", description: "Best for implementation tasks" },
|
||||
{ label: "Gemini", description: "Best for analysis and large context" },
|
||||
{ label: "Qwen", description: "Alternative analysis tool" },
|
||||
{ label: "Auto", description: "Let agent decide per-task" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
|
||||
**Handle Materials Response** (skipped if autoYes):
|
||||
```javascript
|
||||
if (!autoYes && userConfig.materials === "Provide file paths") {
|
||||
// Follow-up question for file paths
|
||||
const pathsResponse = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Enter file paths to include (comma-separated or one per line):",
|
||||
header: "Paths",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Enter paths", description: "Provide paths in text input" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
|
||||
}
|
||||
```
|
||||
|
||||
**Build userConfig**:
|
||||
```javascript
|
||||
const userConfig = {
|
||||
supplementaryMaterials: {
|
||||
type: "none|paths|inline",
|
||||
content: [...], // Parsed paths or inline content
|
||||
},
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true // Always enable resume for CLI executions
|
||||
}
|
||||
```
|
||||
|
||||
**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2A/2B.
|
||||
|
||||
### Phase 1: Context Preparation & Module Detection (Command Responsibility)
|
||||
|
||||
**Command prepares session paths, metadata, detects module structure. Context priority sorting is NOT performed here - it's already completed in context-gather Phase 2/3.**
|
||||
|
||||
**Session Path Structure**:
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── planning-notes.md # Consolidated planning notes
|
||||
├── .process/
|
||||
│ └── context-package.json # Context package with artifact catalog
|
||||
├── .task/ # Output: Task JSON files
|
||||
│ ├── IMPL-A1.json # Multi-module: prefixed by module
|
||||
│ ├── IMPL-A2.json
|
||||
│ ├── IMPL-B1.json
|
||||
│ └── ...
|
||||
├── plan.json # Output: Structured plan overview
|
||||
├── IMPL_PLAN.md # Output: Implementation plan (grouped by module)
|
||||
└── TODO_LIST.md # Output: TODO list (hierarchical)
|
||||
```
|
||||
|
||||
**Command Preparation**:
|
||||
1. **Assemble Session Paths** for agent prompt:
|
||||
- `session_metadata_path`
|
||||
- `context_package_path`
|
||||
- Output directory paths
|
||||
|
||||
2. **Provide Metadata** (simple values):
|
||||
- `session_id`
|
||||
- `mcp_capabilities` (available MCP tools)
|
||||
|
||||
3. **Auto Module Detection** (determines single vs parallel mode):
|
||||
```javascript
|
||||
function autoDetectModules(contextPackage, projectRoot) {
|
||||
// === Complexity Gate: Only parallelize for High complexity ===
|
||||
const complexity = contextPackage.metadata?.complexity || 'Medium';
|
||||
if (complexity !== 'High') {
|
||||
// Force single agent mode for Low/Medium complexity
|
||||
// This maximizes agent context reuse for related tasks
|
||||
return [{ name: 'main', prefix: '', paths: ['.'] }];
|
||||
}
|
||||
|
||||
// Priority 1: Explicit frontend/backend separation
|
||||
if (exists('src/frontend') && exists('src/backend')) {
|
||||
return [
|
||||
{ name: 'frontend', prefix: 'A', paths: ['src/frontend'] },
|
||||
{ name: 'backend', prefix: 'B', paths: ['src/backend'] }
|
||||
];
|
||||
}
|
||||
|
||||
// Priority 2: Monorepo structure
|
||||
if (exists('packages/*') || exists('apps/*')) {
|
||||
return detectMonorepoModules(); // Returns 2-3 main packages
|
||||
}
|
||||
|
||||
// Priority 3: Context-package dependency clustering
|
||||
const modules = clusterByDependencies(contextPackage.dependencies?.internal);
|
||||
if (modules.length >= 2) return modules.slice(0, 3);
|
||||
|
||||
// Default: Single module (original flow)
|
||||
return [{ name: 'main', prefix: '', paths: ['.'] }];
|
||||
}
|
||||
```
|
||||
|
||||
**Decision Logic**:
|
||||
- `complexity !== 'High'` → Force Phase 2A (Single Agent, maximize context reuse)
|
||||
- `modules.length == 1` → Phase 2A (Single Agent, original flow)
|
||||
- `modules.length >= 2 && complexity == 'High'` → Phase 2B + Phase 3 (N+1 Parallel)
|
||||
|
||||
**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags.
|
||||
|
||||
### Phase 2A: Single Agent Planning (Original Flow)
|
||||
|
||||
**Condition**: `modules.length == 1` (no multi-module detected)
|
||||
|
||||
**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",
|
||||
run_in_background=false,
|
||||
description="Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
|
||||
|
||||
IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.
|
||||
|
||||
CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
|
||||
|
||||
## PLANNING NOTES (PHASE 1-3 CONTEXT)
|
||||
Load: .workflow/active/{session-id}/planning-notes.md
|
||||
|
||||
This document contains:
|
||||
- User Intent: Original GOAL and KEY_CONSTRAINTS from Phase 1
|
||||
- Context Findings: Critical files, architecture, and constraints from Phase 2
|
||||
- Conflict Decisions: Resolved conflicts and planning constraints from Phase 3
|
||||
- Consolidated Constraints: All constraints from all phases
|
||||
|
||||
**USAGE**: Read planning-notes.md FIRST. Use Consolidated Constraints list to guide task sequencing and dependencies.
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Planning Notes: .workflow/active/{session-id}/planning-notes.md
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
|
||||
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
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## FEATURE SPECIFICATIONS (conditional)
|
||||
If context-package has brainstorm_artifacts.feature_index_path:
|
||||
Feature Index: ${contextPackage.brainstorm_artifacts.feature_index_path}
|
||||
Feature Spec Dir: ${contextPackage.brainstorm_artifacts.feature_index_path.replace('/feature-index.json', '/')}
|
||||
Else if .workflow/active/{session-id}/.brainstorming/feature-specs/ exists:
|
||||
Feature Index: .workflow/active/{session-id}/.brainstorming/feature-specs/feature-index.json
|
||||
Feature Spec Dir: .workflow/active/{session-id}/.brainstorming/feature-specs/
|
||||
|
||||
Use feature-index.json to:
|
||||
- Map features to implementation tasks (feature_id → task alignment)
|
||||
- Reference individual feature spec files (spec_path) for detailed requirements
|
||||
- Identify cross-cutting concerns (cross_cutting_specs) that span multiple tasks
|
||||
- Align task priorities with feature priorities
|
||||
|
||||
If the directory does not exist, skip this section (backward compatible with non-brainstorm workflows).
|
||||
|
||||
## USER CONFIGURATION (from Phase 0)
|
||||
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
||||
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
||||
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
||||
|
||||
## EXECUTION METHOD MAPPING
|
||||
Based on userConfig.executionMethod, set task-level meta.execution_config:
|
||||
|
||||
"agent" →
|
||||
meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
|
||||
Agent executes implementation steps directly
|
||||
|
||||
"cli" →
|
||||
meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
|
||||
Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()
|
||||
|
||||
"hybrid" →
|
||||
Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task
|
||||
- Simple tasks (≤3 files, straightforward logic) → method: "agent"
|
||||
- Complex tasks (>3 files, complex logic, refactoring) → method: "cli"
|
||||
CLI tool: userConfig.preferredCliTool, enable_resume: true
|
||||
|
||||
IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only.
|
||||
|
||||
## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED
|
||||
Context sorting is ALREADY COMPLETED in context-gather Phase 2/3. DO NOT re-sort.
|
||||
Direct usage:
|
||||
- **user_intent**: Use goal/scope/key_constraints for task alignment
|
||||
- **priority_tiers.critical**: These files are PRIMARY focus for task generation
|
||||
- **priority_tiers.high**: These files are SECONDARY focus
|
||||
- **dependency_order**: Use this for task sequencing - already computed
|
||||
- **sorting_rationale**: Reference for understanding priority decisions
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
|
||||
If prioritized_context is incomplete, fall back to exploration_results:
|
||||
- Load exploration_results from context-package.json
|
||||
- Use aggregated_insights.critical_files for focus_paths generation
|
||||
- Apply aggregated_insights.constraints to acceptance criteria
|
||||
- Reference aggregated_insights.all_patterns for implementation approach
|
||||
- Use aggregated_insights.all_integration_points for precise modification locations
|
||||
- Use conflict_indicators for risk-aware task sequencing
|
||||
|
||||
## CONFLICT RESOLUTION CONTEXT (if exists)
|
||||
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
||||
- If exists, load .process/conflict-resolution.json:
|
||||
- Apply planning_constraints as task constraints (for brainstorm-less workflows)
|
||||
- Reference resolved_conflicts for implementation approach alignment
|
||||
- Handle custom_conflicts with explicit task notes
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
1. Task JSON Files (.task/IMPL-*.json)
|
||||
- Unified flat schema (task-schema.json)
|
||||
- Quantified requirements with explicit counts
|
||||
- Artifacts integration from context package
|
||||
- **focus_paths generated directly from prioritized_context.priority_tiers (critical + high)**
|
||||
- NO re-sorting or re-prioritization - use pre-computed tiers as-is
|
||||
- Critical files are PRIMARY focus, High files are SECONDARY
|
||||
- Pre-analysis steps (use prioritized_context.dependency_order for task sequencing)
|
||||
- **CLI Execution IDs and strategies (MANDATORY)**
|
||||
|
||||
2. Implementation Plan (IMPL_PLAN.md)
|
||||
- Context analysis and artifact references
|
||||
- Task breakdown and execution strategy
|
||||
- Complete structure per agent definition
|
||||
|
||||
3. Plan Overview (plan.json)
|
||||
- Structured plan overview (plan-overview-base-schema)
|
||||
- Machine-readable task IDs, shared context, metadata
|
||||
|
||||
4. TODO List (TODO_LIST.md)
|
||||
- Hierarchical structure (containers, pending, completed markers)
|
||||
- Links to task JSONs and summaries
|
||||
- Matches task JSON hierarchy
|
||||
|
||||
## CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
||||
Each task JSON MUST include:
|
||||
- **cli_execution.id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`)
|
||||
- **cli_execution**: Strategy object based on depends_on:
|
||||
- No deps → `{ "strategy": "new" }`
|
||||
- 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
|
||||
- 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
|
||||
- N deps → `{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }`
|
||||
|
||||
**CLI Execution Strategy Rules**:
|
||||
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
||||
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
||||
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
||||
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
||||
|
||||
**Execution Command Patterns**:
|
||||
- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
|
||||
- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
|
||||
- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- merge_fork: `ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
|
||||
## QUALITY STANDARDS
|
||||
Hard Constraints:
|
||||
- Task count <= 18 (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 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
|
||||
|
||||
## PLANNING NOTES RECORD (REQUIRED)
|
||||
After completing, update planning-notes.md:
|
||||
|
||||
**File**: .workflow/active/{session_id}/planning-notes.md
|
||||
|
||||
1. **Task Generation (Phase 4)**: Task count and key tasks
|
||||
2. **N+1 Context**: Key decisions (with rationale) + deferred items
|
||||
|
||||
\`\`\`markdown
|
||||
## Task Generation (Phase 4)
|
||||
### [Action-Planning Agent] YYYY-MM-DD
|
||||
- **Tasks**: [count] ([IDs])
|
||||
|
||||
## N+1 Context
|
||||
### Decisions
|
||||
| Decision | Rationale | Revisit? |
|
||||
|----------|-----------|----------|
|
||||
| [choice] | [why] | [Yes/No] |
|
||||
|
||||
### Deferred
|
||||
- [ ] [item] - [reason]
|
||||
\`\`\`
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 2B: N Parallel Planning (Multi-Module)
|
||||
|
||||
**Condition**: `modules.length >= 2` (multi-module detected)
|
||||
|
||||
**Purpose**: Launch N action-planning-agents simultaneously, one per module, for parallel task JSON generation.
|
||||
|
||||
**Note**: Phase 2B agents generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md are generated by Phase 3 Coordinator.
|
||||
|
||||
**Parallel Agent Invocation**:
|
||||
```javascript
|
||||
// Launch N agents in parallel (one per module)
|
||||
const planningTasks = modules.map(module =>
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description=`Generate ${module.name} module task JSONs`,
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate task JSON files for ${module.name} module within workflow session
|
||||
|
||||
IMPORTANT: This is PLANNING ONLY - generate task JSONs, NOT implementing code.
|
||||
IMPORTANT: Generate Task JSONs ONLY. IMPL_PLAN.md and TODO_LIST.md by Phase 3 Coordinator.
|
||||
|
||||
CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
|
||||
|
||||
## PLANNING NOTES (PHASE 1-3 CONTEXT)
|
||||
Load: .workflow/active/{session-id}/planning-notes.md
|
||||
|
||||
This document contains consolidated constraints and user intent to guide module-scoped task generation.
|
||||
|
||||
## MODULE SCOPE
|
||||
- Module: ${module.name} (${module.type})
|
||||
- Focus Paths: ${module.paths.join(', ')}
|
||||
- Task ID Prefix: IMPL-${module.prefix}
|
||||
- Task Limit: ≤6 tasks (hard limit for this module)
|
||||
- Other Modules: ${otherModules.join(', ')} (reference only, do NOT generate tasks for them)
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Planning Notes: .workflow/active/{session-id}/planning-notes.md
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
|
||||
Output:
|
||||
- Task Dir: .workflow/active/{session-id}/.task/
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## FEATURE SPECIFICATIONS (conditional)
|
||||
If context-package has brainstorm_artifacts.feature_index_path:
|
||||
Feature Index: ${contextPackage.brainstorm_artifacts.feature_index_path}
|
||||
Feature Spec Dir: ${contextPackage.brainstorm_artifacts.feature_index_path.replace('/feature-index.json', '/')}
|
||||
Else if .workflow/active/{session-id}/.brainstorming/feature-specs/ exists:
|
||||
Feature Index: .workflow/active/{session-id}/.brainstorming/feature-specs/feature-index.json
|
||||
Feature Spec Dir: .workflow/active/{session-id}/.brainstorming/feature-specs/
|
||||
|
||||
Use feature-index.json to:
|
||||
- Map features to module-scoped tasks (filter by ${module.paths.join(', ')})
|
||||
- Reference individual feature spec files (spec_path) for detailed requirements
|
||||
- Identify cross-cutting concerns affecting this module
|
||||
- Align task priorities with feature priorities
|
||||
|
||||
If the directory does not exist, skip this section (backward compatible with non-brainstorm workflows).
|
||||
|
||||
## USER CONFIGURATION (from Phase 0)
|
||||
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
||||
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
||||
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
||||
|
||||
## EXECUTION METHOD MAPPING
|
||||
Based on userConfig.executionMethod, set task-level meta.execution_config:
|
||||
|
||||
"agent" →
|
||||
meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
|
||||
Agent executes implementation steps directly
|
||||
|
||||
"cli" →
|
||||
meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
|
||||
Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()
|
||||
|
||||
"hybrid" →
|
||||
Per-task decision: Analyze task complexity, set method to "agent" OR "cli" per task
|
||||
- Simple tasks (≤3 files, straightforward logic) → method: "agent"
|
||||
- Complex tasks (>3 files, complex logic, refactoring) → method: "cli"
|
||||
CLI tool: userConfig.preferredCliTool, enable_resume: true
|
||||
|
||||
IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only.
|
||||
|
||||
## PRIORITIZED CONTEXT (from context-package.prioritized_context) - ALREADY SORTED
|
||||
Context sorting is ALREADY COMPLETED in context-gather Phase 2/3. DO NOT re-sort.
|
||||
Filter by module scope (${module.paths.join(', ')}):
|
||||
- **user_intent**: Use for task alignment within module
|
||||
- **priority_tiers.critical**: Filter for files in ${module.paths.join(', ')} → PRIMARY focus
|
||||
- **priority_tiers.high**: Filter for files in ${module.paths.join(', ')} → SECONDARY focus
|
||||
- **dependency_order**: Use module-relevant entries for task sequencing
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results) - SUPPLEMENT ONLY
|
||||
If prioritized_context is incomplete for this module, fall back to exploration_results:
|
||||
- Load exploration_results from context-package.json
|
||||
- Filter for ${module.name} module: Use aggregated_insights.critical_files matching ${module.paths.join(', ')}
|
||||
- Apply module-relevant constraints from aggregated_insights.constraints
|
||||
- Reference aggregated_insights.all_patterns applicable to ${module.name}
|
||||
- Use aggregated_insights.all_integration_points for precise modification locations within module scope
|
||||
- Use conflict_indicators for risk-aware task sequencing
|
||||
|
||||
## CONFLICT RESOLUTION CONTEXT (if exists)
|
||||
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
||||
- If exists, load .process/conflict-resolution.json:
|
||||
- Apply planning_constraints relevant to ${module.name} as task constraints
|
||||
- Reference resolved_conflicts affecting ${module.name} for implementation approach alignment
|
||||
- Handle custom_conflicts with explicit task notes
|
||||
|
||||
## CROSS-MODULE DEPENDENCIES
|
||||
- For dependencies ON other modules: Use placeholder depends_on: ["CROSS::{module}::{pattern}"]
|
||||
- Example: depends_on: ["CROSS::B::api-endpoint"] (this module depends on B's api-endpoint task)
|
||||
- Phase 3 Coordinator resolves to actual task IDs
|
||||
- For dependencies FROM other modules: Document in task context as "provides_for" annotation
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
Task JSON Files (.task/IMPL-${module.prefix}*.json):
|
||||
- Unified flat schema (task-schema.json)
|
||||
- Task ID format: IMPL-${module.prefix}1, IMPL-${module.prefix}2, ...
|
||||
- Quantified requirements with explicit counts
|
||||
- Artifacts integration from context package (filtered for ${module.name})
|
||||
- **focus_paths generated directly from prioritized_context.priority_tiers filtered by ${module.paths.join(', ')}**
|
||||
- NO re-sorting - use pre-computed tiers filtered for this module
|
||||
- Critical files are PRIMARY focus, High files are SECONDARY
|
||||
- Pre-analysis steps (use prioritized_context.dependency_order for module task sequencing)
|
||||
- **CLI Execution IDs and strategies (MANDATORY)**
|
||||
- Focus ONLY on ${module.name} module scope
|
||||
|
||||
## CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
||||
Each task JSON MUST include:
|
||||
- **cli_execution.id**: Unique ID for CLI execution (format: `{session_id}-IMPL-${module.prefix}{seq}`)
|
||||
- **cli_execution**: Strategy object based on depends_on:
|
||||
- No deps → `{ "strategy": "new" }`
|
||||
- 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
|
||||
- 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
|
||||
- N deps → `{ "strategy": "merge_fork", "merge_from": ["id1", "id2", ...] }`
|
||||
- Cross-module dep → `{ "strategy": "cross_module_fork", "resume_from": "CROSS::{module}::{pattern}" }`
|
||||
|
||||
**CLI Execution Strategy Rules**:
|
||||
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
||||
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
||||
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
||||
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
||||
5. **cross_module_fork**: Task depends on task from another module - Phase 3 resolves placeholder
|
||||
|
||||
**Execution Command Patterns**:
|
||||
- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
|
||||
- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
|
||||
- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- merge_fork: `ccw cli -p "[prompt]" --resume [merge_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- cross_module_fork: (Phase 3 resolves placeholder, then uses fork pattern)
|
||||
|
||||
## QUALITY STANDARDS
|
||||
Hard Constraints:
|
||||
- Task count <= 9 for this module (hard limit - coordinate with Phase 3 if exceeded)
|
||||
- All requirements quantified (explicit counts and enumerated lists)
|
||||
- Acceptance criteria measurable (include verification commands)
|
||||
- Artifact references mapped from context package (module-scoped filter)
|
||||
- Focus paths use absolute paths or clear relative paths from project root
|
||||
- Cross-module dependencies use CROSS:: placeholder format
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- Task JSONs saved to .task/ with IMPL-${module.prefix}* naming
|
||||
- All task JSONs include cli_execution.id and cli_execution strategy
|
||||
- Cross-module dependencies use CROSS:: placeholder format consistently
|
||||
- Focus paths scoped to ${module.paths.join(', ')} only
|
||||
- Return: task count, task IDs, dependency summary (internal + cross-module)
|
||||
|
||||
## PLANNING NOTES RECORD (REQUIRED)
|
||||
After completing, append to planning-notes.md:
|
||||
|
||||
\`\`\`markdown
|
||||
### [${module.name}] YYYY-MM-DD
|
||||
- **Tasks**: [count] ([IDs])
|
||||
- **CROSS deps**: [placeholders used]
|
||||
\`\`\`
|
||||
`
|
||||
)
|
||||
);
|
||||
|
||||
// Execute all in parallel
|
||||
await Promise.all(planningTasks);
|
||||
```
|
||||
|
||||
**Output Structure** (direct to .task/):
|
||||
```
|
||||
.task/
|
||||
├── IMPL-A1.json # Module A (e.g., frontend)
|
||||
├── IMPL-A2.json
|
||||
├── IMPL-B1.json # Module B (e.g., backend)
|
||||
├── IMPL-B2.json
|
||||
└── IMPL-C1.json # Module C (e.g., shared)
|
||||
```
|
||||
|
||||
**Task ID Naming**:
|
||||
- Format: `IMPL-{prefix}{seq}.json`
|
||||
- Prefix: A, B, C... (assigned by detection order)
|
||||
- Sequence: 1, 2, 3... (per-module increment)
|
||||
|
||||
### Phase 3: Integration (+1 Coordinator Agent, Multi-Module Only)
|
||||
|
||||
**Condition**: Only executed when `modules.length >= 2`
|
||||
|
||||
**Purpose**: Collect all module tasks, resolve cross-module dependencies, generate unified IMPL_PLAN.md and TODO_LIST.md documents.
|
||||
|
||||
**Coordinator Agent Invocation**:
|
||||
```javascript
|
||||
// Wait for all Phase 2B agents to complete
|
||||
const moduleResults = await Promise.all(planningTasks);
|
||||
|
||||
// Launch +1 Coordinator Agent
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Integrate module tasks and generate unified documents",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Integrate all module task JSONs, resolve cross-module dependencies, and generate unified IMPL_PLAN.md and TODO_LIST.md
|
||||
|
||||
IMPORTANT: This is INTEGRATION ONLY - consolidate existing task JSONs, NOT creating new tasks.
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
- Task JSONs: .workflow/active/{session-id}/.task/IMPL-*.json (from Phase 2B)
|
||||
Output:
|
||||
- Updated Task JSONs: .workflow/active/{session-id}/.task/IMPL-*.json (resolved dependencies)
|
||||
- IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
|
||||
- TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
Modules: ${modules.map(m => m.name + '(' + m.prefix + ')').join(', ')}
|
||||
Module Count: ${modules.length}
|
||||
|
||||
## INTEGRATION STEPS
|
||||
1. Collect all .task/IMPL-*.json, group by module prefix
|
||||
2. Resolve CROSS:: dependencies → actual task IDs, update task JSONs
|
||||
3. Generate IMPL_PLAN.md (multi-module format per agent specification)
|
||||
4. Generate TODO_LIST.md (hierarchical format per agent specification)
|
||||
|
||||
## CROSS-MODULE DEPENDENCY RESOLUTION
|
||||
- Pattern: CROSS::{module}::{pattern} → IMPL-{module}* matching title/context
|
||||
- Example: CROSS::B::api-endpoint → IMPL-B1 (if B1 title contains "api-endpoint")
|
||||
- Log unresolved as warnings
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
1. Updated Task JSONs with resolved dependency IDs
|
||||
2. IMPL_PLAN.md - multi-module format with cross-dependency section
|
||||
3. TODO_LIST.md - hierarchical by module with cross-dependency section
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- No CROSS:: placeholders remaining in task JSONs
|
||||
- IMPL_PLAN.md and TODO_LIST.md generated with multi-module structure
|
||||
- Return: task count, per-module breakdown, resolved dependency count
|
||||
|
||||
## PLANNING NOTES RECORD (REQUIRED)
|
||||
After integration, update planning-notes.md:
|
||||
|
||||
\`\`\`markdown
|
||||
### [Coordinator] YYYY-MM-DD
|
||||
- **Total**: [count] tasks
|
||||
- **Resolved**: [CROSS:: resolutions]
|
||||
|
||||
## N+1 Context
|
||||
### Decisions
|
||||
| Decision | Rationale | Revisit? |
|
||||
|----------|-----------|----------|
|
||||
| CROSS::X → IMPL-Y | [why this resolution] | [Yes/No] |
|
||||
|
||||
### Deferred
|
||||
- [ ] [unresolved CROSS or conflict] - [reason]
|
||||
\`\`\`
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Dependency Resolution Algorithm**:
|
||||
```javascript
|
||||
function resolveCrossModuleDependency(placeholder, allTasks) {
|
||||
const [, targetModule, pattern] = placeholder.match(/CROSS::(\w+)::(.+)/);
|
||||
const candidates = allTasks.filter(t =>
|
||||
t.id.startsWith(`IMPL-${targetModule}`) &&
|
||||
(t.title.toLowerCase().includes(pattern.toLowerCase()) ||
|
||||
t.description?.toLowerCase().includes(pattern.toLowerCase()))
|
||||
);
|
||||
return candidates.length > 0
|
||||
? candidates.sort((a, b) => a.id.localeCompare(b.id))[0].id
|
||||
: placeholder; // Keep for manual resolution
|
||||
}
|
||||
```
|
||||
@@ -1,758 +0,0 @@
|
||||
---
|
||||
name: task-generate-tdd
|
||||
description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
|
||||
argument-hint: "[-y|--yes] --session WFS-session-id"
|
||||
examples:
|
||||
- /workflow:tools:task-generate-tdd --session WFS-auth
|
||||
- /workflow:tools:task-generate-tdd -y --session WFS-auth
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor).
|
||||
|
||||
# Autonomous TDD Task Generation Command
|
||||
|
||||
## Overview
|
||||
Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Generates complete Red-Green-Refactor cycles contained within each task.
|
||||
|
||||
## Core Philosophy
|
||||
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
|
||||
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
|
||||
- **Memory-First**: Reuse loaded documents from conversation memory
|
||||
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
|
||||
- **Semantic CLI Selection**: CLI tool usage determined from user's task description, not flags
|
||||
- **Agent Simplicity**: Agent generates content with semantic CLI detection
|
||||
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
- **TDD-First**: Every feature starts with a failing test (Red phase)
|
||||
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
|
||||
- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations
|
||||
|
||||
## Task Strategy & Philosophy
|
||||
|
||||
### Optimized Task Structure (Current)
|
||||
- **1 feature = 1 task** containing complete TDD cycle internally
|
||||
- Each task executes Red-Green-Refactor phases sequentially
|
||||
- Task count = Feature count (typically 5 features = 5 tasks)
|
||||
|
||||
**Previous Approach** (Deprecated):
|
||||
- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
|
||||
- 5 features = 15 tasks with complex dependency chains
|
||||
- High context switching cost between phases
|
||||
|
||||
### When to Use Subtasks
|
||||
- Feature complexity >2500 lines or >6 files per TDD cycle
|
||||
- Multiple independent sub-features needing parallel execution
|
||||
- Strong technical dependency blocking (e.g., API before UI)
|
||||
- Different tech stacks or domains within feature
|
||||
|
||||
### Task Limits
|
||||
- **Maximum 18 tasks** (hard limit for TDD workflows)
|
||||
- **Feature-based**: Complete functional units with internal TDD cycles
|
||||
- **Hierarchy**: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features)
|
||||
- **Re-scope**: If >18 tasks needed, break project into multiple TDD workflow sessions
|
||||
|
||||
### TDD Cycle Mapping
|
||||
- **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
|
||||
- **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
|
||||
- **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
├─ Parse flags: --session
|
||||
└─ 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 (semantic CLI detection)
|
||||
├─ 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 0: User Configuration (Interactive)
|
||||
|
||||
**Purpose**: Collect user preferences before TDD task generation to ensure generated tasks match execution expectations and provide necessary supplementary context.
|
||||
|
||||
**User Questions**:
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Do you have supplementary materials or guidelines to include?",
|
||||
header: "Materials",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "No additional materials", description: "Use existing context only" },
|
||||
{ label: "Provide file paths", description: "I'll specify paths to include" },
|
||||
{ label: "Provide inline content", description: "I'll paste content directly" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "Select execution method for generated TDD tasks:",
|
||||
header: "Execution",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Agent (Recommended)", description: "Claude agent executes Red-Green-Refactor cycles directly" },
|
||||
{ label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps (Red/Green phases)" },
|
||||
{ label: "CLI Only", description: "All TDD cycles via CLI tools (codex/gemini/qwen)" }
|
||||
]
|
||||
},
|
||||
{
|
||||
question: "If using CLI, which tool do you prefer?",
|
||||
header: "CLI Tool",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Codex (Recommended)", description: "Best for TDD Red-Green-Refactor cycles" },
|
||||
{ label: "Gemini", description: "Best for analysis and large context" },
|
||||
{ label: "Qwen", description: "Alternative analysis tool" },
|
||||
{ label: "Auto", description: "Let agent decide per-task" }
|
||||
]
|
||||
}
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
**Handle Materials Response**:
|
||||
```javascript
|
||||
if (userConfig.materials === "Provide file paths") {
|
||||
// Follow-up question for file paths
|
||||
const pathsResponse = AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Enter file paths to include (comma-separated or one per line):",
|
||||
header: "Paths",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Enter paths", description: "Provide paths in text input" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
|
||||
}
|
||||
```
|
||||
|
||||
**Build userConfig**:
|
||||
```javascript
|
||||
const userConfig = {
|
||||
supplementaryMaterials: {
|
||||
type: "none|paths|inline",
|
||||
content: [...], // Parsed paths or inline content
|
||||
},
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true // Always enable resume for CLI executions
|
||||
}
|
||||
```
|
||||
|
||||
**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2.
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Context Preparation & Discovery
|
||||
|
||||
**Command Responsibility**: Command prepares session paths and metadata, provides to agent for autonomous context loading.
|
||||
|
||||
**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
|
||||
|
||||
**📊 Progressive Loading Strategy**: Load context incrementally due to large analysis.md file sizes:
|
||||
- **Core**: session metadata + context-package.json (always load)
|
||||
- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all role analyses
|
||||
- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context
|
||||
|
||||
**🛤️ Path Clarity Requirement**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
|
||||
|
||||
**Session Path Structure** (Provided by Command to Agent):
|
||||
```
|
||||
.workflow/active/WFS-{session-id}/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── .process/
|
||||
│ ├── context-package.json # Context package with artifact catalog
|
||||
│ ├── test-context-package.json # Test coverage analysis
|
||||
│ └── conflict-resolution.json # Conflict resolution (if exists)
|
||||
├── .task/ # Output: Task JSON files
|
||||
│ ├── IMPL-1.json
|
||||
│ ├── IMPL-2.json
|
||||
│ └── ...
|
||||
├── plan.json # Output: Structured plan overview (TDD variant)
|
||||
├── IMPL_PLAN.md # Output: TDD implementation plan
|
||||
└── TODO_LIST.md # Output: TODO list with TDD phases
|
||||
```
|
||||
|
||||
**Command Preparation**:
|
||||
1. **Assemble Session Paths** for agent prompt:
|
||||
- `session_metadata_path`: `.workflow/active/{session-id}/workflow-session.json`
|
||||
- `context_package_path`: `.workflow/active/{session-id}/.process/context-package.json`
|
||||
- `test_context_package_path`: `.workflow/active/{session-id}/.process/test-context-package.json`
|
||||
- Output directory paths
|
||||
|
||||
2. **Provide Metadata** (simple values):
|
||||
- `session_id`: WFS-{session-id}
|
||||
- `workflow_type`: "tdd"
|
||||
- `mcp_capabilities`: {exa_code, exa_web, code_index}
|
||||
|
||||
3. **Pass userConfig** from Phase 0
|
||||
|
||||
**Agent Context Package** (Agent loads autonomously):
|
||||
```javascript
|
||||
{
|
||||
"session_id": "WFS-[session-id]",
|
||||
"workflow_type": "tdd",
|
||||
|
||||
// Core (ALWAYS load)
|
||||
"session_metadata": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from workflow-session.json
|
||||
},
|
||||
"context_package": {
|
||||
// If in memory: use cached content
|
||||
// Else: Load from context-package.json
|
||||
},
|
||||
|
||||
// Selective (load based on progressive strategy)
|
||||
"brainstorm_artifacts": {
|
||||
// Loaded from context-package.json → brainstorm_artifacts section
|
||||
"synthesis_output": {"path": "...", "exists": true}, // Load if exists (highest priority)
|
||||
"guidance_specification": {"path": "...", "exists": true}, // Load if no synthesis
|
||||
"role_analyses": [ // Load SELECTIVELY based on task relevance
|
||||
{
|
||||
"role": "system-architect",
|
||||
"files": [{"path": "...", "type": "primary|supplementary"}]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
// On-Demand (load if exists)
|
||||
"test_context_package": {
|
||||
// Load from test-context-package.json
|
||||
// Contains existing test patterns and coverage analysis
|
||||
},
|
||||
"conflict_resolution": {
|
||||
// Load from conflict-resolution.json if conflict_risk >= medium
|
||||
// Check context-package.conflict_detection.resolution_file
|
||||
},
|
||||
|
||||
// Capabilities
|
||||
"mcp_capabilities": {
|
||||
"exa_code": true,
|
||||
"exa_web": true,
|
||||
"code_index": true
|
||||
},
|
||||
|
||||
// User configuration from Phase 0
|
||||
"user_config": {
|
||||
// From Phase 0 AskUserQuestion
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Discovery Actions**:
|
||||
1. **Load Session Context** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("workflow-session.json")) {
|
||||
Read(.workflow/active/{session-id}/workflow-session.json)
|
||||
}
|
||||
```
|
||||
|
||||
2. **Load Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("context-package.json")) {
|
||||
Read(.workflow/active/{session-id}/.process/context-package.json)
|
||||
}
|
||||
```
|
||||
|
||||
3. **Load Test Context Package** (if not in memory)
|
||||
```javascript
|
||||
if (!memory.has("test-context-package.json")) {
|
||||
Read(.workflow/active/{session-id}/.process/test-context-package.json)
|
||||
}
|
||||
```
|
||||
|
||||
4. **Extract & Load Role Analyses** (from context-package.json)
|
||||
```javascript
|
||||
// Extract role analysis paths from context package
|
||||
const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
|
||||
.flatMap(role => role.files.map(f => f.path));
|
||||
|
||||
// Load each role analysis file
|
||||
roleAnalysisPaths.forEach(path => Read(path));
|
||||
```
|
||||
|
||||
5. **Load Conflict Resolution** (from conflict-resolution.json, if exists)
|
||||
```javascript
|
||||
// Check for new conflict-resolution.json format
|
||||
if (contextPackage.conflict_detection?.resolution_file) {
|
||||
Read(contextPackage.conflict_detection.resolution_file) // .process/conflict-resolution.json
|
||||
}
|
||||
// Fallback: legacy brainstorm_artifacts path
|
||||
else if (contextPackage.brainstorm_artifacts?.conflict_resolution?.exists) {
|
||||
Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
|
||||
}
|
||||
```
|
||||
|
||||
6. **Code Analysis with Native Tools** (optional - enhance understanding)
|
||||
```bash
|
||||
# Find relevant test files and patterns
|
||||
find . -name "*test*" -type f
|
||||
rg "describe|it\(|test\(" -g "*.ts"
|
||||
```
|
||||
|
||||
7. **MCP External Research** (optional - gather TDD best practices)
|
||||
```javascript
|
||||
// Get external TDD examples and patterns
|
||||
mcp__exa__get_code_context_exa(
|
||||
query="TypeScript TDD best practices Red-Green-Refactor",
|
||||
tokensNum="dynamic"
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 2: Agent Execution (TDD Document Generation)
|
||||
|
||||
**Purpose**: Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - planning only, NOT code implementation.
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
|
||||
|
||||
IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.
|
||||
|
||||
CRITICAL: Follow the progressive loading strategy (load analysis.md files incrementally due to file size):
|
||||
- **Core**: session metadata + context-package.json (always)
|
||||
- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all
|
||||
- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context
|
||||
|
||||
## SESSION PATHS
|
||||
Input:
|
||||
- Session Metadata: .workflow/active/{session-id}/workflow-session.json
|
||||
- Context Package: .workflow/active/{session-id}/.process/context-package.json
|
||||
- Test Context: .workflow/active/{session-id}/.process/test-context-package.json
|
||||
|
||||
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
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {session-id}
|
||||
Workflow Type: TDD
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## USER CONFIGURATION (from Phase 0)
|
||||
Execution Method: ${userConfig.executionMethod} // agent|hybrid|cli
|
||||
Preferred CLI Tool: ${userConfig.preferredCliTool} // codex|gemini|qwen|auto
|
||||
Supplementary Materials: ${userConfig.supplementaryMaterials}
|
||||
|
||||
## EXECUTION METHOD MAPPING
|
||||
Based on userConfig.executionMethod, set task-level meta.execution_config:
|
||||
|
||||
"agent" →
|
||||
meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
|
||||
Agent executes Red-Green-Refactor phases directly
|
||||
|
||||
"cli" →
|
||||
meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
|
||||
Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()
|
||||
|
||||
"hybrid" →
|
||||
Per-task decision: Analyze TDD cycle complexity, set method to "agent" OR "cli" per task
|
||||
- Simple cycles (≤5 test cases, ≤3 files) → method: "agent"
|
||||
- Complex cycles (>5 test cases, >3 files, integration tests) → method: "cli"
|
||||
CLI tool: userConfig.preferredCliTool, enable_resume: true
|
||||
|
||||
IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only.
|
||||
|
||||
## EXPLORATION CONTEXT (from context-package.exploration_results)
|
||||
- Load exploration_results from context-package.json
|
||||
- Use aggregated_insights.critical_files for focus_paths generation
|
||||
- Apply aggregated_insights.constraints to acceptance criteria
|
||||
- Reference aggregated_insights.all_patterns for implementation approach
|
||||
- Use aggregated_insights.all_integration_points for precise modification locations
|
||||
- Use conflict_indicators for risk-aware task sequencing
|
||||
|
||||
## CONFLICT RESOLUTION CONTEXT (if exists)
|
||||
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
|
||||
- If exists, load .process/conflict-resolution.json:
|
||||
- Apply planning_constraints as task constraints (for brainstorm-less workflows)
|
||||
- Reference resolved_conflicts for implementation approach alignment
|
||||
- Handle custom_conflicts with explicit task notes
|
||||
|
||||
## TEST CONTEXT INTEGRATION
|
||||
- Load test-context-package.json for existing test patterns and coverage analysis
|
||||
- Extract test framework configuration (Jest/Pytest/etc.)
|
||||
- Identify existing test conventions and patterns
|
||||
- Map coverage gaps to TDD Red phase test targets
|
||||
|
||||
## TDD DOCUMENT GENERATION TASK
|
||||
|
||||
**Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent.
|
||||
|
||||
### TDD-Specific Requirements Summary
|
||||
|
||||
#### Task Structure Philosophy
|
||||
- **1 feature = 1 task** containing complete TDD cycle internally
|
||||
- Each task executes Red-Green-Refactor phases sequentially
|
||||
- Task count = Feature count (typically 5 features = 5 tasks)
|
||||
- Subtasks only when complexity >2500 lines or >6 files per cycle
|
||||
- **Maximum 18 tasks** (hard limit for TDD workflows)
|
||||
|
||||
#### TDD Cycle Mapping
|
||||
- **Simple features**: IMPL-N with internal Red-Green-Refactor phases
|
||||
- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks)
|
||||
- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage
|
||||
|
||||
#### Required Outputs Summary
|
||||
|
||||
##### 1. TDD Task JSON Files (.task/IMPL-*.json)
|
||||
- **Location**: `.workflow/active/{session-id}/.task/`
|
||||
- **Schema**: Unified flat schema (task-schema.json) with TDD-specific metadata
|
||||
- `meta.tdd_workflow`: true (REQUIRED)
|
||||
- `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
|
||||
- `cli_execution.id`: Unique CLI execution ID (format: `{session_id}-{task_id}`)
|
||||
- `cli_execution`: Strategy object (new|resume|fork|merge_fork)
|
||||
- `tdd_cycles`: Array with quantified test cases and coverage
|
||||
- `focus_paths`: Absolute or clear relative paths (enhanced with exploration critical_files)
|
||||
- `implementation`: Exactly 3 steps with `tdd_phase` field
|
||||
1. Red Phase (`tdd_phase: "red"`): Write failing tests
|
||||
2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
|
||||
3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
|
||||
- `pre_analysis`: Include exploration integration_points analysis
|
||||
- **meta.execution_config**: Set per userConfig.executionMethod (agent/cli/hybrid)
|
||||
- **Details**: See action-planning-agent.md § TDD Task JSON Generation
|
||||
|
||||
##### 2. IMPL_PLAN.md (TDD Variant)
|
||||
- **Location**: `.workflow/active/{session-id}/IMPL_PLAN.md`
|
||||
- **Template**: `~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
|
||||
- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
|
||||
- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
|
||||
- **Context Analysis**: Artifact references and exploration insights
|
||||
- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
|
||||
|
||||
##### 3. TODO_LIST.md
|
||||
- **Location**: `.workflow/active/{session-id}/TODO_LIST.md`
|
||||
- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
|
||||
- **Status**: ▸ (container), [ ] (pending), [x] (completed)
|
||||
- **Links**: Task JSON references and summaries
|
||||
- **Details**: See action-planning-agent.md § TODO List Generation
|
||||
|
||||
### CLI EXECUTION ID REQUIREMENTS (MANDATORY)
|
||||
|
||||
Each task JSON MUST include:
|
||||
- **cli_execution.id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`)
|
||||
- **cli_execution**: Strategy object based on depends_on:
|
||||
- No deps → `{ "strategy": "new" }`
|
||||
- 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
|
||||
- 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
|
||||
- N deps → `{ "strategy": "merge_fork", "resume_from": ["id1", "id2", ...] }`
|
||||
- **Type**: `resume_from: string | string[]` (string for resume/fork, array for merge_fork)
|
||||
|
||||
**CLI Execution Strategy Rules**:
|
||||
1. **new**: Task has no dependencies - starts fresh CLI conversation
|
||||
2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
|
||||
3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
|
||||
4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
|
||||
|
||||
**Execution Command Patterns**:
|
||||
- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
|
||||
- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
|
||||
- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
|
||||
- merge_fork: `ccw cli -p "[prompt]" --resume [resume_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` (resume_from is array)
|
||||
|
||||
### Quantification Requirements (MANDATORY)
|
||||
|
||||
**Core Rules**:
|
||||
1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list
|
||||
2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%")
|
||||
3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts
|
||||
4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts
|
||||
|
||||
**TDD Phase Formats**:
|
||||
- **Red Phase**: "Write N test cases: [test1, test2, ...]"
|
||||
- **Green Phase**: "Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"
|
||||
- **Refactor Phase**: "Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"
|
||||
- **Acceptance**: "All N tests pass with >=X% coverage: verify by [test command]"
|
||||
|
||||
**Validation Checklist**:
|
||||
- [ ] Every Red phase specifies exact test case count with enumerated list
|
||||
- [ ] Every Green phase enumerates files, functions, and estimated line counts
|
||||
- [ ] Every Refactor phase lists specific improvements with counts
|
||||
- [ ] Every acceptance criterion includes measurable coverage percentage
|
||||
- [ ] tdd_cycles array contains test_count and test_cases for each cycle
|
||||
- [ ] No vague language ("comprehensive", "complete", "thorough")
|
||||
- [ ] cli_execution.id and cli_execution strategy assigned to each task
|
||||
|
||||
### Agent Execution Summary
|
||||
|
||||
**Key Steps** (Detailed instructions in action-planning-agent.md):
|
||||
1. Load task JSON template from provided path
|
||||
2. Extract and decompose features with TDD cycles
|
||||
3. Generate TDD task JSON files enforcing quantification requirements
|
||||
4. Create IMPL_PLAN.md using TDD template variant
|
||||
5. Generate TODO_LIST.md with TDD phase indicators
|
||||
6. Update session state with TDD metadata
|
||||
|
||||
**Quality Gates** (Full checklist in action-planning-agent.md):
|
||||
- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
|
||||
- ✓ Task count ≤18 (hard limit)
|
||||
- ✓ Each task has meta.tdd_workflow: true
|
||||
- ✓ Each task has exactly 3 implementation steps with tdd_phase field ("red", "green", "refactor")
|
||||
- ✓ Each task has cli_execution.id and cli_execution strategy
|
||||
- ✓ Green phase includes test-fix cycle logic with max_iterations
|
||||
- ✓ focus_paths are absolute or clear relative paths (from exploration critical_files)
|
||||
- ✓ Artifact references mapped correctly from context package
|
||||
- ✓ Exploration context integrated (critical_files, constraints, patterns, integration_points)
|
||||
- ✓ Conflict resolution context applied (if conflict_risk >= medium)
|
||||
- ✓ Test context integrated (existing test patterns and coverage analysis)
|
||||
- ✓ Documents follow TDD template structure
|
||||
- ✓ CLI tool selection based on userConfig.executionMethod
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- All planning documents generated successfully:
|
||||
- Task JSONs valid and saved to .task/ directory with cli_execution.id
|
||||
- IMPL_PLAN.md created with complete TDD structure
|
||||
- TODO_LIST.md generated matching task JSONs
|
||||
- CLI execution strategies assigned based on task dependencies
|
||||
- Return completion status with document count and task breakdown summary
|
||||
|
||||
## OUTPUT SUMMARY
|
||||
Generate all three documents and report:
|
||||
- TDD task JSON files created: N files (IMPL-*.json) with cli_execution.id assigned
|
||||
- TDD cycles configured: N cycles with quantified test cases
|
||||
- CLI execution strategies: new/resume/fork/merge_fork assigned per dependency graph
|
||||
- Artifacts integrated: synthesis-spec/guidance-specification, relevant role analyses
|
||||
- Exploration context: critical_files, constraints, patterns, integration_points
|
||||
- Test context integrated: existing patterns and coverage
|
||||
- Conflict resolution: applied (if conflict_risk >= medium)
|
||||
- Session ready for TDD execution: /workflow:execute
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Agent Context Passing
|
||||
|
||||
**Context Delegation Model**: Command provides paths and metadata, agent loads context autonomously using progressive loading strategy.
|
||||
|
||||
**Command Provides** (in agent prompt):
|
||||
```javascript
|
||||
// Command assembles these simple values and paths for agent
|
||||
const commandProvides = {
|
||||
// Session paths
|
||||
session_metadata_path: ".workflow/active/WFS-{id}/workflow-session.json",
|
||||
context_package_path: ".workflow/active/WFS-{id}/.process/context-package.json",
|
||||
test_context_package_path: ".workflow/active/WFS-{id}/.process/test-context-package.json",
|
||||
output_task_dir: ".workflow/active/WFS-{id}/.task/",
|
||||
output_impl_plan: ".workflow/active/WFS-{id}/IMPL_PLAN.md",
|
||||
output_todo_list: ".workflow/active/WFS-{id}/TODO_LIST.md",
|
||||
|
||||
// Simple metadata
|
||||
session_id: "WFS-{id}",
|
||||
workflow_type: "tdd",
|
||||
mcp_capabilities: { exa_code: true, exa_web: true, code_index: true },
|
||||
|
||||
// User configuration from Phase 0
|
||||
user_config: {
|
||||
supplementaryMaterials: { type: "...", content: [...] },
|
||||
executionMethod: "agent|hybrid|cli",
|
||||
preferredCliTool: "codex|gemini|qwen|auto",
|
||||
enableResume: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Agent Loads Autonomously** (progressive loading):
|
||||
```javascript
|
||||
// Agent executes progressive loading based on memory state
|
||||
const agentLoads = {
|
||||
// Core (ALWAYS load if not in memory)
|
||||
session_metadata: loadIfNotInMemory(session_metadata_path),
|
||||
context_package: loadIfNotInMemory(context_package_path),
|
||||
|
||||
// Selective (based on progressive strategy)
|
||||
// Priority: synthesis_output > guidance + relevant_role_analyses
|
||||
brainstorm_content: loadSelectiveBrainstormArtifacts(context_package),
|
||||
|
||||
// On-Demand (load if exists and relevant)
|
||||
test_context: loadIfExists(test_context_package_path),
|
||||
conflict_resolution: loadConflictResolution(context_package),
|
||||
|
||||
// Optional (if MCP available)
|
||||
exploration_results: extractExplorationResults(context_package),
|
||||
external_research: executeMcpResearch() // If needed
|
||||
}
|
||||
```
|
||||
|
||||
**Progressive Loading Implementation** (agent responsibility):
|
||||
1. **Check memory first** - skip if already loaded
|
||||
2. **Load core files** - session metadata + context-package.json
|
||||
3. **Smart selective loading** - synthesis_output OR (guidance + task-relevant role analyses)
|
||||
4. **On-demand loading** - test context, conflict resolution (if conflict_risk >= medium)
|
||||
5. **Extract references** - exploration results, artifact paths from context package
|
||||
|
||||
## TDD Task Structure Reference
|
||||
|
||||
This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
|
||||
|
||||
**Quick Reference**:
|
||||
- Each TDD task contains complete Red-Green-Refactor cycle
|
||||
- Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks)
|
||||
- Required metadata:
|
||||
- `meta.tdd_workflow: true`
|
||||
- `meta.max_iterations: 3`
|
||||
- `cli_execution.id: "{session_id}-{task_id}"`
|
||||
- `cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
|
||||
- `tdd_cycles` array with quantified test cases and coverage:
|
||||
```javascript
|
||||
tdd_cycles: [
|
||||
{
|
||||
test_count: 5, // Number of test cases to write
|
||||
test_cases: ["case1", "case2"], // Enumerated test scenarios
|
||||
implementation_scope: "...", // Files and functions to implement
|
||||
expected_coverage: ">=85%" // Coverage target
|
||||
}
|
||||
]
|
||||
```
|
||||
- `focus_paths` use absolute or clear relative paths
|
||||
- `implementation`: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor")
|
||||
- `pre_analysis`: includes exploration integration_points analysis
|
||||
- **meta.execution_config**: Set per `userConfig.executionMethod` (agent/cli/hybrid)
|
||||
- See Phase 2 agent prompt for full schema and requirements
|
||||
|
||||
## Output Files Structure
|
||||
```
|
||||
.workflow/active/{session-id}/
|
||||
├── plan.json # Structured plan overview (TDD variant)
|
||||
├── IMPL_PLAN.md # Unified plan with TDD Implementation Tasks section
|
||||
├── TODO_LIST.md # Progress tracking with internal TDD phase indicators
|
||||
├── .task/
|
||||
│ ├── IMPL-1.json # Complete TDD task (Red-Green-Refactor internally)
|
||||
│ ├── IMPL-2.json # Complete TDD task
|
||||
│ ├── IMPL-3.json # Complex feature container (if needed)
|
||||
│ ├── IMPL-3.1.json # Complex feature subtask (if needed)
|
||||
│ ├── IMPL-3.2.json # Complex feature subtask (if needed)
|
||||
│ └── ...
|
||||
└── .process/
|
||||
├── conflict-resolution.json # Conflict resolution results (if conflict_risk ≥ medium)
|
||||
├── test-context-package.json # Test coverage analysis
|
||||
├── context-package.json # Input from context-gather
|
||||
├── context_package_path # Path to smart context package
|
||||
└── green-fix-iteration-*.md # Fix logs from Green phase test-fix cycles
|
||||
```
|
||||
|
||||
**File Count**:
|
||||
- **Old approach**: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5)
|
||||
- **New approach**: 5 features = 5 task JSON files (IMPL-N × 5)
|
||||
- **Complex feature**: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M)
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Task Completeness
|
||||
- Every IMPL-N must contain complete TDD workflow in `implementation`
|
||||
- Each task must have 3 steps with `tdd_phase`: "red", "green", "refactor"
|
||||
- Every task must have `meta.tdd_workflow: true`
|
||||
|
||||
### Dependency Enforcement
|
||||
- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
|
||||
- Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies
|
||||
- No circular dependencies allowed
|
||||
|
||||
### Task Limits
|
||||
- Maximum 18 total tasks (simple + subtasks) - hard limit for TDD workflows
|
||||
- Flat hierarchy (≤5 tasks) or two-level (6-18 tasks with containers)
|
||||
- Re-scope requirements if >18 tasks needed
|
||||
|
||||
### TDD Workflow Validation
|
||||
- `meta.tdd_workflow` must be true
|
||||
- `implementation` must have exactly 3 steps
|
||||
- Each step must have `tdd_phase` field ("red", "green", or "refactor")
|
||||
- Green phase step must include test-fix cycle logic
|
||||
- `meta.max_iterations` must be present (default: 3)
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Input Validation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Session not found | Invalid session ID | Verify session exists |
|
||||
| Context missing | Incomplete planning | Run context-gather first |
|
||||
|
||||
### TDD Generation Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Task count exceeds 18 | Too many features or subtasks | Re-scope requirements or merge features into multiple TDD sessions |
|
||||
| Missing test framework | No test config | Configure testing first |
|
||||
| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
|
||||
| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
**Command Chain**:
|
||||
- Called by: `/workflow:tdd-plan` (Phase 4)
|
||||
- Invokes: `action-planning-agent` for autonomous task generation
|
||||
- Followed by: `/workflow:execute`, `/workflow:tdd-verify`
|
||||
|
||||
**Basic Usage**:
|
||||
```bash
|
||||
# Standard execution
|
||||
/workflow:tools:task-generate-tdd --session WFS-auth
|
||||
|
||||
# With semantic CLI request (include in task description)
|
||||
# e.g., "Generate TDD tasks for auth module, use Codex for implementation"
|
||||
```
|
||||
|
||||
**CLI Tool Selection**: Determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
|
||||
|
||||
**Output**:
|
||||
- TDD task JSON files in `.task/` directory (IMPL-N.json format)
|
||||
- IMPL_PLAN.md with TDD Implementation Tasks section
|
||||
- TODO_LIST.md with internal TDD phase indicators
|
||||
- Session state updated with task count and TDD metadata
|
||||
- MCP enhancements integrated (if available)
|
||||
|
||||
## Test Coverage Analysis Integration
|
||||
|
||||
The TDD workflow includes test coverage analysis (via `/workflow:tools:test-context-gather`) to:
|
||||
- Detect existing test patterns and conventions
|
||||
- Identify current test coverage gaps
|
||||
- Discover test framework and configuration
|
||||
- Enable integration with existing tests
|
||||
|
||||
This makes TDD workflow context-aware instead of assuming greenfield scenarios.
|
||||
|
||||
## Iterative Green Phase with Test-Fix Cycle
|
||||
|
||||
IMPL (Green phase) tasks include automatic test-fix cycle:
|
||||
|
||||
**Process Flow**:
|
||||
1. **Initial Implementation**: Write minimal code to pass tests
|
||||
2. **Test Execution**: Run test suite
|
||||
3. **Success Path**: Tests pass → Complete task
|
||||
4. **Failure Path**: Tests fail → Enter iterative fix cycle:
|
||||
- **Gemini Diagnosis**: Analyze failures with bug-fix template
|
||||
- **Fix Application**: Agent executes fixes directly
|
||||
- **Retest**: Verify fix resolves failures
|
||||
- **Repeat**: Up to max_iterations (default: 3)
|
||||
5. **Safety Net**: Auto-revert all changes if max iterations reached
|
||||
|
||||
|
||||
|
||||
## Configuration Options
|
||||
- **meta.max_iterations**: Number of fix attempts in Green phase (default: 3)
|
||||
- **meta.execution_config.method**: Execution routing (agent/cli) determined from userConfig.executionMethod
|
||||
|
||||
@@ -1,309 +0,0 @@
|
||||
---
|
||||
name: tdd-coverage-analysis
|
||||
description: Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification
|
||||
argument-hint: "--session WFS-session-id"
|
||||
allowed-tools: Read(*), Write(*), Bash(*)
|
||||
---
|
||||
|
||||
# TDD Coverage Analysis Command
|
||||
|
||||
## Overview
|
||||
Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD workflow validation.
|
||||
|
||||
## Core Responsibilities
|
||||
- Extract test files from TEST tasks
|
||||
- Run test suite with coverage
|
||||
- Parse coverage metrics
|
||||
- Verify TDD cycle execution (Red -> Green -> Refactor)
|
||||
- Generate coverage and cycle reports
|
||||
|
||||
## Execution 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
|
||||
```bash
|
||||
find .workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
|
||||
```
|
||||
|
||||
**Output**: List of test directories/files from all TEST tasks
|
||||
|
||||
### Phase 2: Run Test Suite
|
||||
```bash
|
||||
# Node.js/JavaScript
|
||||
npm test -- --coverage --json > .workflow/active/{session_id}/.process/test-results.json
|
||||
|
||||
# Python
|
||||
pytest --cov --json-report > .workflow/active/{session_id}/.process/test-results.json
|
||||
|
||||
# Other frameworks (detect from project)
|
||||
[test_command] --coverage --json-output .workflow/active/{session_id}/.process/test-results.json
|
||||
```
|
||||
|
||||
**Output**: test-results.json with coverage data
|
||||
|
||||
### Phase 3: Parse Coverage Data
|
||||
```bash
|
||||
jq '.coverage' .workflow/active/{session_id}/.process/test-results.json > .workflow/active/{session_id}/.process/coverage-report.json
|
||||
```
|
||||
|
||||
**Extract**:
|
||||
- Line coverage percentage
|
||||
- Branch coverage percentage
|
||||
- Function coverage percentage
|
||||
- Uncovered lines/branches
|
||||
|
||||
### Phase 4: Verify TDD Cycle
|
||||
|
||||
For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M):
|
||||
|
||||
**1. Red Phase Verification**
|
||||
```bash
|
||||
# Check TEST task summary
|
||||
cat .workflow/active/{session_id}/.summaries/TEST-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Tests were created
|
||||
- Tests failed initially
|
||||
- Failure messages were clear
|
||||
|
||||
**2. Green Phase Verification**
|
||||
```bash
|
||||
# Check IMPL task summary
|
||||
cat .workflow/active/{session_id}/.summaries/IMPL-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Implementation was completed
|
||||
- Tests now pass
|
||||
- Implementation was minimal
|
||||
|
||||
**3. Refactor Phase Verification**
|
||||
```bash
|
||||
# Check REFACTOR task summary
|
||||
cat .workflow/active/{session_id}/.summaries/REFACTOR-N.M-summary.md
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Refactoring was completed
|
||||
- Tests still pass
|
||||
- Code quality improved
|
||||
|
||||
### Phase 5: Generate Analysis Report
|
||||
|
||||
Create `.workflow/active/{session_id}/.process/tdd-cycle-report.md`:
|
||||
|
||||
```markdown
|
||||
# TDD Cycle Analysis - {Session ID}
|
||||
|
||||
## Coverage Metrics
|
||||
- **Line Coverage**: {percentage}%
|
||||
- **Branch Coverage**: {percentage}%
|
||||
- **Function Coverage**: {percentage}%
|
||||
|
||||
## Coverage Details
|
||||
### Covered
|
||||
- {covered_lines} lines
|
||||
- {covered_branches} branches
|
||||
- {covered_functions} functions
|
||||
|
||||
### Uncovered
|
||||
- Lines: {uncovered_line_numbers}
|
||||
- Branches: {uncovered_branch_locations}
|
||||
|
||||
## TDD Cycle Verification
|
||||
|
||||
### Feature 1: {Feature Name}
|
||||
**Chain**: TEST-1.1 -> IMPL-1.1 -> REFACTOR-1.1
|
||||
|
||||
- [PASS] **Red Phase**: Tests created and failed initially
|
||||
- [PASS] **Green Phase**: Implementation made tests pass
|
||||
- [PASS] **Refactor Phase**: Refactoring maintained green tests
|
||||
|
||||
### Feature 2: {Feature Name}
|
||||
**Chain**: TEST-2.1 -> IMPL-2.1 -> REFACTOR-2.1
|
||||
|
||||
- [PASS] **Red Phase**: Tests created and failed initially
|
||||
- [WARN] **Green Phase**: Tests pass but implementation seems over-engineered
|
||||
- [PASS] **Refactor Phase**: Refactoring maintained green tests
|
||||
|
||||
[Repeat for all features]
|
||||
|
||||
## TDD Compliance Summary
|
||||
- **Total Chains**: {N}
|
||||
- **Complete Cycles**: {N}
|
||||
- **Incomplete Cycles**: {0}
|
||||
- **Compliance Score**: {score}/100
|
||||
|
||||
## Gaps Identified
|
||||
- Feature 3: Missing initial test failure verification
|
||||
- Feature 5: No refactoring step completed
|
||||
|
||||
## Recommendations
|
||||
- Complete missing refactoring steps
|
||||
- Add edge case tests for Feature 2
|
||||
- Verify test failure messages are descriptive
|
||||
```
|
||||
|
||||
## Output Files
|
||||
```
|
||||
.workflow/active//{session-id}/
|
||||
└── .process/
|
||||
├── test-results.json # Raw test execution results
|
||||
├── coverage-report.json # Parsed coverage data
|
||||
└── tdd-cycle-report.md # TDD cycle analysis
|
||||
```
|
||||
|
||||
## Test Framework Detection
|
||||
|
||||
Auto-detect test framework from project:
|
||||
|
||||
```bash
|
||||
# Check for test frameworks
|
||||
if [ -f "package.json" ] && grep -q "jest\|mocha\|vitest" package.json; then
|
||||
TEST_CMD="npm test -- --coverage --json"
|
||||
elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
|
||||
TEST_CMD="pytest --cov --json-report"
|
||||
elif [ -f "Cargo.toml" ]; then
|
||||
TEST_CMD="cargo test -- --test-threads=1 --nocapture"
|
||||
elif [ -f "go.mod" ]; then
|
||||
TEST_CMD="go test -coverprofile=coverage.out -json ./..."
|
||||
else
|
||||
TEST_CMD="echo 'No supported test framework found'"
|
||||
fi
|
||||
```
|
||||
|
||||
## TDD Cycle Verification Algorithm
|
||||
|
||||
```
|
||||
For each feature N:
|
||||
1. Load TEST-N.M-summary.md
|
||||
IF summary missing:
|
||||
Mark: "Red phase incomplete"
|
||||
SKIP to next feature
|
||||
|
||||
CHECK: Contains "test" AND "fail"
|
||||
IF NOT found:
|
||||
Mark: "Red phase verification failed"
|
||||
ELSE:
|
||||
Mark: "Red phase [PASS]"
|
||||
|
||||
2. Load IMPL-N.M-summary.md
|
||||
IF summary missing:
|
||||
Mark: "Green phase incomplete"
|
||||
SKIP to next feature
|
||||
|
||||
CHECK: Contains "pass" OR "green"
|
||||
IF NOT found:
|
||||
Mark: "Green phase verification failed"
|
||||
ELSE:
|
||||
Mark: "Green phase [PASS]"
|
||||
|
||||
3. Load REFACTOR-N.M-summary.md
|
||||
IF summary missing:
|
||||
Mark: "Refactor phase incomplete"
|
||||
CONTINUE (refactor is optional)
|
||||
|
||||
CHECK: Contains "refactor" AND "pass"
|
||||
IF NOT found:
|
||||
Mark: "Refactor phase verification failed"
|
||||
ELSE:
|
||||
Mark: "Refactor phase [PASS]"
|
||||
|
||||
4. Calculate chain score:
|
||||
- Red + Green + Refactor all [PASS] = 100%
|
||||
- Red + Green [PASS], Refactor missing = 80%
|
||||
- Red [PASS], Green missing = 40%
|
||||
- All missing = 0%
|
||||
```
|
||||
|
||||
## Coverage Metrics Calculation
|
||||
|
||||
```bash
|
||||
# Parse coverage from test-results.json
|
||||
line_coverage=$(jq '.coverage.lineCoverage' test-results.json)
|
||||
branch_coverage=$(jq '.coverage.branchCoverage' test-results.json)
|
||||
function_coverage=$(jq '.coverage.functionCoverage' test-results.json)
|
||||
|
||||
# Calculate overall score
|
||||
overall_score=$(echo "($line_coverage + $branch_coverage + $function_coverage) / 3" | bc)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Test Execution Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Test framework not found | No test config | Configure test framework first |
|
||||
| Tests fail to run | Syntax errors | Fix code before analysis |
|
||||
| Coverage not available | Missing coverage tool | Install coverage plugin |
|
||||
|
||||
### Cycle Verification Errors
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Summary missing | Task not executed | Execute tasks before analysis |
|
||||
| Invalid summary format | Corrupted file | Re-run task to regenerate |
|
||||
| No test evidence | Tests not committed | Ensure tests are committed |
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:tdd-verify` (Phase 3)
|
||||
- **Calls**: Test framework commands (npm test, pytest, etc.)
|
||||
- **Followed By**: Compliance report generation
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
/workflow:tools:tdd-coverage-analysis --session WFS-auth
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
```
|
||||
TDD Coverage Analysis complete for session: WFS-auth
|
||||
|
||||
## Coverage Results
|
||||
Line Coverage: 87%
|
||||
Branch Coverage: 82%
|
||||
Function Coverage: 91%
|
||||
|
||||
## TDD Cycle Verification
|
||||
[PASS] Feature 1: Complete (Red -> Green -> Refactor)
|
||||
[PASS] Feature 2: Complete (Red -> Green -> Refactor)
|
||||
[WARN] Feature 3: Incomplete (Red -> Green, missing Refactor)
|
||||
|
||||
Overall Compliance: 93/100
|
||||
|
||||
Detailed report: .workflow/active/WFS-auth/.process/tdd-cycle-report.md
|
||||
```
|
||||
|
||||
@@ -1,164 +0,0 @@
|
||||
---
|
||||
name: test-concept-enhanced
|
||||
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
|
||||
---
|
||||
|
||||
# Test Concept Enhanced Command
|
||||
|
||||
## Overview
|
||||
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
|
||||
- **Pattern-Based**: Learn from existing tests and project conventions
|
||||
- **Gemini-Powered**: Use Gemini for test requirement analysis and strategy design
|
||||
- **Single-Round Analysis**: Comprehensive test analysis in one execution
|
||||
- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution
|
||||
|
||||
## Core Responsibilities
|
||||
- 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: Context Preparation (Command Responsibility)
|
||||
|
||||
**Command prepares session context and validates prerequisites.**
|
||||
|
||||
1. **Session Validation**
|
||||
- Load `.workflow/active/{test_session_id}/workflow-session.json`
|
||||
- Verify test session type is "test-gen"
|
||||
- Extract source session reference
|
||||
|
||||
2. **Context Package Validation**
|
||||
- Read `test-context-package.json`
|
||||
- Validate required sections: metadata, source_context, test_coverage, test_framework
|
||||
- Extract coverage gaps and framework details
|
||||
|
||||
3. **Strategy Determination**
|
||||
- **Simple** (1-3 files): Single Gemini analysis
|
||||
- **Medium** (4-6 files): Comprehensive analysis
|
||||
- **Complex** (>6 files): Modular analysis approach
|
||||
|
||||
### Phase 2: Test Analysis Execution (Agent Responsibility)
|
||||
|
||||
**Purpose**: Analyze test coverage gaps and generate comprehensive test strategy.
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-execution-agent",
|
||||
run_in_background=false,
|
||||
description="Analyze test coverage gaps and generate test strategy",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Analyze test requirements and generate comprehensive test generation strategy using Gemini CLI
|
||||
|
||||
## EXECUTION CONTEXT
|
||||
Session: {test_session_id}
|
||||
Source Session: {source_session_id}
|
||||
Working Dir: .workflow/active/{test_session_id}/.process
|
||||
Template: ~/.ccw/workflows/cli-templates/prompts/test/test-concept-analysis.txt
|
||||
|
||||
## EXECUTION STEPS
|
||||
1. Execute Gemini analysis:
|
||||
ccw cli -p "..." --tool gemini --mode write --rule test-test-concept-analysis --cd .workflow/active/{test_session_id}/.process
|
||||
|
||||
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
|
||||
|
||||
## EXPECTED OUTPUTS
|
||||
1. gemini-test-analysis.md - Raw Gemini analysis
|
||||
2. TEST_ANALYSIS_RESULTS.md - Standardized test requirements document
|
||||
|
||||
## 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 Files**:
|
||||
- `.workflow/active/{test_session_id}/.process/gemini-test-analysis.md`
|
||||
- `.workflow/active/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
|
||||
|
||||
### Phase 3: Output Validation (Command Responsibility)
|
||||
|
||||
**Command validates agent outputs.**
|
||||
|
||||
- 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 | 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 |
|
||||
|
||||
### 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**: Generate basic TEST_ANALYSIS_RESULTS.md from context package if Gemini fails
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### 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`
|
||||
|
||||
### Performance
|
||||
- Focused analysis: Only analyze files with missing tests
|
||||
- Pattern reuse: Study existing tests for quick extraction
|
||||
- Timeout: 20-minute limit for analysis
|
||||
|
||||
### 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
|
||||
|
||||
@@ -1,235 +0,0 @@
|
||||
---
|
||||
name: test-context-gather
|
||||
description: Collect test coverage context using test-context-search-agent and package into standardized test-context JSON
|
||||
argument-hint: "--session WFS-test-session-id"
|
||||
examples:
|
||||
- /workflow:tools:test-context-gather --session WFS-test-auth
|
||||
- /workflow:tools:test-context-gather --session WFS-test-payment
|
||||
allowed-tools: Task(*), Read(*), Glob(*)
|
||||
---
|
||||
|
||||
# Test Context Gather Command (/workflow:tools:test-context-gather)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
|
||||
|
||||
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution
|
||||
- **Detection-First**: Check for existing test-context-package before executing
|
||||
- **Coverage-First**: Analyze existing test coverage before planning new tests
|
||||
- **Source Context Loading**: Import implementation summaries from source session
|
||||
- **Standardized Output**: Generate `.workflow/active/{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
|
||||
|
||||
**Execute First** - Check if valid package already exists:
|
||||
|
||||
```javascript
|
||||
const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
|
||||
|
||||
if (file_exists(testContextPath)) {
|
||||
const existing = Read(testContextPath);
|
||||
|
||||
// Validate package belongs to current test session
|
||||
if (existing?.metadata?.test_session_id === test_session_id) {
|
||||
console.log("✅ Valid test-context-package found for session:", test_session_id);
|
||||
console.log("📊 Coverage Stats:", existing.test_coverage.coverage_stats);
|
||||
console.log("🧪 Framework:", existing.test_framework.framework);
|
||||
console.log("⚠️ Missing Tests:", existing.test_coverage.missing_tests.length);
|
||||
return existing; // Skip execution, return existing
|
||||
} else {
|
||||
console.warn("⚠️ Invalid test_session_id in existing package, re-generating...");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Invoke Test-Context-Search Agent
|
||||
|
||||
**Only execute if Step 1 finds no valid package**
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="test-context-search-agent",
|
||||
run_in_background=false,
|
||||
description="Gather test coverage context",
|
||||
prompt=`
|
||||
|
||||
## Execution Mode
|
||||
**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
|
||||
|
||||
## Session Information
|
||||
- **Test Session ID**: ${test_session_id}
|
||||
- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json
|
||||
|
||||
## Mission
|
||||
Execute complete test-context-search-agent workflow for test generation planning:
|
||||
|
||||
### Phase 1: Session Validation & Source Context Loading
|
||||
1. **Detection**: Check for existing test-context-package (early exit if valid)
|
||||
2. **Test Session Validation**: Load test session metadata, extract source_session reference
|
||||
3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack
|
||||
|
||||
### Phase 2: Test Coverage Analysis
|
||||
Execute coverage discovery:
|
||||
- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files)
|
||||
- **Track 2**: Coverage gap analysis (match implementation files to test files)
|
||||
- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module)
|
||||
|
||||
### Phase 3: Framework Detection & Packaging
|
||||
1. Framework identification from package.json/requirements.txt
|
||||
2. Convention analysis from existing test patterns
|
||||
3. Generate and validate test-context-package.json
|
||||
|
||||
## Output Requirements
|
||||
Complete test-context-package.json with:
|
||||
- **metadata**: test_session_id, source_session_id, task_type, complexity
|
||||
- **source_context**: implementation_summaries, tech_stack, project_patterns
|
||||
- **test_coverage**: existing_tests[], missing_tests[], coverage_stats
|
||||
- **test_framework**: framework, version, test_pattern, conventions
|
||||
- **assets**: implementation_summary[], existing_test[], source_code[] with priorities
|
||||
- **focus_areas**: Test generation guidance based on coverage gaps
|
||||
|
||||
## Quality Validation
|
||||
Before completion verify:
|
||||
- [ ] Valid JSON format with all required fields
|
||||
- [ ] Source session context loaded successfully
|
||||
- [ ] Test coverage gaps identified
|
||||
- [ ] Test framework detected (or marked as 'unknown')
|
||||
- [ ] Coverage percentage calculated correctly
|
||||
- [ ] Missing tests catalogued with priority
|
||||
- [ ] Execution time < 30 seconds (< 60s for large codebases)
|
||||
|
||||
Execute autonomously following agent documentation.
|
||||
Report completion with coverage statistics.
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
### Step 3: Output Verification
|
||||
|
||||
After agent completes, verify output:
|
||||
|
||||
```javascript
|
||||
// Verify file was created
|
||||
const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
|
||||
if (!file_exists(outputPath)) {
|
||||
throw new Error("❌ Agent failed to generate test-context-package.json");
|
||||
}
|
||||
|
||||
// Load and display summary
|
||||
const testContext = Read(outputPath);
|
||||
console.log("✅ Test context package generated successfully");
|
||||
console.log("📊 Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%");
|
||||
console.log("⚠️ Tests to generate:", testContext.test_coverage.missing_tests.length);
|
||||
```
|
||||
|
||||
## Parameter Reference
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) |
|
||||
|
||||
## Output Schema
|
||||
|
||||
Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema.
|
||||
|
||||
**Key Sections**:
|
||||
- **metadata**: Test session info, source session reference, complexity
|
||||
- **source_context**: Implementation summaries with changed files and tech stack
|
||||
- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics
|
||||
- **test_framework**: Framework name, version, patterns, conventions
|
||||
- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code)
|
||||
- **focus_areas**: Test generation guidance based on analysis
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage
|
||||
```bash
|
||||
/workflow:tools:test-context-gather --session WFS-test-auth
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
```
|
||||
✅ Valid test-context-package found for session: WFS-test-auth
|
||||
📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 }
|
||||
🧪 Framework: jest
|
||||
⚠️ Missing Tests: 1
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Valid test-context-package.json generated in `.workflow/active/{test_session_id}/.process/`
|
||||
- ✅ Source session context loaded successfully
|
||||
- ✅ Test coverage gaps identified (>90% accuracy)
|
||||
- ✅ Test framework detected and documented
|
||||
- ✅ Execution completes within 30 seconds (60s for large codebases)
|
||||
- ✅ All required schema fields present and valid
|
||||
- ✅ Coverage statistics calculated correctly
|
||||
- ✅ Agent reports completion with statistics
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Resolution |
|
||||
|-------|-------|------------|
|
||||
| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate |
|
||||
| Source session not found | Invalid source_session reference | Verify test session metadata |
|
||||
| No implementation summaries | Source session incomplete | Complete source session first |
|
||||
| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access |
|
||||
| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
|
||||
| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed |
|
||||
|
||||
## Integration
|
||||
|
||||
### Called By
|
||||
- `/workflow:test-gen` (Phase 3: Context Gathering)
|
||||
|
||||
### Calls
|
||||
- `test-context-search-agent` - Autonomous test coverage analysis
|
||||
|
||||
### Followed By
|
||||
- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning
|
||||
|
||||
## Notes
|
||||
|
||||
- **Detection-first**: Always check for existing test-context-package before invoking agent
|
||||
|
||||
- **No redundancy**: This command is a thin orchestrator, all logic in agent
|
||||
- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
|
||||
- **Coverage focus**: Primary goal is identifying implementation files without tests
|
||||
|
||||
@@ -1,416 +0,0 @@
|
||||
---
|
||||
name: test-task-generate
|
||||
description: Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) by invoking test-action-planning-agent
|
||||
argument-hint: "--session WFS-test-session-id"
|
||||
examples:
|
||||
- /workflow:tools:test-task-generate --session WFS-test-auth
|
||||
---
|
||||
|
||||
# Generate Test Planning Documents Command
|
||||
|
||||
## Overview
|
||||
|
||||
Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) by invoking **test-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).
|
||||
|
||||
### Agent Specialization
|
||||
|
||||
This command invokes `@test-action-planning-agent` - a specialized variant of action-planning-agent with:
|
||||
- Progressive L0-L3 test layers (Static, Unit, Integration, E2E)
|
||||
- AI code issue detection (L0.5) with severity levels
|
||||
- Project type templates (React, Node API, CLI, Library, Monorepo)
|
||||
- Test anti-pattern detection with quality gates
|
||||
- Layer completeness thresholds and coverage targets
|
||||
|
||||
**See**: `d:\Claude_dms3\.claude\agents\test-action-planning-agent.md` for complete test specifications.
|
||||
|
||||
---
|
||||
|
||||
## Execution Process
|
||||
|
||||
```
|
||||
Input Parsing:
|
||||
└─ Parse flags: --session
|
||||
|
||||
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, source_session_id)
|
||||
└─ Create test-planning-notes.md (User Intent section)
|
||||
|
||||
Phase 1.5: Gemini Test Enhancement (Command)
|
||||
├─ Invoke cli-execution-agent for Gemini analysis
|
||||
├─ Read TEST_ANALYSIS_RESULTS.md for context
|
||||
├─ Generate enriched test suggestions (API, integration, error scenarios)
|
||||
└─ Record enriched suggestions to test-planning-notes.md (Gemini Enhancement section)
|
||||
|
||||
Phase 2: Test Document Generation (Agent)
|
||||
├─ Load TEST_ANALYSIS_RESULTS.md (with enriched suggestions)
|
||||
├─ Load test-planning-notes.md (consolidated context)
|
||||
├─ Generate Test Task JSON Files (.task/IMPL-*.json)
|
||||
│ ├─ IMPL-001: Test generation (L1-L3 layers, project-specific templates)
|
||||
│ ├─ IMPL-001.3: Code validation gate (L0 + AI issue detection)
|
||||
│ ├─ IMPL-001.5: Test quality gate (anti-patterns + coverage)
|
||||
│ └─ IMPL-002: Test execution & fix cycle
|
||||
├─ Create IMPL_PLAN.md (test_session variant)
|
||||
├─ Generate TODO_LIST.md with test phase indicators
|
||||
└─ Update test-planning-notes.md (Task Generation section)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Context Preparation
|
||||
|
||||
**Purpose**: Assemble test session paths, load test analysis context, and create test-planning-notes.md.
|
||||
|
||||
**Execution Steps**:
|
||||
1. Parse `--session` flag to get test session ID
|
||||
2. Load `workflow-session.json` for session metadata
|
||||
3. Verify `TEST_ANALYSIS_RESULTS.md` exists (from test-concept-enhanced)
|
||||
4. Load `test-context-package.json` for coverage data
|
||||
5. Create `test-planning-notes.md` with initial context
|
||||
|
||||
**After Phase 1**: Initialize test-planning-notes.md
|
||||
|
||||
```javascript
|
||||
// Create test-planning-notes.md with N+1 context support
|
||||
const testPlanningNotesPath = `.workflow/active/${testSessionId}/test-planning-notes.md`
|
||||
const sessionMetadata = JSON.parse(Read(`.workflow/active/${testSessionId}/workflow-session.json`))
|
||||
const testAnalysis = Read(`.workflow/active/${testSessionId}/.process/TEST_ANALYSIS_RESULTS.md`)
|
||||
const sourceSessionId = sessionMetadata.source_session_id || 'N/A'
|
||||
|
||||
// Extract key info from TEST_ANALYSIS_RESULTS.md
|
||||
const projectType = testAnalysis.match(/Project Type:\s*(.+)/)?.[1] || 'Unknown'
|
||||
const testFramework = testAnalysis.match(/Test Framework:\s*(.+)/)?.[1] || 'Unknown'
|
||||
const coverageTarget = testAnalysis.match(/Coverage Target:\s*(.+)/)?.[1] || '80%'
|
||||
|
||||
Write(testPlanningNotesPath, `# Test Planning Notes
|
||||
|
||||
**Session**: ${testSessionId}
|
||||
**Source Session**: ${sourceSessionId}
|
||||
**Created**: ${new Date().toISOString()}
|
||||
|
||||
## Test Intent (Phase 1)
|
||||
|
||||
- **PROJECT_TYPE**: ${projectType}
|
||||
- **TEST_FRAMEWORK**: ${testFramework}
|
||||
- **COVERAGE_TARGET**: ${coverageTarget}
|
||||
- **SOURCE_SESSION**: ${sourceSessionId}
|
||||
|
||||
---
|
||||
|
||||
## Context Findings (Phase 1)
|
||||
|
||||
### Files with Coverage Gaps
|
||||
(Extracted from TEST_ANALYSIS_RESULTS.md)
|
||||
|
||||
### Test Framework & Conventions
|
||||
- Framework: ${testFramework}
|
||||
- Coverage Target: ${coverageTarget}
|
||||
|
||||
---
|
||||
|
||||
## Gemini Enhancement (Phase 1.5)
|
||||
(To be filled by Gemini analysis)
|
||||
|
||||
### Enhanced Test Suggestions
|
||||
- **L1 (Unit)**: (Pending)
|
||||
- **L2.1 (Integration)**: (Pending)
|
||||
- **L2.2 (API Contracts)**: (Pending)
|
||||
- **L2.4 (External APIs)**: (Pending)
|
||||
- **L2.5 (Failure Modes)**: (Pending)
|
||||
|
||||
### Gemini Analysis Summary
|
||||
(Pending enrichment)
|
||||
|
||||
---
|
||||
|
||||
## Consolidated Test Requirements (Phase 2 Input)
|
||||
1. [Context] ${testFramework} framework conventions
|
||||
2. [Context] ${coverageTarget} coverage target
|
||||
|
||||
---
|
||||
|
||||
## Task Generation (Phase 2)
|
||||
(To be filled by test-action-planning-agent)
|
||||
|
||||
## N+1 Context
|
||||
### Decisions
|
||||
| Decision | Rationale | Revisit? |
|
||||
|----------|-----------|----------|
|
||||
|
||||
### Deferred
|
||||
- [ ] (For N+1)
|
||||
`)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1.5: Gemini Test Enhancement
|
||||
|
||||
**Purpose**: Enrich test specifications with comprehensive test suggestions and record to test-planning-notes.md.
|
||||
|
||||
**Execution Steps**:
|
||||
1. Load TEST_ANALYSIS_RESULTS.md from `.workflow/active/{test-session-id}/.process/`
|
||||
2. Invoke `cli-execution-agent` with Gemini for test enhancement analysis
|
||||
3. Use template: `~/.ccw/workflows/cli-templates/prompts/test-suggestions-enhancement.txt`
|
||||
4. Gemini generates enriched test suggestions across L1-L3 layers → gemini-enriched-suggestions.md
|
||||
5. Record enriched suggestions to test-planning-notes.md (Gemini Enhancement section)
|
||||
|
||||
**Agent Invocation**:
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="cli-execution-agent",
|
||||
run_in_background=false,
|
||||
description="Enhance test specifications with Gemini analysis",
|
||||
prompt=`
|
||||
## Task Objective
|
||||
Analyze TEST_ANALYSIS_RESULTS.md and generate enriched test suggestions using Gemini CLI
|
||||
|
||||
## Input Files
|
||||
- Read: .workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md
|
||||
- Extract: Project type, test framework, coverage gaps, identified files
|
||||
|
||||
## Gemini Analysis Execution
|
||||
Execute Gemini with comprehensive test enhancement prompt:
|
||||
ccw cli -p "[comprehensive test prompt]" --tool gemini --mode analysis --rule analysis-test-strategy-enhancement --cd .workflow/active/{test-session-id}/.process
|
||||
|
||||
## Expected Output
|
||||
Generate gemini-enriched-suggestions.md with structured test enhancements:
|
||||
- L1 (Unit Tests): Edge cases, boundaries, error paths
|
||||
- L2.1 (Integration): Module interactions, dependency injection
|
||||
- L2.2 (API Contracts): Request/response, validation, error responses
|
||||
- L2.4 (External APIs): Mock strategies, failure scenarios, timeouts
|
||||
- L2.5 (Failure Modes): Exception handling, error propagation, recovery
|
||||
|
||||
## Validation
|
||||
- gemini-enriched-suggestions.md created and complete
|
||||
- Suggestions are actionable and specific (not generic)
|
||||
- All L1-L3 layers covered
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
**Output**: gemini-enriched-suggestions.md (complete Gemini analysis)
|
||||
|
||||
**After Phase 1.5**: Update test-planning-notes.md with Gemini enhancement findings
|
||||
|
||||
```javascript
|
||||
// Read enriched suggestions from gemini-enriched-suggestions.md
|
||||
const enrichedSuggestionsPath = `.workflow/active/${testSessionId}/.process/gemini-enriched-suggestions.md`
|
||||
const enrichedSuggestions = Read(enrichedSuggestionsPath)
|
||||
|
||||
// Update Phase 1.5 section in test-planning-notes.md with full enriched suggestions
|
||||
Edit(testPlanningNotesPath, {
|
||||
old: '## Gemini Enhancement (Phase 1.5)\n(To be filled by Gemini analysis)\n\n### Enhanced Test Suggestions\n- **L1 (Unit)**: (Pending)\n- **L2.1 (Integration)**: (Pending)\n- **L2.2 (API Contracts)**: (Pending)\n- **L2.4 (External APIs)**: (Pending)\n- **L2.5 (Failure Modes)**: (Pending)\n\n### Gemini Analysis Summary\n(Pending enrichment)',
|
||||
new: `## Gemini Enhancement (Phase 1.5)
|
||||
|
||||
**Analysis Timestamp**: ${new Date().toISOString()}
|
||||
**Template**: test-suggestions-enhancement.txt
|
||||
**Output File**: .process/gemini-enriched-suggestions.md
|
||||
|
||||
### Enriched Test Suggestions (Complete Gemini Analysis)
|
||||
|
||||
${enrichedSuggestions}
|
||||
|
||||
### Gemini Analysis Summary
|
||||
- **Status**: Enrichment complete
|
||||
- **Layers Covered**: L1, L2.1, L2.2, L2.4, L2.5
|
||||
- **Focus Areas**: API contracts, integration patterns, error scenarios, edge cases
|
||||
- **Output Stored**: Full analysis in gemini-enriched-suggestions.md`
|
||||
})
|
||||
|
||||
// Append Gemini constraints to consolidated test requirements
|
||||
const geminiConstraints = [
|
||||
'[Gemini] Implement all suggested L1 edge cases and boundary tests',
|
||||
'[Gemini] Apply L2.1 module interaction patterns from analysis',
|
||||
'[Gemini] Follow L2.2 API contract test matrix from analysis',
|
||||
'[Gemini] Use L2.4 external API mock strategies from analysis',
|
||||
'[Gemini] Cover L2.5 error scenarios from analysis'
|
||||
]
|
||||
|
||||
const currentNotes = Read(testPlanningNotesPath)
|
||||
const constraintCount = (currentNotes.match(/^\d+\./gm) || []).length
|
||||
|
||||
Edit(testPlanningNotesPath, {
|
||||
old: '## Consolidated Test Requirements (Phase 2 Input)',
|
||||
new: `## Consolidated Test Requirements (Phase 2 Input)
|
||||
1. [Context] ${testFramework} framework conventions
|
||||
2. [Context] ${coverageTarget} coverage target
|
||||
${geminiConstraints.map((c, i) => `${i + 3}. ${c}`).join('\n')}`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Invocation
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="test-action-planning-agent",
|
||||
run_in_background=false,
|
||||
description="Generate test planning documents",
|
||||
prompt=`
|
||||
## TASK OBJECTIVE
|
||||
Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for test workflow session
|
||||
|
||||
IMPORTANT: This is TEST PLANNING ONLY - you are generating planning documents, NOT executing tests.
|
||||
|
||||
## 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)
|
||||
- Test Planning Notes: .workflow/active/{test-session-id}/test-planning-notes.md (REQUIRED - contains Gemini enhancement findings)
|
||||
- Test Context Package: .workflow/active/{test-session-id}/.process/test-context-package.json
|
||||
- Context Package: .workflow/active/{test-session-id}/.process/context-package.json
|
||||
- Enriched Suggestions: .workflow/active/{test-session-id}/.process/gemini-enriched-suggestions.md (for reference)
|
||||
- Source Session Summaries: .workflow/active/{source-session-id}/.summaries/IMPL-*.md (if exists)
|
||||
|
||||
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
|
||||
|
||||
## CONTEXT METADATA
|
||||
Session ID: {test-session-id}
|
||||
Workflow Type: test_session
|
||||
Source Session: {source-session-id} (if exists)
|
||||
MCP Capabilities: {exa_code, exa_web, code_index}
|
||||
|
||||
## CONSOLIDATED CONTEXT
|
||||
**From test-planning-notes.md**:
|
||||
- Test Intent: Project type, test framework, coverage target
|
||||
- Context Findings: Coverage gaps, file analysis
|
||||
- Gemini Enhancement: Complete enriched test suggestions (L1-L3 layers)
|
||||
* Full analysis embedded in planning-notes.md
|
||||
* API contracts, integration patterns, error scenarios
|
||||
- Consolidated Requirements: Combined constraints from all phases
|
||||
|
||||
## YOUR SPECIFICATIONS
|
||||
You are @test-action-planning-agent. Your complete test specifications are defined in:
|
||||
d:\Claude_dms3\.claude\agents\test-action-planning-agent.md
|
||||
|
||||
This includes:
|
||||
- Progressive Test Layers (L0-L3) with L0.1-L0.5, L1.1-L1.5, L2.1-L2.5, L3.1-L3.4
|
||||
- AI Code Issue Detection (L0.5) with 7 categories and severity levels
|
||||
- Project Type Detection & Templates (6 project types)
|
||||
- Test Anti-Pattern Detection (5 categories)
|
||||
- Layer Completeness & Quality Metrics (thresholds and gate decisions)
|
||||
- Task JSON structure requirements (minimum 4 tasks)
|
||||
- Quality validation rules
|
||||
|
||||
**Follow your specification exactly** when generating test task JSONs.
|
||||
|
||||
## EXPECTED DELIVERABLES
|
||||
1. Test Task JSON Files (.task/IMPL-*.json) - Minimum 4:
|
||||
- IMPL-001.json: Test generation (L1-L3 layers per spec)
|
||||
- IMPL-001.3-validation.json: Code validation gate (L0 + AI issues per spec)
|
||||
- IMPL-001.5-review.json: Test quality gate (anti-patterns + coverage per spec)
|
||||
- IMPL-002.json: Test execution & fix cycle
|
||||
|
||||
2. IMPL_PLAN.md: Test implementation plan with quality gates
|
||||
|
||||
3. TODO_LIST.md: Hierarchical task list with test phase indicators
|
||||
|
||||
## SUCCESS CRITERIA
|
||||
- All test planning documents generated successfully
|
||||
- Task count: minimum 4 (expandable for complex projects)
|
||||
- Test framework: {detected from project}
|
||||
- Coverage targets: L0 zero errors, L1 80%+, L2 70%+
|
||||
- L0-L3 layers explicitly defined per spec
|
||||
- AI issue detection configured per spec
|
||||
- Quality gates with measurable thresholds
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test-Specific Execution Modes
|
||||
|
||||
### Test Generation (IMPL-001)
|
||||
- **Agent Mode** (default): @code-developer generates tests within agent context
|
||||
- **CLI Mode**: Use CLI tools when `command` field present in implementation_approach
|
||||
|
||||
### Test Execution & Fix (IMPL-002+)
|
||||
- **Agent Mode** (default): Gemini diagnosis → agent applies fixes
|
||||
- **CLI Mode**: Gemini diagnosis → CLI applies fixes (when `command` field present)
|
||||
|
||||
**CLI Tool Selection**: Determined semantically from user's task description (e.g., "use Codex for fixes")
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
.workflow/active/WFS-test-[session]/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── IMPL_PLAN.md # Test implementation plan
|
||||
├── TODO_LIST.md # Task checklist
|
||||
├── test-planning-notes.md # [NEW] Consolidated planning notes with full Gemini analysis
|
||||
├── .task/
|
||||
│ ├── IMPL-001.json # Test generation (L1-L3)
|
||||
│ ├── IMPL-001.3-validation.json # Code validation gate (L0 + AI)
|
||||
│ ├── IMPL-001.5-review.json # Test quality gate
|
||||
│ └── IMPL-002.json # Test execution & fix cycle
|
||||
└── .process/
|
||||
├── test-context-package.json # Test coverage and patterns
|
||||
├── gemini-enriched-suggestions.md # [NEW] Gemini-generated test enhancements
|
||||
└── TEST_ANALYSIS_RESULTS.md # L0-L3 requirements (original from test-concept-enhanced)
|
||||
```
|
||||
|
||||
### Task Summary
|
||||
|
||||
| Task | Type | Agent | Purpose |
|
||||
|------|------|-------|---------|
|
||||
| IMPL-001 | test-gen | @code-developer | Generate L1-L3 tests with project templates |
|
||||
| IMPL-001.3 | code-validation | @test-fix-agent | Validate L0 + detect AI issues (CRITICAL/ERROR/WARNING) |
|
||||
| IMPL-001.5 | test-quality-review | @test-fix-agent | Check anti-patterns, layer completeness, coverage |
|
||||
| IMPL-002 | test-fix | @test-fix-agent | Execute tests, diagnose failures, apply fixes |
|
||||
|
||||
---
|
||||
|
||||
## Integration & Usage
|
||||
|
||||
### Command Chain
|
||||
- **Called By**: `/workflow:test-fix-gen` (Phase 4)
|
||||
- **Invokes**: `@test-action-planning-agent` for test planning document generation
|
||||
- **Followed By**: `/workflow:test-cycle-execute` or `/workflow:execute` (user-triggered)
|
||||
|
||||
### Usage Examples
|
||||
```bash
|
||||
# Standard execution
|
||||
/workflow:tools:test-task-generate --session WFS-test-auth
|
||||
|
||||
# With semantic CLI request (include in task description when calling /workflow:test-fix-gen)
|
||||
# e.g., "Generate tests, use Codex for implementation and fixes"
|
||||
```
|
||||
|
||||
### Output Validation
|
||||
|
||||
**Minimum Requirements**:
|
||||
- 4 task JSON files created
|
||||
- IMPL_PLAN.md exists with test-specific sections
|
||||
- TODO_LIST.md exists with test phase hierarchy
|
||||
- All tasks reference TEST_ANALYSIS_RESULTS.md specifications
|
||||
- L0-L3 layers explicitly defined in IMPL-001
|
||||
- AI issue detection configured in IMPL-001.3
|
||||
- Quality gates with thresholds in IMPL-001.5
|
||||
|
||||
---
|
||||
|
||||
## Related Commands
|
||||
|
||||
**Called By**:
|
||||
- `/workflow:test-fix-gen` - Phase 4: Generate test planning documents
|
||||
|
||||
**Prerequisite**:
|
||||
- `/workflow:tools:test-concept-enhanced` - Must generate TEST_ANALYSIS_RESULTS.md first
|
||||
|
||||
**Follow-Up**:
|
||||
- `/workflow:test-cycle-execute` - Execute generated test tasks
|
||||
- `/workflow:execute` - Alternative: Standard task execution
|
||||
@@ -3,7 +3,7 @@
|
||||
// ========================================
|
||||
// Manages allotment-based split panes for CLI viewer
|
||||
|
||||
import { useCallback, useMemo } from 'react';
|
||||
import { useCallback, useMemo, useRef, useEffect } from 'react';
|
||||
import { Allotment } from 'allotment';
|
||||
import 'allotment/dist/style.css';
|
||||
import { cn } from '@/lib/utils';
|
||||
@@ -105,14 +105,46 @@ function LayoutGroupRenderer({ group, minSize, onSizeChange }: LayoutGroupRender
|
||||
export function LayoutContainer({ className }: LayoutContainerProps) {
|
||||
const layout = useViewerLayout();
|
||||
const panes = useViewerPanes();
|
||||
const setLayout = useViewerStore((state) => state.setLayout);
|
||||
|
||||
// Use ref to track if we're currently updating to prevent infinite loops
|
||||
const isUpdatingRef = useRef(false);
|
||||
// Track previous sizes to avoid unnecessary updates
|
||||
const prevSizesRef = useRef<number[] | undefined>(layout.sizes);
|
||||
|
||||
// Update prevSizesRef when layout.sizes changes from external sources
|
||||
useEffect(() => {
|
||||
if (!isUpdatingRef.current) {
|
||||
prevSizesRef.current = layout.sizes;
|
||||
}
|
||||
}, [layout.sizes]);
|
||||
|
||||
// Stable callback with no dependencies - prevents Allotment onChange infinite loop
|
||||
const handleSizeChange = useCallback(
|
||||
(sizes: number[]) => {
|
||||
// Update the root layout with new sizes
|
||||
setLayout({ ...layout, sizes });
|
||||
// Skip if sizes haven't actually changed (compare by value)
|
||||
if (
|
||||
prevSizesRef.current &&
|
||||
sizes.length === prevSizesRef.current.length &&
|
||||
sizes.every((s, i) => Math.abs(s - prevSizesRef.current![i]) < 0.1)
|
||||
) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Use functional update to avoid dependency on layout
|
||||
isUpdatingRef.current = true;
|
||||
prevSizesRef.current = sizes;
|
||||
|
||||
useViewerStore.getState().setLayout((prev) => ({
|
||||
...prev,
|
||||
sizes,
|
||||
}));
|
||||
|
||||
// Reset updating flag after a microtask
|
||||
queueMicrotask(() => {
|
||||
isUpdatingRef.current = false;
|
||||
});
|
||||
},
|
||||
[layout, setLayout]
|
||||
[] // No dependencies - uses getState() and refs to prevent infinite loops
|
||||
);
|
||||
|
||||
// Render based on layout type
|
||||
|
||||
@@ -53,10 +53,10 @@ export function FloatingPanel({
|
||||
{/* Backdrop */}
|
||||
<div
|
||||
className={cn(
|
||||
'fixed inset-0 z-40 transition-opacity duration-200',
|
||||
'fixed z-40 transition-opacity duration-200',
|
||||
isOpen ? 'opacity-100 pointer-events-auto' : 'opacity-0 pointer-events-none'
|
||||
)}
|
||||
style={{ top: '40px' }} // Below toolbar
|
||||
style={{ top: '40px', bottom: 0, left: 0, right: 0 }}
|
||||
onClick={handleBackdropClick}
|
||||
>
|
||||
<div className="absolute inset-0 bg-black/20" />
|
||||
@@ -76,7 +76,7 @@ export function FloatingPanel({
|
||||
)}
|
||||
style={{
|
||||
top: '40px', // Below toolbar
|
||||
height: 'calc(100vh - 56px - 40px)', // Subtract both app header and toolbar
|
||||
height: 'calc(100vh - 40px)', // Full height below toolbar
|
||||
width: `${width}px`,
|
||||
}}
|
||||
>
|
||||
|
||||
@@ -73,7 +73,7 @@ export interface ViewerState {
|
||||
nextTabIdCounter: number;
|
||||
|
||||
// Actions
|
||||
setLayout: (newLayout: AllotmentLayout) => void;
|
||||
setLayout: (newLayout: AllotmentLayout | ((prev: AllotmentLayout) => AllotmentLayout)) => void;
|
||||
addPane: (parentPaneId?: PaneId, direction?: 'horizontal' | 'vertical') => PaneId;
|
||||
removePane: (paneId: PaneId) => void;
|
||||
addTab: (paneId: PaneId, executionId: CliExecutionId, title: string) => TabId;
|
||||
@@ -373,8 +373,14 @@ export const useViewerStore = create<ViewerState>()(
|
||||
|
||||
// ========== Layout Actions ==========
|
||||
|
||||
setLayout: (newLayout: AllotmentLayout) => {
|
||||
setLayout: (newLayout: AllotmentLayout | ((prev: AllotmentLayout) => AllotmentLayout)) => {
|
||||
if (typeof newLayout === 'function') {
|
||||
const currentLayout = get().layout;
|
||||
const result = newLayout(currentLayout);
|
||||
set({ layout: result }, false, 'viewer/setLayout');
|
||||
} else {
|
||||
set({ layout: newLayout }, false, 'viewer/setLayout');
|
||||
}
|
||||
},
|
||||
|
||||
addPane: (parentPaneId?: PaneId, direction: 'horizontal' | 'vertical' = 'horizontal') => {
|
||||
|
||||
Reference in New Issue
Block a user