Create Spec

Overview

Create a living specification (Spec) for a feature by analyzing requirements, reviewing the codebase, and generating a Blueprint + Contract document that evolves with the code.

Definitions

• {TASK_KEY}: Story/Issue ID from the issue tracker (e.g., FB-6, PROJ-123, KAN-42)
• {FEATURE_DOMAIN}: Kebab-case feature name (e.g., user-authentication, payment-processing, notifications)
• Spec Document: Living specification saved at specs/{FEATURE_DOMAIN}/spec.md
  • Blueprint: Context, Architecture, Anti-Patterns (the "why" and "how")
  • Contract: Definition of Done, Regression Guardrails, Scenarios (the "what")
  • Lives permanently with code, updated in same commit as behavior changes
• Plan Document (still exists for transient task planning): Task-level implementation plan at .plans/{TASK_KEY}-{description}.plan.md
  • Defines Delta (what changes) vs Spec which defines State (how it works)
  • Created per-task, discarded after merge
• Story Details: Information from issue tracker (Jira, GitHub Issues, Azure DevOps, etc.)
  • Includes title, description, acceptance criteria, and related context
• User Story Format: Typically follows "As a [user type], I want [goal], so that [benefit]"