/specifold

Specifold Format v0.1 · the architecture layer · the shape of every spec the Specifold skill produces

$ what it is

An agent-native specification format: a software system described as files an agent can build from and a human can reason about. The spec is the durable artifact — the conversation that produces it and any code generated from it are disposable.

v0.1 covers architecture only — a tree of components, their single responsibilities, and the dependencies between them. It does not yet describe features, technologies, data shapes, or code. The version number is a promise the format grows downward, not a claim it is finished.

$ a spec is a directory

my-system/
  specifold.yaml          # root manifest — declares the format version
  <component>.md          # one file per component
  <component>/            # children mirror the tree as subdirs
    <child-component>.md

One file per component. The directory mirrors the tree for humans; the authoritative parent/child link is the parent field.

$ shape (TypeScript)

// specifold.yaml — the root manifest, one per spec
interface SpecRoot {
  spec_format: string;        // format version, e.g. "0.1"
  name: string;               // the system's human name
  root: string;               // id of the root component (parent === null)
  created?: string;           // ISO date the spec was started
}

// <component>.md — frontmatter; the body carries the reasoning
interface Component {
  id: string;                 // stable, lowercase, hyphenated, unique
  title: string;              // human-readable name
  parent: string | null;      // parent id; null for exactly one (the root)
  responsibility: string;     // EXACTLY ONE SENTENCE
  tier?: "core" | "experimental";          // default: core
  status?: "draft" | "open" | "decided";   // default: draft
  depends_on?: string[];      // ids this component needs; must all exist
  open_questions?: string[];  // unresolved decisions parked here
}

$ body contract

The Markdown body carries the why — the most valuable and most perishable content. A component with no body is a ticket, not a spec node.

## Whyrecommended

Why this component exists as its own unit, and why it is shaped so.

## Contractrecommended

What the component provides and what it consumes — Provides: … / Consumes: …

## Essential vs accidentaloptional

What is intrinsic vs an incidental lower-level choice.

## Rejectedoptional

Alternatives considered and why they lose.

$ tier

core

Load-bearing. Expected to survive.

experimental

May not survive. Cheap to delete.

$ status

0draft

Sketched. Boundaries not yet pinned down.

1open

Has unresolved decisions parked in open_questions.

2decided

Settled — responsibility and edges agreed.

$ integrity rules

A spec is valid when all hold. Validity is structural, not aesthetic — it says the tree hangs together, not that the architecture is good. That judgment stays with the human.

1

Unique ids — no two components share an id.

2

Single root — exactly one component has parent: null; the manifest's root names it.

3

Parents exist — every non-root parent is the id of a component in the spec.

4

Dependencies exist — every depends_on id resolves; no dangling edges.

5

No orphans — every component is reachable from the root via parent links.

6

Distinct responsibilities — no two components claim the same one.

7

Single-sentence responsibility.

8

Declared format — specifold.yaml exists and its spec_format is understood.

0.x is unstable — fields may change between minor versions while the format finds its shape. Specs declare the version they were written against. The normative definition, including the Pydantic reference schema, ships with the Specifold skill as SPEC.md.