/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

bash

/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

bash

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

bash

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

bash

/spec --sync

2b. Create Protocol Spec

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

bash

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

markdown

# [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

bash

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

yaml

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

markdown

### §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

spec

NPX Install

Tags

SKILL.md Content

/spec

What is a Spec?

Usage

File Structure

Execution Flow

1. Determine Context

2a. Import External Spec

2b. Create Protocol Spec

3. Spec Status Dashboard

Spec vs Old "Feature Specs"

Integration with /issue

Compliance Tracking

Self-Authored Spec Guidelines

Spec Versioning (differs from ADRs)

Workflow

Related Commands