Roadmap With File

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

const agentId = spawn_agent({
  agent_type: "{agent_type}",
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

const result = wait_agent({
  timeout_ms: 1800000  // 30 minutes
})

if (result.timed_out) {
  // Handle timeout via 4-step cascade: status probe → force finalize → close
}

followup_task({
  target: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent({ target: agentId })

┌─────────────────────────────────────────────────────────────────────────┐
│                    ROADMAP ITERATIVE WORKFLOW                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Session Init                                                            │
│     ├─ Parse flags, generate session ID                                  │
│     ├─ functions.exec_command (mkdir session folder)                      │
│     └─ functions.update_plan (5 phases: Understand → Decompose →         │
│        Refine → Handoff → GATE)                                          │
│                                                                          │
│  Phase 1: Requirement Understanding & Strategy                           │
│     ├─ Parse requirement: goal / constraints / stakeholders              │
│     ├─ Assess uncertainty level → recommend mode                         │
│     ├─ User confirms strategy via functions.request_user_input           │
│     └─ Initialize roadmap.md with Strategy Assessment                    │
│                                                                          │
│  Phase 2: Decomposition & Issue Creation                                 │
│     ├─ Optional codebase exploration (functions.exec_command detection)   │
│     ├─ 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, Decision Recording)         │
│     ├─ Present roadmap to user (Cumulative Context)                      │
│     ├─ Feedback via functions.request_user_input:                        │
│     │   Approve | Adjust Scope | Refine Criteria | Research/Re-decompose │
│     ├─ External research via web.run (optional — patterns, practices)    │
│     ├─ Record decisions in Iteration History (Record-Before-Continue)     │
│     └─ Repeat until approved (max 5 rounds)                              │
│                                                                          │
│  Phase 4: Handoff (PLANNING ENDS HERE)                                   │
│     ├─ Final roadmap.md with Issue ID references                         │
│     └─ MANDATORY Terminal Gate: 执行计划 / 查看Issue / 完成              │
│         ├─ Execute Plan → display csv-wave-pipeline command               │
│         ├─ View Issues → ccw issue list                                  │
│         └─ Done → end workflow                                           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

.workflow/.roadmap/RMAP-{date}-{slug}/
└── 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 csv-wave-pipeline, issue commands

# Requirement Roadmap

**Session**: RMAP-{date}-{slug}
**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**: [...]

Path: .workflow/issues/issues.jsonl
Format: JSONL (one complete JSON object per line)
Encoding: UTF-8
Mode: Append-only (new issues appended to end)

{
  "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-{date}-{slug}",
      "strategy": "progressive|direct",
      "wave": 1,
      "depends_on_issues": []
    }
  },
  "lifecycle_requirements": {
    "test_strategy": "unit",
    "regression_scope": "affected",
    "acceptance_type": "automated",
    "commit_strategy": "per-issue"
  }
}

# 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

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-${dateStr}-${slug}`
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
}

functions.exec_command(`mkdir -p ${sessionFolder}`)

// Initialize progress tracking (MANDATORY)
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Requirement Understanding & Strategy", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "pending" },
  { id: "phase-3", title: "Phase 3: Iterative Refinement", status: "pending" },
  { id: "phase-4", title: "Phase 4: Handoff", status: "pending" },
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])

**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
// Update progress
functions.update_plan([{ id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "in_progress" }])

const hasCodebase = functions.exec_command(`
  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({
    agent_type: "cli_explore_agent",
    message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Read: .workflow/project-tech.json
2. 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_agent({
    timeout_ms: 1800000  // 30 minutes
  })

  close_agent({ target: exploreAgentId })

  if (exploreResult.status[exploreAgentId].completed) {
    codebaseContext = exploreResult.status[exploreAgentId].completed
  }
}

> **Decision**: [Description]
> - **Context**: [What triggered this]
> - **Options**: [What was considered]
> - **Chosen**: [Selected] — **Reason**: [Why]
> - **Impact**: [What changed in roadmap]