Set up or convert a repo

Two starting points: an empty repo, or a codebase with years of docs that never knew the shape. We take you from either one to a conformant Specline repo. Each path runs two ways — hand it to an agent (recommended), or do it yourself.

What you need first

• Install the specline command (Node 22.18+).
• For the agent path: register the MCP server and drop the CLAUDE.md brief into the repo.

Run specline init . --yes to create the starting structure, or add --check to preview without writing. Existing authored files are preserved. There's no tier to choose — it's one system throughout, and Part 3 (unattended builds) is a separate opt-in switch (see below).

Start a new repo

Let the agent scaffold it

With the brief in place, open an agent in the repo and say:

Set this repo up for Specline.

It scaffolds the structure (the pin, an architecture.md) and is ready for your first "shape a feature".

Build it by hand

There isn't much to it. The minimal valid setup is four things:

specline.yml                       # the canon pin — Specline reads it here
docs/
  architecture.md                  # a few lines: what this system is, read first
  drafts/                         # being-shaped specs; not a commitment
  specs/                          # one folder per approved-for-build spec; the folder name is its slug

One file carries the settings. specline.yml at the repo root is where Specline reads your canon pin and thresholds — nothing else:

canon: 3.1
unattended: false   # experimental — Part 3. default false
deciders: [your-name]

docs/conventions/doc-architecture.md is now optional prose/rationale — the machine-readable pins and thresholds live in specline.yml.

Then validate (see Verify), and shape your first feature into docs/drafts/ranch-mgmt/ — the folder name is the slug, which is the spec's identity. Moving it to docs/specs/ is the decider's go.

Convert an existing repo

Your shipped features never had a Specline spec, and you can't write one for the past. So don't. They aren't plans to approve or archive — they're facts about what's true now, and they go straight into knowledge/.

Let the agent convert with you

Convert our docs to Specline with me.

The agent reads your existing docs, assigns slugs, populates knowledge/<slug>/, and adds the conventions pin — checking itself with Specline as it goes.

Convert it by hand

1. Add specline.yml at the repo root with the canon pin (as above).
2. For each shipped feature's existing doc, create docs/knowledge/<slug>/ (the folder name is a descriptive slug, unique for each feature; graduation may pair matching knowledge/ and archive/ folders). Rewrite to present tense; keep intent, rules, and rationale; drop any status, open-questions, or to-do content (those are lifecycle artifacts Specline rejects in knowledge/).
3. Leave archive/ empty — it fills as new features go forward through the loop. Backfill a contract only for a feature whose original spec still carries value.

Verify

specline check .

Zero error findings (exit 0) means no blocking integrity findings for the supplied changed paths; it does not establish semantic correctness. Warnings don't block — they point at things worth a look, not things to stop on. From here every new feature runs the loop: shape → approve → build → graduate.