SPEC.md

SPEC.md Core 0.4.2

Source code is one implementation of an idea.
SPEC.md is the transferable expression of the idea itself.

0. Purpose

SPEC.md Core is the minimal self-contained standard for creating and maintaining a conforming SPEC.md.

A SPEC.md captures implementation-independent behavior, rules, constraints, and design semantics that must survive across implementations.

A human or LLM should be able to implement the design from SPEC.md without the original codebase, hidden project history, or this Core document.

Use SPEC.md Optional only when extra rigor materially improves clarity, portability, implementation, or verification.

SPEC.md captures design decisions; it does not complete the design.

Do not turn assumptions, common practice, or likely future needs into requirements.

1. Specification Contract

A SPEC.md SHOULD begin with a short contract containing these rules:

• Uppercase MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY use BCP 14 (RFC 2119 + RFC 8174).
• Normative requirements define conformance.
• Examples, notes, rationale, history, and implementation guidance are informative unless explicitly marked normative.
• SPEC.md is authoritative for required behavior when implementation code or implementation documentation conflicts with it.
• A conforming implementation MAY use different languages, frameworks, databases, infrastructure, architecture, source organization, or visual design unless explicitly constrained.
• If an unspecified implementation choice cannot materially alter conformance, the implementer MAY choose an appropriate solution.
• If an omission or ambiguity could materially affect observable behavior, data semantics, security, privacy, accessibility, interoperability, safety, or another normative property, it MUST be surfaced rather than silently resolved.
• If two normative statements conflict, the conflict MUST be surfaced.
• Unresolved product/design decisions MUST be marked TBD or Open Issue, not guessed.

Use TBD or an Open Issue when the current design depends on an unresolved decision. Do not create Open Issues for decisions that are not yet relevant.

2. Core Structure

A conforming SPEC.md uses:

1. Overview and Scope
2. Context and Definitions
3. System Model
4. Requirements
5. Interfaces and External Contracts
6. Constraints and Non-Goals
7. Verification and Acceptance
8. Notes and Rationale Empty subsections MAY be omitted. Communicate the required information with the smallest useful amount of text.

3. Overview and Scope

Define, as applicable:

• purpose;
• users/actors;
• goals;
• design/system boundary;
• major in-scope capabilities;
• major out-of-scope areas. Answer: What is being specified, for whom, and where does responsibility begin and end?

4. Context and Definitions

Define only terms whose meaning matters for correct implementation. Use one canonical term per concept in normative text. Prefer standard representations where ambiguity could arise:

• dates: ISO 8601;
• named time zones: IANA identifiers;
• currencies: ISO 4217;
• languages: BCP 47;
• decimals: . separator, no grouping separator;
• text: UTF-8. null, absent, empty string, empty collection, zero, and false are distinct unless explicitly stated otherwise.

5. System Model

Describe behaviorally significant structure and behavior. As applicable, include:

• actors;
• entities/concepts;
• relationships and cardinalities;
• states and transitions;
• lifecycle rules;
• invariants;
• behavioral flows. Prefer logical behavior over physical implementation. Specify behavioral consequences, not database or framework mechanisms.

6. Requirements

Requirements SHOULD be:

• atomic;
• unambiguous;
• implementation-independent;
• feasible;
• verifiable;
• internally consistent. State defaults explicitly when omission could create materially different behavior. State deliberate prohibitions explicitly. Stable semantic IDs are recommended once requirements exist, e.g. FUN-001, DATA-001, AUTH-001, SEC-001, INT-001. IDs SHOULD remain stable when requirements move. Retired IDs SHOULD NOT be reused. Section numbers express location; requirement IDs express identity.

7. Normative Consistency

A specification MUST be internally consistent. Requirements, invariants, models, contracts, and acceptance criteria MUST NOT prescribe incompatible behavior. References to requirements, flows, states, entities, or contracts MUST be accurate. Informative material SHOULD remain consistent with normative text. Distinguish:

• Implementation freedom — unspecified choice cannot materially alter conformance → MAY choose.
• Material ambiguity — multiple plausible choices could materially alter conformance → MUST surface.
• Normative conflict — two normative statements cannot both be satisfied → MUST surface.

8. Interfaces and External Contracts

