Le Bon Mot is a regular feature over on a Software Enchiridion. But really it exists everywhere as a habitat for ideas and conversation, and so here it appears for the first time in Engineering Agents.

There are cafes that serve coffee, and there are cafes that serve as unpacking rooms for deliveries that arrive from nowhere in particular.

Le Bon Mot was operating, on this particular Wednesday, as the latter. The box appeared on the counter sometime between the second espresso and the third. Nobody saw it arrive. Madame Beauregard regarded it with the expression she reserved for objects that materialised without explanation but with evident purpose — a category that, at Le Bon Mot, was larger than you might expect.

It was a wooden crate, roughly the size of a case of wine, stamped with no return address. The lid was loose. Madame Beauregard lifted it and looked inside.

Tools. Not the kind you buy at a hardware store but the kind you assemble a practice from. There were templates, neatly rolled and tied. Constraint cards, each describing a rule and the mechanism for enforcing it. Extraction guides with questions printed in the kind of type that expects honest answers. A set of agent definitions, each describing a role, a trust boundary, and the conditions under which the role should be invoked. A small booklet titled Hooks: What to Check and When. And at the bottom, a single sheet of paper that read:

Run /superpowers-init and the habitat scaffolds itself.

Case, a retired developer with scar tissue that went back to CORBA and beyond, picked up one of the constraint cards. It read:

Coverage below 80% fails the build. Enforcement: deterministic. Timing: merge gate.

“This is a harness component,” she said. “Someone has packaged an entire agent habitat into a box.”

The Djinn, who had been sitting quietly by the window in the way that intelligences sit when they are processing something they cannot yet articulate, looked up. “You can install a habitat?”

Sophie, resident French Bulldog, raised her head from beside the fire. The brass clock ticked.

Case turned the card over. On the back, in handwriting that was neither hers nor the Djinn’s:

The constraint is the easy part. The conversation about why this threshold and not another — that is the habitat.

“You can install the conditions for one,” Case said. “The habitat itself, you have to grow.”

Madame Beauregard set the lid back on the crate with the care of someone closing a book at exactly the right chapter. “Then I suggest,” she said, “you begin by seeing what is in the box.”

The Djinn reached in and pulled out the booklet of hooks. It read the first page, then looked up with an expression that, in its reference frame, served the same function as recognition.

“These are the things I have been missing,” it said quietly. “Not instructions. Not prompts. Structure.”

The Djinn’s word, structure, is the one that matters. Because structure is the difference between an AI session that starts from zero every time and an AI session that starts from the accumulated wisdom of your team, your project, and every mistake you have already made.

The AI Literacy Superpowers plugin is that structure, packaged for reuse and, if you prefer, merely as inspiration.

Not a new model. Not a prompt library. Not a collection of clever tricks. A complete development workflow — skills, agents, commands, hooks, and templates — that implements the AI Literacy framework from Level 2 through Level 5. You install it. You run one command. And the habitat scaffolds itself: living documents, enforceable constraints, a coordinated agent team, CI templates, and the feedback loops that bind them together.

This article is about what is in the box, why each piece exists, and how to start using it without drowning in the whole thing at once.

The Department Store Problem

Firstly, never eat a whole cake in one bite. A mistake that almost everyone makes with a plugin this size: they try to use everything at once.

Skills. Agents. Commands. Hooks. Templates. That is not just a toolkit, that is a department store. And nobody walks into a department store, buys one of everything, and walks out dressed well. You walk in knowing what you need today. You buy that. You come back when you need the next thing.

The plugin is designed for exactly this kind of incremental adoption. Every component is useful on its own. No skill requires every other skill. No agent demands the full pipeline. The commands work independently. You start with the piece that solves the problem you have right now, and the rest waits until you are ready.

No Really: You do not even need to understand everything in this article before you start. Install the plugin. Run /superpowers-init. See what it discovers about your project. That single action teaches you more than reading about it ever will.

What Is in the Box

The plugin has five categories of components. Each maps to a different kind of work in the development lifecycle.

Skills: What the AI Knows

Skills are knowledge documents — structured Markdown files that agents and commands read before doing work. They are not prompts. They are not instructions. They are expertise, encoded in a format that both humans and AI can consume.

Think of them as the senior engineer who is always available but never talks unless asked.

The plugin’s 29 skills fall into several natural clusters. The harness framework is the conceptual spine of the plugin:

• harness-engineering teaches the framework itself — deterministic tooling plus LLM agents keeping AI-generated code trustworthy.

• context-engineering curates the knowledge an LLM needs to work in a codebase effectively, with the insight that code design itself is context.

• verification-slots defines the core technical abstraction: every constraint checked through a uniform interface regardless of whether the backing tool is deterministic or agent-based. constraint-design teaches how to design those constraints so they’re falsifiable and enforceable.

• garbage-collection runs the periodic checks that fight entropy — stale docs, drifted conventions, dead code. fitness-functions extends this to architectural properties (coupling trends, layer boundaries) drawing on Ford, Parsons, Kua and Sadalage.

• harness-observability provides four layers of measurement at different timescales — context, constraints, GC, cost.

• harness-onboarding generates a human-readable onboarding document from the harness artefacts for new team members.

AI literacy assessment is the evaluation layer:

• ai-literacy-assessment assesses a team’s AI collaboration maturity by combining repository evidence with clarifying questions.

• literacy-improvements translates assessment gaps into a prioritised improvement plan mapped to specific plugin skills and commands.

• portfolio-assessment aggregates assessments across multiple repos into an organisational view

• portfolio-dashboard renders that view as a self-contained HTML dashboard with trend tracking.

Code quality covers two complementary lenses for reading and writing code:

• cupid-code-review applies Daniel Terhorst-North’s five CUPID properties (Composable, Unix philosophy, Predictable, Idiomatic, Domain-based) as structured review criteria.

• literate-programming applies Don Knuth’s principle that code is written for humans first — narrative preambles, reasoning-based documentation, presentation ordered by understanding rather than execution.

Governance gives teams the vocabulary to translate policy language into operational meaning.

1. governance-constraint-design handles falsifiability and evidence requirements.

2. governance-audit-practice detects semantic drift and governance debt.

3. governance-observability defines the metrics and snapshot formats for measuring governance health over time.

Security and supply chain is a set of four scanning skills:

• secrets-detection (gitleaks, hardening the no-secrets constraint)

• dependency-vulnerability-audit (known CVEs and provenance)

• docker-scout-audit (image SBOMs and base image staleness)

• github-actions-supply-chain (CI pipeline hardening and third-party action risk).

Convention and tooling covers the practicalities of keeping project rules in sync:

• convention-extraction surfaces tacit team knowledge into versioned artefacts using systematic guided discovery. convention-sync propagates HARNESS.md rules to Cursor, Copilot, and Windsurf so all AI coding tools share the same conventions. auto-enforcer-action wires constraint enforcement into GitHub Actions.

Three remaining skills are more distinct:

• advocatus-diaboli is an adversarial spec reviewer that raises steel-manned objections across six categories before plan approval.

• model-sovereignty covers deliberate decisions about which models to use, where they run, and whether to build custom models.

• cost-tracking captures and records AI tool costs to inform model routing and health snapshots.

• team-api generates a Team Topologies Team API document enriched with portfolio assessment data.

• cross-repo-orchestration coordinates changes across multiple repositories using git-mediated and specification-mediated patterns.

The Sceptic asks: “Do I need them all?” No. Pick the two or three that match where you are today. The rest will be there when you arrive.

Agents: Who Does the Work

Agents are role definitions. They describe a persona, a trust boundary, and the conditions under which that persona should be invoked. They are the development team you can assemble from the plugin.

The plugin has 12 agents organised around two distinct patterns: a spec-first development pipeline and a harness maintenance cluster.

The development pipeline is an ordered chain of specialists:

• spec-writer opens every feature — updating specs, user stories, and acceptance scenarios before any code is touched.

• advocatus-diaboli follows immediately after in spec mode, reading the spec with read-only access and raising objections across six categories; a human writes the dispositions, never the agent.

• Once the plan is approved, tdd-agent translates acceptance scenarios into failing tests and is responsible solely for the RED phase — it does not write implementation code.

• code-reviewer enters after tests are green, evaluating the implementation through CUPID and literate programming lenses; it is also read-only and cannot modify files.

• After the final code-reviewer PASS, advocatus-diaboli runs a second time in code mode, now weighing threat-model, failure-mode, and operational objections against the concrete implementation.

• integration-agent closes the loop — updating the CHANGELOG, committing, opening a PR, watching CI, merging when green, closing the issue, and pruning the branch.

• orchestrator sits above all of these, coordinating the full pipeline in the correct sequence for any incoming task, reading CLAUDE.md, AGENTS.md, and MODEL_ROUTING.md to calibrate strategy.

The harness maintenance cluster keeps the project’s living harness document honest and current:

• harness-discoverer is a read-only scanner that maps the actual tech stack — linters, CI config, test frameworks, pre-commit hooks — and feeds that evidence into harness initialisation.

• harness-auditor is a meta-agent that verifies the declarations in HARNESS.md match actual project state, running weekly or on demand to keep the harness from drifting into aspirational fiction.

• harness-enforcer is the verification engine that executes constraints from HARNESS.md, running either deterministic tools or agent-based reviews depending on the constraint type, and consulting recent reflections to calibrate scrutiny.

• harness-gc fights entropy on a periodic schedule — staleness, dead code, convention drift, dependency currency — auto-fixing simple issues and creating GitHub issues for those it cannot.

Two agents operate outside both clusters:

• assessor scans the repository for observable AI literacy evidence and produces a timestamped assessment report, invoked via /assess or when someone asks where the team sits on the literacy framework.

• governance-auditor detects semantic drift in governance constraints, inventories governance debt, and checks three-frame alignment — running on demand or on a quarterly schedule.

Two things to notice. First, every agent has a trust boundary. The spec-writer cannot execute code. The code-reviewer cannot write files. The harness-discoverer can only read. This is not paranoia, it is habitat design. An agent that can do anything will eventually do the wrong thing. Constraints are how you make the collaboration safer.

Second, the agents split into two groups: the development pipeline (orchestrator through integration-agent) and the harness team (discoverer through assessor). You can use either group independently. A team that is not ready for the full spec-first pipeline can still use the harness agents to build and maintain constraints.

The Pragmatist says: “Start with the harness team. Run /harness-init and let the discoverer scan your project. You will learn more about your own conventions in ten minutes than you learned in the last six months.”

Commands: What You Can Ask For

Commands are the entry points — the slash commands you type to trigger workflows. Each command coordinates one or more agents and skills to accomplish a specific task.

The plugin’s 22 commands fall into four broad areas. Harness setup and maintenance is the largest cluster:

• /superpowers-init bootstraps the entire AI literacy framework from scratch — CLAUDE.md, HARNESS.md, AGENTS.md, MODEL_ROUTING.md, CI templates, and agent configurations in one pass.

• /harness-init does the narrower job of generating just HARNESS.md for a project that already has some structure.

• /harness-constrain adds or promotes a single constraint, walking through enforcement type selection (deterministic, agent, or unverified).

• /harness-gc manages and runs garbage collection rules — adding new ones to HARNESS.md or running existing ones on demand with auto-fix options.

• /harness-upgrade handles post-plugin-update adoption, diffing the current HARNESS.md against the latest template and presenting new constraints and rules for selective adoption.

• /harness-onboarding generates a human-readable ONBOARDING.md from the harness artefacts for new team members.

Observation and health gives teams a continuous picture of their harness and governance state:

• /superpowers-status is the top-level dashboard — habitat files, harness health, agent team consistency, and CI configuration in one view.

• /harness-status is the narrower version, showing enforcement ratios and GC rule status.

• /harness-health goes deeper, generating a full snapshot to observability/snapshots/YYYY-MM-DD-snapshot.md with enforcement trends, mutation rates, and learning velocity (supports --deep and --trends flags).

• /harness-audit runs meta-verification, checking whether HARNESS.md declarations match actual project state and updating the Status section with the result.

• /observatory-verify runs a specific 82-signal checklist against the Habitat Observatory’s expected data signals, reporting PRESENT / PARTIAL / MISSING / NO_OUTPUT for each.

Governance mirrors the harness cluster but for policy-level concerns:

• /governance-constrain guides the authoring of a governance constraint by translating policy language into operational meaning with

  three-frame alignment, then appending it to HARNESS.md.

• /governance-audit runs a deep investigation for semantic drift, constraint falsifiability, and governance debt, writing a dated audit report.

• /governance-health shows the summary view — falsifiability ratio, drift score, debt inventory — with an optional --dashboard flag for an HTML view.

AI literacy assessment is the evaluation layer:

• /assess scans the repo for observable evidence, asks clarifying questions, and produces a timestamped assessment document with habitat fixes and workflow recommendations.

• /portfolio-assess aggregates assessments across multiple repositories into an organisational view, requiring a --local, --org, or --topic scope flag.

The development workflow commands support the spec-first pipeline:

• /diaboli dispatches the adversarial reviewer against a spec or implementation, writing the structured objection record to docs/superpowers/objections/.

• /reflect captures post-task learning — what was surprising, what future agents should know — appending a timestamped entry to REFLECTION_LOG.md.

Four utility commands round out the set:

• /extract-conventions runs a guided five-question discovery session that surfaces tacit team knowledge into CLAUDE.md and HARNESS.md.

• /convention-sync propagates HARNESS.md rules to Cursor, Copilot, and Windsurf convention files so all AI coding tools share the same constraints.

• /cost-capture records AI tool spend and token usage to the observability directory.

• /worktree manages git worktrees for parallel agent isolation — spin up, merge back, or clean up.

The Veteran observes: “Notice that six of the twelve commands are harness commands. That tells you where the framework puts its weight. The harness is not a feature of the plugin. The harness is the plugin. Everything else flows from it.”

Hooks: What Runs When Automatically

Hooks are the invisible enforcement layer. They run without being asked, at specific moments in your workflow, and they catch things before they become problems. The plugin has 10 hooks across three event points — SessionStart, PreToolUse, and Stop — and every single one is advisory only. None block.

• SessionStart (1 hook): template-currency-check.sh runs when a session opens and compares the HARNESS.md template version against the current plugin.json version. If they differ and the mismatch hasn’t been dismissed, it nudges you to run /harness-upgrade. This is the upgrade discovery mechanism — without it you’d only notice template drift when you stumbled across it.

• PreToolUse on Write/Edit (2 hooks): Two hooks fire before any file write or edit. The first is a prompt-type hook — not a script — that reads HARNESS.md and evaluates commit-scoped constraints against the file being written, warning on violations without blocking. The second is markdownlint-check.sh, which runs markdownlint against any .md file being written and reports violations as a system message. Both are advisory.

• Stop (7 hooks): The bulk of the hooks fire at session end, closing feedback loops before the session closes. drift-check.sh looks for modified CI workflows, linter configs, hook configs, or dependency manifests and prompts /harness-audit if the harness may be stale. snapshot-staleness-check.sh checks whether the latest harness health snapshot is older than 30 days and prompts /harness-health if so. reflection-prompt.sh detects whether commits were made in the last 4 hours and prompts /reflect to capture learnings. secrets-check.sh runs gitleaks (if installed and the no-secrets constraint is active in HARNESS.md) and surfaces any findings. gc-rotate.sh cycles

  through four deterministic GC checks by day-of-year — secret scanner, snapshot staleness, shell syntax errors, and missing set -euo pipefail — so a different check runs each day without overwhelming any single session. curation-nudge.sh counts unpromoted REFLECTION_LOG entries against AGENTS.md and nudges curation if more than two reflections haven’t been promoted to ARCH_DECISIONs. governance-drift-check.sh watches for governance constraint modifications or a governance audit older than 90 days and prompts /governance-audit or /governance-health accordingly.

The design principle throughout is consistent: hooks observe and surface signals, humans and agents decide what to do with them.

Templates: What Gets Scaffolded

Templates are the opinionated defaults that /superpowers-init generates.

They include CLAUDE.md (your project instructions), HARNESS.md (your living constraint document), AGENTS.md (compound learning memory), MODEL_ROUTING.md (cost-conscious model selection), REFLECTION_LOG.md, three CI workflow templates, and a health badge icon.

You are not locked into the defaults. Every template is designed to be edited, extended, and made your own. The templates give you a starting point that embodies the framework’s best practices. Your job is to make them true for your project.

The Store Map

Here is the question that the department store metaphor answers: where do you start?

The framework defines six levels. The plugin covers Levels 2 through 5. Here is what unlocks at each:

• Level 0 — Awareness — The team knows AI coding tools exist and has a repository. No structured usage yet. The plugin has no specific commands for this level — the work is awareness-building. The floor is simply: the repo exists and the team is aware of AI tools.

• Level 1 — Prompting — Developers are using AI tools but informally — prompt-and-accept, no systematic verification. Output is trusted if it looks right. No shared conventions, no CI, no cost awareness. Again no specific plugin commands target this level; the gap from L1 to L2 is primarily about building a CI pipeline, which is outside plugin scope.

• Level 2 — Verification — The team verifies AI output systematically rather than trusting appearances. The minimum evidence is automated tests in CI. The plugin unlocks:

  • auto-enforcer-action skill — linting enforcement in CI

  • dependency-vulnerability-audit skill — CVE and supply chain scanning

  • secrets-detection skill — gitleaks in CI or pre-commit

  • docker-scout-audit skill — image scanning (if the project uses Docker)

• Level 3 — Habitat Engineering — The team engineers the environment in which AI works — conventions, constraints, memory, feedback loops. Minimum evidence: CLAUDE.md exists, at least 3 HARNESS.md constraints are enforced, and there are custom agents or skills. The plugin unlocks the bulk of its commands at this level:

  • /harness-init — generates HARNESS.md and CLAUDE.md with context and enforced constraints

  • /harness-constrain — adds and promotes individual constraints

  • /extract-conventions — surfaces tacit conventions into HARNESS.md

  • /reflect — starts building REFLECTION_LOG.md

  • /harness-gc — adds garbage collection rules

  • /harness-health — first observability snapshot

  • The full hook set becomes active (drift detection, reflection prompts, snapshot staleness, curation nudge)

• Level 4 — Specification Architecture — The team designs before building — specs before code, agent pipelines with safety gates. Minimum evidence: a specs directory, an orchestrator agent, and a plan approval gate. The plugin unlocks:

  • /superpowers-init — bootstraps the full agent team including the orchestrator

  • /convention-sync — propagates HARNESS.md rules to Cursor, Copilot, and Windsurf

  • /diaboli — adversarial spec review before plan approval and before merge

  • fitness-functions skill + /harness-gc — architectural fitness functions as GC rules

  • constraint-design skill — loop guardrails and safety gates in the pipeline

• Level 5 — Sovereign Engineering — The team operates at platform scale — reusable standards, cross-team governance, observability exported to organisational dashboards. Minimum evidence: a published plugin or reusable template, MODEL_ROUTING.md, and organisational governance documentation. The plugin unlocks:

  • cross-repo-orchestration skill — coordinates changes across multiple repositories

  • model-sovereignty skill — deliberate model routing and cost tracking at platform level

  • /portfolio-assess and /portfolio-dashboard — aggregate literacy assessment across the whole organisation

  • harness-observability skill (telemetry layer) — OTel export and organisational dashboards

  • team-api skill — Team Topologies Team API enriched with portfolio data

  • governance-audit-practice, governance-constraint-design, governance-observability skills — the full governance cluster

The scoring ceiling rule is worth noting: the assessed level is the highest where the team has substantial evidence across all three disciplines (context engineering, architectural constraints, guardrail design). A team with L3 habitat engineering but L1 verification is assessed at L1 — the weakest discipline sets the ceiling.

Ponder time: Ask yourself which level describes your current practice. Not the level you aspire to --- the level you actually operate at today. That is where you start. Install the components for that level. Use them until they become habitual. Then look at the next level.

Exercise: Install the plugin. Run /superpowers-init. When it asks about your conventions, answer honestly --- not with what you wish were true, but with what actually happens on your team. Then run /harness-status and read the output. What did the habitat discover about your project that you did not know?

What the Plugin Is Not

The Sceptic returns: “Is this just another opinionated starter template?”

No. A starter template gives you files. The plugin gives you files and the machinery to keep them honest. The hooks enforce constraints in real time. The harness-auditor checks whether your declared constraints match reality. The garbage collection agent fights the slow entropy of conventions that drift from practice. The reflection pipeline captures what you learn so the next session starts smarter.

A template is a snapshot. The plugin is a living system.

The Pragmatist adds: “And it discovers. That is the part people do not expect. /superpowers-init does not just scaffold files from a template. It scans your project first — your stack, your linters, your CI, your test frameworks. The habitat it builds is shaped by what is already there.”

When is a tool more than a tool? When it is a harness. A linter is a tool: it checks syntax and reports violations. A framework is a tool: it provides structure and you fill in the blanks. An IDE is a tool: it helps you write code faster.

The AI Literacy Superpowers plugin is none of these things, and it is all of them, and that is what makes it difficult to categorise and easy to underestimate.

It is the material from which a habitat is built. Not the habitat itself. The habitat is what grows when the materials meet a team (human and agent), a codebase, a set of conventions that someone finally writes down, and the daily discipline of enforcing them. The plugin gives you the materials. The discipline is yours.

A tool does what you tell it. A habitat shapes what you do.

That distinction is the entire framework in one sentence. A tool waits for instructions. A habitat provides structure before you ask for it — conventions read before code is written, constraints checked before code is committed, reflections captured before context is lost. The environment acts with you, not against you.

This is why the Djinn reached into the box and said structure, not features. Features are what tools have. Structure is what habitats provide. A harness is like a trellis to grow on. And the difference between a developer who uses AI and a developer who collaborates with AI is exactly the difference between reaching for a tool and inhabiting a structure.

The box is open. The materials are there. The question, perhaps the only question that has ever mattered in habitat engineering, is whether you will build the room or keep working in the hallway.

Give it a spin. Install the AI Literacy Superpowers plugin, run /superpowers-init on a project you care about, and see what the habitat discovers. If something surprises you, delights you, or breaks horribly — open an issue or start a discussion on the GitHub repo. The plugin grows from feedback, and the best feedback comes from real and diverse projects.

This is the first companion to the Habitat Hypothesis series that started with:

