# specfold: full documentation

> specfold keeps design, plan, and maintenance docs next to your code, linked as a graph and guarded by checks.


---

Source: https://specfold.build/start/

# Tutorial: three steps

> [!TIP]
> In five commands you get a `spec.toml`, a document that governs a code path, and a passing
> `spec check`. Install first: [Install](install.md).

## The steps

1. **Write.** `spec init` writes a starter `spec.toml`; `spec new` stores a document with the
   owner of the code it governs.
2. **Link.** `--governs` records the code path. `spec context` now lists the document for any
   file under it.
3. **Check.** `spec check` runs the rules. `spec agents` prints the lines for an agent's
   instruction file.

## Run it

```console
$ spec init --owner 'services/*={1}' --write
$ spec new sot --governs services/shop/src/cart --title "Cart totals"
$ spec context services/shop/src/cart/total.rs
$ spec check
$ spec agents --for claude
```

## What happened

The `--owner` pattern makes every directory under `services/` an owner, so the document lands in
`services/shop/.spec/sot/`. Its id, `sot:shop/cart-totals`, comes from that place.

`spec context` answers the question an agent or reviewer asks first: which documents must I read
before changing this file?

## Next

- [Document types](../concepts/document-types.md): what to write besides a `sot`.
- [Lifecycle](../concepts/lifecycle.md): how a document becomes `active`.
- [Editing documents](../guides/editing.md): change documents without hand-editing front matter.


---

Source: https://specfold.build/start/install/

# Install

> [!TIP]
> Pick one method. Each gives you two commands, `specfold` and its short alias `spec`.

## Choose a method

### npm

```sh
npm install --save-dev @modootoday/specfold
npx spec --version
```

### cargo

```sh
cargo install specfold
```

### Binary

```sh
sha256sum -c specfold-x86_64-unknown-linux-gnu.tar.gz.sha256
tar -xzf specfold-x86_64-unknown-linux-gnu.tar.gz
```

npm downloads only the build for your machine through platform-specific optional dependencies.
Do not install with `--omit=optional` or `--no-optional`. cargo builds from crates.io and needs a
Rust toolchain.

## Prebuilt targets

