Skip to content

Maintain product specs

CLI onlyAdvanced~20 min

Add a new product rule to your spec corpus, share provisions across a group of rules, or replace a rule — without ever breaking a citation someone has written down. Writing specs needs an agent that can run commands — a coding agent such as Claude Code, Codex or Cursor with the hadron CLI (v0.17.0 or later) — or you at a terminal.

A chat-only app connected to Hadron can read specs and draft with you, but can't save through the spec tooling. If you only need to find and read a spec, see Read and cite product specs.

Ask your agent

Most maintenance is a request to a coding agent that has the hadron CLI — you describe the rule and where it belongs, the agent drafts it and previews the result, and you approve before anything is saved:

In acme.com:specs, add a new rule under feature api:010 (onboarding
reminders): when a user completes setup, we send a congratulations message
within one hour. Draft it, tell me the citation it would get, and show it to
me, and wait for my OK before saving.

What comes back: the citation it would allocate (the next free number in that feature, for example api:010:04), the edges it would create — the link to its feature and to the feature's shared contract — and the draft itself. What to check before you approve:

  • The placement. A minted citation is permanent by policy, so make sure the rule sits in the feature you meant. If you named the feature loosely, a good agent says where it actually put it; confirm that.
  • What the agent had to guess. A short request leaves product decisions open, and a good draft lists them instead of deciding them. Answer them or strike them.
  • Any follow-up links. An agent may propose linking the new rule to related specs. Those links can only be created after the rule is saved, so they aren't in the preview; approve them separately.

Manage product specs with a coding agent is the full plain-language workflow, including amending and superseding. The rest of this page is what the agent does underneath, for maintainers who want the exact commands and rules.

What the tooling does

hadron spec is the opinionated layer over node/edge. It creates a spec at the loc you name, or allocates the next number in a numbered corpus. It scaffolds a starter body, wires the edges you ask for, and lets you renumber unminted drafts before publishing them. After minting, treat the citation as a permanent handle, which is publication practice. The full command surface is in the hadron CLI reference.

Prerequisites

  • The hadron CLI, v0.17.0 or later, installed and signed in — see Install the hadron CLI. Check with hadron auth status. Older CLIs enforce the numbering on every command, have no spec new <loc> or supersede --to, and still accept describe --declare.
  • Write access to a spec memory. The examples below use acme.com:specs, numbered <module>:<feature>:<rule>, and acme.com:platform-specs, numbered with a product in front (<product>:<module>:…).
  • Familiarity with how a citation reads — Read a citation covers the numbering convention and the level names used throughout this page.

Set your corpus once so you can drop -m from every command:

hadron spec use acme.com:specs

The examples below keep -m explicit, since a maintainer often works across more than one corpus.

See what a corpus holds

spec describe inventories a memory's specs: how many there are, their root segments, the deepest loc, and how many follow the numbering convention:

hadron spec describe -m acme.com:platform-specs

It also reports the derived corpus state and per-node approval/mint inventory. There is no creation-only draft setting to choose before your first spec. Any valid loc is a spec address, and one memory can hold numbered specs and specs at named paths side by side.

Earlier CLIs let a memory declare a flat or product-rooted "scheme" with spec describe --declare. That flag is retired: it is refused (exit 2) and writes nothing. A declaration still stored in a memory's data is shown by describe as retired, and nothing reads it.

Draft, review and mint

Prepare the rules before giving other people permanent citations. Ask your coding agent to reserve the intended addresses, write the drafts, show any renumbering plan, and return the mint dry-run report for review. Saving a node and minting it are separate steps: approve the wording and the publication separately. The commands below are examples for an authorized maintainer; they are not a record of edits or minting performed for this guide.

This workflow is verified against CLI v0.28.0. Every new node starts unminted in any memory, including one that already has minted nodes. Node.mintedAt records the node's mint state. The memory's derived state is DRAFT while no live node is minted, MINTED once any live node is; it is not a creation-time mode, and MINTED does not mean every node is minted.

  1. Reserve an address when another draft needs to link to an unwritten rule. spec reserve creates a server-marked placeholder, not a blank body you may infer to be a placeholder. A live node already there refuses the reservation (exit 5).
