## 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 <spec>; implement that first or run `/spec:impact <spec-path>` for full analysis"

# Create > 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. - Skill: `latere-ai/create` (Agent Skill) - Install (CLI): `npx skillmds@latest add latere-ai/create` - Raw SKILL.md: https://api.skillmd.com/api/skills/latere-ai/create/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: latere-ai (https://skillmd.com/u/latere-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/latere-ai/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: ` [description...]` - The **first token** is the spec location: `/` where `` is one of the tracks this repo actually uses and `` 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//.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: ` line under `status:` only when the spec's directory does not already name its track): ````markdown --- title: status: drafted depends_on: - affects: -


effort: 
created: 
updated: 
author: your-name
dispatched_task_id: null
---

# 

## 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 <spec>; implement that first
    or run `/spec:impact <spec-path>` for full analysis"