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+, no build).
• For the agent path: register the MCP server and drop the CLAUDE.md brief into the repo.

There's no specline init command yet — setup today is agent-driven or by hand (a generated init/migrate is the planned next tool).

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 + tier pin — Specline reads tier here
docs/
  architecture.md                  # a few lines: what this system is, read first
  specs/                          # one folder per in-flight spec; the folder name is its slug

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

canon: 2.7
tier: 1            # 1 — the loop
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/specs/ranch-mgmt/ — the folder name is the slug, which is the spec's identity.

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 sign 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 + tier pin (as above).
2. For each shipped feature's existing doc, create docs/knowledge/<slug>/ (the folder name is a descriptive slug, unique across specs/, knowledge/, and archive/). 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 the shape is right. 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 → sign → build → graduate.