Ask-Loft/loft

The Loft Specification Format and its reference implementation

Summary

The Loft Specification Format is a document model for writing product specifications inside a git repository, with no server. It comes with a Rust loft command-line tool that formats, validates, publishes, and reconciles the specification, and works with a loft-spec skill that teaching coding agents (Claude Code, Codex) how to write and edit the spec for you. The current public release is 2.0.0, and the format, CLI, and hashing algorithm are all specified in the repository's own spec/ tree.

What it is useful for

It is useful when a team wants the specification, the acceptance criteria, and the code to live together in git, with each criterion traceable to the tests that verify it. The design treats a coding agent as the writer and a human as the reviewer: the agent interviews you, proposes an outline, writes the nodes, and runs loft fmt and loft check until both pass; you read the result through a diff or loft render, then ask it to commit and publish. The format also imports from Loft v1 exports and OpenSpec main specs, supports merges between clones with a git merge driver, and pins published state in loft.lock.json for CI verification.

How engineers can use it

Install the CLI one of three documented ways:

npm install --save-dev @ask-loft/loft
# or
cargo install --locked loft-cli
# or
cargo install --path crates/loft-cli

Building from source requires Rust 1.97 or newer; the npm package ships prebuilt binaries for macOS, Linux, and Windows on x64 and arm64.

Then bootstrap a project:

cd my-product
loft init                       # creates spec/ and the loft-spec skill
loft merge-driver --install     # registers Loft as git's merge driver for spec/
git add .gitattributes .claude .agents && git commit -m "Add the Loft specification tools"

After that, ask your agent to use /loft-spec (Claude Code) or $loft-spec (Codex) to specify a feature. The agent will interview you, draft the spec, run the validators, and commit. When the draft reads right, run loft publish on main to allocate labels and write the lock, and add loft verify to CI to confirm the tree matches.

Documented limitations to be aware of: telemetry is on by default and sends one command event per run to askloft.ai (switch off with loft telemetry off or LOFT_TELEMETRY=off); two clones publishing apart can give one label to two nodes, which loft publish resolves by withdrawing colliding labels and rewriting citations; and if the loft binary is not on git's search path during a merge, the driver falls back to a plain text merge with conflict markers, so the install step matters.