Set up or convert a repo

From zero to a Specline repo — whether you're starting fresh or bringing an existing codebase's docs into the structure. Each path works two ways: let an agent do it (recommended), or do it by hand.

Before you start

• 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).

Set up a new repo

The agent way — recommended

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, the id counter, an architecture.md) and is ready for your first "shape a feature".

By hand

The minimal valid setup is small:

docs/
  architecture.md                  # a few lines: what this system is, read first
  conventions/
    doc-architecture.md            # the canon + tier pin — doctor reads tier here
  specs/
    .id-counter                    # a bare integer, e.g. 0000

conventions/doc-architecture.md is the one file doctor reads to find your tier:

# Doc architecture — pin & deciders

| Field | Value |
|---|---|
| Canon | Specline 2.3.0-draft |
| Tier  | **1 — the loop.** |
| Decider | your-name |

Then validate (see Verify), and shape your first feature into docs/specs/0001-slug/.

Convert an existing repo

Your already-shipped features never had a Specline spec, so there's nothing to ratify or archive — they go straight into knowledge/ as descriptions of what's true now.

The agent way — recommended

Convert our docs to Specline with me.

The agent reads your existing docs, assigns ids, populates knowledge/NNNN-slug/, sets .id-counter, and adds the conventions pin — checking itself with doctor as it goes.

By hand

1. Add docs/conventions/doc-architecture.md with the canon + tier pin (as above).
2. For each shipped feature's existing doc, create docs/knowledge/NNNN-slug/ (sequential ids from 0001). Rewrite to present tense; keep intent, rules, and rationale; drop any status, open-questions, or to-do content (those are lifecycle artifacts doctor rejects in knowledge/).
3. Set docs/specs/.id-counter to the highest id you assigned.
4. 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 doctor .

Zero error findings (exit 0) means the structure is valid. Warnings are fine — they flag things to look at, not things to block on. From here, every new feature flows through the loop: shape → ratify → build → graduate.