pi-archimedes AGENTS.md

AGENTS.md

Rules for AI agents working on this monorepo.

Monorepo Structure

• packages/core — bus, chrome, text/color utils, editor, message, startup, thinking
• packages/ask — structured question tool with tabbed flow and inline notes (depends on core)
• packages/footer — status bar (depends on core)
• packages/diff — Shiki-powered diff rendering (standalone)
• packages/image-paste — clipboard image paste (standalone)
• packages/subagent — subagent dispatch with live TUI streaming and cost tracking (depends on core, todo)
• packages/todo — todo list tool with auto-clear and subagent visibility (depends on core)
• packages/notify — delayed desktop notifications with circuit breaker (depends on core)
• packages/session-name — auto session naming (depends on core)
• packages/mcp — MCP client adapter (feature parity with pi-mcp-adapter: /mcp command family, management + setup panels, OAuth, metadata cache) (depends on core)
• packages/sudo — safe privileged execution (sudo_exec tool, masked password prompt, interactive-sudo bash guard) (depends on core)
• meta — orchestrator + composed settings (depends on all eleven)

Adding a New Package

When a new package is added under packages/<name>/, update all of these or it will silently break the release / pi install flow (this is exactly how todo got missed):

1. packages/<name>/package.json — must include:
   • "version" matching the shared monorepo version
   • "keywords": ["pi-package"]
   • "files": ["src"]
   • "pi": { "extensions": ["./src/index.ts"] } ← required; without it, standalone pi install @pi-archimedes/<name> loads nothing
   • Internal deps as "@pi-archimedes/core": "workspace:*" (pnpm rewrites this to a real version at publish time)
   • peerDependencies for @earendil-works/pi-coding-agent / pi-tui / pi-ai as needed
2. meta/package.json — add "@pi-archimedes/<name>": "workspace:*" to dependencies
3. meta/src/index.ts — import and register the new package's entry, gated by isPluginEnabled("<name>") (the single global gate from meta/src/plugins.ts)
4. meta/src/plugins.ts — add the package to the PLUGINS manifest (id, label, description, namespace (e.g. archimedes.<newkey>), load()). A manifest entry is required: registration alone is not enough — the gate, /archimedes settings items, and shutdown all key off the manifest, and a missing entry means the package also disappears from the /plugins menu. (There is no defaultEnabled any more — the manifest entry carries the settings-namespace key the gate reads, and no plugin is off-by-default today.)
5. .github/workflows/release.yml — add a pnpm --filter "@pi-archimedes/<name>" publish --access public --no-git-checks line, placed after its internal deps and before meta
6. AGENTS.md — add to the Monorepo Structure list; bump the "all N package versions" count and the "N package directories" type-check count in Release Steps; add the package to the publish-order line
7. README.md — add a feature section, a line in the monorepo layout tree, a pi install @pi-archimedes/<name> line under "install selectively", and a settings-table entry if it has settings