spec-driven-docs 0.19.1

Spec-driven documentation: current specs, immutable decision records, and executable gates kept coherent for people and coding agents.
Documentation
# Instance distribution

An instance keeps its current specs, configurations, templates, and manifest in its own checkout. It runs the gates and the verifier from the installed `sdd` binary, which carries the whole payload. Canon provenance is consulted for installation and upgrades, never for routine work.

Ownership has three classes:

- Managed files are byte-for-byte projections. Verification fails on drift. Upgrades replace only an unchanged installed projection.
- Adopted files are seeded once and owned locally. The manifest records both the installed bytes and the upstream baseline they came from. As a result, an edit reports drift until it is reconciled, and upgrades preserve it.
- Integration blocks are delimited regions inside local files. Tools can replace only the marked block.

`sdd` generates two kinds of file in an instance: each managed file, such as `<root>/.markdownlint-cli2.jsonc` and every file of the landed skill packages `sdd-setup/` and `sdd-write-docs/` under `.claude/skills/` and `.agents/skills/`, and the record `.spec-driven-docs/manifest.json`. A generated file keeps the form that `sdd` writes, so the project's own checks that rewrite a file or judge its prose or form exclude both: the whitespace and end-of-file fixers, formatters such as dprint, spell checkers such as typos, editorconfig-checker, and Markdown linters. A check that only reads a file keeps it, such as a syntax parser, a secret scan, a link check, or a gate that `sdd` delivers. Exclude a file in the tool's own configuration where the tool has one, because a run outside pre-commit reads that configuration too. Exclude it in the hook's own `exclude:` where the tool has none. Never use the top-level `exclude:` of `.pre-commit-config.yaml`, because it also hides the file from the reading checks. Adopted files and the content outside an integration block belong to the project, so its checks judge them like any other file. Exclude only those two package folders under each root, never a whole skill root, so the project's own skills there stay under its checks. The root lint configuration that `sdd init` seeds ignores those two folders under each root. A root configuration that an earlier release seeded, or the project's own, needs those ignores added by hand, and an ignore of a whole skill root narrowed to them.

The only requirements are `git`, `prek`, and `sdd` on the PATH of everyone who runs the hooks, including CI. Install `sdd` with `cargo install spec-driven-docs`, with `cargo binstall spec-driven-docs`, or from a GitHub release's installers. The binary embeds the payload for its own version, so verification and upgrades run offline. Every command that reads or writes an instance first compares the version of the binary with the version the instance records. A command that writes refuses a mismatch, and a command that only reads warns where the binary is newer. Each names the command that fixes the mismatch: `sdd init`, `sdd upgrade`, or the sdd of the project's own environment.

## Stage the candidate

What lands is the version of `sdd` that is installed, so the operator chooses it with their own package manager. Before writing anything, render that candidate where you can read it.

```bash
sdd stage --target /path/to/your-project
sdd stage --target /path/to/your-project --json
```

The stage writes nothing into the target. It holds every destination the candidate would land under `artifacts/`, this version's own method, specs, templates and skills under `reference/`, and a receipt naming what it rendered. It survives the landing it informed, and only `sdd stage clean <path>` removes it.

`sdd init` lands a first instance and refuses a target that already documents itself under another convention. `sdd upgrade` moves a landed instance and refuses a target with no instance. Both name what serves the target instead, and both render the candidate again from the binary's own sources rather than reading a staged byte. [method/landing.md](../method/landing.md) owns the model behind all of them.

```bash
sdd init --target /path/to/your-project --profile codebase
sdd init --target /path/to/your-project --profile codebase --apply
```

Use `knowledge-base` to select `_docs/`. `codebase` selects `docs/`. A non-empty target with no instance defaults to a dry run, and `--apply` is what writes into it. Review the managed pre-commit block before applying it to a heavily commented configuration. The block is spliced into the top-level `repos:` sequence, so a configuration without that key is refused rather than rewritten.

## What refuses before the first write

A landing settles what it can refuse on before a byte moves. Every destination must resolve beneath the opened target, checked without following a link. Every whole file this tool would own must be one the record accounts for: a destination holding bytes nothing vouches for refuses the run and names it, because that file is the one somebody else wrote. One writer holds the target for the whole run.

A locally edited managed file is a conflict rather than a question. The stage carries the candidate's bytes to compare against, and the file is resolved before the landing runs. Adopted specs and content outside the markers are never overwritten.

The gates reach a repository by installation, not by remote reference. This repository publishes no `.pre-commit-hooks.yaml`, so it cannot be named as a `repo:` in someone else's configuration: most gates read the layout an instance has. If a repository that never adopted the framework wired those gates, the checks fail on its first commit. Run `sdd init` to become an instance, and the block arrives wired to the layout the profile selected.

## Skills

The binary embeds the agent skills, and the landing writes them into the instance. `sdd init` writes every file of each skill package under `.claude/skills/<name>/`, which Claude Code reads, and under `.agents/skills/<name>/`, which Codex reads. `sdd upgrade` moves them with the rest of the instance, and the project commits them. They are managed files, so `sdd verify` fails on an edited or a missing skill file.

The version lives in the record: `canon_version` in `.spec-driven-docs/manifest.json`. A skill file carries no version stamp, so each project reads the skill text of the sdd it pins.