hadron spec reserve api:010:04 -m hrn:mem:acme.com:specs --name "Invite expiry"
  1. Write the rule and abstract with spec edit. Nonblank content fills the placeholder at the same address. An edit that leaves the body blank does not fill it. Use the guarded edit preview before saving and keep the abstract consistent with the body.

  2. Renumber drafts while they are unminted. Preview first:

hadron spec renumber api:010:04 api:010:05 -m hrn:mem:acme.com:specs --dry-run
hadron spec backlinks api:010:04 -m hrn:mem:acme.com:specs
hadron spec unresolved -m hrn:mem:acme.com:specs

Renumbering moves the spec and its subtree. If any moved node is minted, it refuses NODE_MINTED (exit 5). Unminted moves leave no old-address alias. Node-URN references inside the corpus are rewritten, but text-only citation mentions are not rewritten; they are reported for you to review. The move is atomic; subsequent reference edits are separate guarded writes, so a failed rewrite can leave a moved node with unfinished references (exit 1). Read the whole result.

  1. Review, fix and approve the current revisions using your corpus's review process. A CLI lint pass is not approval. After fixing a body, refresh its abstract and approval as needed; an older approved revision does not approve the new wording.

  2. Check without minting. Run:

hadron spec mint -m hrn:mem:acme.com:specs --dry-run --json

