Pi Agent Rules

An extensible coding agent and toolkit for terminal interfaces and language-model integrations.

Overview

Pi protects multiple agent sessions working in one checkout and asks them to communicate briefly. It names the source files behind generated code, separates safe tests from live-provider calls, and sends interactive testing and releases to focused guides.

Hard prohibitions Generated file guards Router files

Documents

├── 
├── .pi
│   └── skills
│       ├── 
│       └── 
├── packages
│   └── *
│       └── CHANGELOG.md — Per-package changelogs
└──

Techniques in this file

01 / Hard prohibitions

Protect other sessions through explicit Git boundaries

The Git section explains why broad staging, resets, cleaning, and stashing can interfere with other sessions. It requires explicit file paths and checking staged ownership before committing.

55Committing:56 57- Only commit files YOU changed in THIS session.58- Stage explicit paths (`git add <path1> <path2>`); never `git add -A` / `git add .`.59- Before committing, run `git status` and verify you are only staging your files.60- `packages/ai/src/models.generated.ts` may always be included alongside your files.61- Message format: `{feat,fix,docs}[(ai,tui,agent,coding-agent)]: <commit message> (optionally multiple lines)`. Message is informative and concise.62 63Never run (destroys other agents' work or bypasses checks):64 65- `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash`, `git add -A`, `git add .`, `git commit --no-verify`.

02 / Generated file guards

Name the generator and permit its legitimate output

The model catalog may not be edited directly. Its generator is the authority, and the rule explicitly permits generated metadata updates that accompany regeneration.

27- Never modify `packages/ai/src/models.generated.ts` directly; update `packages/ai/scripts/generate-models.ts` instead, then regenerate. Including the resulting `models.generated.ts` diff is always OK, even if regeneration includes unrelated upstream model metadata changes.

Keep regression tests away from real providers

The coding-agent suite uses its harness and a faux provider. The rule explicitly excludes real API credentials and paid tokens from that test path.

37- For `packages/coding-agent/test/suite/`, use `test/suite/harness.ts` + the faux provider. No real provider APIs, keys, or paid tokens.

Separate dependency installation from lifecycle execution

Dependency changes are reviewed as code, and install commands disable lifecycle scripts. New dependencies with lifecycle scripts need review and an explicit allowlist entry in the shrinkwrap generator.

46- Hydrate/update locally with `npm install --ignore-scripts`; clean/CI-style with `npm ci --ignore-scripts`. Don't run lifecycle scripts unless the user asks.47- If dep metadata changes, refresh `package-lock.json` with `npm install --package-lock-only --ignore-scripts`.48- If `packages/coding-agent/npm-shrinkwrap.json` needs regen, run `node scripts/generate-coding-agent-shrinkwrap.mjs` (verify with `--check` or `npm run check`). New deps with lifecycle scripts require review and an explicit allowlist entry in that script; never add one silently.

05 / Router files

Use task guides for interactive testing and releases

The root rules link to separate guides for exercising the interactive agent and preparing or recovering releases. Those procedures are loaded when that work is requested.

99For testing pi's interactive mode, load and follow [.pi/skills/interactive-testing.md](.pi/skills/interactive-testing.md).

Ideas for your repo

Limit shared-checkout Git operations to explicitly owned paths.
Pair generated-file prohibitions with the generator and allowed output changes.
Use a fake provider for tests that should never consume live API tokens.
Review dependency lifecycle scripts separately from dependency installation.