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

Direct Mode

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

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 (detail view)

ccw issue list ISS-20260227-001

List all with status filter

ccw issue list --status planned,queued ccw issue list --brief # JSON minimal output

Queue operations (wave-based execution)

ccw issue queue list # List all queues ccw issue queue dag # Get dependency graph (JSON) ccw issue next --queue <queue-id> # Get next task

Execute

ccw issue queue add <issue-id> # Add to active queue ccw issue done <item-id> # Mark completed

Note: Issues are tagged with wave-N in tags[] field for filtering. Use --brief for programmatic parsing.

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 -m specified 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)

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 {
    // CONSTRAINT: All modifications below ONLY touch roadmap.md and issues.jsonl
    // NEVER modify source code or project files during interactive rounds
    switch (feedback.feedback) {
      case 'scope':
        // Collect scope adjustments
        const scopeAdjustments = ASK_USER([
          { id: "adjustments", type: "text", prompt: "Describe scope adjustments needed:" }
        ])  // BLOCKS

        // Update ONLY roadmap.md Roadmap table + Convergence sections
        Edit({ path: `${sessionFolder}/roadmap.md`, /* scope changes */ })
        // Update ONLY issues.jsonl entries (scope/context fields)

        break

      case 'convergence':
        // Collect convergence refinements
        const convergenceRefinements = ASK_USER([
          { id: "refinements", type: "text", prompt: "Describe convergence refinements needed:" }
        ])  // BLOCKS

        // Update ONLY roadmap.md Convergence Criteria section
        Edit({ path: `${sessionFolder}/roadmap.md`, /* convergence changes */ })

        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 (updates roadmap.md + issues.jsonl only)
        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}`
    ].join('\n'))
    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

- Start Immediately: First action is session initialization, then Phase 1 execution

- Single Source: All context embedded in roadmap.md, no separate JSON files

- Iterate on Roadmap: Use feedback rounds to refine, not recreate

- Testable Convergence: criteria = assertions, DoD = business language

- Explicit Lifecycle: Always close_agent after wait completes to free resources

- DO NOT STOP: Continuous workflow until handoff complete

- Plan-Only Modifications: Interactive feedback (Phase 3) MUST only update roadmap.md
 and issues.jsonl
. NEVER modify source code, configuration files, or any project files during interactive rounds. Code changes happen only after handoff (Phase 4) via team-planex or other execution skills

Best Practices

- Clear Requirements: Detailed description → better decomposition

- Iterate on Roadmap: Use feedback rounds to refine convergence criteria

- Testable Convergence: criteria = assertions, DoD = business language

- Use Continue Mode: Resume to iterate on existing roadmap

- 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
$workflow-lite-plan

Now execute roadmap-with-file for: $ARGUMENTS