spec-feature

Feature Spec

Plan one feature to a depth that survives a fresh build session. The app foundation and design system were decided once at kickoff (spec-foundation, app-design-directions); here you go deep on one feature so the build produces what you pictured, not a generic default.

One feature = one attended session, ending on your sign-off. The build runs in a fresh session afterward (the spec must be self-contained enough to build from cold), then /verify-milestone, then review-feature.

Preconditions

The three movements assume four kickoff outputs exist: specs/00-product.md (the feature backlog), specs/01-architecture.md (data model + environment contract), specs/design.md + the built component gallery, and a green provision. When they do, pick the feature from 00-product.md's backlog + build order — spine-journey features first (a usable walking skeleton) — and run the movements below.

When some are missing, triage:

• A genuinely fresh, multi-feature greenfield app → run the kickoff sequence first (kickoff / spec-foundation).
• One feature against an existing codebase, or a small/contained product that consumes an existing engine / app / platform → don't run the full kickoff. Follow references/no-foundation.md: it satisfies each missing precondition by discovering it from the existing code, establishes the design referent Movement 2 needs, and seeds a minimal foundation, then returns you to the movements below.

The milestone-authoring + verification rules are in ${CLAUDE_PLUGIN_ROOT}/references/milestones-and-verification.md — read it; this skill applies those rules per feature and adds the per-feature design step. Do not restate them.

The three movements (one session, in order)

1. Interview the feature (deep)

Apply the interview discipline but at feature depth. Resolve:

• Every screen/surface this feature adds or touches, and what each shows.
• Every state per surface: empty/first-run (most-skipped), loading, error, partial, and the populated happy path.
• Every interaction: sort, filter, search, inline-edit, bulk action, keyboard, drag. Name them; don't leave them to builder defaults.
• The exact data each surface shows (fields, formats, derived values) — from the real data model in 01-architecture.md.
• The edges: permissions/role differences, validation, conflicts, the worst-case screen.
• Cross-feature seams: what existing surface this feature mounts into or links to — name the integration seam now, per the shared rules, or it's discovered at merge.

