Skip to content

Product Book

Grzegorz Nowak edited this page Oct 12, 2026 · 11 revisions

Product Book

Status: draft for review. A description of what pi-schematic is 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.

About this book

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.

The problem it solves

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

How the parts fit together

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.

The chapters

# 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

Where the product draws its lines

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.

Honest caveats and open questions

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, and reasoning as Model Group modalities (model-groups/types.ts:4-6, and the spawn constraints schema accepts all three), while the README says modalities "today" means text and image only (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.*, but runtime-singletons.ts emits console.warn on an exceptional re-registration path (runtime-singletons.ts:76-90).
  • The date anchor is always on. before_agent_start injects 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.

The drift plan

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.

Clone this wiki locally