Writing Your Plans

The two files you own

Blueprint generates project context, feature specs, and history from two files you write and maintain. They stay useful after the first release because the build plan continues as the project’s living roadmap. Everything downstream depends on them, so they are worth getting right.

You own both. Write them directly, develop them through any AI conversation, or use the optional /discovery command for a guided deep planning session. The decisions are always yours. When they change, edit them and re-run /overview rather than hand-editing the generated context.

Optional guided discovery

$discovery in Codex or /discovery in Claude Code starts an adaptive planning conversation. It asks one focused question at a time, follows consequential answers, and periodically summarizes confirmed decisions and remaining gaps.

There is no fixed question count. When you say the project is ready, Discovery shows full drafts for both plans and waits for explicit approval before writing either file. It keeps the project plan detailed and the build plan concise.

This does not replace the manual path. Onboarding never runs Discovery, and Overview accepts plans written directly or through any conversation. See the Discovery command for its exact boundaries.

project-plan.md

Use as much detail as the project needs. Preserve rationale, constraints, examples, edge cases, tradeoffs, and exclusions that later feature work should not have to rediscover. The example below is intentionally concise, but a real project plan can be much longer.

# Project Plan

## 1. Problem - What problem are we solving?
Sticking to daily habits is hard without visible progress.

## 2. Users - Who is this for?
Individuals building personal routines who want a simple daily tracker.

## 3. Features - What does the MVP need?
Create habits, check them off each day, see streaks, and view a weekly summary.

## 4. Data - What are we storing?
Users, habits, and daily completions.

## 5. Tech - What stack are we using?
Next.js, Postgres, and Tailwind. Use whatever stack you prefer.

## 6. Monetize - How will this make money?
Free core tracker, with an optional paid tier for cross-device sync.

## 7. UI/UX - How should this look and feel?
Calm, mobile-first, and fast. One clear action per day.

## 8. Deployment - Where and how will this ship?
Vercel, with Postgres for storage and the standard framework build.

build-plan.md

This is the file the build loop tracks, so its shape matters most. It must be a numbered checkbox list where each item is a feature-sized outcome, not a loose task or a whole product area.

# Build Plan

- [ ] 1. **Habit list** - create, rename, and delete habits
- [ ] 2. **Daily check-in** - mark a habit done for today
- [ ] 3. **Streak view** - show current and longest streak per habit
- [ ] 4. **Weekly summary** - completion rate for the past seven days
- [ ] 5. **Deployment readiness** - configure the host and verify the production build

/feature with no argument specs the next unchecked item, and completed features get checked off here, so the list doubles as your progress tracker. A large item gets split into sub-items (4a, 4b) when you spec it.

Continue after the initial build

Do not replace the build plan when the first set of features is complete. Keep completed items checked, preserve their numbers, and append new unchecked features. Milestone headings keep a longer plan readable without changing how /feature finds the next item.

## MVP

- [x] 1. **Habit list** - create, rename, and delete habits
- [x] 2. **Daily check-in** - mark a habit done for today

## Post-MVP

- [ ] 3. **Shared habits** - invite another user to track a habit together
- [ ] 4. **Reminder schedule** - choose when habit reminders are sent

For an incremental feature, add a line to build-plan.md, re-run /overview, then continue with /feature. Update project-plan.md too only when the feature changes the product direction, users, data, stack, monetization, UI/UX, or deployment.

You can also run /feature "shared habits". If no existing item matches, the skill proposes a feature-sized plan line, its placement, and any required project-plan changes. It waits for your approval, refreshes the overview, and then writes the feature spec. Bugs and small unplanned changes still use /fix and do not become roadmap items.

Keep items feature-sized

Do not list scaffolding or prototyping as features; those are pre-build steps. Start with your first real slice of functionality.

Before you run overview

Rough bullets are fine on the first pass. /overview checks the plan shape, flags placeholders and vague items, and can propose a cleaned-up checkbox version before generating the project overview. Fill in both files directly, through any AI conversation, or with optional Discovery, then run it.