Skip to content

Manage product specs with a coding agent

CLI onlyBeginner~15 min

You own what the product should do. Hadron stores each product rule as a spec — a short document with a permanent address, its citation. Most corpora number their specs (api:010:04); some name them by path instead (onboarding:mentor:screens:settings). Either way the citation is the handle that other people write into tickets, code, and commit messages to refer to the rule. Where this page says "number", read "citation" if your corpus uses paths.

The tooling that keeps a spec corpus correct is a command-line tool with numbering rules, lint checks, and editing conventions. You do not need to learn any of it. A coding agent — Claude Code, Codex, Cursor, or any agent that can run terminal commands — drives that tooling for you: you say what should change in plain language, the agent does the mechanics, and you check that the result says what you meant.

This page is the workflow for a spec owner working through a coding agent. If you drive the CLI yourself, see Read and cite product specs, Amend a spec, and Maintain product specs instead — this page is the plain-language layer over those three.

Before you start

  • A coding agent that can run terminal commands. Claude Code, Codex, Cursor, OpenCode, and their peers all qualify. A chat-only app connected to Hadron — Claude Desktop, for example — can read and discuss specs, but cannot drive the spec tooling this page relies on.
  • The hadron CLI, v0.17.0 or later, installed and signed in — Install the hadron CLI. Older versions can't create or supersede a spec named by path. You will never run it yourself; the agent uses it, because its hadron spec commands carry the numbering and consistency rules built in. This is a one-time step a technical colleague can do for you.
  • Write access to your organisation's specs memory, and its name — for example acme.com:specs. Ask whoever administers your Hadron organisation. The examples below use acme.com:specs; substitute yours.

How this works

You describe what you want; the agent runs the spec tooling — it searches the corpus, allocates numbers, keeps the required sections in place, and runs the consistency checks. It can teach itself the commands, so you never need to brief it on tooling.

Your job is the two calls only you can make:

  1. What the rule should say. The agent drafts; you are the author of record.
  2. Whether a change keeps the spec's promise — the amend-or-supersede decision below.

Start each session by naming the corpus once ("we're working in acme.com:specs"); after that, plain language is enough.

Find and read a rule

You don't need to know any numbers. Describe the behaviour:

In our specs memory acme.com:specs, find the rules about onboarding
reminders, and show me the one covering the 7-day check-in.

The agent searches the corpus by meaning and shows you candidates with their citations. When you already have a citation — from a ticket, a code comment, a colleague — use it directly:

Show me spec api:010:04 in plain terms: what does it promise, and which
parts does it mark as tunable?

Two things worth noticing in what comes back:

  • A spec normally has a one-paragraph summary (its abstract) and a Durable vs tunable section separating what the spec promises from values that may move. You'll use that split in a moment; if a spec lacks the section, that's worth fixing while you're there.
  • If the agent says the spec is superseded or withdrawn, it no longer governs, though its citation still resolves on purpose. A superseded spec points to its replacement: ask the agent to follow it. A withdrawn spec has no replacement — the mechanism it described is gone — so the answer is that nothing governs there now, unless its own text says what does. A search can surface a retired spec before the current one.

Change a rule

The one decision that is yours: amend or supersede

A citation is permanent. Someone has written api:010:04 into a ticket or a code comment, and that reference must keep meaning what it meant when they wrote it. So before any change, answer one question:

Does this change alter what the spec promises?

Your change is… Then say to the agent…
Clearer wording, a better example, a newly-found edge case, or a new value for something the spec itself marks tunable "Amend api:010:04: …"
A change to the promise itself — who the rule applies to, what is guaranteed, an option being removed "Supersede api:010:04 with a new spec that …"

Amending edits the spec in place under the same number. Superseding retires the number and mints a new one — the old citation keeps resolving and points readers to its replacement, so nobody who wrote it down is misled.

Not sure which side your change falls on? Ask the agent to show you the spec's Durable vs tunable section and say where your change lands. The agent can advise — but this call is product judgment, and it is yours.

Amend

In acme.com:specs, amend api:010:04: change the check-in window from
7 days to 14 days. Update the spec's summary to match. Show me the before
and after, wait for my OK before you save, then run the spec checks.

Asking for the summary and the checks is deliberate: the abstract is what search matches on, so a spec whose body says 14 days but whose summary still says 7 will keep answering questions wrongly. Asking for the before and after matters too: the tooling's own preview only says which parts would change, so the agent has to show you the text itself.

Before you approve, check that the new wording says what you meant and that nothing else changed. If anyone else might be editing the same spec, add "re-read it just before saving, and stop if it changed since your preview": the tooling doesn't warn about a change made in between, and saving replaces what's there. After saving, check that the checks came back clean. See Amend a spec for more on what to review.

Supersede

In acme.com:specs, supersede api:010:04. The check-in becomes an in-app
prompt instead of an email, and it now applies to all users, not only
those who skipped setup. Draft the replacement, show it to me, wait for
my OK before saving, and tell me the new citation.

You get a new citation; the old one stays behind as a signpost. In a numbered corpus the agent takes the next free number. If the spec is named by path, tell the agent the replacement's path too (for example onboarding:mentor:screens-v2); the tooling won't invent one. Put the new citation wherever you announced the change — the ticket, the release note, the team channel.

Never accept a renumbering. If the agent ever proposes changing an existing spec's number in place, say no — that is what supersede exists to avoid.

Create a new rule

In acme.com:specs, create a new spec under the onboarding reminders
feature: when a user completes setup, we send a congratulations message
within one hour. Draft it, show it to me, and wait for my OK
before saving.

The agent picks the next free number (numbers carry no meaning — they are allocated in order and never reused), or, in a corpus that names specs by path, proposes a path that follows the corpus's pattern. Either way it drafts the spec against a fixed rubric. Review the draft like a document, hardest on the two sections that are product judgment rather than mechanics:

  • Definition and Rule & examples — is this the rule you meant, and do the examples match how you'd explain it to the team?
  • Durable vs tunable — is the promise on the durable side, and are the knobs (windows, thresholds, copy) correctly marked tunable? This section is what makes the next amend-or-supersede decision easy.
  • What invalidates this spec — under what future change should someone retire this rule? If you can't answer, the rule may not be settled enough to write down yet.

When it reads right, tell the agent to save it, and note the citation.

Before you call it done

At the end of a session:

Run the spec checks on everything we touched today — including the check
for summaries that no longer match their spec — and tell me what, if
anything, needs fixing.

A clean result means the mechanical rules are satisfied: required sections are present, no two specs share a citation, and no spec's body has changed under a summary that was written for older content. The required-sections check covers numbered rules only, so if your corpus names its specs by path instead of by number, read those sections yourself. What no check can tell you is whether the words say what you meant — that part was your review, above.

Then share the citations you created or changed with whoever needs them; the citation is the handle, not a link.

If the agent gets stuck

  • It asks which memory to use. Name the corpus (acme.com:specs). Say it once at the start of each session.
  • It asks about modules, features, or how to number a spec. Those are questions about how your corpus is laid out. "Look at what already exists and follow the same pattern" resolves most of them; for the rest, loop in whoever set up the corpus.
  • It reports check failures it can't resolve. Ask it to explain each finding in plain terms and what it proposes. Most findings are mechanical (a missing section, a stale summary) and the agent can fix them; anything touching what a spec promises comes back to you.