Scoped reference research — flows, not looks. When a design-reference MCP is connected and the feature has user-facing flows, the flow-level pull runs by default (Mobbin's search_flows) for interaction patterns. Run it per visual-reference.md's delegation mechanics only (a subagent that hands back compact text, never raw volume into this session), with the extraction flow-shaped and explicitly not that file's looks deconstruction pass (palette/type/density/depth), which stays banned in this movement. With no design-reference MCP connected, proceed text-only and record that mode. Findings land as UX-completeness done-conditions, never as tokens or visual choices; reference pulls for looks stay gated at Movement 2's two cases and nowhere else.

End with a one-paragraph feature definition and the resolved decision list. If you can't write that paragraph, you're not done interviewing. Then synthesize that understanding (plus any stack-profile delta) and get the user's explicit sign-off before Movement 2 — the confirm-before-author gate. Don't compose or author until the interview is confirmed.

2. Design the feature's screens (compose the real workbench)

No mockups are produced here — no standalone artifact to approve as the design. You are shown the real workbench composition — this feature's screens assembled from the already-themed gallery components — and the named workbench components are the fidelity reference the build matches and the verifier diffs against. The one exception is the optional divergence sketch for a genuinely novel archetype (below) — not the spec, not a deliverable.

Skip this movement for a no-UI feature (the profile's has-UI? verb, Q8.1): go to Movement 3 with two-dimension done-conditions (logic + behavioral completeness, no fidelity). Otherwise compose this feature's screens from the real workbench components:

• Compose from the locked system, don't re-explore. specs/design.md and the built gallery — the real workbench (Q8.3), the durable fidelity source of truth — own the palette, type, density, material palette (icons, motion, charts, primitives), and the signature element. Assemble the feature's screens from those real themed primitives; for the craft the system leaves open (motion, micro-interactions) apply ${CLAUDE_PLUGIN_ROOT}/references/interaction-craft.md and turn its principles into fidelity done-conditions (motion as tokens). Do not run app-design-directions — the direction is locked.
• Compose the screens into a feature story / preview. Assemble this feature's distinct screens/states from the real workbench components (Q8.3): real themed primitives in this feature's layout, carrying its real states with real domain data. This composition is the fidelity reference a verifier diffs against (§6 — not a static HTML file). At spec time the reference is named, not built as code (realized as real components at build time), so the plan PR stays plan-only (specs/** + design/**): point each pure-composition screen's fidelity done-condition at the named workbench/gallery components it composes — never at nothing — and if a real composed preview route is wanted early, it is design-gate infrastructure committed on main, never code in the plan PR. A bespoke mockup is optional and only for a genuinely novel layout archetype — a divergence sketch (design/mockups/<feature>/<screen>.html, diverge-cheap / converge-real) that is never the re-implemented spec. In the two looks-pull cases — this novel-archetype case and the gallery-absent content type below, and only those two — when a design-reference MCP is connected the reference pull per visual-reference.md's mechanics runs by default (source ladder, subagent delegation, deconstruction before use), with lineage (reference URLs + extraction notes) recorded in the feature spec. Lineage may cite only pulls that preceded the divergence point — before the sketch (novel-archetype) or before the primitive's design (content-grain, no sketch); a citation stapled on afterward is banned. Pure recomposition (content grain, next bullet) stays reference-free — it triggers no reference pull: the chosen archetype converges into the real composed workbench story at build time.
• Pure recomposition is content-grain — and a gallery-absent content type becomes a new workbench primitive. A screen is pure recomposition only when every content type it renders already exists in the gallery. A content type the gallery lacks — an email/message view, a timeline, rich text, an activity feed — is novel at content grain even when its screen archetype is standard, and triggers the reference pull per visual-reference.md's mechanics for that content type (delegation, lineage, pull-timing per the previous bullet). It becomes a new themed workbench primitive, added to the gallery in every state (Q8.3) exactly as controls are — never improvised inline; the milestone adding the surface owns adding the primitive, and the screen's fidelity done-condition names that primitive. The scar: an email panel's sender/subject/body rendered as identical body text — the composition named the containers, the content had no primitive and no condition.
• You redline it. Capture the composed feature story / preview (per the profile's screenshot / review driver, Q8.4 — open on macOS / xdg-open for the web reference) and present it for sign-off. The direction was redlined once at kickoff; each feature's screens are redlined here — clean compositions you may trust-and-proceed. The feature isn't ready to spec until the screens are signed off (or explicitly waved through).

3. Author the feature's milestones

Decompose the feature into 1–5 milestones (the build/verify unit) per ${CLAUDE_PLUGIN_ROOT}/references/milestones-and-verification.md. For this feature:

• Done-conditions span all three dimensions (§2): logic/invariants, UX completeness (the enumerated states + interactions from movement 1), and fidelity — tokens/fonts/themed-components/icon-set/charts, layout matches this feature's own workbench composition from movement 2 (by reference — the real themed gallery per Q8.3, not a static HTML file), and motion + interaction-states specced as tokens (§6 + the profile's motion verb, Q8.5 — named easing/duration and hover/pressed/focus/disabled deltas, plus reduce-motion).
• Tag each done-condition [auto] / [runtime] / [attended] (§2, §7). Route the deterministic core of every interaction to a committed test tier (Q11 — component-render or e2e), tagged [auto]: an open/close, a focus order, an edit that commits, a filter that re-derives are committed-test material, not walk material. Reserve [runtime] for what only a live runtime proves — the surface activates on dev + prod builds, the live call works, the system was visually applied — and have each [runtime] condition name the committed test covering its deterministic core (missing coverage blocks the pin, §3/§5). Nothing is inferred from a passing unit test alone.
• Check every done-condition against §1's three authoring anti-patterns (owned by the shared rules, not restated).
• **Every screen/route of the feature is

Content truncated.