backend-feature-planner
Turn a feature idea into a concrete, editable plan with the fewest questions possible. The reason this exists: generic planners interrogate the user every time because they have no memory of the codebase. This one reads the project's source of truth first, so it only asks what genuinely isn't decided yet.
The output is a markdown file the user reads and edits by hand before any code is generated. This skill never writes feature code and never invokes backend-module-builder.
Step 1 — Load the contract (always first)
First resolve the project dir for this (backend) domain via the resolution protocol in
../LAYOUT.md: read .claude/workspace.json and use the backend entry's folder (it may be the
repo root or a subfolder like backend-shoply/); if there's no manifest but ARCHITECTURE.md sits at
the repo root, that's the legacy single-project layout. All paths below — the contract files,
the grep targets, and the _docs/ output — are relative to that project dir.
Read, in this order:
ARCHITECTURE.md — the project's conventions (paradigm, response envelope, error model, validation flow, import convention, auth primitives, layout).MODULE_REGISTRY.md — what already exists: shared utils/middleware, existing modules and their public service surfaces, and the decisions log.- Grep the codebase for anything related to the requested feature:
src/lib, src/middleware, and sibling modules. Look for models, services, schemas, or middleware the feature could reuse.
If ARCHITECTURE.md/MODULE_REGISTRY.md are missing (a non-bootstrapped repo), say so and offer to generate a lightweight ARCHITECTURE.md by scanning the codebase before planning. Do not invent conventions silently.
Step 2 — Decide what is already answered
Cross off every question that the contract or existing code already settles. Examples:
- If the registry shows
protect/requireRole and jwt.ts exist, do not ask "how will you verify tokens" — that's decided; the auth feature reuses them.
- If ARCHITECTURE.md fixes the response envelope and error model, never ask about response shapes.
- If a
User model already exists, a feature needing users references it, not a new one.
The goal is to walk in already knowing most of the answer, the way a teammate familiar with the repo would.
Step 3 — Ask only the genuine unknowns
Use references/question-banks.md to pick the right scoped questions for the feature type, then filter them against Step 2 — ask only the survivors. Keep it tight (aim for ≤3–4 real decisions). These are feature-shaped product/design choices the codebase can't answer, e.g. for auth: token transport (cookie vs bearer), role model (single role vs RBAC list), whether registration is open or invite-only, refresh-token rotation. Present them as quick choices, not an essay.
If the user already specified some in their request, honor those and don't re-ask.
Step 4 — Write _docs/FEATURE_PLAN_<name>.md
Write the plan to _docs/FEATURE_PLAN_<name>.md under the project dir (resolved in Step 1) — create the _docs/ folder there if it doesn't exist yet. Planner docs live under _docs/; only ARCHITECTURE.md and MODULE_REGISTRY.md stay at the project dir root. Follow references/plan-template.md exactly. The non-negotiable sections are:
- Decisions — resolved choices, and any assumptions made (flagged as assumptions so the user can correct them).
- Reuse (from registry / existing code) — an explicit list with paths of what this feature will import rather than create. This section is the whole point: it commits the feature to dedup before code exists. If Step 1 found a usable util/middleware/model, it goes here.
- Create — the new files, by path, each with a one-line purpose.
- Data model — Mongoose schema additions or new model (fields, indexes), or "none".
- Endpoints — method + path + auth guard + validation schema + brief description, in a table.
- Edge cases & failure modes — the ones worth handling explicitly.
- Out of scope — what this feature deliberately does not include.
- Open questions — anything still genuinely undecided for the user to resolve.
Step 5 — Hand off
Tell the user the plan is written and is plain markdown they can edit — add or delete sections freely. Mention that when they're happy, backend-module-builder executes it. Do not proceed to build. Do not auto-run anything.
Guardrails
- Minimal questions is the entire value — every question the contract could have answered is a failure of Step 1.
- The Reuse section must be honest and specific; "reuse existing utilities" without paths defeats the dedup workflow.
- Plan, don't build. No code in the plan beyond illustrative schema field lists or endpoint signatures.
1---2name: backend-feature-planner3description: Plan a backend feature or module before any code is written. Use this whenever the user wants to add a feature, design a module (auth, products, orders, payments, search, file upload, etc.), or says things like "I want to build X", "plan the auth feature", "design the product module", or "how should I structure Y" for a server-side API. This is the BMAD replacement — it reads the project's ARCHITECTURE.md and MODULE_REGISTRY.md first, asks ONLY the questions those files don't already answer, and writes an editable FEATURE_PLAN markdown file. It does NOT write feature code (that is backend-module-builder) and does NOT write tests (that is backend-test-writer). Works in any project in the Express/TS convention family that has the contract files, or offers to create them for an existing repo.4---56# backend-feature-planner78Turn a feature idea into a concrete, editable plan with the fewest questions possible. The reason this exists: generic planners interrogate the user every time because they have no memory of the codebase. This one reads the project's source of truth first, so it only asks what genuinely isn't decided yet.910The output is a markdown file the user reads and edits by hand before any code is generated. **This skill never writes feature code and never invokes backend-module-builder.**1112## Step 1 — Load the contract (always first)1314**First resolve the project dir** for this (`backend`) domain via the resolution protocol in15`../LAYOUT.md`: read `.claude/workspace.json` and use the `backend` entry's folder (it may be the16repo root or a subfolder like `backend-shoply/`); if there's no manifest but `ARCHITECTURE.md` sits at17the repo root, that's the legacy single-project layout. All paths below — the contract files,18the grep targets, and the `_docs/` output — are **relative to that project dir**.1920Read, in this order:211. `ARCHITECTURE.md` — the project's conventions (paradigm, response envelope, error model, validation flow, import convention, auth primitives, layout).222. `MODULE_REGISTRY.md` — what already exists: shared utils/middleware, existing modules and their public service surfaces, and the decisions log.233. **Grep the codebase** for anything related to the requested feature: `src/lib`, `src/middleware`, and sibling modules. Look for models, services, schemas, or middleware the feature could reuse.2425If `ARCHITECTURE.md`/`MODULE_REGISTRY.md` are missing (a non-bootstrapped repo), say so and offer to generate a lightweight `ARCHITECTURE.md` by scanning the codebase before planning. Do not invent conventions silently.2627## Step 2 — Decide what is already answered2829Cross off every question that the contract or existing code already settles. Examples:30- If the registry shows `protect`/`requireRole` and `jwt.ts` exist, do not ask "how will you verify tokens" — that's decided; the auth feature reuses them.31- If ARCHITECTURE.md fixes the response envelope and error model, never ask about response shapes.32- If a `User` model already exists, a feature needing users references it, not a new one.3334The goal is to walk in already knowing most of the answer, the way a teammate familiar with the repo would.3536## Step 3 — Ask only the genuine unknowns3738Use `references/question-banks.md` to pick the right scoped questions for the feature type, then **filter them against Step 2** — ask only the survivors. Keep it tight (aim for ≤3–4 real decisions). These are feature-shaped product/design choices the codebase can't answer, e.g. for auth: token transport (cookie vs bearer), role model (single role vs RBAC list), whether registration is open or invite-only, refresh-token rotation. Present them as quick choices, not an essay.3940If the user already specified some in their request, honor those and don't re-ask.4142## Step 4 — Write `_docs/FEATURE_PLAN_<name>.md`4344Write the plan to `_docs/FEATURE_PLAN_<name>.md` under the **project dir** (resolved in Step 1) — create the `_docs/` folder there if it doesn't exist yet. Planner docs live under `_docs/`; only `ARCHITECTURE.md` and `MODULE_REGISTRY.md` stay at the project dir root. Follow `references/plan-template.md` exactly. The non-negotiable sections are:45- **Decisions** — resolved choices, and any assumptions made (flagged as assumptions so the user can correct them).46- **Reuse (from registry / existing code)** — an explicit list with paths of what this feature will import rather than create. This section is the whole point: it commits the feature to dedup *before* code exists. If Step 1 found a usable util/middleware/model, it goes here.47- **Create** — the new files, by path, each with a one-line purpose.48- **Data model** — Mongoose schema additions or new model (fields, indexes), or "none".49- **Endpoints** — method + path + auth guard + validation schema + brief description, in a table.50- **Edge cases & failure modes** — the ones worth handling explicitly.51- **Out of scope** — what this feature deliberately does not include.52- **Open questions** — anything still genuinely undecided for the user to resolve.5354## Step 5 — Hand off5556Tell the user the plan is written and is plain markdown they can edit — add or delete sections freely. Mention that when they're happy, backend-module-builder executes it. Do not proceed to build. Do not auto-run anything.5758## Guardrails5960- Minimal questions is the entire value — every question the contract could have answered is a failure of Step 1.61- The Reuse section must be honest and specific; "reuse existing utilities" without paths defeats the dedup workflow.62- Plan, don't build. No code in the plan beyond illustrative schema field lists or endpoint signatures.
vipincode