Experiments with Agent Handoff (v1)

v1 documentation of a personal experimental method, born as a support layer for cusp (Custom Sandbox Pipeline)

Why this article exists

This text wasn't born from an intention to create a methodology. It was born from a concrete problem: while designing cusp, a personal deployment tool, I realized that the real bottleneck wasn't the code — it was the relationship between me and the AI agent that was going to build it with me. Every new session, the agent would lose context, infer decisions I'd already made, and repeat questions we'd already resolved. The friction wasn't in the infrastructure. It was in the communication.

I'm documenting the method I built to fix that — with the honesty of calling it what it is: an experimental prototype, v1, tested on a single real project, built in conversation with an AI agent, and reviewed afterward against published literature to separate what's genuinely mine from what already existed under a different name.

The real problem: inference as a source of error

When an agent picks up a project with only the source code to go on, it has to reconstruct the architecture, the flow, and the design decisions from the implementation. That reconstruction process is, structurally, an informed guess — and that's where the error sneaks in: the agent isn't reading the truth of what was decided, it's inferring a hypothesis from symptoms.

I'm not the first to identify this problem in those terms. Recent work on agentic software development describes the same phenomenon with precision: when an autonomous agent, a newly onboarded engineer, or a senior developer navigating unfamiliar code encounters a business task without institutional context, the result is always the same — guesswork, cascading corrections, and a disproportionate tax on senior engineers who end up manually supplying what others can't infer. The same work draws the explicit parallel: it's structurally the same cycle a new engineer goes through entering someone else's codebase, just compressed into context window turns instead of weeks.

The shift: it's not documentation, it's a state transition protocol

For much of this build, I thought of the system as "documentation optimized for AI." A later conversation, comparing notes with another model on the design, made me see something I hadn't named: I wasn't documenting a project — I was designing the exact point where knowledge stops being a conversation and becomes something an agent can execute without having been part of the original conversation.

There are two working modes that shouldn't be mixed. One human — where everything is ambiguous, shifts, gets debated, gets reverted. And one operational — where an agent needs to start from a consistent state, not from the full history of how we got there. The system I built works, in practice, as the conversion point between the two: conversational planning → a moment where that knowledge gets fixed in .agent/ → a new session, with no memory of the previous conversation, that drops straight into the operational phase by reading that fixed state.

An honest clarification: the idea of consolidating conversational knowledge into a structured artifact isn't originally mine. Recent research on expert domain agent development describes a four-phase cycle — conversational immersion, experiential accumulation, deliberate crystallization, and grounded application — where crystallization is explicitly a deliberate, periodic process that consolidates patterns into structured knowledge assets. What I describe is a much more bounded instance of that same general idea: not a continuous learning cycle for an expert agent, but a single fixed cut-point between planning and execution, formalized as versioned files in two distinct formats according to their function.

The method: two languages, two purposes

`.md` — for the AI to think

A narrative context file (CONTEXT.md) explains philosophy, intent, design decisions, and their reasoning. It's prose, deliberately. It's there so the agent understands why the rules exist — it's never executed directly, only consulted when an explicit rule doesn't cover a case.

`.toon` — for the AI to execute

TOON (Token-Oriented Object Notation) is a tabular format designed for language model consumption: it declares fields once and transmits rows of data without repeating structure, unlike JSON or markdown, where each object repeats its own keys. Public benchmarks report a token reduction close to 40% versus JSON, with better parsing accuracy — 76.4% versus 75.0% in the TOON project's own tests.

That token savings is real, but it's not the central argument of the method. The central argument is structural: a .toon file leaves no room for prose, and therefore no room for interpretive ambiguity. A rule like git_push,FORBIDDEN_ALWAYS can't be read two ways. A sentence saying the same thing can.

An additional honest technical note: TOON's token advantage depends on content size — the fixed cost of "teaching" the model the syntax can cancel out the savings on very short outputs, and it becomes worthwhile when the content grows enough that the accumulated savings compensate. In a system of rules that grows feature by feature, that condition is met quickly.

I haven't found, in the material I reviewed, another system that uses this separation of format (not just file or phase) based on the cognitive function of the content — prose to reason, atomic table to execute. That specific distinction is, as far as I could verify, the most defensible original contribution of the entire method.

FEATURE.toon: operational representation, not documentation

Each feature of a project — not the whole project, each individual piece — gets its own .toon file, named in uppercase after the feature (WISHLIST.toon, PUSH.toon), living inside the actual folder for that feature in the code.