Download from the [latest GitHub release](https://github.com/modootoday/specfold/releases/latest).
Each archive holds `specfold` and `spec` (`.exe` on Windows), the README and the licences.

| platform | target | archive |
| --- | --- | --- |
| Linux x64 (glibc 2.35+) | `x86_64-unknown-linux-gnu` | `.tar.gz` |
| Linux arm64 (glibc 2.35+) | `aarch64-unknown-linux-gnu` | `.tar.gz` |
| macOS Intel | `x86_64-apple-darwin` | `.tar.gz` |
| macOS Apple silicon | `aarch64-apple-darwin` | `.tar.gz` |
| Windows x64 | `x86_64-pc-windows-msvc` | `.zip` |

Archive names are `specfold-<target>` plus the extension. glibc 2.35 covers Ubuntu 22.04 and newer.

## Verify the download

Every archive has a `.sha256` file next to it.

```sh
sha256sum -c specfold-x86_64-unknown-linux-gnu.tar.gz.sha256   # Linux
shasum -a 256 -c specfold-aarch64-apple-darwin.tar.gz.sha256   # macOS
```

On Windows, compare `Get-FileHash specfold-x86_64-pc-windows-msvc.zip -Algorithm SHA256` with the
`.sha256` file. Put the unpacked directory on your `PATH`.


---

Source: https://specfold.build/concepts/

# Concepts

> [!TIP]
> A document is a Markdown file with front matter. It has a type, an owner, a status and
> relations. Together the relations form a graph that `spec check` keeps honest.

## Read in this order

1. **[Document types](document-types.md)** — `sot`, `adr`, `plan` and eight more, and when to use each.
2. **[Lifecycle](lifecycle.md)** — statuses, and why they only move forward.
3. **[Owners and ids](owners-ids.md)** — where a document lives and how its id is made.
4. **[The graph](graph.md)** — relations, `spec context` and `spec graph`.
5. **[Checks](checks.md)** — rules, guards, plugins and audits.
6. **[Times and tasks](times-relations.md)** — timestamps, time zones and task items.


---

Source: https://specfold.build/concepts/document-types/

# Document types

> [!TIP]
> Pick the type by the question the document answers: what holds now (`sot`), why we chose
> (`adr`), what we will do (`plan`), or how to do it (`guide`, `runbook`).

## Types

There are <!-- spec:count rows="Types" -->11<!-- /spec:count --> built-in types.

| type | key | what it is |
| --- | --- | --- |
| sot | slug | a source of truth: the rule that holds now |
| adr | timestamp | a decision and the reason for it |
| plan | timestamp | a plan of work and its running record |
| research | timestamp | a study, benchmark or evaluation |
| evidence | timestamp | the cover of a bundle of measurements or raw outputs |
| audit | timestamp | an audit snapshot; its body is sealed once committed |
| page | slug | the specification of one screen or page |
| design | timestamp | a bundle of design boards |
| guide | slug | how to develop, operate or use something |
| runbook | slug | a step-by-step operational procedure |
| change | timestamp | one user-facing change for the release notes |

## Slug or timestamp

A **slug** key names something that stays: a rule, a page, a procedure. Its id never changes,
and the body is updated in place.

A **timestamp** key names something that happened at a moment: a decision, a study, a plan. A
new decision is a new document that supersedes the old one, so history stays readable.

## Which one to write

- The code must always behave a certain way: write a `sot`, and give it a `verify` command.
- You chose between options: write an `adr` and link the `sot` it shapes.
- Work spans several commits: write a `plan` with task items.
- You measured something: write `research`, and attach raw outputs as `evidence`.
- Someone repeats a procedure: write a `runbook`.

## Change the set

Projects can disable, change or add types in `spec.toml` under `[types.<name>]`: key, form,
statuses, fields, template and transitions. `spec schema <type>` prints a type's front matter.

```console
$ spec schema adr
$ spec new adr --title "Round totals half up"
```

Next, see how a document moves through its [lifecycle](lifecycle.md).


---

Source: https://specfold.build/concepts/lifecycle/

# Lifecycle

> [!TIP]
> A document starts as `draft`, becomes `active`, and ends `superseded`, `archived` or
> `rejected`. Statuses only move forward, and `spec set` is the only way to change them.

## The flow

```mermaid
flowchart LR
  new([spec new]) --> draft
  draft -->|spec set status=active| active
  draft --> rejected
  active -->|a successor supersedes it| superseded
  active --> archived
```

## The statuses

| status | meaning |
| --- | --- |
| `draft` | being written; not binding yet |
| `active` | the document that holds now |
| `superseded` | replaced by exactly one successor |
| `archived` | no longer relevant, kept for history |
| `rejected` | a draft that was not accepted |

## Changing status

```console
$ spec set sot:shop/cart-totals status=active
$ spec set adr:root/20261030 rel.supersedes+=adr:root/20250101
```

`spec set` writes directly and accepts `--dry-run`. It refuses a jump the type does not allow, and
sealed or closed documents. Rule S6 then checks the fields the new status requires.

## What the rules check

- **T1**: a superseded document has exactly one successor.
- **T2**: status only moves forward, along the type's `transitions`.
- **T3**: sealed documents, such as a committed `audit`, keep their body.
- **T4**: an edited body moves its `updated` date.
- **S6**: a status has the fields it requires.

`spec log <id>` shows the history of a document's status and relations, read from git.

## Custom transitions

A type can set its own `transitions` (from → list of to) and `require_when` (status → required
keys) in `spec.toml`. `spec explain T2` prints the rule and how to fix a finding.

Next: where a document lives, in [Owners and ids](owners-ids.md).


---

Source: https://specfold.build/concepts/owners-ids/

# Owners and ids

> [!TIP]
> Each owner (the repository root, an app, a package) keeps its documents in its own `.spec/`.
> A document's id, `<type>:<owner>/<key>`, is computed from where it lives.

## Owners

Owners are found through package manifests (`package.json`, `Cargo.toml` and others) or
`[owners]` patterns in `spec.toml`. A pattern such as `services/*={1}` makes every directory
under `services/` an owner named after the directory.

`spec new` stores a document with the owner of the code it governs. A document without
`rel.governs` stays with the root owner. Rule **P1** reports documents that live with the wrong
owner.

```console
$ spec owners
$ spec new sot --governs services/shop/src/cart --title "Cart totals"
```

## Ids

| part | example | from |
| --- | --- | --- |
| type | `sot` | the document's type |
| owner | `shop` | the owner directory |
| key | `cart-totals` | the slug or UTC timestamp |

So the file `services/shop/.spec/sot/cart-totals.sot.md` has the id `sot:shop/cart-totals`. A
document with chapters or attachments is a directory with `index.<type>.md` instead.

Rule **S2** checks that the id matches the path, and **I1** that ids are unique across every root.

## Moving

`spec mv <id> --slug <new>` moves or renames a document and rewrites every reference to it.
`spec import` brings in a whole layout and writes a frozen alias table, so old ids keep
resolving (rules **I2**, **I3**).

## Public paths

Published paths, such as a package directory, may hold no spec document (rule **V1**). The
`[public]` table names the private owner their documents go to instead.

Next: how documents connect, in [The graph](graph.md).


---

Source: https://specfold.build/concepts/graph/

# The graph

> [!TIP]
> Relations are written once, on the document that makes them. specfold derives the graph on
> every run, so `spec context` can tell you which documents govern a file.

## Relations

| relation | points at | meaning |
| --- | --- | --- |
| `rel.governs` | code paths | this document rules that code |
| `rel.supersedes` | a document | this replaces an older one |
| `rel.implements` | a document | this carries out a plan or rule |
| `rel.evidence` | a document | this backs a claim with data |
| `rel.depends_on` | a document | this needs another to hold |

Body references are `[[<id>]]` or `[[<id>#<anchor>]]`. Rules **L1** and **L3** check that they
resolve and point at the right types.

## A small graph

A plan implements a source of truth, which depends on a decision. Dashed lines are code paths.
This block is the output of `spec graph --format mermaid` on the tutorial repository.

<!-- spec:graph format=mermaid source=tutorial -->

```mermaid
graph LR
  d0["adr:root/20261029190946"]
  d1["plan:shop/20261029190949"]
  d2["sot:shop/cart-totals"]
  d1 -->|implements| d2
  d2 -->|depends_on| d0
  p0[/"services/shop/src/cart"/]
  d0 -.->|governs| p0
  p1[/"services/shop"/]
  d1 -.->|governs| p1
  d2 -.->|governs| p0
```

<!-- /spec:graph -->

## Ask the graph

```console
$ spec context services/shop/src/cart/total.rs
$ spec graph impact sot:shop/cart-totals
$ spec graph chain adr:root/20261029190946
$ spec graph consumers org:adr:root/20261030000000
```

`spec context` lists the documents to read before changing a path. `impact` lists what reaches a
document, with the relation and distance. `chain` shows a supersede chain in both directions. `consumers` lists the documents, in this
repository and in each `[remotes]` directory on disk, whose relations or pins name a document
through a remote. In a shared repository, list the consuming repositories as remotes and run it
before changing a shared decision; `--json` feeds a dashboard. Nothing is fetched.

## Draw it in a terminal

`spec graph` prints a tree from the documents nothing points at. A document already shown ends
in `(*)`, and `--depth N` stops N relations away.

```console
$ spec graph
sot:shop/cart-totals  [draft]
├─ depends_on → adr:root/20261029190946  [draft]
│  └─ governs → services/shop/src/cart
└─ governs → services/shop/src/cart
```

`--format box` draws layered boxes sized to `COLUMNS`, and falls back to the tree when the graph
is too wide or over 60 documents. `--format mermaid` and `--format dot` feed a Markdown renderer
or Graphviz. `--ascii` uses plain lines, chosen automatically outside UTF-8 locales.

Next: how the graph is kept honest, in [Checks](checks.md).


---

Source: https://specfold.build/concepts/checks/

# Checks

> [!TIP]
> `spec check` runs the rules and reports each finding by rule id with a fix. Guards scan any
> file, plugins add rules, and `spec audit` finds what passes yet needs attention.

## How a check runs

```mermaid
flowchart LR
  A[documents + spec.toml] --> B[spec check]
  B --> C{findings?}
  C -->|none| D[exit 0]
  C -->|errors| E[exit 1 + rule ids]
  E --> F[spec explain RULE]
  F --> G[spec fix --write]
  G --> B
```

## Run the rules

```console
$ spec check --staged     # before committing
$ spec check --new        # documents not in the last commit
$ spec check --summary    # findings per rule; -q lists errors only
```

`spec explain <rule>` says why a rule exists and how to fix it. The full list is in
[Rules](../reference/rules.md).

## Unknown keys

A front matter key outside the common set and the type's fields is a warning (**S1**). Keep a
key for one type with `[types.<type>] fields = [...]`, or for every type with
`[check] extra_keys = ["team", "review_*"]`.

## Numbers that stay true

A number in prose can name its source, and `spec check` warns when it drifts (**N1**).
`spec fix --write` rewrites it. Sources are spec's own counts, never shell commands.

```md
We keep <!-- spec:count find type=adr status=active -->12<!-- /spec:count --> active decisions.
```

## Guards, plugins and audits

- **Guards** (`[[guards]]`, `spec guard`) check files and commit messages for denied terms,
  patterns, files, sizes and secrets. Terms can come from an environment variable and are masked.
- **Plugins** (`[[plugins]]`) speak `specfold.plugin.v1` JSON over stdin and stdout. Only
  programs named in `spec.toml` run.
- **Audits** (`spec audit`) report stale documents, orphans, stalled plans and drifted agent
  assets. `spec audit record` seals a review as an `audit` document.

Pin a document to a commit with `spec set <id> verified_at=HEAD`; `spec audit --kind stale` then
reports later commits to the governed paths.


---

Source: https://specfold.build/concepts/times-relations/

# Times and tasks

> [!TIP]
> specfold writes every time in UTC and reads common forms, including a few named zones.
> Checkbox items in a body are counted as tasks.

## Written times

Timestamp keys (`YYYYMMDDHHMMSS`) are UTC. specfold writes `created` and `updated` as RFC 3339
times in UTC, such as `2026-10-30T02:21:00Z`. Times are compared by their UTC day.

## Read times

| form | example | accepted |
| --- | --- | --- |
| date | `2026-10-30` | yes |
| RFC 3339 with offset | `2026-10-30T11:21:00+09:00` | yes |
| named zone | `2026-10-30 11:21 KST` | UTC, GMT, KST, JST only |
| ambiguous zone | `2026-10-30 11:21 CST` | refused |

Named zones are a reading aid only. Rule **S5** checks that dates are valid and that `updated` is
not before `created`.

## Task items

Checkbox items (`- [ ]`, `- [x]`) in a body are tasks.

```console
$ spec show plan:shop/20261029190949
$ spec show plan:shop/20261029190949 --tasks
```

`spec show` reports a document's progress; `--tasks` lists each item with its file and line.
`spec audit` reports plans whose tasks are all ticked but that are still active, and archived
plans with tasks still open.

## Related

- [Lifecycle](lifecycle.md): when a plan should move to `archived`.
- [Checks](checks.md): the audit kinds.


---

Source: https://specfold.build/guides/agents/

# Using with AI agents

> [!TIP]
> Give the agent the lines from `spec agents`, or serve every command over MCP with `spec mcp`.
> Every command takes `--json` and prints the next command to run.

## The agent loop

1. **Read.** `spec context <path> --json` lists the documents that govern a file.
2. **Change.** `spec edit` and `spec set` update a document without hand-editing it.
3. **Check.** `spec check --staged -q` runs before the commit.

## Instructions and MCP

```console
$ spec agents --for claude
$ spec mcp
$ spec help --json
```

`spec agents --for <claude|codex|gemini|cursor|copilot|generic>` prints the lines for an agent's
instruction file. `spec mcp` serves every command as an MCP tool over stdio. `spec help --json`
describes every command, argument, example and output schema.

## Agent assets

Skills, rules, subagents and instruction files (`AGENTS.md`, `CLAUDE.md`) are declared in
`spec.toml` and read beside the documents. They carry no ids.

```toml
[[assets]]
kind = "skill"            # skill, rule, agent or instructions
path = ".agents/skills"
```

`spec assets` lists what was found and the documents each asset names. `spec check` reports
asset front matter (**A1**), duplicate names (**A2**) and paths or `spec` commands that do not
exist (**A3**).

## Copies that never drift

A tool copy can declare its source:

```toml
[[assets]]
kind = "skill"
path = ".claude/skills"
copy_of = ".agents/skills"
```

`spec sync assets` previews the copies; `--write` applies them, only inside roots with
`copy_of`. Files the source lacks stay unless `--prune`. `spec audit --kind drift` names copies
that differ.

## This site for agents

Every page has its Markdown source at `<page>/index.md`, listed in [llms.txt](../llms.txt).


---

Source: https://specfold.build/guides/ci/

# Checks in CI and hooks

> [!TIP]
> Run `spec check --staged` in a pre-commit hook and `spec check` in CI. specfold prints hook
> snippets but never installs them itself.

## Steps

1. **Print a hook.** `spec hook print --for git` (or `pre-commit`, `lefthook`, `husky`).
2. **Add it yourself** to the hook manager you already use.
3. **Run the full check in CI**, with guards over the pushed range.

## Commands

```console
$ spec hook print --for lefthook
$ spec check --staged -q
$ spec check
$ spec guard --range origin/main..HEAD
```

`spec check` exits 1 on errors, so any CI system can gate on it. `--summary` gives findings per
rule, and `--json` gives one object for tooling.

## Adopt gradually

`spec check --write-baseline` records today's findings in a committed file, so only new findings
fail. `[check] severity` sets a rule to `error`, `warn` or `off`. `[check] strict` lists paths that
never get a baseline.

## Verify sources of truth

`spec verify` runs the `verify` commands of `sot` documents (rule **X1**). `[verify]` sets the
deadline, parallel jobs and the shell.

## In CI

`spec check --format` prints a document CI systems read instead of the text: `github` (workflow annotations, plus a table in the step summary), `sarif` (code scanning), `gitlab` (Code Quality) or `rdjson` (reviewdog). The exit code is the same as without it.

The repository's `action.yml` installs a release, checks the archive against its `.sha256` file, and runs `spec check`. Pin `version` to a tag from the releases page:

```yaml
name: specs
on: [pull_request]
permissions:
  contents: read
  security-events: write   # only for the SARIF upload
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: modootoday/specfold@<tag>
        with:
          format: sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: spec-check.sarif.json }
```

On a pull request the action checks only what it changes, from the merge base with the base branch (`changed: auto`, deepening a shallow checkout as needed); `changed: off` checks everything. The release installed is the tag the action is pinned to; pinned to a branch, a commit SHA or used as `./`, the action has no release to match and needs `version: <tag>` (GitHub fills in a composite action's own ref only for release-style pins). `fail-on` limits which rules fail the step, and `fail-on: none` only reports. With `format: github` (the default) the findings show up on the pull request without the upload step. For pre-commit, the repository ships `.pre-commit-hooks.yaml` (`spec-check`, `spec-check-push`); they need pre-commit 4.4.0 or later and `spec` on PATH.


---

Source: https://specfold.build/guides/import/

# Importing an existing layout

> [!TIP]
> Describe the old layout in an import map, review the plan, then apply it. Old ids and paths
> keep resolving through a frozen alias table.

## Steps

1. **Start from a preset or write a map.** `spec import --preset adr-tools|madr|log4brains`
   prints a starter map for those layouts; edit it for your templates and statuses.
2. **Set the alias table.** Applying needs `[aliases] file` in `spec.toml`; old file names,
   numbers and links resolve through it.
3. **Review the plan.** `spec import --map import.toml` changes nothing. Settle every line
   marked `!` (the plan's `next` names the `[status]` line to add), then plan again.
4. **Apply.** `--apply` alone previews; `--apply --write` moves everything and writes the alias
   table.

```console
$ spec import --preset madr > import.toml
$ printf '\n[aliases]\nfile = ".spec/_aliases.tsv"\n' >> spec.toml
$ spec import --map import.toml
$ spec import --map import.toml --apply --write
$ spec check
```

## The map

| Key | What it does |
| --- | ------------ |
| `[[sources]]` | `glob`, `exclude`, `type`, `owner`, `key` (`name`, `created`, `first-commit`) and a `name` regex with `key`, `slug` and `alias` groups |
| `[status]` | Old status to new status, matched as written, then in lower case |
| `[[status_patterns]]` | A regex and a status, for values with more than a word |
| `[body]` | Where the body keeps the status and the date |
| `[body.links]` | A line phrase and the relation it records |
| `[keys]` | Old frontmatter key to new key, `rel.<kind>`, or `-` to drop it |
| `stem_aliases` | Also record each old file name as an alias |
| `strip_title_number` | `# 2. Use X` becomes the title `Use X` |

### Status patterns

```toml
[[status_patterns]]
pattern = '^superseded by\b(?P<by>.*)$'
status = "superseded"
```

The `by` group names the replacing record, such as `[ADR-0002](0002-use-y.md)` or `ADR-0002`.
When that record is in the same import, it gets `rel.supersedes` to the old one. When it is
not, the row needs a decision.

### Body metadata

```toml
[body]
status = "section:Status"     # first line under "## Status"
date = "line:Date"            # "Date: 2024-03-01"
drop_status_section = false   # true removes the Status section once it is in frontmatter

[body.links]
Supersedes = "supersedes"
"Superseded by" = "-"         # the newer record lists the link
```

`status` and `date` take `section:<heading>`, `bullet:<label>` (`* Label: value`) or
`line:<label>`. Frontmatter wins where both have a value. The date becomes `created`.

### What the plan reports

- Relative links between imported records are rewritten to the new paths. Links to files
  outside the import are left for rules **L1** and **L2**.
- A body that still has its Status section is noted, not changed, unless
  `drop_status_section = true`.
- A file name that is mostly non-ASCII gives a slug without its words. The title is kept, and
  `spec mv <id> --slug <slug> --write` renames it.

## After the move

Rules **I2** and **I3** keep the alias table honest: aliases point at one document, and the
table gains no rows. `[forbid]` keeps retired layouts from coming back (rule **Z1**).


---

Source: https://specfold.build/guides/editing/

# Editing documents

> [!TIP]
> Writes are previews until `--write`, except `new` and `set`, which write directly and accept
> `--dry-run`. Sealed and closed documents are refused.

## Create

```console
$ spec new plan --governs services/shop --title "Checkout launch"
$ spec new skill --title review --description "Review a change"
```

## Front matter

```console
$ spec set <id> status=active
$ spec set <id> tags+=money
```

## Bodies

`spec edit` replaces or appends to one section or the whole body, and bumps `updated`.

```sh
spec edit <id> --section Notes --text "Ship on Friday." --write
spec edit <id> --section Notes --write < notes.md
cat body.md | spec edit <id> --write
spec edit <id> --new-section Risks --after Plan --text "None yet." --write
spec edit <id> --row "Login" --cell Status=done --write
```

## Move and fix

`spec mv <id> --slug <new>` moves a document and rewrites every reference to it. `spec fix`
applies fixes that need no judgement; `spec fix --rule I2 --pick <id>` resolves a duplicate alias.

## In an editor

`spec lsp` serves the findings of `spec check` as diagnostics over the Language Server Protocol
(stdio). It checks unsaved buffers, offers each `spec fix` replacement as a quick fix, and runs
only the `--write` fix commands it offered. It finds the repository from the editor's root, or
from `spec lsp --dir <path>`. Point any LSP client at it for Markdown files.

Neovim (0.11 or later):

```lua
vim.lsp.config("specfold", { cmd = { "spec", "lsp" }, filetypes = { "markdown" }, root_markers = { "spec.toml", ".git" } })
vim.lsp.enable("specfold")
```

Helix (`languages.toml`):

```toml
[language-server.specfold]
command = "spec"
args = ["lsp"]

[[language]]
name = "markdown"
language-servers = ["marksman", "specfold"]
```

VS Code: specfold ships no extension; use a generic LSP client extension with the command
`spec lsp` for Markdown files.


---

Source: https://specfold.build/guides/attachments/

# Attachments

> [!TIP]
> `spec attach` registers files with a document and records their SHA-256. Small files stay in
> the repository; larger ones go to a store you configure.

## Commands

```console
$ spec attach <id> results.csv --write
$ spec files <id>
$ spec fetch <id>
```

## Stores

A store is a directory, or a command you already trust (rclone, aws, gsutil, wrangler). specfold
contains no network code and never handles credentials. `[files] inline_max_bytes` sets the
limit for the repository.

## Rules

- **P2**: every attachment is registered.
- **P3**: repository attachments stay small.
- **E1**: recorded attachments carry a matching hash.
- **E2**: stored attachments exist in the store.


---

Source: https://specfold.build/reference/commands/

# Commands

> [!TIP]
> Commands are grouped below. `spec <command> --help` shows arguments and examples,
> `spec help <command> --markdown` prints one command's reference page, and every command takes
> `--json`.

## Query

- `spec context` — The documents that govern code paths: read this before changing code
- `spec find` — Find documents by words, type, owner, status or tag
- `spec show` — Frontmatter, outline, one section, or relations of a document
- `spec resolve` — Resolve an id, alias, path or slug to one document
- `spec graph` — Graph queries: impact, chain, governs, consumers; or the whole graph
- `spec owners` — Owners, their documents and where public owners store theirs
- `spec assets` — Agent skills, rules, subagents and instruction files declared under [[assets]]
- `spec log` — The history of a document's status and relations, from git
- `spec census` — Counts of documents, references and attachments

## Write

- `spec new` — Create a document at the place its owner and type decide
- `spec set` — Change frontmatter with the lifecycle enforced
- `spec edit` — Replace or append to a section or the whole body; previews until --write
- `spec mv` — Move or rename a document and rewrite every reference to it
- `spec fix` — Apply fixes that need no judgement
- `spec sync` — Copy asset sources over the [[assets]] roots that declare copy_of; previews until --write
- `spec attach` — Register files with a document, in the repository or the store
- `spec fetch` — Download a document's stored attachments, verified by hash
- `spec files` — A document's attachments and where each is kept

## Check

- `spec check` — Run the rules
- `spec verify` — Run sot verify commands
- `spec guard` — Run guards over files and commit messages
- `spec audit` — Diagnose what passes the rules yet needs attention; build review packs; record audits
- `spec explain` — Why a rule exists and how to fix it; or the configuration keys
- `spec schema` — Document types and their frontmatter; or output schema names

## Set up and connect

- `spec init` — Write a starter spec.toml
- `spec import` — Bring documents from another layout in through an import map
- `spec agents` — The lines to put in an agent's instruction file
- `spec hook` — Hook snippets for git, pre-commit, lefthook or husky
- `spec plugins` — Configured plugins and what they provide
- `spec export` — Export through an exporter plugin
- `spec mcp` — Serve these commands as MCP tools over stdio
- `spec lsp` — Serve check findings as editor diagnostics (Language Server Protocol over stdio)
- `spec help` — Commands and arguments; with --json, the whole command tree

## All commands

There are <!-- spec:count rows="All commands" -->33<!-- /spec:count --> commands. This table is
generated by `spec help --markdown`; do not edit it by hand.

<!-- spec:commands:begin -->

| command | what it does |
| ------- | ------------ |
| `spec context` | The documents that govern code paths: read this before changing code |
| `spec find` | Find documents by words, type, owner, status or tag (also `spec list`, `spec ls`) |
| `spec show` | Frontmatter, outline, one section, or relations of a document |
| `spec resolve` | Resolve an id, alias, path or slug to one document |
| `spec graph` | Graph queries: impact, chain, governs, consumers; or the whole graph |
| `spec owners` | Owners, their documents and where public owners store theirs |
| `spec assets` | Agent skills, rules, subagents and instruction files declared under [[assets]] |
| `spec log` | The history of a document's status and relations, from git |
| `spec new` | Create a document at the place its owner and type decide |
| `spec set` | Change frontmatter with the lifecycle enforced |
| `spec edit` | Replace or append to a section or the whole body; previews until --write |
| `spec mv` | Move or rename a document and rewrite every reference to it |
| `spec fix` | Apply fixes that need no judgement |
| `spec sync` | Copy asset sources over the [[assets]] roots that declare copy_of; previews until --write |
| `spec attach` | Register files with a document, in the repository or the store |
| `spec fetch` | Download a document's stored attachments, verified by hash |
| `spec files` | A document's attachments and where each is kept |
| `spec init` | Write a starter spec.toml, or upgrade an existing one |
| `spec import` | Bring documents from another layout in through an import map |
| `spec check` | Run the rules |
| `spec verify` | Run sot verify commands |
| `spec guard` | Run guards over files and commit messages |
| `spec audit` | Diagnose what passes the rules yet needs attention; build review packs; record audits |
| `spec census` | Counts of documents, references and attachments |
| `spec doctor` | Read-only setup diagnosis: configuration, conflict markers, ignored local documents |
| `spec explain` | Why a rule exists and how to fix it; or the configuration keys |
| `spec schema` | Document types and their frontmatter; or output schema names |
| `spec help` | Commands and arguments; with --json, the whole command tree |
| `spec agents` | The lines to put in an agent's instruction file |
| `spec hook` | Hook snippets for git, pre-commit, lefthook or husky |
| `spec plugins` | Configured plugins and what they provide |
| `spec export` | Export through an exporter plugin |
| `spec mcp` | Serve these commands as MCP tools over stdio |
| `spec lsp` | Serve check findings as editor diagnostics (Language Server Protocol over stdio) |

<!-- spec:commands:end -->


---

Source: https://specfold.build/reference/rules/

# Rules

> [!TIP]
> Each finding names a rule id. `spec explain <id>` says why the rule exists and how to fix a
> finding; `spec check --rule <id>` runs just that rule.

## Structure

| rule | checks that |
| --- | --- |
| **S1** | frontmatter parses and has the required keys |
| **S2** | id matches the path |
| **S3** | every file in a spec directory belongs to a document |
| **S4** | status is one the type allows |
| **S5** | dates are ISO and updated is not before created |
| **S6** | a status has the fields it requires |
| **S7** | a document has the sections its type requires (`spec new` writes them; the finding names the `spec edit --new-section` command) |

## Identity

| rule | checks that |
| --- | --- |
| **I1** | ids are unique across every root |
| **I2** | aliases do not shadow ids and point at one document |
| **I3** | the alias table gains no rows |

## Links

| rule | checks that |
| --- | --- |
| **L1** | every [[reference]] resolves to one document |
| **L2** | documents are cited by id, not by path |
| **L3** | relations resolve and point at the right types |
| **L4** | anchors are unique within a document |
| **L5** | governed paths exist |
| **L6** | citations outside documents still resolve |
| **L7** | pinned remote documents are unchanged |

A reference or relation written `<name>:<id>` names a document in another repository listed
under `[remotes.<name>]`. L1 and L3 check it when that directory is on disk, with the same type
rules as local targets, and skip it when the directory is absent, so a CI job without that
checkout does not fail. `spec show <name>:<id>` reads it; nothing writes there.
L6 checks `[[<name>:<id>]]` in files listed under `[cites]` the same way. For checking only, a
translation may name a remote source (`rel.translation_of: [org:guide:root/setup]`); R1 compares
its `source_rev` with the remote body, and `spec set <id> --source-rev` records it. `spec new
--translation` does not start from a remote source, because nothing is copied out of a remote:
copy the document into this repository first, or translate it in its own repository. `spec doctor` lists every remote,
its directory and whether it is present.

A document can pin a remote document by content when it depends on that exact text:
`spec set <id> --pin org:guide:root/setup` records `pins: {org:guide:root/setup: sha256:…}`, the
same body hash as a translation's `source_rev`. L7 warns when the remote body has changed; review
the change, then pin again. `spec set <id> --unpin org:guide:root/setup` removes a pin. A pin of a document that does not exist there is an error, and an
absent remote directory is skipped.

## Lifecycle

| rule | checks that |
| --- | --- |
| **T1** | superseded documents have exactly one successor |
| **T2** | status only moves forward |
| **T3** | sealed documents keep their body |
| **T4** | an edited body moves its updated date |
| **T5** | exceptions are reviewed by their date |

A document that departs from another on purpose names it with `rel.exception_of` and sets
`review_by: YYYY-MM-DD`. T5 warns when `review_by` is missing or not a date, and once the date has
passed (UTC). Renew it with `spec set <id> review_by=<date>` (set refuses a value that is not a date). When the
rule is kept again, retire the exception with `status=rejected`, or supersede it with a newer one.
Superseded and rejected exceptions are not checked. An exception that names itself is refused by
`spec set` and warned by T5. `spec audit --kind exception` lists the overdue ones. A local exception
lives in `.spec.local`, so it stays out of the shared repository.

T5 is a warning by default. To fail the check on an overdue exception, raise it in `spec.toml`:

```toml
[check.severity]
T5 = "error"
```

## Visibility

| rule | checks that |
| --- | --- |
| **V1** | no spec documents under public paths |
| **V2** | committed documents do not cite local ones |
| **V3** | external notes cite documents that exist |

## Placement and attachments

| rule | checks that |
| --- | --- |
| **P1** | documents live with the owner of the code they govern |
| **P2** | every attachment is registered |
| **P3** | repository attachments stay small |
| **E1** | recorded attachments carry a matching hash |
| **E2** | stored attachments exist in the store |

## Retired layouts

| rule | checks that |
| --- | --- |
| **Z1** | retired layouts and identifiers stay retired |

## Verification

| rule | checks that |
| --- | --- |
| **X1** | a source of truth's verify commands pass |
| **X2** | an active source of truth says how it is verified |

## Generated documents

| rule | checks that |
| --- | --- |
| **G1** | generated documents match their generator |

## Guards

| rule | checks that |
| --- | --- |
| **U1** | guards pass |

## Agent assets

| rule | checks that |
| --- | --- |
| **A1** | agent assets have the frontmatter their tools read |
| **A2** | asset names are unique within a tool |
| **A3** | paths and spec commands in agent assets exist |
| **A4** | agent assets use repository paths, not machine paths |

A3 does not read URLs, ids, globs, placeholders such as `<id>`, or git refs such as `origin/main` and `refs/heads/main` as paths. A4 reports home directories (`/Users/<name>`, `/home/<name>`, `C:\Users\<name>`) but not the hosted CI runner's `/home/runner/`, which is the same on every run; `/home/runner2/` is still reported.

## Translations

| rule | checks that |
| --- | --- |
| **R1** | translations are current with their source |
| **R2** | translations are where the `[translations]` layout expects them |

A translation names its source with `rel.translation_of` and records `source_rev`, a hash of the source body (`sha256:` and 12 hex digits) with frontmatter removed and whitespace collapsed, so it needs no git history and reformatting does not count. For a bundle, the hash covers the main file and then its chapters in path order. When the source body changes, R1 warns until the translation is updated and `spec set <id> --source-rev` records the source again. When git still has a commit with the recorded revision, the warning names the sections that changed since, for example `in Install (1 paragraph changed), Support (new)`; chapter sections are prefixed with the chapter file name. A source that no longer exists is an L3 finding. `spec census --translations` lists every translation's state, the changed sections of those behind, and the sources each language lacks. It exits 1 when anything is behind or missing; `--fail-on stale` fails only on translations that are behind or unrecorded, and `--fail-on none` reports without failing.

R1 also checks the values. `lang` must be a language tag (BCP 47, such as `ko`, `ja`, `pt-BR`). `source_rev` must be `sha256:` and 12 hex digits; `spec set` refuses other values. One source should have one translation per language. A translation must name an original: naming itself or another translation is an error, and the message names the original to use. `spec census --translations` lists only originals as sources. A translation's frontmatter looks like this:

```yaml
lang: ko
rel:
  translation_of: [guide:shop/setup]
source_rev: sha256:3f2a9c0b1d4e
```

A translation can also be paired by place, without frontmatter, when `spec.toml` sets `[translations] layout`. With `layout = "suffix"`, `guide:shop/setup-ko` is the `ko` translation of `guide:shop/setup`: same type and spec directory, slug ending in `-<lang>`. With `layout = "dir"`, the translation has the source's slug under an owner in a `<lang>` directory of the source's owner, for example `services/shop/ko/.spec/guide/setup.guide.md`; that directory must be an owner (`[[owners.kinds]] pattern = "services/*/ko"`). `<lang>` is one of `languages`. Timestamp-keyed translations keep their own timestamp and are paired by slug. `rel.translation_of` and `lang` in frontmatter win over the layout. R2 reports a document placed as a translation with no source, or more than one, in the matching place; `rel.translation_of` that names another document than the layout; and `lang` that differs from the language of its place. R2 warns; `strict = true` makes it an error. `spec fix --translations` previews writing `rel.translation_of` and `lang` into every pair the layout infers, and `--write` applies it.

`spec new --translation <lang> --from <id>` starts a translation: it takes the source's type, gets its own key, is placed by the layout (`<slug>-<lang>` beside the source without one), copies the source body (and the chapters and files of a bundle), and records `lang`, `rel.translation_of` and `source_rev`. It starts as `draft` where the type has that status. The tag in the name is lower case (`setup-pt-br`); `lang` keeps the BCP 47 form (`pt-BR`). A source that is itself a translation is refused with the original's id.

## Numbers

| rule | checks that |
| --- | --- |
| **N1** | counts in spec:count markers are current |

## Hidden characters

| rule | checks that |
| --- | --- |
| **H1** | no invisible characters in documents, declared agent assets, or well-known agent files |

Well-known agent files are checked even when they are not declared: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.agents/skills/*/SKILL.md`, `.claude/skills/*/SKILL.md`, `.claude/agents/*.md`, `.claude/commands/*.md`, and `.cursor/rules/*.mdc`. Joiners used inside emoji (U+200C, U+200D) are allowed. Output never prints the characters themselves: messages, fixes, previews, and editor quick fixes show them as `\u{XXXX}`, and in an editor the warning covers just the one character. `spec fix` shows each changed line before and after.

A4 (machine-local paths) checks the same files as H1: declared agent assets and the well-known agent files, each once.

Plugin rules are named `x.<plugin>.<id>` and are explained the same way.


---

Source: https://specfold.build/reference/config/

# Configuration

> [!TIP]
> `spec init` writes a starter `spec.toml`. `spec explain config` prints this list from the CLI
> itself.

## Layout and owners

| table | controls |
| --- | --- |
| `[spec]` | format version and the document directory name (`.spec`) |
| `[owners]` | the root owner, owner patterns, manifests and retired directories |
| `[public]` | published paths that hold no documents, and where their documents go |
| `[local]` | the git-ignored directory for drafts and private notes |
| `[external.<name>]` | directories outside the repository whose citations are checked |
| `[remotes.<name>]` | other repositories on disk whose documents are named `<name>:<id>`, read-only |

## Documents

| table | controls |
| --- | --- |
| `[types.<name>]` | override, disable or add a type: key, statuses, fields, transitions, required sections |
| `[forbid]` | retired layouts and identifiers (rule Z1) |
| `[aliases]` | the frozen alias table written by `spec import` |
| `[files]` | the attachment size limit and the store for larger files |
| `[[assets]]` | agent skills, rules, subagents and instruction files |

## Checks

| table | controls |
| --- | --- |
| `[check]` | baseline, strict paths, rule severity, `extra_keys`, `count_paths` |
| `[[guards]]` | named checks over files and commit messages (rule U1) |
| `[[plugins]]` | external programs speaking `specfold.plugin.v1` |
| `[translations]` | translations paired by place: `layout`, `languages`, `source_lang`, `strict` (rule R2) |
| `[audit]` | thresholds for stale, stalled and draft documents |
| `[verify]` | deadline, parallel jobs and shell for `spec verify` |
| `[cites]` | files outside documents whose citations rule L6 checks |

## Example

```toml
[owners]
root = "root"

[[owners.kinds]]
pattern = "services/*"
id = "{1}"
manifest = false

[check]
extra_keys = ["team", "review_*"]
count_paths = ["README.md", "docs/**/*.md"]

[translations]
layout = "suffix"   # guide:shop/setup-ko translates guide:shop/setup
languages = ["ko", "ja"]

[remotes.org]
path = "../shared-decisions"   # [[org:adr:root/20261030000000]] names a document there
```


---

Source: https://specfold.build/faq/

# FAQ

## What is specfold?

A command-line tool, `spec`, that keeps design, plan and maintenance documents in your
repository and checks their links and metadata.

## Does it need a server or network access?

No. `spec` is a single offline binary. Stores and plugins are external commands you configure.

## How do AI agents use it?

They run `spec` with `--json` to find the documents that govern a file, edit sections, and run
`spec check` before committing. See [Using with AI agents](guides/agents.md).

## Can I keep my current docs folder?

Yes. `spec import` moves an existing layout through a map, and old paths keep resolving. See
[Importing an existing layout](guides/import.md).

## Where do private notes go?

Into the git-ignored `[local]` directory, created with `spec new --local`. Rule **V2** stops
committed documents from citing them.

## What is the license?

MIT or Apache-2.0, at your option.


---

Source: https://specfold.build/changelog/

# Changelog

> [!TIP]
> Release notes are on [GitHub releases](https://github.com/modootoday/specfold/releases). Each
> release also ships to crates.io and npm.

## How changes are recorded

In a project that uses specfold, one user-facing change can be a `change` document, written with
`spec new change` when the work lands, so the note and its reason stay next to the code.

## Releases

| version | notes |
| --- | --- |
| 0.3.0 | [v0.3.0 on GitHub](https://github.com/modootoday/specfold/releases/tag/v0.3.0) |
| 0.2.6 | [v0.2.6 on GitHub](https://github.com/modootoday/specfold/releases/tag/v0.2.6) |