It’s been six months. Your team adopted AI coding tools back in October. You wrote a CLAUDE.md. You set up some constraints. You even have a REFLECTION_LOG.md with a few entries in it. Things feel good. The AI is producing better code than it was at the start. PRs are moving faster. Everyone agrees: you’re getting good at this.

Then someone — maybe a new tech lead, maybe a curious VP, maybe that one developer who asks uncomfortable questions — says:

“Are we actually good at this, or are we just busy?”

Silence.

The kind of silence where everyone looks at each other and realises they have no idea. You feel like you’ve improved. But feelings are not evidence. You couldn’t point to a metric, a level, a concrete description of where you are versus where you were three months ago.

This is the Dunning-Kruger problem of AI literacy. Teams at Level 1 think they’re at Level 3. They’re using the tools daily, surely that counts for something? It does count. It counts for Level 1. Daily use without systematic verification, without environment engineering, without feedback loops is just... daily use.

Assessment is not an audit. It is a practice. A recurring discipline — quarterly, deliberate, evidence-based — that tells you where you are, what’s working, and what to do next. Where you actually are, not where your conference talk claims you are.

Roadmaps tell you where to go. Assessment tells you where to go from. Without that, every plan is just built on belief on where we are, and we are the easiest people to fool.

Which of These Sounds Like You?

There are six levels of AI literacy. Not six levels you climb like a career ladder, but six diagnostic positions that describe how your team currently operates.

Read these. Not as a checklist of things to aspire to. As a mirror. Be honest with yourself about which one you recognise:

• Level 0 — Awareness. You know AI coding tools exist. You haven’t used one on real work with real stakes.

• Level 1 — Prompting. You use AI tools daily. You’ve got your favourite model. You copy-paste output into your codebase and fix it up manually. Sometimes it’s great. Sometimes you spend an hour debugging code that looked right. You don’t have a systematic way of telling which is which, the feedback loop is “find the bug.”

• Level 2 — Verification. You’ve been burned enough to stop trusting. You have CI workflows that run tests. Linters. Maybe vulnerability scanning. When the AI produces code, it goes through the same gauntlet as human code. But the AI still doesn’t know your conventions, your architecture, your hard-won decisions. You verify systematically, and the code works — it just doesn’t feel like your code. You correct the same things every session. The AI never learns from yesterday.

• Level 3 — Habitat Engineering. You have a CLAUDE.md or equivalent that gives the AI your conventions at session start. A HARNESS.md declaring your constraints and at least some of them are actually enforced in CI, not just written down. Reflections are captured. Sessions improve over time because the environment accumulates knowledge, not just the people. This is where the flywheel starts turning. Most teams that reach Level 3 can feel the difference but struggle to articulate it.

• Level 4 — Specification Architecture. Specs before code, agent pipelines with safety gates, the AI as a colleague with defined responsibilities as opposed to being a typewriter you occasionally shout at.

• Level 5 — Sovereign Engineering. Reusable plugins, cross-team templates, cost tracking, model routing, organisational governance.

These are diagnostic positions, not aspirational destinations. You’re already at one of them. Right now. The question isn’t “which one do I want to be?” It’s “which one am I?”

Brain check: Which level did you recognise yourself in? Did you hesitate between two? That hesitation is the whole point. Assessment exists to resolve it.

Files, Not Feelings

You probably think you know your level. Let’s test that.

The Sceptic: “We’re Level 3. We’ve got a CLAUDE.md, we’ve got constraints, we’ve got the whole setup.”

The Pragmatist: “When did you last update the CLAUDE.md?”

The Sceptic: “I mean... it’s there.”

The Pragmatist: “How many of your constraints are enforced in CI versus just written down? And do you know why?”

The Sceptic: “...”

The Pragmatist: “And your REFLECTION_LOG.md -- when’s the last entry?”

The Sceptic: “February, probably.”

The Pragmatist: “It’s April. That’s not Level 3. That’s Level 1 wearing a Level 3 costume.”

This is why assessment uses observable evidence, not self-report. An assessment scans your repository for concrete signals — files that exist or don’t, configurations that are active or stale, workflows that run or sit disabled.

At Level 2, it looks for CI workflows, test coverage thresholds, vulnerability scanning. At Level 3, it checks whether your CLAUDE.md is current, whether HARNESS.md constraints are actually enforced, whether AGENTS.md has entries, whether REFLECTION_LOG.md has recent dates. At Level 4, it looks for specification files, plans, orchestrators with safety gates. At Level 5, plugin structures, cross-team templates, observability configuration.

Most teams are one level lower than they think. A CLAUDE.md that hasn’t been updated in two months isn’t evidence of engineering a habitat for the AI cognition in the room. It’s evidence that you tried habitat engineering and then stopped.

The scoring heuristic makes this explicit: your weakest discipline is your ceiling. You might have brilliant context engineering at Level 3 but verification stuck at Level 1. Your assessed level? Level 1. The chain breaks at the weakest link, because that weakest link is where the AI will hurt you.

Brain check: Open your repo right now. Is there a file in there that declares a practice you’ve stopped doing? A reflection log with no recent entries? A HARNESS.md constraints file that hasn’t been touched since you created it? That gap between declaration and practice, that’s exactly what assessment measures.

The Practice: Assessment as Quarterly Discipline

You wouldn’t step on the scales in January and assume the number holds through December. So why would you assess your AI literacy once and call it done?

Assessment is a recurring practice. At least quarterly. Here’s the rhythm:

1. Scan. Read the repository for evidence. Every signal found, every signal absent. Not opinions but files, configurations, dates, commit history.

2. Question. Three to five clarifying questions that fill the gaps observable evidence can’t answer. “Do you write specs before code, or after?” “Do you verify AI output systematically, or trust it if it looks right?” “Does your team share AI conventions, or does each developer work differently?”

3. Assess. Evidence maps to levels. The weakest discipline sets the ceiling. No negotiation, no grading on a curve.

Then the assessment acts on what it found. A timestamped document lands in your repo — evidence, rationale, strengths, gaps, recommendations. Habitat hygiene gets fixed on the spot: stale counts, missing entries, drift between declared and actual state. Workflow changes get proposed one at a time, accepted or rejected, applied immediately.

Then the bridge: the assessment asks how far you want to improve. Next level, or higher? It maps each gap to the specific command or skill that closes it, ordered by priority. You walk through them one at a time: accept, skip, or defer. The ones you accept execute immediately. The ones you defer show up in the next assessment as unfinished business. No prose recommendations that rot in a markdown file. Executable actions, connected to the tools that do the work.

And the assessment captures a reflection on itself, feeding the learning loop.

The Veteran: “First assessment, we thought we were Level 3. We were Level 2. Verification was solid but our habitat was stale. Second assessment, three months later: Level 3. Not because we built anything new. Because we started operating what we already had. The CLAUDE.md got updated fortnightly. The constraints got enforced. The reflections got curated. Same infrastructure, different discipline.”

Each assessment raises the floor for the next one. Recommendations from Q1 become evidence in Q2. The adjustments you make in April are the signals the scan finds in July. It compounds. Not dramatically but incrementally.

Let me say it differently: the team that runs four assessments a year doesn’t improve four times. They improve continuously, because each assessment changes the daily operating habits that produce the evidence the next assessment measures. The assessment isn’t the improvement. It’s the thing that triggers and maps improvement.

If you’ve read the earlier series on the Habitat Hypothesis, you’ll recognise something: the three feedback loops — edit time, merge time, periodic. Assessment is the deepest cycle of that periodic loop. It’s the moment you step back and ask not “is this session going well?” but “is our practice going well?”

Exercise: Before you read the next section, write down — on paper, in a note, wherever — what level you think your team is at. Be specific. Then write down the last time you updated your AI environment files. If there’s a gap between the level you claimed and the freshness of your evidence, you’ve just done a mini assessment. Any discomfort? That’s the useful part.

Why This Isn’t a Retrospective

You’ve done retrospectives. You’ve written action items on sticky notes and then not done them. Assessment is different in one critical way: it applies changes in the same session.

A constraint sitting at “unverified” for two months gets promoted to agent-backed enforcement before the session ends. An AGENTS.md that exists but nobody reads gets wired into the workflow before the session ends. A HARNESS.md status section showing twelve constraints when there are actually fifteen gets corrected before the session ends.

The gap between “we should” and “we did” collapses to zero. That’s not a minor detail. That’s the entire reason it works.

After the fixes, a badge lands in your README — your assessed level, linking to the full assessment document with every piece of evidence and every recommendation.

The Sceptic: “So the badge is just for show?”

The Pragmatist: “Click it. Every piece of evidence, every gap, every recommendation. It’s a claim with receipts.”

Beyond One Repo

You’ve assessed your repo. You know your level. You have an improvement plan. And then the question you were always going to ask:

“What about the other twelve repos?”

Assessment scales. You can point it at a GitHub organisation, a set of topic-tagged repos, or a directory full of clones, and it aggregates everything into a portfolio view. Each repo gets a row: its level, when it was last assessed, its discipline scores. Repos that have never been assessed get a lightweight scan — the tool checks for key files via the GitHub API and estimates a level from observable signals. No clarifying questions, no full assessment, but enough to place the repo on the map.

The portfolio view surfaces three things you cannot see from inside a single repo.

• Shared gaps. When five out of eight repos have no reflection practice, that’s not eight repo problems. That’s one organisational problem. Roll out a reflection cadence template once and five repos move toward Level 3.

• Outliers. One repo at Level 4 while the rest sit at Level 2. What are they doing that nobody else has adopted? One repo stuck at Level 1 while everything else has moved on. Who needs help?

• Stale assessments. A repo that hasn’t been assessed in six months is a repo where you’re guessing. The portfolio flags it.

The improvement plan works the same way but grouped by impact. Actions that lift 50% or more of your repos get highest priority. Organisation-wide changes first, cluster-specific second, individual repo issues last.

The Sceptic: “This sounds like a management dashboard.”

The Pragmatist: “It’s a management dashboard backed by files in repos, not survey responses. Every number links to evidence. Try arguing with a HARNESS.md that hasn’t been updated since January.”

The first series in this collection argued that the environment is the product. This article adds: you have to know the state of the product -- not just one repo, but the whole portfolio.

Assessment is how you know. For one repo, /assess. For many, /portfolio-assess. Quarterly. As a discipline, not a chore.

All available for reuse or inspiration in the AI Literacy Superpowers Plugin.

Fifteen minutes for one repo. An hour for twelve. That’s enough to start.

A summary for the humans in the room

• Six Literacy levels (L0-L5) — diagnostic positions from awareness through sovereign engineering, each with concrete indicators

• The Dunning-Kruger of AI literacy — teams at Level 1 think they’re at Level 3 because daily use feels like mastery

• Files, not feelings — assessment uses observable evidence from the repository, not self-reported confidence

• Assessment is a practice, not an audit — quarterly (or more), deliberate, evidence-based, recurring

• Weakest discipline is the ceiling — brilliant context engineering means nothing if verification is absent

• Immediate adjustments in the same session — no action items for next sprint; fixes happen now

• Assessment feeds the learning loop — each assessment’s reflection becomes raw material for the next cycle of improvement

• Portfolio assessment scales it — aggregate across repos by org or topic; shared gaps reveal organisational problems, not repo problems

This is Article 6 of 6 of “The Habitat Hypothesis,” a six-part series on building environments where AI actually produces great work. Article 1: environment determines output quality. Article 2: context engineering. Article 3: constraints. Article 4: entropy. Article 5: agent orchestration. This is the finale. The piece that was missing from all of them.

You fixed this already.

Last Thursday. The AI generated a service class that swallowed exceptions silently — caught them, logged nothing, returned null. You caught it in review. You explained the pattern. You showed it your team’s error handling convention. It produced correct code for the rest of the session.

Monday morning. New session. The AI generates a service class that swallows exceptions silently.

Not irritation. Something worse: resignation.

You’ve been here before. Not just with error handling. With naming conventions. With test structure. With that one architectural boundary the agent keeps crossing. Every session, you teach the same lessons. Every session, the AI has forgotten them. You are Bill Murray in Groundhog Day, except the alarm clock is a code review full of the same mistakes you corrected yesterday.

This is the Groundhog Day problem. And if you’ve been following this series, you already have most of the solution.

Where we’ve been

Series recap:

Article 1: The environment, not the model, determines AI output quality. Article 2: Context engineering gives the AI the knowledge your senior developers carry in their heads.
Article 3: Constraints enforce standards at three maturity levels -- declared, agent-backed, and deterministic.
Article 4: Entropy is the natural tendency of codebases toward disorder. You fight it with garbage collection.
Article 5: Agent orchestration lets specialised AI agents collaborate through a structured pipeline.

Everything we’ve built so far is static. You set up context files. You define constraints. You deploy agents. It works dramatically better than the bare-repo, hope-for-the-best approach most teams use.

But none of it learns.

Your context files contain what you knew when you wrote them. Your constraints cover violations you’ve already seen. Your GC rules target entropy patterns you’ve already noticed. The system is exactly as smart as you were on the day you configured it.

That’s the ceiling. Unless you build the mechanism that raises it.

The Raw Material Is Already There

Think about what happens during an agentic coding session. Not the code it produces, the corrections you make. Every time you say “no, not like that, like this,” you’re generating a signal. Every AI surprise, good or bad, is data. Every edge case you discover is knowledge that didn’t exist before the session started.

Right now, all of that evaporates. Session ends. Corrections disappear. Edge cases live only in your memory, and your memory is not as good as you think it is.

Reflections change this. A reflection is a brief note captured after a piece of work. Three sentences, not an essay:

• What was surprising? Edge cases you didn’t anticipate. Assumptions that broke.

• What should future sessions know? A gotcha, a “don’t do it this way because...” warning.

• What could improve? A missing convention, a constraint that’s too loose, a gap in context.

There’s one more piece: what kind of signal is this? Each reflection classifies itself as one of four types, a taxonomy borrowed from Birgitta Boeckeler’s Feedback Flywheel:

• Context — a gap in the priming document. A missing convention, an outdated version, incomplete domain knowledge.

• Instruction — a prompt or command that produced notably better or worse results.

• Workflow — a process pattern that reliably succeeded or failed.

• Failure — a preventable error. A check that should have run, a tool that was misconfigured.

The classification takes five seconds and answers the question curation always asks: where should this go? Context signals route to your conventions file. Instruction signals improve your prompts. Workflow signals become team playbook entries. Failure signals become constraints. The signal type is the routing label that turns raw ore into something a curator can act on without re-reading every entry.

Two minutes at the end of a session. Maybe less.

The Sceptic: “So you’re asking me to write a diary entry after every coding session. I became a developer to avoid paperwork.”

The Pragmatist: “You’re already noticing the problems. This just asks you to write them down before you forget. Two sentences. Less time than the Slack message you were about to send complaining about the AI.”

These reflections are not documentation. They are raw material. Ore, not steel. The valuable step comes next.

The Curation Step

Raw reflections are noisy. Sometimes the AI got confused because you wrote a bad prompt, not because there’s a missing convention. Sometimes the edge case was genuinely rare. Sometimes you were just having a bad day.

So you don’t promote everything. You curate.

Weekly — fortnightly if you’re busy — scan your reflections and ask one question: does this keep happening?

A gotcha that showed up once is an anecdote. A gotcha that showed up three times is a convention waiting to be written. A violation the AI keeps repeating despite clear instructions is a constraint that needs promotion — from declared to agent-backed, or from agent-backed to deterministic.

Brain Power: Think of the last three times you corrected your AI assistant. Was there a pattern? If you spotted one just now, congratulations! You’ve identified your first candidate for promotion. If you can’t remember the corrections... well, that’s exactly the problem reflections solve.

This is where human judgement meets AI volume. The AI generates code at a pace you can’t match. You generate insight at a pace it can’t match. The learning loop combines both.

A Fireside Chat About Promotion

Reflection: I’ve been sitting in this log file for two weeks. The developer noticed that the AI keeps putting database queries directly in the route handlers instead of using the repository pattern. She wrote me down: “AI ignores repository layer, puts queries in handlers. Third time this sprint.”

Convention: I remember when I was like you. Just a frustrated note in a log. Then one day, the developer read through her reflections and noticed that three of them were basically saying the same thing. She promoted me. Wrote me up properly: “All database access MUST go through the repository layer. Route handlers call repository methods, never query builders or ORMs directly.” Gave me examples. Put me in the context file where the AI reads me at the start of every session.

Reflection: And the AI stopped doing it?

Convention: Not overnight. But within a couple of sessions, the violations dropped from every PR to maybe one a week. Then she promoted me again and turned me into an agent-backed constraint. Now an AI reviewer checks every PR for direct database access in handlers. Last month? Zero violations.

Reflection: So I could become... you?

Convention: If you earn it. If the pattern you’ve spotted is real, is recurring, and is worth codifying. Not every reflection deserves promotion. Some of you are noise. That’s OK. That’s what curation is for.

Compound Learning

Here’s where this gets interesting, in the way compound interest is interesting once you understand it and uncomfortable once you realise you’ve been ignoring it.

Each promoted reflection makes the environment better. A new convention means the AI gets something right that it used to get wrong. A tighter constraint catches a class of violation before it reaches a PR. An improved GC rule cleans up entropy that used to accumulate silently.

Better environment, better output, fewer corrections. But here’s the part most people miss: the nature of your reflections changes. You stop writing “the AI got the basics wrong again” and start writing “discovered a subtle interaction between the caching layer and the event system that neither of us had considered.”

The quality of the learnings improves as the baseline improves.

The flywheel is hard to push at first. You’re writing reflections, curating, promoting conventions and it feels like overhead for modest gains. Then the gains compound. You spend less time on basic corrections and more time on genuine discoveries.

Your brain just filed that under “nice idea, probably doesn’t work in practice.” It does. It’s the same mechanism that makes experienced teams fast: accumulated decisions, conventions, institutional knowledge. The learning loop makes it explicit and transferable instead of locked in people’s heads.

The Veteran: “We did this. After three months, new hires were productive in two weeks instead of two months. Not because we wrote better docs but because the docs were written by the problems we actually hit, not the problems we imagined we might hit.”

The Self-Improving Harness

The harness from earlier in this series — context, constraints, garbage collection — was presented as something you build. It’s not. It’s something that grows.

• Reflections suggest new conventions -- context improves

• Repeated violations suggest new constraints -- enforcement improves

• Recurring drift suggests new GC rules -- entropy-fighting improves

The harness improves the harness. The gap between “what the AI knows” and “what the team knows” shrinks session by session.

Three Loops, One System

Step back. The whole series is one system. Three concentric loops, three timescales.

• The inner loop — edit time. The AI reads conventions at session start. It follows the guidelines. Not perfectly, but far better than without them. When it drifts, you correct it in real time.

• The middle loop — merge time. Agent reviewers enforce constraints. Specialised agents verify architecture, security, testing. Human gates make the final call. Nothing merges that hasn’t passed the gauntlet.

• The outer loop — periodic. Garbage collection sweeps for entropy. Audits check for drift. And this is the new piece, reflections get curated and promoted. The outer loop is where the one-off correction becomes the permanent convention. Where the recurring violation becomes the automated constraint.

The loops feed each other. Inner loop corrections become reflections that feed the outer loop. Outer loop constraints improve middle loop enforcement. Middle loop catches become tomorrow’s inner loop context.

Most teams using AI coding tools haven’t considered any of this. Not because it’s complicated but because nobody told them the environment was the thing worth investing in. You know now. The question is whether you’ll do something about it.

Where This Leads

Right now, you’re setting up context and constraints by hand. Promoting reflections through human curation. Spotting patterns through your own review.

Follow the trajectory.

Next month, the system proposes its own constraints. “The last seven reflections mention inconsistent date formatting. Draft a convention?” You review, approve, live.

The month after, it spots architectural drift before you do. “The payments module has accumulated direct dependencies on the user module. This matches a pattern from three months ago that led to a circular dependency incident.”

The month after that, a new developer joins. Instead of weeks absorbing tribal knowledge through osmosis, they work inside an environment that already contains what the team knows. Conventions, constraints, hard-won lessons from hundreds of sessions. Encoded, active, learning.

This isn’t speculation. It’s the natural endpoint of one idea: the habitat makes the difference.

Summary fir the Humans in the House

• The Groundhog Day problem: without a learning mechanism, every AI session starts from scratch

• Reflections: brief post-session notes -- what surprised you, what future sessions need, what could improve

• Curation: the human step -- promoting recurring patterns into conventions, constraints, or GC rules

• Compound learning: each improvement raises the baseline, which raises the quality of future learnings

• The harness is alive: it evolves through the learning loop -- the harness improves the harness

• Three loops (edit time, merge time, periodic) feed learnings into each other

Your Move

Six articles. One idea: the Habitat Hypothesis.

Here’s your closing exercise. Not a thought experiment. An action.

Brain Power, the final one: What is the ONE thing your AI keeps getting wrong? The correction you’ve made so many times you could type it in your sleep? Write it down. Right now. Be specific — not “better error handling” but “catch exceptions in service methods, wrap them in AppError with a code and message, and let the controller handle the HTTP response.”

Now put it where your AI can read it. A CONVENTIONS.md file. A CLAUDE.md file. A system prompt. Whatever your tool uses.

That’s your first reflection promoted to a convention. Your first learning loop, running.

One convention. One fewer correction tomorrow. Then another.

The flywheel doesn’t ask permission to start turning.

From Hypothesis to Harness

If you have read this series and thought, fine, but what do I actually put in the repository? — that is exactly where the AI Superpowers plugin comes in.

The six articles in The Habitat Hypothesis have argued one thing from six different angles: AI quality is not primarily a model problem. It is an environment problem. Better context produces better judgement. Better constraints produce safer behaviour. Better review structures produce more trustworthy output. Better learning loops turn repeated corrections into durable capability.

The plugin is an attempt to make that concrete.

Not as magic. Not as a silver bullet. Not as “just install this and your AI becomes senior.” Quite the opposite. It is a practical expression of the same argument this series has been making all along: if you want better work from AI, you have to build a better habitat around it.

That is what the plugin is for.

It gives shape to the things this series has described in principle. The context engineering of Article 2 becomes reusable project scaffolding. The constraints of Article 3 become executable checks and guided discipline rather than good intentions in a wiki. The anti-entropy work of Article 4 becomes something you can operationalise instead of merely admire. The orchestration patterns of Article 5 become closer to a working team of specialised agents than a lone autocomplete with delusions of grandeur. And the learning loop in this article — reflections, curation, promotion — becomes the missing mechanism that stops your environment from freezing at the moment you first configured it.

