pi-continue: Instructions file for Codex

AGENTS.md

pi-continue is a Pi extension package with one product promise: when context fills during a long Pi run, Pi compacts at a safe checkpoint and the same task continues in the same session from the new summary. It is published on npm and in the pi.dev package gallery and accepts outside contributions, so it has real users. Breaking changes are announced under Breaking changes and Migration in CHANGELOG.md; the product still keeps no aliases or compatibility shims (see the product contract).

This guide is for agents working in this checkout. It is tracked in Git and deliberately excluded from the npm package, where README.md is the operator guide. Paths written src/... are under extensions/continue/src/.

Where things live

The tracked documentation is intentionally small:

• README.md is the npm-package guide: install, /continue, configuration, prompt customization, boundaries and a compact product explanation.
• CHANGELOG.md holds the release notes. Keep it concise, complete and tied to validated shipped behavior.
• AGENTS.md (this file) holds the product invariants, the Pi runtime boundary, code ownership, checks and the release invariants. It is tracked for everyone who works on the repository and excluded from the npm package by the package.json files allowlist; tracking it does not bring the ignored local notes below back into the documentation.

Everything else explains itself through source and tests. extensions/continue/index.ts is the entry point and registers the Pi hooks; the ownership map below says which src/ module owns each behavior; assets/ holds the customizable system/user prompt corpus; examples/ holds the public config and output examples; tests/ is the executable contract, including the no-network host-loop fixture in tests/mid-run-host-integration.test.ts, which drives a real Pi agent session with a faux provider.

PLAN.md, ARCH.md and VISION.md are ignored local notes, not documentation, and MAINTAINER.md is the maintainer's ignored local release runbook (see Releasing). Do not re-track them or grow a larger documentation set unless the maintainer explicitly restores one. CONTINUE.md is retired local state: pi-continue neither writes nor reads it, and if it exists, leave it alone unless the task is about continuation-document behavior. .pi/continue/*.md is package-owned runtime output (the per-session continuation artifacts). None of these belong in the package.