| name | planner-spec-expand |
| description | Expand a 1-4 sentence product brief into a full spec with a design language, acceptance surface, and an ordered feature list. |
| when_to_use | Bootstrapping a project from a one-liner prompt before any generator agent runs, re-planning after scope creep changes the target, producing the input document that feature-list-json will be seeded from |
| targets | ["*"] |
Planner Spec Expand
A one-line brief ("build a chat app clone", "a habit tracker with streaks") is not enough surface for a coding agent to make good decisions from. It has no design language, no acceptance criteria, no ordering. The generator ends up inventing scope mid-session and shipping incoherent slices.
The planner's job is to expand the brief into a spec dense enough that every downstream decision - what feature to pick, what "done" looks like, what the button should say - has an answer already written down. See Prithvi's post on planner/generator/evaluator separation for the underlying architecture: https://www.prithvirajrk.com/blog/three-agent-harness.
When to apply
- The user handed you a brief under ~200 words and expects a real product.
- You're about to seed [[feature-list-json]] and the brief has no orderable features yet.
- Scope drifted mid-project and the original spec no longer describes the target - rewrite, don't patch.
Procedure - expand in this order
Do the sections in order. Later sections depend on earlier ones being locked.
- Restate the brief in one paragraph. In your own words, what is being built and for whom. If you can't write this cleanly, ask the user before continuing - the brief is under-specified.
- Pick a design language. One sentence each on: visual tone (minimal / dense / playful), typography stance (one sans / serif+sans / mono accents), color posture (monochrome + one accent / two-color / full palette), density (airy / compact). This locks a thousand later micro-decisions.
- Enumerate the acceptance surface. For each user-observable capability, write one sentence of user-observable behavior AND the concrete steps a human would take to verify it. This is the shape [[feature-list-json]] wants - write it in that shape now.
- Order the features. Sort by dependency: nothing appears before what it depends on. Ties broken by "what does the user see first when they open the app." The top of the list must be runnable-alone.
- Name the out-of-scope. One short list of things the brief could imply but you are explicitly not building. Prevents the generator from wandering.
- Write the smoke path. The single user journey that proves the product exists - 3-6 steps end-to-end. This becomes the initializer's smoke test.
Checklist before you hand off
- Every feature has
description + steps in the shape [[feature-list-json]] expects.
- The first 3 features can be built in order with no forward dependency.
- Design language fits on one screen - if it's a page, you over-specified.
- Out-of-scope list is non-empty. If everything is in scope, you didn't plan, you transcribed.
- Smoke path touches the core value prop, not auth or settings.
Anti-patterns
- Padding the feature list to look thorough. 40 real features beats 200 fake ones. The generator will build all of them.
- Designing the schema. That's the generator's job. You describe user-observable behavior; the generator picks the data model.
- Writing prose where you should write steps. "User can manage conversations" is not a feature. "Clicking the trash icon on a sidebar item deletes that conversation and removes it from the sidebar" is.
- Leaving priority implicit. If two features tie, break the tie now. The generator will not.
When NOT to apply
Skip this for briefs already specified to acceptance-criteria depth, or for single-feature edits to an existing project - use [[shift-notes]] and pick from the existing [[feature-list-json]] instead.
Related: [[feature-list-json]], [[shift-notes]], [[broken-window-check]].
