---
name: wf-spec-create
description: Write a new spec from scratch when none exists for the idea yet. Gathers context, explores the codebase, fills the frontmatter, and indexes it in specs/README.md. Use when the user says "create a spec", "write a spec", or "new spec". When a spec already exists but is out of date, use refine instead.
argument-hint: <track/name> [one-line description...]
user-invocable: true
allowed-tools: Read, Grep, Glob, Edit, Write, Agent, Bash(ls *), Bash(mkdir *), Bash(git log *), Bash(git diff *)
---

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

````markdown
---
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
    `/wf-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. If the index keeps a status overview (e.g., a tree of `○`/`◐`/`✅` markers),
   add the spec there as 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 `/wf-spec-breakdown <spec-path> design` to decompose
    into sub-design problems"
  - If small/medium: "Run `/wf-spec-breakdown <spec-path> tasks` to create
    implementable tasks, or `/wf-spec-implement <spec-path>` to implement directly"
  - If dependencies are incomplete: "Blocked by <spec>; implement that first
    or run `/wf-spec-impact <spec-path>` for full analysis"