A skill lands as a package: one directory holding `SKILL.md` and every shared artifact under `references/`. Each skill names its gates by a path relative to its own directory, which is what the Agent Skills format resolves a supporting file against. A package folder that the record does not attribute is never replaced: the landing refuses it and names it.

Before an instance exists, the binary serves each skill file to the agent:

```bash
sdd skill list
sdd skill show sdd-setup
sdd skill show sdd-setup --file references/pre-flight-gate.md
```

Earlier releases installed the skills under the home. A home copy shadows the instance copy, because an agent prefers a personal skill or shows both. `sdd doctor` names such a copy, and `sdd skill uninstall --apply` removes it. The uninstall removes a file only where its digest is the one the receipt of the earlier install records, and names every file it keeps with the reason, so a file you edited stays.

## Keep the pin fresh

```bash
sdd self-depend status --target /path/to/your-project --json
sdd self-depend add --target /path/to/your-project --manager mise --venue crates
sdd self-depend sync --target /path/to/your-project --apply
sdd self-depend clean --target /path/to/your-project --also scripts/bump.sh
```

Where the target pins `sdd` through a manager, a landing does not close until the operator has answered about the freshness wire. After the variables land, run `sdd self-depend status --target . --json` and hold `wired`, `envrc_check`, and `envrc_old_line`. Where `wired` is `null`, there is no pin to keep fresh. Where `envrc_old_line` is `true`, the `.envrc` still runs the retired line `sdd self-depend sync --apply || true`: move the pin with `sdd self-depend sync --apply`, then run `sdd self-depend clean --target . --apply`, which swaps that line for the check line. Where `wired` names a manager and `envrc_check` is `false`, decide whether the project lands the line `sdd self-depend check || true` in its `.envrc`: on each directory entry it warns on stderr when a newer release is out, it reads the network at most once every seven days, it writes no file but its cache, and it never moves the pin. The operator moves the pin with `sdd self-depend sync --apply`, which leaves a diff for the operator to review and commit. On yes, `sdd self-depend add --target . --manager <wired>` prints the line with its placement and seeds `.envrc` only where the target has none: run it with `--apply` where it names `.envrc` among its seeds, and where it seeds nothing, place the line in the `.envrc` you already have. Re-run the status verb until `envrc_check` reads `true`. On no, the landing is complete without the wire, and the answer goes into the task's close.

A project pins this tool through the manager it already runs, and `sdd self-depend` keeps that pin fresh. `status` reports offline, one entry per manager with the absent ones included, plus the shell-entry line, the version-check cache, the host probes, and any leftover; every state exits 0. `add` prints the fragments one manager and venue pair needs with their anchors and placements, edits no file the project owns, and seeds a manager file only where the project has none and only with `--apply`. `sync` moves the pin to the latest release through the wired manager in one transaction: a flake moves its tag and its lock together or not at all. `sync` is the operator's act: it reports every outcome, fails loudly, and leaves a diff for review. Where `DIRENV_IN_ENVRC` is set, in an `.envrc` evaluation or under `direnv exec`, it moves nothing, warns, and exits 1: run it from the loaded shell or with `nix develop -c sdd self-depend sync --apply`. `check`, the line `sdd self-depend check || true` in `.envrc`, reads a cache under `$XDG_CACHE_HOME/spec-driven-docs/`, refreshes it at most once every seven days or one hour after a failure, warns on stderr, writes no file but its cache, and exits 0. `CI` or `SDD_SELF_DEPEND_OFF` switches the check off, never an operator's sync. `clean` removes only what a predecessor mechanism left, swaps the retired sync line for the check line, removes the retired daily stamps, and names what it keeps.

## Read the corpus

```bash
sdd docs
sdd docs context budget
```

`sdd docs` prints one described index of everything the binary carries: the method chapters, the specifications, the templates, and the operator tasks whose answer is a help page. `sdd docs <topic>` resolves one entry by its id, an alias, or a unique prefix, and renders it. An ambiguous query names every candidate rather than guessing one. The managed documentation block a landing writes names this verb, so an agent that has never opened the canon reaches any chapter in two commands.

## Report

```bash
sdd status --target /path/to/your-project --json
```

The object declares the schema `sdd.status/3`, and its `paths` section is where every path the tool names comes from. `paths.user` carries the roots under the invoking user's home, each with the variable that moved it. `paths.active` is the landed instance, or `null` where there is none. `paths.candidates` carries one destination set per profile, and `paths.proposals` carries what the target offers for the docs scratch. Every entry states its source, so a recorded answer and a derived one never read alike. Read a path from here rather than writing it down: a skill, a runbook, or a chapter that spells one is a copy that drifts at the first rename.

## Land

```bash
sdd init --target /path/to/your-project --profile codebase --apply
sdd upgrade --target /path/to/your-project --dry-run
sdd upgrade --target /path/to/your-project
```

The landing replaces each destination in its own directory and writes the record last, so until the record lands the previous one still describes the target. It never touches `.git`. There is no rollback and no stored result: a run that stops names the destinations that hold candidate bytes, and running it again finishes the rest.

Two things prove it finished: the record matches the tree, and verification passes. Compare the result against the stage before removing it.

```bash
sdd verify --target /path/to/your-project
```

Verification is always offline: hashes, the managed block, the landed skills, local rule IDs, and the version alignment between the binary and the instance. Where the binary is newer than the instance, verification warns and names `sdd upgrade`, and keeps its own exit code, so the hooks keep working after a pin move.