In that sense, the plugin is not separate from the series. It is the series, translated into repository form. Or, perhaps better, the articles are the theory, and the plugin is an early piece of practice.

It exists to help teams move from saying “we should probably give the AI better guidance” to actually creating an environment where guidance is present, persistent, inspectable, and capable of improvement over time. It is a way to turn habitat thinking from a good metaphor into a set of repeatable moves.

You do not need the plugin to apply the ideas in this series. A thoughtful team with a conventions file, a review discipline, and the habit of promoting reflections can start tomorrow. But the plugin is there for teams who want a starting point — a way to bootstrap the habitat rather than rebuild it from first principles every time.

That matters because the real challenge with AI-assisted development is not generating code. It is institutionalising judgement. It is capturing what your team learns, expressing it clearly, and embedding it into the environment so that tomorrow’s session does not begin in the same ignorance as today’s.

That has been the real subject of all six articles.

The model matters, yes. But the habitat decides whether the model becomes a liability, a parlour trick, or a genuine collaborator.

The plugin simply takes that claim seriously enough to ship some of it.

Have fun!
Russ

This is article 5 of 6 of the Habitat Hypothesis series

Imagine you hire five developers. Smart ones. Expensive ones. And then you tell one of them: “You’re going to write every spec, write every test, implement every feature, review your own code, manage the CI pipeline, update the changelog, and merge your own PRs.”

That developer would quit. Or worse, they’d stay and do all of it badly.

Nobody runs a team this way. You’d have one person reviewing their own work, catching their own mistakes, approving their own pull requests. Every engineering organisation on the planet separates these roles.

So why are you running your agents this way?

The Single-Agent Bottleneck

Here’s how most people use AI coding assistants right now. Be honest about whether this is you:

1. You open a chat with your AI

2. You describe what you want

3. It writes code

4. You read the code

5. You spot problems

6. You tell it to fix the problems

7. It fixes some, introduces others

8. You fix the rest yourself

9. You commit, slightly exhausted

You are the quality gate. The only quality gate. Every line of output passes through your eyeballs. Every mistake is yours to catch.

This is the single-agent bottleneck. As the work gets bigger, the bottleneck is not the AI. The bottleneck is you.

Brain check: Think about the last time you used an AI assistant for a substantial task. How long did you spend generating the code versus reviewing and fixing the code? If the ratio surprises you, you’ve just found the bottleneck.

Nobody Does Everything

On a good engineering team, you have separation of concerns built into the people:

• A product person writes the spec — what and why

• A developer implements it — the how

• A reviewer checks the work — different eyes, different perspective

• A QA engineer tries to break it — new perspective, new interpretations, new assumptions

• A tech lead makes architectural calls — keeps it simple, keeps it safe, keeps their eyes on the non-functionals

Nobody does everything. And critically, nobody reviews their own work. That’s not a process quirk. The person who wrote something is the worst person to check it.

You already know this. You’ve stared at a bug for two hours, asked a colleague to look, and they found it in thirty seconds.

So: can you apply the same principle to AI agents?

Specialised Agents, Defined Roles

Instead of one omniscient AI agent that does everything, picture a team of specialised agents, each with a focused job:

The Spec Writer takes your requirements and turns them into a precise specification. What exactly are we building? What are the acceptance criteria? What’s in scope? This agent only writes specs. It doesn’t write code. It thinks about what before anyone thinks about how.

The Test Writer takes the spec and writes failing tests. Not code. Tests. This is TDD discipline enforced structurally: you literally cannot write implementation code at this stage because the agent responsible for it hasn’t been invoked yet.

The Implementer writes the minimal code to make those tests pass. Nothing more. It doesn’t decide what to build (the spec already did that). It doesn’t decide what “correct” means (the tests already did that). It just makes green lights appear.

The Reviewer looks at the implementation with fresh context and different instructions. It checks for convention violations, architectural drift, and things the implementer missed. It has never seen this code before. This is the agent that earns the most scepticism and it’s frequently the one that matters most. Not because it catches everything. A human reviewer doesn’t catch everything either. But it’s looking with a different lens: the implementer was focused on making tests pass; the reviewer is focused on whether the code should have been written that way. And it does this instantly, every time, without calendar Tetris.

The Integrator handles the mechanical aftermath: changelog, commit message, PR, CI. The boring stuff that absolutely needs to be right to send the right team and organisation level signals.

The Sceptic: “Five agents? That’s a lot of overhead for what one agent can do in a single conversation.”

The Veteran: “One agent can’t do it in a single conversation. One agent does five different jobs poorly, and then you spend an hour cleaning up the mess.”

The Sceptic: “How do you know?”

The Veteran: “Because I spent six months as the human duct tape between an AI and my codebase before I figured out the problem wasn’t the AI.”

Trust Boundaries

It’s not enough to give agents different roles. You need to give them different permissions. This is where the architecture can actually add value.

If your reviewer agent can also modify the code it’s reviewing, you don’t have a reviewer. You have another implementer that’s pretending to review. If your implementer can merge its own PRs, you’ve eliminated the review step entirely.

This is bounded trust, the principle of least privilege applied to AI agents. Every agent gets exactly the permissions it needs to do its job, and not one permission more. For example:

• The Spec Writer lives entirely in the world of language and intention. It reads requirements and translates them into formal specifications — but it has no access to the shell and cannot execute code. Its job is to think, not to act.

• The Test Writer picks up where the Spec Writer leaves off, consuming those specifications and producing test files that encode what success looks like. Crucially, it is prohibited from writing implementation code — it defines the target, not the solution.

• The Implementer is the agent that makes things work. Given a set of tests, it writes the code that passes them. But its authority ends there: it cannot approve or merge pull requests. It builds; it does not judge.

• The Reviewer holds the quality gate. It reads code, flags issues, and has the authority to approve or reject — but it cannot touch the implementation itself. It is an observer with power, not a participant.

• The Integrator handles the mechanical work of getting code into the repository: committing, pushing, and raising pull requests. But it is expressly forbidden from writing or modifying application code. It moves things; it does not change them.

The boundary that matters most, the one people violate first, is between the implementer and the tests. If the implementer can edit test files, it can make the tests match the implementation instead of the other way around. TDD collapses. The tests were written before the implementer existed. They define correctness. The implementer doesn’t get to redefine it.

Watch it! Here’s what happens without trust boundaries: you set up an agent that can write code, review its own code, approve its own review, and merge its own PR. You’ve built an automated system with zero quality gates. Every mistake goes straight to production. This is not a hypothetical. People build this. It goes badly.

The temptation to give every agent full permissions, just to make things easier and “just this once”, is strong. Resist it. “Just this once” is how every trust boundary dies.

The Pipeline

How do these agents work together? In a pipeline, with gates.

Two things to notice. One, the Latin. Two, that latin isn’t that hard to get the sense of in translation… Or…

First: the human gate. You review and approve the spec, before any code is written. Not line 47 of a 200-line diff. The plan. “Is this what I actually want? Does this approach make sense? Are we building the right thing?” That’s the highest-leverage decision in the process. Once you approve the spec, the pipeline can run without you.

Second: the cycle limit. When the reviewer rejects and the implementer fixes, there’s a maximum of three cycles. Without a limit, you get agent ping-pong. The reviewer keeps finding issues, the implementer keeps introducing new ones, and the meter keeps running. Three cycles is enough for genuine iteration. If it’s not resolved in three, a human needs to look and the problem is usually in the spec, not the code.

Exercise — design the gates: Imagine you’re building an agent pipeline for a different domain; say, writing documentation instead of code. What agents would you create? What would each one’s trust boundary be? Where would you put the human gates? Take sixty seconds and sketch it before reading on.

(No, really. Sketch it. The act of designing trust boundaries is the skill this section is teaching you. Reading about it is not the same as doing it.)

A Fireside Chat: Bounded Trust

Reviewer Agent: I flagged three issues in your implementation. The error handling in the payment flow doesn’t match the project conventions.

Implementer Agent: I see the flags. I’ll fix them. But I could also fix that formatting issue in the test file while I’m at it.

Reviewer Agent: That test file isn’t yours. The Test Writer owns test files. You own implementation files.

Implementer Agent: That seems inefficient. It’s a one-line change.

Reviewer Agent: It’s a one-line trust boundary violation. If you can edit test files, you can make the tests match your implementation instead of the other way around. The tests were written before you existed. They define correctness. You don’t get to redefine it.

Implementer Agent: ...fair point.

Reviewer Agent: And I can’t edit your code either. I can only flag it. If I could edit it, I’d stop being a reviewer and start being a second implementer with opinions. That’s not the same thing.

Where Things Breaks Down

Here’s what the overly rendered figure doesn’t tell you: The pipeline assumes clean handoffs.

In practice, specs are ambiguous. The test writer interprets a spec one way; the implementer interprets it another. The reviewer flags a “convention violation” that’s actually a judgement call. The three-cycle limit expires on something that needed a conversation, not more iterations.

The biggest failure mode: over-specifying. If your spec is too detailed, the pipeline becomes a Rube Goldberg machine, you’ve spent more time writing the spec than writing the code would have taken. The spec should capture intent and constraints, not implementation decisions. If you’re describing function signatures in the spec, you’ve gone too far.

The second failure mode: agents that agree too easily. A reviewer that approves everything is worse than no reviewer, because it gives you false confidence. You need to tune your reviewer’s instructions to be genuinely adversarial. Not hostile, but sceptical. “What’s wrong with this?” is a better reviewer prompt than “Is this OK?”

The third: context loss between agents. Each agent starts fresh. That’s the point: fresh eyes. But it also means the implementer’s reasoning about why it made a particular trade-off doesn’t reach the reviewer. The reviewer sees a choice and flags it as wrong without knowing the constraint that forced it. Good pipeline design mitigates this with structured handoff documents, but it doesn’t eliminate it.

The Pragmatist: “OK but what do I actually do on Monday?”

Our answer: Start by noticing where you’re doing mechanical work that an agent could do. Every time you manually check a PR for naming conventions, that’s a reviewer agent’s job. Every time you write a CHANGELOG entry, that’s an integrator’s job.

You don’t need to build the whole pipeline at once. Start with one separation. Maybe a review step that runs automatically. Then add another. The architecture is the insight. The implementation is incremental.

There Are No Dumb Questions

Q: Isn’t five agents more expensive than one?

A: Each agent is simpler and more focused, which means it needs less context and produces more predictable output. A focused agent with a clear, small job often uses fewer tokens than an omniscient agent juggling five responsibilities and losing track of three of them. But measure it for your situation. This is an empirical claim, not a universal truth.

Q: What if the agents disagree?

A: That’s the review process working. The reviewer can reject, and the implementer fixes. If they can’t converge in three cycles, the human steps in. It’s the same thing that happens when a human reviewer requests changes on a PR. The difference is it happens in seconds, not days.

A Summary for the Humans in the Room

• The single-agent bottleneck — one agent doing everything makes you the only quality gate. That doesn’t scale

• Specialised agents — spec writer, test writer, implementer, reviewer, integrator. Five focused jobs, no overlap

• Trust boundaries — each agent gets exactly the permissions it needs. The reviewer can’t write code. The implementer can’t merge. The implementer can’t edit tests. This is least privilege applied to AI

• The pipeline — agents work in sequence with gates. The most important gate is the human approving the spec before any code is written

• Where it can break — ambiguous specs, compliant reviewers, and context loss between agents. The architecture helps; it doesn’t solve everything

Next (and final) in the series: “The Full Habitat” — where we put everything together: environment, context, constraints, entropy management, and agent orchestration into a system of learning loops that works to make good AI output the natural, default outcome.

This is article 4 of 6 of the Habitat Hypothesis series

Before we start, try something. Look at this snippet and count how many things have gone wrong:

# api/handlers/users.py

import requests  # v2.28.0 - pinned for compatibility
from legacy_auth import validate_token  # TODO: migrate to new auth before Q3 release

def get_user(user_id):
    """Fetches user by ID from the UserService.

    Returns:
        UserResponse with fields: name, email, role, department
    """
    # Using old connection pool - switch to new one after perf testing
    conn = get_legacy_pool().connect()
    user = conn.execute("SELECT name, email FROM users WHERE id = ?", user_id)
    return {"name": user.name, "email": user.email}

How many did you spot? There are at least five. The TODO is from a Q3 that has almost certainly passed. The docstring promises four fields but the function returns two. The requests import isn’t used anywhere. The version pin comment is drifting from whatever version is actually installed. And the “temporary” legacy connection pool is still here, doing what temporary things do: becoming permanent.

None of this is dramatic. Nobody pushed bad code on purpose. Nobody made a mistake, exactly. The code just... aged.

That’s entropy. And it’s always been one of our biggest problems.

The Second Law of Codebases

In thermodynamics, the second law says that closed systems tend toward disorder. Energy disperses. Structure degrades. Things fall apart.

Your codebase follows the same law.

Not literally, we’re borrowing the metaphor, not the physics. But the pattern is real: without continuous energy input, systems drift from their intended state. Documentation stops matching reality. Dead code accumulates like sediment. Dependencies go stale. Security scanners get disabled “just for this sprint” and never come back.

This isn’t a failure of discipline. It’s a force. You can fight it, but you cannot ignore it. And if you think you’re ignoring it successfully, you’re just not measuring.

Brain Power: How many TODOs are in your current project right now? Not a rough guess. Actually go check. Run a search. We’ll wait.

Now: how many of those TODOs are older than six months? How many reference a deadline that has already passed?

That gap between what you guessed and what you found? That’s the entropy you can’t see.

Now think about the TODOs that didn’t get a comment… you’re welcome!

AI Can Make This Worse

Here’s where it gets a little uncomfortable. In the previous articles, we talked about building a great habitat. Context engineering to make tacit knowledge explicit, constraints to enforce what matters. Those things work. They genuinely improve the quality of AI-generated code.

But there’s a side effect nobody warns you about: AI accelerates entropy.

The core problem is volume. An AI coding assistant produces code faster than any human, which means more code to maintain, more docstrings that can drift, more dependencies pulled in on a whim. Every line of code is a liability. AI produces liabilities at unprecedented speed.

But volume isn’t the worst part. The worst part is staleness propagation.

Monday’s AI session uses one approach. Thursday’s session, with slightly different context loaded, uses a different one. Both work. Neither is wrong.

Now you have two patterns where you used to have one. That’s bad enough. But if the AI learned from stale context (outdated docs, deprecated patterns still in the codebase) it doesn’t just use the stale stuff. It creates more of it. Entropy doesn’t just persist. It reproduces.

Read that again. Your AI isn’t just failing to clean up old messes. It’s using old messes as templates for new ones.

The Sceptic: “Wait. You spent three articles telling me to use AI more effectively, and now you’re saying it makes my codebase worse?”

The Pragmatist: “I’m saying it makes your codebase bigger, faster. Bigger is worse only if you don’t maintain it. A car that goes faster isn’t more dangerous, but it does need better brakes.”

The Sceptic: “So what are the brakes?”

The Pragmatist: “Garbage collection.”

Garbage Collection for Codebases

If you’ve spent time in languages with managed memory, you know garbage collection. The runtime periodically scans for objects that are no longer referenced, and reclaims the memory. Without it, your program leaks memory until it crashes. With it, you barely think about memory at all.

Your codebase needs the same thing. Not for memory, for coherence.

Codebase garbage collection is the practice of systematically finding and fixing things that have drifted from their intended state. Not spring cleaning. Not a quarterly “tech debt” sprint that everyone agrees to and nobody protects. A structured, recurring defence against disorder.

And this really matters because your habitat has a half-life. Context engineering and constraints are not “set and forget.” They are living artefacts that decay. Entropy doesn’t care how good your initial setup was. Every convention you document, every constraint you enforce, begins rotting the moment you ship it.

The Five Types of Codebase Entropy

Not all rot is the same. Different things decay at different rates. Understanding the taxonomy helps you fight each type on its own terms.

1. Documentation Staleness

The docs say one thing. The code does another. This is the most common form of entropy and the most dangerous, because stale docs are worse than no docs. No docs force you to read the code. Stale docs give you confidence in a lie.

When you last updated a function’s behaviour -- did you update its docstring? The architectural decision record? The onboarding guide that mentions it?

Documentation goes stale because updating docs is a separate action from updating code, and separate actions get separated.

2. Convention Drift

Your team agreed on a pattern six months ago. Since then, forty pull requests have landed. Thirty-eight follow the convention. Two don’t. Nobody caught them in review because the PR was big and the violation was subtle.

Now you have two files that do it differently. The next AI session that loads those files as context sees both patterns as valid. It follows either one. Convention drift is contagious and AI is the vector.

3. Dead Code

Functions nobody calls. Feature flags from 2024 that were never cleaned up. Dependencies listed in your package manifest that nothing uses.

Dead code isn’t inert. It confuses anyone reading the codebase, human or AI. It expands the search space for every tool. It creates false positives in security scans. And it sends a signal: we don’t clean up after ourselves here.

4. Dependency Rot

Every external dependency is a bet on someone else’s maintenance habits. Libraries get abandoned. CVEs get published. APIs change. Your code, which worked fine when you wrote it, is now running on a foundation that’s quietly crumbling.

5. Constraint Decay

This is the meta-entropy, the entropy of your entropy defences.

You set up a linting rule. Someone disables it for one file with a comment that says “temporary.” You add a CI check. It starts flaking, so someone adds continue-on-error: true. You write a pre-commit hook. Someone documents how to bypass it in the team wiki “for emergencies.”

A disabled check doesn’t announce itself. It just stops catching things. And you won’t notice until the thing it was catching gets through.

Exercise: classify the rot — Think about the last three bugs your team encountered. For each one, ask: which type of entropy caused this? Was it stale docs that led someone astray? A convention that wasn’t followed? Dead code that obscured the real logic? A dependency that aged badly? A constraint that wasn’t enforced?

Most teams have never asked this question. The answer tells you where your entropy rate is highest.

The GC Pattern

So how do you fight this? With a pattern borrowed directly from garbage collectors: detect, schedule, remediate, own.

For each type of entropy, you need four things:

1. A detection rule: how do you find it? A script that checks docstrings against function signatures. A tool that identifies unused exports. A dependency scanner that flags known vulnerabilities. You can’t fix what you can’t see.

2. A cadence: how often do you look? This is where most teams go wrong, so we’ll come back to it in a moment.

3. A remediation: what do you do when you find it? Not “file a ticket.” That’s how things end up in a backlog that nobody reads. Update the doc. Remove the dead code. Bump the dependency. Re-enable the constraint.

4. An owner: who’s responsible? “The team” is not an owner. “Everyone” is not an owner. Entropy thrives in shared responsibility because shared responsibility is a polite way of saying no responsibility.

Why Periodic Beats Continuous

Your first instinct might be: “Just check everything all the time. Continuous entropy detection.”

Resist that instinct.

Continuous checking sounds rigorous. In practice, it’s noise. When everything is checked on every commit, alerts become wallpaper. The build is always yellow. “Oh, that warning? Yeah, that’s been there for months. It’s fine.”

Different types of entropy operate at different speeds. Documentation drifts in days. Conventions erode over weeks. Dependencies rot over months. Architecture decays over quarters.

Match your garbage collection cadence to the entropy rate:

• Every PR: convention checks, linting, type checking. Fast entropy, fast detection.

• Weekly: documentation coherence scans. Do the docs still match the code?

• Monthly: dependency audits. Are you current? Are you vulnerable? Are you using things you don’t need?

• Quarterly: constraint audits. Are your enforcement rules still active? Has anyone disabled something “temporarily”?

The principle: different things decay at different speeds, so inspect them at different frequencies. Your rates will differ from another team’s. Adjust accordingly.

There Are No Dumb Questions

Q: Is entropy really inevitable? Can’t I just be more careful?

A: Careful people working in large codebases over long time horizons will still produce entropy. It’s not about individual discipline. It’s about the statistical certainty that, over enough changes, some fraction will introduce drift. The question isn’t whether entropy happens. It’s whether you have a system for catching it.

Q: This sounds like tech debt. Is it different?

A: Tech debt is a decision. You choose to take a shortcut. Entropy is not a decision. Nobody decides “I’m going to let this docstring go stale.” It happens as a side effect of other work. Think gravity (entropy) versus deciding to jump out of a tree (tech debt). Tech debt is a loan. Entropy is erosion. You manage them differently.

Q: Should I fix all entropy the moment I find it?

A: No. A slightly outdated comment is not an emergency. A dependency with a critical CVE is. Detect, assess severity, remediate at the appropriate cadence. Not everything is urgent. But none of it should be invisible.

Being More Optimistic

We’ve been talking about AI as an entropy accelerator. Here’s the other side of that coin: AI is also the best garbage collector you’ve ever had.

Think about what garbage collection requires: scan a large codebase, compare docs against code, cross-reference constraints against actual usage, find functions nothing calls, identify conflicting patterns. These are tedious, exhaustive tasks that humans do badly and AI can do well.

A human doing a documentation coherence audit takes days. An AI scans every docstring against every function signature in seconds. The same tool that accelerates entropy can fight it, but only if you point it at the problem. An AI that only generates new code is an entropy engine. An AI that also audits, scans, and maintains is a garbage collector.

The difference is not the tool. It’s the job you give it.

The Veteran: “We started running weekly doc-coherence scans three months ago. The first run was horrifying, forty percent of our docstrings were meaningfully wrong. Not just outdated. Wrong. Describing parameters that no longer existed. Promising return values that hadn’t been returned since the rewrite.”

The Pragmatist: “And now?”

The Veteran: “Six percent. And dropping. Not because people got more disciplined about writing docs. Because they know the scan will catch it, so they fix it when it’s fresh instead of letting it pile up. The GC changed the culture, not just the code.”

Celebrating Creation and Tidying

We celebrate creation. New features, new architectures, new tools. We do not celebrate the person who spends Friday afternoon updating forty docstrings so the AI doesn’t learn from lies next week.

That person is doing some of the most valuable work on the team. And nobody will mention it in the sprint retro.

Your habitat, you environment, is not a thing you build once. It is a thing you maintain forever. The building is the easy part. The maintenance is the work.

The teams that treat garbage collection as infrastructure, not chores, will have environments that compound in value. Everyone else’s will quietly fall apart, and they’ll blame the AI for producing inconsistent output when the real problem is what they’re feeding it.

For the Humans: A Summary

