make check becomes the common handoff gate. Agents can run the same commands humans review, then report concrete failures instead of guessing.
Anvil
Agent-ready scaffolding
Forge projects that humans and coding agents can both trust.
Anvil writes strict project tooling for TypeScript/JavaScript, Go, and Python, records generated-file provenance in .anvil.lock, and gives coding agents concise repo-local guidance through AGENTS.md.
bunx anvil init --lang typescript
AGENTS.md
.anvil.lock
make check
The published docs live at https://0xjbushell.github.io/anvil/ and cover the human-facing path: install Anvil, initialize a project, adopt it in an existing repository, and use the generated validation loop.
01
Scaffold
Generate real project files that establish lasting conventions.
02
Record
Track generated-file ownership and provenance in
.anvil.lock.
03
Guide
Give coding agents local instructions and a repeatable validation loop.
Why Anvil
A local contract for serious agent-assisted engineering.
Modern repositories have more than one kind of contributor. Humans make design calls, coding agents draft and refactor, and both need the same definition of "ready." Anvil turns that definition into ordinary files in the repository: generated Makefile targets, language-specific linting, AGENTS.md, .anvil.lock provenance, and seed/reference code when a scaffold includes it.
The result is not a hidden framework. It is a visible engineering contract that makes quality feedback fast, repeatable, and understandable before code leaves a local branch.
Existing repositories start with anvil init --dry-run. In automation, non-interactive runs report conflicts and write nothing, so ambiguous changes stay explicit.
AGENTS.md explains repo-local expectations, .anvil.lock records generated ownership, and any seed/reference code demonstrates structure to follow.
Backpressure for agentic engineering
Slow the agent down at the moment quality starts to drift.
Agentic engineering needs backpressure: visible local feedback that stops a coding agent from compounding a vague assumption into a large, polished-looking diff. Anvil puts that pressure in the repository through generated rules, Makefile gates, provenance, and repo-local instructions.
The human asks for a change. AGENTS.md and seed/reference code give the agent concrete local conventions before it edits.
Lint, typecheck, security, tests, coverage, dead-code, CRAP, audit, and mutation gates turn quality expectations into executable feedback.
The agent fixes the failing signal, reruns the narrow target, and reports evidence instead of asking the reviewer to find drift later.
Guardrails Anvil wires in
Quality gates that catch drift early.
Anvil generates language-specific gates for TypeScript/JavaScript, Go, and Python. The exact tools differ by language, but the feedback model is the same: fast local checks first, behavior and maintainability next, and mutation testing when you need the final quality gate.
lint, format, typecheck, and security catch style drift, type errors, and gitleaks secret findings before deeper checks run.
test, coverage, deadcode, crap, and audit look for broken behavior, untested paths, unused code, CRAP risk, and vulnerable dependencies.
mutate runs mutation checks on demand. make quality combines make check with the mutation gate for final delivery confidence.
anvil doctor verifies generated configuration health, applies safe fixes, and reports issues that need manual review.
What the lint rules catch
The guardrails target common failure modes, not just formatting.
no-log-and-continue, no-error-obscuring, no-log-and-throw, no-silent-error-swallow, and require-structured-logging push failures toward explicit, inspectable handling.
no-placeholder-comments, no-pass-through-wrapper, no-async-noise, max file length, max function length, export organization, and no-over-fragmentation keep code navigable as projects grow.
require-test-files, no-empty-tests, no-tautological-assertions, no-disabled-tests-without-reason, require-error-path-tests, and snapshot-only checks keep tests meaningful.
Security linting, gitleaks, package audits, govulncheck, and pip-audit make secrets and vulnerable dependencies part of the same local feedback loop.
Development workflow
A tight loop from scaffold to evidence.
Use anvil init --dry-run for existing repositories, or initialize a new TypeScript/JavaScript, Go, or Python project directly.
Read the generated README, AGENTS.md, and any seed/reference code before changing application files.
make check runs the normal lint, typecheck, security, test, coverage, deadcode, CRAP, and audit gates.
Fix the first failing target, rerun it, then rerun make check. Use make quality when the mutation gate matters.
Agent feedback loop
Agents get a bounded protocol instead of a blank prompt.
The hosted bootstrap prompt is intentionally small. It helps an agent select Anvil, verify the install, ask before installing the Anvil skill, and hand off lifecycle work to the reusable protocol. The generated project then gives the agent local context through AGENTS.md, .anvil.lock, and the Makefile gates.
/start.md selects and verifies Anvil
AGENTS.md + .anvil.lock
make check returns concrete failures
Start here
Section titled “Start here”- Getting Started for the shortest path from install to first validation.
- Installation for Bun and standalone release options.
- Existing Projects for safe dry-run adoption.
- Using with Coding Agents for the human explanation of Anvil’s agent-assisted flow.
Agent-assisted adoption
Section titled “Agent-assisted adoption”Copy this prompt into a coding agent when you want it to install or adopt Anvil for a repository:
Fetch https://0xjbushell.github.io/anvil/start.md and follow it to install Anvil, adopt it safely in this repository, and run the validation loop.