- Created a new directory structure for epics and stories with templates for individual epics and an index file. - Added a product brief template for generating product brief documents in Phase 2. - Introduced a requirements PRD template for generating a Product Requirements Document as a directory of individual requirement files in Phase 3. feat: implement V2PipelineTab component for Memory V2 management - Developed the V2PipelineTab component to manage extraction and consolidation processes. - Included ExtractionCard and ConsolidationCard components to handle respective functionalities. - Added JobsList component to display job statuses and allow filtering by job kind. feat: create hooks for Memory V2 pipeline - Implemented custom hooks for managing extraction and consolidation statuses, as well as job listings. - Added mutation hooks to trigger extraction and consolidation processes with automatic query invalidation on success.
26 KiB
name, description, argument-hint, allowed-tools
| name | description | argument-hint | allowed-tools |
|---|---|---|---|
| roadmap-with-file | Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable). Handoff to team-planex. | [-y|--yes] [-c|--continue] [-m progressive|direct|auto] "requirement description" | spawn_agent, wait, send_input, close_agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep |
Auto Mode
When --yes or -y: Auto-confirm strategy selection, use recommended mode, skip interactive rounds.
Roadmap-with-file Skill
Usage
$roadmap-with-file "Implement user authentication system with OAuth and 2FA"
$roadmap-with-file -m progressive "Build real-time notification system"
$roadmap-with-file -m direct "Refactor payment module"
$roadmap-with-file -m auto "Add data export feature"
$roadmap-with-file --continue "auth system"
$roadmap-with-file -y "Implement caching layer"
Flags:
-y, --yes: Skip all confirmations (auto mode)-c, --continue: Continue existing session-m, --mode: Strategy selection (progressive / direct / auto)
Context Source: cli-explore-agent (optional) + requirement analysis
Output Directory: .workflow/.roadmap/{session-id}/
Core Output: roadmap.md (single source, human-readable) + issues.jsonl (global, machine-executable)
Subagent API Reference
spawn_agent
Create a new subagent with task assignment.
const agentId = spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json
## TASK CONTEXT
${taskContext}
## DELIVERABLES
${deliverables}
`
})
wait
Get results from subagent (only way to retrieve results).
const result = wait({
ids: [agentId],
timeout_ms: 600000 // 10 minutes
})
if (result.timed_out) {
// Handle timeout - can continue waiting or send_input to prompt completion
}
send_input
Continue interaction with active subagent (for clarification or follow-up).
send_input({
id: agentId,
message: `
## CLARIFICATION ANSWERS
${answers}
## NEXT STEP
Continue with plan generation.
`
})
close_agent
Clean up subagent resources (irreversible).
close_agent({ id: agentId })
Output Artifacts
Single Source of Truth
| Artifact | Purpose | Consumer |
|---|---|---|
roadmap.md |
⭐ Human-readable strategic roadmap with all context | Human review, team-planex handoff |
.workflow/issues/issues.jsonl |
Global issue store (appended) | team-planex, issue commands |
Why No Separate JSON Files?
| Original File | Why Removed | Where Content Goes |
|---|---|---|
strategy-assessment.json |
Duplicates roadmap.md content | Embedded in roadmap.md Strategy Assessment section |
exploration-codebase.json |
Single-use intermediate | Embedded in roadmap.md Codebase Context appendix |
Overview
Strategic requirement roadmap with iterative decomposition. Creates a single roadmap.md that evolves through discussion, with issues persisted to global issues.jsonl for execution.
Core workflow: Understand → Decompose → Iterate → Validate → Handoff
┌─────────────────────────────────────────────────────────────────────────┐
│ ROADMAP ITERATIVE WORKFLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: Requirement Understanding & Strategy │
│ ├─ Parse requirement: goal / constraints / stakeholders │
│ ├─ Assess uncertainty level → recommend mode │
│ ├─ User confirms strategy (-m skips, -y auto-selects) │
│ └─ Initialize roadmap.md with Strategy Assessment │
│ │
│ Phase 2: Decomposition & Issue Creation │
│ ├─ cli-roadmap-plan-agent executes decomposition │
│ ├─ Progressive: 2-4 layers (MVP→Optimized) with convergence │
│ ├─ Direct: Topological task sequence with convergence │
│ ├─ Create issues via ccw issue create → issues.jsonl │
│ └─ Update roadmap.md with Roadmap table + Issue references │
│ │
│ Phase 3: Iterative Refinement (Multi-Round) │
│ ├─ Present roadmap to user │
│ ├─ Feedback: Approve | Adjust Scope | Modify Convergence | Replan │
│ ├─ Update roadmap.md with each round │
│ └─ Repeat until approved (max 5 rounds) │
│ │
│ Phase 4: Handoff │
│ ├─ Final roadmap.md with Issue ID references │
│ ├─ Options: team-planex | first wave | view issues | done │
│ └─ Issues ready in .workflow/issues/issues.jsonl │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Dual Modes
| Mode | Strategy | Best For | Decomposition |
|---|---|---|---|
| Progressive | MVP → Usable → Refined → Optimized | High uncertainty, need validation | 2-4 layers, each with full convergence |
| Direct | Topological task sequence | Clear requirements, confirmed tech | Tasks with explicit inputs/outputs |
Auto-selection logic:
- ≥3 high uncertainty factors → Progressive
- ≥3 low uncertainty factors → Direct
- Otherwise → Ask user preference
Output Structure
.workflow/.roadmap/RMAP-{slug}-{date}/
└── roadmap.md # ⭐ Single source of truth
# - Strategy Assessment (embedded)
# - Roadmap Table
# - Convergence Criteria per Issue
# - Codebase Context (appendix, if applicable)
# - Iteration History
.workflow/issues/issues.jsonl # Global issue store (appended)
# - One JSON object per line
# - Consumed by team-planex, issue commands
roadmap.md Template
# Requirement Roadmap
**Session**: RMAP-{slug}-{date}
**Requirement**: {requirement}
**Strategy**: {progressive|direct}
**Status**: {Planning|Refining|Ready}
**Created**: {timestamp}
---
## Strategy Assessment
- **Uncertainty Level**: {high|medium|low}
- **Decomposition Mode**: {progressive|direct}
- **Assessment Basis**: {factors summary}
- **Goal**: {extracted goal}
- **Constraints**: {extracted constraints}
- **Stakeholders**: {extracted stakeholders}
---
## Roadmap
### Progressive Mode
| Wave | Issue ID | Layer | Goal | Priority | Dependencies |
|------|----------|-------|------|----------|--------------|
| 1 | ISS-xxx | MVP | ... | 2 | - |
| 2 | ISS-yyy | Usable | ... | 3 | ISS-xxx |
### Direct Mode
| Wave | Issue ID | Title | Type | Dependencies |
|------|----------|-------|------|--------------|
| 1 | ISS-xxx | ... | infrastructure | - |
| 2 | ISS-yyy | ... | feature | ISS-xxx |
---
## Convergence Criteria
### ISS-xxx: {Issue Title}
- **Criteria**: [testable conditions]
- **Verification**: [executable steps/commands]
- **Definition of Done**: [business language, non-technical]
### ISS-yyy: {Issue Title}
...
---
## Risks
| Risk | Severity | Mitigation |
|------|----------|------------|
| ... | ... | ... |
---
## Iteration History
### Round 1 - {timestamp}
**User Feedback**: {feedback summary}
**Changes Made**: {adjustments}
**Status**: {approved|continue iteration}
---
## Codebase Context (Optional)
*Included when codebase exploration was performed*
- **Relevant Modules**: [...]
- **Existing Patterns**: [...]
- **Integration Points**: [...]
Issues JSONL Specification
Location & Format
Path: .workflow/issues/issues.jsonl
Format: JSONL (one complete JSON object per line)
Encoding: UTF-8
Mode: Append-only (new issues appended to end)
Record Schema
{
"id": "ISS-YYYYMMDD-NNN",
"title": "[LayerName] goal or [TaskType] title",
"status": "pending",
"priority": 2,
"context": "Markdown with goal, scope, convergence, verification, DoD",
"source": "text",
"tags": ["roadmap", "progressive|direct", "wave-N", "layer-name"],
"extended_context": {
"notes": {
"session": "RMAP-{slug}-{date}",
"strategy": "progressive|direct",
"wave": 1,
"depends_on_issues": []
}
},
"lifecycle_requirements": {
"test_strategy": "unit",
"regression_scope": "affected",
"acceptance_type": "automated",
"commit_strategy": "per-issue"
}
}
Query Interface
# By ID
ccw issue get ISS-20260227-001
# By tag
ccw issue list --tag wave-1
ccw issue list --tag roadmap
# By session
ccw issue list --session RMAP-auth-2026-02-27
# Execute
ccw issue execute ISS-20260227-001 ISS-20260227-002
Implementation
Session Initialization
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
// Parse flags
const AUTO_YES = $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 = `RMAP-${slug}-${dateStr}`
const sessionFolder = `.workflow/.roadmap/${sessionId}`
// Auto-detect continue mode
if (continueMode || file_exists(`${sessionFolder}/roadmap.md`)) {
// Resume existing session
const existingRoadmap = Read(`${sessionFolder}/roadmap.md`)
// Extract current phase and continue from there
}
Bash(`mkdir -p ${sessionFolder}`)
Phase 1: Requirement Understanding & Strategy
Objective: Parse requirement, assess uncertainty, select decomposition strategy, initialize roadmap.md.
Steps:
-
Parse Requirement
- Extract: goal, constraints, stakeholders, keywords
-
Assess Uncertainty
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' } // Calculate recommendation const highCount = Object.values(uncertaintyFactors).filter(v => v === 'high').length const lowCount = Object.values(uncertaintyFactors).filter(v => v === 'low').length let recommendedMode if (highCount >= 3) recommendedMode = 'progressive' else if (lowCount >= 3) recommendedMode = 'direct' else recommendedMode = 'progressive' // default safer choice -
Strategy Selection (skip if
-mspecified or AUTO_YES)let selectedMode if (requestedMode !== 'auto') { selectedMode = requestedMode } else if (AUTO_YES) { selectedMode = recommendedMode } else { const answer = ASK_USER([ { id: "strategy", type: "choice", prompt: `Decomposition strategy:\nUncertainty: ${uncertaintyLevel}\nRecommended: ${recommendedMode}`, options: [ { value: "progressive", label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive" }, { value: "direct", label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct" } ], default: recommendedMode } ]) // BLOCKS (wait for user response) selectedMode = answer.strategy } -
Initialize roadmap.md
const roadmapContent = `# Requirement Roadmap
Session: ${sessionId} Requirement: ${requirement} Strategy: ${selectedMode} Status: Planning Created: ${getUtc8ISOString()}
Strategy Assessment
- Uncertainty Level: ${uncertaintyLevel}
- Decomposition Mode: ${selectedMode}
- Assessment Basis: ${factorsSummary}
- Goal: ${extractedGoal}
- Constraints: ${extractedConstraints}
- Stakeholders: ${extractedStakeholders}
Roadmap
To be populated after Phase 2 decomposition
Convergence Criteria Details
To be populated after Phase 2 decomposition
Risks
To be populated after Phase 2 decomposition
Iteration History
To be populated during Phase 3 refinement
Codebase Context (Optional)
To be populated if codebase exploration was performed `
Write(${sessionFolder}/roadmap.md, roadmapContent)
**Success Criteria**:
- roadmap.md created with Strategy Assessment
- Strategy selected (progressive or direct)
- Uncertainty factors documented
---
### Phase 2: Decomposition & Issue Creation
**Objective**: Execute decomposition via `cli-roadmap-plan-agent`, create issues, update roadmap.md.
**Steps**:
1. **Optional Codebase Exploration** (if codebase detected)
```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 -d src && echo "generic" ||
echo "none"
`).trim()
let codebaseContext = null
if (hasCodebase !== 'none') {
const exploreAgentId = spawn_agent({
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json
---
## Exploration Context
- **Requirement**: ${requirement}
- **Strategy**: ${selectedMode}
- **Project Type**: ${hasCodebase}
- **Session**: ${sessionFolder}
## 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
Return findings as JSON with 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}
}
`
})
const exploreResult = wait({
ids: [exploreAgentId],
timeout_ms: 120000
})
close_agent({ id: exploreAgentId })
if (exploreResult.status[exploreAgentId].completed) {
codebaseContext = exploreResult.status[exploreAgentId].completed
}
}
- Execute Decomposition Agent
const decompositionAgentId = spawn_agent({ message: `
TASK ASSIGNMENT
MANDATORY FIRST STEPS (Agent Execute)
- Read role definition: ~/.codex/agents/cli-roadmap-plan-agent.md (MUST read first)
- Read: .workflow/project-tech.json
- Read: .workflow/project-guidelines.json
Roadmap Decomposition Task
Input Context
- Requirement: ${requirement}
- Selected Mode: ${selectedMode}
- Session ID: ${sessionId}
- Session Folder: ${sessionFolder}
Strategy Assessment
${JSON.stringify(strategyAssessment, null, 2)}
Codebase Context
${codebaseContext ? JSON.stringify(codebaseContext, null, 2) : 'No codebase detected - pure requirement decomposition'}
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, risks, 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)
Expected Output
- Update ${sessionFolder}/roadmap.md with Roadmap table + Convergence sections
- Create issues via ccw issue create - append to .workflow/issues/issues.jsonl
Issue Format (for ccw issue create)
- id: ISS-YYYYMMDD-NNN (auto-generated)
- title: [LayerName] goal or [TaskType] title
- context: Markdown with goal, scope, convergence criteria, verification, DoD
- priority: small→4, medium→3, large→2
- tags: ["roadmap", mode, wave-N, layer-name]
- extended_context.notes: {session, strategy, wave, depends_on_issues}
Execution Steps
-
Analyze requirement and build decomposition context
-
Execute decomposition (internal reasoning)
-
Validate records, check convergence quality
-
For each decomposed item:
- Run: ccw issue create --title "..." --context "..." --tags "..." --priority N
- Record returned Issue ID
-
Update roadmap.md with Issue ID references
-
Return brief completion summary with Issue IDs ` })
const decompositionResult = wait({ ids: [decompositionAgentId], timeout_ms: 300000 // 5 minutes for complex decomposition })
close_agent({ id: decompositionAgentId })
if (!decompositionResult.status[decompositionAgentId].completed) { throw new Error('Decomposition agent failed to complete') }
const issueIds = decompositionResult.status[decompositionAgentId].completed.issueIds || []
Success Criteria:
- Issues created in
.workflow/issues/issues.jsonl - roadmap.md updated with Issue references
- No circular dependencies
- Convergence criteria testable
Phase 3: Iterative Refinement
Objective: Multi-round user feedback to refine roadmap.
Steps:
-
Display Current Roadmap
- Read and display Roadmap table + key Convergence criteria
- Show issue count and wave breakdown
-
Feedback Loop (skip if AUTO_YES)
let round = 0 let approved = false while (!approved && round < 5) { round++ const feedback = ASK_USER([ { id: "feedback", type: "choice", prompt: `Roadmap validation (round ${round}):\n${issueIds.length} issues across ${waveCount} waves. Feedback?`, options: [ { value: "approve", label: "Approve", description: "Proceed to handoff" }, { value: "scope", label: "Adjust Scope", description: "Modify issue scopes" }, { value: "convergence", label: "Modify Convergence", description: "Refine criteria/verification" }, { value: "replan", label: "Re-decompose", description: "Change strategy/layering" } ] } ]) // BLOCKS (wait for user response) if (feedback.feedback === 'approve') { approved = true } else { // Handle feedback type switch (feedback.feedback) { case 'scope': // Collect scope adjustments const scopeAdjustments = ASK_USER([ { id: "adjustments", type: "text", prompt: "Describe scope adjustments needed:" } ]) // BLOCKS // Update roadmap.md and issues // ... implementation ... break case 'convergence': // Collect convergence refinements const convergenceRefinements = ASK_USER([ { id: "refinements", type: "text", prompt: "Describe convergence refinements needed:" } ]) // BLOCKS // Update roadmap.md // ... implementation ... break case 'replan': // Return to Phase 2 with new strategy const newStrategy = ASK_USER([ { id: "strategy", type: "choice", prompt: "Select new decomposition strategy:", options: [ { value: "progressive", label: "Progressive" }, { value: "direct", label: "Direct" } ] } ]) // BLOCKS selectedMode = newStrategy.strategy // Re-execute Phase 2 // ... goto Phase 2 ... break } // Update Iteration History in roadmap.md const iterationEntry = `
Round ${round} - ${getUtc8ISOString()}
User Feedback: ${feedback.feedback}
Changes Made: ${changesMade}
Status: continue iteration
Edit({ path:${sessionFolder}/roadmap.md, old_string: "## Iteration History\n\n> To be populated during Phase 3 refinement", new_string: ## Iteration History\n${iterationEntry}`
})
}
}
3. **Finalize Iteration History**
```javascript
// Update final status in roadmap.md
Edit({
path: `${sessionFolder}/roadmap.md`,
old_string: "**Status**: Planning",
new_string: "**Status**: Ready"
})
Success Criteria:
- User approved OR max rounds reached
- All changes recorded in Iteration History
- roadmap.md reflects final state
Phase 4: Handoff
Objective: Present final roadmap, offer execution options.
Steps:
-
Display Summary
## Roadmap Complete - **Session**: RMAP-{slug}-{date} - **Strategy**: {progressive|direct} - **Issues Created**: {count} across {waves} waves - **Roadmap**: .workflow/.roadmap/RMAP-{slug}-{date}/roadmap.md | Wave | Issue Count | Layer/Type | |------|-------------|------------| | 1 | 2 | MVP / infrastructure | | 2 | 3 | Usable / feature | -
Offer Options (skip if AUTO_YES)
let nextStep if (AUTO_YES) { nextStep = "done" // Default to done in auto mode } else { const answer = ASK_USER([ { id: "next", type: "choice", prompt: `${issueIds.length} issues ready. Next step:`, options: [ { value: "planex", label: "Execute with team-planex (Recommended)", description: `Run all ${issueIds.length} issues via team-planex` }, { value: "wave1", label: "Execute first wave", description: "Run wave-1 issues only" }, { value: "view", label: "View issues", description: "Display issue details" }, { value: "done", label: "Done", description: "Save and exit" } ] } ]) // BLOCKS (wait for user response) nextStep = answer.next } -
Execute Selection
switch (nextStep) { case 'planex': // Launch team-planex with all issue IDs Bash(`ccw skill team-planex ${issueIds.join(' ')}`) break case 'wave1': // Filter issues by wave-1 tag Bash(`ccw skill team-planex --tag wave-1 --session ${sessionId}`) break case 'view': // Display issues from issues.jsonl Bash(`ccw issue list --session ${sessionId}`) break case 'done': // Output paths and end console.log(`
Roadmap saved: ${sessionFolder}/roadmap.md Issues created: ${issueIds.length}
To execute later: $team-planex ${issueIds.slice(0, 3).join(' ')}... ccw issue list --session ${sessionId} `) break }
**Success Criteria**:
- User selection executed
- Session complete
- All artifacts accessible
---
## Error Handling
| Error | Resolution |
|-------|------------|
| cli-explore-agent fails | Skip code exploration, proceed with pure requirement decomposition |
| cli-roadmap-plan-agent fails | Retry once, fallback to manual decomposition prompt |
| No codebase | Normal flow, skip exploration step |
| Circular dependency detected | Prompt user, re-decompose |
| User timeout in feedback loop | Save roadmap.md, show `--continue` command |
| Max rounds reached | Force proceed with current roadmap |
| Session folder conflict | Append timestamp suffix |
---
## Core Rules
1. **Start Immediately**: First action is session initialization, then Phase 1 execution
2. **Single Source**: All context embedded in roadmap.md, no separate JSON files
3. **Iterate on Roadmap**: Use feedback rounds to refine, not recreate
4. **Testable Convergence**: criteria = assertions, DoD = business language
5. **Explicit Lifecycle**: Always close_agent after wait completes to free resources
6. **DO NOT STOP**: Continuous workflow until handoff complete
---
## Best Practices
1. **Clear Requirements**: Detailed description → better decomposition
2. **Iterate on Roadmap**: Use feedback rounds to refine convergence criteria
3. **Testable Convergence**: criteria = assertions, DoD = business language
4. **Use Continue Mode**: Resume to iterate on existing roadmap
5. **Wave Execution**: Start with wave-1 (MVP) to validate before full execution
---
## Usage Recommendations
**When to Use Roadmap vs Other Skills:**
| Scenario | Recommended Skill |
|----------|------------------|
| Strategic planning, need issue tracking | `$roadmap-with-file` |
| Quick task breakdown, immediate execution | `$lite-plan` |
| Collaborative multi-agent planning | `$collaborative-plan-with-file` |
| Full specification documents | `$spec-generator` |
| Code implementation from existing plan | `$lite-execute` |