That file explains the complete lifecycle of the feature to the agent in a single read: where the logic originates, every transformation it goes through, where it ends, what data types it uses or produces, what it depends on. No prose. No need for the agent to open the source code to understand the intent — the agent already saw it once, and that knowledge gets externalized so the next agent doesn't have to reconstruct it by reading code again.

This also connects to a problem already named in the literature: the bottleneck in agentic software development isn't model capability, it's knowledge architecture — when institutional knowledge gets trapped in formats designed only for human interpretation, every new consumer (agent or person) repeats the same guessing cycle. FEATURE.toon is my specific resolution to that problem at the level of a single piece of code, not at the level of an entire organization.

It comes with a strict sync rule: if the feature changes, the .toon changes in the same cycle. A .toon describing a version of the feature that no longer exists can never be allowed to sit — because that would be worse than having no .toon at all: it would be a source of truth that lies with authority.

Governance hierarchy: why order matters

The rules that govern the agent (RULES.toon) follow a fixed cascade:

Security — hard prohibitions (never push, never commit without approval, never modify code without asking first)
Scope — what the project is and isn't
Permissions — what the agent can do, in detail
Automation — what fires without asking permission (the bounded exception)
Ambiguity protocol — what to do when no rule covers the case
Meta — information about the document itself

The order isn't aesthetic. When two rules conflict, the category that appears first wins — that resolves priority without the agent having to infer which one weighs more. It's, in essence, a handcrafted implementation of what the industry is starting to formalize as policy-as-code for agents: permission rules, approval requirements, and limits translated into something verifiable and versioned, not rules that exist only in the head of whoever wrote them.

An unplanned finding: the self-propagating bootstrap

During the build I tried something outside the original plan: instead of writing AGENTS.md by hand upfront, I instructed the agent to read RULES.toon and CONTEXT.md first — and let it, already governed by those rules, generate its own AGENTS.md as a pointer toward them.

The result was better than planned: that AGENTS.md isn't a promise from me about how the agent should behave — it's an artifact the agent produced after understanding the system. It reflects real comprehension, not expectation. From that point on, any new agent entering the project finds AGENTS.md through the already-standard ecosystem convention, follows the pointer, and gets governed the same way without manual repetition. This specific pattern — deferred pointer generation, posterior to comprehension — isn't something I found documented in the material I reviewed.

Related work

No idea is born in a vacuum, and I'd rather explicitly name where this method treads ground already explored by others than leave it implicit:

AGENTS.md (open standard, now under the Agentic AI Foundation of the Linux Foundation) addresses where an agent's context lives. This method doesn't replace it — it uses it as an entrypoint, and builds the format separation the standard doesn't define.
Knowledge Crystallization (2026 research on expert domain agent development) describes the consolidation of conversational knowledge into structured assets as a continuous, cyclic process. This method applies a much more bounded version of the same idea: a single cut-point between planning and execution, not a continuous learning cycle.
Knowledge Activation (2026 research on enterprise agentic software development) names the same underlying problem — institutional knowledge trapped in human-only formats, and the structural parallel with human onboarding. This method is a specific implementation, at the scale of a single personal project, of the same diagnosis.
Policy-as-code for agents — the formalization of governance rules as verifiable code, rather than prose documents, is a trend already underway in the industry (e.g., agent control specifications published by infrastructure providers in 2026). The RULES.toon hierarchy is one person's handcrafted implementation of the same idea.

What this method is NOT

Not formal Spec-Driven Development. SDD is a broader discipline, with tooling, automated validation, and guarantees this method doesn't have yet.
Not tested at scale. It ran on a single project, in active development, not in production with multiple collaborators.
Not the first work to identify these problems, as documented above. What it contributes is a specific combination — format separation by cognitive function, lifecycle specification per feature, a fixed rule hierarchy, and the deferred bootstrap pattern — not the diagnosis of the problem itself.
It doesn't eliminate exposure risk, it shifts it. Publishing atomic, textual governance rules is potentially a readable surface for anyone wanting to manipulate an agent that follows them. My resolution was to separate real governance (private) from a curated example (public, illustrative, not executable against anything real) — that's a mitigation, not an elimination.
It doesn't replace human review. The agent proposes changes when it detects fixes, errors, or contradictions — it never executes them without explicit approval.

What I'm after, in one sentence

I'm not trying to sell a finished methodology or claim an isolated discovery. I'm trying to document — with real evidence from a genuine work session, in honest conversation with already-published literature — a specific combination that reduced inference: the most silent source of error when an agent acts on a project it didn't write from scratch.

This is v1. The intention is to keep iterating on cusp as a test case, and to come back and write about what changes, what breaks, and what actually holds up over time.