Read and cite product specs¶
A spec corpus is a Hadron memory run like a legal code: each spec's loc is its citation number, and every colon level is a real parent/child node. This guide is for reading one — you want the rule that governs a behaviour, and a stable number to cite it by.
If you write or curate specs, see Maintain product specs instead. And if you'd rather not drive the CLI at all, a coding agent can do it for you — see Manage product specs with a coding agent.
Point the CLI at a corpus¶
Every spec subcommand takes -m/--memory, which accepts a memory PK, an
hrn:/urn: URN, a bare org:memory, or the memory's name. Set it once
and drop the flag:
That default is stored separately from your active memory, so switching the
memory you're working in doesn't change your spec corpus. Pass "" to clear
it. The examples below omit -m and assume you've done this.
Read a citation¶
A citation is self-describing. If the second segment is letters, the corpus is product-rooted; if it's digits, the corpus is flat:
flat <module>:<feature>:<rule>[:<flow>] api:010:02
product-rooted <product>:<module>:<feature>:<rule>[:<flow>] srv:api:010:02
- product — a shippable artifact (
srv,cli,por). Three lowercase letters, frozen once created. - module — a top-level division of it (a service, a command group). Three lowercase letters, also frozen.
- feature — three digits, numbered in tens (
010,020, …). - rule — two digits. This is usually the thing you cite.
- flow — two digits; a pull-on-demand sub-part of a rule.
Numbers are never recycled and never renumbered, so a citation you write down today resolves to the same rule indefinitely. To see which scheme a corpus uses and what's in it:
Spec scheme — acme.com:specs
scheme: product (declared)
products: srv
modules: srv:api, srv:cha
counts: 1 products, 2 modules, 12 features, 40 rules, 8 flows, 5 contracts
contracts: product <p>:gen · module <m>:000 · feature <m>:<f>:00
Find the spec you need¶
Citations are opaque, so discovery rides on each spec's abstract, which the memory's vector index embeds. Search by intent rather than guessing a number:
CITATION NAME
srv:api:010:04 srv:api:010:04 — W4 — 7-day check-in
srv:api:010:02 srv:api:010:02 — W2 — welcome nudge
spec find is semantic by default (hybrid keyword + vector) and returns 15
results unless you pass --limit. On a corpus with no vector index it falls
back to keyword search and says so.
For an exact fragment — most often a citation — pass --match-exactly,
which switches to literal regex matching over name/loc/description/tags.
Plain keyword search is full-text ranked and stemmed rather than substring,
so it won't reliably match a bare number:
Search the prose, not the metadata¶
spec find ranks over name, loc, description, and tags. When you need to
know where a token actually appears in the body — an identifier, a tool
name, a TODO — use spec grep, which reads every spec's full text and prints
each hit as citation:line: text:
It's exhaustive rather than ranked, literal unless you pass --regex, and
-i folds case. Scope it with --prefix, or restrict to one field with
--field content|abstract.
Read the spec¶
You get the abstract, the node's edges, the markdown body, and a one-line lint summary. Two narrower forms are useful:
--abstract-onlyprints metadata and abstract without the body — the right size for scanning, or for stuffing many specs into an agent's context.--body-onlyprints just the raw markdown of a single spec, with no metadata.
To pull a whole branch — one feature, one module, or an entire product — use
--prefix instead of a citation:
hadron spec get --prefix srv:api:010 # a feature and its rules
hadron spec get --prefix srv:cha --abstract-only # a module, scannable
Every spec under the prefix is fetched by default; --limit (with optional
--offset) fetches a single explicit page instead.
To just see what exists without reading bodies:
Check what else governs the rule¶
A rule is rarely the whole story. Each tier reserves a general-provisions contract that its siblings inherit, so provisions shared across a whole tier are stated once rather than repeated:
| A spec at this tier | inherits | which holds |
|---|---|---|
a rule (srv:api:010:04) |
its feature's :00 (srv:api:010:00) |
provisions common to every rule of the feature |
a feature (srv:api:010) |
its module's :000 (srv:api:000) |
provisions common to every feature of the module |
a module (srv:api) |
its product's :gen (srv:gen) |
provisions common to every module of the product |
The inheritance is explicit in the graph, so spec get shows it as an edge:
Edges:
→ srv:api:010:00 inherits the shared contract (general provisions)
→ srv:api:010 W4 — 7-day check-in
Read that edge as "governed by this tier's general provisions" — not as "is another instance of the same kind of thing." When a rule seems to leave something undefined, the contract one level up is where to look next. A sibling overrides a provision only by saying so explicitly.
Spot a retired spec¶
Specs are never renumbered or deleted. When one is replaced it is
superseded: it keeps its citation, gains the tag superseded, and gets a
superseded-by edge pointing at its replacement. So an old citation in a
commit message or a ticket still resolves — it just tells you where to go
next:
Check the tag before you rely on a spec you found by citation rather than by search.
Cite it¶
Cite the bare citation — srv:api:010:04 — not a URL or a node ID. It is the
permanent handle, it survives edits and relocations, and anyone with access
to the corpus can resolve it with hadron spec get. The full node URN
(hrn:node:acme.com:specs:srv:api:010:04) is what the generic node and edge
commands take, if you need to reach past hadron spec.
Related¶
- Maintain product specs — the write side: scaffold, lint, split, and supersede.
- hadron CLI reference → Product specs — the full command surface, numbering policy, and semantics.
- Use Obsidian to view/edit memory — browse a synced corpus as a vault, with citation-numbered nodes made readable.