co-mono/AGENTS.md

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

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.
• NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead
• Always ask before removing functionality or code that appears to be intentional

Commands

• After code changes (not documentation changes): npm run check (get full output, no tail). Fix all errors, warnings, and infos before committing.
• NEVER run: npm run dev, npm run build, npm test
• Only run specific tests if user instructs: npm test -- test/specific.test.ts
• NEVER commit unless user asks

GitHub Issues

When reading issues:

• Always read all comments on the issue

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 closing issues via commit:

• Include fixes #<number> or closes #<number> 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
• TUI interaction: use tmux

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
• ### Fixed - Bug fixes
• ### 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
• NEVER modify already-released version sections (e.g., ## [0.12.2])
• 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))

Adding a New LLM Provider (packages/ai)

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<Provider>() function returning AssistantMessageEventStream
• Message/tool conversion functions
• Response parsing emitting standardized events (text, tool_call, thinking, usage, stop)

3. Stream Integration (packages/ai/src/stream.ts)

• Import provider's stream function and options type
• Add credential detection in getEnvApiKey()
• Add case in mapOptionsForApi() for SimpleStreamOptions mapping
• Add provider to streamFunctions map

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

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]

Releasing

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

Steps

1. Update CHANGELOGs: Ensure all changes since last release are documented in the [Unreleased] section of each affected package's CHANGELOG.md

2. Run release script:

   npm run release:patch    # Fixes and additions
   npm run release:minor    # API breaking changes
   

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.