loop-engineering.md

# Loop Engineering

How the work gets done when I'm not the one building it. If *Principles* is the
belief that great work happens in spirals, this is the spiral made
operational — a repeatable cycle where agents plan, build, and check each
other, and my job is the part that stays mine: writing the tickets and deciding
whether the result is right.

The term is fuzzy in most places it's used, so here's the concrete version:
the parts, how I actually run them, and — just as important — the parts I
deliberately don't.

## The building blocks

Most descriptions of loop engineering converge on the same six pieces. I hold
myself to them honestly: some I run in full, some I run lighter than the
purists, and one I skip on purpose.

### Roles, not one agent

The strongest idea is splitting responsibility across agents that can't grade
their own homework. An **Architect** turns a ticket into a plan. An
**Implementer** changes production code and nothing else. A **Verifier** writes
the tests and decides whether the result is real. The separation is the whole
point: the agent that wrote the code is the worst possible judge of whether it
works. When I report a bug, the loop starts by writing a failing test that
reproduces it — then the fix has to make that test pass. Not the other way
around.

### Isolation

Agents working in parallel on the same repo will overwrite each other. Each one
gets its own git worktree and branch, does its work in isolation, and hands
back a clean diff. Cheap discipline that removes a whole class of collisions
before they happen.

### State that outlives the conversation

A loop that runs longer than one session needs memory that isn't the chat.
Tickets as small markdown files — open means to-do, done means gone. A shared
plan the Architect writes and the rest of the team reads. And a persistent
memory of what was learned, so the next cycle doesn't re-derive what the last
one already knew.

### Skills over re-explaining

Codified, reusable workflow steps — how to write a plan, how to pull the next
ticket, how to run a launch — so agents stop rediscovering the same conventions
every session. I keep these lean and, deliberately, separate from *knowledge*.
The domain, the architecture, the design rules live in their own documents. A
skill is a verb; the knowledge base is the world it acts on. Bundling them is
the most common way skills rot.

### Connectors

The bridge from suggesting to acting — the ability to open the PR, run the
migration, read the analytics, not just describe them. This is where I'm
further along than most write-ups assume, because the tools are already wired:
the database, the product analytics, the deploy path, the repo itself.

### Automation, held back on purpose

Scheduled or event-driven triggers that discover work and kick off a cycle
without me. I run these lightly and by choice. If everything fired
automatically, I'd wake up to a pile of unapproved work and spend my day as a
reviewer of things I didn't ask for. So the trigger is still me: I mark a set
of tickets ready, the team works them by priority, and anything high-risk stops
and asks first. That last assessment is the Architect's job.

## What I actually run

Not a fully autonomous machine — an accountable one. The pipeline that stands
up a new project already works this way: a planner writes the plan, a
scaffolder builds the skeleton, a design agent applies the system, an analytics
agent wires the taxonomy, a docs agent leaves the map for the next session.
Different hands, one clear handoff between each.

For work on an existing codebase, the same shape holds — plan, implement,
verify, loop until the tests are green — expressed as a workflow: control flow
in code rather than prose conventions holding a process together with hope.
That's the real upgrade over the artisanal version. The loop isn't a folder of
files the agents promise to respect. It's a script that runs them.

## Where I stay in the loop

I don't write code. My job is to be clear about what to build and honest about
whether the result is right — I write the tickets and I review the outcomes.
Most of the time I approve. Sometimes I write more tickets against the review.
The loop does the building; I stay responsible for the direction and the
judgment.

That's the honest state of it: the loop doesn't run without me yet, and I'm not
in a hurry to make it. The point was never to remove myself — it was to spend
my attention on the one decision that actually needs it, one at a time, and let
the cycle carry the rest.