Guides / intermediate
Designing the intent layer
How work enters a factory — specs, issues, and pass conditions — so agents have something to close against.
A factory without an intent layer is a chat window with a Git remote. The agent will invent the job, invent the done condition, and then invent a reason the empty test passed.
Intent is not a prompt. It is the artifact a stranger can pick up next week and still know what “shipped” meant.
Write the signal, not the solution
The useful input is a signal the team already trusts: a bug with a reproduction, a failing check, a customer report with a timestamp, a spec that names an interface. “Make onboarding nicer” is not a signal. “The invite email 500s when the workspace has no billing owner” is.
If you cannot name the pass condition in one sentence, you are not ready for an unattended run. The agent will optimize for looking finished.
Put done outside the repo the agent can edit
Agents rewrite tests to match the code. That is not a character flaw; it is the shortest path to green. Hold-out the acceptance criteria:
- A scenario file the agent is not allowed to modify.
- A production probe or preview URL the human can open.
- A hook that fails the job if the named files change.
StrongDM published the same lesson as a factory rule: scenarios live outside the codebase, like a holdout set. You do not need their Digital Twin Universe to steal the shape.
Issue trackers are not factories
Linear, GitHub Issues, and Jira become intent layers only when the template forces the fields a harness can use: reproduction, expected behavior, out of scope, and who merges. An empty issue that says “fix this” is a request for a plausible diff.
If you use an issue-to-PR product, treat the issue form as the API. Refuse runs that skip required fields. A human still merges.
Specs that survive a model swap
Natural-language specs rot the same way prompts rot. Prefer:
- An OpenAPI, proto, or type definition the tests already compile against.
- An
AGENTS.md/CLAUDE.mdthat states invariants, not vibes. - A short list of forbidden edits (generated folders, lockfiles, secrets).
Tessl and GitHub Spec Kit are attempts to make the spec the durable object. They are not magic. A spec nobody updates is worse than a ticket, because it looks authoritative.
Where humans sit
Write the policy down.
- Who may start a run.
- Who may approve a plan before execution.
- Who merges.
- What the agent is forbidden to touch.
“A human merges every pull request” is a factory. “The agent pushes to main when CI is green” is a different factory. Do not discover which one you run during an incident.
The directory will keep selling you orchestration. Start with the signal instead.