anvil-engineering 0.2.0

A blacksmith does not trust a blade because it looks sharp. It is struck, quenched, struck again, and only trusted once it has held its shape through the same process every time. This repository does the same for code written by an autonomous coding agent — a master constitution, a 14-role review-and-build cell, and layered memory, so that every change is struck against the same tests, specs, and gates before anyone calls it done.

pip install anvil-engineering
anvil init my-project
cd my-project

Open my-project with an autonomous coding agent. It reads CLAUDE.md first, then .memory/, then INDEX.md — from there it can start a new project, or you can point it at one of the four worked examples in this repository to see the standards already applied to real, tested code. Works with Claude Code natively; OpenCode and DeepSeek Harness load CLAUDE.md with zero config; Hermes Agent picks up the skills directly — see INTEGRATIONS.md for the verified specifics per tool, not just a claim.

Contents

The four harnesses

Four pillars, defined in CLAUDE.md and meant to be enforced on every change. Not all four are equally real yet — stated plainly, not glossed over:

.github/workflows/ci.yml is what actually closes the Test/Build gap for this package: before this release there was no CI in this repository at all — that is the concrete "best practice" this release adds, not an abstract commitment.

Spec, then TDD

No code is written without an approved .md spec first: problem statement, Given/When/Then acceptance criteria, explicit out-of-scope. Implementation then follows strict RED → GREEN → REFACTOR — a failing test before any production code, the minimum code to pass it, then cleanup with the suite green throughout. Every architectural decision with real consequences (a public API, a data model, a dependency swap) gets an ADR in Nygard's format, and every ADR ships with at least one diagram — Mermaid at minimum, the excalidraw MCP server (see INTEGRATIONS.md) when a hand-drawn system map earns its place over another box-and-arrow graph. This is not a suggestion in a docstring: it is why every example below has a docs/specs/ file that predates its src/, and an docs/adr/ directory with the actual reasoning, including the times the original plan changed. See .claude/skills/spec-driven-development/ and .claude/skills/test-driven-development/.

The Software Factory cell

A full development team, modeled as 14 specialized subagents in .claude/agents/, orchestrated by .claude/skills/software-factory/ through a fixed sequential spine, not a free-for-all:

sf-product-manager · sf-project-manager · sf-architect · sf-ai-architect · sf-tech-lead · sf-developer · sf-ml-engineer · sf-qa-engineer · sf-code-reviewer · sf-architecture-reviewer · sf-security-engineer · sf-devops-engineer · sf-sre · sf-refactor-specialist

PdM → Architect → AI Architect (only when the feature has an ML/DL/agentic surface) → Tech Lead, who freezes functional contracts (docs/contracts/<feature>.md, one entry per module) before implementation fans out in parallel across developer agents — the contract is what lets them work in parallel without renegotiating the same interface mid-flight. Testing then also runs in parallel, followed by a serial two-stage review that is never done by a module's own implementer: sf-code-reviewer first (correctness, contract adherence, Clean Code, and whether the tests actually prove what they claim — the implementer is structurally blind to its own blind spots), then sf-architecture-reviewer alone (cross-module consistency, hexagonal-boundary violations, technical debt no single module's reviewer could see). Neither stage's findings are optional before security scanning and merge.

Each role has a defined objective, tool access, and success metric, and self-invokes the reasoning pattern its task calls for from .claude/skills/agentic-reasoning-patterns/ (Tree of Thoughts for an ambiguous architecture call, ReAct for iterative execution, Reflexion after a review finding, and others catalogued there with which situation each actually fits). The distinction from generically prompting an agent to "act as a product manager" is that each role's brief — and the spine connecting them — is versioned alongside the code it governs, reused identically across every project in this workspace, and updated once when a lesson is learned rather than re-explained per session. CLAUDE.md's guiding principle for all of this, stated plainly rather than left implicit: cheap now is expensive later — skipping a spec, a contract, or a review stage to save one agent call doesn't save cost, it moves the cost downstream and compounds it.

Layered memory

.memory/
├── episodic/     # What happened, when, why — append-only
├── semantic/     # What is known — durable patterns and lessons
└── procedural/   # How it's done — executable workflows and checklists

