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

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))

Releasing

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

Run release script:

npm run release:patch    # Bug fixes
npm run release:minor    # New features
npm run release:major    # 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.

3.7 KiB Raw Blame History