create-feature-spec

name	create-feature-spec
description	Create Feature Specs for Stage E of the VibeFlow docs-first workflow
metadata	{"triggers":["create feature spec","write feature","design feature","acceptance criteria","API design","Stage E","feature planning"]}

create-feature-spec

Create Feature Specs for Stage E of the VibeFlow docs-first workflow.

Purpose

This skill creates Feature Spec documents that:

• Define the API design contract (exact function/class signatures)
• Specify testable acceptance criteria
• Document design changes (UI/API/schema)
• Include test and evaluation plan
• Reference discovery findings and specs

Workflow

Stage E: Feature Spec
    │
    ├── Define API Design (exact signatures)
    ├── Write testable acceptance criteria
    ├── Document design changes (UI/API/schema)
    ├── Create test and evaluation plan
    ├── Map telemetry and metrics
    └── Reference discovery findings and specs

Usage

Create Feature Spec

/create-feature-spec <ID> <slug>

Creates docs/features/ft-<ID>-<slug>.md with required sections.

Example:

/create-feature-spec 030 anti-hallucination

Validate Feature Spec

/create-feature-spec validate <ID>

Validates that the feature spec has all required sections.

Update Schedule

/create-feature-spec schedule

Updates docs/features/schedule.md with feature status.

Document Requirements

Required Sections

For All Features:

• Header (ID, File, Owner, TECH-SPECs with versions)
• Architecture Conformance
• API Design (exact signatures)
• Acceptance Criteria
• Design Changes
• Test & Eval Plan
• Telemetry & Metrics
• Edge Cases & Risks

For Medium/Large Features (Additional):

• Stage B Discovery Findings
  • Test Impact Analysis
  • Existing Implementation Analysis
  • Dependency & Side Effect Mapping

API Design Section (Critical)

The API Design section defines the contract for Stage F (test writing):

## API Design

### ServiceName.method_name()
- **Signature:** `method_name(param: Type, param2: Type = default) -> ReturnType`
- **Purpose:** [Brief description]
- **Parameters:**
  - `param`: [Description]
  - `param2`: [Description, default value]
- **Returns:** [Description of return type and structure]

### API Endpoint: POST /api/v1/endpoint
- **Method:** POST
- **Path:** `/api/v1/endpoint`
- **Request Body:**
  ```json
  {
    "field": "type"
  }

• Response Body:

  {
    "result": "type"
  }
  

Why This Matters:

• Stage F creates implementation stubs from these signatures
• Tests are written using these exact function names
• Any changes require updating specs first (Stage G.1)

Acceptance Criteria

Format as testable checklist or Gherkin:

## Acceptance Criteria

- [ ] User can [action] with [condition] resulting in [outcome]
- [ ] System returns [response] when [condition]
- [ ] Error [X] is shown when [condition]

Or Gherkin:

Given [context]
When [action]
Then [expected outcome]

Validation

• scripts/validate_feature.py — Validate feature spec structure and API Design

References

See assets/:

• feature-template.md — Complete feature spec template

See references/:

• api-design-guide.md — API Design section guidance

Context7 Library Research

Follow the workflow in .claude/rules/context7-research.md to fetch current library documentation.

What to look for: exact method signatures, error types, configuration options, parameter defaults.

Where to incorporate findings:

• API Design — use verified signatures and types from library docs, not assumed ones
• Acceptance Criteria — reference actual error types and edge cases from docs
• Edge Cases & Risks — document known limitations and version-specific behaviors

Manifest Update

After completing Stage E, update docs/workflow-state.yaml:

• Set stage: E
• Set docs.feature: docs/features/ft-<ID>-<slug>.md

Checkpoint #2 (after Stage E):

• Set checkpoint: 2 after passing validation
• Criteria: Feature spec exists with all required sections, API Design section has exact signatures, acceptance criteria are testable

Git Commit

After completing this stage, ask the user for permission before committing:

git add docs/features/ft-<ID>-<slug>.md docs/workflow-state.yaml
git commit -m "feat(feature): define <slug> feature spec (#ft-<ID>)"

Replace <ID> and <slug> with actual values.

Auto-Advance

After the commit is complete, directly run /manage-work advance <ID> to advance to the next stage. The advance command will automatically validate Checkpoint #2 at the E→F boundary.