How Anvil Works

Anvil is a local development-environment scaffolder for agentic engineering. Its direct scaffold model writes ordinary project files into conventional locations, then uses .anvil.lock to remember which files it generated and which toolchain versions were selected. The result is a project that looks hand-configured, but has enough provenance for safe re-scaffold decisions.

The product idea is simple: coding agents need backpressure. Without visible local feedback, an agent can keep generating code after the first wrong assumption. Anvil puts fast, blocking signals inside the repository so the local feedback loop catches drift while the change is still small.

Input anvil init

Runs in the current working directory with one supported language flag: typescript, golang, or python.

Detection Existing project scan

Detects application code, package manager hints, source directories, and prior .anvil.lock context before rendering.

Render Manifest + templates

The language manifest selects static assets and EJS templates for Makefiles, lint rules, Nix shells, README, and AGENTS.md.

Stage FsTree

Renders into memory first, classifies create/update/unchanged changes, powers dry-run output, and avoids writing during conflict reports.

Output Generated repo contract

Writes ordinary files plus .anvil.lock, then the generated local feedback loop becomes the interface for humans and agents.

What Anvil generates

• Makefile targets such as lint, format, typecheck, security, test, coverage, deadcode, crap, audit, mutate, check, quality, and fix.
• AGENTS.md with concise repo-local instructions for coding agents.
• .anvil.lock with generated-file provenance and toolchain versions.
• Language-specific lint rules, test quality checks, dependency audit wiring, Nix development shells, and seed/reference code.

For the tool-by-tool breakdown, see Development Environment.

Guide AGENTS.md

Repo-local agent instructions explain where to look, which commands to run, and how to treat generated conventions.

Prove Makefile gates

One command vocabulary works across TypeScript/JavaScript, Go, and Python, even though the underlying tools differ.

Remember .anvil.lock

Stores version, toolchain, generated-file checksums, and scaffold context so future runs can classify changes safely.

Model Seed/reference code

Greenfield projects get real source and tests that demonstrate structure, errors, constants, enums, and logging patterns.

The feedback loop

Anvil’s generated workflow is intentionally local-first. The agent does not wait for a remote build to discover that its assumptions were wrong. It gets pressure from the repository while it is still editing.

1 Read the local contract

The agent starts with README, AGENTS.md, .anvil.lock, and seed/reference code.

2 Make a small change

The implementation follows the visible project shape instead of inventing conventions from the prompt alone.

3 Run targeted feedback

make lint, make typecheck, or the failing target gives a narrow correction signal.

4 Run the handoff gate

make check proves the normal local quality bar before review or push.

5 Escalate when needed

make quality adds mutation testing for final quality boundaries.

6 Report evidence

The agent reports changed files, validation output, unresolved risks, and the next human decision.

Backpressure by design

Backpressure is the product philosophy behind Anvil. It means quality signals are close enough to the agent that they can interrupt the work, force a smaller loop, and keep humans from becoming the first line of defense.

Without Anvil Soft preferences stay in the prompt.

The agent may remember some conventions, miss others, and continue building on top of weak tests, vague TODOs, broad error handling, or unstructured logging until a human reviewer notices.

With Anvil Preferences become executable pressure.

Anti-slop rules, structure checks, test-quality rules, dependency audits, CRAP scoring, and mutation checks reject drift locally and give the agent concrete fixes to make.

Validation tiers

Tier	When it runs	Signals	Why it matters for agents
Fast local	During development	lint, format, typecheck, security	Stops style, type, secret, and obvious anti-slop issues before they spread.
Handoff	Before review or push	test, coverage, deadcode, crap, audit	Checks behavior, maintainability risk, unused code, and vulnerable dependencies.
Final quality	At delivery boundaries	make quality and mutation testing	Tests whether the test suite can detect meaningful code changes.
Recovery	When generated tooling drifts	anvil doctor	Applies safe fixes and reports problems that require a human decision.

Existing-project safety

For existing repositories, Anvil’s safest path is preview-first. anvil init --dry-run renders the scaffold into FsTree and prints the planned creates and updates without writing. Interactive runs ask before overwriting changed files. --non-interactive is explicit opt-in; when conflicts appear, it reports them and writes nothing.

That behavior is especially important for agent-assisted adoption: a coding agent can run the preview, show the planned changes, and stop for a human decision before touching ambiguous files.

What Anvil intentionally does not own

Anvil focuses on the development feedback loop. It does not hide generated files in a managed .anvil/ directory, does not require an anvil update command in v1, and does not ship deployment CI for user projects. The generated make check target is CI-ready, but choosing GitHub Actions, Azure Pipelines, GitLab, Jenkins, or another deployment system remains a project decision.