Skip to content

AGENTS.md

Latest commit

 

History

History
150 lines (113 loc) · 3.96 KB

AGENTS.md

File metadata and controls

150 lines (113 loc) · 3.96 KB
Raw

AGENTS.md

Instructions for AI coding agents working in this repository.

Repository purpose

This is a Pi package monorepo for packages published under the @codella npm scope.

Package naming

Packages should use pi-<type>-<name> names where practical:

  • Themes use pi-theme-* names:
    • @codella/pi-theme-cyberpunk
    • @codella/pi-theme-candy
    • @codella/pi-theme-christmas
    • @codella/pi-theme-halloween
    • @codella/pi-theme-grayscale
  • Prompt templates use pi-prompt-* names:
    • @codella/pi-prompt-plan
  • Compatibility packages may keep old names while pointing to renamed packages:
    • @codella/pi-plan-mode -> @codella/pi-prompt-plan
  • Extensions currently include:
    • @codella/pi-mcp-support

Layout

packages/
  pi-theme-cyberpunk/
    themes/
  pi-theme-candy/
    themes/
  pi-theme-christmas/
    themes/
  pi-theme-halloween/
    themes/
  pi-theme-grayscale/
    themes/
  pi-prompt-plan/
    prompts/
  pi-plan-mode/     # compatibility package for pi-prompt-plan
    prompts/
  pi-mcp-support/
    extensions/
    examples/

Pi package rules

Every publishable package must:

  • Include "keywords": ["pi-package", ...].
  • Include a pi manifest in package.json.
  • Use a files allowlist so tarballs contain only intended package assets.
  • Include README.md and LICENSE.
  • Use publishConfig.access = "public" for scoped public npm packages.

Dependencies

  • Pi core imports should be peerDependencies with a "*" range and optional peer metadata.
  • Runtime dependencies needed by an extension must be in dependencies.
  • Do not rely on root devDependencies at Pi runtime.

Commit preparation

Before making any commit, consider whether the change also requires updating AGENTS.md and any relevant README.md files. If it does, include those documentation updates in the same atomic commit as the related change.

Validation

Before considering changes complete, run:

npm run validate
npm run pack:dry-run

Or dry-run individual packages:

npm run pack:theme
npm run pack:candy
npm run pack:christmas
npm run pack:halloween
npm run pack:grayscale
npm run pack:plan
npm run pack:plan-mode
npm run pack:mcp

Review tarball contents before publishing.

Local testing before publishing

Test Pi packages locally before publishing.

Load prompt templates/extensions directly for a quick test:

pi --no-prompt-templates -e ./packages/pi-prompt-plan
pi --no-extensions -e ./packages/pi-mcp-support

Load a theme directly for a quick test:

pi --no-themes --theme ./packages/pi-theme-cyberpunk/themes/cyberpunk.json
pi --no-themes --theme ./packages/pi-theme-candy/themes/candy.json
pi --no-themes --theme ./packages/pi-theme-christmas/themes/christmas.json
pi --no-themes --theme ./packages/pi-theme-halloween/themes/halloween.json
pi --no-themes --theme ./packages/pi-theme-grayscale/themes/grayscale.json

For a more realistic local install, use project settings:

pi install ./packages/pi-prompt-plan -l
pi install ./packages/pi-mcp-support -l
pi install ./packages/pi-theme-cyberpunk -l
pi install ./packages/pi-theme-candy -l
pi install ./packages/pi-theme-christmas -l
pi install ./packages/pi-theme-halloween -l
pi install ./packages/pi-theme-grayscale -l

Remove local test installs when done:

pi remove ./packages/pi-prompt-plan -l
pi remove ./packages/pi-mcp-support -l
pi remove ./packages/pi-theme-cyberpunk -l
pi remove ./packages/pi-theme-candy -l
pi remove ./packages/pi-theme-christmas -l
pi remove ./packages/pi-theme-halloween -l
pi remove ./packages/pi-theme-grayscale -l

Publishing safety

Never run npm publish without explicit user approval for the exact package(s) and version(s).

MCP support

@codella/pi-mcp-support documents config in packages/pi-mcp-support/README.md and example config in packages/pi-mcp-support/examples/mcp.json.

Supported config lookup order:

  1. .pi/mcp.json
  2. ~/.pi/agent/mcp.json
  3. ~/.pi/mcp.json legacy fallback