# Roadmap Builder

> Interactive roadmap creation through structured questioning, optimized for ephemeral execution

- Skill: `yarlson/roadmap-builder` (Agent Skill)
- Install (CLI): `npx skillmds add yarlson/roadmap-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yarlson/roadmap-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: yarlson (https://skillmd.com/u/yarlson)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/yarlson/roadmap-builder

---


# Roadmap Builder

Create execution-ready roadmap through one-question-at-a-time dialogue.

## Process

Ask questions one at a time. Use AskUserQuestion tool with clear options.

### Questions Sequence

**1. Project name?**

- Free text input
- Example: "Calculator CLI"

**2. Programming language?**

- Options: Python, Go, Rust, TypeScript, Java, Other
- If Other: ask for specific language

**3. Test command?**

- Show common options for selected language:
  - Python: `pytest tests/ -v`
  - Go: `go test ./... -race -cover`
  - Rust: `cargo test`
  - TypeScript: `npm test` or `jest`
  - Java: `mvn test` or `gradle test`
- Allow custom command

**4. Lint command?**

- Show common options for selected language:
  - Python: `ruff check .` or `pylint`
  - Go: `golangci-lint run ./...`
  - Rust: `cargo clippy --all-targets`
  - TypeScript: `eslint .`
  - Java: `mvn checkstyle:check`
- Allow custom command

**5. One-sentence project goal?**

- Free text input
- Example: "Build a command-line calculator with expression parsing"

**6. How many phases?**

- Options: 2, 3, 4, 5, 6, More than 6
- Recommend: 3-6 phases for most projects

**7-N. For each phase, ask:**

- **Phase name?** (e.g., "Foundation", "Core Feature", "Integration")
- **Phase goal?** (one sentence, what this phase accomplishes)
- **Success criteria?** (2-4 measurable outcomes)
  - Ask: "What are 2-4 things that must work when this phase is done?"
  - Examples: "Calculator.add() works", "Tests pass", "CLI parses input"

### Build Roadmap YAML

After gathering all info, create roadmap at:
`docs/roadmaps/[YYYY-MM-DD]-[project-name-slug]-roadmap.yml`

Format:

```yaml
proj:
  name: "[Project Name]"
  lang: "[Language]"
  test: "[Test Command]"
  lint: "[Lint Command]"
  goal: "[One-sentence goal]"

phases:
  - id: 0
    name: "[Phase Name]"
    goal: "[Phase goal]"
    success:
      - "[Success criterion 1]"
      - "[Success criterion 2]"
      - "[Success criterion 3]"

  - id: 1
    name: "[Phase Name]"
    goal: "[Phase goal]"
    success:
      - "[Success criterion 1]"
      - "[Success criterion 2]"
```

### Validate Roadmap

Check:

- All required fields present
- Phase IDs sequential (0, 1, 2, ...)
- Each phase has 2-4 success criteria
- Valid YAML syntax

### Output

Display:

```
✅ Roadmap created: docs/roadmaps/[filename]

Project: [name]
Language: [lang]
Phases: [count]

To execute:
/autonomous-dev docs/roadmaps/[filename]

To review first:
cat docs/roadmaps/[filename]
```

## Tips for Good Roadmaps

**Phase granularity:**

- Each phase: 2-8 hours of work
- Too small: overhead of phase management
- Too large: hard to review, risky

**Success criteria:**

- Specific and measurable
- Testable (can verify with command)
- Clear definition of done

**Phase sequencing:**

- Foundation first (structure, utilities)
- Core features next (main functionality)
- Integration/polish last (CLI, API, docs)

**Examples:**

Good success criteria:

- "Calculator.add() returns correct sum"
- "Parser handles nested parentheses"
- "CLI prints result to stdout"

Bad success criteria:

- "Code is good" (not measurable)
- "Everything works" (not specific)
- "Ready for production" (ambiguous)