pi AGENTS.md
3.6 kB · 33 lines
Markdown

Agent instructions for working on the user's pi configuration #

  • If the user mentions a pi extension to reference, assume first they are referring to the extensions directory in this repo: agent/extensions/
  • If the user mentions an "example extension", look in examples/extensions/ under pi's installation source directory
  • Tests for extensions should be in a dedicated tests subdirectory (i.e. extensions/<name>/test/)
  • Design and implement extensions such that they don't have inner knowledge of each other's workings. They should be well isolated and expose clear interfaces without depending on internal implementation details of other extensions. Use Pi's event bus mechanism for "message passing" between extensions.
  • You MUST use pnpm, never npm
  • All changes must pass pnpm oxlint and be formatted with pnpm oxfmt. Use the normal LSP extension feedback during normal development iteration, but use pnpm oxlint as a final validation step.
  • Keep tests minimal. Avoid writing duplicate tests. Extend existing tests when possible before creating new tests. Tests must be "timeless": they must only cover the current behavioral and functional requirements, not prior behavior (except for bug fixes/regression tests) or capture intermediate state due to decisions made during development and iteration.
  • Pi merges the promptGuidelines of all active tools into one flat list without tool names. Each guideline must make sense alone. Name the tool or subject in each guideline (for example "work record brief", not "brief"), and do not use pronouns or terms that refer to the tool definition or to another guideline. A guideline must not assume that the reader has a tool it may not have.
  • Do not add README files to extensions.
  • Do not add a new Pi patch when existing extension APIs can meet the requirement. Before you propose a patch, explain the API limit and the tradeoffs. Patches are acceptable for pi bug fixes but should be removed as soon as the issue is fixed upstream (treat patches as a cost).
  • Put dependencies that several extensions share in the catalog of pnpm-workspace.yaml, and refer to them with catalog:. Keep the root test script as pnpm --recursive --if-present test. An extension with tests needs its own workspace package and test script.

Design goals and evaluation criteria #

  1. Cost / token minimization

    Extensions and custom tools should aim to be as token efficient as possible. This means providing the maximum amount of signal using the minimum number of tokens. This is not always an easy balance to strike, but changes that increase the "signal-to-token" ratio are good. Designs that lower it are bad. Maximize prompt caching. Avoid context window pollution. Filter outputs before they reach the model. Do things in the harness and/or extensions instead of in the model when possible.

  2. Performance

    Keep memory and CPU usage to a minimum and prefer approaches that minimize network latency or round-trips.

  3. Capability

    Ensure designs take full advantage of Pi's built-in capabilities as well as capabilities of upstream providers and models.

  4. Simplicity

    Keep source code simple. Use abstractions where appropriate. Avoid over-engineering for rare or obscure edge cases. Prefer native APIs from the Pi SDK or other relevant libraries over custom implementations when possible. Treat new lines of code as a cost. Respect separation of concerns. Avoid hidden coupling between components and leaky abstractions.

In cases where the design goals above conflict, prioritize them in the numbered order.