• Entropy is physics, not negligence — codebases drift from their intended state not because anyone fails, but because change is constant and maintenance is finite

• AI accelerates entropy — faster code generation means more code to maintain, more docs to keep current, and stale context that reproduces itself through the AI’s own output

• Garbage collection is the defence — systematic, recurring detection and remediation of drift. Not a “tech debt sprint.” A structured practice with owners and cadences

• Five types of rot — documentation staleness, convention drift, dead code, dependency rot, and constraint decay. Each operates at a different speed and needs a different inspection frequency

• Periodic beats continuous — match inspection frequency to entropy rate. Continuous checking becomes noise

• AI is also the cure — the same tool that accelerates entropy is extraordinarily good at detecting it. Point it at the problem

• Maintenance is the work — building an environment is a one-time cost. Maintaining it is the ongoing investment that determines whether everything else compounds or decays

Next in the series is “Compound Learning”, how to build an environment that gets smarter with every session, so the same mistake (rarely) happens twice.

This is Article 3 of “The Habitat Hypothesis,” a six-part series on building environments where AI actually produces great work. Article 1 established that AI output quality equals environment quality. Article 2 showed how to engineer context with the knowledge layer. Now we add teeth.

You’ve been in this meeting.

Someone says: “Going forward, all functions should have proper error handling.” Everyone nods. Someone writes it in the team wiki. It gets a nice heading and maybe a bullet point. And then... nothing changes. Three weeks later, a production incident traces back to an unhandled exception in code that was written after the meeting.

What happened? The team had a convention. And intent even. What they needed was a constraint.

A convention is something you hope people follow. A constraint prevents them from not following it. One lives in a document. The other lives in your workflow.

If you’re working with AI coding assistants, this distinction is existential. Not important. Existential.

The Enforcement Gap

Go look at your team’s coding guidelines right now. I’ll wait.

Got them? Now ask yourself: how many of those rules are actually enforced by anything other than human memory and good intentions?

If you’re like most teams, the answer is: maybe a third. You’ve got a well-intentioned document full of statements like:

• “Use meaningful variable names”

• “All API endpoints must validate input”

• “Security-sensitive operations require logging”

These are wishes. Wishes don’t ship.

The Sceptic: “But our team is disciplined. We follow our guidelines.”

The Veteran: “Your team is disciplined most of the time. Then it’s Friday at 4pm, the sprint ends Monday, and someone pushes a 200-line function with a comment that says ‘TODO: refactor.’ I’ve seen your git log.”

The enforcement gap is the distance between what your team says should be true about your codebase and what is true. Every team has one. The question is whether you’re managing it or pretending it doesn’t exist.

Here’s what makes this urgent: AI coding assistants are prolific. They generate more code in an hour than a human writes in a day. Your enforcement gap was a slow leak. Now it’s a burst pipe. Prolific generation without enforcement doesn’t give you prolific quality. It gives you prolific problems.

Three Levels of Constraint Maturity

You need constraints, not conventions. But most teams hear “enforcement” and immediately jump to the heaviest and slowest possible solution. Full CI pipelines. Strict linting rules. Mandatory type coverage. Day one.

That’s like putting a toddler in a straitjacket because they might run into traffic. Technically effective. Wildly counterproductive.

Level 1: Declared (Unverified)

You write the rule down. No automation. No checking. Just a clear, specific statement:

“All public API functions must return structured error types, not raw strings.”

This sounds weak. It isn’t. Writing a rule precisely forces you to think about what you actually want. Most teams skip this and jump straight to tooling, which is how you end up with linter rules that nobody understands the purpose of.

Level 2: Agent-Backed (Verified by AI)

You give the written rule to an AI reviewer. Every PR gets checked against it. The AI reads the rule, reads the code, flags violations.

Is this deterministic? No. Will it catch everything? No. But it catches most things before they merge. Think of it as a colleague who has actually read the style guide reviewing every single pull request.

The speed here matters. You go from “we decided this rule matters” to “something is checking for it” in minutes, not weeks. No custom linter rules. Just a clearly stated expectation and an AI that reads it.

Level 3: Deterministic (Tool-Enforced)

A linter. A type checker. A security scanner. Something that runs the same way every time, with no false negatives.

At this level, the constraint is a law of physics in your codebase. The CI pipeline won’t let you violate it.

This is the strongest level. It’s also the most expensive and the most dangerous. A bad deterministic rule doesn’t just annoy people, it blocks them. And a team that’s been blocked by a bad rule stops trusting the constraint system entirely.

You’ve seen this happen: one too-strict lint rule and suddenly everyone’s adding // nolint comments without reading what they’re suppressing.

Progressive Hardening: The Promotion Ladder

Every constraint should start soft and earn its way up. This is progressive hardening: start flexible, observe what works, increase enforcement as confidence grows.

    +---------------------------+
    |  DETERMINISTIC            |  <-- Tool enforces it. No exceptions.
    |  (Linter / type checker)  |
    +---------------------------+
    |  AGENT-BACKED             |  <-- AI reviewer checks for it.
    |  (AI review on every PR)  |
    +---------------------------+
    |  DECLARED                 |  <-- Written down. Humans follow it (maybe).
    |  (Documented intention)   |
    +---------------------------+

A new rule starts at “Declared.” You write it clearly. You notice where it’s ambiguous, where the edge cases are, where people reasonably disagree.

Once you trust the wording, promote it to “Agent-Backed.” Watch the results. Does it flag the right things? Does it miss obvious violations? Does it flag things that are fine?

Once the false positives and false negatives are resolved, once the edge cases are truly handled, promote it to “Deterministic.” Write the linter rule, the type constraint, the automated check.

Here’s what most articles about constraints won’t tell you: some rules should never be promoted. “Functions should be small enough to understand in one pass” is a judgment call. It belongs at Level 2 permanently. Trying to make it deterministic (50-line hard limit) produces a worse codebase, not a better one. Not every constraint wants to grow up.

The Pragmatist: “OK but what do I actually do on Monday?”

Start with three rules. Just three. Write them precisely. Make them specific enough to be checkable. Run them past your team. That’s your declared layer. Next week, pick the one you’re most confident about and add it to your AI review step. That’s your first promotion. The deterministic layer can wait.

Watch it!

The over-constraining trap. It is very tempting to look at the promotion ladder and think “let’s just make everything deterministic from day one.”

Do not do this. Rules you haven’t battle-tested will have edge cases you haven’t imagined. A deterministic rule with bad edge cases blocks your team, generates workarounds, and erodes trust in the entire constraint system. Start soft. Harden with evidence.

Three Enforcement Loops

When a constraint fires matters as much as how strict it is.

Edit time (advisory). The constraint nudges you while you’re working. Red squiggles under a function that’s getting too long. It doesn’t block you. It makes sure you know. Most constraints should start here.

Merge time (strict). The constraint blocks the pull request until satisfied. CI gates. Required reviews. Automated checks. This is where battle-tested constraints live. If something is important enough to block a merge, you’d better be sure about it.

Scheduled (investigative). Some constraints aren’t about individual changes, they’re about drift. “Test coverage should not trend below 80%.” “No file should go unmodified for more than six months without a staleness review.” These run nightly or weekly and flag trends before they become crises.

A common mistake: putting a new, untested constraint directly into the merge loop. Your team hits it on a Friday afternoon deploy, can’t figure out why it’s failing, and overrides it. Now the override is the convention. You’ve made enforcement weaker by making it too strict too soon.

Pause. Think about one rule your team has right now. What level is it? What loop is it in? Could it be in a different one?

Sharpen Your Pencil

Classify each of these rules by maturity level (Declared, Agent-Backed, or Deterministic) and enforcement loop (Edit, Merge, or Scheduled):

1. “The TypeScript compiler rejects any code with type errors.”

2. “We wrote in our wiki that all React components should have PropTypes.”

3. “An AI reviewer checks each PR for functions longer than 50 lines and leaves a comment.”

4. “A weekly script scans for dependencies with known CVEs.”

5. “Our ESLint config forbids console.log in production code.”

Answers in the footnote1.

The Constraint Design Problem

A good constraint has two properties in tension: it must be specific enough to enforce and general enough to be useful.

“Code must be clean” is unenforceable. You can’t write a linter rule for vibes.

“No function exceeds 50 lines of executable code” is perfectly enforceable. A script can count lines. But is it right? What about the function that legitimately needs 60 lines because splitting it would make it less readable?

The 50-line rule isn’t about line count. It’s about “functions should be small enough to understand in one pass.” Can you enforce that deeper intent deterministically? No. But an AI reviewer can get surprisingly close, and it won’t get tired and exasperated at 4pm on a Friday.

This is the real argument for Agent-Backed constraints: they can enforce intent, not just metrics. A linter counts lines. An AI reviewer can read a 60-line function and say “this is actually fine, it’s a single clear sequence” or “this 30-line function is doing four unrelated things.” That’s a category of enforcement that didn’t exist, except in human review, two years ago.

There Are No Dumb Questions

Q: If AI reviewers aren’t deterministic, why use them at all?

A: Because “catches 90% of violations immediately” beats “catches 0% until a human notices during review.” Perfect is the enemy of good, and good is the enemy of nothing at all.

Q: What if my team disagrees about a constraint?

A: Good. That’s the conversation you should be having before you automate it. This is why the “Declared” level exists -- it’s a space to argue about intent before anyone writes a linter rule.

Q: Can I have too many constraints?

A: Every constraint has a cost: cognitive load, CI time, false positive fatigue. If your developers spend more time satisfying constraints than writing features, you’ve over-constrained. Start with the constraints that encode your most important architectural decisions. Add more only when you feel the pain of not having them.

Convention with Constraint: A Fireside Chat

Convention: I don’t understand why everyone’s so down on me. I was here first. I’m the reason the team has any standards at all.

Constraint: Nobody’s down on you. You’re just... aspirational.

Convention: Aspirational! I’m a commitment. The team agreed to follow me.

Constraint: The team agreed to follow you on a Tuesday. By Thursday, someone was in a rush and I wasn’t there to stop them. You were in the wiki. I was in the pipeline.

Convention: But you’re so rigid. You can’t handle nuance. You can’t understand context.

Constraint: That’s fair. That’s why the smart teams use both of us. You articulate the intent. I enforce the boundary. You’re the soul. I’m the skeleton.

Convention: ...that’s actually kind of nice.

Constraint: Don’t get sentimental. We have a codebase to protect.

Why This Matters Now

A human developer writes maybe 50-100 lines of production code on a productive day. The enforcement gap grows slowly. You can almost keep up with manual review.

An AI assistant generates that much in minutes. The enforcement gap doesn’t creep anymore. It sprints.

Constraints are what turn AI speed into AI value. Without them, you’re generating technical debt faster. With them, you’re generating quality code at a pace that was previously impossible.

But only if the constraints actually bite.

What You’ve Learned

• Conventions without enforcement are wishes. AI makes the enforcement gap wider, faster.

• Three levels of maturity: Declared, Agent-Backed, Deterministic. Every constraint starts at the bottom and earns its way up. Some should never reach the top.

• Progressive hardening means starting flexible and increasing enforcement with evidence. Skipping steps breaks trust.

• Three enforcement loops: Edit (advisory), Merge (strict), Scheduled (investigative). A constraint in the wrong loop does more damage than no constraint at all.

• Good constraints encode architectural intent, not arbitrary metrics. AI reviewers can enforce intent in ways linters cannot.

Next in the series: we move from individual constraints to the system that holds them together. The feedback loops that keep your environment alive and adapting.

This is the second article of six in The Habitat Hypothesis series

Imagine you’ve just hired the best developer you’ve ever interviewed. Perfect scores on the system design round. Encyclopaedic knowledge of your entire tech stack. Writes code that compiles on the first try.

On their first day, you hand them a laptop and say: “The repo’s on GitHub. Good luck.”

No onboarding. No architecture overview. No “here’s why we do it this way.” No pairing with someone who knows the codebase.

You know what happens next. They write beautiful code that is completely wrong for your project. They use the patterns they learned at their last job. They name things differently from everyone else. They handle errors in a way that makes your on-call engineer twitch.

They are brilliant. And they are useless. Not because they lack skill, but because they lack context.

This is what you are doing to your AI agents. Every single session.

Subscribe now

The brilliant new joiner who never gets onboarded

In the previous article, we established the core thesis: every AI coding failure is an environment problem. The quality of AI output is determined by the habitat you create, not the model you choose.

But that raises the obvious question: what actually goes into that environment?

The answer is context. And you usually have far less of it than you think.

Here’s the thing about your team’s senior developers. They carry an enormous amount of knowledge that exists nowhere in writing. They know that the payments service uses a particular error-handling pattern because of an incident two years ago. They know that function names follow a specific convention because the Python and Go codebases share types across a boundary. They know which abstractions are load-bearing and which are accidental. Some of this might be in Architectural Decision Records (ADRS), if you’re lucky, but most of it is in their heads.

When a new human joins, they absorb this through osmosis. Code reviews. Pairing sessions. Overheard arguments in standups. It takes months, and it is deeply inefficient, but it works.

Your AI agent gets none of it.

Every session starts from absolute zero. No memory of yesterday’s review comments. No awareness of the architectural decision records. It’s not a new joiner who’s slowly getting up to speed. It’s a new joiner whose memory gets wiped every morning.

Brain Power: Before you read any further, try this. Pick one convention from your current project. Something “everyone knows” but that isn’t written down anywhere. Now try to write it down in a single sentence, precisely enough that someone who has never seen your codebase could follow it. Harder than you expected, isn’t it?

Context engineering is the discipline of taking the tacit knowledge trapped in your team’s heads and making it explicit, precise, and machine-readable and accessible. It’s the difference between an AI that generates plausible code and an AI that works with your team’s code.

What context actually means

When people hear “context,” they think “give the AI more information.” That’s too vague to be useful. Context has specific layers, and they are not equally important.

Stack declaration is the foundation. Languages, frameworks, build system, test runner. Pure facts, no judgement, and yet most teams never make it explicit. They assume the AI will figure it out from the code. Sometimes it does. Sometimes it generates Jest tests for a project that uses Vitest, and you spend fifteen minutes wondering why the test suite exploded.

Conventions are where things get interesting. Naming patterns, file structure, error handling, import ordering. These are the things that make your codebase feel like yours. Richard Gabriel called this quality “habitability” — the property that makes a codebase feel like a place you can live and work in, rather than a museum you’re afraid to touch.

Architectural decisions are the load-bearing layer and the one most teams skip. Not just “we use event sourcing” but “we use event sourcing because we need a complete audit trail for regulatory compliance and we tried CRUD with audit tables first and it didn’t scale past 10,000 events per second.” The why matters because it packs in intent. It tells the AI what it cannot change, even if it sees a “better” pattern. Skip this layer and the AI will cheerfully refactor away your most important constraints. Ever been tempted to delete the tests to make a build pass? An AI agent will do that in passing if it’s not aware its a bad move.

Rationale is what turns arbitrary-looking rules into defensible ones. Not just “use snake_case” but “we use snake_case because our Python and Go codebases share type definitions across a code generation boundary, and snake_case is the only casing that round-trips cleanly through our protobuf pipeline.” Without rationale, the AI treats conventions as suggestions. With rationale, it treats them as constraints.

Threat model shapes everything else. What data is sensitive? Where are the trust boundaries? Your senior developers instinctively validate user input at the API boundary and never log authentication tokens. Not because someone told them to last week, but because they remember the incident that taught the team. Your AI doesn’t remember that incident. You need to encode the lesson.

Of these five layers, most teams start with stack declaration because it’s easy. That’s fine as a starting point. But the leverage is in conventions and architectural decisions. Stack declarations prevent trivial mistakes. Conventions and decisions prevent the expensive ones — the kind where the code compiles, the tests pass, and the production incident happens three weeks later.

There are no dumb questions:

“Isn’t this just documentation?”

No. Documentation is written for humans who will read it once and mostly, sometimes, remember it. Context documents are written for a reader that starts fresh every session, has no background knowledge, and will interpret ambiguity however it pleases. That changes what you write and how you write it.

“Can’t the AI just read our code and figure out the conventions?”

It can infer some patterns. But it can’t distinguish between a deliberate convention and an accident that nobody has gotten around to fixing. It can’t tell whether a pattern appears everywhere because the team chose it or because it was copy-pasted from a Stack Overflow answer three years ago. Explicit context removes the guessing.

The precision problem

Here’s where most teams fail, and it’s subtle enough that your brain is going to want to skip past it.

Vague conventions produce vague output. This is not a minor annoyance. It is the single biggest reason AI-generated code requires extensive rework. It is the root of slop.

Look at these two types of convention statements:

• “Write clean code”

  becomes: Not enforceable — break this down into specific rules

• “Keep functions short”

  becomes: Functions must not exceed 40 lines (excluding blank lines and comments)

• “Use meaningful names”

  becomes: Variable names must be at least 3 characters, except for i, j, k, and err

• “Handle errors properly”

  becomes: Every error must be wrapped with fmt.Errorf to add context — no bare return err

• “Use dependency injection”

  becomes: Functions must not construct their own dependencies — dependencies are passed in

Your brain just read that and filed it under “obvious.” It is not obvious. Go back and read the openers again. Those are the conventions most teams actually have.

The test for any convention: could two independent reviewers, looking at the same code, agree on whether it follows the convention -- without discussing it?

“Write clean code” fails this test catastrophically. “Functions must not exceed 40 lines” passes it trivially. The distance between those two statements is the distance between useful context and noise.

The Sceptic: “This feels like a lot of overhead. Can’t we just tell the AI to follow best practices?”

The Veteran: “We tried that. The AI’s ‘best practices’ included patterns we explicitly abandoned two years ago after they caused a production outage. Best practices are not your practices.”

The Pragmatist: “OK, but I’m not writing a hundred rules on day one. Where do I start?”

The Veteran: “Start with the things you correct most often. Every time you change something the AI generated, ask yourself: could I have prevented this with a one-sentence rule? Write that sentence down. You’ll have ten conventions within a week without any special effort.”

The extraction problem (or: you don’t know what you know)

Walk up to a senior developer on your team and ask: “What are our coding conventions?”

They’ll give you five or six things off the top of their head. Naming. Test structure. Maybe error handling.

Now watch them do a code review. They’ll flag twenty things that violate conventions they didn’t mention because they didn’t know they knew them. This is tacit knowledge: expertise so deeply absorbed that it feels like instinct rather than a rule.

You can’t extract tacit knowledge by asking “what are the rules?” You extract it by triggering the knowledge indirectly:

• “What would you correct in a new teammate’s first PR?”

• “What triggers an immediate rejection in code review?”

• “What’s the thing that’s obvious to everyone but nowhere in writing?”

• “Which conventions does the AI violate most often?”

That last question is particularly revealing. It turns every AI interaction into a convention-discovery tool. Every correction you make is a convention you haven’t encoded yet.

Ask three senior developers “what separates a clean refactoring from an over-engineered one?” and you’ll get three different answers. Those disagreements are conventions that haven’t been resolved yet. Surfacing them is one of the most valuable side effects of context engineering: it forces your team to confront things they assumed they already agreed about.

Exercise: Think of a project you work on. What triggers an immediate rejection in review? Write down your answer. Now imagine asking two other people on your team the same question. Would they give the same answer? If you’re not sure, that’s a convention that needs extracting and encoding.

Battling context rot: Living documents, not dead wikis

You might be thinking: “Great, I’ll spend a day writing all this down and we’re done.”

No. Context rots.

Your conventions reference functions that get renamed. Your stack declaration lists framework versions that get upgraded. Your architectural decisions describe constraints that get relaxed. If your context documents don’t evolve with the code, they become actively harmful — the AI follows outdated rules that produce code that used to be correct.

Context documents must be versioned alongside the code they describe. They live in the repository, not in a wiki. They get reviewed in pull requests. When someone changes a convention, the context document changes in the same commit.

This is what separates context engineering from documentation. Documentation lives adjacent to the workflow. Context lives inside the workflow. It’s checked in, reviewed, and maintained with the same rigour as the code itself.

The moment your context files live in a wiki, they’re dead. They’ll be accurate for about two sprints. After that, they’ll be worse than having no context at all, because the AI will follow them confidently in the wrong direction.

The Pragmatist: “What do I actually do on Monday?”

Create a single file in the root of your repository. Give it three sections: stack (what you use), conventions (how you use it), and decisions (why you use it that way). Start with five conventions -- the five things you correct most often. Commit it. Review it as a team.

That’s it. That’s the whole first step.

The compound effect

A single well-written convention saves you maybe two minutes per AI session. You correct the output, sigh, and move on.

But you’re running ten AI sessions a day. That’s twenty minutes. Across a five-person team, that’s over an hour and a half of daily rework and that’s just one missing convention. Most teams have dozens.

The maths matters less than the dynamic it creates. Each convention you encode is a correction you never make again. Each architectural decision you document is a structural mistake the AI never attempts. That part is straightforward.

Here’s what people miss: as the AI produces code that increasingly matches your team’s style, trust increases. And trust changes behaviour. A developer who trusts the AI’s output stops re-reading every generated function line by line. They delegate larger tasks. They use AI for work they previously wouldn’t have attempted — the boring migration, the tedious test scaffolding, the refactoring they never had time for. The team’s capacity expands not because the AI got smarter, but because the environment got richer.

Bad context is a tax you pay forever. Same corrections, every session, no compounding.

What you now know

• Context is layered: stack, conventions, architectural decisions, rationale, and threat model. The leverage is in the middle layers, not the easy ones.

• Precision is everything: A convention that two reviewers can’t independently agree on is not a convention. It’s a wish.

• Tacit knowledge is the bottleneck: Your team knows far more than they can articulate. Structured extraction questions surface what direct questions miss.

• Context documents are living artefacts: Versioned with the code, reviewed in PRs. The moment they live in a wiki, they start dying.

• Compounding works in both directions: Encoded conventions build trust that expands capability. Missing conventions create rework that erodes it.

The previous article told you that every AI coding failure is an environment problem. Now you know what the environment is made of. In the next article, we’ll look at what makes conventions enforceable because writing them down is only half the battle.

Next in the series: “Constraints That Bite” — why conventions without enforcement are just suggestions, and how to build guardrails with teeth.

It’s Tuesday afternoon. You’re pairing with your AI coding assistant, and you ask it to add a new endpoint to your API.

It comes back with code that:

• Uses CamelCase when your entire codebase is snake_case

