Feature Specification Generator

Create structured feature specifications from natural language descriptions.

---

SpecKit Workflow

This skill is Step 1 of 6 in the Relentless workflow:

specify → plan → tasks → analyze → implement (task by task) or relentless run --feature [FEATURE NAME] --tui

What flows to next step:

• User requirements → plan will create technical approach
• Routing preference → carried through all artifacts
• Acceptance criteria → basis for TDD in implementation

---

TDD is MANDATORY

The specification MUST include testable acceptance criteria:

• Every user requirement should be verifiable with tests
• Test scenarios should be part of each story
• Edge cases should be documented for test coverage

All acceptance criteria must be written in Given/When/Then format to enable direct test implementation.

---

The Job

1. Receive feature description from user
2. Confirm routing preference (Step 0)
3. Generate short name and feature number
4. Create branch and feature directory in relentless/features/NNN-feature-name/
5. Generate specification using template
6. Validate specification quality (including TDD readiness)
7. Save to spec.md

---

Step 0: Confirm Routing Preference (BEFORE generating spec)

Ask the user these specific questions:

1. "Which routing mode?" (free/cheap/good/genius) - Default: good
2. "Allow free models in fallback?" - Default: yes
3. "Specific harness/model preference?" - Default: auto

Record the answer in spec.md metadata:

**Routing Preference**: auto: good | allow free: yes
<!-- Options: auto: free|cheap|good|genius | allow free: yes|no | OR specific: harness/model -->

---

Step 1: Create Feature Structure

Run the create-new-feature script to set up the branch and directory:

.claude/skills/specify/scripts/bash/create-new-feature.sh --json "FEATURE_DESCRIPTION"

This will output JSON with:

• BRANCH_NAME: e.g., "003-user-auth"
• SPEC_FILE: Full path to spec.md
• FEATURE_DIR: Full path to feature directory
• FEATURE_NUM: e.g., "003"

Important: Parse this JSON and use these paths for all subsequent operations.

---

Step 2: Load Constitution & Context

1. Read relentless/constitution.md for project governance
2. Note any MUST/SHOULD rules that apply to specifications
3. Keep these principles in mind while generating the spec
4. Pay special attention to TDD requirements - all features must be testable

---

Step 3: Generate Specification

Using the template at templates/spec.md, create a specification with:

Required Sections:

1. Feature Overview

• One-paragraph summary
• User value proposition
• Problem being solved

2. User Scenarios & Testing

• Concrete user stories with priorities (P1, P2, P3...)
• Step-by-step flows
• Expected outcomes
• Given/When/Then acceptance scenarios (MANDATORY)
• Independent testability explanation for each story

3. Functional Requirements

• What the system must do
• Testable requirements (no implementation details)
• Clear success criteria

4. Test Strategy (MANDATORY)

• Unit test approach
• Integration test scenarios
• Edge case tests
• Test data requirements

5. Success Criteria

• Measurable, technology-agnostic outcomes
• Quantitative metrics (time, performance, volume)
• Qualitative measures (user satisfaction, task completion)

6. Key Entities (if applicable)

• Data models and relationships
• Fields and types (logical, not implementation)

7. Dependencies & Assumptions

• External systems required
• Prerequisites
• Assumptions made

8. Out of Scope

• What this feature explicitly does NOT include
• Future considerations

---

Step 4: Handle Ambiguities

If aspects are unclear:

• Interview the user first with questions to clarify any doubts, concerns or about his opinion on eventual ideas to improve the feature.
• Only mark [NEEDS CLARIFICATION: specific question] if:
  • Choice significantly impacts scope or UX
  • Multiple reasonable interpretations exist
  • No reasonable default exists
  • Question not already solved by interview
• LIMIT: Maximum 3 clarifications

If clarifications needed, present to user:

## Clarification Needed

**Q1: [Topic]**
Context: [Quote spec section]
Question: [Specific question]

