open standard · one markdown file

give your agents
the briefing they need.

a single markdown file that tells every developer and AI agent how your codebase is built, what is decided, and what to work on next.

get the template see an example

curl -O https://raw.githubusercontent.com/mirageglobe/spec-md/main/template/SPEC.md

SPEC.md

# SPEC - my-project

## architecture
rest api (go) → postgres → s3 for assets.

## roadmap
- [~] `[api]` rate limiting  [hard]
- [ ] `[cli]` export command  [medium]
- [x] `[api]` basic crud endpoints  [easy]

## decisions
- **jwt over sessions**: stateless;
  scales without a shared cache.

## complexity score
| dimension | score | notes          |
| :-------- | :---- | :------------- |
| overall   | 3 / 5 | async job queue |
| storage   | 4 / 5 | custom migrations |

the problem

AI agents are powerful, but blind.

drop one into an unfamiliar codebase and it will guess at architecture, re-litigate settled decisions, and pick up tasks it cannot handle, because nothing told it not to.

no architecture context →wrong abstractions

no decision log →past choices relitigated

no roadmap tags →wrong tasks picked up

no complexity score →too light or too heavy a touch

the solution

four required sections. zero tooling.

SPEC.md lives in the repo root, versioned with the code, so it never drifts. think agents.md for agent behaviour, but for architecture.

## architecture

architecture

system design, components, boundaries

## roadmap

roadmap

open tasks scoped by component and difficulty

## decisions

decisions

what was chosen and why; stops re-litigation

## complexity score

complexity score

how carefully to tread, per layer

add more when the project needs them:

overviewtechnology stackprinciplesconstraintsnon-goalsfile structurebuild & runmilestonesopen questionsrisksreleasingkey bindings

built for agents

structure an agent can act on.

scope

[api][cli][ui]

component tags tell an agent exactly which subsystem a task belongs to. no guessing, no sprawl.

select

[easy][medium][hard]

difficulty tags let agents self-select suitable tasks without human triage.

trust

the decisions section is a settled record. agents read it and move on instead of proposing alternatives.

calibrate

a 4/5 storage layer gets different care than a 1/5 config file. the score says how careful to be before touching anything.

get started in 30 seconds

drop it in your repo root.

fill in each section, then point your agents at it.