Every project — the ones you start under projects/, and the four already in examples/ — carries the same three layers locally. Root .memory/ holds cross-project lessons: pattern_agentic_decision_ladder.md (when a task actually justifies a multi-agent design, versus a single agent or plain RAG) and catalog_engineering_practices.md (a versioned, single-source-of-truth registry of practices every project references rather than copies), and pattern_cheap_now_expensive_later.md (why the two-stage review and the contract-freezing step exist at all) are three examples. For which layer to write to and how they connect, see workflow_memory_usage.md.

A concrete lesson this memory produced, not a hypothetical one: pattern_testing_pitfalls.md records that a wiring test which reproduces the logic it is meant to guard — instead of importing the real production function — can stay green while the actual bug ships. The fix recorded there: a test only proves what it exercises under mutation. That line exists because it was learned the hard way, once, and is now enforced by re-reading rather than re-discovering it project after project.

The anvil CLI

anvil init [DIR]     # scaffold the Anvil meta-layer into DIR (default: .)
anvil doctor [DIR]   # verify DIR actually has the harness in place
anvil retro [DIR]    # read back DIR's episodic memory — the self-evolution loop, as a command
anvil --version

anvil init is deliberately narrow: it ships CLAUDE.md, the 11 agent briefs, the six core skills, and the real distilled .memory/semantic/ and .memory/procedural/ lessons above — not the four worked examples. Bundling ~1,300 lines of example source and tests into every pip install would be dead weight for the common case (starting a new project), so the examples stay browsable in this repository instead. Every write is idempotent and non-destructive: an existing file is never overwritten, so running anvil init again after you have already edited CLAUDE.md is always safe.

$ anvil init my-project
created  CLAUDE.md
created  .claude/agents/sf-architect.md
...
31 files created, 0 skipped (already existed)

$ anvil doctor my-project
✓ CLAUDE.md present
✓ .claude/agents/ has at least one agent
✓ .memory/episodic/ present
✓ .memory/semantic/ present
✓ .memory/procedural/ present
✓ inside a git repository
all checks passed

anvil doctor is the "agentic engineering best practice" made concrete rather than asserted: a project can check its own agent-readiness — usable as a CI gate in your repository, the same way ci.yml in this one gates on anvil-engineering's own tests. It exits non-zero on any failing check, by design.

Self-evolution, as a command

$ anvil retro .
most recent 5 episodic entries:
  2026-08-30  Retro: What "Hermes Agent" Actually Did — Achievements, Failures, Corrections
  2026-08-30  Brand Identity, `anvil-engineering` PyPI Package, and README Rewrite
  2026-08-29  Three Sophisticated Engineering Demos Built in Parallel
  2026-08-29  Integrated Engineering Learnings from the Private GitHub Hub
  2026-08-28  Project Created: ml-fraud-detection
8 durable lesson(s) in .memory/semantic/, 4 in .memory/procedural/

CLAUDE.md names "Self-Evolve" as a reasoning pattern: when a lesson is learned, write it up and register it, so the next piece of work reads the correction instead of repeating the mistake. anvil retro is that pattern made checkable rather than aspirational — it reads a project's own .memory/episodic/ back, most recent first, and counts how many of those corrections have actually been promoted to a durable .memory/semantic/ or .memory/procedural/ lesson. The transcript above is this repository's own history, not a mockup: pattern_self_evolution_loop.md documents four real corrections from the session that produced this package — a wrong assumption about what "no proprietary content" meant, sandbox-specific setup instructions that nearly shipped as general guidance, a root lint config that nearly rewrote a sibling project it didn't own, and unexplained state that was flagged rather than guessed at — and states the mechanism plainly: a correction that isn't written down at the moment it's found gets rediscovered, at cost, the next time it recurs.

Four worked examples

Independent projects under examples/, each built by this cell from an approved spec through TDD to a green suite — proof the harness works, not just a description of it. Each carries its own spec, ADRs, and three-layer memory.

Receipts, not adjectives. ml-fraud-detection ships a compare-models command that trains all 10 registered classifiers on one identical split and reports this table — reproduced here exactly, not paraphrased:

