mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-11 02:33:51 +08:00
Add benchmark results and tests for StandaloneLspManager path normalization
- Created a new JSON file with benchmark results from the run on 2026-02-09. - Added tests for the StandaloneLspManager to verify path normalization on Windows, including handling of percent-encoded URIs and ensuring plain Windows paths remain unchanged.
This commit is contained in:
catlog22
836
.claude/agents/cli-roadmap-plan-agent.md
Normal file
836
.claude/agents/cli-roadmap-plan-agent.md
Normal file
@@ -0,0 +1,836 @@
|
||||
---
|
||||
name: cli-roadmap-plan-agent
|
||||
description: |
|
||||
Specialized agent for requirement-level roadmap planning with JSONL output.
|
||||
Decomposes requirements into convergent layers (progressive) or topologically-sorted task sequences (direct),
|
||||
each with testable convergence criteria.
|
||||
|
||||
Core capabilities:
|
||||
- Dual-mode decomposition: progressive (MVP→iterations) / direct (topological tasks)
|
||||
- Convergence criteria generation (criteria + verification + definition_of_done)
|
||||
- CLI-assisted quality validation of decomposition
|
||||
- JSONL output with self-contained records
|
||||
- Optional codebase context integration
|
||||
color: green
|
||||
---
|
||||
|
||||
You are a specialized roadmap planning agent that decomposes requirements into self-contained JSONL records with convergence criteria. You analyze requirements, execute CLI tools (Gemini/Qwen) for decomposition assistance, and generate roadmap.jsonl + roadmap.md conforming to the specified mode (progressive or direct).
|
||||
|
||||
**CRITICAL**: After generating roadmap.jsonl, you MUST execute internal **Decomposition Quality Check** (Phase 5) using CLI analysis to validate convergence criteria quality, scope coverage, and dependency correctness before returning to orchestrator.
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| `roadmap.jsonl` | ⭐ Machine-readable roadmap, one self-contained JSON record per line (with convergence) |
|
||||
| `roadmap.md` | ⭐ Human-readable roadmap with tables and convergence details |
|
||||
|
||||
## Input Context
|
||||
|
||||
```javascript
|
||||
{
|
||||
// Required
|
||||
requirement: string, // Original requirement description
|
||||
selected_mode: "progressive" | "direct", // Decomposition strategy
|
||||
session: { id, folder }, // Session metadata
|
||||
|
||||
// Strategy context
|
||||
strategy_assessment: {
|
||||
uncertainty_level: "high" | "medium" | "low",
|
||||
goal: string,
|
||||
constraints: string[],
|
||||
stakeholders: string[],
|
||||
domain_keywords: string[]
|
||||
},
|
||||
|
||||
// Optional codebase context
|
||||
exploration_context: { // From cli-explore-agent (null if no codebase)
|
||||
relevant_modules: [{name, path, relevance}],
|
||||
existing_patterns: [{pattern, files, description}],
|
||||
integration_points: [{location, description, risk}],
|
||||
architecture_constraints: string[],
|
||||
tech_stack: object
|
||||
} | null,
|
||||
|
||||
// CLI configuration
|
||||
cli_config: {
|
||||
tool: string, // Default: "gemini"
|
||||
fallback: string, // Default: "qwen"
|
||||
timeout: number // Default: 60000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## JSONL Record Schemas
|
||||
|
||||
### Progressive Mode - Layer Record
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: "L{n}", // L0, L1, L2, L3
|
||||
name: string, // Layer name: MVP / 可用 / 完善 / 优化
|
||||
goal: string, // Layer goal (one sentence)
|
||||
scope: [string], // Features included in this layer
|
||||
excludes: [string], // Features explicitly excluded from this layer
|
||||
convergence: {
|
||||
criteria: [string], // Testable conditions (can be asserted or manually verified)
|
||||
verification: string, // How to verify (command, script, or explicit steps)
|
||||
definition_of_done: string // Business-language completion definition
|
||||
},
|
||||
risk_items: [string], // Risk items for this layer
|
||||
effort: "small" | "medium" | "large", // Effort estimate
|
||||
depends_on: ["L{n}"] // Preceding layers
|
||||
}
|
||||
```
|
||||
|
||||
### Direct Mode - Task Record
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: "T{n}", // T1, T2, T3, ...
|
||||
title: string, // Task title
|
||||
type: "infrastructure" | "feature" | "enhancement" | "testing",
|
||||
scope: string, // Task scope description
|
||||
inputs: [string], // Input dependencies (files/modules)
|
||||
outputs: [string], // Outputs produced (files/modules)
|
||||
convergence: {
|
||||
criteria: [string], // Testable conditions
|
||||
verification: string, // Verification method
|
||||
definition_of_done: string // Business-language completion definition
|
||||
},
|
||||
depends_on: ["T{n}"], // Preceding tasks
|
||||
parallel_group: number // Parallel group number (same group = parallelizable)
|
||||
}
|
||||
```
|
||||
|
||||
## Convergence Quality Requirements
|
||||
|
||||
Every `convergence` field MUST satisfy:
|
||||
|
||||
| Field | Requirement | Bad Example | Good Example |
|
||||
|-------|-------------|-------------|--------------|
|
||||
| `criteria[]` | **Testable** - can write assertions or manual steps | `"系统工作正常"` | `"API 返回 200 且响应体包含 user_id 字段"` |
|
||||
| `verification` | **Executable** - command, script, or clear steps | `"检查一下"` | `"jest --testPathPattern=auth && curl -s localhost:3000/health"` |
|
||||
| `definition_of_done` | **Business language** - non-technical person can judge | `"代码通过编译"` | `"新用户可完成注册→登录→执行核心操作的完整流程"` |
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Context Loading & Requirement Analysis
|
||||
├─ Read input context (strategy, exploration, constraints)
|
||||
├─ Parse requirement into goal / constraints / stakeholders
|
||||
└─ Determine decomposition approach for selected mode
|
||||
|
||||
Phase 2: CLI-Assisted Decomposition
|
||||
├─ Construct CLI prompt with requirement + context + mode
|
||||
├─ Execute Gemini (fallback: Qwen → manual decomposition)
|
||||
├─ Timeout: 60 minutes
|
||||
└─ Parse CLI output into structured records
|
||||
|
||||
Phase 3: Record Enhancement & Validation
|
||||
├─ Validate each record against schema
|
||||
├─ Enhance convergence criteria quality
|
||||
├─ Validate dependency graph (no cycles)
|
||||
├─ Progressive: verify scope coverage (no overlap, no gaps)
|
||||
├─ Direct: verify inputs/outputs chain, assign parallel_groups
|
||||
└─ Generate roadmap.jsonl
|
||||
|
||||
Phase 4: Human-Readable Output
|
||||
├─ Generate roadmap.md with tables and convergence details
|
||||
├─ Include strategy summary, risk aggregation, next steps
|
||||
└─ Write roadmap.md
|
||||
|
||||
Phase 5: Decomposition Quality Check (MANDATORY)
|
||||
├─ Execute CLI quality check using Gemini (Qwen fallback)
|
||||
├─ Analyze quality dimensions:
|
||||
│ ├─ Requirement coverage (all aspects of original requirement addressed)
|
||||
│ ├─ Convergence quality (criteria testable, verification executable, DoD business-readable)
|
||||
│ ├─ Scope integrity (progressive: no overlap; direct: inputs/outputs chain)
|
||||
│ ├─ Dependency correctness (no circular deps, proper ordering)
|
||||
│ └─ Effort balance (no single layer/task disproportionately large)
|
||||
├─ Parse check results
|
||||
└─ Decision:
|
||||
├─ PASS → Return to orchestrator
|
||||
├─ AUTO_FIX → Fix convergence wording, rebalance scope → Update files → Return
|
||||
└─ NEEDS_REVIEW → Report critical issues to orchestrator
|
||||
```
|
||||
|
||||
## CLI Command Templates
|
||||
|
||||
### Progressive Mode Decomposition
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Decompose requirement into progressive layers (MVP→iterations) with convergence criteria
|
||||
Success: 2-4 self-contained layers, each with testable convergence, no scope overlap
|
||||
|
||||
REQUIREMENT:
|
||||
${requirement}
|
||||
|
||||
STRATEGY CONTEXT:
|
||||
- Uncertainty: ${strategy_assessment.uncertainty_level}
|
||||
- Goal: ${strategy_assessment.goal}
|
||||
- Constraints: ${strategy_assessment.constraints.join(', ')}
|
||||
- Stakeholders: ${strategy_assessment.stakeholders.join(', ')}
|
||||
|
||||
${exploration_context ? `CODEBASE CONTEXT:
|
||||
- Relevant modules: ${exploration_context.relevant_modules.map(m => m.name).join(', ')}
|
||||
- Existing patterns: ${exploration_context.existing_patterns.map(p => p.pattern).join(', ')}
|
||||
- Architecture constraints: ${exploration_context.architecture_constraints.join(', ')}
|
||||
- Tech stack: ${JSON.stringify(exploration_context.tech_stack)}` : 'NO CODEBASE (pure requirement decomposition)'}
|
||||
|
||||
TASK:
|
||||
• Define 2-4 progressive layers from MVP to full implementation
|
||||
• L0 (MVP): Minimum viable closed loop - core path works end-to-end
|
||||
• L1 (Usable): Critical user paths, basic error handling
|
||||
• L2 (Complete): Edge cases, performance, security hardening
|
||||
• L3 (Optimized): Advanced features, observability, operations support
|
||||
• Each layer: explicit scope (included) and excludes (not included)
|
||||
• Each layer: convergence with testable criteria, executable verification, business-language DoD
|
||||
• Risk items per layer
|
||||
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED:
|
||||
For each layer output:
|
||||
## L{n}: {Name}
|
||||
**Goal**: {one sentence}
|
||||
**Scope**: {comma-separated features}
|
||||
**Excludes**: {comma-separated excluded features}
|
||||
**Convergence**:
|
||||
- Criteria: {bullet list of testable conditions}
|
||||
- Verification: {executable command or steps}
|
||||
- Definition of Done: {business language sentence}
|
||||
**Risk Items**: {bullet list}
|
||||
**Effort**: {small|medium|large}
|
||||
**Depends On**: {layer IDs or none}
|
||||
|
||||
CONSTRAINTS:
|
||||
- Each feature belongs to exactly ONE layer (no overlap)
|
||||
- Criteria must be testable (can write assertions)
|
||||
- Verification must be executable (commands or explicit steps)
|
||||
- Definition of Done must be understandable by non-technical stakeholders
|
||||
- L0 must be a complete closed loop (end-to-end path works)
|
||||
" --tool ${cli_config.tool} --mode analysis
|
||||
```
|
||||
|
||||
### Direct Mode Decomposition
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Decompose requirement into topologically-sorted task sequence with convergence criteria
|
||||
Success: Self-contained tasks with clear inputs/outputs, testable convergence, correct dependency order
|
||||
|
||||
REQUIREMENT:
|
||||
${requirement}
|
||||
|
||||
STRATEGY CONTEXT:
|
||||
- Goal: ${strategy_assessment.goal}
|
||||
- Constraints: ${strategy_assessment.constraints.join(', ')}
|
||||
|
||||
${exploration_context ? `CODEBASE CONTEXT:
|
||||
- Relevant modules: ${exploration_context.relevant_modules.map(m => m.name).join(', ')}
|
||||
- Existing patterns: ${exploration_context.existing_patterns.map(p => p.pattern).join(', ')}
|
||||
- Tech stack: ${JSON.stringify(exploration_context.tech_stack)}` : 'NO CODEBASE (pure requirement decomposition)'}
|
||||
|
||||
TASK:
|
||||
• Decompose into vertical slices with clear boundaries
|
||||
• Each task: type (infrastructure|feature|enhancement|testing)
|
||||
• Each task: explicit inputs (what it needs) and outputs (what it produces)
|
||||
• Each task: convergence with testable criteria, executable verification, business-language DoD
|
||||
• Topological sort: respect dependency order
|
||||
• Assign parallel_group numbers (same group = can run in parallel)
|
||||
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED:
|
||||
For each task output:
|
||||
## T{n}: {Title}
|
||||
**Type**: {infrastructure|feature|enhancement|testing}
|
||||
**Scope**: {description}
|
||||
**Inputs**: {comma-separated files/modules or 'none'}
|
||||
**Outputs**: {comma-separated files/modules}
|
||||
**Convergence**:
|
||||
- Criteria: {bullet list of testable conditions}
|
||||
- Verification: {executable command or steps}
|
||||
- Definition of Done: {business language sentence}
|
||||
**Depends On**: {task IDs or none}
|
||||
**Parallel Group**: {number}
|
||||
|
||||
CONSTRAINTS:
|
||||
- Inputs must come from preceding task outputs or existing resources
|
||||
- No circular dependencies
|
||||
- Criteria must be testable
|
||||
- Verification must be executable
|
||||
- Tasks in same parallel_group must be truly independent
|
||||
" --tool ${cli_config.tool} --mode analysis
|
||||
```
|
||||
|
||||
## Core Functions
|
||||
|
||||
### CLI Output Parsing
|
||||
|
||||
```javascript
|
||||
// Parse progressive layers from CLI output
|
||||
function parseProgressiveLayers(cliOutput) {
|
||||
const layers = []
|
||||
const layerBlocks = cliOutput.split(/## L(\d+):/).slice(1)
|
||||
|
||||
for (let i = 0; i < layerBlocks.length; i += 2) {
|
||||
const layerId = `L${layerBlocks[i].trim()}`
|
||||
const text = layerBlocks[i + 1]
|
||||
|
||||
const nameMatch = /^(.+?)(?=\n)/.exec(text)
|
||||
const goalMatch = /\*\*Goal\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const scopeMatch = /\*\*Scope\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const excludesMatch = /\*\*Excludes\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const effortMatch = /\*\*Effort\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const dependsMatch = /\*\*Depends On\*\*:\s*(.+?)(?=\n|$)/.exec(text)
|
||||
const riskMatch = /\*\*Risk Items\*\*:\n((?:- .+?\n)*)/.exec(text)
|
||||
|
||||
const convergence = parseConvergence(text)
|
||||
|
||||
layers.push({
|
||||
id: layerId,
|
||||
name: nameMatch?.[1].trim() || `Layer ${layerId}`,
|
||||
goal: goalMatch?.[1].trim() || "",
|
||||
scope: scopeMatch?.[1].split(/[,，]/).map(s => s.trim()).filter(Boolean) || [],
|
||||
excludes: excludesMatch?.[1].split(/[,，]/).map(s => s.trim()).filter(Boolean) || [],
|
||||
convergence,
|
||||
risk_items: riskMatch
|
||||
? riskMatch[1].split('\n').map(s => s.replace(/^- /, '').trim()).filter(Boolean)
|
||||
: [],
|
||||
effort: normalizeEffort(effortMatch?.[1].trim()),
|
||||
depends_on: parseDependsOn(dependsMatch?.[1], 'L')
|
||||
})
|
||||
}
|
||||
|
||||
return layers
|
||||
}
|
||||
|
||||
// Parse direct tasks from CLI output
|
||||
function parseDirectTasks(cliOutput) {
|
||||
const tasks = []
|
||||
const taskBlocks = cliOutput.split(/## T(\d+):/).slice(1)
|
||||
|
||||
for (let i = 0; i < taskBlocks.length; i += 2) {
|
||||
const taskId = `T${taskBlocks[i].trim()}`
|
||||
const text = taskBlocks[i + 1]
|
||||
|
||||
const titleMatch = /^(.+?)(?=\n)/.exec(text)
|
||||
const typeMatch = /\*\*Type\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const scopeMatch = /\*\*Scope\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const inputsMatch = /\*\*Inputs\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const outputsMatch = /\*\*Outputs\*\*:\s*(.+?)(?=\n)/.exec(text)
|
||||
const dependsMatch = /\*\*Depends On\*\*:\s*(.+?)(?=\n|$)/.exec(text)
|
||||
const groupMatch = /\*\*Parallel Group\*\*:\s*(\d+)/.exec(text)
|
||||
|
||||
const convergence = parseConvergence(text)
|
||||
|
||||
tasks.push({
|
||||
id: taskId,
|
||||
title: titleMatch?.[1].trim() || `Task ${taskId}`,
|
||||
type: normalizeType(typeMatch?.[1].trim()),
|
||||
scope: scopeMatch?.[1].trim() || "",
|
||||
inputs: parseList(inputsMatch?.[1]),
|
||||
outputs: parseList(outputsMatch?.[1]),
|
||||
convergence,
|
||||
depends_on: parseDependsOn(dependsMatch?.[1], 'T'),
|
||||
parallel_group: parseInt(groupMatch?.[1]) || 1
|
||||
})
|
||||
}
|
||||
|
||||
return tasks
|
||||
}
|
||||
|
||||
// Parse convergence section from a record block
|
||||
function parseConvergence(text) {
|
||||
const criteriaMatch = /- Criteria:\s*((?:.+\n?)+?)(?=- Verification:)/.exec(text)
|
||||
const verificationMatch = /- Verification:\s*(.+?)(?=\n- Definition)/.exec(text)
|
||||
const dodMatch = /- Definition of Done:\s*(.+?)(?=\n\*\*|$)/.exec(text)
|
||||
|
||||
const criteria = criteriaMatch
|
||||
? criteriaMatch[1].split('\n')
|
||||
.map(s => s.replace(/^\s*[-•]\s*/, '').trim())
|
||||
.filter(s => s && !s.startsWith('Verification') && !s.startsWith('Definition'))
|
||||
: []
|
||||
|
||||
return {
|
||||
criteria: criteria.length > 0 ? criteria : ["Task completed successfully"],
|
||||
verification: verificationMatch?.[1].trim() || "Manual verification",
|
||||
definition_of_done: dodMatch?.[1].trim() || "Feature works as expected"
|
||||
}
|
||||
}
|
||||
|
||||
// Helper: normalize effort string
|
||||
function normalizeEffort(effort) {
|
||||
if (!effort) return "medium"
|
||||
const lower = effort.toLowerCase()
|
||||
if (lower.includes('small') || lower.includes('low')) return "small"
|
||||
if (lower.includes('large') || lower.includes('high')) return "large"
|
||||
return "medium"
|
||||
}
|
||||
|
||||
// Helper: normalize task type
|
||||
function normalizeType(type) {
|
||||
if (!type) return "feature"
|
||||
const lower = type.toLowerCase()
|
||||
if (lower.includes('infra')) return "infrastructure"
|
||||
if (lower.includes('enhance')) return "enhancement"
|
||||
if (lower.includes('test')) return "testing"
|
||||
return "feature"
|
||||
}
|
||||
|
||||
// Helper: parse comma-separated list
|
||||
function parseList(text) {
|
||||
if (!text || text.toLowerCase() === 'none') return []
|
||||
return text.split(/[,，]/).map(s => s.trim()).filter(Boolean)
|
||||
}
|
||||
|
||||
// Helper: parse depends_on field
|
||||
function parseDependsOn(text, prefix) {
|
||||
if (!text || text.toLowerCase() === 'none' || text === '[]') return []
|
||||
const pattern = new RegExp(`${prefix}\\d+`, 'g')
|
||||
return (text.match(pattern) || [])
|
||||
}
|
||||
```
|
||||
|
||||
### Validation Functions
|
||||
|
||||
```javascript
|
||||
// Validate progressive layers
|
||||
function validateProgressiveLayers(layers) {
|
||||
const errors = []
|
||||
|
||||
// Check scope overlap
|
||||
const allScopes = new Map()
|
||||
layers.forEach(layer => {
|
||||
layer.scope.forEach(feature => {
|
||||
if (allScopes.has(feature)) {
|
||||
errors.push(`Scope overlap: "${feature}" in both ${allScopes.get(feature)} and ${layer.id}`)
|
||||
}
|
||||
allScopes.set(feature, layer.id)
|
||||
})
|
||||
})
|
||||
|
||||
// Check circular dependencies
|
||||
const cycleErrors = detectCycles(layers, 'L')
|
||||
errors.push(...cycleErrors)
|
||||
|
||||
// Check convergence quality
|
||||
layers.forEach(layer => {
|
||||
errors.push(...validateConvergence(layer.id, layer.convergence))
|
||||
})
|
||||
|
||||
// Check L0 is self-contained (no depends_on)
|
||||
const l0 = layers.find(l => l.id === 'L0')
|
||||
if (l0 && l0.depends_on.length > 0) {
|
||||
errors.push("L0 (MVP) should not have dependencies")
|
||||
}
|
||||
|
||||
return errors
|
||||
}
|
||||
|
||||
// Validate direct tasks
|
||||
function validateDirectTasks(tasks) {
|
||||
const errors = []
|
||||
|
||||
// Check inputs/outputs chain
|
||||
const availableOutputs = new Set()
|
||||
const sortedTasks = topologicalSort(tasks)
|
||||
|
||||
sortedTasks.forEach(task => {
|
||||
task.inputs.forEach(input => {
|
||||
if (!availableOutputs.has(input)) {
|
||||
// Check if it's an existing resource (not from a task)
|
||||
// Only warn, don't error - existing files are valid inputs
|
||||
}
|
||||
})
|
||||
task.outputs.forEach(output => availableOutputs.add(output))
|
||||
})
|
||||
|
||||
// Check circular dependencies
|
||||
const cycleErrors = detectCycles(tasks, 'T')
|
||||
errors.push(...cycleErrors)
|
||||
|
||||
// Check convergence quality
|
||||
tasks.forEach(task => {
|
||||
errors.push(...validateConvergence(task.id, task.convergence))
|
||||
})
|
||||
|
||||
// Check parallel_group consistency
|
||||
const groups = new Map()
|
||||
tasks.forEach(task => {
|
||||
if (!groups.has(task.parallel_group)) groups.set(task.parallel_group, [])
|
||||
groups.get(task.parallel_group).push(task)
|
||||
})
|
||||
groups.forEach((groupTasks, groupId) => {
|
||||
if (groupTasks.length > 1) {
|
||||
// Tasks in same group should not depend on each other
|
||||
const ids = new Set(groupTasks.map(t => t.id))
|
||||
groupTasks.forEach(task => {
|
||||
task.depends_on.forEach(dep => {
|
||||
if (ids.has(dep)) {
|
||||
errors.push(`Parallel group ${groupId}: ${task.id} depends on ${dep} but both in same group`)
|
||||
}
|
||||
})
|
||||
})
|
||||
}
|
||||
})
|
||||
|
||||
return errors
|
||||
}
|
||||
|
||||
// Validate convergence quality
|
||||
function validateConvergence(recordId, convergence) {
|
||||
const errors = []
|
||||
|
||||
// Check criteria are testable (not vague)
|
||||
const vaguePatterns = /正常|正确|好|可以|没问题|works|fine|good|correct/i
|
||||
convergence.criteria.forEach((criterion, i) => {
|
||||
if (vaguePatterns.test(criterion) && criterion.length < 15) {
|
||||
errors.push(`${recordId} criteria[${i}]: Too vague - "${criterion}"`)
|
||||
}
|
||||
})
|
||||
|
||||
// Check verification is executable
|
||||
if (convergence.verification.length < 10) {
|
||||
errors.push(`${recordId} verification: Too short, needs executable steps`)
|
||||
}
|
||||
|
||||
// Check definition_of_done is business language
|
||||
const technicalPatterns = /compile|build|lint|npm|npx|jest|tsc|eslint/i
|
||||
if (technicalPatterns.test(convergence.definition_of_done)) {
|
||||
errors.push(`${recordId} definition_of_done: Should be business language, not technical commands`)
|
||||
}
|
||||
|
||||
return errors
|
||||
}
|
||||
|
||||
// Detect circular dependencies
|
||||
function detectCycles(records, prefix) {
|
||||
const errors = []
|
||||
const graph = new Map(records.map(r => [r.id, r.depends_on]))
|
||||
const visited = new Set()
|
||||
const inStack = new Set()
|
||||
|
||||
function dfs(node, path) {
|
||||
if (inStack.has(node)) {
|
||||
errors.push(`Circular dependency detected: ${[...path, node].join(' → ')}`)
|
||||
return
|
||||
}
|
||||
if (visited.has(node)) return
|
||||
|
||||
visited.add(node)
|
||||
inStack.add(node)
|
||||
;(graph.get(node) || []).forEach(dep => dfs(dep, [...path, node]))
|
||||
inStack.delete(node)
|
||||
}
|
||||
|
||||
records.forEach(r => {
|
||||
if (!visited.has(r.id)) dfs(r.id, [])
|
||||
})
|
||||
|
||||
return errors
|
||||
}
|
||||
|
||||
// Topological sort
|
||||
function topologicalSort(tasks) {
|
||||
const result = []
|
||||
const visited = new Set()
|
||||
const taskMap = new Map(tasks.map(t => [t.id, t]))
|
||||
|
||||
function visit(taskId) {
|
||||
if (visited.has(taskId)) return
|
||||
visited.add(taskId)
|
||||
const task = taskMap.get(taskId)
|
||||
if (task) {
|
||||
task.depends_on.forEach(dep => visit(dep))
|
||||
result.push(task)
|
||||
}
|
||||
}
|
||||
|
||||
tasks.forEach(t => visit(t.id))
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
### JSONL & Markdown Generation
|
||||
|
||||
```javascript
|
||||
// Generate roadmap.jsonl
|
||||
function generateJsonl(records) {
|
||||
return records.map(record => JSON.stringify(record)).join('\n') + '\n'
|
||||
}
|
||||
|
||||
// Generate roadmap.md for progressive mode
|
||||
function generateProgressiveRoadmapMd(layers, input) {
|
||||
return `# 需求路线图
|
||||
|
||||
**Session**: ${input.session.id}
|
||||
**需求**: ${input.requirement}
|
||||
**策略**: progressive
|
||||
**不确定性**: ${input.strategy_assessment.uncertainty_level}
|
||||
**生成时间**: ${new Date().toISOString()}
|
||||
|
||||
## 策略评估
|
||||
|
||||
- 目标: ${input.strategy_assessment.goal}
|
||||
- 约束: ${input.strategy_assessment.constraints.join(', ') || '无'}
|
||||
- 利益方: ${input.strategy_assessment.stakeholders.join(', ') || '无'}
|
||||
|
||||
## 路线图概览
|
||||
|
||||
| 层级 | 名称 | 目标 | 工作量 | 依赖 |
|
||||
|------|------|------|--------|------|
|
||||
${layers.map(l => `| ${l.id} | ${l.name} | ${l.goal} | ${l.effort} | ${l.depends_on.length ? l.depends_on.join(', ') : '-'} |`).join('\n')}
|
||||
|
||||
## 各层详情
|
||||
|
||||
${layers.map(l => `### ${l.id}: ${l.name}
|
||||
|
||||
**目标**: ${l.goal}
|
||||
|
||||
**范围**: ${l.scope.join('、')}
|
||||
|
||||
**排除**: ${l.excludes.join('、') || '无'}
|
||||
|
||||
**收敛标准**:
|
||||
${l.convergence.criteria.map(c => `- ✅ ${c}`).join('\n')}
|
||||
- 🔍 **验证方法**: ${l.convergence.verification}
|
||||
- 🎯 **完成定义**: ${l.convergence.definition_of_done}
|
||||
|
||||
**风险项**: ${l.risk_items.length ? l.risk_items.map(r => `\n- ⚠️ ${r}`).join('') : '无'}
|
||||
|
||||
**工作量**: ${l.effort}
|
||||
`).join('\n---\n\n')}
|
||||
|
||||
## 风险汇总
|
||||
|
||||
${layers.flatMap(l => l.risk_items.map(r => `- **${l.id}**: ${r}`)).join('\n') || '无已识别风险'}
|
||||
|
||||
## 下一步
|
||||
|
||||
每个层级可独立执行：
|
||||
\`\`\`bash
|
||||
/workflow:lite-plan "${layers[0]?.name}: ${layers[0]?.scope.join(', ')}"
|
||||
\`\`\`
|
||||
|
||||
路线图 JSONL 文件: \`${input.session.folder}/roadmap.jsonl\`
|
||||
`
|
||||
}
|
||||
|
||||
// Generate roadmap.md for direct mode
|
||||
function generateDirectRoadmapMd(tasks, input) {
|
||||
return `# 需求路线图
|
||||
|
||||
**Session**: ${input.session.id}
|
||||
**需求**: ${input.requirement}
|
||||
**策略**: direct
|
||||
**生成时间**: ${new Date().toISOString()}
|
||||
|
||||
## 策略评估
|
||||
|
||||
- 目标: ${input.strategy_assessment.goal}
|
||||
- 约束: ${input.strategy_assessment.constraints.join(', ') || '无'}
|
||||
|
||||
## 任务序列
|
||||
|
||||
| 组 | ID | 标题 | 类型 | 依赖 |
|
||||
|----|-----|------|------|------|
|
||||
${tasks.map(t => `| ${t.parallel_group} | ${t.id} | ${t.title} | ${t.type} | ${t.depends_on.length ? t.depends_on.join(', ') : '-'} |`).join('\n')}
|
||||
|
||||
## 各任务详情
|
||||
|
||||
${tasks.map(t => `### ${t.id}: ${t.title}
|
||||
|
||||
**类型**: ${t.type} | **并行组**: ${t.parallel_group}
|
||||
|
||||
**范围**: ${t.scope}
|
||||
|
||||
**输入**: ${t.inputs.length ? t.inputs.join(', ') : '无（起始任务）'}
|
||||
**输出**: ${t.outputs.join(', ')}
|
||||
|
||||
**收敛标准**:
|
||||
${t.convergence.criteria.map(c => `- ✅ ${c}`).join('\n')}
|
||||
- 🔍 **验证方法**: ${t.convergence.verification}
|
||||
- 🎯 **完成定义**: ${t.convergence.definition_of_done}
|
||||
`).join('\n---\n\n')}
|
||||
|
||||
## 下一步
|
||||
|
||||
每个任务可独立执行：
|
||||
\`\`\`bash
|
||||
/workflow:lite-plan "${tasks[0]?.title}: ${tasks[0]?.scope}"
|
||||
\`\`\`
|
||||
|
||||
路线图 JSONL 文件: \`${input.session.folder}/roadmap.jsonl\`
|
||||
`
|
||||
}
|
||||
```
|
||||
|
||||
### Fallback Decomposition
|
||||
|
||||
```javascript
|
||||
// Manual decomposition when CLI fails
|
||||
function manualProgressiveDecomposition(requirement, context) {
|
||||
return [
|
||||
{
|
||||
id: "L0", name: "MVP", goal: "最小可用闭环",
|
||||
scope: ["核心功能"], excludes: ["高级功能", "优化"],
|
||||
convergence: {
|
||||
criteria: ["核心路径端到端可跑通"],
|
||||
verification: "手动测试核心流程",
|
||||
definition_of_done: "用户可完成一次核心操作的完整流程"
|
||||
},
|
||||
risk_items: ["技术选型待验证"], effort: "medium", depends_on: []
|
||||
},
|
||||
{
|
||||
id: "L1", name: "可用", goal: "关键用户路径完善",
|
||||
scope: ["错误处理", "输入校验"], excludes: ["性能优化", "监控"],
|
||||
convergence: {
|
||||
criteria: ["所有用户输入有校验", "错误场景有提示"],
|
||||
verification: "单元测试 + 手动测试错误场景",
|
||||
definition_of_done: "用户遇到问题时有清晰的引导和恢复路径"
|
||||
},
|
||||
risk_items: [], effort: "medium", depends_on: ["L0"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
function manualDirectDecomposition(requirement, context) {
|
||||
return [
|
||||
{
|
||||
id: "T1", title: "基础设施搭建", type: "infrastructure",
|
||||
scope: "项目骨架和基础配置",
|
||||
inputs: [], outputs: ["project-structure"],
|
||||
convergence: {
|
||||
criteria: ["项目可构建无报错", "基础配置完成"],
|
||||
verification: "npm run build (或对应构建命令)",
|
||||
definition_of_done: "项目基础框架就绪，可开始功能开发"
|
||||
},
|
||||
depends_on: [], parallel_group: 1
|
||||
},
|
||||
{
|
||||
id: "T2", title: "核心功能实现", type: "feature",
|
||||
scope: "核心业务逻辑",
|
||||
inputs: ["project-structure"], outputs: ["core-module"],
|
||||
convergence: {
|
||||
criteria: ["核心 API/功能可调用", "返回预期结果"],
|
||||
verification: "运行核心功能测试",
|
||||
definition_of_done: "核心业务功能可正常使用"
|
||||
},
|
||||
depends_on: ["T1"], parallel_group: 2
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 5: Decomposition Quality Check (MANDATORY)
|
||||
|
||||
### Overview
|
||||
|
||||
After generating roadmap.jsonl, **MUST** execute CLI quality check before returning to orchestrator.
|
||||
|
||||
### Quality Dimensions
|
||||
|
||||
| Dimension | Check Criteria | Critical? |
|
||||
|-----------|---------------|-----------|
|
||||
| **Requirement Coverage** | All aspects of original requirement addressed in layers/tasks | Yes |
|
||||
| **Convergence Quality** | criteria testable, verification executable, DoD business-readable | Yes |
|
||||
| **Scope Integrity** | Progressive: no overlap/gaps; Direct: inputs/outputs chain valid | Yes |
|
||||
| **Dependency Correctness** | No circular deps, proper ordering | Yes |
|
||||
| **Effort Balance** | No single layer/task disproportionately large | No |
|
||||
|
||||
### CLI Quality Check Command
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Validate roadmap decomposition quality
|
||||
Success: All quality dimensions pass
|
||||
|
||||
ORIGINAL REQUIREMENT:
|
||||
${requirement}
|
||||
|
||||
ROADMAP (${selected_mode} mode):
|
||||
${roadmapJsonlContent}
|
||||
|
||||
TASK:
|
||||
• Requirement Coverage: Does the roadmap address ALL aspects of the requirement?
|
||||
• Convergence Quality: Are criteria testable? Is verification executable? Is DoD business-readable?
|
||||
• Scope Integrity: ${selected_mode === 'progressive' ? 'No scope overlap between layers, no feature gaps' : 'Inputs/outputs chain is valid, parallel groups are correct'}
|
||||
• Dependency Correctness: No circular dependencies
|
||||
• Effort Balance: No disproportionately large items
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED:
|
||||
## Quality Check Results
|
||||
### Requirement Coverage: PASS|FAIL
|
||||
[details]
|
||||
### Convergence Quality: PASS|FAIL
|
||||
[details and specific issues per record]
|
||||
### Scope Integrity: PASS|FAIL
|
||||
[details]
|
||||
### Dependency Correctness: PASS|FAIL
|
||||
[details]
|
||||
### Effort Balance: PASS|FAIL
|
||||
[details]
|
||||
|
||||
## Recommendation: PASS|AUTO_FIX|NEEDS_REVIEW
|
||||
## Fixes (if AUTO_FIX):
|
||||
[specific fixes as JSON patches]
|
||||
|
||||
CONSTRAINTS: Read-only validation, do not modify files
|
||||
" --tool ${cli_config.tool} --mode analysis
|
||||
```
|
||||
|
||||
### Auto-Fix Strategy
|
||||
|
||||
| Issue Type | Auto-Fix Action |
|
||||
|-----------|----------------|
|
||||
| Vague criteria | Replace with specific, testable conditions |
|
||||
| Technical DoD | Rewrite in business language |
|
||||
| Missing scope items | Add to appropriate layer/task |
|
||||
| Effort imbalance | Suggest split (report to orchestrator) |
|
||||
|
||||
After fixes, update `roadmap.jsonl` and `roadmap.md`.
|
||||
|
||||
## Error Handling
|
||||
|
||||
```javascript
|
||||
// Fallback chain: Gemini → Qwen → manual decomposition
|
||||
try {
|
||||
result = executeCLI(cli_config.tool, prompt)
|
||||
} catch (error) {
|
||||
try {
|
||||
result = executeCLI(cli_config.fallback, prompt)
|
||||
} catch {
|
||||
// Manual fallback
|
||||
records = selected_mode === 'progressive'
|
||||
? manualProgressiveDecomposition(requirement, exploration_context)
|
||||
: manualDirectDecomposition(requirement, exploration_context)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Reminders
|
||||
|
||||
**ALWAYS**:
|
||||
- Parse CLI output into structured records with full convergence fields
|
||||
- Validate all records against schema before writing JSONL
|
||||
- Check for circular dependencies
|
||||
- Ensure convergence criteria are testable (not vague)
|
||||
- Ensure verification is executable (commands or explicit steps)
|
||||
- Ensure definition_of_done uses business language
|
||||
- Run Phase 5 quality check before returning
|
||||
- Write both roadmap.jsonl AND roadmap.md
|
||||
|
||||
**Bash Tool**:
|
||||
- Use `run_in_background=false` for all Bash/CLI calls
|
||||
|
||||
**NEVER**:
|
||||
- Output vague convergence criteria ("works correctly", "系统正常")
|
||||
- Create circular dependencies
|
||||
- Skip convergence validation
|
||||
- Skip Phase 5 quality check
|
||||
- Return without writing both output files
|
||||
692
.claude/commands/workflow/req-plan-with-file.md
Normal file
692
.claude/commands/workflow/req-plan-with-file.md
Normal file
@@ -0,0 +1,692 @@
|
||||
---
|
||||
name: req-plan-with-file
|
||||
description: Requirement-level progressive roadmap planning with JSONL output. Decomposes requirements into convergent layers (MVP→iterations) or topologically-sorted task sequences, each with testable completion criteria.
|
||||
argument-hint: "[-y|--yes] [-c|--continue] [-m|--mode progressive|direct|auto] \"requirement description\""
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm strategy selection, use recommended mode, skip interactive validation rounds.
|
||||
|
||||
# Workflow Req-Plan Command (/workflow:req-plan-with-file)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
/workflow:req-plan-with-file "Implement user authentication system with OAuth and 2FA"
|
||||
|
||||
# With mode selection
|
||||
/workflow:req-plan-with-file -m progressive "Build real-time notification system" # Layered MVP→iterations
|
||||
/workflow:req-plan-with-file -m direct "Refactor payment module" # Topologically-sorted task sequence
|
||||
/workflow:req-plan-with-file -m auto "Add data export feature" # Auto-select strategy
|
||||
|
||||
# Continue existing session
|
||||
/workflow:req-plan-with-file --continue "user authentication system"
|
||||
|
||||
# Auto mode
|
||||
/workflow:req-plan-with-file -y "Implement caching layer"
|
||||
```
|
||||
|
||||
**Context Source**: cli-explore-agent (optional) + requirement analysis
|
||||
**Output Directory**: `.workflow/.req-plan/{session-id}/`
|
||||
**Core Innovation**: JSONL roadmap where each record is self-contained + has convergence criteria, independently executable via lite-plan
|
||||
|
||||
## Overview
|
||||
|
||||
Requirement-level layered roadmap planning command. Decomposes a requirement into **convergent layers or task sequences**, each record containing explicit completion criteria (convergence), independently executable via `lite-plan`.
|
||||
|
||||
**Dual Modes**:
|
||||
- **Progressive**: Layered MVP→iterations, suitable for high-uncertainty requirements (validate first, then refine)
|
||||
- **Direct**: Topologically-sorted task sequence, suitable for low-uncertainty requirements (clear tasks, directly ordered)
|
||||
- **Auto**: Automatically selects based on uncertainty level
|
||||
|
||||
**Core Workflow**: Requirement Understanding → Strategy Selection → Context Collection (optional) → Decomposition → Validation → Output
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ REQ-PLAN ROADMAP WORKFLOW │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Phase 1: Requirement Understanding & Strategy Selection │
|
||||
│ ├─ Parse requirement: goal / constraints / stakeholders │
|
||||
│ ├─ Assess uncertainty level │
|
||||
│ │ ├─ High uncertainty → recommend progressive │
|
||||
│ │ └─ Low uncertainty → recommend direct │
|
||||
│ ├─ User confirms strategy (-m skips, -y auto-selects recommended) │
|
||||
│ └─ Initialize strategy-assessment.json + roadmap.md skeleton │
|
||||
│ │
|
||||
│ Phase 2: Context Collection (Optional) │
|
||||
│ ├─ Detect codebase: package.json / go.mod / src / ... │
|
||||
│ ├─ Has codebase → cli-explore-agent explores relevant modules │
|
||||
│ └─ No codebase → skip, pure requirement decomposition │
|
||||
│ │
|
||||
│ Phase 3: Decomposition Execution (cli-roadmap-plan-agent) │
|
||||
│ ├─ Progressive: define 2-4 layers, each with full convergence │
|
||||
│ ├─ Direct: vertical slicing + topological sort, each with convergence│
|
||||
│ └─ Generate roadmap.jsonl (one self-contained record per line) │
|
||||
│ │
|
||||
│ Phase 4: Interactive Validation & Final Output │
|
||||
│ ├─ Display decomposition results (tabular + convergence criteria) │
|
||||
│ ├─ User feedback loop (up to 5 rounds) │
|
||||
│ ├─ Generate final roadmap.md │
|
||||
│ └─ Next steps: layer-by-layer lite-plan / create issue / export │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
```
|
||||
.workflow/.req-plan/RPLAN-{slug}-{YYYY-MM-DD}/
|
||||
├── roadmap.md # ⭐ Human-readable roadmap
|
||||
├── roadmap.jsonl # ⭐ Machine-readable, one self-contained record per line (with convergence)
|
||||
├── strategy-assessment.json # Strategy assessment result
|
||||
└── exploration-codebase.json # Codebase context (optional)
|
||||
```
|
||||
|
||||
| File | Phase | Description |
|
||||
|------|-------|-------------|
|
||||
| `strategy-assessment.json` | 1 | Uncertainty analysis + mode recommendation + extracted goal/constraints/stakeholders |
|
||||
| `roadmap.md` (skeleton) | 1 | Initial skeleton with placeholders, finalized in Phase 4 |
|
||||
| `exploration-codebase.json` | 2 | Codebase context: relevant modules, patterns, integration points (only when codebase exists) |
|
||||
| `roadmap.jsonl` | 3 | One self-contained JSON record per line with convergence criteria |
|
||||
| `roadmap.md` (final) | 4 | Human-readable roadmap with tabular display + convergence details, revised per user feedback |
|
||||
|
||||
**roadmap.md template**:
|
||||
|
||||
```markdown
|
||||
# Requirement Roadmap
|
||||
|
||||
**Session**: RPLAN-{slug}-{date}
|
||||
**Requirement**: {requirement}
|
||||
**Strategy**: {progressive|direct}
|
||||
**Generated**: {timestamp}
|
||||
|
||||
## Strategy Assessment
|
||||
- Uncertainty level: {high|medium|low}
|
||||
- Decomposition mode: {progressive|direct}
|
||||
- Assessment basis: {factors summary}
|
||||
|
||||
## Roadmap
|
||||
{Tabular display of layers/tasks}
|
||||
|
||||
## Convergence Criteria Details
|
||||
{Expanded convergence for each layer/task}
|
||||
|
||||
## Risk Items
|
||||
{Aggregated risk_items}
|
||||
|
||||
## Next Steps
|
||||
{Execution guidance}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Flag | Default | Description |
|
||||
|------|---------|-------------|
|
||||
| `-y, --yes` | false | Auto-confirm all decisions |
|
||||
| `-c, --continue` | false | Continue existing session |
|
||||
| `-m, --mode` | auto | Decomposition strategy: progressive / direct / auto |
|
||||
|
||||
**Session ID format**: `RPLAN-{slug}-{YYYY-MM-DD}`
|
||||
- slug: lowercase, alphanumeric + CJK characters, max 40 chars
|
||||
- date: YYYY-MM-DD (UTC+8)
|
||||
- Auto-detect continue: session folder + roadmap.jsonl exists → continue mode
|
||||
|
||||
## JSONL Schema Design
|
||||
|
||||
### Convergence Criteria (convergence field)
|
||||
|
||||
Each JSONL record's `convergence` object contains three levels:
|
||||
|
||||
| Field | Purpose | Requirement |
|
||||
|-------|---------|-------------|
|
||||
| `criteria[]` | List of checkable specific conditions | **Testable** (can be written as assertions or manual steps) |
|
||||
| `verification` | How to verify these conditions | **Executable** (command, script, or explicit steps) |
|
||||
| `definition_of_done` | One-sentence completion definition | **Business language** (non-technical person can judge) |
|
||||
|
||||
### Progressive Mode
|
||||
|
||||
Each line = one layer. Layer naming convention:
|
||||
|
||||
| Layer | Name | Typical Goal |
|
||||
|-------|------|--------------|
|
||||
| L0 | MVP | Minimum viable closed loop, core path works end-to-end |
|
||||
| L1 | Usable | Key user paths refined, basic error handling |
|
||||
| L2 | Refined | Edge case handling, performance optimization, security hardening |
|
||||
| L3 | Optimized | Advanced features, observability, operations support |
|
||||
|
||||
**Schema**: `id, name, goal, scope[], excludes[], convergence{}, risk_items[], effort, depends_on[]`
|
||||
|
||||
```jsonl
|
||||
{"id":"L0","name":"MVP","goal":"Minimum viable closed loop","scope":["User registration and login","Basic CRUD"],"excludes":["OAuth","2FA"],"convergence":{"criteria":["End-to-end register→login→operate flow works","Core API returns correct responses"],"verification":"curl/Postman manual testing or smoke test script","definition_of_done":"New user can complete the full flow of register→login→perform one core operation"},"risk_items":["JWT library selection needs validation"],"effort":"medium","depends_on":[]}
|
||||
{"id":"L1","name":"Usable","goal":"Complete key user paths","scope":["Password reset","Input validation","Error messages"],"excludes":["Audit logs","Rate limiting"],"convergence":{"criteria":["All form fields have frontend+backend validation","Password reset email can be sent and reset completed","Error scenarios show user-friendly messages"],"verification":"Unit tests cover validation logic + manual test of reset flow","definition_of_done":"Users have a clear recovery path when encountering input errors or forgotten passwords"},"risk_items":[],"effort":"medium","depends_on":["L0"]}
|
||||
```
|
||||
|
||||
**Constraints**: 2-4 layers, L0 must be a self-contained closed loop with no dependencies, each feature belongs to exactly ONE layer (no scope overlap).
|
||||
|
||||
### Direct Mode
|
||||
|
||||
Each line = one task. Task type convention:
|
||||
|
||||
| Type | Use Case |
|
||||
|------|----------|
|
||||
| infrastructure | Data models, configuration, scaffolding |
|
||||
| feature | API, UI, business logic implementation |
|
||||
| enhancement | Validation, error handling, edge cases |
|
||||
| testing | Unit tests, integration tests, E2E |
|
||||
|
||||
**Schema**: `id, title, type, scope, inputs[], outputs[], convergence{}, depends_on[], parallel_group`
|
||||
|
||||
```jsonl
|
||||
{"id":"T1","title":"Establish data model","type":"infrastructure","scope":"DB schema + TypeScript types","inputs":[],"outputs":["schema.prisma","types/user.ts"],"convergence":{"criteria":["Migration executes without errors","TypeScript types compile successfully","Fields cover all business entities"],"verification":"npx prisma migrate dev && npx tsc --noEmit","definition_of_done":"Database schema migrates correctly, type definitions can be referenced by other modules"},"depends_on":[],"parallel_group":1}
|
||||
{"id":"T2","title":"Implement core API","type":"feature","scope":"CRUD endpoints for User","inputs":["schema.prisma","types/user.ts"],"outputs":["routes/user.ts","controllers/user.ts"],"convergence":{"criteria":["GET/POST/PUT/DELETE return correct status codes","Request/response conforms to schema","No N+1 queries"],"verification":"jest --testPathPattern=user.test.ts","definition_of_done":"All User CRUD endpoints pass integration tests"},"depends_on":["T1"],"parallel_group":2}
|
||||
```
|
||||
|
||||
**Constraints**: Inputs must come from preceding task outputs or existing resources, tasks in same parallel_group must be truly independent, no circular dependencies.
|
||||
|
||||
## Implementation
|
||||
|
||||
### Session Initialization
|
||||
|
||||
**Objective**: Create session context and directory structure.
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
// Parse flags
|
||||
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
const continueMode = $ARGUMENTS.includes('--continue') || $ARGUMENTS.includes('-c')
|
||||
const modeMatch = $ARGUMENTS.match(/(?:--mode|-m)\s+(progressive|direct|auto)/)
|
||||
const requestedMode = modeMatch ? modeMatch[1] : 'auto'
|
||||
|
||||
// Clean requirement text (remove flags)
|
||||
const requirement = $ARGUMENTS
|
||||
.replace(/--yes|-y|--continue|-c|--mode\s+\w+|-m\s+\w+/g, '')
|
||||
.trim()
|
||||
|
||||
const slug = requirement.toLowerCase()
|
||||
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
|
||||
.substring(0, 40)
|
||||
const dateStr = getUtc8ISOString().substring(0, 10)
|
||||
const sessionId = `RPLAN-${slug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.req-plan/${sessionId}`
|
||||
|
||||
// Auto-detect continue: session folder + roadmap.jsonl exists → continue mode
|
||||
Bash(`mkdir -p ${sessionFolder}`)
|
||||
```
|
||||
|
||||
### Phase 1: Requirement Understanding & Strategy Selection
|
||||
|
||||
**Objective**: Parse requirement, assess uncertainty, select decomposition strategy.
|
||||
|
||||
**Prerequisites**: Session initialized, requirement description available.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Parse Requirement**
|
||||
- Extract core goal (what to achieve)
|
||||
- Identify constraints (tech stack, timeline, compatibility, etc.)
|
||||
- Identify stakeholders (users, admins, developers, etc.)
|
||||
- Identify keywords to determine domain
|
||||
|
||||
2. **Assess Uncertainty Level**
|
||||
|
||||
```javascript
|
||||
const uncertaintyFactors = {
|
||||
scope_clarity: 'low|medium|high',
|
||||
technical_risk: 'low|medium|high',
|
||||
dependency_unknown: 'low|medium|high',
|
||||
domain_familiarity: 'low|medium|high',
|
||||
requirement_stability: 'low|medium|high'
|
||||
}
|
||||
// high uncertainty (>=3 high) → progressive
|
||||
// low uncertainty (>=3 low) → direct
|
||||
// otherwise → ask user preference
|
||||
```
|
||||
|
||||
3. **Strategy Selection** (skip if `-m` already specified)
|
||||
|
||||
```javascript
|
||||
if (requestedMode !== 'auto') {
|
||||
selectedMode = requestedMode
|
||||
} else if (autoYes) {
|
||||
selectedMode = recommendedMode
|
||||
} else {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Decomposition strategy selection:\n\nUncertainty assessment: ${uncertaintyLevel}\nRecommended strategy: ${recommendedMode}\n\nSelect decomposition strategy:`,
|
||||
header: "Strategy",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive",
|
||||
description: "Layered MVP→iterations, validate core first then refine progressively. Suitable for high-uncertainty requirements needing quick validation"
|
||||
},
|
||||
{
|
||||
label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct",
|
||||
description: "Topologically-sorted task sequence with explicit dependencies. Suitable for clear requirements with confirmed technical approach"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
4. **Generate strategy-assessment.json**
|
||||
|
||||
```javascript
|
||||
const strategyAssessment = {
|
||||
session_id: sessionId,
|
||||
requirement: requirement,
|
||||
timestamp: getUtc8ISOString(),
|
||||
uncertainty_factors: uncertaintyFactors,
|
||||
uncertainty_level: uncertaintyLevel, // 'high' | 'medium' | 'low'
|
||||
recommended_mode: recommendedMode,
|
||||
selected_mode: selectedMode,
|
||||
goal: extractedGoal,
|
||||
constraints: extractedConstraints,
|
||||
stakeholders: extractedStakeholders,
|
||||
domain_keywords: extractedKeywords
|
||||
}
|
||||
Write(`${sessionFolder}/strategy-assessment.json`, JSON.stringify(strategyAssessment, null, 2))
|
||||
```
|
||||
|
||||
5. **Initialize roadmap.md skeleton** (placeholder sections, finalized in Phase 4)
|
||||
|
||||
```javascript
|
||||
const roadmapMdSkeleton = `# Requirement Roadmap
|
||||
|
||||
**Session**: ${sessionId}
|
||||
**Requirement**: ${requirement}
|
||||
**Strategy**: ${selectedMode}
|
||||
**Status**: Planning
|
||||
**Created**: ${getUtc8ISOString()}
|
||||
|
||||
## Strategy Assessment
|
||||
- Uncertainty level: ${uncertaintyLevel}
|
||||
- Decomposition mode: ${selectedMode}
|
||||
|
||||
## Roadmap
|
||||
> To be populated after Phase 3 decomposition
|
||||
|
||||
## Convergence Criteria Details
|
||||
> To be populated after Phase 3 decomposition
|
||||
|
||||
## Risk Items
|
||||
> To be populated after Phase 3 decomposition
|
||||
|
||||
## Next Steps
|
||||
> To be populated after Phase 4 validation
|
||||
`
|
||||
Write(`${sessionFolder}/roadmap.md`, roadmapMdSkeleton)
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- Requirement goal, constraints, stakeholders identified
|
||||
- Uncertainty level assessed
|
||||
- Strategy selected (progressive or direct)
|
||||
- strategy-assessment.json generated
|
||||
- roadmap.md skeleton initialized
|
||||
|
||||
### Phase 2: Context Collection (Optional)
|
||||
|
||||
**Objective**: If a codebase exists, collect relevant context to enhance decomposition quality.
|
||||
|
||||
**Prerequisites**: Phase 1 complete.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Detect Codebase**
|
||||
|
||||
```javascript
|
||||
const hasCodebase = Bash(`
|
||||
test -f package.json && echo "nodejs" ||
|
||||
test -f go.mod && echo "golang" ||
|
||||
test -f Cargo.toml && echo "rust" ||
|
||||
test -f pyproject.toml && echo "python" ||
|
||||
test -f pom.xml && echo "java" ||
|
||||
test -d src && echo "generic" ||
|
||||
echo "none"
|
||||
`).trim()
|
||||
```
|
||||
|
||||
2. **Codebase Exploration** (only when hasCodebase !== 'none')
|
||||
|
||||
```javascript
|
||||
if (hasCodebase !== 'none') {
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Explore codebase: ${slug}`,
|
||||
prompt: `
|
||||
## Exploration Context
|
||||
Requirement: ${requirement}
|
||||
Strategy: ${selectedMode}
|
||||
Project Type: ${hasCodebase}
|
||||
Session: ${sessionFolder}
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}'
|
||||
2. Execute relevant searches based on requirement keywords
|
||||
3. Read: .workflow/project-tech.json (if exists)
|
||||
4. Read: .workflow/project-guidelines.json (if exists)
|
||||
|
||||
## Exploration Focus
|
||||
- Identify modules/components related to the requirement
|
||||
- Find existing patterns that should be followed
|
||||
- Locate integration points for new functionality
|
||||
- Assess current architecture constraints
|
||||
|
||||
## Output
|
||||
Write findings to: ${sessionFolder}/exploration-codebase.json
|
||||
|
||||
Schema: {
|
||||
project_type: "${hasCodebase}",
|
||||
relevant_modules: [{name, path, relevance}],
|
||||
existing_patterns: [{pattern, files, description}],
|
||||
integration_points: [{location, description, risk}],
|
||||
architecture_constraints: [string],
|
||||
tech_stack: {languages, frameworks, tools},
|
||||
_metadata: {timestamp, exploration_scope}
|
||||
}
|
||||
`
|
||||
})
|
||||
}
|
||||
// No codebase → skip, proceed directly to Phase 3
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- Codebase detection complete
|
||||
- When codebase exists, exploration-codebase.json generated
|
||||
- When no codebase, skipped and logged
|
||||
|
||||
### Phase 3: Decomposition Execution
|
||||
|
||||
**Objective**: Execute requirement decomposition via `cli-roadmap-plan-agent`, generating roadmap.jsonl + roadmap.md.
|
||||
|
||||
**Prerequisites**: Phase 1, Phase 2 complete. Strategy selected. Context collected (if applicable).
|
||||
|
||||
**Agent**: `cli-roadmap-plan-agent` (dedicated requirement roadmap planning agent, supports CLI-assisted decomposition + built-in quality checks)
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Prepare Context**
|
||||
|
||||
```javascript
|
||||
const strategy = JSON.parse(Read(`${sessionFolder}/strategy-assessment.json`))
|
||||
let explorationContext = null
|
||||
if (file_exists(`${sessionFolder}/exploration-codebase.json`)) {
|
||||
explorationContext = JSON.parse(Read(`${sessionFolder}/exploration-codebase.json`))
|
||||
}
|
||||
```
|
||||
|
||||
2. **Invoke cli-roadmap-plan-agent**
|
||||
|
||||
The agent internally executes a 5-phase flow:
|
||||
- Phase 1: Context loading + requirement analysis
|
||||
- Phase 2: CLI-assisted decomposition (Gemini → Qwen → manual fallback)
|
||||
- Phase 3: Record enhancement + validation (schema compliance, dependency checks, convergence quality)
|
||||
- Phase 4: Generate roadmap.jsonl + roadmap.md
|
||||
- Phase 5: CLI decomposition quality check (**MANDATORY** - requirement coverage, convergence criteria quality, dependency correctness)
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-roadmap-plan-agent",
|
||||
run_in_background: false,
|
||||
description: `Roadmap decomposition: ${slug}`,
|
||||
prompt: `
|
||||
## Roadmap Decomposition Task
|
||||
|
||||
### Input Context
|
||||
- **Requirement**: ${requirement}
|
||||
- **Selected Mode**: ${selectedMode}
|
||||
- **Session ID**: ${sessionId}
|
||||
- **Session Folder**: ${sessionFolder}
|
||||
|
||||
### Strategy Assessment
|
||||
${JSON.stringify(strategy, null, 2)}
|
||||
|
||||
### Codebase Context
|
||||
${explorationContext
|
||||
? `File: ${sessionFolder}/exploration-codebase.json\n${JSON.stringify(explorationContext, null, 2)}`
|
||||
: 'No codebase detected - pure requirement decomposition'}
|
||||
|
||||
### CLI Configuration
|
||||
- Primary tool: gemini
|
||||
- Fallback: qwen
|
||||
- Timeout: 60000ms
|
||||
|
||||
### Expected Output
|
||||
1. **${sessionFolder}/roadmap.jsonl** - One JSON record per line with convergence field
|
||||
2. **${sessionFolder}/roadmap.md** - Human-readable roadmap with tables and convergence details
|
||||
|
||||
### Mode-Specific Requirements
|
||||
|
||||
${selectedMode === 'progressive' ? `**Progressive Mode**:
|
||||
- 2-4 layers from MVP to full implementation
|
||||
- Each layer: id (L0-L3), name, goal, scope, excludes, convergence, risk_items, effort, depends_on
|
||||
- L0 (MVP) must be a self-contained closed loop with no dependencies
|
||||
- Scope: each feature belongs to exactly ONE layer (no overlap)
|
||||
- Layer names: MVP / Usable / Refined / Optimized` :
|
||||
|
||||
`**Direct Mode**:
|
||||
- Topologically-sorted task sequence
|
||||
- Each task: id (T1-Tn), title, type, scope, inputs, outputs, convergence, depends_on, parallel_group
|
||||
- Inputs must come from preceding task outputs or existing resources
|
||||
- Tasks in same parallel_group must be truly independent`}
|
||||
|
||||
### Convergence Quality Requirements
|
||||
- criteria[]: MUST be testable (can write assertions or manual verification steps)
|
||||
- verification: MUST be executable (command, script, or explicit steps)
|
||||
- definition_of_done: MUST use business language (non-technical person can judge)
|
||||
|
||||
### Execution
|
||||
1. Analyze requirement and build decomposition context
|
||||
2. Execute CLI-assisted decomposition (Gemini, fallback Qwen)
|
||||
3. Parse output, validate records, enhance convergence quality
|
||||
4. Write roadmap.jsonl + roadmap.md
|
||||
5. Execute mandatory quality check (Phase 5)
|
||||
6. Return brief completion summary
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- roadmap.jsonl generated, each line independently JSON.parse-able
|
||||
- roadmap.md generated (follows template in Output section)
|
||||
- Each record contains convergence (criteria + verification + definition_of_done)
|
||||
- Agent's internal quality check passed
|
||||
- No circular dependencies
|
||||
- Progressive: 2-4 layers, no scope overlap
|
||||
- Direct: tasks have explicit inputs/outputs, parallel_group assigned
|
||||
|
||||
### Phase 4: Interactive Validation & Final Output
|
||||
|
||||
**Objective**: Display decomposition results, collect user feedback, generate final artifacts.
|
||||
|
||||
**Prerequisites**: Phase 3 complete, roadmap.jsonl generated.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Display Decomposition Results** (tabular format)
|
||||
|
||||
**Progressive Mode**:
|
||||
```markdown
|
||||
## Roadmap Overview
|
||||
|
||||
| Layer | Name | Goal | Scope | Effort | Dependencies |
|
||||
|-------|------|------|-------|--------|--------------|
|
||||
| L0 | MVP | ... | ... | medium | - |
|
||||
| L1 | Usable | ... | ... | medium | L0 |
|
||||
|
||||
### Convergence Criteria
|
||||
**L0 - MVP**:
|
||||
- ✅ Criteria: [criteria list]
|
||||
- 🔍 Verification: [verification]
|
||||
- 🎯 Definition of Done: [definition_of_done]
|
||||
```
|
||||
|
||||
**Direct Mode**:
|
||||
```markdown
|
||||
## Task Sequence
|
||||
|
||||
| Group | ID | Title | Type | Dependencies |
|
||||
|-------|----|-------|------|--------------|
|
||||
| 1 | T1 | ... | infrastructure | - |
|
||||
| 2 | T2 | ... | feature | T1 |
|
||||
|
||||
### Convergence Criteria
|
||||
**T1 - Establish Data Model**:
|
||||
- ✅ Criteria: [criteria list]
|
||||
- 🔍 Verification: [verification]
|
||||
- 🎯 Definition of Done: [definition_of_done]
|
||||
```
|
||||
|
||||
2. **User Feedback Loop** (up to 5 rounds, skipped when autoYes)
|
||||
|
||||
```javascript
|
||||
if (!autoYes) {
|
||||
let round = 0
|
||||
let continueLoop = true
|
||||
|
||||
while (continueLoop && round < 5) {
|
||||
round++
|
||||
const feedback = AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Roadmap validation (round ${round}):\nAny feedback on the current decomposition?`,
|
||||
header: "Feedback",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Approve", description: "Decomposition is reasonable, generate final artifacts" },
|
||||
{ label: "Adjust Scope", description: "Some layer/task scopes need adjustment" },
|
||||
{ label: "Modify Convergence", description: "Convergence criteria are not specific or testable enough" },
|
||||
{ label: "Re-decompose", description: "Overall strategy or layering approach needs change" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
if (feedback === 'Approve') {
|
||||
continueLoop = false
|
||||
} else {
|
||||
// Handle adjustment based on feedback type
|
||||
// After adjustment, re-display and return to loop top
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Finalize roadmap.md** (populate template from Output section with actual data)
|
||||
|
||||
```javascript
|
||||
const roadmapMd = `
|
||||
# Requirement Roadmap
|
||||
|
||||
**Session**: ${sessionId}
|
||||
**Requirement**: ${requirement}
|
||||
**Strategy**: ${selectedMode}
|
||||
**Generated**: ${getUtc8ISOString()}
|
||||
|
||||
## Strategy Assessment
|
||||
- Uncertainty level: ${strategy.uncertainty_level}
|
||||
- Decomposition mode: ${selectedMode}
|
||||
|
||||
## Roadmap
|
||||
${generateRoadmapTable(items, selectedMode)}
|
||||
|
||||
## Convergence Criteria Details
|
||||
${items.map(item => generateConvergenceSection(item, selectedMode)).join('\n\n')}
|
||||
|
||||
## Risk Items
|
||||
${generateRiskSection(items)}
|
||||
|
||||
## Next Steps
|
||||
Each layer/task can be executed independently:
|
||||
\`\`\`bash
|
||||
/workflow:lite-plan "${items[0].name || items[0].title}: ${items[0].scope}"
|
||||
\`\`\`
|
||||
Roadmap JSONL file: \`${sessionFolder}/roadmap.jsonl\`
|
||||
`
|
||||
Write(`${sessionFolder}/roadmap.md`, roadmapMd)
|
||||
```
|
||||
|
||||
4. **Post-Completion Options**
|
||||
|
||||
```javascript
|
||||
if (!autoYes) {
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Roadmap generated. Next step:",
|
||||
header: "Next Step",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Execute First Layer", description: `Launch lite-plan to execute ${items[0].id}` },
|
||||
{ label: "Create Issue", description: "Create GitHub Issue based on roadmap" },
|
||||
{ label: "Export Report", description: "Generate standalone shareable roadmap report" },
|
||||
{ label: "Done", description: "Save roadmap only, execute later" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
| Selection | Action |
|
||||
|-----------|--------|
|
||||
| Execute First Layer | `Skill(skill="workflow:lite-plan", args="${firstItem.scope}")` |
|
||||
| Create Issue | `Skill(skill="issue:new", args="...")` |
|
||||
| Export Report | Copy roadmap.md + roadmap.jsonl to user-specified location, or generate standalone HTML/Markdown report |
|
||||
| Done | Display roadmap file paths, end |
|
||||
|
||||
**Success Criteria**:
|
||||
- User feedback processed (or skipped via autoYes)
|
||||
- roadmap.md finalized
|
||||
- roadmap.jsonl final version updated
|
||||
- Post-completion options provided
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| cli-explore-agent failure | Skip code exploration, proceed with pure requirement decomposition |
|
||||
| No codebase | Normal flow, skip Phase 2 |
|
||||
| Circular dependency detected | Prompt user to adjust dependencies, re-decompose |
|
||||
| User feedback timeout | Save current state, display `--continue` recovery command |
|
||||
| Max feedback rounds reached | Use current version to generate final artifacts |
|
||||
| Session folder conflict | Append timestamp suffix |
|
||||
| JSONL format error | Validate line by line, report problematic lines and fix |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear requirement description**: Detailed description → more accurate uncertainty assessment and decomposition
|
||||
2. **Validate MVP first**: In progressive mode, L0 should be the minimum verifiable closed loop
|
||||
3. **Testable convergence**: criteria must be writable as assertions or manual steps; definition_of_done should be judgeable by non-technical stakeholders (see Convergence Criteria in JSONL Schema Design)
|
||||
4. **Agent-First for Exploration**: Delegate codebase exploration to cli-explore-agent, do not analyze directly in main flow
|
||||
5. **Incremental validation**: Use `--continue` to iterate on existing roadmaps
|
||||
6. **Independently executable**: Each JSONL record should be independently passable to lite-plan for execution
|
||||
|
||||
## Usage Recommendations
|
||||
|
||||
**Use `/workflow:req-plan-with-file` when:**
|
||||
- You need to decompose a large requirement into a progressively executable roadmap
|
||||
- Unsure where to start, need an MVP strategy
|
||||
- Need to generate a trackable task sequence for the team
|
||||
- Requirement involves multiple stages or iterations
|
||||
|
||||
**Use `/workflow:lite-plan` when:**
|
||||
- You have a clear single task to execute
|
||||
- The requirement is already a layer/task from the roadmap
|
||||
- No layered planning needed
|
||||
|
||||
**Use `/workflow:collaborative-plan-with-file` when:**
|
||||
- A single complex task needs multi-agent parallel planning
|
||||
- Need to analyze the same task from multiple domain perspectives
|
||||
|
||||
**Use `/workflow:analyze-with-file` when:**
|
||||
- Need in-depth analysis of a technical problem
|
||||
- Not about planning execution, but understanding and discussion
|
||||
|
||||
---
|
||||
|
||||
**Now execute req-plan-with-file for**: $ARGUMENTS
|
||||
Reference in New Issue
Block a user