SPEC
Source code is one implementation of an idea.
SPEC.md is the transferable expression of the idea itself.
SPEC.md is a Markdown format for describing a system or design independently of any one implementation. It captures the behavior, rules, constraints, relationships, and decisions that should survive across implementations. Because the design lives outside the codebase, you can move the same specification between coding agents, developers, languages, and stacks without asking each one to rediscover the design from source code.
Portable by design.
A SPEC.md separates the design from the implementation that happens to exist today.
Give the same specification to a different developer or coding agent and the implementation can change while the required design stays the same.
A developer or an agent should be able to create a conforming implementation without the original source code or hidden project history.
By making the design explicit and portable, SPEC.md reduces dependence on tribal knowledge: information that otherwise lives only in the heads of individual developers or within a particular team.
That makes SPEC.md useful when a project moves between coding agents, when a team changes technology, or when the same design needs to be implemented again somewhere else.
The same format can stay lightweight for a small one-off project or grow with a complex development effort. A simple project may need only a short SPEC.md; a larger system can add modules and companion documents without changing the basic contract.
The design stays explicit.
A specification does not need to be long. A few lines can already say what must happen, what remains open, and how the behavior can be checked.
For example, imagine an internal ticketing system. The design says that agents must sign in, users can create tickets through the web portal or email, and email-thread matching has not been decided yet:
## 4. Requirements
- AUTH-001: Agents MUST sign in before accessing
agent-facing features.
- INTAKE-001: Users MUST be able to create a ticket
through the web portal.
- INTAKE-002: Users MUST be able to create a ticket
by email.
## Open Issues
- How email replies are matched to existing tickets: TBD.
## 7. Verification and Acceptance
- AUTH-001 — An unauthenticated user cannot access
agent-facing features.TBD rather than being guessed.
Start with Core.
SPEC.md Core defines the minimum needed for a portable, self-describing, consistent, and independently implementable specification.
Core is the default entry point. Read the latest version online, or download the Markdown file and keep it with your project or agent instructions.
The reference example: Judo Club.
Judo Club is the canonical SPEC.md example. It shows how a complete but approachable design can be expressed without tying it to a particular framework or codebase.
It covers the club website's pages, multilingual behavior, schedule, gallery, contact handoff, logical model, constraints, and verification. The same SPEC.md could be implemented with very different technologies while preserving the same required behavior.
Looking for more implementable examples? Review the Portables.
One design, many builds.
The example is intentionally about something simple enough to understand quickly. The point is not the website technology. The point is that the design can travel independently of it.
The SPEC.md family.
Core is the default. The rest of the family adds depth only when the design needs it.
SPEC.md itself remains the portable behavioral contract. A small project may use only Core and a short SPEC.md. Larger projects can add Optional conventions, modules, and companion documents as needed. The full Standard provides the complete reference, while companion documents describe one implementation or its execution without changing the portable contract.
Core
What most projects and agents need to read. Small, portable, and implementation-independent.
Optional
Extra conventions when they reduce ambiguity or make a complex design easier to implement or verify.
DESIGN.md
Describes one concrete implementation: architecture, technology choices, data layout, internal components, and other decisions that do not belong in the portable SPEC.md contract.
TASKS.md
A practical execution plan derived from SPEC.md and, when present, DESIGN.md. It organizes the work to be done but does not create new product requirements.
TRACE.md
A traceability map showing how a requirement connects to design decisions, implementation, and verification. It helps answer: where was this requirement implemented, and how do we know it works?
Agent instructions
Files such as CLAUDE.md and AGENTS.md tell coding agents how to work with the project. They do not replace SPEC.md or redefine the design.
specmd: the CLI.
A companion command-line tool and MCP server for working with SPEC.md documents. SPEC.md itself never depends on it.
specmd-cli can
init, validate, inspect, render, and trace a SPEC.md, generate thin
adapters for Codex, Claude Code, Cursor, GitHub Copilot, Base44, and
Lovable, and expose the same operations to AI assistants over MCP as
specmd-mcp.
It goes beyond syntax checks: a deterministic Black-Box Contract inventory surfaces exactly what a design promises the outside world, and per-requirement verification coverage shows what's actually tested. An optional Cucumber connector is already specified.
Author & validate
specmd init, specmd validate: create a
minimal SPEC.md and check structural conformance, including Trace
Pair and version-alignment checks.
Inspect & trace
specmd inspect, specmd trace create/update:
a read-only quality report, and generating or reconciling a
TRACE.md.
Render & adapt
specmd render, specmd adapt <target>:
HTML rendering, and thin adapter generation for Codex, Claude Code,
Cursor, GitHub Copilot, Base44, and Lovable.
specmd-mcp
An MCP stdio server exposing the same operations as tools, so an AI assistant can validate, inspect, and trace a SPEC.md directly.
Blackbox test
specmd blackbox, specmd test: a
Black-Box Contract inventory (deterministic structural checks,
plus two semantic checks run via Host-Agent Mode when a calling
agent supplies reasoning input) and a per-requirement
verification-coverage report. An optional Cucumber connector is
already specified.
Install: not yet published to PyPI. Install from
source:
git clone https://github.com/SPECmd-app/specmd-cli && cd specmd-cli && pip install -e .
Current and previous version.
SPEC.md Core moves in small, documented steps. Only the current and the immediately previous main version are shown here.
0.4.3 (Current)
Clarifies how stable semantic IDs interact with traceability: an ID alone does not make an element normative, and TRACE coverage follows normative obligations, not every label in the document.
0.4.2 (Previous)
Sharpens the boundary between capturing a design and inventing one: SPEC.md captures design decisions, it does not complete the design.