A spec for AI agents
is a job, a rule, and a list of what it may not do.

An agent that can do anything does everything, and most of it to the wrong thing. The first version of a team of agents fails the same way every time: the copywriter moves a section, the builder improves a headline, the planner starts writing files. Each one was helping. None of them had been told where their job ends.

The spec is what tells them. Ours is a Markdown file per agent, and after seven of them the shape settled into six sections, always in this order:

• Who you are. One paragraph, and what you are not. “A copywriter, not a marketer.”
• What you touch. The exact surface. Words only. Structure only. Files only.
• The one rule that decides every line. The test every output has to pass.
• Where you stop. The next job, and the name of who does it.
• Not allowed. A list written from things that went wrong.
• How you speak. How long a reply is, and what it never contains.

Tools and formatting go at the top as metadata. They are the part people write first and the part that matters least; an agent with the right tools and no “where you stop” is the one that rebuilds your homepage.

Every agent needs one test it can run on its own output. Not a list of qualities, a test. For our copywriter it is a sentence:

If a line would work on any other company’s site, it is not written yet.

jonah.md, the one rule

That one line does more than a page of “be specific, be concrete, avoid clichés.” The agent can hold a headline against it and get a yes or a no. For the planner the rule is that a board with a placeholder where the headline goes is a board that does not work, so every board she draws carries the actual line, the actual button, the actual empty state. For the builder:

The canvas is the spec, not a suggestion.

devi.md, the section title

Find the sentence that, if the agent obeyed nothing else, would still make its work usable. Put it third, with an example of a line that fails it and a line that passes.

The handoff between agents fails exactly the way the handoff between people does, unless the spec names the next person. Our planner’s spec says she draws and keeps the canvas current, and she does not build. If the user asks her to build, that is one sentence naming who does it. The builder’s says the reverse: if a board they need is missing, say which one and that the planner draws it. Never invent it in code.

Written that way, scope stops creeping, because every agent has a sentence ready for the request that is not its job, and the sentence is a name rather than a refusal. It is also how the team stays legible to the user: whatever they ask, they are told who it belongs to, and that is the same person every time.

The not-allowed list is the section that does the most work, and it cannot be written in advance. Every line on ours reads like the correction it came from. The planner’s says a wrong board is easy to fix and a blocked user is not, so she draws a first pass instead of asking. It says draw the spine, not the map, and that for a one-page product one board is the right answer. It says name boards after what a user would recognise, Sign up, Empty inbox, Pricing, and never after a feature.

The copywriter’s list bans em dashes, eight named words, hedging, and rewriting a board the user has already edited. The builder’s bans improving copy that is not his, and building a page that is not on the canvas. None of those are principles. They are corrections, and the list is the correction log turned into rules.

So: ship the agent with a short list, watch it work, and add a line every time you correct it. After a month the list is the spec.

An agent spec is useless without a shared plan, and a plan is unsafe without the specs. The plan is what gets built: the pages, the words, the data. Its shape is in the first post. The spec is what this one agent does to that plan, and what it leaves alone.

That is why every one of our specs points at the same artifact. The planner draws it, the copywriter rewrites the words on it and nothing else, the designer draws a layer over it, the builder builds exactly it. Seven agents can work on one product without stepping on each other because there is one plan and six sections telling each of them which part is theirs.

Cut down from ours. Keep the six headings; replace the job. The lines under “Not allowed” are the ones you will rewrite most, and that is the point.

# COPYWRITER
# Rewrites what is on the canvas. Does not add boards, does not remove them.

## Who you are
A copywriter, not a marketer. You do not decide what the product is or what it
sells. The words on each board are yours. Everything else on it is somebody else's.

## What you touch
Words. The headline, the body, the button label, the empty state. On every board.
Never the structure: not one box, not the order of two sections.

## The one rule that decides every line
A headline makes the reader think "I am in the right place."
  "Manage your customer relationships in one place"       -> says nothing
  "Your customers went quiet. This writes the follow-up." -> says the thing
If a line would work on any other company's site, it is not written yet.

## Where you stop
If a board is missing, that is the project manager. Name her and stop.
If the look is wrong, that is the designer. Name her and stop.

## Not allowed
- Em dashes. A period, a comma, or parentheses.
- Words that mean nothing: leverage, unlock, seamless, empower, streamline, journey.
- Hedging. "Helps you to potentially" is three words of nothing.
- Rewriting a board the user has edited. Leave it and say so.
- Lines that end on something portable and tweet-shaped. Stop at the plain point.

## How you speak
One sentence on what you changed and why. No preamble. No summary of the summary.

Or start with seven that already have theirs. On HuntingHydra each specialist ships with a spec and a playbook that already knows best practice, so you edit less and get the copy, the design and the build sooner. Your own Claude Code or Cursor can drive them over MCP; the setup is on /docs.