The docs/ layout
Specline defines docs/ as the product's source of truth — the prescriptive
record it's built from and the descriptive memory of what it became. Each
directory has one job. Specline enforces the lifecycle core
(specs/, knowledge/, archive/); the rest are
conventions the canon defines and you maintain.
Knowing which directory a thing belongs in — and which it does not — is the difference between a rule and a habit:
architecture.md convention
What's here. The system's shape — core areas, and the orientation an agent reads first.
How to write it. One or two paragraphs. What this system is and any guidance before touching code.
What's not here. Not feature detail (that's a spec) and not history (that's knowledge/archive).
conventions/ convention
What's here. Doc and code standards, templates, the graduation prompt.
How to write it. Standards the whole repo follows. Stable, rarely changing.
What's not here. Not the repo's pins/thresholds — those live in specline.yml at the root, not here.
decisions/ convention
What's here. Repo-local ADRs — one per decision, append-only once accepted.
How to write it. A decision and its rationale. ADR > spec > knowledge in precedence.
What's not here. Not a plan (spec) and not a description of what exists (knowledge).
strategy/ convention
What's here. Vision, roadmap snapshots, launch contracts. Dated; archived, not deleted.
How to write it. Where the product is going. Point-in-time, so date it.
What's not here. Not how a feature works — that's knowledge.
technical/ convention
What's here. Cross-cutting implementation patterns that span features.
How to write it. Only when a pattern is non-obvious and reused across specs.
What's not here. Not per-feature mechanics (that's the code, or a spec's implementation.md).
specs/ Specline · enforced
What's here. IN-FLIGHT work. One folder per feature being shaped or built.
How to write it. Prescriptive — what we intend to build. Temporary by design.
What's not here. Not shipped reality. The moment it ships it graduates out of here.
knowledge/ Specline · enforced
What's here. SHIPPED reality. The living, present-tense description of what's true now.
How to write it. Intent, rules, rationale — what the code can't say. Cut anything the code already says.
What's not here. No lifecycle files (status.md, open-questions.md) — this isn't in-flight work.
archive/ Specline · enforced
What's here. TERMINAL contracts. The final spec of every shipped/killed feature, frozen.
How to write it. Nothing by hand — graduation writes it. Read-only, permanent.
What's not here. Never edited. It's the audit trail; editing it is a Specline error.
Two generated files round it out: relations-index.yml (reverse-edge index, regenerated by Specline — never hand-edited) and a README.md in each directory carrying this same four-part definition, so the structure explains itself in place.