Bonus: Adopting It on Your Team

Why this matters

Nadia has seen what Quill can do in nine minutes and wants Bramble Books to use it for everything by next quarter. Priya has seen what Quill did to the newsletter export and wants nothing to change until someone can prove it is safe. Omar sits between them with a course's worth of ideas and no plan. If he proposes "adopt spec-driven development," Nadia hears delay and Priya hears paperwork. If he proposes nothing, Quill keeps merging work that nobody defined and nobody can prove. This lesson is the path Omar can put in front of both: thirty days, one change, one spec, one gate, one eval suite, and three ways to talk about it.

1. The one gate you would not let an agent pass

Start with a question, not a plan. Ask your team: which single action would you never let an agent perform without a person watching?

A human gate is a point in the workflow where a named person must approve before an action proceeds. Every team has one action that already feels like that, even if nothing enforces it today. Finding it tells you where your first gate goes, and proves the team already believes in gates.

The second half of the question matters as much: what evidence would change your mind? If the answer is "nothing," the gate is permanent, and that is fine. If it is "a hundred runs where the agent got it right, and a log I can read," you have described the eval suite and decision log of weeks three and four.

2. Week 1: one change through the chain

The artifact chain is the sequence of files a change passes through: intent.md, spec.md, plan.md, make test, evals/*.json, and the merged pull request. In week one you push exactly one change through it. A CR-101-sized change: visible to a user, touching one boundary, finishable in days.

Do these four things and nothing else.

1. Nadia writes intent.md, one paragraph, in business terms.
2. Omar writes spec.md with all six parts and routes the constraints to Priya.
3. Omar writes one failing test from one criterion and watches it fail for the expected reason.
4. Quill builds from plan.md, and Omar merges with the test log attached.

3. Week 2: one gate

In week two you add enforcement. gate.sh runs the checks the agent must pass before a person looks: build, tests, lint, stop on first failure, exit non-zero. One hook lets the gate allow, ask, or block an action. Every decision lands in .gates/log.jsonl.

Wire the hook with the Claude Code shape from L4:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash|Edit|Write", "hooks": [{ "type": "command", "command": "./gate.sh hook" }] }
    ]
  }
}

Pick one rule. For most teams the right first rule is the test lock: block writes under tests/. It is easy to explain and catches the most common way an agent cheats.

The log is the point. A gate that leaves no record is a gate you cannot prove ran. Put .gates/log.jsonl where no single engineer can edit it quietly, such as CI output or a shared bucket.

4. Week 3: the first 20 eval cases

An eval suite is a set of eval cases, each pairing a real task with the outcome the team accepted, stored as evals/*.json and run against the agent's configuration. In week three you write the first twenty. You mine them, not invent them.

Open the last month of merged pull requests. For each one, copy the request as it arrived, in the original words, into a case. Then write the checks: tests pass, lint clean, behavior unchanged, policy followed. Twenty cases take two people one afternoon.

Twenty is enough to see drift, a change in the agent's behavior with no change in the code. It is not enough for statistical confidence, and that is fine. You want a baseline pass rate to compare against next week.

5. Week 4: the gate moves into CI, and the first incident becomes an eval

Config is code: CLAUDE.md, skills, and hooks change what the agent does, so they get the same regression testing as source code. In week four you run the eval suite in CI, on configuration changes and nightly.

# .github/workflows/agent-evals.yml
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**']
  schedule:
    - cron: '0 2 * * *'

Set a merge threshold. Bramble picks 90 percent: a configuration change that drops the pass rate below 90 needs review by the owning team before it merges.

Then turn the first incident into a permanent eval. Incident-to-eval is the rule that every production incident becomes a permanent eval case, written by the team that had it. Do not wait for a new one. Use the one that made your team care.

Week four is also when the refund gate goes live. The hook returns ask for a refund over $200, Priya approves in the PR, and the approval lands in the log. The untrusted action now has a human gate, a record, and an eval.

6. Objections and answers

You will hear three objections. Each answer is a measurement, not an argument.

7. Three explanations

The same approach sounds different to different people. Use the version your listener needs.

For Nadia, the product owner: "You write one paragraph saying what done means, and you accept or reject it before anyone builds. Quill builds only what you accepted. The PR shows your paragraph next to the code."

For Omar's peers, the engineers: "The spec is the contract. Quill is the implementer. The gate is the evidence. You write the failing test, Quill makes it green without touching tests/, and the hook makes sure of that. Config changes run the eval suite the way code changes run the tests."

For Mr. Hale, the auditor: "Every change carries an author, a timestamp, and a reviewer of record. Every gate decision is logged outside any one engineer's control. Every action that moves money or touches personal data pauses for a named approver. Here is CR-102's evidence pack. It is six files."

8. What to read and do next

Thirty days gets you one change through the chain, one gate with a log, twenty eval cases, and a CI workflow that runs them. That is a working spec-driven lifecycle on one team. Next comes width: more change requests, more hook rules, more incidents turned into evals.

The evals side of this course was deliberately shallow. To build evaluators, generate scenarios, or measure an agent in depth, take the platform's Building and Evaluating AI Agents course. It covers what makes a case honest, how to grade a written answer, and when twenty cases is too few.

By day thirty Bramble has four changes shipped, every one with a named approver and a log line. Nadia got her speed. Priya got her proof.

Summary

• Start with the one action your team already refuses to trust an agent with, and write down what evidence would change that. That is your plan.
• Week 1: one small change through the artifact chain. Week 2: gate.sh, one hook, a decision log. Week 3: twenty eval cases mined from merged PRs. Week 4: the suite in CI, the first incident as an eval.
• Answer objections with measurements: wait time per gate, files the team already needed, the pass rate moving with no code change.
• One rule, three versions: outcome and acceptance for the product owner, contract and evidence for the engineer, control and log for the auditor.
• Adoption is one change, one spec, one gate, one eval suite. Width comes after; the Building and Evaluating AI Agents course covers evals in depth.