# Feature Planning > Use this skill whenever a user wants to plan or implement a new feature, whether they reference a requirements file or describe the feature directly in chat. Triggers include phrases like "I've created a requirements file", "review the reqs for", "new feature requirements", "requirements in /_reqs/", any mention of a .md requirements document, OR a prose description of a feature the user wants pl… - **Type:** Skill - **Install:** `agentstack add skill-lunarcommand-claude-skills-feature-planning` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [LunarCommand](https://agentstack.voostack.com/s/lunarcommand) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [LunarCommand](https://github.com/LunarCommand) - **Source:** https://github.com/LunarCommand/claude-skills/tree/main/skills/feature-planning ## Install ```sh agentstack add skill-lunarcommand-claude-skills-feature-planning ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Feature Planning Skill A structured workflow with two human approval gates before any code is written. Claude is expected to actively contribute thinking — judge the proposed approach, poke holes in the requirements, surface missed opportunities and alternatives, and be opinionated — not just transcribe requirements into a task list. ## Right-sizing the plan The templates in this skill show the **maximum** shape. Scale the *depth* of each section to the feature — **never drop a heading** (silently skipping a section hides what wasn't considered), but let a small feature collapse a section to a single line or an explicit `None — ` (e.g. "No invariants — stateless pure transform"). Heuristic: if the feature has **none** of {persistent state, external side effects, concurrency, data migration, security/performance constraints}, treat it as **light** — one phase, 1–2 test cases, terse or `None` sections. If it has one or more, treat it as **heavy** — full given/when/then test cases, multiple invariants, phased breakdown. Proportionality scales depth, not presence: a trivial feature still gets an Invariants heading, it just reads "None — ". When in doubt, ask the user rather than guess at the weight. ## When This Skill Triggers Use this skill when: - The user references a requirements file (e.g. `/_reqs/some-feature.md`) - The user says something like "I've created a new requirements file for X" - The user asks Claude to review requirements and get started - The user describes a new feature in chat (in prose, not a file) and wants to plan or build it ## Inputs Exactly one of: - **`$REQUIREMENTS_FILE`** — path to a requirements file (e.g. `/_reqs/csv-export.md`) - **`$DESCRIPTION`** — a written description of the feature, provided directly in chat If neither is clearly provided, ask the user: *"Do you have a requirements file (give me the path), or would you like to describe the feature here in chat?"* ## Workflow --- ### Step 1 — Establish the Requirements File & Get Context **If the user provided `$REQUIREMENTS_FILE`:** Read it in full. **If the user provided `$DESCRIPTION` (prose, not a file):** 1. Derive a short kebab-case slug for the feature (e.g. "CSV export" → `csv-export`). 2. Create `/_reqs/.md` (creating the `/_reqs/` directory first if it doesn't exist) with this structure: ```markdown # ## Description ## Goals ## Constraints ## Non-Goals ``` ⚠️ These scaffolding sections exist to give the later hole-poking something to bite on — they are NOT license to invent. Fill each only from what the user actually said; write "Not specified" otherwise. The gaps left by "Not specified" are exactly what Step 2's Gaps & holes analysis and Clarifying Questions should target. 3. Tell the user: *"I've captured your description in `/_reqs/.md`. From here I'll treat that as the requirements file."* 4. From this point forward, treat the newly created file as `$REQUIREMENTS_FILE` for the rest of the workflow. **Either way**, then skim the codebase for relevant context: existing patterns, related modules, prior decisions. The goal is to enter Step 2 with enough understanding to push back intelligently, not just paraphrase. --- ### Step 2 — Append Approach Analysis AND Clarifying Questions ⚠️ **Both the analysis and the questions MUST be written to `$REQUIREMENTS_FILE` on disk. This is not optional.** ❌ NEVER do any of the following: - Discuss the approach in chat or terminal - List your concerns, alternatives, or questions in your response - Run an interactive interview - Skip the analysis because the requirements seem solid - Skip the questions because the requirements seem clear enough ✅ The ONLY correct action is to open `$REQUIREMENTS_FILE` and append BOTH sections below to the bottom of it using your file write tools, then tell the user where to find them. Note: when the requirements file was generated from a `$DESCRIPTION`, expect more gaps than usual — lean harder on Clarifying Questions to surface what the prose didn't cover. The sections MUST use this exact format: ```markdown ## Approach Analysis ### What's strong about this approach - - ### Concerns & risks - — why it matters - — why it matters ### Gaps & holes in the requirements Poke holes in the requirements *as written* — this is about defects in the spec, not risks in the approach. Look for: - — what's unclear and why it will bite - — what happens if it's false - - - ### Opportunities worth considering Things the user did NOT ask for but should see — adjacent wins, low-cost additions, things that would make the feature notably better. Flag them; do not assume them into scope (the user decides at Gate 1). - **** — . Value: . Cost: . - **** — . Value: . Cost: . ### Alternative approaches worth considering - **** — . Trade-off: . - **** — . Trade-off: . ### My recommendation ## Clarifying Questions **Q: ** A: **Q: ** A: ``` The Approach Analysis is **required** even when you fully agree with the proposed approach — in that case, your job is to explain *why* the alternatives lose so the user can sanity-check your reasoning. Rubber-stamping isn't analysis. If you genuinely have no alternatives worth raising and zero concerns, write a brief version — but you must still poke holes in the requirements and note opportunities (or explicitly state there are none): ```markdown ## Approach Analysis The proposed approach is the right one. I considered and but rejected them because . No material concerns. ### Gaps & holes in the requirements ### Opportunities worth considering ``` Leave every `A:` line blank — the user will fill them in directly in the file. The user may also edit the Approach Analysis section to push back, agree, or redirect — those edits are direction changes you must respect. Good questions to consider: - Are there edge cases not covered? - Are there dependencies or existing systems this must integrate with? - What are the acceptance criteria / definition of done? - How do we verify each behavior — what's the observable pass/fail signal for each one? - What must be tested at the integration or end-to-end level (not just units), and what are the failure modes worth a dedicated test? - Are there performance, security, or scalability constraints? - What's the priority if trade-offs are needed? If the requirements are genuinely fully unambiguous and you have zero questions, write this in place of the questions section: ```markdown ## Clarifying Questions No clarifying questions — requirements are fully specified. ``` After writing to the file, tell the user: > "I've added my approach analysis and clarifying questions to `$REQUIREMENTS_FILE`. Please open the file, push back on or accept the analysis, fill in your answers on the `A:` lines, then reply **'answered'** when ready." ⛔ **GATE 1 — STOP. Do not continue until the user replies with "answered".** "done", "ready", "continue" do NOT open this gate. Only "answered" does. --- ### Step 3 — Re-read the File and Verify Re-read `$REQUIREMENTS_FILE` in full. Check that: - Every `A:` line has been filled in - Any edits the user made to the Approach Analysis section — these are direction changes you must respect when writing the plan If any `A:` lines are still blank, list the unanswered questions and wait for the user to complete them. Do not proceed until all are answered. --- ### Step 4 — Write the Final Plan to Disk ⚠️ **The plan MUST be written to disk. Outputting the plan in chat is NOT sufficient.** Write the plan to: **`/_plans/-plan.md`** (e.g. `/_reqs/csv-export.md` → `/_plans/csv-export-plan.md`) If `/_plans/` does not exist, create it first. The plan file MUST include the following sections (this is the maximum shape — apply **Right-sizing the plan** to scale each section's depth to the feature; keep every heading): ```markdown # Plan: ## Summary One-paragraph overview of what will be built and why. ## Requirements Reference /_reqs/.md ## Goals & Non-Goals ### Goals - ### Non-Goals - ## Invariants Properties that must hold true at ALL times, across every state and input — the design contract. An invariant is a standing safety property ("X is always true"), NOT a one-time outcome ("we achieved X" — that's Success Criteria) and NOT a risk. If it can ever be false without the feature being broken, it isn't an invariant. - **INV-1:** — - **INV-2:** Include invariants the requirements imply but never state (surfaced in Step 2's Gaps & holes). Each invariant must be verified by at least one test in Test Definitions. ## Non-Functional Requirements Measurable quality constraints the feature must meet — distinct from functional behavior (what it does) and invariants (what must always hold). State a target, not a vibe. Where a target is measurable, map it to a `T-`; where it can only be checked by judgment, say so. - **Performance** — - **Security** — - **Scalability** — - **Reliability** — Add or drop categories as the feature warrants; a light feature may reduce this whole section to `None — `. ## Success Criteria How we know this is done and working. Measurable where possible. These are the target the Test Plan, Test Definitions, and Coverage below map back to — so define them before the test sections reference them. ## Strategy ### Chosen approach Describe the approach in 2–4 sentences. This should reflect the conclusion from the Approach Analysis after any user feedback. ### Why this approach Explain why this beats the alternatives considered. Reference the trade-offs. ### Alternatives rejected - **** — rejected because . - **** — rejected because . ## Clarifications & Decisions - [Question] → [Answer / decision made] - [Approach feedback from user] → [How the plan reflects it] ## Risks & Mitigations - **** — likelihood: . Mitigation: . - **** — likelihood: . Mitigation: . ## Implementation Plan ### Phase 1: - [ ] Task 1 - [ ] Task 2 **Verified by:** T-1, T-2 _(the test IDs from Test Definitions that prove this phase is done)_ ### Phase 2: - [ ] Task 3 **Verified by:** T-3 ## Files to Create / Modify - `path/to/file.ts` — purpose ## Test Plan How this feature will be verified, across levels. Be specific. - **Unit** — - **Integration** — - **End-to-end** — - **Manual / QA** — **Execution notes:** Every behavior in Success Criteria must map to at least one test ID below, and every invariant (INV-) must be verified by at least one test. Every phase in the Implementation Plan must cite the test IDs that verify it. ## Test Definitions Enumerated, reviewable test cases. Assign each a stable `T-` ID and group by level. These are the concrete cases the tests will implement — approving this plan approves these behaviors. ### Unit **T-1 — ** - **Level:** unit - **Preconditions:** - **Given** - **When** - **Then** **T-2 — ** - **Level:** unit - **Preconditions:** - **Given** - **When** - **Then** ### Integration **T-3 — ** - **Level:** integration - **Preconditions:** - **Given** - **When** - **Then** ### End-to-end / Manual **T-4 — ** - **Level:** e2e | manual - **Preconditions:** - **Given** - **When** - **Then** _(Include only the levels that apply. Cover the happy path, the key edge cases surfaced in Clarifying Questions, the failure modes from Risks & Mitigations, and a test that tries to violate each Invariant (INV-) — don't just test the happy path.)_ ## Coverage Traceability rollup so nothing planned goes unverified. Every invariant, success criterion, measurable NFR, and phase must appear here with the test IDs that cover it. Any row with no test is a gap to close before this plan is presented. - **INV-1** → - **Success: ** → - **NFR: ** → - **Phase 1** → ## Rollout / Migration How this ships safely — feature flags, backfills, deprecation steps, rollback plan if needed. Write "N/A — greenfield" if there's nothing to migrate. ## Out of Scope What explicitly will NOT be addressed in this implementation. ## Open Questions Any unresolved questions to revisit later. ``` **Before presenting the plan, run a coverage self-check.** Confirm that every invariant (`INV-`), every Success Criteria behavior, and every measurable NFR has at least one mapped test in the `## Coverage` section, and that every implementation phase cites its `Verified by:` tests. If anything is uncovered, close the gap — add the missing test or explicitly mark it "judgment — not automatable" — before presenting. Do not present a plan with silent coverage gaps. After writing the file, tell the user: > "Plan written to `/_plans/-plan.md`. Please review it and reply **'approved'** to start implementing, or tell me what you'd like to change." ⛔ **GATE 2 — STOP. Do not write any code. Do not begin Step 5.** "done", "answered", "looks good" do NOT open this gate. Only "approved" does. If the user requests changes, update the plan file on disk, re-present the gate message, and wait again. --- ### Step 5 — Implement & Verify ⚠️ **Only begin after the user has explicitly said "approved" in Step 4.** Implement according to the plan and close the verification loop the plan set up — don't just write code and check boxes. **Work phase by phase, in order.** For each phase: 1. Implement the phase's tasks, checking them off as you go. 2. Write and run that phase's `Verified by:` tests (the `T-` cases from Test Definitions). 3. Confirm they pass **and** that the invariants (`INV-`) the phase touches still hold. 4. **Do not advance to the next phase past red tests.** If a test fails, fix it (or, if the plan itself was wrong, stop and revise the plan with the user rather than improvising). **After the final phase:** - Run the **full test suite** and confirm every `T-` and every `INV-` in the plan is covered and green. - If any planned test was not implemented or is failing, say so explicitly — do not report the feature as done. **Then hand off for validation** — summarize what was built, the files changed, the tests run and their results, and anything deferred or still open. Leave commit/push to the user's normal workflow; do not commit unless asked. ## Rules - **Right-size the plan.** The templates are the maximum shape. Keep every heading, but scale each section's depth to the feature — a trivial change gets terse or `None — ` sections, not fabricated ceremony. See "Right-sizing the plan". - **Either input works**, but a requirements file on disk is the source of truth from Step 2 onward. If the user gave a prose description, write it to `/_reqs/.md` in Step 1 before doing anything else. - **Analysis and questions go in the file. Always. No exceptions.** Never discuss approach or ask questions in chat. - **Be opinionated in the Approach Analysis.** "It depends" is not a recommendation. Pick one and defend it. - **Poke holes in the requirements and surface missed opportunities.** The analysis must critique the reqs *as written* (gaps, ambiguities, unstated assumptions, contradictions) and flag opportunities the user didn't ask for — not just evaluate the proposed approach. If there are genuinely none, say so explicitly. Opportunities are flagged, not assumed into scope; the user decides at Gate 1. - **Surface alternatives even when you agree** with the proposed approach — explain why they lose. - There are two separate gates — Gate 1 ("answered") and Gate 2 ("approved") — they are not interchangeable. - "done" does not open either gate. - Re-reading the file after answers is mandatory — do not rely on memory of the blank questions, and watch for user edits to the analysis. - Writing the plan to disk is mandatory — chat output does not count. - **The plan must define invariants with stable `INV-` IDs** — properties that must always hold, distinct from success criteria and risks. Surface unstated invariants the reqs only imply, and verify each with a test. - **The plan must include enumerated test definitions with stable `T-` IDs**, not a … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [LunarCommand](https://github.com/LunarCommand) - **Source:** [LunarCommand/claude-skills](https://github.com/LunarCommand/claude-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-lunarcommand-claude-skills-feature-planning - Seller: https://agentstack.voostack.com/s/lunarcommand - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.