Overview

overview - turn the two plans into the AI-facing source of truth

Context reuse: Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.

First action: Before project inspection, preflight, or any other tool call, publish running to blueprint/.state/run.json using the dashboard activity contract in AGENTS.md.

Where this sits in the workflow:

project-plan.md  +  build-plan.md  ->  [this skill]  ->  project-overview.md  ->  /feature  ->  build
(what & why,         (high-level                          (compact product         (one spec
 written by you)      feature list,                        context loaded            at a time)
                      written by you)                      on demand)

You provide two files: blueprint/project-plan.md (what & why) and blueprint/build-plan.md (the ordered feature list), drafted directly, through any AI conversation, or with the optional /discovery skill. What matters is that you own their content. /discovery is never required. Everything else in the workflow is generated from those two. This skill is the first generation step: it distills both plans into blueprint/context/project-overview.md, the compact doc workflow skills load on demand when they need durable product context.

Input

The two planning docs, already written:

• blueprint/project-plan.md - problem, users, features, data, tech, monetization, UI/UX, deployment, and optional usage model
• blueprint/build-plan.md - the ordered, one-line-per-feature list; bullets, numbered lists, and clearly separated feature lines are accepted

If project-plan.md is missing or still a placeholder, ask the user to supply their project decisions. This skill distills plans; it does not invent them. For a missing or placeholder-only build plan, follow Step 2's reviewed reconciliation instead of generating an overview without a real feature list.

Placeholder text means the blueprint template's own scaffolding, not real content: unchanged starter instructions, legacy checklist items like Feature one / Feature two, a trailing - description, TODO, TBD, or the template's example bullets left in place. Starter instructions are not features. Watch for the masking trap in particular: build-plan.md can still be the stub while project-plan.md §3 already lists the real features. When that happens the overview can be synthesized from project-plan.md alone and come out looking complete, hiding the empty checklist that /feature actually reads. A rich project-plan.md must not paper over a stub build-plan.md - reconcile the checklist first (Step 2) rather than generating over the gap.

Step 1 - read both plans

Read project-plan.md and build-plan.md in full. Note where they disagree - a feature in the build plan the project plan never mentions, a data point no feature uses, a stack choice that contradicts a standard. You will surface these, not paper over them.

Step 2 - validate plan shape

Before writing project-overview.md, check that the plans are shaped well enough to drive the build loop.

Format clear feature lists automatically. Invoking /overview authorizes syntax-only formatting without an extra approval pause. Convert plain bullets, ordinary numbered lists, or clearly separated feature lines into tracked numbered checkboxes, such as - [ ] 1. Save an article. A valid tracked checklist stays byte-for-byte unchanged.

Preserve wording, order, feature count, notes, headings, nesting, existing IDs, and completion markers, including [X]. Add only missing tracking syntax:

• Preserve explicit numbered identities, including lettered child IDs.
• Give unnumbered features unused IDs. Check the existing plan, active work, and archived feature identities first; never renumber existing items or reuse an ID from history or active work.
• Keep child relationships and attached notes intact. Do not turn nested notes into features or flatten the hierarchy.
• You may remove unchanged shipped starter guidance only. Preserve user notes.

Ask for clarification before editing when structure, identities, scope, or build order are unclear, including duplicate IDs or ambiguous feature boundaries. Adding, removing, splitting, combining, reordering, or changing feature meaning requires a user decision; none is syntax-only formatting. Flag vague items, oversized bundles, pre-build setup chores, and disagreements between the two plans instead of silently rewriting them. Minor gaps that do not affect scope or build order can remain in the final report.

Missing or stub build plan. If build-plan.md is missing, empty, or only starter guidance/placeholders while project-plan.md lists real features, propose a checklist derived from those features and wait for approval before writing it. This is reviewed reconciliation, not automatic formatting. If neither plan supplies real features, ask the user for their feature list; never invent one. Do not generate the overview while the build plan remains missing or a stub.

Save the formatted checklist or approved reconciliation in build-plan.md before generating the overview. Briefly report any formatting performed. Formatting authority does not change Git or other approval gates.

Step 3 - synthesize the overview

Write blueprint/context/project-overview.md (create blueprint/context/ if needed), following reference/project-overview-template.md. The overview is a consolidation, not a copy:

After the title, write a plan fingerprint in this exact form:

<!-- blueprint:source-hash <sha256> -->

Read the final saved plan bytes after any formatting or approved reconciliation. Before hashing, normalize only build-plan completion markers by replacing each - [x] or - [X] marker with - [ ], while preserving indentation and every other byte. Compute <sha256> from the exact UTF-8 bytes of project-plan.md, one zero byte, then the normalized UTF-8 bytes of build-plan.md. This lets /status detect real plan changes after cloning, copying, or updating without treating completed features as overview drift. Replace the previous marker every time this skill regenerates the overview.

• One source of truth. Merge both plans into one coherent document. After this runs, the AI reads the overview, not the raw plans.
• Make the data model concrete. Turn the plan's data list into actual models with fields, types, and relationships, derived from the features that use them. This is the most valuable thing the overview adds.
• Tie features to build order. List the features with a one-line purpose each, in build-plan order, so the AI knows what exists and what's next.
• Carry deployment constraints forward. If the plan names Render, Vercel, build commands, env vars, health checks, or provider constraints, include them in a short Deployment section. If deployment is unknown, mark it > TODO.
• Carry confirmed usage constraints forward. Preserve established scale, reachability, trust, tenancy, security, compliance, availability, audit constraints, and explicit non-requirements in a compact Usage model section. Omit it when the usage-model section, section 9 in the shipped worksheet, is absent, unanswered, or contains only worksheet prompts. Never turn missing usage facts into enterprise, hostile, multi-tenant, or single-user requirements.
• Stay faithful. Don't add features, data, or stack choices that aren't in the plans. If something is underspecified, leave a clearly marked > TODO rather than inventing an answer.
• Keep the overview compact. Never copy long plan passages. The generated overview must remain below 20,000 bytes. Measure it before the final handoff. If a draft is larger, compact narrative and repeated lists while preserving concrete contracts, build order, and constraints. If those distinct facts cannot fit, stop and identify which plan section needs to be split or moved to a focused reference instead of writing an oversized overview.
• Write one generated context file. This skill writes blueprint/context/project-overview.md, the syntax-only build-plan formatting above, and any separately approved plan changes only. Never create additional generated context files such as data-model.md, architecture.md, or open-questions.md unless the user explicitly requests a separately scoped artifact.

Report what you wrote and list any contradictions or gaps you found between the two plans, so the user can fix the plans and re-run. Then apply the initial planning baseline handoff below before giving the next-step guidance.

In the next-step guidance, keep /feature as the main path. If the UI direction still feels unsettled, also mention that /prototype is available before /feature: it writes throwaway static HTML/CSS mockups to prototypes/ and does not modify the main app code.