tomevault-io Agent Spec Writing
Write specifications for AI agents using a specialized template and writing disciplines. Agent specs
define contracts — what the agent must accomplish, its boundaries, and its integration points.
The agent definition (.claude/agents/<name>.md) owns the prompt — step-by-step workflows,
command examples, and execution instructions.
The spec is for the person building or reviewing the agent. The agent definition is for the LLM doing the work.
Constraints
- Agent specs live in
docs/specs/(subfolders allowed) - Filenames: lowercase, hyphenated (e.g.,
agent-reviewer.md) - All fixed template sections required
- New specs start with
status: draft - No duplication between spec, agent definition, and shared contracts document (except operational constraints — see Contract vs Prompt)
- The spec must not read like a system prompt rewritten in third person
Workflow
- Gather context: agent's role, trigger, inputs, outputs, integration points
- Identify shared data formats — templates produced/consumed across agents go in a shared contracts
document (e.g.,
workflow-contracts.md) - Invoke
/doc-coauthoringto develop the spec - Conform to the agent spec template (see below)
- Apply all writing disciplines (general and agent-specific)
- Apply the Contract Test to every behavioral section
- Final check: no spec/agent-definition duplication, shared templates extracted, Agent Profile complete, AC tests behavior not configuration, cross-references resolve
Template
---
title: <Agent Name> Agent
version: 0.1.0
last_updated: <ISO 8601 date>
status: draft | review | approved | deprecated
---
# <Agent Name> Agent
## Overview
What this agent does, its role in the system, and what it produces.
## Constraints
Hard boundaries. Must/must not. Behavioral constraints (e.g., "must read full files before assessing
correctness") belong here alongside operational rules (e.g., "must use gh.sh for all GitHub
operations").
## Agent Profile
| Constraint | Value | Rationale |
| ---------------- | ----- | --------- |
| Model tier | ... | ... |
| Tool access | ... | ... |
| Turn budget | ... | ... |
| Permission model | ... | ... |
## Trigger
When and how the agent is invoked.
## Inputs
What the agent receives at dispatch time (injected by the caller) vs. what it fetches itself via
tool calls.
## [Agent-specific contract sections]
Behavioral contracts that survive the Contract Test.
## Completion Output
What the agent returns as its final output to the invoking process. Reference the format in the
shared contracts document.
## Acceptance Criteria
- [ ] Given <precondition>, when <action>, then <outcome>
## Known Limitations
_(Optional)_ Intentional capability gaps. Omit entirely when none.
## Dependencies
What this agent relies on to function.
## References
Related specs, external docs, prior art.
Section Guidance
| Section | Purpose |
|---|---|
| Overview | One paragraph. Role, what it does, what it produces. |
| Constraints | Hard rules — both operational and behavioral. Behavioral constraints that affect correctness belong here, not in a "how to use your inputs" section. |
| Agent Profile | Configuration decisions with rationale. Four standard rows required (see below). Values describe intent, not YAML syntax. Include a note referencing the agent definition file path. |
| Trigger | Event or condition that causes dispatch. Reference the mechanism that triggers it. |
| Inputs | Two parts: (1) injected context (precise data interface — enumerate fields), (2) self-fetched data (summary). |
| Agent-specific sections | Contract-level content that varies per agent. Must pass the Contract Test. |
| Completion Output | Output contract with caller. Reference format in shared contracts doc. |
| Acceptance Criteria | Observable behavioral outcomes only. See AC guidance below. |
| Dependencies | CLI wrappers, shared contracts, engine specs, validators, tools. |
| References | Related specs and docs. Not required to function. |
Agent Profile Table
Four standard rows, always present:
| Constraint | Guidance |
|---|---|
| Model tier | Sonnet or Opus, with justification |
| Tool access | Which tools and why — frame as capability boundary |
| Turn budget | Upper bound with workload rationale |
| Permission model | Interactive vs non-interactive, safety mechanism |
Additional rows allowed for agent-specific constraints. Values describe intent: write "No write
tools (Read, Grep, Glob, Bash)" not "disallowedTools: Write, Edit, ...".
General Writing Disciplines
Define Once, Reference Elsewhere
Every normative behavior has exactly one home. When referencing behavior owned elsewhere:
- One-sentence summary of what happens (not how)
- Section-level cross-reference:
See [<spec-name>: <section>](./<spec-name>#<section-anchor>) for full behavior.
Never copy procedures, tables, or step lists across specs.
Rationale Separation
"Why" content goes in blockquote admonitions:
> **Rationale:** Explanation of why this design decision was made.
Test: Read the spec with rationale blocks hidden — it should be complete and implementable on its own.
Structured Formats Over Prose
| Content Type | Preferred Format |
|---|---|
| Procedures with branches | Numbered step lists with explicit branch points |
| Classification logic | Decision tables |
| Multi-case behavior | Tables or labeled sub-sections |
| Configuration | Tables (Setting, Type, Description, Default) |
| Data shapes | TypeScript type definitions in code blocks |
Avoid paragraph-form procedures with inline conditionals.
Agent-Specific Writing Disciplines
Contract vs Prompt
Belongs in the spec:
- Constraints and boundaries (what and why)
- Input/output contracts
- Integration points with other agents
- Acceptance criteria
- Design rationale
Belongs only in the agent definition:
- Step-by-step execution flows
- Command examples
- Numbered "you" voice instructions
- Templates transcribed from shared contracts
Wrong altitude indicators:
- Spec reads like a third-person system prompt
- Substantial textual overlap between spec and agent definition
- Removing a behavioral section wouldn't change what an implementor builds
The spec says "must validate inputs before starting work." The agent definition says "Step 3: Validate inputs — check A, B, C." The requirement is contract; the numbered steps are prompt.
Acceptable duplication: Operational constraints (command wrappers, style conformance, commit format) necessarily appear in both the spec and the agent definition. The spec is the normative source of truth; the agent definition transcribes what the LLM needs to see at runtime. This is the one expected exception to the "no duplication" rule — agents do not fetch the spec at runtime, so constraints they must follow must be restated in the agent definition.
The Contract Test
After drafting, apply to each behavioral section:
If you could delete the section and the acceptance criteria would still fully define correctness, that section is prompt-level content.
How to apply:
- Remove each behavioral section one at a time
- Check: does an AC cover this behavior?
- If yes → prompt (move to agent definition or remove)
- If no → contract (keep), or AC set is incomplete (add one)
Does not apply to structural sections (Overview, Constraints, Agent Profile, Dependencies, References).
Shared Contracts
Templates produced by one agent and consumed by another are defined once in a shared contracts document.
Extraction rule: If a template is produced by one agent and consumed by another, or if two specs reference the same format, extract it. The final spec should contain only cross-references, never inlined template text.
Inlining requirement: Agent definitions must inline templates they use — agents do not fetch templates at runtime. The contracts doc is the source of truth; agent definitions transcribe verbatim.
Cross-reference format:
(see
[workflow-contracts.md: Blocker Comment Format](./workflow-contracts.md#blocker-comment-format))
Acceptance Criteria for Agents
Criteria are for: Edge cases, ordering guarantees, interaction effects, negative cases, error handling paths. Not a GWT reformatting of spec prose.
Keep — observable behavioral outcomes: state transitions, output format conformance, error handling, cross-agent contracts.
Remove — constraint restatements ("uses gh.sh") and configuration tests (model choice, tool access). The Constraints section and Agent Profile table handle these.
Rework — execution ordering into behavioral terms: "reads spec before writing code" (behavioral, keep) vs "step 2 before step 3" (procedural, remove).
Budget: ~30-40 acceptance criteria max per spec.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.