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.

## 9. Usage model and constraints (optional)
Personal use, single user, local only. No compliance requirements.

Section 9 is optional. Record only established facts such as expected scale, local or internet-facing operation, trusted or adversarial users, tenancy, required security or compliance constraints, and explicit non-requirements. Leaving it blank is valid and means those facts are unknown. An unknown never becomes an enterprise, hostile, multi-tenant, or single-user requirement.

build-plan.md

Write one feature-sized outcome per line in build order. Plain bullets or a numbered list are enough: /overview adds numbered checkboxes automatically. You can also write the tracked format directly:

# 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

Clear feature lists are enough on the first pass. /overview adds only missing tracking syntax, preserving your wording, order, IDs, completion state, and attached notes. Valid checklists stay unchanged. The starter build plan keeps its checklist examples at the end for reference; replace the starter guidance with your own features.

Overview asks before changing feature meaning or order, splitting or combining items, or resolving ambiguous IDs. If only the project plan has real features, it proposes the missing build checklist for your approval first. Fill in both files directly, through any AI conversation, or with optional Discovery, then run Overview.