spec

Manage protocol-level specifications - the contract defining what a system must do.

What is a Spec?

A spec (specification) defines requirements at the protocol/standard level:

• External specs: Standards you implement (LEAF spec, OAuth, OpenAPI)
• Self-authored specs: Your own protocol defining what your system does

Specs are NOT feature breakdowns or epics. They are the source of truth for requirements.

Usage

/spec                           # Show current project's spec status
/spec --import <url>            # Import external spec (GitHub, raw URL)
/spec --init                    # Create new protocol spec for project
/spec --sync                    # Sync imported spec with upstream
/spec --section <name>          # Show specific section of spec

File Structure

spaces/[project]/
├── docs/
│   ├── specs/                  # The protocol spec (source of truth)
│   │   ├── README.md           # Spec overview and compliance status
│   │   ├── api-specification.md # API contract
│   │   ├── data-models.md      # Data structures
│   │   ├── required-features.md # Feature requirements
│   │   └── ...
│   └── adrs/                   # Architecture decisions
└── src/                        # Implementation

ideas/[project]/
├── project-brief.md            # Strategy (private)
└── issues/
    └── 001-auth/
        └── TASK.md             # implements: docs/specs/required-features.md#authentication

Why specs live with code:

• Specs are the contract the code fulfills
• Developers need them alongside implementation
• Changes to spec and code can be atomic commits
• All documentation (specs, ADRs) lives together in docs/

Execution Flow

1. Determine Context

Read: ideas/[project]/project-brief.md    # Strategy context
Glob: spaces/[project]/docs/specs/*.md    # Existing specs

Questions:

• Does this project implement an external spec?
• Or does it need its own protocol spec?

2a. Import External Spec

For projects implementing a standard (like leaf-nextjs-convex → LEAF spec):

/spec --import https://github.com/leafspec/spec

Process:

1. Clone/fetch spec files
2. Copy to spaces/[project]/docs/specs/
3. Create docs/specs/README.md with:
   • Source URL and version
   • Last synced date
   • Compliance checklist
4. Suggest initial TASKs based on spec sections

Sync upstream changes:

/spec --sync

2b. Create Protocol Spec

For projects that need their own spec (like coordinatr):

/spec --init

Conversational creation:

1. What does this system do? (elevator pitch)
2. Who are the actors/users?
3. What are the core operations?
4. What are the API boundaries?
5. What are the data models?

Output structure:

# [Project] Specification

## Overview
[What this system does and why]

## Actors
[Who/what interacts with the system]

## Core Operations
[The fundamental things the system must do]

## API Specification
[Endpoints, inputs, outputs, errors]

## Data Models
[Entity definitions, relationships, constraints]

## Required Features
[Feature requirements organized by domain]

## Test Criteria
[How to verify compliance]

3. Spec Status Dashboard

/spec  # No arguments

Shows:

• Spec source (external URL or self-authored)
• Last updated/synced
• Sections and their implementation status
• Linked TASKs per section

Spec vs Old "Feature Specs"

| Old Model (Wrong) | New Model (Correct) | |-------------------|---------------------| | SPEC-001, SPEC-002... | Single protocol spec | | Feature breakdown | Requirements contract | | Internal planning docs | Source of truth | | Created per feature | Created once, evolved | | TASKs link to SPEC-### | TASKs implement spec sections |

Integration with /issue

When creating a TASK, link to the spec section it implements:

---
implements: docs/specs/required-features.md#authentication
---

The /issue command will prompt:

"Which spec section does this implement? (or 'none' for standalone)"

Compliance Tracking

Status is tracked inline within spec documents at the requirement level:

### §1 Authentication

**Requirements:**
- ✅ User registration with email/password
- ✅ User login with JWT token
- ⏳ Password reset flow
- ⏳ Email verification

**API Endpoints:**
- ✅ `POST /api/auth/register`
- ✅ `POST /api/auth/login`
- ⏳ `POST /api/auth/reset-password`

Status markers:

• ✅ Implemented and working
• 🚧 In progress
• ⏳ Not started

This allows granular visibility into what's done without referencing private TASKs.

The /complete command updates these markers when work is finished.

Self-Authored Spec Guidelines

When creating your own protocol spec:

1. Be specific - Vague specs lead to vague implementations
2. Define boundaries - What's in scope vs out of scope
3. Include test criteria - How do you verify compliance?
4. Version it - Specs evolve; track changes
5. Keep it stable - Changes should be deliberate

Spec Versioning (differs from ADRs)

ADRs are immutable - changes create a new superseding document.

Specs are edited in place - they're living contracts that evolve:

1. Frontmatter version - Use semantic versioning (version: 1.0.0)
2. Git history - Preserves full evolution
3. Git tags - Mark release points (git tag spec-v1.0.0)
4. CHANGELOG - Note significant spec changes

Version bumps:

• Patch (1.0.1): Typos, clarifications, no behavior change
• Minor (1.1.0): New optional features, backwards compatible
• Major (2.0.0): Breaking changes, removed requirements

This keeps specs simple while git provides the audit trail.

Workflow

/spec --init or --import    # Define what to build
        ↓
/issue                      # Create work items that implement spec sections
        ↓
/plan                       # Break down implementation
        ↓
/implement                  # Build against the spec
        ↓
/complete                   # Verify spec compliance

Related Commands

• /issue - Create TASKs that implement spec sections
• /plan - Break down implementation of a TASK
• /validate-spec - Check implementation against spec
• /project-status - See spec compliance overview