ADR-0005: Adopt Spec-Driven Development

Status:  Accepted
Date:    2026-05-02
Owner:   @satya

Context

Treeper will be vibecoded across three runtimes by a small team using LLMs heavily. LLMs make typing cheap, which makes “what are we building?” disproportionately the rate-limiting step.

Without a forcing function, we get drift between intended and shipped behaviour, and we lose track of why anything is the way it is.

Decision

Adopt Spec-Driven Development. Every non-trivial change starts with a short markdown spec or ADR in specs/. The spec is reviewed and merged before implementation. Code is the implementation of a spec; if the two disagree, the spec wins by default.

The full method, lifecycle, and templates live in specs/README.md.

Alternatives considered

Option	Why not
Heavy PRD process (Notion)	Out-of-repo docs go stale; nobody reads them.
GitHub issues only	Issues describe work, not behaviour. No good template for AC.
No process	Tried. Drifts. Especially bad for AI-assisted coding.

Consequences

Positive

Future-us, contractors, and AI agents can read a spec in 5 minutes and know the intended behaviour.
Acceptance criteria become the test plan, not a separate document.
New contributors know exactly where to start.

Negative / risks

Small overhead for tiny changes (mitigated by allowing trivial PRs to skip the spec step).
Risk of writing specs that nobody reads — kept in check by the “no PR without a spec link for non-trivial work” rule.

Follow-ups

Add a PR template that asks for spec ID(s).
A linter / CI check for “PR title references 0NNN from specs/” once we’re not the only contributors.