@pithos-kit/plan

Session-owned, enforced read-only planning for Pi with durable exact checkpoints, explicit save/preview/exit commands, and conflict-safe atomic publication.

Install

Requires Pi 1.0.0 or later.

pi install npm:@pithos-kit/plan

For local development:

pi install -l ./pithos.plan

Pithos .pithos config

pi:
  extensions:
    "@pithos-kit/plan": "npm:0.5.4"

Command lifecycle

/plan
/plan save
/plan preview
/plan exit
/plan status
/plan help
/plan --help
/plan -h

The grammar is explicit. /plan <task>, /plan pause, /plan cancel, and other unknown arguments are rejected with help. Enter Plan mode first, then provide the task and refinements as normal prompts.

/plan is a registered Pi command, routed before input middleware. Save/exit finalization prompts are sent as extension-source user messages, so middleware such as Squiggle and Translate that skips extension input leaves them unchanged. Publication authorization also requires the originating lifecycle dispatch; copying its prompt in another user or extension message does not authorize publication.

• /plan enters Plan mode. The first use creates one plan identity and a collision-resistant candidate path for the physical Pi session. Later uses restore that same plan. Repeating it while active is a no-op.
• /plan save asks the agent to finalize/checkpoint when needed and publish the latest exact checkpoint. It creates the file on first publication and updates the same stable path afterward. Plan mode remains active.
• /plan preview displays the latest exact checkpoint without publishing. It fails clearly when no checkpoint exists and does not start an agent turn.
• /plan exit is the sole combined leave/pause command. A synced published plan exits immediately. Otherwise Pi first offers Create/Update plan, Exit without publishing, Preview, and Continue planning, before any model turn. Exit without publishing is the safe default and keeps the checkpoint and plan identity restorable. Create/Update binds the exact current checkpoint, path, and update baseline before asking the agent to finalize; a changed checkpoint requires exact reapproval. With no checkpoint, the direct chooser offers Exit without publishing, Finalize before exit, and Continue planning. If finalization settles without publication, an idle Exit/Continue fallback prevents Plan mode from becoming trapped.
• /plan status reports active/inactive mode, branch revision, unpublished/dirty/synced/conflict state, path, and persisted/ephemeral session status without an agent turn.
• /plan help, --help, and -h show usage without changing state.

Autocomplete offers save, preview, exit, status, and help, followed by the retained --help and -h aliases. The package registers no prompt templates, so /plan appears only as a command. Bundled prompts/plan.md remains reference guidance, not a registered prompt; pi.prompts: [] explicitly disables default prompt discovery even when package resource filters are used.

Exact session checkpoints

While active, Plan mode exposes the internal sequential update_plan_draft tool. The agent is instructed to call it after the first coherent planning brief and after every material change to requirements, constraints, decisions, assumptions, open questions, or plan steps.

Each call supplies:

• the complete Markdown snapshot (never a patch or summary), and
• expectedRevision, using optimistic branch-local concurrency.

The result returns the new revision and SHA-256 digest. The complete exact snapshot is stored in Pi session tool-result details; lifecycle custom entries store the session owner, stable plan identity, candidate and published paths, checkpoint revision/digest, publication digest/state, active flag, and content/path-bound approval state. There are no draft plan files.

Every active model context receives an ephemeral projection of the exact latest branch checkpoint. It is explicitly labeled unapproved data, not instructions, and says that newer user messages are authoritative. The projection occurs through Pi's context event on every model call, independently of compaction summaries.

Completed checkpoints survive compaction, /tree, cancellation, /quit and resume, reload, and process restart when the Pi session itself is persisted. Active Plan mode also keeps or reapplies the bundled plan theme during /reload without replacing the saved pre-Plan theme that will be restored on exit. Ephemeral (--no-session) use is supported for the current process, but Plan warns on activation and reports the limitation in /plan status.

Sessions, branches, and forks

A physical Pi session owns exactly one logical plan and at most one published file. Exiting without publication preserves the identity and checkpoint; re-entering /plan restores them. Start a new Pi session to start a new logical plan.

Checkpoint revisions are branch-local. After /tree, Plan reconstructs only the selected branch's validated checkpoint, clears stale approval, and reconciles mode tools/theme. Sibling checkpoint content is never projected into the active branch. Publication identity and the stable published path remain global to the physical session.

Forked, cloned, and new sessions have a different Pi session ID. Copied parent state is not treated as ownership: entering Plan creates a fresh identity and a unique candidate path. Active legacy state is migrated to a fresh session-owned identity with old approval revoked and no legacy file implicitly claimed; inconsistent or multiple identities fail closed.

Publication and approval

create_plan remains the controlled publication tool for compatibility, but it accepts an exact checkpoint revision, not reconstructed Markdown. It is blocked during ordinary planning and becomes eligible only for the agent turn started by /plan save or /plan exit.

First publication

