a-organvm/speckit

Spec Kit: Specification-Driven Development

Overview

Spec Kit implements Specification-Driven Development (SDD) - a methodology where specifications drive code, not vice versa. Instead of specs serving as documentation for code, code becomes the expression of specifications.

The Power Inversion

Traditional development: Code is truth, specs are scaffolding SDD: Specifications are truth, code is generated output

This eliminates the gap between intent and implementation by making specifications executable through AI.

Commands

/speckit.specify <feature-description>

Creates a comprehensive feature specification from a natural language description.

Usage: /speckit.specify Real-time chat with message history and presence

Output:

• specs/{feature-name}/spec.md - Complete feature specification
• specs/{feature-name}/checklists/requirements.md - Quality validation checklist

Process:

1. Parse user description, extract key concepts (actors, actions, data, constraints)
2. Generate user scenarios with prioritized stories (P1, P2, P3)
3. Define functional requirements (FR-001, FR-002, etc.)
4. Create measurable success criteria
5. Identify key entities
6. Validate against quality checklist
7. Present clarification questions (max 3) if critical ambiguities exist

Guidelines:

• Focus on WHAT users need and WHY
• Avoid HOW (no tech stack, APIs, code structure)
• Make informed guesses using industry standards
• Limit [NEEDS CLARIFICATION] markers to 3 maximum
• Every requirement must be testable

For detailed template: read assets/templates/spec-template.md For command details: read references/commands/specify.md

---

/speckit.plan [tech-context]

Creates an implementation plan from an existing specification.

Usage: /speckit.plan WebSocket, PostgreSQL, Redis or /speckit.plan (will determine tech from context)

Prerequisites: spec.md must exist in the feature directory

Output:

• specs/{feature}/plan.md - Implementation plan with tech decisions
• specs/{feature}/research.md - Technology research and decisions
• specs/{feature}/data-model.md - Entity definitions
• specs/{feature}/contracts/ - API specifications (OpenAPI/GraphQL)
• specs/{feature}/quickstart.md - Validation scenarios

Process:

1. Load feature specification and project constitution
2. Fill Technical Context section
3. Run Constitution Check (evaluate architectural gates)
4. Phase 0: Research unknowns, generate research.md
5. Phase 1: Design data models, generate contracts
6. Re-evaluate constitution compliance post-design

Constitution Gates (if using constitution):

• Simplicity Gate: Using ≤3 projects? No future-proofing?
• Anti-Abstraction Gate: Using framework directly?
• Integration-First Gate: Contracts defined?

For detailed template: read assets/templates/plan-template.md For command details: read references/commands/plan.md

---

/speckit.tasks

Generates an executable task list from the implementation plan.

Usage: /speckit.tasks

Prerequisites: plan.md and spec.md must exist

Output:

• specs/{feature}/tasks.md - Dependency-ordered task list

Process:

1. Load plan.md (tech stack, structure) and spec.md (user stories)
2. Optionally load: data-model.md, contracts/, research.md
3. Generate tasks organized by user story:
   • Phase 1: Setup (shared infrastructure)
   • Phase 2: Foundational (blocking prerequisites)
   • Phase 3+: User Stories in priority order (P1, P2, P3...)
   • Final Phase: Polish & cross-cutting
4. Mark parallelizable tasks with [P]
5. Number tasks (T001, T002...)
6. Generate dependency graph and parallel execution examples

Task Format: [ID] [P?] [Story] Description

• [P] = Can run in parallel (different files, no dependencies)
• [Story] = Which user story (US1, US2, US3)

For detailed template: read assets/templates/tasks-template.md For command details: read references/commands/tasks.md

---

Workflow Example

# 1. Create specification (5 min)
/speckit.specify Real-time chat with message history and user presence

# 2. Generate implementation plan (5 min)
/speckit.plan WebSocket for messaging, PostgreSQL for history, Redis for presence

# 3. Create task list (5 min)
/speckit.tasks

Result (in 15 minutes):

• Complete feature spec with user stories and acceptance criteria
• Detailed implementation plan with technology rationale
• API contracts and data models
• Executable task list organized by user story

Project Constitution

A constitution defines immutable architectural principles for a project. When present at memory/constitution.md, the /speckit.plan command will:

1. Validate against constitutional gates before planning
2. Require justification for any violations
3. Track complexity deviations

Sample principles:

• Library-First: Features start as standalone libraries
• Test-First: TDD mandatory (Red-Green-Refactor)
• Simplicity: Maximum 3 projects, YAGNI
• Integration-First: Real databases over mocks

For constitution template: read assets/templates/constitution-template.md

Key Concepts

User Story Organization

Tasks are grouped by user story to enable:

• Independent implementation
• Independent testing
• Incremental delivery (ship P1, then P2, then P3)

MVP-First Delivery

1. Complete Setup + Foundational phases
2. Implement User Story 1 (P1) → Test → Deploy
3. Add User Story 2 (P2) → Test → Deploy
4. Continue incrementally

Template-Driven Quality

Templates constrain AI behavior for better outcomes:

• Prevent premature implementation details
• Force explicit uncertainty markers
• Enforce test-first thinking
• Prevent speculative features

File Locations

When working in a project:

• Specifications: specs/{feature-name}/
• Constitution: memory/constitution.md

Reference Files

Templates (fill-in artifacts for output)

• assets/templates/spec-template.md - Feature specification template
• assets/templates/plan-template.md - Implementation plan template
• assets/templates/tasks-template.md - Task list template
• assets/templates/constitution-template.md - Project constitution template

Documentation (methodology and command details)

• references/methodology.md - Full SDD philosophy document
• references/commands/specify.md - /speckit.specify command definition
• references/commands/plan.md - /speckit.plan command definition
• references/commands/tasks.md - /speckit.tasks command definition