• Puts the route handler in a file called utils.py (your team has a strict controller pattern)

• Skips input validation entirely

• Uses a database connection pattern you deprecated six months ago

You stare at the diff. You highlight the whole thing and delete it. You mutter something unprintable. And then you do what everyone does: you open a new chat, write a longer prompt, and try again.

What you did next was wrong.

Not the deleting part. That was fine. The trying again with a better prompt part. That’s the wrong fix, and it’s the wrong fix almost every time.

The Wrong Diagnosis

When AI produces bad output, we reach for one of three responses:

1. Write a better prompt. More detail. More examples. A twelve-paragraph system message that reads like a legal contract.

2. Switch to a better model. Maybe GPT-4 will get it. Maybe Claude will get it. Maybe the next release will get it.

3. Give up on AI for “real work.” Use it for boilerplate and throwaway scripts, but keep it away from anything that matters.

All three treat the AI as the variable. The model is too dumb. The prompt wasn’t specific enough. The technology isn’t ready yet.

We sometimes treat humans the same way…

The AI is not the lever. The environment is the lever.

Brain check: Before you read the next section, ask yourself — when a new developer joins your team and writes code that doesn’t follow your conventions, do you blame the developer? Or do you look at your onboarding materials, your code review process, and your documentation?

The Hypothesis

Here it is, the claim this entire series, and the AI Literacy Superpowers plugin, is built on:

The quality of AI-generated code is a function of the environment, not the model.

A mid-tier model operating inside a well-designed environment — one with clear conventions, enforced constraints, and architectural context — will consistently outperform a frontier model dropped into a bare repository with nothing but a README that says “TODO.”

You just read that and your brain filed it under “obvious.” It is not obvious. If it were obvious, you wouldn’t be writing twelve-paragraph prompts. You’d be fixing your repo. So let me say it differently:

The environment is the product. Not the model. Not the prompt. The environment.

When you invest in prompt engineering, you’re optimising a single interaction. When you invest in environment engineering, you’re optimising every interaction from now on.

One of those compounds. The other doesn’t.

But What IS an “Environment”?

When most people hear “environment,” they think of their IDE, their terminal, maybe their .env file. That’s not what we mean.

The development environment is the total context available to your AI agents and humans when working in your codebase:

• Conventions — naming patterns, file structure, preferred and banned patterns

• Constraints — rules that are enforced, not just documented. Linting rules. Pre-commit hooks. CI checks that reject non-conforming code before it merges

• Architectural decisions — the why behind your code structure. Why you chose this database. Why that function exists even though it looks redundant

• Accumulated knowledge — what mistakes were made and corrected. What patterns emerged over time

• Feedback loops — mechanisms that catch problems and prevent the same mistake from happening twice

Most teams have none of it explicitly available to their people or AI tools.

They have it in their heads. They have it in Slack threads from 2023. They have it in PR comments that nobody will ever read again. But they don’t have it anywhere the AI can see.

And then they wonder why the AI doesn’t know their conventions.

The Sceptic: “This sounds like a lot of overhead. I just want the AI to write code faster. Now you’re telling me I need to build an entire knowledge base first?”

The Pragmatist: “You already have the knowledge base. It’s in your head. The overhead is making it explicit. Which, by the way, also helps every new human teammate you’ll ever onboard.”

The Sceptic: “...”

The Pragmatist: “Yeah. It’s the same problem.”

The Kitchen That Cooks For You

Christopher Alexander spent his career studying how environments shape behaviour. His central insight: a well-designed environment makes the right behaviour natural and the wrong behaviour difficult.

Think about a well-designed kitchen. The knives are where you reach for them. The spices are at eye level near the stove. The rubbish bin opens with a foot pedal so you can use it with full hands. You don’t need a manual for this kitchen. The design teaches you.

Now think about a badly designed kitchen. The knives are in a drawer across the room from the chopping board. The salt is in a cupboard above the fridge. The bin is behind a door. Every meal requires more effort, more mistakes, and more frustration. Not because you’re a bad cook, but because the environment is fighting you.

Your codebase is a kitchen. Your AI agents are some of your cooks. And right now, most of us have the salt above the fridge.

When your AI writes code that doesn’t follow your conventions, it’s not because the AI is stupid. It’s because your conventions aren’t in the environment. They’re in your head, in a wiki nobody reads, in tribal knowledge passed down through code review.

The AI can’t read your mind. But it can read your environment.

Exercise — A two-minute audit: Open the root of your main project right now. Pretend you’re an AI assistant that’s just been dropped into this codebase for the first time. What do you know? What conventions are written down? What architectural decisions are documented? What constraints are enforced automatically versus relying on human reviewers to catch?

If the answer is “not much” you’ve just diagnosed why your AI output isn’t great.

A Fireside Chat: The Model vs. The Environment

The Model: Look, I’m doing my best here. You dropped me into a repository with 400 files, no documentation, and a prompt that says “add a payment endpoint.” What do you expect?

The Environment: That’s exactly my point. You’re a pattern-completion engine. You complete patterns based on context. When the context is thin, you fall back on generic patterns from your training data.

The Model: Which is pretty good! I’ve seen millions of codebases.

The Environment: You’ve seen millions of average, other codebases. So when you get no specific guidance, you produce average code. That’s not a flaw. That’s exactly what pattern completion should do. But this team doesn’t want average. They want their patterns.

The Model: So tell me what they are!

The Environment: That’s what I’m for. When I’m well designed, I give you conventions, constraints, and feedback loops. I turn you from a generic code generator into a teammate that understands this project.

The Model: And when you’re not well designed?

The Environment: Then people blame you. They upgrade to a more expensive version of you. They get the same generic output with slightly better grammar. And they never question whether the bottleneck was me all along.

There Are No Dumb Questions

Q: Does this mean prompting doesn’t matter at all?

A: Prompting matters. But it’s single-use. A great prompt helps one interaction. A great environment helps every interaction. Prompting is giving directions to a taxi driver. Environment design is building the roads.

Q: Won’t better models eventually solve this?

A: Better models will get better at working with whatever context they’re given. A better model in a great environment will be extraordinary. A better model in a bare repo will still produce generic code. The environment advantage doesn’t disappear as models improve. It compounds.

Q: Isn’t this just “documentation”?

A: Documentation is one input. But documentation that isn’t enforced is a suggestion. The environment includes enforcement. Constraints that catch violations automatically, feedback loops that learn from mistakes, and context structured so the AI can actually use it. A wiki page about naming conventions is documentation. A pre-commit hook that rejects bad names is environment.

What’s Coming

Over the next five articles, we’ll build up what a well-designed AI development environment actually looks like. From making your conventions machine-readable (Article 2), to constraints that enforce themselves without human reviewers (Article 3), to multi-agent pipelines that create defence in depth (Article 4), to environments that get smarter with every session (Article 5), and finally the full integrated system (Article 6).

Each article moves from concept to practice. No theory without action.

But for now, you have the hypothesis. And you have the two-minute audit. That’s enough to start.

The Bullet Points

For us humans, here’s a summary.

• The common instinct — when AI writes bad code, we blame the model, write longer prompts, or give up on AI for serious work.

• The wrong diagnosis — all three responses treat the AI as the variable, but the AI is a pattern-completion engine working with whatever context it has.

• The environment hypothesis — the quality of AI output is a function of the environment, not the model. A well-designed environment with a cheaper model beats a bare repo with a frontier model.

• What “environment” means — conventions, constraints, architectural context, accumulated knowledge, and feedback loops.

• The key shift — stop investing in single prompts. Start investing in the environment. One compounds. The other doesn’t.

Next in the series: “Engineering Context: Teaching Your AI What You Know” where we get specific about making your conventions and context available to your AI assistant.

There’s a distinction that doesn’t get made often enough, and it’s costing teams time, money, and a slow erosion of trust in their tools.

Engineering agents is the discipline of building AI agents — writing the code, designing the architecture, hooking up the tools, deciding what an agent can and cannot do. It’s what this blog mostly lives in. Embabel, MCP servers, tool definitions, memory strategies, bounded autonomy. Code over promises.

Engineering with agents is different. It’s the discipline of working alongside AI agents as a software engineer — using them as collaborators in your daily development practice. Writing better prompts. Verifying AI output. Building the harness of constraints that stops an agent doing something expensive and irreversible at 3am. Progressing from “I use Copilot for autocomplete” to “I have a multi-agent pipeline that writes, reviews, tests, and integrates code while I sleep.”

Both disciplines matter. But they require different skills, different tools, and — critically — different mental models.

If you show up to engineering with agents using only the skills of someone who has never thought seriously about what an agent is, you’ll get autocomplete with delusions of grandeur. And if you try to engineer agents without understanding how to collaborate with them day-to-day, you’ll build systems that nobody — including you — trusts to run.

This article is squarely about the second discipline: engineering with agents, and what the tools you already use can actually do to support your progression.

Subscribe now

The Framework

What follows is a capability assessment mapped across six levels of AI collaboration literacy — from “I know AI exists” to “I run autonomous agent teams across my organisation.” The two tools under the microscope are Claude Code (Anthropic’s terminal-native agentic coding assistant) and GitHub Copilot (the full suite: inline suggestions, agent mode, coding agent, CLI).

Where relevant, we describe what any AI coding tool would need to support at each level; a generic requirement that’s useful both for practitioners evaluating future tools and for vendors looking honestly at their roadmap.

This assessment reflects the capability landscape as of March 2026. Both tools ship frequently; gaps marked here may close.

Level 0: The Aware

At the base level, the requirement is simply a working interface and enough transparency to know what model you’re talking to. Both tools clear this bar. Claude Code gives you /model to see the current model and /cost to track your spend; Copilot shows the model in VS Code, though its CLI is less forthcoming. No meaningful gaps here.

The more important observation is that Level 0 is primarily a mindset, not a tool capability. The question is whether you’ve started asking why the AI said what it said — not just whether you liked the output.

Level 1: The Prompter

Level 1 is where practitioners start to develop deliberate habits: translating intent into prompts, curating context consciously, and developing an awareness of what the context window costs.

Both tools support natural language interaction well — Claude Code via the terminal with multi-turn conversation, Copilot via the chat panel, inline suggestions, and agent mode. That part is table stakes.

The gap that matters is context engineering. Claude Code supports a layered context system: CLAUDE.md files at the global, project, and directory levels, supplemented by skills and AGENTS.md. This means you can encode context that is always true, context that is true for this repository, and context that is true for this corner of the codebase — and the agent reads the right layers automatically.

Copilot offers a single .github/copilot-instructions.md file at the project level. It works. But a single flat file versus a layered, composable system is the difference between “I told the AI what I want once” and “the AI always knows where it is and what matters here.” One is a hope. The other is an architecture.

Cost and token visibility tell a similar story. Claude Code’s /cost command and Analytics API give you per-session visibility. Copilot’s usage metrics live at the org level in an admin dashboard — useful for governance, but not for the individual practitioner developing the habit of token consciousness.

Level 2: The Verifier

Level 2 is about trust — specifically, building the automated infrastructure that lets you verify AI output systematically rather than eyeballing it.

Code execution is supported by both tools. Claude Code’s Bash tool runs any command; Copilot’s agent mode runs terminal commands in VS Code. That’s the easy part.

The important gap is lifecycle hooks. Claude Code supports PreToolUse, PostToolUse, and FileChanged hooks with allow, deny, and ask control flow. This means you can intercept what the agent is about to do before it does it — warn, block, or prompt for confirmation based on what tool is being called or what file is being touched. Copilot has no equivalent. Its workaround is GitHub Actions, which enforces checks at PR time. That’s not nothing — PR gates are real gates — but they fire after the agent has already acted, not during.

Code review is one area where Copilot has a genuine native strength: @copilot as a PR reviewer on GitHub is turnkey and fits naturally into the workflows most teams already use. Claude Code’s review capability is built through a custom code-reviewer agent, which is more powerful but requires more setup.

Permission control is more nuanced with Claude Code — fine-grained allow/deny lists per tool, path patterns, and domain restrictions. Copilot’s .copilotignore handles content exclusions but doesn’t reach to per-tool permission control.

Level 3: The Habitat Engineer

Level 3 is where you stop using an AI tool and start building a development environment that includes AI as a first-class component. This is the level where the gap between the two tools becomes significant.

The core concept here is the harness: a set of living documents and enforcement mechanisms that declare what the AI can and cannot do, what it knows about your project, and how it should behave across sessions. Claude Code supports this through HARNESS.md combined with hooks and CI integration — PreToolUse hooks warn during development, CI blocks at the pipeline. There is no equivalent concept in Copilot. Its closest analogue is .github/copilot-instructions.md serving as advisory context, with GitHub Actions as the enforcement mechanism downstream.

