This repository is the executable form of AAWD, a methodology for building custom AI agents from substrate to production. Clone it, point a general-purpose coding agent at it, and the agent applies the methodology — the phase discipline, the acceptance criteria, the anti-mandates — because they are loaded as its operating instructions. The methodology stops being a paper you follow and becomes a repository you run.
Works out of the box with Claude Code (reads CLAUDE.md) and
opencode (reads AGENTS.md); any scaffolding that can be told
to read AGENTS.md works the same way — the durable layer is plain markdown.
git clone <this-repo> aawd && cd aawd
# Claude Code
claude "Apply the AAWD methodology: run the P3 phase for a custom agent
that manages examples/notes-platform/notes.sh. P3 only."
# opencode
opencode run "Read AGENTS.md and follow it. Then: run the P3 phase for a
custom agent that manages examples/notes-platform/notes.sh."Or bring the methodology to your own project: from your project's root, tell
your agent to read <path-to-aawd>/AGENTS.md and apply it to your problem.
| Path | What |
|---|---|
| AGENTS.md | The operating instructions — phase routing, artifact conventions, standing rules. Canonical entry point. |
| skills/ | The methodology as skills: the map (aawd.md), the two preconditions (P1 substrate, P2 building blocks), the three practice phases (P3 prototype, P4 ship-as-CLI, P5 agent-tests-agent), and the orchestration corollary. Each skill carries its phase's claim, procedure, acceptance criteria and anti-mandates. |
| templates/ | The phase artifacts as forms: reconnaissance log (P3), Turtle CLI checklist (P4), scenario suite, evaluation report and bug table (P5). |
| examples/notes-platform/ | A self-contained P3 exercise against a deliberately incomplete toy platform. Also this repository's own behavioural test. |
| tools/check.sh | Deterministic structural self-check: routing complete, section contract holds, referenced templates exist. |
Two preconditions are internalised once: the LLM as a software component with
its cached prefix tools → system → messages (P1), and the building-block
vocabulary — function calling, MCP versus CLI, liteshell, the minimal loop,
hooks (P2). The practice is a cycle iterated for the life of the agent:
prototype with a general-purpose agent against the real platform (P3), harvest
and ship the agent as a CLI another agent can drive (P4), and have another
agent test it behaviourally against a scenario suite (P5), whose gap list
feeds the next pass. Multi-agent orchestration falls out as a corollary — an
agent shipped as a CLI is just another tool — rather than requiring a
framework.
This repository is the executable companion of:
Marc Alier Forment, Juanan Pereira, Francisco José García-Peñalvo, María José Casañ Guerrero. Agents All the Way Down: A Methodology for Building Custom AI Agents from Substrate to Production. arXiv:2606.11869.
If you use this repository, cite the paper (a CITATION.cff is provided).
The measurement companion — The Scaffolding Matters More Than the
Interface, an MCP-versus-CLI benchmark across seven scaffoldings and five
models — is pending arXiv announcement; its dataset and harness are archived
at doi:10.5281/zenodo.21851992.
By the paper's authors: Marc Alier Forment (UPC), Juanan Pereira (UPV/EHU), Francisco José García-Peñalvo (USAL), María José Casañ Guerrero (UPC) — the LAMB project team.
Version 0.1 — the skills track the methodology paper currently under review; expect them to move with it. Issues and pull requests about where the skills fail to drive the discipline in practice are the most valuable kind: that is this repository's own P5.
License: GPL-3.0-or-later (see LICENSE).