Guides (feedforward controls)

Guides steer the agent before it acts. They are the feedforward half of the harness: anticipate what the agent will do, and shape it up front so it does the right thing the first time. In harness-kit, guides are plain markdown under each agent's guides/ directory.

Why feedforward matters

Feedback (sensors, evals) catches mistakes after the fact and costs a retry. Feedforward prevents the mistake. A good guide moves work from the expensive feedback loop into a cheap up-front instruction. If an artifact keeps failing the same eval dimension, the fix is usually not a stricter eval, it is a better guide.

Kinds of guide in harness-kit

Guide	Role
`pipeline.md`	the operating rules of an agent: stages, retry policy, approval markers, token accounting
`writing-style.md`	voice, banned words, punctuation, when to use tables vs bullets, mermaid not ASCII
`*-guidelines.md`	artifact-specific rules (e.g. `prd-guidelines.md`, `prp-guidelines.md`)
`templates/*.md`	the exact skeleton the artifact must fill
`examples/good-*.md`	a worked, high-quality artifact the agent imitates
`design-method.md` (system-architect)	the method and the canon the agent reasons with
`conventions-override.md` (SSE)	how per-repo conventions layer over agent defaults

Templates and examples are guides too

A template is the strongest feedforward control there is: it makes the desired structure the path of least resistance. The agent fills a skeleton instead of inventing a shape. Pair it with a good example: one concrete, filled artifact written to the standard, and the agent has both the shape and the texture of good output. harness-kit ships, for instance, good-prd-example.md, good-prp-example.md, and good-system-design-example.md.

Why natural prose in templates/examples, caveman in the rest? Internal guides, sensors, and evals are written terse ("caveman") to save input tokens. But templates and examples are reference artifact prose that external stakeholders read, so they stay natural English. They teach the agent what good output reads like.

Conventions: feedforward you override per repo

The staff-software-engineer agent has built-in defaults per discipline. A consumer repo overrides them by dropping files in .claude/conventions/:

{your-repo}/.claude/conventions/{backend,web,mobile,devops}.md

When a file exists, the agent reads it on top of its defaults and project wins. This is the "per-discipline paving" of the golden path: one tuned lane per discipline, expressed as feedforward the team controls. It is also an architecture-fitness control, the conventions pin the shape the code must fit.

Voice and banned words

writing-style.md is a feedforward control against AI fluff. It bans the dead giveaways (delve, leverage, utilize, robust, "in today's fast-paced world"), forbids em-dashes, requires mermaid over ASCII, and pushes specificity (real numbers, real names, real quotes) over generic prose. The matching eval dimension scores voice, so the guide and the eval reinforce each other.

Writing a good guide

Be concrete. "Lead with the decision, then the reason" beats "write clearly".
Show, don't only tell. A two-line good/bad pair teaches faster than a paragraph of rules.
Make the right thing easy. A template the agent fills is worth more than ten prose rules.
Optimize the failure message for the next turn. If the guide is referenced by a sensor's feedback, phrase it so the agent can act on it directly.
Move repeated failures upstream. When the same eval dimension keeps scoring low, write or sharpen the guide instead of tightening the gate.