# Harness layering, and which parts transfer to a dedicated agent

Notes taken from a widely-shared account of building a personal *coding* harness on
pi ([@chasen_liao, 2026-08-27](https://x.com/chasen_liao/status/2092963119337476137)),
checked against what this repository actually runs. Recorded because the layering
is a good frame and because several of its specifics are actively wrong for a
service-embedded agent — and the reasons are worth stating once rather than
rediscovering.

## The frame: three layers

| layer | coding harness | this repository |
|---|---|---|
| discipline — durable, always loaded | global + project `AGENTS.md` | `.pi/SYSTEM.md` + `.pi/APPEND_SYSTEM.md` |
| capability — loaded when needed | Skills, hidden by default | tool list generated into the system prompt |
| control plane | third-party packages | one scenario extension + a loopback bridge |

The frame holds. What differs is every mechanism, and the differences are not
stylistic.

## What transfers

**Discipline belongs in a durable file, not in each request.** We reached the same
place from the opposite direction: per-request restatements of "which adapters
exist" were removed in phase 2 because they varied the prompt prefix and cost
cache hits (`pi-runtime-notes.md` §24).

**Don't pile on capabilities.** "Several dozen enabled made routing worse" matches
the reason Curator exposes five tools and not fifteen. Every tool is a branch the
model can take wrongly.

**Watch where context goes.** The article uses `pi-context-usage` for this. We take
the same numbers from `message_update.usage` in the RPC stream, which costs nothing
extra, and write them to `control_events` per turn. The article's reported 98%
cache hit is the single most useful figure in it, and it is what justified phase
3b's long-lived sessions; we measure 99.97% on a continuing conversation.

**One writer at a time.** Their rule for parallel subagents ("only one writer per
directory; reviewers may run in parallel because they are read-only") is the same
shape as Curator's: many read tools, exactly one write path through
`CuratorService`.

**No claiming done without evidence.** Their coding loop insists on it; Curator
enforces it mechanically, generating receipts from `tool_execution_end` rather than
letting the model narrate what it did.

**pi has no sandbox and runs at full privilege.** Stated as a closing caution
there; recorded as `pi-runtime-notes.md` §20 here, and the reason isolation is four
layers rather than a flag.

## What does not transfer, and why

**Third-party packages.** `pi install npm:...` is the article's main recommendation.
For a dedicated agent it is disqualifying: a package runs arbitrary code in the
same process as the agent, and Curator's whole posture is that the agent reaches
exactly five audited endpoints over loopback. The article says as much in passing
("look at the source and permissions before installing") — advice that scales to a
human's interactive tool and not to an unattended service holding tracker
credentials. `no_extensions = true` plus one reviewed extension stays.

**`AGENTS.md` as the discipline layer.** For an interactive agent in a repository
this is right. For us it is precisely the thing to block: `AGENTS.md` is discovered
from *every parent directory* of the workspace, so a file written for an unrelated
project leaks in. `--no-context-files` is the only switch that stops it, and it is
on. Discipline lives in the system-prompt files, which that flag does not touch.

**Skills as the capability layer.** Cannot work here at all: pi emits the skills
section only when a tool named `read` is active, and Curator's tools are all
domain-specific, so every `--skill` argument is discarded in silence
(`pi-runtime-notes.md` §23). The capability layer is generated into the system
prompt instead.

Beyond the mechanism, on-demand loading is *undesirable* for us: it varies the
prompt prefix, and a varying prefix is exactly what destroys the cache hit the
article is celebrating. Interactive sessions can afford it; a per-message service
cannot.

**Subagents and parallel lanes.** Curator answers one message about one library.
There is no plan to decompose. The article's own caution — "don't force the full
workflow onto a small task" — applies, and here every task is small.

**`$`-expansion, `/btw`, `/goal`, `/context`, TUI packages.** All interactive
affordances for a human at a terminal. Curator has no human at a terminal; it has
Telegram and an HTTP server.

**`pi-ask` for stopping at ambiguity.** The instinct is right and Curator has an
equivalent, but it cannot be a tool: a Telegram round-trip is not a blocking
prompt. Ambiguity is handled by the `clarify` intent, and the harder rule is that
ambiguity must resolve towards *reading*, not asking — phase 0 removed a
`clarify → library_query` rewrite that was guessing, while phase 3 keeps "when a
message is only a title, query rather than ask what the user wants".

## The transferable conclusion

The article's actual thesis is not its package list, it is that a small core plus
your own assembly beats a fixed harness. That is the same conclusion this
repository reached, with the opposite emphasis: for an unattended agent holding
real credentials, most of the assembly is deciding what *not* to load, and every
capability has to be justified against what it would cost if the model were
adversarial rather than merely wrong.