Is Your Repo Ready for Agents?
A field guide
Audit the interface your coding agents actually use.
Audit the interface your coding agents actually use.
discover → act → prove
Dan Gerlanc
Engineering leadership for the age of AI.
Builder
Co-founder and CTO of .txt; VP of Eng. at Normal Computing.
Co-founder and CTO of .txt; VP of Eng. at Normal Computing.
Teacher
O’Reilly instructor on Python, Pandas, and Dask.
O’Reilly instructor on Python, Pandas, and Dask.
Partner
Fractional CTO / VP Engineering and advisor for AI/ML teams.
Fractional CTO / VP Engineering and advisor for AI/ML teams.
A PODCAST FOR ENGINEERS BUILDING WITH AI
The craft of software engineering is being rewritten.
Dispatches from engineers building—and building with—agents. Wins, dead ends, and practical lessons.
Your repo is the agent's interface.
The repository configuration determines whether the agent can
discover the path, make a safe change, and prove the result.
Probabilistic orchestrator. Deterministic checker.
LLM
Slow + variable
Spend judgment where judgment matters.
CODE
Fast + exact
Automate every cheap, repeatable decision.
Seven signals of an agent-ready repo
static analysis
defined tasks
durable memory
skills
observability
verification
history
Do not spend tokens on formatting.
Move cheap mechanical judgment into one fast command.
$ prek install
$ prek run --all-files
✓ format · lint · types · secrets
$ prek run --all-files
✓ format · lint · types · secrets
Audit question
Can one fast command catch routine mistakes?
Can one fast command catch routine mistakes?
One file, three layers of protection.
12
checks on staged files
$ git commit
→ prek run
→ prek run
Python
ruff-check · ruff-format
Lint and normalize code.
Lint and normalize code.
Dependencies
uv-lock
Keep the lockfile synchronized.
Keep the lockfile synchronized.
Repository
9 built-ins
whitespace · EOF · BOM · JSON · YAML
line endings · symlinks · merge conflicts · private keys
whitespace · EOF · BOM · JSON · YAML
line endings · symlinks · merge conflicts · private keys
One obvious task interface
script/bootstrap
script/setup
script/test
script/server
script/setup
script/test
script/server
Audit question
Are setup, test, and server/run commands unambiguous?
Are setup, test, and server/run commands unambiguous?
Docs are the API between turns.
TURN 14
ARCHITECTURE.md
TURN 15
Update architecture docs when a boundary, dependency, or invariant changes.
ARCHITECTURE.md · ADRs · root → nested AGENTS.md
Audit question
Can a fresh agent recover what changed and why without the prior conversation?
Can a fresh agent recover what changed and why without the prior conversation?
Make documentation part of “done.”
AGENTS.md / TASK SKILL
“When a change affects architecture, interfaces, or invariants, update the relevant docs before finishing. Delegate the docs pass to a sub-agent.”
code change
docs sub-agent
next turn
Generated context
DeepWiki in Devin can index a repo and generate a navigable wiki.
DeepWiki in Devin can index a repo and generate a navigable wiki.
Automated backstops
CI drift checks · scheduled agent runs · docs-freshness pull requests
CI drift checks · scheduled agent runs · docs-freshness pull requests
Default in the workflow. Reinforce on a schedule.
Repo-specific skills encode expert moves.
Database migration
Check tenant row-level security.
Check tenant row-level security.
Security review
Run the repo's actual threat checks.
Run the repo's actual threat checks.
Audit question
Are domain-sensitive tasks executable and verifiable?
Are domain-sensitive tasks executable and verifiable?
Agent-observable systems
symptom
logs
trace
code
reproduced failure
verified fix
Give the agent structured logs, traces, metrics, stable fixtures, and documented queries.
Audit question
Can an agent reproduce and inspect runtime behavior?
Can an agent reproduce and inspect runtime behavior?
The builder should not be the only judge.
builder
artifact + evidence
independent judge
verdict
Examples
RoboRev · deadreckon.sh · Superpowers
RoboRev · deadreckon.sh · Superpowers
Audit question
Can an independent check falsify “done”?
Can an independent check falsify “done”?
Define “done” before the agent starts.
goal
text or file
done contract
.deadreckon/acceptance.yaml
isolated run
worktree + sandbox
dr-gate
checks + signs
deadreckon
validates completion
Goal
Inline or from a file: what must become true.
Inline or from a file: what must become true.
Done contract
Executable, falsifiable checks created by
Executable, falsifiable checks created by
start or def-done.$ deadreckon startenter your goal and kick-off
$ deadreckon def-donedefine the goal
Machine-readable history
What changed?
Focused commits and legible diffs.
Focused commits and legible diffs.
Why did it change?
A consistent message convention.
A consistent message convention.
Audit question
Can an agent infer what changed and why?
Can an agent infer what changed and why?
Your Repo Readiness score
0/14
START HERE
Lowest-scoring candidates
Choose your first change
YOUR NEXT MOVE
Add one fast deterministic check
1 · Lowest score
Start with the visible gap.
Start with the visible gap.
2 · Frequency or risk
Resolve ties with the work that matters most.
Resolve ties with the work that matters most.
Audit a repo you know.
Where does an agent lose the trail?
What is the first change you would make?
10–20 minutes · compare scores · challenge assumptions
Score all seven checks in one place
01Static analysis
Can one fast command catch routine mistakes?
02Defined tasks
Are setup, test, and server/run commands unambiguous?
03Durable memory
Can a fresh agent recover what changed and why without the prior conversation?
04Skills
Are domain-sensitive tasks executable and verifiable?
05Observability
Can an agent reproduce and inspect runtime behavior?
06Verification
Can an independent check falsify “done”?
07History
Can an agent infer what changed and why?
0–4 START HERE · 5–9 USEFUL FOUNDATION · 10–14 AGENT-READY
0/14 · START HERE