Repository navigation
Product Book
Status: draft for review. A description of what
pi-schematicis and how it behaves, written to be read from start to finish. The drift plan at the end is method-only until the target state is confirmed.
This book explains pi-schematic as a product: what problem it solves, what an operator and
their agent can do with it, and where its edges are. It is built from pi-schematic @
36bd569 (main, 2026-10-12, package version 0.6.0). Every factual statement is tied to that
revision. The chapters are written for an intelligent reader who is new to the
project and possibly new to Pi, and each one ends with a collapsed list of the exact behaviours
it describes, so the same text serves both a first read and later change work.
The chapters are narrative. Read in order, they describe a single idea — the agent managing its
own context — and the pieces that support it. Each chapter ends with an Appendix — baseline
behaviour rows: a collapsible table of atomic, observable behaviours, one per row, each with a
stable ID (PB-<AREA>-<nn>) and a file:line citation to the baseline. You can read a chapter
without opening its appendix; you open the appendix when you need to know exactly what the code
does today.
The atomic rows are the book's memory for change. A drift vector is one row-anchored change
record: op ∈ {MODIFY, ADD, REMOVE, KEEP}, with from = the baseline row's behaviour, to =
the intended behaviour, why, and acceptance. Because rows are atomic and stable, a change has
an unambiguous anchor and a directly diffable before/after pair. The method is described at the
end of this page; the plan itself is deliberately kept separate from the baseline.
Coding agents degrade as their context grows — often far from the token limit. The detail a model reasons well with sits in roughly the first part of its window (the practical primacy zone, around the first 30%); beyond that, useful information drifts out of the region the model uses well, even while a token counter still looks comfortable. The agent keeps working, but worse.
Most harnesses respond by managing context around the model: auto-compaction near a token
ceiling, a manual /compact, or a full reset. Those are all lossy summarization passes the agent
does not control. The threshold is blunt, the timing is the user's burden, and the summary is
optimized for cost rather than for what the working agent actually needed.
pi-schematic takes the opposite stance: it gives the agent tools to manage its own context.
The agent chooses what to isolate, what to remember, when to cut, and what may not be touched —
instead of inheriting a compacter's guess. The four moves:
| Move | Primitive | What it prevents |
|---|---|---|
| Isolate | Spawn | Noisy subtasks polluting the parent's context |
| Remember | Notebook | Losing reusable knowledge across deliberate cuts in the same task |
| Compact | Handoff | Waiting on late auto-summarize, or one mixed summary blob |
| Guard | Readonly | Accidental edits during research and planning |
Delegation (spawn) launches a child in a separate context with the tools and working
directory it needs, and returns only a concise report — so the parent's context is not inflated
by the child's exploration. Children cannot delegate further or restart themselves; the work
stays one level deep and the parent keeps the thread.
Memory (the notebook) is deliberately short-lived. It is not a forever store that accumulates facts until it rots; it is a set of named pages coupled to the current work stream. Pages travel through delegation and handoff, they are scoped to the session branch you are on, and they clear with the conversation. Re-derivable code facts are a discardable cache; guidance, decisions, design, and scope are kept and refreshed for the life of the stream. An active topic gives the work its current frame and frames the spawn-versus-handoff choice.
Boundaries (handoff) are deliberate. The agent prepares the next context — writes the remaining situational context and curates the notebook — while the extension carries the next instruction verbatim, so it reaches the successor word for word instead of being paraphrased at compaction. The successor starts from a small context with one real user message and fetches the notebook pages it needs by name.
Model choice (Model Groups and workflows) is separated from the procedure. A saved prompt or skill names a role; a Model Group holds the provider/model pool behind that role, so workflows survive model churn. The same workflow files carry declarative policy for model, thinking level, and readonly posture.
Awareness (the TUI and the watchdog) makes pressure visible early. Status indicators, advisory nudges, and a system-prompt primer tell the agent when to isolate, when to remember, and when to cut. They advise; they never force.
| # | Chapter | What it covers |
|---|---|---|
| 1 | Spawn — Delegation in Clean Contexts | handing a task to a child, what it inherits, how its model and capabilities are chosen, what returns |
| 2 | Notebook — Short-Lived Shared Memory | pages and topics, how they persist and travel, branch scoping, and pruning |
| 3 | Handoff — Deliberate Context Boundaries | the instruction/preparation split, eligibility, what the successor sees, recovery, and readonly |
| 4 | Model Groups — Roles Independent of Providers | naming roles, configuring them, capabilities, and how a spawn routes through them |
| 5 | Readonly — Research Guardrail | the research posture, what it blocks, how the shell is guarded per platform, and its honest limits |
| 6 | Workflows — Repeat the Procedure, Not the Steering | saved prompts and skills, $@, and the frontmatter policy contract |
| 7 | TUI & Observability | what you see and operate: indicators, overlays, live child rendering, and inline output |
| 8 | Context Awareness — Advisory Pressure & the Primacy Zone | the 30/50/70 bands, adaptive advice, and what is injected before a run |
| 9 | Install, Lifecycle & Compatibility | installation, what loads, the session lifecycle, configuration, and compatibility |
The product is opinionated, and its limits are part of the deal.
It requires Pi 0.99.2+ and Node.js 22.19.0+, and the documented install also turns off Pi's built-in compaction so that handoff owns deliberate restarts. Children return condensed results and cannot delegate or hand off, and there is no worktree isolation or per-child tool policy — a child shares the parent's working directory and authority.
A known Model Group chooses uniformly with replacement from the entries that are authenticated and usable, so repeated calls may select the same model. There is no weighting, no-repeat, health routing, retry/failover, or optimizer. A group's capabilities are derived from its members and can be narrowed, never invented. When a required capability cannot be met, spawn fails before creating anything.
Spawn and handoff create genuinely separate contexts and input prefixes, which is what protects quality and keeps cost down; a model or provider switch starts a different cache. The extension creates cache-aware boundaries, but it does not configure provider cache lifetimes.
The notebook is branch- and work-stream-scoped, survives handoff, and clears with /new — it is
memory for this task, not forever memory. Handoff can transactionally discard stale pages.
Readonly is a coding guardrail, not a hardened security boundary. Readonly blocks write and edit everywhere; the shell guard classifies shell commands and, on macOS and Linux, additionally sandboxes them at the OS level when the sandbox binary is present. Windows has no syscall-level sandbox and is classifier-only. Interpreters and piped indirection can bypass classification.
These are points where verified behaviour and shipped documentation disagree, or where a behaviour is incomplete. They are observations, not fixes.
-
Modality names. The code supports
text,image, andreasoningas Model Group modalities (model-groups/types.ts:4-6, and thespawnconstraints schema accepts all three), while the README says modalities "today" meanstextandimageonly (README.md:130). The code is the baseline. - Notebook clipping is reported. The 2,000-line / 50 KiB caps retain the head; writes report dropped tails and reject zero-content truncation before mutation. A durable flag drives a read notice and human-only selector badge. Plain previews/index remain undecorated, so they are not completeness checks; absent legacy flags do not prove completeness. No aggregate cap or warning is exposed. See Notebook, claims -07/-11/-17/-18/-46…-49.
-
The 70% advice differs from its documentation. The changelog says the 70%+ tier warns that
automatic compaction may trigger soon, but the generated default nudge says only that topic
discipline is urgent (
watchdog.ts:63-72,CHANGELOG.md:161-162). - Handoff recovery is quiet. Recovery has no product-visible timeout or attempt counter; only the required-handoff cancellation (5 turns) surfaces to the operator.
-
One diagnostics exception. The repository forbids extension-host
console.*, butruntime-singletons.tsemitsconsole.warnon an exceptional re-registration path (runtime-singletons.ts:76-90). -
The date anchor is always on.
before_agent_startinjects the current-date anchor on every run; the extension's prompt injections are unconditional and no flag disables this one (index.ts:772). An operator who wants no date in the system prompt cannot turn it off while the extension is loaded.
Reserved. Each planned change becomes one row-anchored vector:
{ op, anchor, from, to, why, acceptance }, where anchor is a PB-<AREA>-<nn> row ID and
from restates that row's baseline behaviour. The plan stays separate from this baseline so the
book can be read without proposals; the "Known gaps" notes in each chapter mark the sharpest
candidates.