Metadata-Version: 2.5
Name: anvil-engineering
Version: 0.2.0
Summary: Scaffold and verify an agentic-AI harness-engineering workspace: a master constitution, a 14-role Software Factory agent cell, and layered memory, ready for an autonomous coding agent
Project-URL: Repository, https://github.com/Kemquiros/anvil
Author: Anvil Engineering Contributors
License: MIT License
        
        Copyright (c) 2026 Anvil Engineering Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agentic-engineering,claude-code,harness-engineering,hexagonal-architecture,scaffolding,software-factory,spec-driven-development,tdd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.svg" alt="anvil" width="560">
</p>

<p align="center">
  <a href="https://github.com/Kemquiros/anvil/actions/workflows/ci.yml"><img src="https://github.com/Kemquiros/anvil/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/tests-21-brightgreen" alt="21 tests">
  <a href="https://pypi.org/project/anvil-engineering/"><img src="https://img.shields.io/pypi/v/anvil-engineering" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
</p>

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.

```bash
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`](./INTEGRATIONS.md) for the verified specifics per tool, not just a claim.

---

## Contents

| | |
|---|---|
| [**The four harnesses**](#the-four-harnesses) | test · build · deploy · observability — what each actually guarantees today |
| [**Spec, then TDD**](#spec-then-tdd) | why no code gets written without an approved spec first |
| [**Integrations**](./INTEGRATIONS.md) | Claude Code, OpenCode, Hermes Agent, DeepSeek Harness — what's native, what needs an adapter, what's unconfirmed |
| [**The Software Factory cell**](#the-software-factory-cell) | 14 specialized roles on a fixed spine — contracts frozen before parallel work, serial two-stage review before merge |
| [**Layered memory**](#layered-memory) | episodic · semantic · procedural, and a real lesson it produced |
| [**The `anvil` CLI**](#the-anvil-cli) | `init`, `doctor`, and why templates ship in the package, not the examples |
| [**Four worked examples**](#four-worked-examples) | real code, real numbers, built under this discipline |
| [**What this is (and isn't)**](#what-this-is-and-isnt) | the honest limits |
| [**Development**](#development) | working on `anvil-engineering` itself |

---

## The four harnesses

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

| Harness | What it guarantees | State in this repository |
|---|---|---|
| **Test** | Deterministic, fast, isolated tests, plus a documented catalog of *false-green* patterns to avoid | Real: [`pattern_testing_pitfalls.md`](./.memory/semantic/pattern_testing_pitfalls.md) exists because a test that only proves "it runs" has caused real bugs in this workspace's history, and every example below carries ≥95% coverage against that standard |
| **Build** | Reproducible, cacheable build targets | Real for the `anvil-engineering` package (`pyproject.toml` + `hatchling`); each example project has its own, independently |
| **Deploy** | Rollback-ready, incremental delivery | Real for `anvil-engineering` itself: [`.github/workflows/release.yml`](./.github/workflows/release.yml) gates a PyPI release behind the full test suite and OIDC Trusted Publishing, no token to leak (see [`RELEASING.md`](./RELEASING.md)) — not yet wired for the example projects, which stay demo-only |
| **Observability** | Structured logs, RED metrics, tracing from day zero | **Stated as a principle in `CLAUDE.md`, not yet enforced by any check in this repository.** No example ships tracing. Said here rather than implied, because a harness you don't verify is a claim, not a harness |

`.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/`](./.claude/skills/spec-driven-development/) and
[`.claude/skills/test-driven-development/`](./.claude/skills/test-driven-development/).

## The Software Factory cell

A full development team, modeled as 14 specialized subagents in
[`.claude/agents/`](./.claude/agents/), orchestrated by
[`.claude/skills/software-factory/`](./.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/`](./.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`](./.memory/semantic/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`](./.memory/procedural/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`](./.memory/semantic/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`](./.memory/procedural/workflow_memory_usage.md).

**A concrete lesson this memory produced, not a hypothetical one:**
[`pattern_testing_pitfalls.md`](./.memory/semantic/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

```bash
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`](./.memory/semantic/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/`](./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.

| Project | What it demonstrates | Tests | Coverage |
|---|---|---|---|
| **[ml-fraud-detection](./examples/ml-fraud-detection)** | Hexagonal architecture around ML: 10 classifiers from scratch in NumPy behind one `ModelPort`, ROC-AUC/PR metrics, stratified evaluation, a CLI and a REST API sharing the same use cases | 227 | 98% |
| **[llm-gateway](./examples/llm-gateway)** | A provider-agnostic LLM completion gateway: retry with backoff, TTL caching, a vendor-neutral HTTP adapter — fully offline-testable, no SDK lock-in | 43 | 97% |
| **[fastapi-url-shortener](./examples/fastapi-url-shortener)** | A FastAPI service with a genuinely swappable persistence port (in-memory + SQLite), both verified against one shared contract test | 25 | 98% |
| **[langgraph-research-agent](./examples/langgraph-research-agent)** | A LangGraph research agent with a real, single-graph, bounded guardrail-retry cycle — ports around the chat model/retriever/guardrails, an offline golden-set evaluator, CLI serving, and structured observability logging | 256 | 98% |

**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`):

```bash
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`](./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`](CITATION.cff).

## Further reading

- Kent Beck, *Test-Driven Development: By Example* — the discipline behind [Spec, then TDD](#spec-then-tdd).
- Alistair Cockburn, [Hexagonal Architecture](https://alistaircockburn.com/hexagonal-architecture/) — the pattern every example applies.
- [Conventional Commits](https://www.conventionalcommits.org/) — the commit convention this repository follows.
- Martin Fowler, [Harness Engineering](https://martinfowler.com/articles/harness-engineering.html) — the source of the four-pillar framing above.
- Martin Fowler, [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html) — this workspace's rewrite protocol, in `CLAUDE.md`.

## License

[MIT](./LICENSE) — use this as a starting point for your own agentic engineering workspace.
