Contribution Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/sync-versions.js
• packages/mom/CHANGELOG.md
• AGENTS.md
• package.json
• packages/coding-agent/src/main.ts

This guide provides instructions for contributing to the pi-mono monorepo. It covers development setup, coding standards, versioning, changelog management, and the release process. The project uses a lockstep versioning system, meaning all packages within the monorepo share the same version number.

Sources: README.md:3-4, README.md:40-42

Development

Initial Setup

To set up the development environment, install all dependencies and build the packages.

# Install all dependencies for all workspaces
npm install

# Build all packages
npm run build

# Run linting, formatting, and type checking
npm run check

For active development, you can start watch builds for all packages, which will automatically recompile on file changes.

# Start watch builds for all packages
npm run dev

Sources: README.md:15-20, README.md:29-31

Development Commands

The following table summarizes the key npm scripts for development.

Command	Description
npm install	Installs all dependencies across all workspaces.
npm run build	Builds all packages in the correct order.
npm run dev	Starts concurrent watch builds for all packages.
npm run check	Runs Biome for linting/formatting and tsgo for type checking.
npm run test	Runs tests for all workspaces that have a test script.

Sources: README.md:15-23, package.json:9-14

Coding and Style Guidelines

To maintain code quality and consistency, please adhere to the following rules.

Code Quality

• Avoid using any types unless absolutely necessary.
• Check node_modules for external API type definitions instead of guessing.
• Do not use inline imports like await import("./foo.js").
• After making code changes, always run npm run check to ensure code quality.
• NEVER run npm run dev or npm run build as part of an automated agent workflow.
• NEVER commit code unless explicitly asked by a user.

Sources: AGENTS.md:12-20

Communication Style

• Keep answers short and concise.
• Do not use emojis in commits, issues, PR comments, or code.
• Avoid fluff or cheerful filler text. Use technical prose only.
• Be kind but direct (e.g., "Thanks @user" instead of "Thanks so much @user!").

Sources: AGENTS.md:38-43

Versioning

The monorepo uses a lockstep versioning system, where all packages must always have the same version number. This is enforced by scripts.

Sources: README.md:40-42, scripts/sync-versions.js:3-5

Bumping Versions

Version numbers should never be edited manually. Use the provided npm scripts to bump versions across all packages simultaneously.

Command	Purpose	Example
npm run version:patch	For bug fixes	0.7.5 → 0.7.6
npm run version:minor	For new features	0.7.5 → 0.8.0
npm run version:major	For breaking changes	0.7.5 → 1.0.0

These commands perform two main actions:

1. Update the version field in the package.json of every workspace.
2. Run the scripts/sync-versions.js script to update all inter-package dependency versions.

Sources: README.md:44-53, package.json:15-17

Version Synchronization Flow

The sync-versions.js script ensures that all @mariozechner/* dependencies within the monorepo point to the correct, synchronized version.

The following diagram illustrates the version synchronization process.

Changelog Management

Changelog updates are a critical part of the release process, particularly for the @mariozechner/pi-coding-agent and @mariozechner/pi-mom packages.

• New entries must always be added under the ## [Unreleased] section.
• Sections for already-released versions (e.g., ## [0.10.2] - 2025-11-27) are immutable and must not be modified after release.
• During a release, the [Unreleased] section is renamed to the new version, and a new, empty [Unreleased] section is added for the next development cycle.

Example structure:

# Changelog

## [Unreleased]

### Added
- New feature for the next release.

## [0.10.2] - 2025-11-27

### Breaking Changes
- Timestamps now use Slack format...

### Added
- Channel and user ID mappings in system prompt.

Sources: AGENTS.md:45-50, README.md:57-64, packages/mom/CHANGELOG.md

Release Process

The release process involves versioning, finalizing the changelog, tagging the release in Git, and publishing to npm.

The following diagram shows the complete release workflow.

Step-by-Step Instructions

1. Update Changelog: Add all new changes to the [Unreleased] section of the relevant CHANGELOG.md file(s).
   Sources: README.md:57-60
2. Bump Version: Run the appropriate versioning command (npm run version:patch, npm run version:minor, or npm run version:major).
   Sources: README.md:62-66
3. Finalize Changelog: Edit the CHANGELOG.md file, changing ## [Unreleased] to the new version number and today's date (e.g., ## [0.12.12] - 2025-12-05).
   Sources: AGENTS.md:56-57, README.md:68-72
4. Commit and Tag:

   git add .
   git commit -m "Release v0.12.12"
   git tag v0.12.12
   git push origin main
   git push origin v0.12.12
   

   Sources: AGENTS.md:60-65, README.md:74-79
5. Publish:

   npm run publish
   

   This script runs prepublishOnly (which cleans, builds, and checks) and then publishes all workspaces to npm.
   Sources: AGENTS.md:68-70, package.json:19
6. Prepare for Next Cycle: Add a new, empty ## [Unreleased] section to the top of the CHANGELOG.md file and commit it.
   Sources: AGENTS.md:72-73, README.md:81-84

GitHub Issues and Pull Requests

• When creating issues, add pkg:* labels to indicate which package(s) the issue affects.
• If an issue spans multiple packages, add all relevant labels.
• When closing an issue via a commit, include fixes #<number> or closes #<number> in the commit message to automatically link and close the issue upon merging.

Available package labels:

Label
pkg:agent
pkg:ai
pkg:coding-agent
pkg:mom
pkg:pods
pkg:proxy
pkg:tui
pkg:web-ui

Sources: AGENTS.md:22-36