specfold

One command line for a repository's design, planning and maintenance documents: rules, decisions, plans, research, evidence, audits, page specs, design boards, guides and runbooks.

• Documents live with the code they govern. Each owner (the repository root, an app, a package) keeps its documents in its own .spec/ directory. spec new --governs <path> works out which owner that is; you never pick a directory by hand.
• Definitions live in one place. Types, ids, frontmatter, statuses, relations and checks come from specfold and one spec.toml, not from conventions written in several READMEs.
• The graph is derived, never stored. References between documents, supersede chains and the code each document governs are computed on every run.
• Built for AI agents first. Every command is non-interactive, prints text or a stable --json schema, bounds its output, attaches a fix to every finding and ends with a suggested next command. The same commands are served as MCP tools by spec mcp.
• Language- and agent-neutral. Owners are found through any common package manifest; the CLI, JSON Schemas and MCP work with any agent that can run a command.

Install

Pick whichever fits your project. Each gives you two commands, specfold and its short alias spec.

With Rust installed:

cargo install specfold

In a JavaScript project, add it as a dev dependency so everyone on the team gets the same version from the lockfile:

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

Or download a ready-built binary for Linux, macOS or Windows from the GitHub releases.

Start

spec init --owner 'services/*={1}' --owner 'libs/*=lib.{1}:manifest' --write
spec new sot --governs services/shop/src/cart --title "Cart totals"
spec context services/shop/src/cart/total.rs     # what governs this code
spec check --staged                          # before committing
spec agents --for claude                     # lines for your agent's instructions
spec hook print --for pre-commit             # a hook for your hook manager

Documents

Ids are <type>:<owner>/<key>, computed from where a document lives. Files are <owner>/.spec/<type>/<key>-<slug>.<type>.md, or a directory with index.<type>.md when the document has chapters or attachments. Projects can disable, change or add types in spec.toml.

Statuses are draft, active, superseded, archived and rejected, and only move forward. Relations are written once, on the document that makes them: rel.governs (code paths), rel.supersedes, rel.implements, rel.evidence, rel.depends_on. Body references are [[<id>]] or [[<id>#<anchor>]].

Commands

spec help lists every command; spec help --json describes all of them with their arguments, examples and output schemas. spec explain documents every rule.

Writes are previews until --write (or plain for new and set, which accept --dry-run). Exit codes: 0 nothing to report, 1 findings or an ambiguous answer, 2 usage, 3 environment.

Attachments

Non-Markdown files belong to a document and are listed, with their SHA-256, in its files frontmatter by spec attach. Small files stay in the repository; larger ones go to a store configured in spec.toml: a directory, or a command you already trust (rclone, aws, gsutil, wrangler …). specfold contains no network code and never handles credentials.

Guards, plugins and audits

• Guards ([[guards]], spec guard) check any file and commit message in a range for denied terms, patterns, files, sizes and secret formats. Terms may come from a file outside the repository or an environment variable, and are masked in output.
• Plugins ([[plugins]]) are programs in any language that speak specfold.plugin.v1 JSON over stdin and stdout to add rules, importers, exporters, audits and event handlers. Only programs named in spec.toml run.
• Audits (spec audit) find what passes the rules yet needs attention: stale documents, orphans, owners without a source of truth, stalled plans, open items. --pack groups documents for a reviewer, and spec audit record stores a review as a sealed audit document.

Importing an existing layout

spec import --map import.toml reads files from any other layout through a map of patterns, types, owners, key rules, status mappings and redirect stubs; it prints a reviewable plan and, with --apply --write, moves everything and writes a frozen alias table so old ids and paths keep resolving until they are rewritten.

License

MIT or Apache-2.0, at your option.