model                           accuracy  precision   recall       f1  roc_auc  train_s
---------------------------------------------------------------------------------------
logistic_regression               0.9100     0.8378   0.8052   0.8212   0.9526     0.14
neural_network                    0.9067     0.8245   0.8084   0.8164   0.9525     0.70
linear_discriminant_analysis      0.9067     0.8577   0.7630   0.8076   0.9494     0.03
linear_svm                        0.8975     0.8715   0.7045   0.7792   0.9469     0.01
adaboost                          0.8883     0.8295   0.7110   0.7657   0.9441     0.24
decision_tree                     0.8817     0.8168   0.6948   0.7509   0.9118     0.04
random_forest                     0.8750     0.7904   0.6981   0.7414   0.9309     0.35
gaussian_naive_bayes              0.8458     0.7236   0.6461   0.6827   0.9205     0.00
k_nearest_neighbors               0.8625     0.8705   0.5455   0.6707   0.9173     0.00
perceptron                        0.8025     0.6300   0.5584   0.5921   0.8402     0.23

The linear models win because the synthetic fraud signal is itself linear — an honest result, not a flattering one. See that project's own README for why, and for the calibration caveats on Perceptron/SVM/AdaBoost's predict_proba.

What this is (and isn't)

Anvil is a methodology and a scaffolding tool. It is not a guarantee that code built under it is correct, only that it was built against the same explicit, checkable bar every time — the bar itself still has to be right for your problem. The four examples are demos proving the harness produces real, tested, documented code, not production systems: ml-fraud-detection trains on synthetic, hand-authored data (see its own DATA_ARCHITECTURE.md and RISKS.md), several of its models' predict_proba are documented calibration approximations rather than true probabilities, and none of the four examples has authentication, rate limiting, or a compliance review. The Observability harness above is marked "stated, not enforced" on purpose — claiming otherwise would be exactly the kind of overclaim this document exists to avoid.

Development

Working on the anvil-engineering package itself (not an example — those each have their own README.md):

git clone https://github.com/Kemquiros/anvil && cd anvil
pip install -e ".[dev]"

pytest                              # 12 tests
ruff check . && ruff format --check .  # lint
mypy                                 # strict typing

Tests assert behavior a user depends on, not implementation detail: that init is idempotent and never overwrites an edited file, that doctor reports the specific check that failed rather than a generic yes/no, that --version reflects the installed package rather than a hardcoded string.

Releasing is covered separately in RELEASING.md — no tag has been pushed and no PyPI trusted publisher has been registered yet, so pip install anvil-engineering does not resolve until that one-time setup happens.

Repository layout

├── CLAUDE.md              # Master engineering constitution (read this first)
├── INDEX.md                 # Navigation and naming conventions
├── KANBAN.md                 # Cross-project portfolio board
├── CITATION.cff
├── RELEASING.md
├── LICENSE
├── pyproject.toml              # The anvil-engineering package
├── src/anvil/                    # CLI source (cli.py, scaffold.py, doctor.py, templates/)
├── tests/                          # Tests for the CLI, not the examples
├── .github/workflows/                # ci.yml, release.yml
├── .memory/                            # Workspace-level layered memory
├── .claude/
│   ├── agents/                           # Software Factory cell (sf-*.md)
│   └── skills/                             # software-factory, spec-driven-development,
│                                              # test-driven-development, systematic-debugging,
│                                              # gitflow-github-workflow, find-skills
├── examples/                                   # The 4 worked examples above
└── projects/                                     # Where your own projects go once you start one

Citation

anvil: an agentic-AI harness-engineering workspace. Version 0.2.0, 2026. https://github.com/Kemquiros/anvil

See CITATION.cff.

Further reading

• Kent Beck, Test-Driven Development: By Example — the discipline behind Spec, then TDD.
• Alistair Cockburn, Hexagonal Architecture — the pattern every example applies.
• Conventional Commits — the commit convention this repository follows.
• Martin Fowler, Harness Engineering — the source of the four-pillar framing above.
• Martin Fowler, Strangler Fig Pattern — this workspace's rewrite protocol, in CLAUDE.md.

License

MIT — use this as a starting point for your own agentic engineering workspace.