Skill snapshot v1

frontend-feature-planner

Turn "bind this design to the API" into a concrete, editable plan — with the fewest questions possible — by reading the real backend so the binding contract is observed, not invented.

The premise: the design already exists (built by figma-to-component / html-to-component), the project was scaffolded by nextjs-bootstrap (BFF proxy, axios, Zod, TanStack Query, RHF, shared *Field components), and now the user wants to make it functional against a backend endpoint. Generic planners guess the API shape and the frontend ends up with types that don't match what the server actually returns. This skill goes and looks.

The output is a markdown file the user reads and edits by hand before any code is generated. This skill never writes binding code and never invokes frontend-module-builder.

Step 1 — Load the frontend contract (always first)

Resolve the project dir for the frontend domain via the protocol in ../LAYOUT.md: read .claude/workspace.json and use the frontend entry's folder; if there's no manifest but an ARCHITECTURE.md describing a Next.js/React app sits at the repo root, that's the legacy single-project layout. All frontend paths below — the contract files, the src/ greps, the _docs/ output — are relative to that project dir.

Read, in this order:

1. ARCHITECTURE.md (frontend) — the fixed conventions: BFF proxy is the only thing that talks to the backend, axios instance at lib/axios.ts (baseURL: "/api"), Zod for validation, types via z.infer, TanStack Query v5 for server-state with array query keys, RHF + shared *Field for forms, feature-module anatomy (types/ schema/ api/ hooks/ components/ template/ index.ts), component placement rule (generic → components/shared, domain → features/<name>/components).
2. MODULE_REGISTRY.md (frontend) — what already exists: shared form fields, typography, overlay, lib singletons (axios/query-client/env/auth), hooks, and any existing feature modules with their public surface.
3. Scan the existing design for this feature: grep src/features/<name>/ and src/components/shared/. You need to know which components are already built (so the plan binds those, by name and path) and which the design still needs (so you can flag the gap, not silently assume).

If the frontend contract files are missing, say so and offer to run frontend-onboard (or nextjs-bootstrap for an empty dir) first — don't invent frontend conventions.

Step 2 — Learn the REAL API contract (the signature step)

This is what makes the binding accurate. Follow the resolution ladder in references/reading-backend.md, taking the highest-fidelity source available:

1. Monorepo backend source (best) — the backend entry in .claude/workspace.json. Read the route → controller → service → schema → model chain for the requested capability and extract, per endpoint: method + path, auth guard, request shape (path params, query, body), the exact success envelope (e.g. { success, data, message }) and the data shape, status codes, and the error cases.
2. Backend contract files — if source isn't fully readable, read the backend's ARCHITECTURE.md (response envelope, error model) + MODULE_REGISTRY.md (the module's public surface) for the shape.
3. OpenAPI / Swagger — a spec file or URL: parse paths, request bodies, and response schemas.
4. User-pasted endpoint + sample — last resort: ask for the endpoint(s) and a real sample request/response.

Record where each fact came from (source path / spec / pasted) in the plan's API contract section. The frontend types, Zod schemas, and BFF must mirror this envelope exactly — a mismatch here is the #1 cause of broken bindings, so getting it from ground truth is the whole point. Never silently guess a field; if a fact is unavailable from every rung, flag it as an open question rather than inventing it.

Step 3 — Map design ↔ data

Cross-reference the observed API against the built design:

• Which existing components/screens render which response fields (name them by path).
• Design gaps — components the binding needs that aren't built yet → list them and point to figma-to-component / html-to-component. Plan the binding anyway (per the user's intent); don't block on the missing design.
• Data gaps — fields the design shows that the API doesn't return, or actions the design implies with no endpoint → flag as open questions.

Step 4 — Decide what's already answered

Cross off every question the frontend contract already settles, the way a teammate who knows the repo would. Examples:

• Don't ask "how do we call the backend" — it's the BFF proxy + axios instance, always.
• Don't ask "what validation library" or "where do types come from" — Zod + z.infer, fixed.
• Don't ask "how do we manage server state" — TanStack Query v5, array query keys namespaced by feature.
• Don't ask "what form components" — the shared *Field set, always.

Step 5 — Ask only the genuine unknowns

Use references/question-banks.md, then filter against Step 4 — ask only the survivors. Keep it tight (aim for ≤3–4 real decisions). These are product/UX choices the codebase can't answer: e.g. list vs detail vs both, pagination/infinite-scroll/filter UI, optimistic update vs invalidate-on-success, which mutations need a confirm modal, cache-invalidation scope, whether this feeds an existing route or a new one. If the user already specified some, honor those and don't re-ask.

Step 6 — Write _docs/FEATURE_PLAN_<name>.md

Write the plan to _docs/FEATURE_PLAN_<name>.md under the frontend project dir — create _docs/ if needed. Only ARCHITECTURE.md / MODULE_REGISTRY.md stay at the project-dir root; planner docs live under _docs/. Follow references/plan-template.md exactly. The non-negotiable sections:

• API contract (observed) — the ground truth from Step 2: an endpoints table (method/path/auth/request/response-data shape) and the exact success + error envelope, each with its source. This anchors everything downstream.
• Reuse (do NOT recreate) — explicit paths the binding will import rather than rebuild: the axios instance, BFF proxy, query-client, shared *Field components, useAuth, and any existing feature pieces / shared components from the registry. This commits the feature to dedup before code exists.
• Types & schema — the TS types and Zod schemas mirroring the observed envelope (types via z.infer, never parallel interfaces).
• Create — the new files by path, following feature-module anatomy, plus any BFF route handlers under app/api/ (note when the catch-all proxy already covers it).
• Data-binding map — component ↔ query/mutation hook ↔ fields. The concrete wiring.
• Query/mutation hooks — query keys, what each invalidates, loading/empty/error states.
• Design gaps — components still to build (→ figma-to-component / html-to-component), or "none".
• Edge cases & states — loading, empty, error, end-of-pagination, auth-expired/401, optimistic rollback.
• Out of scope and Open questions — including any data gaps from Step 3.

Step 7 — Hand off

Tell the user the plan is written, it's plain markdown they can edit freely, and that when they're happy frontend-module-builder executes it to write the binding code and make the design functional. Mention tests are a separate, optional step via frontend-test-writer. Do not build, do not auto-run anything.

Guardrails

• Observed, not guessed. The API contract section must come from a real source with the source cited. Reading the backend is the entire value — a guessed envelope defeats the skill.
• Minimal questions. Every question the frontend contract could have answered is a failure of Step 1/Step 4.
• Reuse must be specific. List paths (axios instance, BFF, shared fields, registry entries), not "reuse existing utilities".
• Plan, don't build. No binding code beyond illustrative type/schema field lists or hook signatures. Don't build missing design components — flag them.
• Frontend scope. This plans the client-side binding. Server-side feature design is backend-feature-planner.