Create

Create a Design Spec

Create a new design spec in specs/ following the spec document model.

Step 0: Parse arguments

$ARGUMENTS has the form: <track/name> [description...]

• The first token is the spec location: <track>/<name> where <track> is one of the tracks this repo actually uses and <name> is the kebab-case spec name without .md. Example: local/live-serve.
• Never assume a fixed track list — tracks come and go. Read the live set from the directories under specs/, plus any track: frontmatter values in use where specs sit directly in a directory that holds no sub-tracks. Take each track's meaning from its section heading and intro in specs/README.md.
• If only a name is given without a track, list the live tracks with those one-line meanings and ask the user which one it belongs to.
• Everything after the first token is a description — a short explanation of what the spec should cover. If no description is provided, ask the user what the spec should address.

Derive the output file path by answering two independent questions from how the tree is actually laid out. They compose: specs/local/003-live-serve.md is a perfectly ordinary path.

If specs/ does not exist yet, bootstrap a flat tree: create specs/, put the first spec directly inside it with the requested track in track: frontmatter, and create specs/README.md in Step 5. Do not force a directory scheme before the project has chosen one.

1. Which directory? If specs/ has track directories, the spec goes in the one it belongs to: specs/<track>/<name>.md. If specs sit directly under specs/, it goes there and the track is recorded as a track: frontmatter field instead.
2. Numbered or not? If the sibling specs in that same directory carry an NNN- prefix, give the new one the next number in that directory — usually its current max + 1, zero-padded to three digits. If they do not, use the bare name. Numbering is a per-directory reading-order convention, not a property of the repo, and a repo may number one directory and not another.

The number is a local ordering hint only. Dependency order lives in depends_on, which resolves repo-root-relative and forms one DAG across the whole tree regardless of how any directory is grouped or numbered.

Step 1: Read context

1. Read specs/README.md to understand the track organization, dependency graph, and what already exists. For a new tree where it is absent, record that Step 5 must create a minimal index.
2. Review the frontmatter schema and spec conventions. Where they are written down varies by repo — look for a document-model spec under specs/, or an internals doc describing how specs are parsed. If neither exists, infer the schema from the most recently updated spec in the tree.
3. Grep spec files for any existing specs that overlap with the proposed topic — check by name and by affects paths. If a closely related spec exists, warn the user and ask whether to proceed, merge, or abort.

Step 2: Explore the codebase

Based on the description, identify which parts of the codebase are relevant:

1. Determine which packages, files, and interfaces the spec will affect.
2. Use Grep and Glob to find existing code, types, and patterns in those areas.
3. Launch Agent subagents (Explore type) for up to 3 independent areas in parallel if the spec spans multiple subsystems.
4. Note existing patterns, interfaces, and constraints that the spec must account for.

The goal is to ground the spec in reality — reference actual file paths, function names, and existing patterns rather than hypothetical code.

Step 3: Identify dependencies

Determine which existing specs this new spec depends on:

1. Check specs/README.md for specs that produce interfaces, types, or infrastructure this spec needs.
2. Check the affects lists of existing specs for overlapping code paths.
3. Only add depends_on entries for specs whose deliverables are prerequisites — not merely related specs.

Also identify which existing specs might depend on this new one (reverse impact). Flag these to the user but do NOT modify them.

Step 4: Write the spec

Create the spec file at the path derived in Step 0 with this structure (add a track: <track> line under status: only when the spec's directory does not already name its track):

---
title: <Human-readable title>
status: drafted
depends_on:
  - <spec paths, or empty list>
affects:
  - <code paths and packages this spec will modify>
effort: <small | medium | large | xlarge>
created: <today's date, YYYY-MM-DD>
updated: <today's date, YYYY-MM-DD>
author: your-name
dispatched_task_id: null
---

# <Title>

## Overview

<2-4 sentences: what this spec delivers and why it matters. State the problem,
the user need, or the architectural gap it fills.>

## Current State

<Brief description of what exists today in the codebase that is relevant.
Reference actual file paths, types, and functions. This grounds the spec in
reality and helps readers understand the starting point.>

## Architecture

<How the solution fits into the existing system. Describe the key components,
their relationships, and where they live in the codebase. Use a diagram
(Mermaid) if the relationships are non-trivial.>

## Components

<For each major component or change:>

### <Component Name>

<What it does, where it lives, key design decisions. Reference existing
patterns in the codebase where relevant. Include:>
- File paths (existing files to modify, new files to create)
- Key types and interfaces
- Integration points with existing code

## Data Flow

<How data moves through the system for the primary use cases. Describe the
request/response path, state transitions, or processing pipeline. Skip this
section if the spec doesn't involve data flow.>

## API Surface

<New or modified API routes, CLI flags, env variables, or configuration
options. Follow the repository's existing reference format. Skip this section
if no external surface changes.>

## Error Handling

<How errors are detected, reported, and recovered from. What failure modes
exist and how the system degrades. Skip this section if error handling is
trivial.>

## Testing Strategy

<What to test and how. Reference existing test patterns in the affected
packages. Identify:>
- Unit tests (per-function, per-method)
- Integration tests (cross-package, end-to-end)
- Edge cases and failure scenarios

Writing guidelines:

• Focus on system design, not inline code. Use references to actual files instead of code blocks where possible.
• Keep sections proportional to complexity — a simple spec doesn't need all sections. Delete sections marked "skip if..." when they don't apply.
• Reference existing patterns with a concrete path from the repository instead of re-explaining the pattern.
• Be specific about file paths and function names. Vague specs produce vague implementations.
• Size the spec appropriately:
  • Small/medium effort: one file, all sections concise. Can be implemented directly.
  • Large/xlarge effort: may be a parent spec that will be broken down via /spec:breakdown. Focus on architecture and component boundaries rather than implementation details.

Step 5: Update specs/README.md

1. Read specs/README.md. If it does not exist, create a minimal index with a title, a short explanation of the track recorded in frontmatter, and the spec table below.
2. Add the new spec to the appropriate track table, maintaining the table's existing order — alphabetical, or by number where the directory is numbered. The link path is whatever Step 0 derived, relative to specs/:

   | [<name>.md](<track>/<name>.md) | Not started | <one-line deliverable> |
   

3. Add the spec to the Status Quo section if appropriate (use ○ for not started).
4. If the spec has dependencies, note them in the dependency graph section if one exists.

Step 6: Commit

Stage the new spec file and the updated specs/README.md. Commit with: specs: add <name> spec for <one-line purpose>

Do NOT push unless the user explicitly asks.

Step 7: Summary

Report to the user:

• The spec file path and a one-line summary
• Dependencies identified (both upstream and downstream impact)
• Effort estimate and rationale
• Suggested next steps:
  • If large/xlarge: "Run /spec:breakdown <spec-path> design to decompose into sub-design problems"
  • If small/medium: "Run /spec:breakdown <spec-path> tasks to create implementable tasks, or /spec:implement <spec-path> to implement directly"
  • If dependencies are incomplete: "Blocked by ; implement that first or run /spec:impact <spec-path> for full analysis"