One shape for
every feature
you design.

The structure, made real

You write a plan, hand it to a model, it more or less follows it. The next feature has a different shape and different gaps. Nothing is wrong, but nothing is consistent — and inconsistency is where things get missed.

Specline fixes the shape. Every feature becomes the same kind of folder, with the same sections, and a checker (doctor) that tells you when a plan doesn't fit. A convention everyone agrees to but nothing enforces is just a suggestion; Specline makes it something you can actually rely on.

A convention without a validator is a suggestion.

Four moves

A feature moves through four steps. You're only ever on the two ends — shaping the intent and approving the result. The middle runs itself.

Shape — you and an agent talk the feature through and write the spec; unknowns become logged questions with a default, so nothing blocks. Ratify — you read it in one sitting and approve. Build — the agent implements against the ratified spec. Graduate — on ship, the spec is archived and a short knowledge note records why the code is the way it is.

The same files, every time

That sameness is the benefit. Read one spec and you can read them all.

docs/specs/0007-trade-in-quote/
  spec.md            # the contract — what we're building and why
  relations.md       # how this feature connects to others
  status.md          # the build's memory (once you start building)
  open-questions.md  # decisions not yet made (optional)

spec.md always carries the same sections, in the same order:

---
id: 0007
slug: trade-in-quote
status: draft
decider: jonathan
---

# Trade-In Quote

## Intent        # what + why, and the appetite (how big?)
## Non-goals     # what this deliberately won't do
## Behavior      # numbered, observable statements
## Business rules # the must / must-not constraints
## Acceptance checks # how you know it's done
## Out of scope   # deferred for later

Why the number 0007? So features can reference each other by a name that never changes even if you rename or move them. It's bookkeeping — the agent assigns it; you can mostly ignore it.

One structured home for the whole product

Specline isn't just a folder for specs. It defines docs/ as the product's source of truth — one structured place holding everything that determines the product: its intent, its decisions, its strategy, what actually shipped, and the trail of what was promised.

"docs" usually means afterthought — written late, read never. Here it's the reverse: the primary, prescriptive record the product is built from, and the descriptive memory of what it became. Every directory earns its place.

docs/
  architecture.md     # system shape — read first
  conventions/        # standards, templates, the canon + tier pin
  decisions/          # repo-local ADRs — append-only (ADR > spec > knowledge)
  strategy/           # vision, roadmap, launch contracts — dated, archived
  technical/          # cross-cutting patterns — only when non-obvious
  specs/              # IN-FLIGHT — prescriptive, temporary
  knowledge/          # SHIPPED — descriptive, permanent
  archive/            # TERMINAL — contracts, read-only
  relations-index.yml # generated reverse-edge index

Some of these doctor enforces; the rest are conventions the canon defines and you maintain. Knowing which is which is the difference between a rule and a habit.

doctor validates the lifecycle-core — specs/, knowledge/, archive/, the pin, ids, links. decisions/, strategy/, and technical/ are defined by the canon but maintained by you: convention, not policed.

How a feature is documented

A feature's documentation changes posture as it moves through the loop — from a contract you're building toward, to a description of what you built.

In flight, it lives in docs/specs/NNNN-slug/: prescriptive — what we intend to build. Temporary by design.

When it ships, it graduates into two permanent homes at once:

The in-flight spec is then deleted — the contract survives only in archive/. A feature is never in specs/ and archive/ at once.

If a knowledge doc would lose an argument with the code, it shouldn't exist. If it records why the code is the way it is, it can't lose that argument.

That's the test for what belongs in knowledge/: keep intent, rules, and rationale; cut anything the code already says. Tense and posture are a judgment call at the gate — doctor only checks that knowledge/ carries no lifecycle files.

Migrating an existing repo

Already-shipped features never had a Specline spec, so there's no contract to archive. In practice you populate knowledge/NNNN-slug/ directly from your existing descriptive docs — they're usually already knowledge-shaped — assign an id, and let archive/ fill as features go forward. Backfill a minimal contract only where the original still carries value. doctor permits knowledge without an archived spec, so a migrated repo is conformant from day one.

Two gates, one machine

Specline draws one hard line: structure is checked by a machine; meaning is judged by you.

So you're only ever on the two ends. The middle runs itself.

Claims & failure modes

A claim without a failure mode is marketing.

Every promise Specline makes names the condition under which it breaks.

Start light

You do not adopt all of Specline at once. You pick a tier, and doctor enforces only the one you declare.

How you use it

When you're ready, you do almost nothing to brief the agent:

Drop the CLAUDE.md brief into your repo. Open a fresh agent chat and say, in your own words — "Let's shape a new feature: …" or "Migrate this plan into Specline with me: …". The agent pulls the methodology itself, asks you the shaping questions, and produces the spec folder, checking its own work with doctor as it goes. You read the result in one sitting and approve it.

You don't memorize the rules and you don't paste the canon. The agent learns the methodology from the tool; you bring the judgment.

The doctor

doctor is the deterministic validator. It reads only markdown, YAML, and folder structure — it never runs your code, never calls a model, never touches the network. One question, the same answer every time: is this repo structurally valid?

It checks things like:

It runs at your command, in CI, or as a tool the agent calls while it writes. What it never does is judge meaning — tense, sizing, whether the spec is right. That stays yours, at the two gates.

Same input, same output, every run.