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
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/roadmap
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
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
📊 Stats
Stars940
Forks96
LanguagePython
LicenseMIT
📦 Ships with jezweb-skills
</> SKILL.md
roadmap.SKILL.md
---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
| 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:
```markdown
| 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.
```markdown
## 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:
```markdown
## 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, semantic search
- The thing competitors don't have
- The reason someone would choose this over the established player
#### Phase 4+ — Growth Features
Each subsequent phase adds capabilities:
- Multi-user / team features
- Advanced views (graph, canvas, calendar, kanban)
| POST /api/workspaces | 4 | Yes | Team workspaces |
```
## Output
Write the roadmap to `docs/ROADMAP.md` (or the project root if no `docs/` exists).
The file should be a single markdown document that Claude Code can read at the start of any session and know exactly what to build next. It's the project's north star.
After generating, also update:
- `CLAUDE.md` — add a reference to the roadmap
- `SESSION.md` — set current phase
## Quality Rules
1. **Every task must be actionable** — "Set up auth" is too vague. "Configure better-auth with email/password, create user and session tables, add auth middleware to Hono" is actionable.
2. **Phases must be deployable** — after each phase the app works. No "infrastructure phase" that produces nothing usable.
3. **Phase 1 must be ruthlessly small** — if it takes more than 2-3 sessions, cut scope.
4. **The data model must be complete upfront** — schema redesigns mid-build are the #1 time waster.
5. **"Deliberately not building" is mandatory** — without it, every phase grows.
6. **Tasks are grouped by layer** (data, API, frontend, infra) — Claude Code works in layers, not features.
7. **Each phase has a definition of done** — specific things to test and verify.
8. **Include the stack table** — don't make Claude guess the tech choices per phase.
---
## Execution Modes
The roadmap isn't just a document — it's an execution engine. After generating the plan, use these modes to drive the build.
### Mode: `start`
**Trigger**: "start building", "execute the roadmap", "build the whole thing", "start from phase 1"
1. Read `docs/ROADMAP.md`
2. Verify the project is set up (repo exists, dependencies installed, Cloudflare resources created)
3. Begin Phase 1, task by task
4. After each task: verify it works (build, run, test)
5. After all tasks in a phase: run the Definition of Done checks
6. Commit: `git add -A && git commit -m "Phase N complete: [goal]"`
7. Deploy if applicable: `npx wrangler deploy`
8. Run `/ux-audit quick` on the deployed app
9. Update the roadmap: mark the phase as complete
10. **Continue to the next phase. Don't stop. Don't ask.**
11. Repeat until all phases are complete or you hit a blocker
### Mode: `resume`
**Trigger**: "resume the build", "keep going", "continue", "what phase are we on"
1. Read `docs/ROADMAP.md` — find the first incomplete phase
2. Check `git log` — what was the last roadmap-related commit?
3. Check what exists in the codebase vs what the phase expects
4. Pick up from the first uncompleted task in the current phase
5. Continue executing as in `start` mode
### Mode: `status`
**Trigger**: "roadmap status", "where are we", "what's done"
Read `docs/ROADMAP.md` and produce a summary:
```
Phase 1: Personal MVP ✓ (committed abc1234)
Phase 2: Polish + Search ✓ (committed def5678)
Phase 3: AI + MCP ← IN PROGRESS (7/15 tasks done)
Phase 4: Team Features — not started
Phase 5: Integrations — not started
```
### Execution Rules
**Keep going.** The default is to continue to the next phase after completing one. Don't pause between phases to ask permission. The roadmap IS the permission.
**Commit at phase boundaries.** Every completed phase gets its own commit with a clear message. This creates natural restore points.
**Deploy after every phase.** If the project has a deployment target (wrangler.jsonc, vercel.json), deploy after each phase completes. Real deployment catches issues that local dev doesn't.
**Quick audit between phases.** Run a quick visual check on the deployed app between phases — catch layout issues, broken routes, obvious regressions before building on top of them.
**Thorough audit at the end.** After the final phase, run:
1. `/ux-audit thorough` — comprehensive overnight test
2. `/onboarding-ux` — generate empty states, welcome flow, help content
