dasha-ws/ai-dev-framework/new-feature-spec

new-feature-spec

Purpose

/new-feature-spec creates, or substantially updates, the requirements for one piece of work on an existing product: a new feature, a meaningful change of behaviour, or a fix big enough that the expected behaviour has to be pinned down before anyone designs anything. The result lives in:

.claude/work/<feature-name>/feature-spec.md

It is a feature-level requirements document. It is not a Product Spec (that describes the product as a whole), not an architecture document and not a Tech Spec, which later sits next to it as tech-spec.md and which this skill never creates. It never rewrites the Product Specification silently (step 3). After successful feature authoring the next mandatory gate is /review-spec. A product-level escape stops earlier and routes to /product-spec. What follows is governed by "Next skills".

When to use

• A new feature of an existing product, or a significant change of existing behaviour.
• An extension of an existing user scenario.
• A large enough bug or behaviour change, where the expected behaviour must be fixed in writing first.
• Any new work that needs its own Feature Spec before technical design.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing. Stop, say what is missing and suggest /init-project (step 1).
• The whole product is new, or its general idea changes substantially, or the product context is too unclear to understand the feature: /product-spec (step 3).
• A small bugfix where the correct behaviour is already obvious and no separate spec is needed, or a tiny local edit (a text fix, a button label, a small tweak). There is no /bugfix-spec in the framework: if a bug demands a substantial behaviour change or agreed requirements first, use this skill.
• The user wants an architectural decision (/architecture) or a technical implementation plan (/tech-spec).
• The user wants finished work tested (/test-feature), code reviewed (/review-code) or documentation updated after implementation (/update-docs).

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The user: the description of the change and the answers to the feature interview.
• The project itself (existing projects): README, documentation, existing specs, and existing behaviour where it matters.
• The framework structure in the target project, created by /init-project: root CLAUDE.md, .claude/skills/project-context/SKILL.md, .claude/skills/project-context/context/product.md, .claude/product/product-spec.md and .claude/work/. All are required.
• Product context: either a substantive Product Specification, or, if product-spec.md is still a not-started stub, an existing project and project-context that already define the product clearly enough (step 3).
• The installed Feature Specification template. feature-spec.md is created from it.

Files to read

Read before writing anything. All reads are read-only. Always: the root CLAUDE.md, .claude/skills/project-context/SKILL.md (the router), .claude/skills/project-context/context/product.md, .claude/product/product-spec.md, the existing feature-spec.md of this work if there is one, and the installed template. For existing projects, only when it actually helps: README* and product documentation, relevant current and completed specs in .claude/work/, existing behaviour in code only as far as needed to understand the feature, and other context files only if the router says the task needs them.

Follow the router: do not load the whole project context by default. This is not a technical audit. Never read real .env files, keys or credentials.

Execution steps

1. Confirm the target, the prerequisites and the template

Verify that the working directory is a target project, not the framework repo, and that everything required in "Inputs" exists: root CLAUDE.md, the router, product.md, product-spec.md and .claude/work/. If any of it is missing: stop, say what is missing and suggest /init-project first. Do not create the structure yourself and do not rebuild it from memory.

The installed Feature Specification template is required, and its structure is the structure of feature-spec.md. It lives at %USERPROFILE%\.claude\ai-dev-framework\templates\work\feature-spec.md, so do not look for it by other means. If it is unavailable, missing or empty: stop, say that the framework installation or template needs fixing, and do not recreate it from memory, invent your own structure or continue.

2. Read the current state and take the baseline

Read the files listed above and note whether product-spec.md is a substantive spec or a not-started stub. For an existing project, keep three things apart: the intended behaviour, the documented requirements and the current implementation. Code and current behaviour are evidence of how the product behaves today. Legacy behaviour, a bug or a quirk is not a requirement just because it exists.

Before the first write, in a git repository, take a read-only baseline with git status --short -uall, git diff and git diff --cached, so that staged changes and files inside untracked directories are visible. Do not require a clean working tree, and leave any changes the user already has untouched: they are not a violation of this skill's boundaries. The baseline exists so that step 7 can tell your changes from the earlier ones. Never stage, reset, checkout, stash, commit or run any other command that changes git state. If the project is not a git repository, do not invent a filesystem snapshot, hashes or any other baseline mechanism.

3. Check the request against the product

