| name | spec-feature |
| description | Spec Driven Development – gathers business features through a structured interview sequence (context, behavior, technical hints, quality) and creates a specification file in specs/. Use this skill for "specify a feature", "create a spec", "describe the feature", "what should the system do?" or when requirements should be captured in a structured way before code is written. |
| argument-hint | [feature-name] |
Spec Feature Skill
Structured interview for capturing business requirements.
The result is a spec file in specs/ that serves as the foundation for implementation,
tests, and documentation.
Philosophy: First understand, then build. The spec is the shared language
between business requirements and code.
What This Skill Does
- Conducts structured interview – 4 question groups (Context, Behavior, Technical Hints, Quality) asked sequentially
- Summarizes answers – Compact summary for confirmation
- Creates spec file –
specs/<feature-name-kebab-case>.md from template
How to Use
I want to specify a new feature
Create a spec for order processing
Describe the feature user registration before we implement
Instructions
Step 1 – Interview
The interview is the content foundation for the entire spec. Ask questions sequentially – one group at a time, so the user can answer with focus. Collect answers and summarize at the end of each phase.
Group 1 – Context
- What is the feature called? (short, business-oriented name – becomes the filename)
- What is the goal? (1–3 sentences: what problem is being solved?)
- Who uses it? (role / actor, e.g. "case worker", "external API client")
Group 2 – Behavior
- What should the system do? (main flow in simple sentences)
- What variants / edge cases exist? (alternative flows, error cases)
- What should the system explicitly NOT do? (boundaries – prevents scope creep)
Group 3 – Technical Hints
- Are there API endpoints? (method + path, e.g.
POST /orders)
- What data is involved? (fields, types – rough is fine)
- Are there messaging events? (published / consumed, channel names)
- Are there dependencies on other features / services?
Group 4 – Quality
- What acceptance criteria must be met? (measurable, testable)
- Are there non-functional requirements? (performance, security, availability)
- Are there any open questions / assumptions?
Step 2 – Summary
After the interview: summarize all answers compactly and get confirmation.
Only write the spec file after confirmation.
Step 3 – Create Spec File
Filename: specs/<feature-name-kebab-case>.md
Template: see templates/feature-spec.md.template
References
Conventions
- Filename: kebab-case, English (
order-creation.md)
- Feature name (heading): Title case, English (
Order Creation)
- Code artifacts in the proposal: English (
OrderService, createOrder)
Integration with java-scaffold
After spec creation, the java-scaffold can use the spec as input:
Implement the feature according to specs/order-creation.md
The scaffold skill reads the spec and derives:
- Boundary: REST endpoints and/or messaging consumers
- Control: Service classes for business logic
- Entity: JPA entities, Flyway migration, repositories
Position in Workflow
[spec-feature] <-- capture business requirements
|
[openapi] if OpenAPI spec needed
|
[java-scaffold] framework: DB, messaging, infra
|
[review] code review
|
[doc] project documentation
