Spec workflow

Agent Smith evolves through a structured spec process. Each spec is a bounded development increment with a clear goal, scope, dependencies and definition of done.

What is a spec?

A spec is a YAML spec in .agentsmith/specs/ that describes a feature, refactor, or capability addition. The file is named {id}-{label}.yaml, for example 2026-09-27-481bf-ticket-kind-is-a-word.yaml.

.agentsmith/specs/
  done/              # Completed specs (historical reference)
  active/            # Currently in progress
  planned/           # Specified, not yet implemented

Spec ids

A new spec id is minted from the clock: today's UTC date plus four random hex digits, {yyyy-MM-dd}-{xxxx}, for example 2026-08-24-8a3f. Minting needs no knowledge of what anyone else has taken, so a worktree, an agent without network access and two agents working in parallel can all mint safely. The four hex digits make a same-day collision unlikely.

Specs cut from one piece of work form a series. They share one minted number and append a lowercase letter: 2026-08-24-8a3fa, 2026-08-24-8a3fb, 2026-08-24-8a3fc. The letter is appended, not dashed, because a label may itself begin with a one-letter word. The base number of a series is not itself a spec, and a spec that turns up later mints its own number instead of extending the series.

Counter ids such as p0042, p0057a and p0131c-pre are a closed namespace. Every one of them stays valid and is never renamed, but no new ones are minted.

An id is frozen; the file name is a pointer. Every requires: edge, decision file and commit message cites the id, so moving or relabelling a spec file breaks nothing but the pointer to it in context.yaml.

Spec labels

The label after the id is a topic of 2 to 5 words and at most 50 characters. It is area-first: the leading word names the subject area and the rest narrows it, as in checkpoint-partial-restore or ticket-kind-is-a-word, so related specs group together in a directory listing. The claim itself lives in the goal:, one sentence of at most 200 characters.

Spec lifecycle

planned/  -->  active/  -->  done/

Status	Directory	Meaning
Planned	specs/planned/	Specified with goal, scope and definition of done, not yet started
Active	specs/active/	Currently being implemented
Done	specs/done/	Implemented. The spec stays as historical reference

Spec structure

spec: 2026-09-27-481bf
goal: "One sentence stating what the spec makes true."
applies_to: "Which part of the system the spec touches"
requires: ["2026-09-27-481bb", "2026-09-27-481bc"]
scope:
  - What is in and out of this spec
steps:
  - The implementation steps, in order
tests:
  - The tests that prove it
done:
  - "One line: an acceptance criterion that is true once the spec is finished"
  - given: "an optional precondition"
    when: "the trigger"
    then: "the observable result"

spec and goal are required; the schema is .agentsmith/spec.schema.json. A done item is one line, or a scenario with when and then (and an optional given, nothing else) when the criterion has a trigger and an observable result. Every reader sees a scenario as one plain line — GIVEN an optional precondition WHEN the trigger THEN the observable result — in the run's acceptance contract, the execution prompt and the filed ticket alike. A filed ticket shows the spec in a reader's shape, described in Writing a ticket. The reasoning behind the choices goes into a separate decision file, .agentsmith/decisions/{id}.yaml.

Spec tracking

The state section of each context's context.yaml (.agentsmith/contexts/<name>/context.yaml) tracks the specs. A done entry is one index line of at most 400 characters: what shipped, and a pointer to the spec.

state:
  done:
    2026-09-27-481bf: "A ticket says what kind its tracker calls it. -> .agentsmith/specs/done/2026-09-27-481bf-ticket-kind-is-a-word.yaml"
    p0001: "Initial pipeline: fetch ticket, checkout, plan, execute, commit -> .agentsmith/specs/done/p0001-core-infrastructure.yaml"
  active: {}
  planned: {}

Creating a new spec

1. Mint an id and write the spec in specs/planned/ with goal, scope and definition of done
2. Move it to specs/active/ when starting implementation
3. Implement according to the spec, logging decisions in decisions/{id}.yaml
4. Move it to specs/done/ when all acceptance criteria are met
5. Add the state.done line to context.yaml

Spec-first workflow

The spec is always written before implementation starts. This ensures clear scope and prevents scope creep.

Specs in your repositories

The code pipeline applies the same method to the repositories it works on. Each spec a run executes is written to that repository's .agentsmith/specs/done/ and indexed with a state.done line in its context.yaml, so the target repository carries the same planned-to-done record. Those ids are minted from the ticket number plus a series letter: ticket 57 becomes p0057a, p0057b, and so on.