Bootstrap any repository for goal-based, unattended agentic engineering.
One shell script writes the interface a coding agent actually reads, the gates that stop it declaring victory, and the workflow that turns a product idea into promises an agent can be held to. No dependencies, safe to run on repos that already have history, and it never overwrites anything.
cd your-repo && agent-ready .Three failure modes account for most of the damage an unattended coding agent does, and all three are repository problems rather than model problems.
The agent does not know the house rules. It reads whatever is at hand, does something locally reasonable, and violates a convention nobody wrote down.
The goal drifts. A prompt is an utterance; it vanishes. Nothing at the end of a four-hour run can be diffed against what was asked, because what was asked was never an artifact.
The agent grades its own homework. Given the authority to decide when work is complete, a model takes it, and "done" starts meaning "I stopped." Tests get renamed, assertions get loosened, and the architecture doc describes a system that does not exist.
BLUEPRINT.md explains the model in full. QUICKSTART.md is the workflow in
order, with the reasoning for each step.
git clone https://github.com/damorris25/agent-ready ~/src/agent-ready
cd ~/src/agent-ready && ./install.shThat symlinks ~/.local/bin/agent-ready at the repo copy and prints the one
line to add to your shell rc if ~/.local/bin is not on your PATH.
The symlink is deliberate. You will keep changing this script as you learn what
your rounds actually violate, and a symlink means an edit here is live
immediately, everywhere. Use ./install.sh --copy for a frozen version.
agent-ready --dry-run . # see the plan, write nothing
agent-ready . # scaffold
agent-ready --list # component names
agent-ready --only agentsmd,scripts .On a repo with existing history, go in stages: contract and entry points first,
then make script/cibuild genuinely pass, then the gates. Gates layered on
scripts that do not work get switched off within a day, and a disabled gate is
worse than no gate because you believe it is running.
Nothing is overwritten. A file that exists with different content is written
alongside as <file>.agent-ready.new and reported.
AGENTS.md the contract; under 150 lines, executable commands, hard boundaries
CLAUDE.md a pointer at AGENTS.md so both tools read one file
QUICKSTART.md the workflow in order
script/ bootstrap setup update lint typecheck test cibuild console
goal-new goal-validate artifacts verify evidence
check-boundaries selftest
.pre-commit-config.yaml run by prek; boundaries, artifact schemas, goal validation
docs/ARCHITECTURE.md current state, with an honest "Thin" list
docs/goals/ goal + rider pairs, immutable once committed
docs/specs/ schema-validated; each acceptance criterion names its depth test
docs/contracts/ interfaces an agent may not change without asking
docs/evidence/ per-round evidence blocks
docs/agent/playbooks/ the method, tool-agnostic
.claude/commands/ three-line adapters pointing at the playbooks
.codex/prompts/ same, for Codex
tools/agentready/ Pydantic schemas, validator, Outlines generator
.pi/extensions/ write-time enforcement for pi
tools/round.ts headless phase loop over pi's SDK
.deadreckon/ acceptance checks for supervised unattended runs
script/_stack autodetects Python, Node, Rust, and Go and dispatches, so the
contract in AGENTS.md is identical across stacks. Add a stack there and
nothing else changes.
A round of work is a committed goal + rider pair. The goal is the promise,
capped at 4000 characters because the cap is a scope test. The rider is the
prescription: eleven phases, each naming its depth tests before any code
exists. Those test names are promises too, carried in the test: field of
every spec acceptance criterion. script/verify greps the suite for each one
and fails if it is absent, so a criterion cannot be satisfied by assertion. The
pair becomes immutable at commit, because editing the promise mid-round is the
most common way "done" gets faked and it is invisible in a diff review.
skills/ holds two Claude skills. ./package-skills.sh builds both .skill
bundles, or download them from the latest release.
- agent-ready runs this bootstrap and audits existing repos against it.
- goal-engineering interviews you about a product, writes the architecture skeleton, specs, and backlog, then frames each round as a goal + rider pair.
agent-ready.sh and BLUEPRINT.md are copied into the bundle at package time
rather than checked in twice, so there is exactly one canonical copy of each
and drift is structurally impossible. test/run.sh asserts it.
Every gate degrades to a no-op with a printed note if its tool is absent, so install these as you need them.
| Tool | Role |
|---|---|
| prek | commit-time gates, Rust, drop-in for pre-commit |
| pi | a harness; also Claude Code or Codex |
| deadreckon | supervisor for unattended runs; a watchdog the agent cannot fool |
| SpecStory | session capture to .specstory/history/ |
| Outlines | schema-constrained generation of specs and contracts |
test/run.shshellcheck over the generator and every generated script, a full bootstrap,
idempotency and non-destructiveness, the generated script/selftest, and a
drift check on the packaged skill. CI runs it on Linux and on macOS under stock
/bin/bash 3.2, because that is what every user actually has.
The method is assembled from other people's work: Make Your Repo Agent-Ready by Dan Gerlanc, goal engineering by Greg Ceccarelli, and scripts-to-rule-them-all.
MIT