/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:

• Clone/fetch spec files

• Copy to spaces/[project]/docs/specs/

• Create docs/specs/README.md with:

• Source URL and version

• Last synced date

• Compliance checklist

• 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:

• What does this system do? (elevator pitch)

• Who are the actors/users?

• What are the core operations?

• What are the API boundaries?

• 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:

• Be specific - Vague specs lead to vague implementations

• Define boundaries - What's in scope vs out of scope

• Include test criteria - How do you verify compliance?

• Version it - Specs evolve; track changes

• 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:

• Frontmatter version - Use semantic versioning (version: 1.0.0 )

• Git history - Preserves full evolution

• Git tags - Mark release points (git tag spec-v1.0.0 )

• 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