Options:
A. [Option 1] - [Implications]
B. [Option 2] - [Implications]
C. Custom - [Your answer]

Your choice: _

---

Step 5: Validate Quality

Check the specification against:

General Quality

• No implementation details (languages, frameworks, APIs)
• Focused on user value and business needs
• All requirements are testable
• Success criteria are measurable
• User scenarios cover primary flows
• Dependencies identified
• Scope clearly bounded
• No more than 3 [NEEDS CLARIFICATION] markers

TDD Readiness (MANDATORY)

• Every user story has Given/When/Then acceptance criteria
• Acceptance criteria are specific enough to write tests against
• Edge cases are documented for test coverage
• Test strategy section is complete

Routing Compliance

• Routing preference is recorded in metadata
• Routing choice is reasonable for feature complexity

If validation fails, revise and re-check (max 3 iterations).

---

Step 6: Save & Validate

1. Write complete specification to SPEC_FILE from JSON output

2. Run the validator to ensure spec.md is correctly formatted:

   .claude/skills/validators/scripts/validate-spec.sh "$SPEC_FILE"
   

   • If validation fails, fix the errors and re-run
   • Warnings are acceptable but should be reviewed

3. Create progress.txt if it doesn't exist (note that markdown frontmatter must be properly formatted YAML):

   ---
   feature: FEATURE_NAME
   started: DATE
   last_updated: DATE
   stories_completed: 0
   routing_preference: "[auto: mode | allow free: yes/no]"
   ---
   
   # Progress Log: FEATURE_NAME
   

4. Report to user:

   • Branch created: BRANCH_NAME
   • Spec saved: SPEC_FILE
   • Quality validation: PASSED/FAILED
   • TDD readiness: PASSED/FAILED
   • Routing preference: [recorded value]
   • Next step: /relentless.plan or /relentless.clarify

---

Example Output

# Feature: User Authentication

**Routing Preference**: auto: good | allow free: yes

## Overview
Enable users to create accounts and log in securely using email/password.

## User Scenarios

### User Story 1: New User Registration (Priority: P1)

User visits signup page, enters email and password, and creates an account.

**Why this priority**: Core functionality, blocks all other auth features.

**Independent Test**: Can be fully tested by registering a new account and verifying the account exists.

**Acceptance Scenarios**:

1. **Given** a visitor on the signup page, **When** they submit valid email and password, **Then** the account is created and confirmation email sent
2. **Given** an email already in use, **When** visitor tries to register, **Then** error message shown without revealing account exists

## Functional Requirements

**REQ-1:** System must validate email format
**REQ-2:** System must require passwords ≥ 8 characters
**REQ-3:** System must send confirmation email within 1 minute
**REQ-4:** System must hash passwords before storage

## Test Strategy (MANDATORY)

### Unit Test Approach
- Email validation logic
- Password strength validation
- Password hashing utility

### Integration Test Scenarios
- Full registration flow (submit form → create account → send email)
- Duplicate email rejection

### Edge Case Tests
- Invalid email formats (missing @, invalid domain)
- Password too short
- Unicode in email/password

### Test Data Requirements
- Valid test email addresses
- Various invalid email formats
- Password examples at boundary conditions

## Success Criteria

1. 95% of signups complete within 60 seconds
2. Zero plaintext passwords in database
3. Email confirmation rate > 80%

## Key Entities

**User**
- email: string (unique)
- password_hash: string
- confirmed: boolean
- created_at: timestamp

## Dependencies

- Email service provider (e.g., SendGrid, Mailgun)
- Session management system

## Out of Scope

- Social login (OAuth)
- Two-factor authentication
- Password reset (separate feature)

---

Notes

• Always run the script first to get proper paths
• Use absolute paths from JSON output
• Validate before marking complete
• Keep specification technology-agnostic
• Focus on WHAT, not HOW
• TDD readiness is non-negotiable - all acceptance criteria must be testable