roadmap

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, 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)
• Integrations (API, webhooks, third-party connections)
• Admin / settings
• Performance optimisation
• Public-facing features (sharing, embedding, white-label)

Final Phase — Platform

Only if the product is heading toward multi-tenant / SaaS:

• Client workspaces
• Billing / plans
• White-label / custom domains
• API tokens for third-party access

6. Build Order

Summarise the phases in a table:

| Phase | Goal | New tables | New routes | Sessions |
|-------|------|-----------|-----------|----------|
| 1 | Personal MVP | 3 | 8 | 2-3 |
| 2 | Polish + search | +1 | +4 | 1-2 |
| 3 | AI + MCP | +1 (vectors) | +5 | 2-3 |
| 4 | Team features | +2 | +6 | 2-3 |
| 5 | Integrations | 0 | +4 | 1-2 |
| 6 | Platform | +2 | +8 | 3-4 |

7. Deliberately Not Building

List what's explicitly out of scope and why. This prevents scope creep during execution:

## Deliberately Not Building (v1)

- Real-time collaborative editing (CRDTs) — too complex, Phase 5+ at earliest
- Plugin ecosystem — too much surface area
- Native mobile app — PWA is good enough
- Offline-first with local storage — we're cloud-native

8. Schema Evolution Map

Show how the database grows across phases:

| Table | Phase 1 | Phase 2 | Phase 3 | Phase 4 |
|-------|---------|---------|---------|---------|
| users | ✓ | | | |
| notes | ✓ | +tags col | +embeddings | |
| folders | ✓ | | | |
| note_links | | ✓ | | |
| workspaces | | | | ✓ |
| workspace_users | | | | ✓ |

9. API Surface Map

Show how the API grows:

| Route | Phase | Auth | Purpose |
|-------|-------|------|---------|
| POST /api/auth/* | 1 | — | Authentication |
| GET/POST /api/notes | 1 | Yes | Note CRUD |
| GET /api/search | 2 | Yes | Full-text search |
| GET /api/search/semantic | 3 | Yes | Vector search |
| GET/POST /mcp/tools | 3 | Token | MCP interface |
| 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