Skip to content

Customizing your agent and repository

Week 4 · Instruction files, hook gates and subagent roles

The failure comes first

An agent changes a parser and also edits the lockfile.

What rule would have predicted and prevented that failure?

One rule, one failure, one check

Failure Rule Check
Lockfile changes with parser Keep dependency files out of parser fixes staged path list
Test is omitted Name and run the focused test command output
Path escapes checkout Stop on an outside path negative path case

An instruction file is scoped context

AGENTS.md can state:

Before editing: read the target and its tests.
After editing: run the focused test.
Stop: do not change lockfiles for this task.

The rule is readable. It is not yet a Git permission boundary.

Request versus gate

Request: “Run the focused test and report it.”

Gate: “At before_commit, exit 2 when a staged Python file has an unused import.”

A request can be skipped. Git still invokes the gate.

Generate, then verify

Generated proposal: add import json to report.py.

Verification: stage it, commit, read the nonzero hook result; remove the import and commit again; read the PASS result.

The first record proves the gate stopped that input. The second proves the clean path passed.

A hook is a narrow invariant

A hook should:

  • read the staged paths;
  • reject malformed input and protected paths;
  • return a nonzero status for a finding;
  • avoid importing or executing the staged file.

It does not replace tests, review or a specification.

Live gate: bad commit

$ git commit -m "practice: blocked import"
src/report.py:1: unused import 'json'
STOP: fix the findings above, then run the hook again

The commit is not created. Save this output as evidence.

Live gate: good commit

$ git commit -m "practice: pass the gate"
PASS: no protected file and no unused import in 1 file(s)

Now inspect git show --stat. A green hook leaves application behavior unverified.

Role is a contract

A subagent role supplies:

  1. one instruction;
  2. a small tool allowlist;
  3. a named hand-back;
  4. a stop condition.

A label such as “reviewer” supplies none of these by itself.

Researcher role

Instruction: locate the parser and its callers; change nothing.

Tools: read, search, one named read-only test.

Hand-back: research.md with file/function references, command and open questions.

Stop: parser is generated or the named test is absent.

Implementer role

Instruction: change only the named function and preserve its contract.

Tools: read, edit that file, run the named test.

Hand-back: diff, test output and one remaining risk.

The parent opens the diff and decides whether to continue.

Reviewer role

Instruction: judge issue, diff and evidence without editing.

Tools: read the named files and run the named check.

Hand-back: each finding is confirmed, refuted or cannot tell with evidence.

A summary without a location or input is not a finding.

Fresh context, smaller boundary

Pass the implementer only the role contract, the research record and named files.

Pass the reviewer the issue, diff and evidence. Do not pass the implementer's private plan.

A fresh context makes the contract visible; it does not make the reviewer infallible.

Studio output

You will keep:

  • AGENTS.md and instruction-review.md;
  • blocked.txt and passed.txt;
  • hook-record.md with the commit hash;
  • role-contract.md and role-review.md;
  • one decision line: accept, narrow, recheck or stop.

Check the evidence

For every record ask:

  • Which exact input did the check see?
  • What did the exit status establish?
  • Which behavior remains untested?

Do not turn a course-written example or a generated proposal into a real run record.

Technical specification hand-off

Carry the same boundaries into this week's project technical specification:

  • instruction scope and failure it prevents;
  • hook event, input and exit condition;
  • subagent role, tools and hand-back;
  • the check that could falsify each claim.

Exit decision

Accept only the invariant your records check.

Narrow when a role or gate is too broad.

Recheck when the command or input is missing.

Stop when the boundary cannot be enforced safely.

Studio

Write the rule. Trigger the gate. Read the hand-back.

Then decide from evidence.