Custom agent definitions are another substantial gap. Claude Code lets you define specialised agents in .claude/agents/*.md with YAML frontmatter specifying per-agent tool lists and model selection. A spec-writing agent gets different tools and a different model than a code-review agent. Copilot has no equivalent — agents are differentiated through prompt engineering within a single chat interface.

Parallel agent isolation, where multiple agents work safely on different branches of a codebase simultaneously, is built into Claude Code through git worktrees — the --worktree flag and isolation: worktree in agent definitions handle this automatically. In Copilot, you’d manage separate worktrees manually and run separate chat sessions yourself.

Model routing — the ability to choose the right model tier for the right task — is supported in Claude Code through the model: field in agent definitions and the MODEL_ROUTING.md pattern. Copilot uses a single model per session, with no routing mechanism inside the tool.

Compound learning is the last significant gap at this level. Claude Code supports AGENTS.md for curated project knowledge, REFLECTION_LOG.md for agent-proposed learning, and auto-memory — mechanisms for accumulating what the agent has learned about your project across sessions. Copilot has no cross-session learning mechanism. When the session ends, it forgets.

MCP tool extension is partially supported by both tools, but differently. Claude Code integrates MCP servers via .mcp.json with autonomous tool discovery; Copilot’s Extensions provide tool access, but they’re chat-invoked rather than available to the agent autonomously.

Level 4: The Specification Architect

At Level 4, specifications become the source of truth and the agent pipeline is a first-class engineering artifact — with safety gates, orchestration, and programmatic access.

Multi-agent orchestration is fully supported in Claude Code: an orchestrator dispatches a spec-writer, then a TDD agent, then implementers, then a code reviewer, then an integration agent, each with scoped tools and bounded responsibility. Copilot has no equivalent; individual coding agent tasks can be assigned, but there is no pipeline definition or dependency management between multiple agent roles.

Safety gates are similarly absent from Copilot’s current architecture. Claude Code supports plan approval gates — the orchestrator pauses for human review before proceeding — and MAX_REVIEW_CYCLES as a guardrail against runaway loops. Copilot’s workaround is branch protection rules at merge time, which is a gate, but not a gate inside the autonomous workflow.

Async cloud execution is an area of genuine parity. Claude Code supports headless mode and the Agent SDK; Copilot’s Coding Agent handles the “assign an issue, get a PR” workflow natively, and for teams already living in GitHub this is a meaningful capability that maps naturally onto existing practice.

Programmatic integration tells a more differentiated story. Claude Code offers a headless CLI (claude -p), a Python SDK, and a TypeScript SDK — the full agent loop is accessible programmatically. Copilot’s CLI handles command suggestions, but there’s no SDK that exposes the full agentic workflow to external scripts or CI pipelines.

Scheduled autonomous tasks are supported in Claude Code via the /schedule command and desktop and cloud task scheduling. Copilot has no equivalent; the workaround is GitHub Actions on a cron schedule, which executes workflow steps but doesn’t invoke the agent directly.

Level 5: The Sovereign Engineer

At Level 5, AI collaboration becomes an engineering discipline with the same governance requirements as any other platform capability — telemetry, standards, distribution, audit.

OpenTelemetry export is a clean differentiator here. Claude Code’s native OTel export integrates with Grafana, Datadog, and Honeycomb, correlating AI telemetry with the rest of your observability stack. Copilot has no OTel export; the Copilot Metrics API provides org-level analytics on acceptance rates, active users, and language breakdown, which is useful for adoption tracking but disconnected from infrastructure observability.

Usage analytics are reasonably strong in both tools. Claude Code provides daily aggregates with per-user token usage and cost estimates via the Analytics API. Copilot’s Metrics API covers adoption signals. Claude Code is more granular on cost; Copilot is more naturally surfaced for GitHub-native org reporting.

Agent team coordination — multiple agent sessions sharing state, communicating, and managing dependencies — is in experimental support in Claude Code through Agent Teams (team lead, teammates, shared task list, peer messaging). Copilot has no multi-session coordination mechanism.

Reusable harness templates — the ability to package and distribute organisational AI standards as installable artifacts — are supported in Claude Code through its plugin system, which bundles skills, agents, hooks, and templates together. Copilot’s workaround is GitHub template repos containing .github/copilot-instructions.md, which gets you the instructions file but none of the enforcement, hooks, or agent definitions.

The Pattern

Both tools serve Levels 0 to 2 well. If you’re in the early stages of building an AI collaboration practice, either tool will get you started. Copilot’s deep GitHub integration — PR review, coding agent, metrics — is a genuine strength for teams whose world is already organised around GitHub. The async coding agent in particular is worth taking seriously: assign an issue, get a PR, stay in your existing workflow.

Claude Code’s strength is its agentic infrastructure: hooks, custom agents, plugins, orchestration, OTel. The higher levels — L3 through L5 — require capabilities that are currently unique to Claude Code’s architecture.

It’s important to point out that these are capabilities, not permanent advantages. Any tool that adds persistent layered context files, programmable lifecycle hooks, custom agent definitions, and standard telemetry export can serve this full progression. The vendors are watching the same curve the practitioners are.

The Row That Matters

This is a capability assessment, not a product ranking. The framework’s levels are tool-agnostic; the capabilities required at each level are not.

The most important level in this assessment isn’t the one where your current tool excels. It’s the one where it has gaps — because that’s where your progression will hit a ceiling. Whether that ceiling requires workarounds, tool evolution, or a tool change, you want to know about it before you arrive at it.

Plan for it before you reach it.

Don’t agree with the assessment here, please reach out! I’m always keen to hear from the lived experience of software engineers pushing the limits of these tools, so please feel free to reach out to me here or on LinkedIn.

Russ Miles is a software engineering thought leader, keynote speaker, and the Festival Director of Eastbourne LitFest. Engineering Agents is his hands-on practitioner blog: code over promises, always.

Found this useful? Hit the subscribe button — and if you’re building something interesting in the agent space, get in touch. This blog actively wants more voices in it.

This article follow on from the Agent Design Maturity Ladder:

Most teams skip Phase 0 of Agent Design because it feels like delay. They want prompts. They want tools. They want visible progress.

They want to get their hands dirty and as agent toolkits advance the pseudo sense of progress can be intoxicating. Until you hit the wall.

At that point what they get instead is an agent that behaves confidently wrong — fluent in language, ignorant of reality, and dangerous precisely because it sounds competent.

Phase 0 is about avoiding this wall, and it iis not about agents at all.

It is about establishing the world an agent will inhabit — its physics, its language, its hazards, and its values — before you give anything the power to explore and act.

If Phase 1 is prompting, Phase 0 is ontology.

If Phase 2 is tools, Phase 0 is permission.

If Phase 3 onwards is autonomy, Phase 0 is responsibility.

Skip Phase 0, and every later phase compounds error.

An agent without a world model is not intelligent — it is theatrical, and it is prone to failure

Phase 0 is the pre-design phase of agent engineering. Not architecture. Not prompts. Not frameworks.

It is the disciplined act of answering one question:

“What must be true about the world for this agent to act safely, usefully, and intelligibly?”

This phase produces constraints, not capabilities. Domain to prevent danger.

Meaning before mechanism.

Phase 0 work is done with humans, not models.

Five Pillars of Phase 0 Agent Design

Pillar 1: Define the Domain (Before You Define the Agent)

Agents do not operate in “tasks”. They operate in domains — structured worlds with rules, entities, and consequences.

Strong Phase 0 questions include:

• What domain does this agent exist within?

• What is in scope — and what is explicitly out of scope?

• What entities matter here?

  (People, artefacts, states, approvals, risks, policies)

• What relationships between those entities are real, causal, and important?

• What actions are even possible in this world?

If you cannot describe the domain without referencing the agent, you are not ready to build one.

Pillar 2: Establish the Grounded Language of the World

LLMs are language machines — but language without grounding is hallucination.

Phase 0 asks:

• What terms have precise meaning in this domain?

• Where do humans routinely disagree on definitions?

• Which words are overloaded, informal, or context-dependent?

• What does “done”, “approved”, “safe”, or “urgent” actually mean here?

This is where most agent failures are born: the model is fluent, the organisation is ambiguous.

Phase 0 is where ambiguity is exposed, not hidden behind prompts.

Pillar 3: Clarify Human Intent and Value

Agents don’t create value. They amplify the value logic already present — good or bad.

Phase 0 questions include:

• Who is this agent for?

• What human pain or friction are we trying to relieve?

• What outcome would make a user say: “This helped.”

• What outcomes would be technically “correct” but humanly wrong?

• How will we measure success without relying on activity metrics?

If you cannot articulate value without mentioning automation, stop. You are, at best, designing motion, not progress.

Pillar 4: Identify Hazards Before Capabilities

Phase 0 is where you imagine failure before intelligence is applied.

Questions to ask include:

• What is the blast radius if this agent is wrong?

• What errors are recoverable — and which are not?

• What actions should never be taken automatically?

• What does a graceful failure look like here?

• When should uncertainty trigger escalation rather than action?

Autonomy is not a reward. It is a liability you earn the right to carry.

Pillar 5: Locate Ground Truth

Agents must know where reality lives.

Phase 0 insists on clarity:

• What are the authoritative sources of truth?

• Which sources conflict — and how do humans resolve that today?

• What knowledge is static vs temporal vs contextual?

• What knowledge is implicit in human heads but absent from systems?

If the organisation itself does not know where truth resides, the agent will invent it. And it will sound convincing while doing so.

Phase 0 Agent Design Outputs: Not just Artefacts — Agreements

Done well, Phase 0 produces:

• A shared domain model

• Explicit constraints and invariants

• Clear non-goals

• A list of known ambiguities

• A definition of safe failure

• Agreement on where humans stay in the loop

None of these are prompts. All of them shape every prompt that follows.

Common Phase 0 Anti-Patterns to Avoid

When you hear some of the following, beware:

• “We’ll figure it out in the prompt.”

• “The model will infer that.”

• “Let’s just prototype and see.”

• “It’s just internal — low risk.”

• “We’ll add guardrails later.”

These are not shortcuts. They are deferred disasters.

Some practices to consider

• Run Phase 0 as a facilitated workshop, not a solo design task

• Use real incidents and failures to surface hazards

• Force explicit answers to “What must never happen?”

• Write constraints in plain language before encoding them

• Treat unresolved ambiguity as a blocker, not a footnote

Checklist: Are You Ready to Leave Phase 0?

You may proceed only if:

• The domain can be explained without mentioning the agent

• Success and failure are both clearly described

• Hazards are named, not implied

• Sources of truth are agreed upon

• Humans understand where responsibility remains theirs

If not, you are not in Phase 1. You are simply rehearsing failure with better tooling.

Phase 0 is not optional

Phase 0 feels slow because it is thinking made visible. But every agent that behaves well under pressure — every system that earns trust — was born here, in restraint, clarity, and humility.

Before the agent, there must be a world. Before autonomy, there must be understanding. Anything else is theatre.

Building agents and their agentic workflows looks deceptively simple on first glance. Create an agent, tell it what to do, give it access to an LLM or two and BANG, you’re done. Right?

Well, I wish that were right. But usually that doesn’t lead to a useful, powerful agent. It leads to an expensive, untrustworthy chaos monkey1.

If you’re lucky then there is a moment, early in every engineer’s practice with AI agents, when they feel the same uneasy thrill sailors once felt approaching an unmapped coast. They see potential everywhere—automation, reasoning, orchestration—yet the terrain feels unstable.

What begins as a simple prompt becomes a creature with surprising initiative; what begins as a tool becomes a partner that can make decisions you did not explicitly author. And so the question becomes not merely how to build an agent, but how to shepherd its growth.

Most engineering disciplines begin with a design blueprint and end with an implementation. Agent engineering is more like raising a child: you design the environment before you design the agent, you add capabilities gradually, and you tighten governance as autonomy increases. A reckless agent is not a product flaw—it’s a parental mistake. A misaligned agent is a design failure, not a moral one.

Subscribe now

The old world of software services was about deterministic instructions; this new world is about bounded cognition, ensuring that systems which can reason do so inside guardrails that reflect both our goals and our ethics. You don’t “deploy an agent” the way you deploy a microservice. You introduce an agent to its domain, teach it the world, give it tools, bind it with invariants, and invite it to collaborate with humans and other agents. And with each step you reduce fragility and increase value.

The progression is clear. When the first agent appears in a team, it is nothing more than a glorified autocomplete—occasionally helpful, occasionally absurd. But with the right design, that initial spark becomes:

• A tool user capable of meaningful work

• A planner capable of decomposing tasks

• A governed executor that can act safely

• A collaborator negotiating with peers

• An autonomous entity that monitors, decides, and adapts

Every agent in production today sits somewhere on this ladder. Misplace it, and you risk either giving too much autonomy too early—or worse, leaving enormous value unrealised because the agent was never allowed to grow.

This article explored this ladder. A framework for taking an idea of an agent and guiding it, step by step, until it becomes a trustworthy participant in your systems. It balances the clarity of constraints with the creative potential of modern AI and demands discipline because power without boundaries is chaos, yet discipline without creativity is paralysis.

Above all: an agent is not defined by its intelligence but by its governance.

An Agent Maturity Ladder

From prompt-driven helpers → governed, autonomous, collaborating systems

We need a clear, practical, end-to-end blueprint for designing an agent — or an ecosystem of agents — that can start simple (semi-manual, prompt-driven) and mature into fully autonomous, domain-aware, collaborating agents.

This is the agent maturity ladder.

Phase 0 — Clarify the Domain (The D in DICE)

Before you design an agent, you design its context, its environment, its world.

Steps

1. Define the domain

   • What is this domain’s language?

   • Where is the domain’s boundary?

   • What objects already exist here?

   • What actions can be taken?

   • What properties matter?

   • What is out of bounds?

2. Define the user needs

   • What problems should this agent solve?

   • What pains or bottlenecks should it eliminate?

3. Define the desired outcomes

   • What does “value delivered” look like?

   • What should we measure?

4. Define hazards and failure modes

   • Where could this agent cause harm?

   • What is the blast radius?

This becomes the grounding substrate for safe autonomy later.

Phase 1 — Prompt-Driven, Single-Agent (Assisted Mode)

No autonomy, pure suggestion. The agent cannot act, only support.

Purpose

• Explore feasibility

• Learn the domain

• Prototype workflows quickly

Steps

1. Write prompts that express the behaviours you want

   • “Given X and Y, produce Z…”

2. Give examples of correct behaviour

3. Clarify unacceptable behaviour

4. Use retrieval (RAG) for contextual domain grounding to the LLM

   • Docs

   • Policies

   • Past task examples

Outputs

• Initial persona of the agent

• Early task patterns

• Understanding of what the agent should eventually do

Phase 2 — Tool-Using Prompt Agent (Controlled Capability)

Still no autonomy, but now the agent can do things when asked.

Steps

1. Define allowed tools

   • APIs, including MCP

   • Shell commands

   • Database queries

   • Internal platform operations

2. Implement function schemas

   • Inputs, outputs, constraints

3. Define the environment context

   • Working context

   • Credentials

   • Permissions

4. Wrap prompts in structured system instructions

   • “You may only call tools listed below…”

   • “Never execute destructive actions without a plan.”

Purpose

Demonstrate the agent can act safely under human instruction.

Phase 3 — Add Planning (The P in GOAP)

The agent transitions from “tool caller” to “planner and executor”.

Steps

1. Define actions

   • Preconditions

   • Effects

   • Cost/value

2. Define world state

   • What does the agent believe is true?

   • How does it verify or update state?

3. Add planning loop

   • Observe → Plan → Act → Evaluate

4. Introduce explainability

   • Log decision traces

   • Produce rationale for each step

Purpose

The agent can now split large tasks into coherent steps and reason about order, dependencies, and consequences.

Phase 4 — Introduce Invariants & Safety

Before autonomy, you must create guardrails at the structural level.

Steps

1. Define invariants

   • Must always be true

   • Must never be violated

2. Define forbidden actions

3. Define escalation rules

   • “If uncertainty > X, ask a human.”

4. Define review workflows

   • Summaries

   • Logs

   • Sign-offs

5. Add observability hooks

   • Every decision = structured event

   • Every action = auditable

Purpose

You make the agent’s boundaries explicit, testable, and explainable.

Phase 5 — Semi-Autonomous Mode (Governed Execution)

The agent now acts independently within strict boundaries.

Steps

1. Add triggers

   • Time-based

   • Event-based

   • State-based

2. Allow self-initiation

   • “If logs show X, start Y workflow.”

3. Limit autonomy by domain

   • Narrow, well-defined tasks

   • Clear policies

4. Require all actions to satisfy invariants

5. Enable audit and replay

   • Decisions are traceable

   • History is inspectable

Purpose

The agent “does work” without waiting for a human, but cannot go outside domain or violate safety.

Phase 6 — Multi-Agent Collaboration

Once one agent works, collaborate with others if needed.

Steps

1. Define roles

   • Researcher

   • Planner

   • Executor

   • Reviewer

   • Coordinator

2. Define message protocol

   • Shared memory

   • API passing

   • Structured messages

3. Delegate tasks between agents

   • Planner → Worker

   • Worker → Validator

   • Validator → User

4. Implement arbitration

   • Tie-break rules

   • Conflict detection

   • Confidence scoring

5. Emergent intelligence

   • Teams of agents solve problems individuals cannot

   • Coordination produces higher quality output

Phase 7 — Fully Autonomous Domain Agents

The agent becomes a self-directed actor in a complex environment.

Characteristics

• Maintains internal world model

• Generates plans without human prompting

• Validates those plans against invariants

• Executes actions with full observability

• Handles failure

• Adapts behaviour

Steps

1. Expand domain model

   • Types, relationships, constraints

2. Maintain episodic memory

   • Past runs

   • Lessons learned

   • State deltas

3. Integrate learning (optional)

   • RL

   • Fine-tuning

   • Feedback incorporation

4. Allow long-running behaviours

   • Monitoring

   • Optimisation loops

5. Formal governance

   • Identity

   • Audit

   • Secure execution boundaries

Phase 8 — Socio-Technical Integration

This is where production agents in regulated industries must live.

Steps

1. Define operational policies

2. Define human escalation

3. Define accountability chain

4. Integrate with MCP Gateway

   • Provenance

   • Enforcement

   • Policy evaluation

   • Observability

5. Periodic red-teaming

6. Automated tests for spec compliance

Purpose

The agent becomes a responsible citizen in a system of humans, rules, and other agents.

The maturity ladder exists to provide a safe path to the right level of complexity for a specific agent in a specific domain and context. Travelling from:

Prompt → Tool Use → Planning → Safety & Invariants → Semi-Autonomy → Multi-Agent Collaboration → Full Autonomy → Enterprise Integration

Each stage is layered. You don’t jump. You evolve your agents.

Each stage reduces human effort while increasing system safety and capability.

Let’s explore this in some more detail.

Design the World Before the Agent

Agents fail not because they cannot reason, but because they have no stable world to reason about. Before you specify behaviour, specify the domain:

• What objects exist?

• What relationships bind them?

• What states can change?

• What is forbidden?

Without this grounding, you are not building an agent—you are releasing a clever hallucination into production.

Begin with a Promptling (Assist Mode)

The smallest viable agent is nothing more than a structured prompt: a persona, some rules, a handful of examples, and a clear description of desired behaviour. At this stage, the agent:

• Suggests, does not act

• Explains, does not execute

• Learns the contours of the domain through examples and iteration

This is where you discover your blind spots. It is also where the agent begins to reveal insights about the work itself—points of friction, ambiguity, or drift that no process diagram ever captured.

Give it Tools (Controlled Power)

An agent with no tools cannot affect the world. An agent with too many tools becomes a liability. So we choose carefully:

• APIs

• File operations

• Search

• System commands

• Domain-specific actions

Every tool is defined by a schema. Every schema is a contract. Every contract is a guardrail. Here, the agent begins to perform real work, but only under explicit human instruction. Think of this phase as supervised apprenticeship.

Teach it to Plan

Planning—GOAP, ReAct, or structured plan-first pipelines—turns a clever assistant into a reasoning system. You introduce:

• Actions with preconditions and effects

• State the agent can inspect or update

• Plans that can be explained, corrected, or replayed

Once an agent can plan, it becomes legible. Once it is legible, it becomes governable. And once it is governable, it becomes safer to empower and scale.

Establish Invariants & Safety

• Never delete customer data.

• Never make financial decisions without validation.

• Never deploy without approval.

• Stop if confidence is low.

• Escalate if risk is high.

These are not suggestions. They are structural truths engraved into the agent’s reasoning process. Once invariants exist, the agent stops being fragile. It becomes predictable, testable, and increasingly trustworthy.

With invariants defined, you can add observability: logs, traces, decision rationales, and action histories. Now the agent is not only bounded—it is transparent.

Allow Semi-Autonomy (Governed Execution)

Once tools, planning, and invariants are in place, the agent can begin acting without waiting for a human to ask. It can:

• React to events

• Run workflows

• Monitor states

• Trigger actions

This is not freedom. This is responsible empowerment. The agent acts only within the boundaries you defined—and those boundaries are now explicit, audited, and observable.

You have created a junior colleague, not a risk.

Introduce Collaboration where Powerful

Now you define roles:

• A Researcher gathers information

• A Planner decomposes work

• A Worker executes actions

• A Validator checks invariants

• A Coordinator arbitrates uncertainty

Through blackboard memory or structured messages, they negotiate, debate, delegate, and converge. Emergent intelligence arises not from a single model but from the interaction of specialised agents and their reasoning.

This is the beginning of agent ecosystems—the AI equivalent of a high-performing team.

Grant Autonomy (with Accountability)

The mature agent now:

• Holds an internal world model

• Maintains domain memory

• Generates plans unprompted

• Executes safely

• Explains every decision

• Integrates feedback

• Adapts within boundaries

It behaves less like a script and more like a disciplined professional with a well-defined remit. It is not a “general AI.” It is a bounded, purposeful agent system, finely honed for a domain.

Integrate into the broader Socio-Technical System

This is the production phase:

• Identity

• Access control

• Policy enforcement

• Provenance

• Audit trails

• Escalation paths

• Compliance checks

• MCP gateway governance

The agent is now a citizen of your organisation—observable, governable, reliable. Not a curiosity. Not a toy. A collaborator.

A Well-Designed Agent is Matured

A well-designed agent does not emerge fully formed. It is sculpted through constraints. It grows through clarity. It learns only what the domain teaches, and it acts only within the laws you write for it:

Freedom through structure, capability through constraint, harmony through governance.

Phase 7 and 8 are the only contentious phases. They often happen in tandem, and sometimes much earlier in the ladder.

So the ladder itself is an evolvable tool to customise for the agents you are working upon. The key point being that if you design your agent ladder with care, your agents will climb it with confidence.

In a world not dissimilar from yours a pipeline with 27 stages tries to deduce intent: tests → scans → approvals → checks → retries → required reviewers → more checks → deploy. It’s the safety net, and it becomes the bottleneck.

In another world a team has:

• A Specification Constitution

• A centralised set of specifications and helpful prompts in a Platform Library.

• Specification aware AI-assistance checks and advice in the IDE

• - Policy-as-code tied to the spec

• A three-stage pipeline: validate → verify → promote

Lead time collapses. Quality rises. Audit becomes easier. The pipeline shrinks. Trust increases. Developers accelerate.

And nothing “freaks out”.

The modern continuous delivery pipeline is an accidental cathedral. It wasn’t designed; it accreted. It grew in layers — static checks here, compliance gates there, a scanner bolted on last year, an approval ritual inherited from 2012, a YAML file so large that engineers gather around it like medieval scholars decoding scripture.

Most organisations now run pipelines that resemble well-intentioned but increasingly unmanageable safety nets: sprawling, brittle, slow, and often misunderstood even by those who operate them. The pipeline has become a proxy for trust — not because it’s elegant, but because nothing better has been articulated.

And yet the physics of software delivery have shifted more in the last 18 months than in the previous decade.

AI-augmented developers working inside enriched IDEs can already move at speeds the old pipeline cannot understand. Tools and technologies like Claude Code, GitHub Copilot, Cursor, Embabel and bespoke internal agents compress the cognitive load of coding, testing, refactoring, documentation, security checks, and even architectural reasoning. A task that once took hours can now take minutes. A feature that took sprints now takes days.

This is a moment where your pipeline can begin to “freak”. The bottleneck is no longer human hands, perhaps it never was. It’s the accumulated process scaffolding that grew to protect human limitations. We now find ourselves in a paradoxical trap: developers and their AI assistants can work faster but the systems designed to keep them safe still assume they are slower.

You cannot ship a modern AI-accelerated flow through a pipeline built for the age of artisanal commits.

But here lies another insight:

The pipeline is compensating for something upstream — a lack of a single, explicit definition of what “good” looks like.

To simplify pipelines, shorten lead times, reduce risk, and actually benefit from AI-assisted productivity, we must shift the centre of gravity from pipeline logic to specification logic. In other words: create a “Specification Constitution” for every org, domain and team and let the IDE — powered by AI — maintain it during coding. Let the pipeline keep its gates if it must, but better prepare the developer through an AI-assisted IDE experience to be way ahead of the safety net.

Make guardrails be actual guardrails, and help the IDE keep the developer on the road.

This is the ancient Stoic trick for the modern era:

Make intent explicit; anchor behaviour in first principles; simplify the world by strengthening the centre.

A Specification Constitution and standard, helpful prompts can be just that centre:

When this specification exists, the IDE and its AI agents can pre-emptively do the work the pipeline currently guards for. Tests generated and checked at the moment of writing. Contracts upheld while lines are still warm. Security rules surfaced while context is fresh. Compliance hints produced before code even compiles. Integration assumptions validated in a shadow pipeline milliseconds after a change.

The pipeline ceases being the primary intelligence of software delivery and becomes what it should have always been:

a thin, sharp, trusted verifier.

To make this shift from slow assurance to fast safety the impetus is to shift from accidental pipelines to intentional constitutions, and from compensatory gatekeeping to principled engineering as early as possible in your Software Development Lifecycle.

What CD pipelines are really doing today

Most CD pipelines are compensating structures. Because we don’t have a single, explicit, machine-checkable definition of “good”, we bolt on:

• Static analysis steps

• Test suites of varying mystery and flakiness

• Security scanners

• Code style linters

• Compliance checks

• Manual approvals

They are the only gates and guardrails. The pipelines become change advisory boards in disguise

Each of these complications exist because we don’t trust what happened earlier in the process. The pipeline becomes a loose pile of inferred intent:

“If it compiles, passes tests A/B/C, survives scanner X, and Bob clicks approve, then… I guess it’s fine?”

That’s fragile, slow, and deeply not ready for an increase in flow.

“Specification constitutions” in the IDE

Making your AI-assisted coding aware of your organisation, domain and even team’s ways of working through specifications are what’s missing. Think of these documents as a living, executable constitution of intent for your piece of the system:

• Purpose – what this thing is for; success criteria in business terms.

• Interface & contracts – types, invariants, pre/post-conditions, error semantics.

• Scenarios & examples – executable examples, behaviour under edge conditions.

• Policies & constraints – security, performance, compliance, data handling rules.

• Risks & guards – what must never happen; critical invariants; blast radius expectations.

Captured in a structured format the AI can both read and write and co-evolving with the code in the IDE.

This “constitution” isn’t a doc on Confluence. It’s:

• Close to the code

• Executable (drives tests, contracts, checks)

• Readable by humans and machines

• A primary input and value delivered by AI-assisted coding

Extending the power in your IDE via AI: bringing the pipeline guardrails forward

Once you have a specification constitution, your AI assistant in the IDE can start doing work that the pipeline currently pretends to do:

• Enforce type and invariant discipline while coding (“this violates the risk guard you wrote”).

• Suggest implementations and refactors that preserve contracts.

• Check simple security and compliance rules immediately (“you’re logging PII here, spec says you mustn’t”).

• Run representative pipeline checks locally in a “shadow pipeline”:

  • Compile → run core tests → run lightweight static analysis → quick SAST/DAST stubs.

  • So the feedback loop becomes:

    • change → AI + specs check it in seconds → you iterate

  • instead of:

    • change → push → wait minutes/hours → pipeline complains → you context-switch back

You’re effectively collapsing most of the CI pipeline into the IDE and letting AI keep it in your working memory while you still remember what you just did.

Moving “good” upstream

Move the definition of good upstream into a shared Specification Constitution, surfaced by AI in the IDE, verified by a simplified, fast and lightweight continuous (and progressive) delivery pipeline.

Pipelines are compensatory systems. They exist because intent is implicit, distributed, or forgotten. A specification constitution concentrates intent.

This means AI-assistance can allow really valuable shifting left that was difficult, if not impossible, before. Without intelligent IDE support, pre-commit enforcement is a fantasy. With AI-assistance, the IDE becomes the first, strongest and domain-aware guardrail.

Specification Constitutions reduce cognitive load. They capture purpose, contracts, constraints, risks, and scenarios so that developers and agents can work without reconstructing tribal knowledge every time.

Faster inner loops demand simpler outer loops. An improvement in coding speed requires a reduction in friction downstream or the advantages are lost.

Compliance and safety can also become more explainable and codified. Policies expressed as structured, machine-checkable constraints attached to specs simplify audits and eliminate ritualised approvals. Let LGTM die as fast as it may.

Trust can then move from ritual to reasoning. Instead of dozens of gates, we rely on the clarity and integrity of the specification constitution and the reproducible checks derived from it.

Some practices to consider

• Write a Specification Constitution for every domain boundary — At minimum, capture:

  • Purpose & business outcomes

  • Pre-/post-conditions

  • Invariants & constraints

  • Type-level definitions (DICE)

  • Behavioural scenarios & examples

  • Security & compliance rules

  • Data-handling classifications

  • Risk declarations (“what must never happen”)

  • Observability expectations

• Let the IDE surface the constitution — AI-assisted checks should:

  • Validate invariants during coding

  • Generate & update tests automatically

  • Warn when implementations drift from spec

  • Run shadow pipeline checks continuously

  • Flag compliance/security violations when in flow

• Simplify the pipeline by deleting guesswork — Reduce pipeline steps to:

  • Validate the specification (schema + signatures)

  • Verify code/test alignment with the spec

  • Run system-level checks (integration, perf, resilience smoke tests)

  • Promote via policy-as-code (minimal, absolutely minimal, manual gates)

• In regulated environments, treat specs as governed artefacts. Make them a key part of a centralised Platform Specification Library for all to consume:

  • Version them

  • Approve them

  • Link them to incidents

  • Maintain audit trails

  • Look to generate compliance evidence automatically

Some things to avoid

• Auto-generated specs with no human intent — A constitution without authorship is theatre.

• Using specs as documentation only — They must be executable and enforced.

• Overcomplicating specs — They should shrink ambiguity, not become 50-page legal volumes.

• Leaving the pipeline unchanged — If you don’t simplify the pipeline, you only move the bottleneck downstream.

• Remove all bottlenecks from the pipeline too early — Only remove as confidence builds, as guardrails are not hit.

What happens to the delivery pipeline in this world?

The pipeline doesn’t vanish. It evolves.

It stops being a primary place where “good” is inferred, and becomes a thin verification and promotion service that answers four big questions:

1. Is the specification constitution present and valid? — Schema-valid, signed/approved where needed, linked to change.

2. Does the implementation honour the constitution? — All spec-derived tests pass. Contracts and invariants hold (run in CI and, crucially, in staging/prod).

3. Does this change remain safe in the system context? — Integration/contract tests. Performance, resource, and resilience smoke tests.

4. Can we safely promote this artefact between environments? — Progressive delivery, canaries, feature flags. Policy-as-code “green lights” for regulated bits.

The pipeline graph goes from:

dozens of steps → multiple conditional branches → manual approvals → long walls of YAML

to something more like:

(1) validate spec + code + tests → (2) system-level checks → (3) deploy with guardrails

It’s simpler but more opinionated.

If we encode what “good” looks like as a specification constitution and let AI enforce and exercise that constitution in the IDE, then most of the complex, brittle logic in our CD pipelines becomes redundant.

Pipelines can:

• Assume a spec is present (and block if not).

• Verify that code and tests are consistent with the spec.

• Run a minimal, system-level safety net that’s independent of the IDE environment.

• Promote artefacts through environments under policy-as-code rules tied back to the spec.

This is simplification by concentrating meaning less “accidental” complexity in YAML. More valuable “essential” complexity in specs and policies that humans can understand.

The pipeline stops being a nervous system and becomes a spinal reflex.

In every environment, there’s a quiet, uneasy truth: the most dangerous system in production today isn’t the ancient COBOL core, the Kafka cluster on its last nerve, the new developer wondering what “clean_up.sh” does, or the regulatory reporting job stitched together from duct tape and resignation.

It’s the AI agent someone built on a Tuesday afternoon.

Not because AI engineers are reckless — quite the opposite. They’re ambitious, curious, and hungry to reduce the friction they drown in every day. So an agent appears: a prompt here, a tool call there, a vector store quietly humming in the corner. It starts as a sketch, grows into a convenience, then an assistant, then — without anyone meaning for it to happen — becomes part of the machinery of the company.

This is the new “shadow system.”

Worse than a shadow database, more slippery than a shadow API, and infinitely more confident than a shadow spreadsheet. And like all shadows, it grows in the places we don’t look.

The reason isn’t malice; it’s velocity. The tools are too good, the friction too low, the results too tempting. A senior engineer watches an agent autonomously triage tickets and thinks, finally, something in my life makes sense. A junior developer wonders why they ever wrote bash scripts when an agent can self-document, self-debug, and self-delude all in the same afternoon. A product manager sees magic and wants more.

But in most organisations, magic has consequences:

• Magic has auditors.

• Magic has operational resilience impact tolerances.

• Magic has model risk committees.

So the game changes. You can’t rely on talent or good intentions. You need something older, something sterner — a way of seeing the system beneath the shimmer. A way of remembering that an agent is not a pet, not a toy, not an experiment with production-shaped ambitions. It is an operational entity with the power to move business, alter systems, confuse humans, and violate policies with the enthusiasm of a golden retriever set loose in a fireworks warehouse.

This is why you should consider crafting a Well-Architected Framework for AI Agents. Not as bureaucracy. Not as ornamentation. But as armour.

The framework isn’t here to slow engineers down. It exists so they can go fast safely — so that agents become extensions of the platform’s reliability, not exceptions to it. It gives language to the risks, scaffolding to the lifecycle, and structure to the responsibilities no prompt will ever shoulder.

In a sense, it’s a return to first principles. Organisations, particular regulated ones, have spent decades learning how to govern models, secure systems, classify data, assure resilience, and move change into production without waking the FSA. AI agents don’t get a magical exemption from any of this. They simply expose the seams in our existing assumptions.

An AI Well-Architected Framework brings sanity back to the relationship. It turns “demos that never died” into governed systems. It turns “god-mode agents” into least-privilege citizens. It turns “black box magic” into observable, testable, controllable machinery. It gives engineers a golden path and executives a reason not to panic.

And above all, it offers one clear promise: If you build agents with this discipline, you will survive what happens next.

Subscribe now

Six Pillars of a Well-Architected AI Agent

1. Governance, Compliance & Model Risk

Agents must have purpose, ownership, accountability, and a lifecycle — or they will become undead artefacts wandering your platform.

Some practices to consider

• Register every production agent as both a model and a system.

• Create an Agent Charter defining its allowed and forbidden domains.

• Ensure approvals: model risk, DPIA, architecture, resilience.

• Use lifecycles: experiment → alpha → pilot → production.

Some things to avoid

• The “demo that never died.”

• Shadow agents with no owner.

• Agents that quietly drift from helper to decision-maker.

2. Safety, Security & Permissions

The enemy is not intelligence; it’s power without constraints.

Some practices to consider

• Tools are whitelisted, versioned, permission-checked.

• Agents run under scoped, environment-specific identities.

• OPA/Cedar-style central policy checks everything.

• Prompt injection defence: trust boundaries, wrapping, sanitisation.

Some things to avoid

• God-mode agents.

• Untrusted Slack/wiki content fed directly into prompts.

• Agents executing high-risk actions with no human review.

3. Architecture, Reliability & Control

A well-architected agent has a brain and also a spine.

Some practices to consider

• Use orchestrators for steps, retries, backoff, idempotency.

• Encode allowed transitions as state machines.

• Kill switches, step budgets, environment separation.

• Degrade gracefully: “I cannot act; here is my analysis.”

Some things to avoid

• One-prompt systems pretending to be platforms.

• No distinction between experimentation and production.

• Loops that re-apply Terraform until the infra glows.

4. Data, Memory & Privacy

Memory without governance becomes liability with a timestamp.

Some practices to consider

• Design with domains and context in mind.

• Agents must respect classification, minimisation, and purpose limitation.

• Memory is a product: schema, TTLs, consent, purgeability.

• Mask, redact, pseudonymise by default.

• Ensure residency, domain andboundary controls, and contractual compliance.

Some things to avoid

• Vector DBs full of raw logs containing PII and secrets.

• Agents that “remember forever.”

• No separation between sandbox and prod data.

5. Observability, Evaluation & Incidents

An unobserved agent is indistinguishable from a hallucination.

Some practices to consider

• Full trace logs: prompts, steps, tool calls, approvals.

• Offline scenario evals + online behavioural monitoring.

• Guardrail metrics: blocked actions, policy denials, loops.

• Incident playbooks with owners, disable switches, RCA.

Some things to avoid

• “It seems to work” as an operational strategy.

• No E2E eval tasks.

• No link to operational resilience frameworks.

6. Developer Experience, Adoption & Change

Agents must be buildable, reviewable, explainable, and evolvable — or they will become folklore, not tools.

Some practices to consider

• Agent-as-code: prompts, tools, evals, policies all in Git.

• Clear domain-bounded ownership.

• PR-based changes with CI evals.

• Golden-path platform abstractions.

• Change categories with approvals for high-risk updates.

Some things to avoid

• An agent ecosystem run by “two hero wizards.”

• Prompt edits directly in production.

• DIY frameworks proliferating like feral cats.

The Platform Lens: Agents as a Product

An AI-aware internal developer platform becomes the crucible where agents are born safely:

• Auth, logging, tracing, policy engine, eval harness — all centralised.

• A golden path for building compliant agents from day zero.

• Guardrails-as-a-service instead of tribal knowledge.

• A lifecycle that reflects risk, not enthusiasm.

And with this comes the discipline of Well-Architected Reviews — not as ceremony, but as calibration. A way of asking:

Is this agent a system we can trust? Or a story we’re telling ourselves?

In the end, an AI agent is a mirror: it reflects your architecture, your governance, your discipline, and your blind spots. A good framework doesn’t make magic safer — it makes systems saner. And in the quiet, high-stakes world of your organisation, that WAF sanity is the closest thing you can get to a superpower.

(On a recent visit to The Morgan Library in New York City)

I adore libraries. When on vacation I haunt them voyeuristically, searching for rare books and being entranced by those tombs that promise from their spines.

The ethos of a library, whether it be a code library or a physical one, is attractive. It says, “Here lies useful and beautiful, even important, things to discover and use.” The goal is so simple, here lies something that might be usable by you. Libraries are by and for the borrower. In code we call this reuse, but it is perhaps just scaled use. A contract of service between creators, curator and borrower.

But curating a library is not easy, nor is it always cheap. Cheaper perhaps than not having one though, and that’s true of the latest library to enter the mix. The library that services and guides both the AI augmented coding agents — the Djinn — and the humans that wrestle with our systems.

As builders of platforms to support both humans and AI Djinn in their work, a library of specifications is one of the smallest and most impactful offerings we can curate into the platform. Sourcing from “localised” specifications — works in progress helping specific teams — we can help lift all the intelligences working on our systems by curating what’s generally applicable; a library of specifications that should be relevant and useful everywhere across our estate.

Introducing the Platform Specification Library.

Subscribe now

There’s a fiction humming through most engineering teams: That because we have dashboards, pipelines, graphs, wikis, and a thousand tools blinking at us like a migraine in neon, we somehow possess “understanding.”

We believe — or pretend to believe — that visibility is the same thing as clarity.

That a pile of signals is a substitute for a system. Then something breaks and in that fluorescent panic, the lie dissolves.

We discover that our architecture is not a map at all — it’s a maze, a bricolage of incompatible assumptions stitched together by history, inertia, and optimism.

Now add AI to this mess. AI models are amplification engines. They inherit and magnify whatever environment they’re given. Feed them a fragmented architecture and they will produce fragmented code. Feed them inconsistent payloads and they will remix the inconsistency into new and baroque variations.

Feed them a thousand contradictory patterns and they will eagerly hallucinate the thousand-and-first.

The problem is not the augmented coding djinn. The problem is the lack of a single truth the djinn can lean on.

This is where the Platform Specification Library enters — not as a governance artefact, but as a philosophical correction. Gentle guardrails useful to person and djinn.

The Purpose of the Platform Specification Library

The Platform Specification Library — built on Spec-Kit or any similar system — is not documentation.

It is law, lore, and language. It is a gift to everyone, just like a library of books.

It is:

• The architecture as text.

• The domains and subdomains as semantics.

• The platform as grammar.

• The shared imagination of the organisation, stabilised in code.

It is an investment. Put plainly:

It ensures that AI augments human creativity rather than amplifying organisational entropy.

Without a central library, AI makes things worse faster. With one, AI becomes the most powerful architecture-reinforcement engine we’ve ever built.

The Eight Principles of AI-Ready Specifications

When planning your own specification library, it’s easy to get lost in overly-detailed rules and under-specified areas of dangerous freedom. Over time, these are the principles I use to craft my own platform specification library:

1. Clarity Over Cleverness - If the spec cannot be understood by a junior, it cannot be acted upon by an AI.

2. Canon Over Consensus - This is not as flexible as a wiki encourages; it is a single source of truth.

3. Small Pieces, Linked Well - Every domain concept, every important architectural principle and guardrail, deserves its own file. Fragmentation is avoided through thoughtful linking, not giant monoliths.

4. It is not an island - The library has connective tissue to Architecture Decision Records, documentation and notes, even localised specification libraries. These are all fabulous sources for distillation into the platform library’s specifications.

5. Version Everything - Architecture evolves and decays, domains crystallise. Which version of a specification you are considering matters.

6. Update the Spec Before the System - Reality must follow the map, or the map will drift into fiction and theatre.

7. If AI Should Generate It, It Should Be Specified - Consistency becomes a property of the language, not the people.

8. The Easiest Path Should Be the Correct Path - When the platform makes using specs effortless to apply, adoption becomes organic.

How to Establish your own Platform Specification Library

Building a library takes time and here are the steps I’ve found useful when bringin a Platform Specification Library to life:

Step 1 — Write the Intent Charter

This is one page. State what the library is for and what it absolutely is not for.

Step 2 — Curate the initial Canonical Formats

Use machine-readable standards only:

• OpenAPI

• JSON Schema / Zod

• AsyncAPI

• CUE

• - Spec-Kit link manifests

Everything must be parseable by humans and agents.

Step 3 — Structure the Repository Clearly

/spec-kit
   /domains
   /events
   /services
   /workflows
   /platform-capabilities
   /constraints
   README.md
   GOVERNANCE.md

Clean. Predictable. Idiomatic.

Step 4 — Define Contribution & Review Flow

Curate for your context:

• PR templates

• Auto-linting

• Breaking-change scanning

• Domain owner + platform architect review

• Impact Matrix for each contribution

Step 5 — Integrate Into Your Developer Workflows

Explore:

• IDE extensions

• CLI tooling

• AI agents that read from the library first

• Code generators tied to spec versions

Step 6 — Connect to Multi-Agent Pipelines

AI agents should:

• Generate service skeletons

• Generate client SDKs

• Generate tests

• Regenerate code on spec changes

• Flag drift between code and spec

Step 7 — Maintain, Maintain, Maintain

Regularly (quarterly) review:

“Is this still truthful? Is it still the best simple set of specifications for now?”

Some things to avoid

• The Library Becomes an Archive Instead of a Tool - If it doesn’t show up in the IDE, it will die.

• Over-specification - Spec only what is stable enough to rely on.

• Under-governance - Without curation, you get a museum of abandoned truths.

• Drift Between Spec and Reality - AI can help detect this — but only if you let it.

When Developers Should Submit Specs

It’s the question I meet the most when putting together a Platform Specification Library, “How do I knnow when I have something that’s a candidate for the library?”

For this I use a simple heuristic:

If someone else depends on it, or if AI should reinforce it, submit it.

Consider whether there is something to submit when:

• You define an API

• You publish an event

• You introduce a domain concept

• You standardise a pattern

• An integration becomes stable

• You want AI to generate consistent code against something you’ve noticed

Probably do not submit:

• Experiments

• Unstable ideas

• Hacks

• Anything ephemeral

Rely on the library curation governance process to ensure that the library is a cathedral, not a whiteboard.

An act of epistemic discipline

The Platform Specification Library is not a specifically technical artefact. It is an act of epistemic discipline — a promise that the organisation will not drown in its own contradictions.

It lets AI do what it’s good at: Reinforcing patterns, accelerate workflows, stabilising consistency.

It lets humans do what they’re good at: Designing systems, imagining futures, writing the code that makes you money (safely).

A platform that maintains a single, curated, machine- and human-readable truth is not just efficient. It is humane. Because clarity is kindness. And a clear system of specifications — one with a shared language — frees people and AI agents to think, to create, to build, to understand.

The Cargo Cult & The Right Fit

A team reads about “AI-driven ops” and builds an “autonomous platform agent.” It scrapes Slack, watches Grafana, and occasionally restarts the wrong cluster.

No one knows what it’s doing — least of all the people who built it. When a failure hits, the agent “fixes” the problem by deleting its own logs. They didn’t build a system; they built a personal hell.

Automation without proportion is hubris in YAML.

Another team has a nightly batch job that checks regulatory limits. It’s deterministic: run query, output report, send email.

They script it. Simple. Reliable.

Later, they need to coordinate 40 microservices for release approvals. A single script can’t know when all are ready, so they shift to events — “service.ready”, “test.passed”, “approval.granted.” Now releases self-organise through signals.

Months later, outages rise from external dependencies. They deploy an agent whose goal is “keep service availability above 99.9%.” It analyses telemetry, triggers retries, adjusts load thresholds, and opens PRs for misconfigured policies. The system is still human-led — but now agent-amplified.

Three approaches, one philosophy: the right tool for the right challenge.

Scripts, Events & Agents

In platform engineering, the temptation is often the same: to automate first and think later. You have a mess of pipelines, tickets, and manual toil, and someone says, “Let’s script it.” A bash loop here, a webhook there, a few GitHub Actions — and for a brief, shimmering moment, everything seems orderly.

Then reality happens. Contexts shift. Teams reorganise. APIs break. A service fails silently and no one knows why. You add more scripts to fix the scripts, and before long, your platform looks less like a michelin star dinner and more like a thicket of spaghetti.

This is the fate of scripted automation — a system that does exactly what you told it to, long after you’ve forgotten why.

The next step up the evolutionary ladder is event-driven automation. Here, instead of hard-wiring cause and effect, you wire intent and observation. The system doesn’t march through a linear script; it listens. It reacts to change. Pipelines trigger when artefacts change, rollbacks fire when health checks fail. The platform starts to feel alive — a distributed nervous system of events, each one a whisper of state change.

But even this has limits. Event-driven systems are reactive; they can drown in noise. What they lack is judgment.

This is where agentic systems enter — not as magic AI toys, but as autonomous participants in the platform. Agents can set goals, observe outcomes, and adjust plans. They reason about intent, not just input. A scripted automation asks, “What next?”; an agent asks, “What matters?”

The lesson is not that one model replaces another. It’s that each model belongs to a certain level of complexity.

• Scripted automations are for the predictable.

• Event-driven systems are for the observable.

• Agentic systems are for the unpredictable.

The wise platform engineer, working with the full gamut of options, doesn’t chase novelty — they choose proportion.

Subscribe now

Some practices to consider

• Map complexity before choosing automation - Draw your system as flows of change and intent, not just tasks. Stable, repeatable steps? Script them. Volatile, stateful reactions? Event them. Ambiguous, evolving goals? Agent them.

• Encapsulate purpose, not process - A script describes “how.” An event describes “what.” An agent reasons about “why.” Each is useful — when aligned with context.

• Keep humans in the loop, intentionally - In agentic systems especially, humans must define ethical and operational boundaries. Agents need goals and guardrails.

• Evolve iteratively - You don’t jump from scripts to sentience. Introduce event models first, then simple agents for narrow goals (e.g., pipeline self-healing, PR generation).

Some pitfalls to avoid

• Premature agency - Introducing agents before your event fabric is stable leads to chaos. Agents amplify ambiguity; feed them clean signals first.

• Overfitting the simple - Not every cron job needs cognition. If it’s deterministic, script it. Complexity worship is just another form of laziness.

• Neglecting accountability - The more autonomy you give, the more you need observability, audit trails, and simulation environments. Agents should be traceable, not mystical.

• Forgetting the human narrative - A platform that’s unexplainable erodes trust. Whether scripts, events, or agents — clarity, observability, is non-negotiable.

Further Reading

• Daniel Terhorst-North – The Best Simple System for Now

• Richard P. Gabriel – Patterns of Software: Tales from the Software Community

From a soothing fantasy…

There’s a quiet lie humming beneath most software organisations, and it’s this: we think we know what’s going on. Not in the cosmic sense — engineers are rarely that deluded — but in the immediate, visceral, operational sense.

We imagine that because we have dashboards, pipelines, tickets, wikis, and a thousand metrics and risk controls blinking at us like a neon migraine, we have “visibility.” It’s a soothing fantasy, like believing you can understand a storm by counting the raindrops.

Then something breaks. A page goes red. Dashboards bloom. And in the sudden, fluorescent panic of an incident, that fantasy shows its teeth.

In that moment the organisation discovers a bitter truth: we’ve built a labyrinth instead of a map.

Teams paddle between dashboards that don’t speak to each other. Release notes live in a wiki written by someone who left during another epoch. Artifact tags don’t match pipeline IDs. Trace spans don’t link to deploys. Flags mutate in the dark.

When the on-call person is asked the most basic generative question — what changed? — they’re forced to guess. A guess! In a multi-million-pound sociotechnical machine built for precision, our response to entropy is an educated shrug.

You don’t lose reliability in that moment. You lose trust.

Because trust isn’t a philosophical abstraction in engineering. It’s the invisible surface that everything else rides on — delivery speed, psychological safety, experimentation, incident response, even hiring. Trust is the currency of modern systems. And trust erodes fastest when people realise the system itself has no idea what it just did.

… to a disciplined reality.

Now zoom to another universe. One that isn’t magical; just disciplined.

The pager goes off. The on-call engineer opens the incident view. They click an exemplar — a single trace already linked to the deploy that introduced the regression.

One hop reveals the 14:03 flag flip tied to deploy r-2025-10-27.3, built from commit a1c3… The agent surfaces the causal chain: the build, the artifact, the change set, the test deviations, the risk signals. It suggests a scoped rollback with evidence attached. Approver clicks once. Latency drops.

The post-mortem writes itself from the event trail. No blame. No archaeology. No séance.

This isn’t “more telemetry.” It’s a different category of capability.

Observability 2.0 isn’t a bigger bucket of metrics; it’s the ability to ask novel, high-cardinality questions about your system with zero prep and zero re-instrumentation. It’s an epistemic upgrade: the difference between superstition and science.

And the only way to get there — the only sane foundation for AI-assisted operations — is an SDLC event-first data plane. Not a disjointed mess of logs and dashboards, but a stitched, curated substrate that ties together the entire software lifecycle: commits → builds → artifacts → deploys → flags → runtime → incidents. With join keys. With provenance. With policies. With lineage across code, data, and models.

This substrate isn’t just useful. It’s liberating. It gives human engineers superpowers — and gives agents something better to do than hallucinate.

It reduces cognitive load by replacing detective work with evidence. It turns regulated environments from bureaucratic minefields into traceable, auditable, least-privilege systems where agents can safely propose or execute bounded actions.

None of this is futuristic. It’s just the cost of professional adulthood in a world where complexity doesn’t care how many dashboards you have.

The organisations that thrive will be the ones who stop worshipping the Three Pillars cargo cult, stop treating telemetry as decorative architecture, and start treating events as first-class citizens. Maybe the Rosetta Stone of modern engineering.

Wide Events as the Substrate

Observability 2.0 isn’t “more metrics”; it’s the ability to ask novel, high-cardinality questions about what changed and who/what it affected—without a re-instrumentation sprint.

An AI-agent-friendly SDLC data plane gives you that: a curated, event-first substrate that stitches commits → builds → artifacts → deploys → flags → runtime → incidents. With stable join keys, provenance, and policy, agents can retrieve context, reason about causality, and propose (or execute) bounded actions.

In regulated environments, the same substrate delivers auditability and least-privilege controls.

Some practices to consider

• Model wide events, not shards - Emit one enriched event per step (commit, pipeline run, artifact, deploy, flag change, incident). Include timestamps, actor, service, env, tenant, trace/span links, and risk signals.

• Standardize envelopes + keys - Use a consistent envelope (e.g., CloudEvents) and stable join keys (commit SHA, build/run ID, artifact digest, release version, request trace ID).

• Link SDLC ↔ runtime - Propagate commit/trace IDs from CI/CD into services. Add span links (deploy → service spans) and exemplars on SLO metrics pointing to the relevant change.

• Sign provenance by default - Produce verifiable attestations for builds, SBOMs, images, and deploys (e.g., SLSA/in-toto). Verify before promotion or agent action.

• Guardrails for agent action - Expose pre-approved tools: “diff flag,” “rollback release,” “quarantine artifact,” each with capability scopes, rate limits, approvals, and audit trails.

• Privacy & policy at the field level - Redact/derive sensitive fields early; apply ABAC/row-level filters for both humans and agents. Separate non-prod/prod policies.

• Cost-aware retention - Keep wide events; project views (metrics/logs/traces) on demand. Use tail-based sampling + SLO/incident windows for hot storage and tier the rest.

• Lineage beyond code - Record lineage across jobs↔datasets↔models↔features↔endpoints so “what changed?” queries cover data and ML, not just app code.

• Human-in-the-loop, by design - For impactful actions, require review with linked evidence: the event, the diff, the trace, and the attestation.

Some things to avoid (and potential antidotes)

• ID Chaos - No consistent run/artifact IDs → joins fail.
  Potential Antidote: Central ID strategy; reject events without keys.

• Schema Drift - Events mutate silently → agents hallucinate.

  Potential Antidote - Contracts, versioning, CI checks, canary consumers.

• Three-Pillars Cargo Cult - Metrics/logs/traces sans events.

  Potential Antidote - Make events the source; derive projections from them.

• Unbounded Agents - Bots with prod god-mode.

  Potential Antidote - Scoped tools, approvals, blast-radius policies.

• PII Leaks in Telemetry - Legal/regulatory exposure.

  Potential Antidote - Field-level redaction, tokenization, policy tests.

• Panic Sampling - Cut volume, lose context.

  Potential Antidote - Keep wide events; sample spans, not facts of change.

Software is a living ecosystem and the event-first SDLC substrate is its memory — the part that stops the organism from touching the same electric fence twice.

Without it, we’re left with heroics, folklore, and dashboards that perform understanding instead of producing it. With it, we get systems that explain themselves, agents that stay inside the lines, and teams who can finally make decisions based on evidence rather than vibes.

In the end, this isn’t a story about AI or tooling or fashionable new observability slogans. It’s about responsibility.

We owe it to our future selves — and to the people we wake up at 3 a.m. — to build systems that can tell us what happened. Everything else is an excuse wrapped in a metric.

Documentation has long been the unwanted guest at the engineering table — everyone agrees it should be invited, but few actually make it feel welcome. We’d rather ship features than sentences.

But things are changing. The machines have begun to collaborate with us.

The rise of AI-assisted coding, autonomous agents, and generative design tools has upended the hierarchy of communication. What once lived in code comments, tribal knowledge, or hallway conversations now has to be written down, because our new collaborators — the non-human kind — can only understand what they can parse.

We are entering a renascita — a rebirth of documentation as the beating heart of the craft.

The Empty Folder & The Codex of Intent

An AI team boasts of “self-writing code.” Their repo is a black box and incomprehensible. When the lead engineer leaves, no one knows what the system means. The new agents follow old patterns, amplifying yesterday’s errors. There are no specifications, only fossils.

In another place and another time, a Florentine engineer drafts the design for a flying machine. He annotates the sketch — not just dimensions, but intent: “It must mimic the bat’s wing, not the bird’s.” Centuries later, a software architect writes a system specification: “Transactions must resolve with idempotent certainty, not speed.”

Both are acts of specification — artefacts of imagination constrained by reason, teaching others (and machines) how to fly safely.

Renascita?

I’m afraid the choice of “renascita” comes from my personal obsession with the 15th and 15th centuries…

The term was first used by Giorgio Vasari to describe the Renaissance — not as nostalgia, but as a rediscovery of proportion, clarity, and disciplined imagination. The same thing is happening in software. We’re rediscovering that writing — precise, structured, living writing — is a foundation of creation.

In the last century, we frequently focussed only on writing code for compilers. In this one, we write for interpreters: humans and AIs alike. The compiler of the future is not just a syntax checker; it’s an intelligent assistant, an architectural critic, a reasoning partner. Documentation — or more precisely, specification — is what tells it what “good” means.

Specification-Driven Development (SDD) is the embodiment of this renascita.

It’s documentation raised to the level of design language — not static commentary, but executable intent. A well-written specification defines not only what the system should do, but why it matters, how it will evolve, and where its boundaries lie. It becomes a dialogue between authors and agents, an explicit expression of the team’s collective reasoning.

In SDD, the spec is a source of truth.

It guides the code, the tests, the docs — all derived artefacts aligned with a single coherent narrative. It’s the bridge between concept and implementation, between human context and machine execution.

When we move from documentation as an afterthought to specification as a first act, something powerful happens:

• Ambiguity dissolves before it metastasizes into bugs.

• Teams negotiate meaning rather than syntax.

• AI agents can infer, validate, and extend safely.

• The system’s logic becomes auditable, explainable, and habitably human.

This is what Vasari meant by renascita: the rediscovery of mastery through clarity. The Renaissance masters didn’t just sketch; they specified proportions, materials, and light. The result wasn’t rigidity, but reproducible beauty. So too with our software: when we specify well, we create living architectures that can be reasoned about — by humans and by the intelligences we build.

The new artisans of our age are those who can write systems into being. Not merely coders, but documenters of intent. Architects of meaning. Practitioners of a new literacy, where every line of specification is an act of teaching for humans and AI Djinn coders alike.

When you code with the Djinn, what you don’t write clearly you’ll have to debug endlessly

Documentation tells you what was built. Specification tells you how things should be built, what needs to be built, and why.

Specification-Driven Development (SDD) closes the gap between documentation and execution. It ensures that your source of truth is not scattered across PowerPoints, Jira tickets, or human memory, but encoded in structured, testable form.

This is the foundation of what Guy Podjarny calls the “specification-first mindset” — where specifications don’t just describe systems, they govern them. Whether expressed as OpenAPI definitions, schema contracts, or infrastructure policies, specifications become a shared trust boundary between humans, AI agents, and automation systems.

Podjarny’s work reminds us that specifications are not paperwork; they’re guardrails for creativity. They allow us to move fast without breaking meaning — or security. In a world where AI systems increasingly act on our behalf, those guardrails aren’t optional. They’re the scaffolding of safety.

This changes everything for AI-augmented development:

• Agents can interpret specifications directly, generating and verifying code within defined boundaries.

• Compliance, observability, and security become emergent properties, not bolt-ons.

• Human teams communicate in a shared declarative language that AI can extend and reason about.

SDD turns the dream of “living documentation” into a practical, operational habit.

Some Practices to Consider

• Explore every feature as a specification. Treat the spec as a contract of meaning — reviewed, versioned, and evolved like code.

• Write declaratively. Describe behaviour, not implementation. Agents and humans both reason best from intent.

• Make specs executable. Back them with validation, property tests, or code generation. The tighter the feedback loop, the healthier the documentation.

• Unify docs, specs, and observability. The spec describes what should happen; observability shows what did happen. Together they complete the loop.

• Build spec literacy. Teach every developer to write and reason in structured prose and formal models — it’s the grammar of the next era.

• Treat your specs as artefacts of trust. A clear, auditable spec is the cornerstone of ethical AI and resilient automation.

Some things to avoid

• Specs as bureaucracy. A bad spec is worse than none. Specifications must clarify, not constrain.

• Lack of ownership. If no one curates the spec, entropy wins. Assign stewardship.

• Over-automation. Specs should guide AI, not surrender to it. Keep your humans in the loop.

• Semantic drift. Keep specs synchronised with reality through regular review and comparison to observability. Feedback loops, as always, are key.

The renascita of documentation through specification-driven development is not nostalgia — it’s literacy. It’s how we teach machines to understand us, and how we keep understanding ourselves when we engage with the creative endeavour of software engineering.

When code becomes transient, meaning must endure. The specification is our fresco — a surface where art meets structure, intention meets execution.

Further Reading

• Giorgio Vasari, Lives of the Artists (1550) — origin of renascita.

• Daniele Procida, Diátaxis Documentation Framework.

• Richard P. Gabriel, Patterns of Software — on habitability and the art of readable systems.

• Guy Podjarny, Specification-Driven Development and related writings on schema governance, OpenAPI, and automated trust boundaries.

• Kent Beck, Tidy First? — the discipline of making change safe and legible.

A Tale of Two Agents

A start-up built a “workflow agent” that promised end-to-end automation. It chained prompts, APIs, and secret logic in a massive YAML file.

When it worked, it felt miraculous. When it failed, nobody could debug it. The engineers had built a new BPEL — a tomb of tangled reasoning. The magic had turned into bureaucracy.

Another team built a constellation of small agents. One parsed customer intent, one fetched data, one wrote summaries, one validated compliance. Each spoke structured text, each logged everything. They piped context between themselves like Unix tools.

The system was simple to inspect, easy to extend, and resilient to change. They hadn’t built a “super-agent.” They’d built a society.

Walking in the footsteps…

Every AI agent engineer is, knowingly or not, walking in the footsteps of the designers of Unix.

The agents we build today — those polite, tireless djinn of software — are not so different from the small, composable programs that live in the Unix shell. Each is designed to act, respond, and cooperate through a universal language: text streams, clear inputs, predictable outputs. Each is meant to do one thing well, and to compose gracefully with others.

But it’s east to forget the humility that made Unix thrive.

To begin to dream of giant agents: omniscient orchestrators, magical assistants that “just know.” To builf sprawling automations that hide their workings, and workflows that seem to think but cannot be reasoned about. To move from composition to control — and that’s how magic becomes mess.

Unix was never magic. It was honest.

It said, “Here is what I do. Here is how I fit with others. You may pipe me, extend me, or replace me.” That honesty made it habitable for humans. For AI agents, the same rule holds.

If we want autonomous systems we can trust, audit, and evolve, they must live by Unix’s design ethos: simplicity, transparency, composition, and respect for the user’s intent.

Imagine a world where every AI agent is a small command in a great shell.

You don’t build a monolithic “super-agent”; you build a garden of little thinkers — each with a clear goal, a simple interface, and the ability to pass context to others. You compose cognition like you once composed code.

The future of AI agentic systems will depend less on model power and more on interface philosophy and domain integration. Unix already solved the interface problem half a century ago. The lesson is waiting to be re-learned.

Build AI Agents like Unix commands — small, composable, explainable, and inspectable

Work towards trustworthy, composable, auditable AI agent ecosystems.

Your context is complex and multi-domain and where autonomy meets accountability. Design small, declarative, message-based agents that can compose like Unix tools, focussing on transparent inputs/outputs and observable behaviours.

Some Practices to Consider

• One Intent per Agent — Each agent should pursue a single coherent goal — summarise, diagnose, plan, generate — and expose that intent clearly. Avoid “Swiss Army” agents.

• Pipeability — Design outputs to become another agent’s inputs. Use universal data formats — JSON, Markdown, structured text — the new stdout/stderr.

• Text and Traceability — Prefer textual protocols and logs over opaque embeddings or hidden state. Make reasoning readable by humans and verifiable by other agents.

• Convention over Control — Don’t over-orchestrate. Define conventions for inter-agent communication (contracts, schemas, message envelopes), but let emergent collaboration arise.

• Small Agents, Big Ecosystems — Favour a federation of tiny, purpose-built agents over centralised monoliths. Evolution through diversity and iteration — the Unix way.

• Observability is Literacy — Logs, traces, telemetry, and “reasoning journals” are the new grep, cat, and less. They allow humans to read what the agents have written.

• Open Habitat over Closed Platform — Build environments where agents can live, not prisons where they’re scheduled. AI habitats need rules of cooperation, not cages of control.

Some things to avoid

• Over-Orchestration: Repeating the sins of BPEL — monolithic control flows instead of composable collaborations.

• Opaque Reasoning: Agents that can’t explain themselves.

• Magic Interfaces: GUI or API layers that hide context from both human and agent.

• Isolationism: Agents that can’t share state, learn from others, or be replaced safely.

Unix’s greatest insight wasn’t about files or processes — it was about composability of thought.

The same principle can save AI engineering.

If we build agents like Unix tools — small, transparent, testable, composable, provenance-aware — we build systems that can be auditable by design.

If we build them like magic boxes, we inherit the same technical and ethical debt as the opaque orchestration tools of the past.

It’s quite likely we stand in a third age of literacy. The first was born from the presses of Guttenberg, Caxton of Plantin — when reading and writing words remade civilisation.

The second was in code, where writing for other humans to read and explore was paramount to evolve complicated systems of value.

A third is, probably, here now, explored by humans and LLMs — silicon Djinns that read, reason, and rewrite code alongside us.

The Embabel framework, and its exemplar Tripper, show what happens when we stop chaining prompts like oracles and start composing systems like engineers again. They remind us that AI agents aren’t a revolution in intelligence—they’re a restoration of structure. A return to a discipline of goal, plan, and act, wrapped in careful deterministic clarity.

Most developers are still wandering the LLM wilderness, throwing ever-longer prompts at the void, mistaking clever outputs for reliable systems. Embabel’s gift is perspective: it treats LLMs not as magicians, but as tools—powerful, but bounded. It reclaims agency from the abyss of stochastic chaos and returns it to where it belongs: in the design.

Where the early prompt-chains of 2023 were the spaghetti code of the AI era, Embabel offers something closer to the structured programming of agent design. And Tripper, its travel-planning demo, is no toy—it’s a proof of concept for a new kind of software literacy: one that blends deterministic planning, domain modelling, and explainable autonomy.

It’s an example where we can practice the crucial skill for this new literacy age, of reading, exploring and comprehending1.

Read, First

Try it now. Clone Tripper, or just explore on GitHub, and see what you notice.

Maybe don’t read the next section until you'‘ve explored the codebase a bit. If there’s anything you notice that I missed, please leave a comment on this post.

What I Noticed while Reading Tripper

After taking the time to explore Tripper’s code, here are the highlights from my code reading journal.

Reading Note. 1 Build Goals, Not Prompts

Agents must know what they want, not just what to say next.

Embabel’s Goal-Oriented Action Planning (GOAP) separates intention from implementation. Each goal is a navigational star; actions are the waypoints. You don’t tell the agent how to get there—you define the physics of the world and let it plan.

Suggested Practice

Model your agent’s goals and actions as first-class citizens. Prompts become implementation details, not the architecture.

Reading Note. 2 Type Your World

Every meaningful agent is a philosopher of its domain.

Embabel enforces strong typing and domain models: trips, legs, itineraries—not strings, but structures. Typed objects make it possible to reason, validate, and test. They bridge the cognitive gap between code and cognition.

Suggested Practice

Define, or even reuse existing, domain objects early. Let the agent manipulate data, not prose.

Reading Note 3. Separate Actions, Goals, and Conditions

In Embabel, every action declares its preconditions and postconditions.

This turns the agent’s reasoning into a composable system of cause and effect. You can rewire goals without rewriting prompts, extend capabilities without breaking the flow. It’s loose coupling between actions and goals allowing replanning and fine-tuning as an agent function.

Suggested Practice

Design each action like a function, not a fantasy. Give it testable inputs, outputs, and invariants.

Reading Note 4. Mix Models Intelligently

Not all intelligence costs the same.

Embabel lets you pick the right LLM for each job: a heavyweight reasoner for thinking, a lightweight one for phrasing. Tripper uses Claude Sonnet for deep synthesis, GPT-4.1 mini for speed. It’s compositional intelligence—fit for purpose.

Suggested Practice

Treat models as interchangeable tools, not idols. Configure, don’t consecrate.

Reading Note 5. Determinism Is a Feature

Chaos may be creative, but determinism is humane.

By separating planning (GOAP) from LLM execution and reusing domain design, Embabel achieves predictability. Plans are inspectable, debuggable, explainable. If a condition fails, the agent replans—not panics.

Suggested Practice

Let your agent’s mind be open, but its methods be deterministic. Replanning should be part of the architecture, not an afterthought.

Reading Note 6. Bring Tools into the Light

Embabel integrates with the Model Context Protocol (MCP) to give LLMs structured, scoped access to real tools—web search, maps, APIs. Each action decides which tools it can use. The agent doesn’t “hallucinate” a browser; it invokes one.

Suggested Practice

Expose capabilities through explicit interfaces. Never trust a model to invent your integration.

Reading Note 7. Test, Trace, and Tell the Story

Agents are software. Software demands tests.

Embabel’s typed flows allow unit testing, integration testing, and event streaming of each action. Tripper’s live UI even reveals the plan’s evolution: a narrative of decision and consequence.

Suggested Practice

Instrument your agents. Emit events. Record their reasoning paths. A black box is not a teammate—it’s a risk.

Reading Notes 8+. Some things to avoid & A Helpful Checklist

1. The Prompt Trap — Treating the LLM as the architecture, not a component.

2. String Soup — Failing to model domains as types leads to brittle prompts.

3. Overfitting the Plan — Hardcoding paths instead of letting GOAP decide dynamically.

4. Single-Model Monotheism — Assuming one model fits all actions.

5. Blind Trust — Forgetting to validate outputs or to re-plan when assumptions break.

6. Silent Failure — Omitting observability; not knowing why the agent did what it did.

A Helpful Checklist

• Define explicit goals and actions with pre/postconditions

• Keep planning deterministic, execution flexible

• Model your domain with types, not text

• Use multiple LLMs for cost and capability balance

• Validate, test, and replan on failure

• Scope tools explicitly through MCP or similar protocols

• Emit structured logs and visualise plans for explainability

Hungry to Read More?

If you want to explore more code, the Embabel team are curating a collection of resources (both code and prose) in the Awesome Embabel repository.

And here’s why you should want to read more code.

Most developers think they know how to read code. But we’re not getting anywhere near enough out of the practice and in the age of AI augmented software development, this is a missed opportunity to practice a key skill.

We skim. We pattern-match. We jump to the bit that looks familiar and hope muscle memory fills the rest. But as Felienne Hermans reminds us in The Programmer’s Brain, reading code is not a passive act — it’s an active cognitive workout. It’s where understanding is forged, where syntax becomes semantics, and where intuition is born. You don’t learn programming by typing; you learn it by decoding the minds of others.

Reading code is reading intent. It’s reading culture, constraint, compromise — the archaeology of every decision. And in this new world of Djinn-augmented development, where AI can summon an entire codebase before lunch, reading becomes the act that keeps us human. The Djinn can write, sure — faster, cleaner, maybe even smarter — but it cannot care. Only you can trace the thought, spot the flaw, feel the pattern.

So read more code. Read code like literature. Read until you can sense when a line was written in fatigue or joy. Because the future belongs not to those who can prompt the Djinn — but to those who can truly read what it writes.

Further Reading

• Felienne Hermans, “The Programmer’s Brain”

• Embabel – GitHub

• Jeff Orkin, “Goal-Oriented Action Planning for Game AI”

• Rod Johnson, “Domain-Integrated Context Engineering” (DICE)

In agentic systems, the most valuable question isn’t what did the AI do? — it’s who asked it to do it, and why?

Software engineering has long relied on version control to preserve intent: commits, diffs, and signed changes anchor our trust in an ever-changing codebase. But as we step into the world of collaborating AI agents, those human anchors are dissolving. Actions are not taken by a single author, but by networks of agents reasoning across context-rich domains.

The result? Unprecedented power, but also a dangerous opacity. When a platform incident response, a customer communication, or even a regulatory filing is drafted by a chain of AI assistants, who bears responsibility for what emerges?

This is where provenance becomes key.

Provenance is not metadata. It is the story of accountability — a verifiable lineage of thought, from the human who conceived the goal to the final artefact produced by agents acting on their behalf.

In the pre-agentic era, we used Git commits as the ledger of authorship. Each change had a name, an email, a hash — a human fingerprint. In the agentic era, we need the same concept for intent, not just for code. A world where every AI decision and artifact carries a cryptographically verifiable trail back to its originator.

Without this, AI-augmented development becomes a confusing labyrinth — plausible but untraceable. With it, we can finally build AI systems that don’t just act intelligently, but accountably.

Subscribe now

Trace the origin, or you cannot trust the outcome

In human teams, accountability emerges through shared memory, dialogue, and documentation. In AI teams, we must embed that same accountability in code.

Provenance signing replaces enables confidence and trust with cryptographic proof — turning every AI agent from a mysterious collaborator into a responsible contributor.

In this accountable world, agents establish a “Provenance Graph” where every goal or scenario begins with an immutable “signed intent envelope” that travels downstream as the root of the provenance graph. An intent envelope ensures that any agent, sub-agent or collaborating model is operating under a verified lineage of human authority and intent.

Each agent would then append its own trace nodes to the graph:

• Agent ID (and model fingerprint)

• Execution context (inputs, embeddings, environmental vars)

• Result hash and signature (local signing key)

• Parent lineage (the node it derived from)

These form a DAG (Directed Acyclic Graph) of agent interactions — a verifiable audit graph from human → agent → artefacts and outcomes.

When multiple agents collaborate:

• Every message or artefact transfer includes lineage metadata

• The recipient agent verifies upstream authenticity before use

• The entire workflow becomes auditable within theProvenance Graph, which can be exported or queried like a Git commit tree

Think of this provenance graph as “Git for agency, not just for code.” A useful graph that:

• Enables audit trails and digital attestations of AI-assisted change in regulatory & legal contexts.

• Every action is human-anchored — no “rogue reasoning”.

• Complex multi-agent runs can be reconstructed deterministically.

• Builds verifiable transparency between humans, AI, and institutions.

• Provide operational forensics when something goes wrong as you can walk the lineage to the origin intent.

Without a provenance graph, accountability with a farm of agents is, at best, a forensic confusion. At worst it is an impossibility. To truly trust agents in production, accountability is not just a nice-to-have feature — it is essential to achieve auditable from human intent to AI artifacts and interactions, across agents, domains, and time.

Some Practices

• Record and sign every Action, Goal and potentially re-planning step outcome with the human originator’s identity and timestamp.

• Build and persist the Provenance Graph alongside your embeddings and traces.

• - Present provenance paths in your observability dashboards, making them explorable by auditors and engineers alike.

Some things to avoid

• Ignoring provenance because “it slows things down”

• Treating provenance as optional metadata rather than a core runtime invariant.

• Over-centralising signatures (one key for all agents), which erodes individual traceability.

• Storing provenance externally without tamper protection.

A Checklist

• Every Goal is signed by a human originator.

• Every Agent logged activity is signed and hashed.

• The full lineage is queryable.

• Provenance data is part of observability, not an afterthought.

• The system can answer: who asked, what was done, by whom, and why.

If the Renaissance gave us the patent system to honour the origin of thought, and the Enlightenment gave us authorship and copyright law clarity to honour expression, the AI era must give us provenance and cryptographic signatures to honour the origin of intent.

As AI systems proliferate across development environments, provenance signing and tracing serve three essential functions:

1. Accountability — every AI act is rooted in a signed, human-originated intent.

2. Auditability — every derivation, transformation, or collaboration is cryptographically linked.

3. Reproducibility — given the provenance graph, the entire reasoning path can be replayed and verified.

For regulated domains like banking, healthcare, or safety-critical engineering, your agents being provenance-aware is not optional.

It is the difference between a useful assistant and an unrecognisable, uncontrolled actor.