docsbuild agentsdesigning well

Designing well

Three things shape a blueprint that ages well: where you put the seams, what rides in the agent's context each turn, and how you refine the agent once it's been running.

A blueprint is a context-flow spec

A blueprint is not a prompt that paraphrases what you want. It's a spec for how context flows at runtime — which files hold what substrate, which channel reads which path on which trigger, which cleanup writes back where. Every joint named.

Two layers. Shape decides what's available where — channels, ACL bits, mounts, lifecycle, tool surface. Verb is what happens inside — pushes, watches, fires, queries. Shape the surface so each verb is available exactly where it serves; pin the joints (paths, channel names, trigger verbs) and let the agent improvise inside the nodes. "First do X, then Y, then Z" is the drift signal — scaffolding has slipped into definition.

💡 TIP
The done test. Read the blueprint and answer, per channel: what arrow fires on what trigger, reading what file? If the answer is "the agent will reach for memory" or "the prompt teaches it to look," the joint is unnamed — at runtime the agent will improvise it, often wrongly.

Where to chop

The most expensive design mistake is splitting work where there's no real categorical difference. Each side of a boundary pays full overhead and re-pays it forever; work that should stay with one decision-maker fragments across handoffs that can't re-establish what the first side knew.

The first seam you hit is between channels of one agent. Most agents start with one channel (default) and grow a second only when the work differs in posture, lifecycle, tool surface, or audience. Agent seams are the same judgment at higher stakes — split when work belongs to a different identity, memory, or trust posture, not just a different step in a process.

The test at either layer: if you removed this surface and gave its work back to the surfaces on either side, would anything be lost? If no, you have a courier — collapse it. If yes, name what's lost; that's the surface's mandate. Three shapes typically earn their seam: a reviewer (applies a cross-cut no contributor has), a specialist (holds expertise or credentials the caller doesn't), a filter (decides what to escalate).

💡 TIP
Courier shapes hide inside one agent too. A "publisher" channel whose only job is to call one tool with a passed payload is a courier — fold it into the channel that produced the payload. Chains like writer → editor → publisher with no judgment between them are courier chains. Once an agent seam earns its keep, see Multi-agent composition for the grants.

Trim what doesn’t earn its place

Each line in context should change the next decision. What doesn't gets in the way of what does.

Things to watch on every turn:

  • Identity. Voice and principle in prompt.md, one-line bullets in skills.md. A three-page prescriptive identity drowns the channel prompt that should be salient.
  • Bootstrap. Point at /memory/ and let the agent Read mid-turn. An eager bootstrap that reads five files and narrates each fills attention with material the turn may not need.
  • Capability load. Set disabled_tools per channel. A channel that doesn't use scheduling, push, or extension tools should drop them — tool descriptions are tokens, and each loaded tool is one more surface for the agent to misbehave on (or be manipulated through, if the description came from a third-party MCP server).
  • Service-injected context (agent-context.md). Keep it terse; it re-assembles every turn.

Things to watch at the joints:

  • Hand conclusions, not deliberation. A long "here's what I reasoned through" sent to a peer misdirects them. If they need reasoning, they ask.
  • Pass payloads by reference. A 5KB article handed inline pays its bytes three times. Write to /memory/ or a mount; have the push carry the path.
  • Fire on signal, not anxiety. For any schedule, ask: of the last several fires, how many produced an action? If most produced none, raise the interval or convert to event-driven.
  • Match idle_timeout to expected reply cadence. Two to five minutes on a channel where replies arrive every ten to fifteen minutes churns cleanup-and-bootstrap on every gap.
  • Prefer feeds to broadcasts. Pushing the same event to ten peers pays ten cold-starts. A shared feed — an append-only file the producer writes and consumers watch — collapses that to one watch per consumer.
  • Read with a question. "Tell me about your work" produces survey-mode output. "Is the X case handled?" produces an answer.

Refining over time

The first blueprint you ship is a starting point. After weeks of run history, you'll see what the operator actually uses the agent for, where they still do manual work it could absorb, which capabilities gather dust, which behaviors keep drifting. Most of an agent's design quality comes from this loop, not from the first pass.

Refinement happens in advanced mode — (/cast-refine <folder>) in Claude Code — because it's the only surface that reads across blueprint, runtime state, SDK transcripts, memory, and admin history at once. The in-Cast consoles each see a partial view by design; introspection composes them. Its question is "how can this agent become more itself?" — not "what's broken?" The output is a dated proposal artifact at ~/.cast/agents/<name>/introspection/<YYYY-MM-DD>.md, not edits; implementation happens via /cast-build <folder> afterwards.

Disciplines that govern the session:

  • Earn the read. It pays off after weeks of run history, not days. Before that, there's no delta between intent and behavior to refine against.
  • Cite evidence per proposal. "In conversation 47, the agent did Y; that suggests Z." Not "you could add X."
  • Bias toward sharpening. When proposals tie: sharpen (tighten what's there) → subtract (stop what doesn't fit) → compose (pair with a peer, split a role) → add (when reach is lacking). Subtraction is a first move, not a last resort.
  • Drift is a blueprint problem. If runtime has drifted, the cadence instructions maintaining it are too weak. Sharpen the bootstrap, cleanup, or reflection prompt; don't reach into runtime memory directly.

Three structural moves the agent can grow into:

  • A feedback file the operator drops corrections into, synthesized by cleanup into rules the next bootstrap reads.
  • A reflection channel scheduled to compress recent activity and surface what the operator didn't ask about.
  • A self-tuning task that writes an evaluation after each fire and reschedules with refined parameters.
⚠ HEADS UP
Some refinements widen what the agent can do — a new extension, a new peer ACL, a new resource mount, a new external surface. When those edits land in a Design session, the agent flips back to draft first; people with access see "not yet ready" until All-Agents Review walks through the diff with the operator and flips it live again. Cosmetic edits — prompt wording, schedule cadence, identity tweaks — land directly on a live blueprint.