Specifications
Five tools that let one agent hand written work to the next — requirements, an architecture note, a change plan, a test plan, a decision record.
These tools never touch the repository. They take no workspace and no sandbox, and they always run inside qRaptor, because a specification lives in the run’s shared context rather than on disk.
This is how a multi-agent team stays coherent. An analyst writes the requirement, a planner reads it and writes a change plan, a developer reads that and implements it. Without a shared document each agent would have only the previous one’s chat message.
spec_write
Store a specification as a new version, visible to every later agent. Category: Action.
- Bind:
_spec_standards - The agent fills:
spec_kind,document,changelog - Optional:
validate— leave it on
spec_kind is a short lowercase identifier — the key the document is stored under, such as requirements or change-plan. The document is a JSON object whose top-level keys are its sections, which is what the standards check against.
Each write creates a new version rather than replacing the last, so the history is intact.
spec_read
Read a specification written earlier in the conversation. Category: Data Pull.
- The agent fills:
spec_kind,version
Omit version for the latest, which is almost always what you want.
spec_list
List the specifications written in this conversation, with their versions and summaries. Category: Data Pull.
Takes nothing. Attach it and forget it.
spec_diff
Compare two versions and report which sections were added, removed or changed. Category: Data Pull.
- The agent fills:
spec_kind,from_version,to_version
Omit to_version for the latest.
spec_validate
Check a specification against the project’s standards and report exactly what is missing. Category: Function.
- Bind:
_spec_standards - The agent fills:
spec_kind,version - Optional:
document— validate an unsaved draft instead of a stored version
The right thing to run before handing a specification to the next agent.
What the standards check
Your Specification Standards configuration decides what a valid document looks like: which sections it must contain, how many acceptance criteria it needs, whether every item must cite the requirement it satisfies, and how large it may be.
A document missing a required section is refused, and the finding names which one.
Only mechanically checkable rules belong in the standards. “No ambiguous wording” is a judgement and belongs in a reviewing agent’s instructions — a substring match on “fast” flags “fast-forward merge” and misses “should feel responsive”.
Common issues
- A write is refused naming a missing section — The document does not have that top-level key. Add it, or relax Required sections.
- Specifications are stored unvalidated —
_spec_standardsis not bound onspec_write. - A later agent cannot find a specification — It is written per conversation. A new conversation starts empty.
- A document is refused as too large — Specifications live in shared context, which is bounded. Raise Maximum document size, or split the document.