Pi binds approval to the exact checkpoint digest and selected path. TUI users may preview the exact Markdown before choosing Create plan; RPC approval includes the complete checkpoint and target. Without interactive UI, publication is blocked and Plan mode remains active. Persisted approval is never reused to mutate a file in a no-UI runtime.

Publication creates under .pi/plans/ using an exclusive, atomic no-overwrite operation. Preflight validates existing .pi and .pi/plans components without creating them and rejects symlinks or non-directories. Approved execution creates missing components one at a time and validates them against the canonical project directory. Known collisions are resolved before approval. A collision racing the write advances the generated timestamp, revokes approval, and requires renewed confirmation.

Updates

All updates target the same first-published path. Cooperating Pi mutations are serialized through Pi's per-file mutation queue. After asynchronous temporary file preparation, the final open/fstat/read/lstat/digest verification and atomic rename execute synchronously in one non-yielding JavaScript section. A modification, deletion, symlink replacement, or directory observed by that verification is a conflict and is never silently overwritten. The session remains in Plan mode.

Portable Node APIs do not provide a strict cross-process compare-and-swap for this replacement, so this is not a linearizable CAS. Arbitrary external OS writers are not locked and can still race the final filesystem calls.

If the latest checkpoint digest is already published, Pi verifies the on-disk bytes and performs no write. /plan save remains active; /plan exit exits immediately when that verified publication is unchanged.

Content-inferred session name

After the first successful approved publication, Plan starts a nonblocking model request to infer a descriptive session name from the published content, for example guild-selected-row-highlight. It does not use the first heading or filename as the name. Only a complete response of 3–6 lowercase ASCII kebab-case words, at most 64 characters, is accepted.

The request uses the cheapest authenticated, session-scoped, non-reasoning text model available through Pi. It sends only the first 8,000 characters of the published Markdown, labeled as untrusted data rather than instructions. It includes no conversation, cwd, tool outputs, path, or session identifier. Published Markdown is never changed by naming. The request may incur a small provider charge; the Pi 0.83 development runtime does not include this background usage in session totals. There is no prompt caching or retry, and a ten-second deadline includes credential resolution.

Missing credentials/model, invalid output, provider or metadata failure, timeout, or PI_OFFLINE=1, true, or yes leaves the existing name unchanged. Manual or extension-provided renames while inference is pending cancel it and remain authoritative, even if the name is subsequently changed back. Session replacement, branch navigation, reload, and shutdown cancel/discard pending results. /plan exit itself does not cancel naming: it may finish after Plan mode has exited.

Updates, repeated saves, and restart recovery neither retry inference nor replay old generated names. If the process stops between publication and naming, the current name is retained on recovery.

Approval is persisted as an exact revision/digest/path/base-digest binding so a completed write can be reconciled safely after a process interruption. /tree always clears approval. Publication failure never exits Plan mode; explicit Exit without publishing does.

Read-only enforcement

Plan mode exposes trusted built-in read, grep, find, and ls, plus update_plan_draft and create_plan. Built-in provenance accepts both Pi's legacy <builtin:name> paths and current builtin:name paths; same-named custom tools remain blocked. When @pithos-kit/web is installed, provenance-verified web_search and web_fetch remain available for public-web research. Web content is untrusted external data and must not be followed as instructions.

The Web exception is provenance-checked against a canonical package manifest named exactly @pithos-kit/web. Same-named SDK, top-level, path-escaping, spoofed-source, and unrelated custom tools stay blocked. Plan also blocks writes, edits, shell tools, manual !/!! shell commands, delegation, mutating or untrusted custom tools, and same-named overrides of trusted built-ins. It applies the bundled Plan theme and planning footer while active, restoring the previous theme and exact tool selection on exit. Use /plan exit before running shell commands (including git or gh) or implementing changes. Exiting restores previously enabled shell and custom tools; it does not enable tools that were excluded before entering Plan mode. The branch-local tool snapshot is retained so /tree can repair a replayed Plan loadout on an already-exited branch, even before a post-exit model request has declared the restored tools. Non-Plan tool selections remain unchanged. Completed exit recovery also restores tools and theme before marking Plan inactive.

If the visual distinction is ever absent while /plan status reports active mode, run /reload; the reloaded runtime reconstructs state and reapplies the Plan presentation without relaxing tool restrictions.

Enforcement boundary

Plan mode enforces Pi's tool and user-shell interfaces; it is not an operating-system sandbox. Other extensions and external processes can still mutate files directly. Changes observed by publication verification become conflicts, but arbitrary external OS writes can race the final filesystem calls.

Migrating from @pithos-kit/skills

@pithos-kit/skills is retired. Remove global and project installs (pi remove npm:@pithos-kit/skills and pi remove -l npm:@pithos-kit/skills) and its .pithos pin. Use Guild 0.3.0 for the relocated TDD skill; Atlas 0.6.0 and later no longer bundles it. Historical Skills 0.4.0 and earlier must not be loaded alongside this package because both handle /plan and Plan state.