diff --git a/AGENTS.md b/AGENTS.md index 6b30ee38..485c7bd5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,17 +1,14 @@ # Development Rules -## First Message -If the user did not give you a concrete task in their first message, -read README.md, then ask which module(s) to work on. Based on the answer, read the relevant README.md files in parallel. -- packages/ai/README.md -- packages/tui/README.md -- packages/agent/README.md -- packages/coding-agent/README.md -- packages/mom/README.md -- packages/pods/README.md -- packages/web-ui/README.md +## Conversational Style + +- Keep answers short and concise +- No emojis in commits, issues, PR comments, or code +- No fluff or cheerful filler text +- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!") ## Code Quality + - No `any` types unless absolutely necessary - Check node_modules for external API type definitions instead of guessing - **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports. @@ -21,6 +18,7 @@ read README.md, then ask which module(s) to work on. Based on the answer, read t - Never hardcode key checks with, eg. `matchesKey(keyData, "ctrl+x")`. All keybindings must be configurable. Add default to matching object (`DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS`) ## Commands + - After code changes (not documentation changes): `npm run check` (get full output, no tail). Fix all errors, warnings, and infos before committing. - Note: `npm run check` does not run tests. - NEVER run: `npm run dev`, `npm run build`, `npm test` @@ -32,15 +30,8 @@ read README.md, then ask which module(s) to work on. Based on the answer, read t - Put issue-specific regressions under `packages/coding-agent/test/suite/regressions/` and name them `-.test.ts`. - NEVER commit unless user asks -## GitHub Issues -When reading issues: -- Always read all comments on the issue -- Use this command to get everything in one call: - ```bash - gh issue view --json title,body,comments,labels,state - ``` - ## Contribution Gate + - New issues from new contributors are auto-closed by `.github/workflows/issue-gate.yml` - New PRs from new contributors without PR rights are auto-closed by `.github/workflows/pr-gate.yml` - Maintainer approval comments are handled by `.github/workflows/approve-contributor.yml` @@ -50,11 +41,13 @@ When reading issues: - `lgtm` approves future issues and rights to submit PRs When creating issues: + - Add `pkg:*` labels to indicate which package(s) the issue affects - Available labels: `pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:mom`, `pkg:pods`, `pkg:tui`, `pkg:web-ui` - If an issue spans multiple packages, add all relevant labels When posting issue/PR comments: + - Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file` - Never pass multi-line markdown directly via `--body` in shell commands - Preview the exact comment text before posting @@ -63,18 +56,16 @@ When posting issue/PR comments: - Keep comments concise, technical, and in the user's tone When closing issues via commit: + - Include `fixes #` or `closes #` in the commit message - This automatically closes the issue when the commit is merged ## PR Workflow + - Analyze PRs without pulling locally first - If the user approves: create a feature branch, pull PR, rebase on main, apply adjustments, commit, merge into main, push, close PR, and leave a comment in the user's tone - You never open PRs yourself. We work in feature branches until everything is according to the user's requirements, then merge into main, and push. -## Tools -- GitHub CLI for issues/PRs -- Add package labels to issues/PRs: pkg:agent, pkg:ai, pkg:coding-agent, pkg:mom, pkg:pods, pkg:tui, pkg:web-ui - ## Testing pi Interactive Mode with tmux To test pi's TUI in a controlled terminal environment: @@ -100,17 +91,14 @@ tmux send-keys -t pi-test C-o # ctrl+o tmux kill-session -t pi-test ``` -## Style -- Keep answers short and concise -- No emojis in commits, issues, PR comments, or code -- No fluff or cheerful filler text -- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!") - ## Changelog + Location: `packages/*/CHANGELOG.md` (each package has its own) ### Format + Use these sections under `## [Unreleased]`: + - `### Breaking Changes` - API changes requiring migration - `### Added` - New features - `### Changed` - Changes to existing functionality @@ -118,6 +106,7 @@ Use these sections under `## [Unreleased]`: - `### Removed` - Removed features ### Rules + - Before adding entries, read the full `[Unreleased]` section to see which subsections already exist - New entries ALWAYS go under `## [Unreleased]` section - Append to existing subsections (e.g., `### Fixed`), do not create duplicates @@ -125,6 +114,7 @@ Use these sections under `## [Unreleased]`: - Each version section is immutable once released ### Attribution + - **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/badlogic/pi-mono/issues/123))` - **External contributions**: `Added feature X ([#456](https://github.com/badlogic/pi-mono/pull/456) by [@username](https://github.com/username))` @@ -133,13 +123,16 @@ Use these sections under `## [Unreleased]`: Adding a new provider requires changes across multiple files: ### 1. Core Types (`packages/ai/src/types.ts`) + - Add API identifier to `Api` type union (e.g., `"bedrock-converse-stream"`) - Create options interface extending `StreamOptions` - Add mapping to `ApiOptionsMap` - Add provider name to `KnownProvider` type union ### 2. Provider Implementation (`packages/ai/src/providers/`) + Create provider file exporting: + - `stream()` function returning `AssistantMessageEventStream` - `streamSimple()` for `SimpleStreamOptions` mapping - Provider-specific options interface @@ -147,16 +140,19 @@ Create provider file exporting: - Response parsing emitting standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`) ### 3. Provider Exports and Lazy Registration + - Add a package subpath export in `packages/ai/package.json` pointing at `./dist/providers/.js` - Add `export type` re-exports in `packages/ai/src/index.ts` for provider option types that should remain available from the root entry - Register the provider in `packages/ai/src/providers/register-builtins.ts` via lazy loader wrappers, do not statically import provider implementation modules there - Add credential detection in `packages/ai/src/env-api-keys.ts` ### 4. Model Generation (`packages/ai/scripts/generate-models.ts`) + - Add logic to fetch/parse models from provider source - Map to standardized `Model` interface ### 5. Tests (`packages/ai/test/`) + Add provider to: `stream.test.ts`, `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `image-limits.test.ts`, `unicode-surrogate.test.ts`, `tool-call-without-result.test.ts`, `image-tool-result.test.ts`, `total-tokens.test.ts`, `cross-provider-handoff.test.ts`. For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If the provider exposes multiple model families (for example GPT and Claude), add at least one pair per family. @@ -164,11 +160,13 @@ For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If t For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential detection. ### 6. Coding Agent (`packages/coding-agent/`) + - `src/core/model-resolver.ts`: Add default model ID to `DEFAULT_MODELS` - `src/cli/args.ts`: Add env var documentation - `README.md`: Add provider setup instructions ### 7. Documentation + - `packages/ai/README.md`: Add to providers table, document options/auth, add env vars - `packages/ai/CHANGELOG.md`: Add entry under `## [Unreleased]` @@ -177,6 +175,7 @@ For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential **Lockstep versioning**: All packages always share the same version number. Every release updates all packages together. **Version semantics** (no major releases): + - `patch`: Bug fixes and new features - `minor`: API breaking changes @@ -192,15 +191,12 @@ For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential The script handles: version bump, CHANGELOG finalization, commit, tag, publish, and adding new `[Unreleased]` sections. -## **CRITICAL** Tool Usage Rules **CRITICAL** -- NEVER use sed/cat to read a file or a range of a file. Always use the read tool (use offset + limit for ranged reads). -- You MUST read every file you modify in full before editing. - ## **CRITICAL** Git Rules for Parallel Agents **CRITICAL** Multiple agents may work on different files in the same worktree simultaneously. You MUST follow these rules: ### Committing + - **ONLY commit files YOU changed in THIS session** - ALWAYS include `fixes #` or `closes #` in the commit message when there is a related issue or PR - NEVER use `git add -A` or `git add .` - these sweep up changes from other agents @@ -209,7 +205,9 @@ Multiple agents may work on different files in the same worktree simultaneously. - Track which files you created/modified/deleted during the session ### Forbidden Git Operations + These commands can destroy other agents' work: + - `git reset --hard` - destroys uncommitted changes - `git checkout .` - destroys uncommitted changes - `git clean -fd` - deletes untracked files @@ -218,6 +216,7 @@ These commands can destroy other agents' work: - `git commit --no-verify` - bypasses required checks and is never allowed ### Safe Workflow + ```bash # 1. Check status first git status @@ -234,9 +233,11 @@ git pull --rebase && git push ``` ### If Rebase Conflicts Occur + - Resolve conflicts in YOUR files only - If conflict is in a file you didn't modify, abort and ask the user - NEVER force push ### User override + If the user instructions conflict with rules set out here, ask for confirmation that they want to override the rules. Only then execute their instructions.