Kai
b5a29b05e1
Two findings that changed the plan rather than confirming it:
23. Skills require a tool literally named `read`. Curator's tools are all
domain-specific, so every --skill argument was discarded in silence. The
planned split into curator-core / video-arr / books-ingest was inert before
it was written; the policy stays in APPEND_SYSTEM.md. memo-inbox is
unaffected because it registers a restricted `read` override, which is why
the earlier note generalised wrongly from it.
24. A long-lived session is worth far more than the startup it saves: 99.97% of
input read from cache on a continuing conversation against 0% on a new one.
That is what makes the generated tool list necessary rather than merely
tidy -- anything varying at the front of the prompt destroys it -- and it
makes rotation a cost to be bounded rather than applied eagerly.
profile.toml now describes the phase-3 configuration that is actually deployed,
including that the empty `skills` list is a finding and not an oversight.
pi_rpc gains --system-prompt support and no longer guesses whether a `read` tool
will exist; extension_registers_read has to be stated.
harness-layering.md records what transfers from a widely-shared account of
building a personal coding harness on pi, and what does not. The layering frame
holds and the cache-hit figure was the useful part. Its central recommendation --
installing third-party packages -- is disqualifying for an unattended agent
holding tracker credentials, and its discipline layer (AGENTS.md) is precisely
what we block, because it is discovered from every parent directory.
5.3 KiB
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), 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.