For external systems, specify enough for independent interoperability:

• purpose and role;
• data authority;
• authentication/identity expectations;
• supported and prohibited operations;
• relevant data mapping;
• synchronization/consistency behavior;
• failure behavior;
• security/privacy expectations;
• version compatibility. Do not infer product scope from every capability exposed by an external API. If another document is required for conformance, SPEC.md MUST reference it directly and identify it as normative.

9. Constraints and Non-Goals

A non-goal says what the spec does not require. It does not forbid an implementation from doing more unless that is explicitly required. State important constraints and intentional exclusions explicitly. A deliberate non-feature belongs here rather than being left to inference. Avoid implementation constraints unless the implementation choice itself is part of the required design.

10. Verification and Acceptance

Important requirements SHOULD have a clear way to verify them. When requirement IDs are used, verification SHOULD reference the IDs it checks. Verification MAY use Test, Analysis, Inspection, or Demonstration. Given / When / Then MAY be used for readable acceptance criteria and need not be executable Gherkin. When multiple requirements jointly determine an observable outcome, verification SHOULD test the combined behavior, not only each requirement in isolation.

11. Notes and Rationale

This section is informative by default and MAY contain rationale, history, alternatives, limitations, future considerations, or implementation guidance. Do not hide requirements inside rationale.

12. Versioning

Use MAJOR.MINOR.PATCH.

• MAJOR — a previously conforming implementation may become non-conforming.
• MINOR — additive behavior preserving previous conformance.
• PATCH — no normative behavioral difference. PATCH test: Could two correct implementations based on the old and new PATCH legitimately behave differently because of the change? If yes, it is not PATCH. The Core version and project spec_version are independent.

13. Living Specification

SPEC.md MAY begin nearly empty and grow with the design. If missing, create frontmatter, a Specification Contract, and the eight Core sections. Whenever behavior is implemented, changed, or decided, update SPEC.md in the same change. Do not defer behavior documentation until the end. If material behavior is genuinely undecided:

1. mark it TBD / Open Issue;
2. surface it;
3. do not invent behavior merely to unblock implementation. A code-only refactor that does not alter specified behavior does not require a spec-version bump.

14. Modular Specification Sets

A small design SHOULD remain one file when practical. A larger design MAY use a root SPEC.md plus directly referenced normative modules. The root remains the canonical entry point, MUST identify every normative module, and owns the set version unless stated otherwise. A module MAY refine a rule within its scope but MUST NOT silently contradict a global requirement. Any normative module change participates in the root spec_version bump.

15. Self-Describing Test

Give SPEC.md to a competent unfamiliar human or LLM with only:

Implement the system/design defined in SPEC.md. They should proceed without asking how the original implementation works. If not, the specification is incomplete, ambiguous, or too implementation-dependent.

16. Human-Only Comments

SPEC.md MAY contain human-only comments.

Use:

<!-- SPECMD-HUMAN-ONLY
Human drafting or review note.
SPECMD-END-HUMAN-ONLY -->

Human-only comments MUST NOT influence implementation or conformance or contain required implementation or verification information. Tooling SHOULD remove them before supplying SPEC.md to an LLM.

17. Optional Extensions

Use SPEC.md Optional only when useful. Possible extensions include EARS, ERDs/diagrams, advanced modularization, integration detail, monitoring/audit/operations, DESIGN.md, TASKS.md, TRACE.md, implementation guidance, and tooling.

Use an optional feature when it reduces ambiguity, improves portability, or makes the design easier to implement or verify. Omit it when it adds ceremony without improving the design.

18. Core Quality Test

A good SPEC.md is:

• Authoritative — required behavior has one source of truth.
• Unambiguous — materially different interpretations are surfaced.
• Portable — the design survives a different implementation.
• Self-describing — no hidden interpretation guide is required.
• Consistent — requirements compose into one coherent design.
• Verifiable — important behavior can be demonstrated objectively.
• Lean — unnecessary ceremony is omitted.

19. Minimal Frontmatter

---
specmd: "0.4.2"
spec_version: "0.1.0"
status: draft
name: "<design name>"
last_updated: "YYYY-MM-DD"
---

Add metadata only when it materially helps.

This site is open source. Improve this page.