/roadmap

name: roadmap
description: "Plan and execute entire application builds. Generates phased delivery roadmaps, then executes them autonomously — phase by phase, committing at milestones, deploying, testing, and continuing until done or stuck. Modes: plan (generate roadmap), start (begin executing), resume (continue from where you left off), status (show progress). Triggers: 'roadmap', 'start building', 'resume the build', 'keep going', 'build the whole thing', 'execute the roadmap', 'what phase are we on'."
compatibility: claude-code-only
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash

Roadmap

Generate a comprehensive technical roadmap for building an entire application. Detailed enough that Claude Code can pick up any phase and execute it autonomously for hours.

This is not a high-level strategy doc. It's a **delivery blueprint** — every phase has concrete tasks, every task is actionable, and the whole thing is ordered so you can build from phase 1 through to launch without backtracking.

When to Use

• Starting a major new product (after deep-research, or from a product brief)
• Converting a vague idea into an executable plan
• Planning a multi-week build that will span many Claude Code sessions
• Before saying "build this" — the roadmap is what you hand Claude Code to execute

Inputs

The skill needs one of these:

| Input | Where to find it | |-------|-----------------| | Deep research brief | `.jez/artifacts/research-brief-{topic}.md` (from `/deep-research`) | | Product brief | User describes what they want to build | | Existing partial app | Read CLAUDE.md + codebase to understand what exists | | Competitor to clone/improve | URL or product name — skill analyses it |

If the user just says "plan a note-taking app on Cloudflare", that's enough — ask clarifying questions as needed.

Workflow

1. Establish the Vision

Before any technical planning, nail down:

• **One sentence**: What is this? ("A cloud-native markdown knowledge workspace for teams and AI agents")
• **Who**: Primary users, secondary users, agents? ("Jez first, then Jezweb team, then clients")
• **Why**: What existing tools fail at? What's the gap? ("Existing tools are headless — you can't browse them or stumble across things")
• **Constraint**: Stack, budget, timeline, must-haves? ("Cloudflare, must have MCP, needs to be a PWA")
• **Not building**: What's explicitly out of scope? ("No real-time CRDT collab, no plugin ecosystem")

2. Define the Stack

Based on the vision and constraints, lock in the technical stack:

| Layer | Choice | Why |
|-------|--------|-----|
| Frontend | [framework] | [reason] |
| Backend | [framework + runtime] | [reason] |
| Database | [engine + ORM] | [reason] |
| Auth | [provider] | [reason] |
| Storage | [service] | [reason] |
| Search | [method] | [reason] |
| Hosting | [platform] | [reason] |

If a deep-research brief exists, pull the recommendations from there. If not, make opinionated choices based on the user's existing stack (check `~/Documents/` for patterns).

3. Design the Data Model

Sketch all tables/collections the full product will need. Not just phase 1 — the complete model. This prevents schema redesigns mid-build.

## Data Model

### [entity]
  id, [type]
  [field], [type], [constraints]
  ...
  created_at, updated_at

### [entity]
  ...

### Relationships
- [entity] has many [entity] via [field]
- [entity] belongs to [entity] via [field]

Mark which tables are needed in which phase. Phase 1 might only need 3 of 8 tables, but designing them all upfront avoids migration pain.

4. Plan the Phases

This is the core of the roadmap. Each phase must:

• **Have a clear goal** — one sentence describing what's different when this phase is done
• **Be independently deployable** — the app works (with reduced features) after each phase
• **Build on the previous phase** — no phase requires ripping out what came before
• **Be completable in 1-3 Claude Code sessions** — if a phase takes more than a day, split it

Phase Structure

For each phase:

## Phase N — [Name]
*Goal: [One sentence — what the user can do after this phase that they couldn't before]*
*Depends on: Phase N-1*
*Estimated effort: [hours/sessions]*

### What's New
[Bullet list of user-visible features]

### Database Changes
[New tables, new columns, migrations needed]

### API Routes
[New endpoints this phase adds]

### Frontend
[New pages, components, UI changes]

### Infrastructure
[New Cloudflare resources, secrets, config]

### Task Checklist
[Actionable tasks grouped by area — these are what Claude Code executes]

#### Setup
- [ ] [task]

#### Data Layer
- [ ] [task]
- [ ] [task]

#### API
- [ ] [task]

#### Frontend
- [ ] [task]

#### Testing & Polish
- [ ] [task]
- [ ] [task]

### Definition of Done
[How to verify this phase is complete — what to test, what to deploy]

5. Phase Planning Patterns

Phase 1 — Always the MVP

The first phase must produce something **usable by one person for one purpose**. Not a demo, not a skeleton — a working tool that replaces whatever the user currently does (even if it's a spreadsheet or Apple Notes).

Phase 1 scope test: "Would you use this instead of what you use now?" If no, the MVP is too thin.

Typical Phase 1:

• Auth (single user or invite-only)
• Core data model (2-3 tables)
• CRUD for the primary entity
• Basic UI (list + detail + create/edit)
• Deploy to production domain
• Bare minimum styling (dark mode, responsive)

Phase 2 — Make It Real

The second phase turns the MVP into something you'd show to others:

• Polish the UI
• Add secondary features (search, filters, sort)
• Better error handling and validation
• Empty states and onboarding (use the `onboarding-ux` skill)
• Mobile responsiveness
• Data export/import

Phase 3 — The Differentiator

What makes this product different from alternatives? Build that here:

• AI features, MCP server, semant