---
description: Create detailed feature specification
argument-hint: <feature-name> [description]
---

# Create Feature Specification

Create a comprehensive specification for a new feature using the spec-writer agent.

## Input

- **Feature name**: First word of $ARGUMENTS (required)
- **Description**: Rest of $ARGUMENTS (optional, will prompt if missing)

## Workflow

### 1. Initialize

- Parse feature name from arguments (kebab-case: "User Dashboard" -> "user-dashboard")
- Check if `.auto-build-data/` exists
  - If not: Run `bash .auto-build/scripts/setup.sh` first
- Check if spec already exists at `.auto-build-data/specs/{feature-name}/`
  - If exists: Ask "Update existing spec or create new version?"

### 2. Gather Requirements

Ask the user these questions (one at a time, adapt based on answers):

1. **Problem Statement**
   "What problem does this feature solve? Who are the users?"

2. **Success Criteria**
   "How will we know this feature is complete? What are the acceptance criteria?"

3. **Constraints**
   "Are there any constraints? (performance, compatibility, existing patterns to follow)"

4. **Scope**
   "What is explicitly NOT included in this feature?"

### 3. Codebase Analysis

Launch the **spec-writer** agent with:
- Feature name and description
- User's answers to requirements questions
- Instruction to analyze the codebase for:
  - Similar existing features
  - Patterns to follow
  - Files likely to be affected
  - Dependencies and integrations

### 4. Generate Specification

The spec-writer agent creates:
- `.auto-build-data/specs/{feature-name}/spec.md` using the template
- `.auto-build-data/specs/{feature-name}/status.json` with state: "SPEC_COMPLETE"

### 5. Confirmation

Display:
```
Specification created: .auto-build-data/specs/{feature-name}/spec.md

Summary:
- [Key requirement 1]
- [Key requirement 2]
- [Key requirement 3]

Affected files identified: X files
Estimated complexity: [Low/Medium/High]

Next steps:
- Review the spec: Read .auto-build-data/specs/{feature-name}/spec.md
- Start implementation: /ab:build {feature-name}
```

## Spec Template

The generated spec.md follows this structure:

```markdown
# Feature: {name}

## Overview
Brief description and purpose

## Problem Statement
What problem this solves

## User Stories
- As a [user], I want [action] so that [benefit]

## Functional Requirements
1. [Requirement 1]
2. [Requirement 2]

## Technical Requirements
- Files to modify: [list]
- New files to create: [list]
- Dependencies: [list]
- Database changes: [if any]
- API changes: [if any]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Out of Scope
What is NOT included

## Risks and Mitigations
| Risk | Mitigation |
|------|------------|

## Open Questions
- [Any unresolved questions]
```

## Status JSON Format

```json
{
  "feature": "feature-name",
  "status": "SPEC_COMPLETE",
  "created": "2025-01-15T10:00:00Z",
  "updated": "2025-01-15T10:30:00Z",
  "history": [
    {"status": "SPEC_DRAFT", "at": "2025-01-15T10:00:00Z"},
    {"status": "SPEC_COMPLETE", "at": "2025-01-15T10:30:00Z"}
  ]
}
```