AGENTS.md

1# Development Rules
2 
3## Conversational Style
4 
5- Keep answers short and concise
6- No emojis in commits, issues, PR comments, or code
7- No fluff or cheerful filler text (e.g., "Thanks @user" not "Thanks so much @user!")
8- Technical prose only, be direct
9- When the user asks a question, answer it first before making edits or running implementation commands.
10- When responding to user feedback or an analysis, explicitly say whether you agree or disagree before saying what you changed.
11 
12## Code Quality
13 
14- Read files in full before wide-ranging changes, before editing files you have not fully inspected, and when asked to investigate or audit. Do not rely on search snippets for broad changes.
15- No `any` unless absolutely necessary.
16- Inline single-line helpers that have only one call site.
17- Check node_modules for external API types; don't guess.
18- **No inline imports** (`await import()`, `import("pkg").Type`, dynamic type imports). Top-level imports only.
19- Never remove or downgrade code to fix type errors from outdated deps; upgrade the dep instead.
20- Use only erasable TypeScript syntax (Node strip-only mode) in code checked by the root config (`packages/*/src`, `packages/*/test`, `packages/coding-agent/examples`): no parameter properties, `enum`, `namespace`/`module`, `import =`, `export =`, or other constructs needing JS emit. Use explicit fields with constructor assignments.
21- Always ask before removing functionality or code that appears intentional.
22- Do not preserve backward compatibility unless the user asks for it.
23- Never hardcode key checks (e.g. `matchesKey(keyData, "ctrl+x")`). Add defaults to `DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS` so they stay configurable.
24- 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.
25 
26## Commands
27 
28- After code changes (not docs): `npm run check` (full output, no tail). Fix all errors, warnings, and infos before committing. Does not run tests.
29- Never run `npm run build` or `npm test` unless requested by the user.
30- Never run the full vitest suite directly: it includes e2e tests that activate when endpoint/auth env vars are present. For all non-e2e tests, run `./test.sh` from the repo root. Otherwise run specific tests from the package root: `node ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts`.
31- If you create or modify a test file, run it and iterate on test or implementation until it passes.
32- For `packages/coding-agent/test/suite/`, use `test/suite/harness.ts` + the faux provider. No real provider APIs, keys, or paid tokens.
33- Put issue-specific regressions under `packages/coding-agent/test/suite/regressions/` named `<issue-number>-<short-slug>.test.ts`.
34- For ad-hoc scripts, `write` them to a temp file (e.g. `/tmp`), run, edit if needed, remove when done. Don't embed multi-line scripts in `bash` commands.
35- Never commit unless the user asks.
36 
37## Dependency and Install Security
38 
39- Treat npm dep and lockfile changes as reviewed code. Direct external deps stay pinned to exact versions.
40- 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.
41- If dep metadata changes, refresh `package-lock.json` with `npm install --package-lock-only --ignore-scripts`.
42- 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.
43- Pre-commit blocks lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1`. Don't bypass unless the user wants the lockfile change committed.
44 
45## Git
46 
47Multiple pi sessions may be running in this cwd at the same time, each modifying different files. Git operations that touch unstaged, staged, or untracked files outside your own changes will stomp on other sessions' work. Follow these rules:
48 
49Committing:
50 
51- Only commit files YOU changed in THIS session.
52- Stage explicit paths (`git add <path1> <path2>`); never `git add -A` / `git add .`.
53- Before committing, run `git status` and verify you are only staging your files.
54- `packages/ai/src/models.generated.ts` may always be included alongside your files.
55- Message format: `{feat,fix,docs}[(ai,tui,agent,coding-agent)]: <commit message> (optionally multiple lines)`. Message is informative and concise.
56 
57Never run (destroys other agents' work or bypasses checks):
58 
59- `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash`, `git add -A`, `git add .`, `git commit --no-verify`.
60 
61If rebase conflicts occur:
62 
63- Resolve conflicts only in files you modified.
64- If a conflict is in a file you did not modify, abort and ask the user.
65- Never force push.
66 
67## Issues and PRs
68 
69See `CONTRIBUTING.md` for the contributor gate (auto-close workflows, `lgtm`/`lgtmi`, quality bar).
70 
71When reviewing PRs:
72 
73- Do not run `gh pr checkout`, `git switch`, or otherwise move the worktree to the PR branch unless the user explicitly asks.
74- Use `gh pr view`, `gh pr diff`, `gh api`, and local `git show`/`git diff` against fetched refs to inspect PR metadata, commits, and patches without changing branches.
75- If you need PR file contents, fetch/read them into temporary files or use `git show <ref>:<path>` without switching branches.
76 
77When creating issues:
78 
79- Add `pkg:*` labels for affected packages (`pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:tui`); use all that apply.
80 
81When posting issue/PR comments:
82 
83- Write the comment to a temp file and post with `gh issue/pr comment --body-file` (never multi-line markdown via `--body`).
84- Keep comments concise, technical, in the user's tone.
85- End every AI-posted comment with the AI-generated disclaimer line specified by the originating prompt (e.g. `This comment is AI-generated by `/wr``).
86 
87When closing issues via commit:
88 
89- Include `fixes #<number>` or `closes #<number>` in the message so merging auto-closes the issue. For multiple issues, repeat the keyword per issue (`closes #1, closes #2`); a shared keyword (`closes #1, #2`) only closes the first.
90 
91## Testing pi Interactive Mode with tmux
92 
93Run the TUI in a controlled terminal (from the repo root):
94 
95```bash
96tmux new-session -d -s pi-test -x 80 -y 24
97tmux send-keys -t pi-test &quot;./pi-test.sh&quot; Enter
98sleep 3 && tmux capture-pane -t pi-test -p     # capture after startup
99tmux send-keys -t pi-test &quot;your prompt here&quot; Enter
100tmux send-keys -t pi-test Escape               # special keys (also C-o for ctrl+o, etc.)
101tmux kill-session -t pi-test
102```
103 
104## Changelog
105 
106Location: `packages/*/CHANGELOG.md` (one per package).
107 
108Sections under `## [Unreleased]`: `### Breaking Changes` (API changes requiring migration), `### Added`, `### Changed`, `### Fixed`, `### Removed`.
109 
110Rules:
111 
112- All new entries go under `## [Unreleased]`. Read the full section first and append to existing subsections; never duplicate them.
113- Released version sections (e.g. `## [0.12.2]`) are immutable; never modify them.
114 
115Attribution:
116 
117- Internal (from issues): `Fixed foo bar ([#123](https://github.com/earendil-works/pi-mono/issues/123))`
118- External contributions: `Added feature X ([#456](https://github.com/earendil-works/pi-mono/pull/456) by [@username](https://github.com/username))`
119 
120## Releasing
121 
122**Lockstep versioning**: all packages share one version; every release updates all together. `patch` = fixes + additions, `minor` = breaking changes. No major releases.
123 
1241. **Update CHANGELOGs**: ask the user whether they ran the `/cl` prompt on the latest commit on `main`. If not, they must run `/cl` first to audit and update each package's `[Unreleased]` section before releasing.
125 
1262. **Local smoke test**: build an unpublished release and smoke test from outside the repo (so it can't resolve workspace files):
127```bash
128   npm run release:local -- --out /tmp/pi-local-release --force
129   cd /tmp
130 
131   # Node package install smoke tests
132   /tmp/pi-local-release/node/pi --help
133   /tmp/pi-local-release/node/pi --version
134   /tmp/pi-local-release/node/pi --list-models
135   /tmp/pi-local-release/node/pi -p &quot;Say exactly: ok&quot;
136   /tmp/pi-local-release/node/pi
137 
138   # Bun binary smoke tests
139   /tmp/pi-local-release/bun/pi --help
140   /tmp/pi-local-release/bun/pi --version
141   /tmp/pi-local-release/bun/pi --list-models
142   /tmp/pi-local-release/bun/pi -p &quot;Say exactly: ok&quot;
143   /tmp/pi-local-release/bun/pi
144```
145   Verify both Node and Bun startup, model/account listing, interactive startup, and at least one real prompt with the intended default provider. The bare commands `/tmp/pi-local-release/node/pi` and `/tmp/pi-local-release/bun/pi` start interactive mode; run each in tmux, submit a prompt, and wait for the model reply before considering the interactive smoke test passed. Failures are release blockers unless the user explicitly accepts the risk.
146 
1473. **Run the release script**:
148```bash
149   PI_ALLOW_LOCKFILE_CHANGE=1 npm_config_min_release_age=0 npm run release:patch    # fixes + additions
150   PI_ALLOW_LOCKFILE_CHANGE=1 npm_config_min_release_age=0 npm run release:minor    # breaking changes
151```
152   Use `npm_config_min_release_age=0` only for the release command. The repo's normal npm age gate can otherwise block the release lockfile refresh when the current workspace package version was published recently. Review any lockfile or shrinkwrap diffs the release creates before push.
153 
154   The release script bumps all package versions, updates changelogs, regenerates release artifacts, runs `npm run check`, commits `Release vX.Y.Z`, tags `vX.Y.Z`, adds fresh `## [Unreleased]` changelog sections, commits `Add [Unreleased] section for next cycle`, then pushes `main` and the tag. Do not rerun the release script after a tag was pushed.
155 
1564. **CI publishes npm packages**: pushing the `vX.Y.Z` tag triggers `.github/workflows/build-binaries.yml`. The `publish-npm` job uses npm trusted publishing through GitHub Actions OIDC with environment `npm-publish`; no local `npm publish`, `npm whoami`, OTP, or WebAuthn flow is required.
157 
1585. **If CI publish fails**: inspect the failed `publish-npm` job. The publish helper is idempotent and skips package versions already present on npm, so rerun the tag workflow after fixing CI or transient npm issues. Do not rerun `npm run release:patch` or `npm run release:minor` for the same version.
159 
160## User Override
161 
162If the user's instructions conflict with any rule in this document, ask for explicit confirmation before overriding. Only then execute their instructions.
163