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, numbered document — and the number (a citation, like api:010:04) is a permanent handle that other people write into tickets, code, and commit messages to refer to the rule.

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 installed and signed in — Install the hadron CLI. 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:

  • Every spec 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 the agent says the spec is superseded, the rule has been replaced. The old number still resolves on purpose — ask the agent to follow it to the replacement.

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, and run the spec
checks when you're done.

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. The spec tooling updates both together and lints the result; your prompt just makes the expectation explicit.

Before you move on, check two things in the agent's report: the new wording says what you meant, and the checks came back clean.

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 before
saving, and tell me the new citation.

You get a new number; the old one stays behind as a signpost. 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 and show it to me before saving.

The agent picks the next free number (numbers carry no meaning — they are allocated in order and never reused) and 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, numbering is intact, and no spec's body has changed under a summary that was written for older content. 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 number 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 numbering schemes. 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.