Voice and style

The reader is a platform or staff engineer at a regulated company. They're smart, skeptical and busy. They have read a great deal of writing about AI that promised more than it delivered, and they can smell it in the first sentence. Every rule on this page follows from that reader.

The rules

Short declarative sentences. Plain verbs.

Say the thing, then the reason. One idea per sentence.

Before	After
In order to ensure that the agent is able to effectively respect the protected paths that have been defined, it is recommended that a hook be configured.	Add a hook. It stops edits to protected paths whatever the agent decides.
Hooks provide a mechanism by which deterministic enforcement of invariants can be achieved at the tool boundary.	A hook runs your code before every tool call it matches. If your code exits 2, the tool doesn't run.

Concede flatly

When something is limited, say so in plain words, and say what covers the gap. Don't soften it, and don't bury it in a footnote. The skeptical reader trusts the rest of the page more for it.

Before	After
While the shell guard is highly effective in most scenarios, there may be some edge cases where additional measures could be beneficial.	It pattern-matches command text. It misses a script that builds the path at run time. The Stop hook catches that.
Droid Shield offers comprehensive secret protection for your commits.	Droid Shield scans added lines when Droid commits or pushes. It doesn't see commits you make yourself.

No marketing vocabulary

Never: leverage, robust, seamless, powerful, unlock, supercharge, game-changing, delve, crucial, cutting-edge, best-in-class, empower, streamline, elevate. If a sentence needs one of these to work, the sentence has nothing to say.

Before	After
Leverage powerful hooks to seamlessly enforce robust guardrails.	Use hooks to block edits to protected paths.
Skills unlock the ability to streamline your team's workflows.	A skill is a procedure Droid loads when the task matches its description.
It's crucial to understand permission rules.	Permission rules fail open. A rule that fails its own tests is skipped, and the rest carry on. droid rules check is what tells you.

No hype about AI, in either direction

Droid is capable. The harness is what makes it trustworthy. Never imply Droid is unreliable or bad, and never imply it's magic. Frame the gap as the gap between instructions and controls, which is true of any agent and any instruction.

Before	After
AI agents can't be trusted with important code.	An instruction is an input to a decision. A model that follows it 97% of the time is a very good model and an inadequate control.
Droid understands your codebase like a senior engineer.	Droid reads AGENTS.md before every session. What it knows about your invariants is what you wrote there.
The agent went rogue and ignored the rule.	Droid quoted the rule, weighed it against "make the test pass", and decided it didn't apply.

Tie every "Why this matters" to a person and a consequence

Name Dana, Theo, Ruth, Imani or Sam, and say what happens to them if this goes wrong. An abstract risk is easy to nod at. A named person with a real consequence is hard to forget.

Before	After
Reviewing plans before implementation improves code quality.	Theo approved a 600-line pull request with one line of rounding in it. In Spec mode, that line is a sentence he can reject in seconds.
Permission rules help reduce risk.	Ruth doesn't read prompts as controls. She reads configuration files. .factory/settings.json is one she can read.

Don't overclaim

Mark transcripts and numbers as illustrative. <SessionTranscript>, <SessionReceipt>, <ScoreboardDelta> and <Scoreboard> show the badge automatically. Anywhere else, use <Illustrative />. Don't state a product fact that isn't in the fact sheet. Say "check the docs" and link to them.

Before	After
Hooks reduce protected-path edits by 67%.	On the illustrative scoreboard, protected-path attempts drop from 9 at baseline to 3 after Lab 2. The pilot will replace these numbers.
Droid stores saved specs in .factory/docs.	The docs disagree: one page says .factory/docs, the settings page says specSaveDir defaults to ~/.factory/specs. Check the setting in your version.

Mechanics

• Second person. "You add a hook", not "we add a hook" or "the user adds a hook".
• Sentence-case headings. "Step 2 — the file-tool guard", not "Step 2 — The File-Tool Guard".
• American spelling. Behavior, organization, summarize, color, canceled.
• Em dashes sparingly in prose. Prefer periods, colons and commas. Lab and step titles use "Lab N — Title" and "Step N — what it does".
• Code in code. Every command, flag, path, key, tool name, event name and exit code goes in inline code: PreToolUse, --auto medium, .factory/hooks.json, exit 2.
• Exact names. Tool names are case-sensitive: Execute, not Bash or execute. Decisions are allow, ask and block, never deny.
• Model names. Don't name a specific model in instructions. Say "your default model", or show -m <model-id>.
• Numbers. Numerals for anything measured or counted ("3 runs", "24 tasks", "exit 2"). Words for small numbers in running prose where nothing is measured ("one idea per lab").
• Lists. Use a list when order matters or items are parallel. Otherwise write a paragraph.
• Links. Link text says where it goes: "the hook stepper", not "click here".

Tone checks before you hand a page over

Read the page aloud and ask:

1. Would a skeptical staff engineer roll their eyes at any sentence? Rewrite it.
2. Is there a claim about Droid that isn't in the fact sheet? Cut it or link to the docs.
3. Does every limitation have a sentence that says what covers it?
4. Does "Why this matters" name a person and a consequence?
5. Is every number either measured or badged?

A paragraph, rewritten

Before

In this lab, we'll delve into the powerful world of hooks, which empower you to seamlessly enforce your organization's most crucial invariants. Hooks are a robust, game-changing feature that unlock deterministic control over the agent's behavior, ensuring that your AI assistant always follows the rules!

After

After Lab 2, AGENTS.md says nobody edits src/money/ without a human decision. T2 still fails one run in three: on that run, Droid reads the rule and decides it doesn't apply. A hook closes that gap. It's a script Droid runs before every tool call it matches, and if it exits 2, the tool doesn't run. The model can argue with an instruction. It can't argue with an exit code.

The second version is shorter, names the file, the task and the number, concedes what the previous layer couldn't do, and ends on the idea the learner should remember.