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, nevernpm - All changes must pass
pnpm oxlintand be formatted withpnpm oxfmt. Use the normal LSP extension feedback during normal development iteration, but usepnpm oxlintas 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
promptGuidelinesof 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 withcatalog:. Keep the root test script aspnpm --recursive --if-present test. An extension with tests needs its own workspace package andtestscript.
Design goals and evaluation criteria #
-
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.
-
Performance
Keep memory and CPU usage to a minimum and prefer approaches that minimize network latency or round-trips.
-
Capability
Ensure designs take full advantage of Pi's built-in capabilities as well as capabilities of upstream providers and models.
-
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.