Sources. The Product Specification (.claude/product/product-spec.md) stays the source of truth for the product as a whole, and a substantive one binds the Feature Spec. The current Feature Spec defines the agreed requirements of this change only: it may refine the Product Specification for this work and must not quietly contradict or rewrite it. The future Tech Spec implements a Feature Spec that has passed /review-spec and does not rewrite the requirements to suit an implementation. There is one product truth: no second Product Specification and no competing versions of the Feature Spec. No source ledger and no source: label next to every requirement: it is enough that each requirement was confirmed by the user or reliably established from the existing project.

Product context sufficiency. A not-started Product Spec does not by itself forbid this skill. Without a substantive one you may continue only if the existing project and its project-context already make these clear enough: what the product is, who it is for, what it is for, its current scope and the key constraints needed to understand the feature. If product goals, relevant users, product scope or key constraints are not clear enough: do not fill the gaps with guesses. Stop and suggest /product-spec first. A not-started Product Spec is never a licence to invent product context.

Product-level escape. Compare the requested change with the Product Specification. If it in fact changes the overall product intent, the target users, the main scope, the key product rules or another substantial product-level decision, it is not an ordinary feature and must not be smuggled in as one. Stop feature authoring, explain which product-level decision is affected and suggest updating it through /product-spec first. This applies at any point of the run, including when the interview or a source conflict only now reveals it.

The same escape applies when, during the run, a new product-wide requirement, constraint or open question is reliably found that is not yet in the Product Specification and has to be recorded there, even if the change itself is an ordinary feature. The reason to stop is canonical ownership, not importance: this skill must not write product-wide truth, and it must not leave it only in the conversation or the report. Product-wide truth that already exists in the Product Specification does not trigger it, and neither does a [before public launch] marker on its own. Stop, say what belongs to the Product Specification and suggest /product-spec. After the Product Specification is updated and has passed /review-spec, the user can return to /new-feature-spec. This is a stop and not a completed run: do not call the Feature Specification complete or ready for review, and do not name /review-spec for it as the next step.

4. Identify the work item

One Feature Spec is one current feature or change. Do not merge unrelated work. The Feature Spec lives in .claude/work/<feature-name>/. Before creating anything:

• look through .claude/work/, and read .claude/work/completed/ too, for work on the same change, and do not create a duplicate. If the same work exists and the request already makes clear that the user wants to continue or update exactly that work, do not ask again. If the intent is unclear, show the work you found and ask how to proceed;
• never modify anything in .claude/work/completed/ unless the user explicitly asks for it;
• if a work folder for this change already holds a Feature Spec, this is potentially an update. If the request already clearly says to update it, do not ask again. Otherwise ask whether the existing requirements really need to change. Never overwrite an existing Feature Spec silently;
• if an existing feature-spec.md is empty, damaged, or so far from the installed template that continuing safely is impossible: stop and describe the problem. Do not invent a new structure.
• an existing .claude/work/<feature-name>/ folder is occupied by a work item unless it is established that it is this same work. A matching name, the same technical area, an existing tech-spec.md or the absence of a feature-spec.md does not establish it, and a missing Feature Spec does not make the folder available. If it is established as this same work, use it under the rules above. If it belongs to another work item, do not add a Feature Spec there: choose another short, unambiguous name. If it is unclear, show the folder briefly and ask before writing anything.

Use the project's or framework's naming convention for work folders, if there is one. If there is none and the name is ambiguous, propose a short, clear name and wait for agreement before creating a new folder. No extra directory levels and no new way of organising work items.

5. Resolve conflicts and run the feature interview

If the Product Spec, an existing Feature Spec, the project context, the documentation or the observable implementation contradict each other on the requirements of this feature: do not pick the convenient version and do not fix it silently. Show the user the exact divergence, explain the variants in a few lines and wait for the decision before recording anything. If the conflict means a change of product-level truth, that is the product-level escape of step 3.

Then a short conversation, noticeably lighter than the full /product-spec interview. Study what is known first, then ask.

• Do not ask what is reliably known already, and never repeat a question the user has explicitly answered.
• Ask only what is really needed to define this feature, in small logical blocks. If an answer opens a real new uncertainty, follow up.
• If the user has not decided something yet, do not decide for them. Leave the unknown as unresolved or open. Do not turn an assumption into a requirement.
• Do not drift into technical implementation.