How I currently run agents

Some notes on how we run coding agents these days.

The cockpit

• One launch point for all the projects we manage. The cockpit.
• It holds what is not specific to any project: our delivery preferences, how we operate agents, and other generic instructions.
• Akin to our personal tastes. It then adjusts to each project's own instructions.
• We also keep a lookup directory of each project, a mixed bag of notes, diagrams, reports and whatever else piles up.
• We normally run a separate session per project, each in its own terminal pane. Nothing stops one session from handling several projects, I just find it easier to context switch when they're different panes.
• All markdown, no runtime.

A primary agent and its sub-agents

• I talk to one agent, the primary agent. It's the communication point.
• The primary agent splits the request into pieces and hands each piece to a sub-agent. Harness native sub-agents, nothing custom.
• A sub-agent doesn't get the whole conversation, it gets a brief:
  • which project, and which of its instructions to read
  • the piece it owns, and what it must not touch
  • what it's allowed to do
  • how to show the result, and where to report back
• It returns something compact: the result, what proves it, what's left, observations.
• We find the sub-agents still pick up each project's own style. Whether the project is spec-driven, BDD or TDD, the sub-agents follow along.

Protecting the primary agent's context

• The primary agent is the long-running one. It stays up across multiple requests. We normally give it long-horizon work, a set of features, user journeys, etc.
• We protect its context. Anything substantial goes to a sub-agent, even reading and searching.
• The raw logs stay with the sub-agents. The primary only keeps the intent, the decisions, a short summary of each return, and the coordination.
• The sub-agents talk to the primary, and the primary relays to other agents. We could probably change this, but it's working for us for now.

Fan-out, fold-in

We also use a mini workgraph approach.

• Fan-out. Split the work into bounded pieces and hand them out, in parallel when they don't touch the same files.
• Fold-in. The primary agent reads the returns, reconciles them, and runs the combined thing itself. A sub-agent saying done is input, not acceptance.
• We run it as a loop with progressive refinement, a thin pass across the whole thing first, then deeper each round. So agents don't forget, we ask them to keep the loop in the harness's own task list.

The agreement

A short doc every agent reads. Just guardrails, nothing fancy.

• Authority. To keep them from asking, and to stop them from doing bad things.
• Harness native first. To not build what the tool already gives us. Use what it has, no new machinery.
• Scope & sizing. To keep work from quietly growing. The request fixes what done is. Tiny work gets done directly. Bigger work gets split by outcome.
• Communication. To keep it readable, for me and for the primary agent's context. Outcomes and decisions, short.
• What done looks like. To stop "done" from meaning "tried". Judged by the outcome, not the activity.
• Continuity. To pick up where we left off without re-explaining. At a handoff or a pause, the primary agent leaves a pickup note in the cockpit.
• Lessons for learning. To not repeat mistakes we've already hit. Every return carries one observation, and lessons become proposed changes to the agreement.
• Staying focused. To keep them from drifting. Some rules exist only because current models slip. We call them shims, and they're meant to go once the models stop slipping.

We could probably write about focus, and human plus agent attention, next time. Also ledgers, ha... agents and ledgers, they match well together.

We have also recently started using a desk, to put several machines to work, minis and linux boxes inside a tailnet.