The report covers live, unminted nodes; previously minted nodes are not re-linted or re-approved by this call. It still scans the memory to resolve references. Dry run stamps nothing and exits 5 if blocked. Editing hashed content of a minted spec ends its approval today, without restoring draft rights. Re-approving and re-minting edited minted specs is decided but not yet built (server#1612); until then, this mint call does not cover them.

  1. Mint only after the report and publication are approved. A memory writer may run spec mint on the chosen memory. It checks again before confirmation; noninteractive application requires --yes. A successful call stamps eligible nodes individually. An in-flight writer can produce SPEC_CORPUS_BUSY (exit 5): retry after it finishes, rather than treating the earlier dry run as a guarantee. Encrypted memories currently refuse the mint scan.

Read the mint report

Finding Effect in the verified server source
Placeholder or unresolved reference (including a reference to a placeholder) Blocks minting.
Server structural lint: nodetype-info, tag-spec (spec tag or spec-family role), serialization-leak, duplicate-loc Blocks minting. Other CLI lint is not automatically a mint blocker.
Current revision not approved (NOT_APPROVED) or approval evidence tampered with (TAMPERED) Blocks minting. Fix and re-approve the current revision.
A node being minted cites an unminted node in another memory, by an edge or by a full hrn:node: or urn:node: URN in its name, description, abstract or content (CITES_UNMINTED) Blocks minting. A cited node in a memory you cannot read produces no finding, so the result is the same as for an address that does not exist. A bare org:memory:loc in text is not matched.
Stale abstract Reported; blocks only if the report's staleAbstractsBlock is true. It is false in the verified source.
Open question, grouped by the named decider or unassigned Reported, never a mint blocker. This is not a product decision or approval.

These synthetic CLI v0.28.0 fixture results illustrate the distinction; no real corpus was contacted or minted. Every fixture request used dryRun: true:

Synthetic report blocked in CLI JSON Exit
No findings false 0
One placeholder blocker true 5
Stale abstract, staleAbstractsBlock: false false 0
Stale abstract, staleAbstractsBlock: true true 5
Open question only false 0

A body bullet under an Open Questions heading ending Name decides. identifies the decider. Fenced code is ignored. The full dry-run report is the place to inspect findings; a real refusal may contain only a capped subset.

Replace text while drafting

spec replace previews counts, searched nodes and protected skips before a bulk edit. In CLI v0.28.0 a DRAFT corpus uses the spec-only bulk door with explicit selected nodes; a MINTED corpus uses the generic door, which skips governed specs. Do not read zero matches as proof that every spec was searched. The server's spec-only door accepts unminted targets in one memory; minted targets refuse. Use guarded individual edits when CLI bulk replacement skips the specs you need.

hadron spec replace old-term new-term -m hrn:mem:acme.com:specs --dry-run

On the draft door, apply must carry the exact preview fingerprint. A change to the selected rows, their state or match set makes it refuse SEARCH_REPLACE_PLAN_STALE with zero writes; take a fresh preview. A real CLI run previews again and uses that plan for its confirmed apply, rather than replaying an old terminal report. Protected and governed-kind skips remain explicit in the result. Unrevisioned drift must first be reconciled by a canonical node read before previewing again. Applied edits create normal revision history; a body rewrite can leave its abstract stale even if the abstract contains none of the replaced token.

Permanence is a policy, not a universal rejection

After minting, preserve citations and supersede published rules instead of reusing their addresses. The spec renumber door enforces its minted-node refusal, and the spec-only bulk door refuses minted targets. Other citation permanence enforcement is currently off: minting is not a promise that every server edit, move or removal path will reject a later change. See the citation lifecycle for the distinction between the publication policy and enabled guards.

Decide whether it belongs

Write a spec when a change introduces a product-level rule a product manager would need to read — a threshold, a time window, a categorical rule, or a lifecycle / eligibility / delivery contract. Pure implementation details (file paths, query shapes, caching) do not belong here.

Then decide where it goes. Follow the pattern the corpus already uses: in a numbered corpus, pick the module (e.g. api for messaging) — and, if the corpus numbers products, the product (e.g. srv) — then the feature the rule belongs to. A product or module code that automatic numbering allocates under must be exactly three lowercase letters; spec new refuses any other code. See Building a corpus one tier at a time for the way around that. See what already exists and which numbers are free:

hadron spec list -m acme.com:specs --prefix api
hadron spec register -m acme.com:specs

spec register prints the ledger for the numbered specs, derived from the live nodes, including the next free feature per module and next free rule per feature. Specs at any other loc are listed by name under outsideNumbering rather than left out.

Create a spec at the loc you choose

When the corpus isn't numbered, or the rule doesn't fit its numbering, name the loc yourself. If a coding agent drives the CLI for you, say what the spec is for, where it goes, and that you want to see it first:

In acme.com:specs, add a new spec at onboarding:mentor:screens:settings —
the mentor settings screen: it lets a mentor change their notification
preferences and pause new mentee requests. Draft it, show it to me, and
wait for my OK before saving.

The agent checks that the loc is free, drafts the abstract and the sections, and previews the spec with --dry-run — which writes nothing — then shows you the draft. It saves only after you approve. Read the draft for what the agent had to guess: a short request leaves product decisions open, and a good draft lists them rather than deciding them. (A plain-text preview doesn't show the abstract; ask to see it, or have the agent use --json.)

To do the same by hand, preview first — --dry-run writes nothing:

hadron spec new -m acme.com:specs onboarding:mentor:screens:settings \
  --title "Settings screen" --dry-run
would create onboarding:mentor:screens:settings — onboarding:mentor:screens:settings — Settings screen
  tags: [spec]

That creates exactly that spec. No parent is required, no contract is created, and no number is allocated. The one thing taken from the loc is its sort order: if the last segment is a number, it sets the spec's seq. It gets no edges unless you ask for one. --inherit <loc> adds an inheritance edge to a general-provisions contract, and spec link adds anything else afterward. A loc that already holds a node is refused (exit 2), never overwritten. The body is the same starter scaffold as below unless you supply your own with --content / --content-file; --abstract / --abstract-file set the abstract only.

A positional loc can't be combined with the numbering flags (--product, --module, --feature, --rule, --new-*, --contract). Those allocate a number instead, as the next sections show.

Create a typed spec with --role

From CLI v0.18.0, a positional spec new takes --role, a spec-family role such as spec.rule. A role is lower-case letter, digit and dash segments joined by dots, up to 64 characters, and the CLI checks that shape before it contacts the server; a valid subrole can still be refused by the memory's own role rules. An explicit --role (--role spec included) changes two defaults: the node is named with your plain --title, with no citation prefix, and only the tags you pass with --tag are written. Leave --role out and you get the earlier behaviour, a citation-prefixed name and the spec tag. The dry-run shows the role:

hadron spec new -m acme.com:specs onboarding:mentor:screens:settings \
  --title "Settings screen" --role spec.rule --dry-run
would create onboarding:mentor:screens:settings — Settings screen
  role: spec.rule
  tags: []

Add --tag spec if you still want the tag on a role-created spec. Choosing a role in a command does not give you any right to use it: whether the memory lets you write a governed spec role is decided by the server, not by the example. --json prints the same plan with a role field. For a default-role spec the field is absent.

Allocate the next number in an existing feature

In a numbered corpus, when the module and feature already exist, you're just allocating the next rule. Preview it first — --dry-run writes nothing:

hadron spec new -m acme.com:specs --module api --feature 010 \
  --title "W4 — 7-day check-in" --dry-run

The output shows the citation it would allocate (the next free rule under api:010 — here api:010:04), the node name and tags, and the table-of-contents and inheritance edges it would create. When it looks right, create it — supplying the abstract and body up front so the spec is complete:

hadron spec new -m acme.com:specs --module api --feature 010 \
  --title "W4 — 7-day check-in" \
  --abstract "Re-engage users who signed up but never finished setup, 7 days in." \
  --content-file w4.md

Without --abstract / --content-file, the spec is created from a scaffold — a placeholder abstract and a section skeleton (Definition, Rule & examples, Durable vs tunable, What invalidates this spec) — which you fill in afterward. spec lint does not require those sections: which sections a spec needs depends on its type, and the checks for that live in the corpus's own authoring framework (for the Hadron platform corpus, its review checks and review tasks), not in lint.

To change a spec that already exists, see Amend a spec: it covers the amend-vs-supersede decision and spec edit, which opens the body and abstract together because they are one logical unit.

Scaffold a whole branch

In a numbered corpus, a new rule usually needs a new feature, and sometimes a new module or product above it. --new-path creates the citation you name plus every missing ancestor in one call:

hadron spec new -m acme.com:platform-specs srv:api:010:01 \
  --new-path --title "Place new order"
✓ created srv:api:010:01 — srv:api:010:01 — Place new order
  edge: Place new order → srv:api:010
  edge: inherits the shared contract (general provisions) → srv:api:010:00

✓ created srv — srv — srv
✓ created srv:gen — srv:gen — srv general provisions
  edge: srv general provisions → srv
✓ created srv:api — srv:api — api
  edge: api → srv
  edge: inherits the shared contract (general provisions) → srv:gen
✓ created srv:api:000 — srv:api:000 — api general provisions
  edge: api general provisions → srv:api
✓ created srv:api:010 — srv:api:010 — 010
  edge: 010 → srv:api
  edge: inherits the shared contract (general provisions) → srv:api:000
✓ created srv:api:010:00 — srv:api:010:00 — 010 general provisions
  edge: 010 general provisions → srv:api:010

Your --title goes on the citation you named. The ancestors get placeholder titles taken from their own citation segment — srv:api is titled api, srv:api:010 is titled 010. They lint clean (the name leads with the citation), so nothing will remind you. Rename them afterward:

hadron node update hrn:node:acme.com:platform-specs:srv:api --name "srv:api — Ordering API"

--dry-run previews the whole chain the same way.

--new-path only builds numbered chains. Given a loc outside the numbering, it refuses (exit 2) and tells you to drop --new-path, because spec new <loc> creates that spec directly and has no ancestors to build.

Every root also gets its contract

Creating a root — with --new-path, or with --new-product / --new-module / --new-feature — also scaffolds that tier's general-provisions contract, which is why seven nodes appear above for one rule. Each root's children inherit that contract, and creating it up front is what lets the inheritance edges wire themselves:

Creating this root also creates
a product (srv) srv:gen
a module (srv:api) srv:api:000
a feature (srv:api:010) srv:api:010:00

Pass --no-contract to suppress it. You rarely want to — adding a contract to a tier later means back-wiring its existing siblings by hand.

Building a corpus one tier at a time

Pick the codes first. Automatic numbering needs a module code, and a product code if the corpus numbers products, each exactly three lowercase letters (srv, api). spec new refuses any other shape: spec new --product qa fails with an error saying the code must be 3 lowercase letters, and --module is checked the same way. A corpus that already uses such codes is not stuck, because it can create specs at explicit locs with spec new <loc>. That form takes any valid node loc and allocates no number, so hadron spec new qa:auth:login --title "Login" -m acme.com:platform-specs works with a two-letter code.

--new-path is the short form of a top-down build. The explicit form is still there when you want to title and populate each tier as you go:

M=acme.com:platform-specs

hadron spec new -m $M --new-product --product srv --title "Server"
hadron spec new -m $M --product srv --new-module --module api --title "Ordering API"
hadron spec new -m $M --product srv --module api --new-feature --title "Order placement"
hadron spec new -m $M --product srv --module api --feature 010 --title "Place new order"

Each level must exist before its children, and each of the first three calls also creates its contract, exactly as above. A live product or module address is already occupied: spec new refuses to create another there (exit 5). This is not the mint step; an unminted address can still be changed through the draft renumber workflow.

Everything else — list --prefix srv, lint, find, supersede — works the same when the numbering carries a product; the citations simply start with it (srv:api:010:01).

When scaffolding fails

Two different failures look similar and are worth telling apart. Both exit non-zero, but only one of them writes anything.

A missing parent tier is rejected up front (exit 4). Nothing is created:

hadron: module "srv:qqq" does not exist — create it first with --new-module

Create the parent tier and re-run — or use --new-path, which mints the missing ancestors for you.

An edge that can't be wired fails after the node is created (exit 1). A spec without its table-of-contents and inheritance edges is silently orphaned, so spec new refuses to report ✓ created and tells you what's missing instead:

hadron: created srv:api:010:01 but failed to wire 1 required edge(s) to
srv:api:010 — the node is orphaned; fix the target(s) and re-run, or wire
the edge(s) with `hadron edge add`

This one genuinely half-worked: the node exists. Fix the edge target and either re-run or wire the edge by hand — don't assume a clean slate.

Share provisions across siblings

When a provision is shared by a group of sibling specs — every rule of a feature, every feature of a module, or every module of a product — put it in a general-provisions contract instead of repeating it. A spec inherits the contract through an inheritance edge, and the edge is the whole mechanism: a spec with the edge is bound by the contract, and a spec without it is not.

In a numbered corpus the contract has a reserved number, and allocating a spec with spec new wires the edge to it for you. Roots created by spec new already have theirs; to add one to a tier that doesn't, use --contract at the deepest level you name:

Shared across Contract citation Create with
every rule of a feature api:010:00 spec new --module api --feature 010 --contract
every feature of a module api:000 spec new --module api --contract
every module of a product srv:gen spec new --product srv --contract

The numeric tiers use their reserved zero (00, 000); the alpha product tier uses the reserved code gen.

Outside the numbering there is no reserved place. A contract is an ordinary spec at a loc you choose, and each spec that shares its provisions inherits it through --inherit <loc> when you create it, or through spec link afterward.

Add a contract to a tier that already has siblings

Introducing a contract into a tier that already has siblings binds only the specs you connect to it. spec new --contract creates the contract, but the pre-existing siblings carry no edge to it, and nothing adds one for you or reports that it is missing. Back-wire each sibling that should be bound with spec link, using the inheritance label spec new would have written:

for f in api:010 api:020 api:030; do
  hadron spec link "$f" api:000 -m acme.com:specs \
    --label "inherits the shared contract (general provisions)"
done

--dry-run previews each link. The same back-wiring applies at every level — feature siblings to a module's :000, or modules to a product's :gen — not just the module level shown here.

Decide which siblings inherit

Whether a sibling inherits a contract is your decision, and the edge records it. It can feel forced when a group is heterogeneous — say a module whose contract states a scoring model, but one of its features is an A/B assignment mechanism rather than a scoring rule. Read the inheritance edge as "governed by these general provisions," not "is another instance of the same kind." If the outlier is genuinely bound by the shared provisions, give it the edge. If it isn't, leave the edge off rather than stretching the contract to fit.

Lint it

spec lint checks a spec's structure and stability: names, duplicate locs, whether the abstract still matches the body, and the abstract's length. It does not check a spec's content sections, because those depend on the spec's type. Pick the scope you want:

hadron spec lint api:010:04 -m acme.com:specs               # one spec
hadron spec lint --prefix api:010 -m acme.com:specs         # a feature and its rules
hadron spec lint --module api -m acme.com:specs             # a whole module
hadron spec lint --product srv -m acme.com:platform-specs   # a whole product
hadron spec lint --all -m acme.com:specs                    # the corpus

Errors exit with code 5: two specs at the same loc, or an abstract close to the server's length cap, for example. Warnings do not, unless you pass --strict; an abstract that may no longer match its body is one. Fix the findings and re-run until it is clean.

Lint does not check content sections. From CLI v0.18.0 a missing abstract, a missing "What invalidates this spec" statement, a missing data.version and a body that is still the unedited scaffold are no longer findings, at any loc. Names may be human-readable and need not start with the citation. A spec that carries the spec role but not the spec tag is not reported either: the role marks it as a spec, and spec list, get --prefix, grep and the other scans now find role-only specs as well as tagged ones. The sections a spec needs depend on its type, so check them with the corpus's own review checks and review tasks (for the Hadron platform corpus, the specs-engineer-system memory), and read the abstract and the "what invalidates" statement yourself.

Lint asks nothing about a spec's position: no parent, no inheritance edge, no contract, and no index of children is required, at any loc.

Restructure without breaking citations

Three commands cover the common reshaping moves, all of which preserve existing numbers:

  • spec extract splits a sub-rule out of a fat parent into its own citation under another feature, piping the moved chunk in as the new body and auto-wiring a cross-reference edge back. --strip-source also trims the chunk from the source, but only when it matches verbatim. It allocates in the numbering, so the source must be a numbered spec. For a spec at any other loc, create the new spec with spec new <loc> and trim the source with spec edit.
  • spec link cross-references one spec from another by bare citation, validating that both are specs in the same corpus. The convention is that the more specific spec cites the more general one.
  • spec replace does a citation-aware find/replace across every spec's body and abstract. It is word-boundary-aware by default, so renaming h-read-node never touches h-read-nodes. Preview with --dry-run, cap the blast radius with --max-specs N, and pass --yes non-interactively; changed specs are re-linted afterward.

Replace a spec without renumbering

Once minted, treat a citation as a permanent handle: do not change its number in place. To replace a published spec, supersede it: spec creates the replacement, links the old spec to the new one with a superseded-by edge, and tags the old spec superseded (its loc is untouched). Like the other destructive commands, it requires --yes when run non-interactively. Preview it with --dry-run.

For a numbered rule or flow, spec mints the next free number in the same feature (--feature moves the replacement to another existing feature):

hadron spec supersede api:010:04 -m acme.com:specs \
  --title "Some new spec" --copy-body --yes

For any other spec, name the replacement's loc with --to. It must be a free, valid loc, and nothing else is derived from it:

hadron spec supersede onboarding:mentor:screens -m acme.com:specs \
  --to onboarding:mentor:screens-v2 --title "Screens v2" --copy-body --yes

Without --to, a spec outside the numbering is refused (exit 2) with nothing written, because there is no number to allocate for it. --to works on a numbered spec too, when you'd rather choose the replacement's loc yourself.

--copy-body seeds the replacement from the old spec's content and abstract. Afterward, mark the old number retired in the register ledger — the command prints a reminder, and never edits the register itself.

Keep the corpus honest

Two checks are worth running in CI; both exit 5 on findings.

hadron spec lint --all -m acme.com:specs        # structure + stability rules
hadron spec check-tools -m acme.com:specs       # hadron_* tool references
hadron spec register --check -m acme.com:specs  # ledger drift vs live nodes

spec check-tools flags hadron_* tool names in spec prose that aren't real registered tools — the drift that lets stale shorthand rot unnoticed. spec register --check diffs the hand-written register ledger against the live nodes; the register is advisory and spec never writes it.