$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"

• -y, --yes

  : Skip all confirmations (auto mode)

• -c, --continue

  : Continue existing session

• -m, --mode

  : Strategy selection (progressive / direct / auto)

.workflow/.roadmap/{session-id}/

roadmap.md

issues.jsonl

1. Read role definition: ~/.codex/agents/{agent-type}.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

• ≥3 high uncertainty factors → Progressive
• ≥3 low uncertainty factors → Direct
• Otherwise → Ask user preference

• Uncertainty Level: {high|medium|low}
• Decomposition Mode: {progressive|direct}
• Assessment Basis: {factors summary}
• Goal: {extracted goal}
• Constraints: {extracted constraints}
• Stakeholders: {extracted stakeholders}

• Criteria: [testable conditions]
• Verification: [executable steps/commands]
• Definition of Done: [business language, non-technical]

• Relevant Modules: [...]
• Existing Patterns: [...]
• Integration Points: [...]

---

1. Parse Requirement
   • Extract: goal, constraints, stakeholders, keywords
2. Assess Uncertainty
   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'
   }
   
   // 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

3. Strategy Selection (skip if

   -m

   specified or AUTO_YES)
   javascript

   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
   }

4. Initialize roadmap.md
   javascript

   const roadmapContent = `# Requirement Roadmap

• Uncertainty Level: ${uncertaintyLevel}
• Decomposition Mode: ${selectedMode}
• Assessment Basis: ${factorsSummary}
• Goal: ${extractedGoal}
• Constraints: ${extractedConstraints}
• Stakeholders: ${extractedStakeholders}

To be populated after Phase 2 decomposition

To be populated after Phase 2 decomposition

To be populated after Phase 2 decomposition

To be populated during Phase 3 refinement

To be populated if codebase exploration was performed `

${sessionFolder}/roadmap.md

**Success Criteria**:
- roadmap.md created with Strategy Assessment
- Strategy selected (progressive or direct)
- Uncertainty factors documented

---

cli-roadmap-plan-agent

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: `

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

• Requirement: ${requirement}
• Strategy: ${selectedMode}
• Project Type: ${hasCodebase}
• Session: ${sessionFolder}

• Identify modules/components related to the requirement
• Find existing patterns that should be followed
• Locate integration points for new functionality
• Assess current architecture constraints

1. Read role definition: ~/.codex/agents/cli-roadmap-plan-agent.md (MUST read first)
2. Read: .workflow/project-tech.json
3. Read: .workflow/project-guidelines.json

• Requirement: ${requirement}
• Selected Mode: ${selectedMode}
• Session ID: ${sessionId}
• Session Folder: ${sessionFolder}

• 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` :

• 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`}

• 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)

1. Update ${sessionFolder}/roadmap.md with Roadmap table + Convergence sections
2. Create issues via ccw issue create - append to .workflow/issues/issues.jsonl

• 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}

1. Analyze requirement and build decomposition context
2. Execute decomposition (internal reasoning)
3. Validate records, check convergence quality
4. For each decomposed item:
   • Run: ccw issue create --title "..." --context "..." --tags "..." --priority N
   • Record returned Issue ID
5. Update roadmap.md with Issue ID references
6. 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 || []

   undefined

• Issues created in

  .workflow/issues/issues.jsonl

• roadmap.md updated with Issue references
• No circular dependencies
• Convergence criteria testable

1. Display Current Roadmap
   • Read and display Roadmap table + key Convergence criteria
   • Show issue count and wave breakdown
2. Feedback Loop (skip if AUTO_YES)
   javascript

   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 = `

       Edit({          path:

,          old_string: "## Iteration History\n\n> To be populated during Phase 3 refinement",          new_string: 

3. **Finalize Iteration History**
```javascript
// Update final status in roadmap.md
Edit({
  path: `${sessionFolder}/roadmap.md`,
  old_string: "**Status**: Planning",
  new_string: "**Status**: Ready"
})

• User approved OR max rounds reached
• All changes recorded in Iteration History
• roadmap.md reflects final state

1. Display Summary
   markdown

   ## 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 |

2. Offer Options (skip if AUTO_YES)
   javascript

   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
   }

3. Execute Selection
   javascript

   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
   }

• User selection executed
• Session complete
• All artifacts accessible

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
7. 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

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