pi-archimedes: Instructions file for Codex

AGENTS.md

Rules for AI agents working on this monorepo.

Monorepo Structure

• packages/core — event-channel vocabulary, bridge, chrome, text/color utils, overlay, profiler, settings-io, tool-render
• packages/ui — TUI enhancements: bash tool styling, custom editor, border spinner, thinking collapse, splash animation (depends on core)
• 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 (depends on core)
• 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/web — web search and content fetching with multi-provider routing (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 twelve)

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. npm trusted publishing — on npmjs.com, add a Trusted Publisher for @pi-archimedes/<name>: package page → Access → Trusted Publishing → add a GitHub Actions publisher for repo danielcherubini/pi-archimedes, workflow .github/workflows/release.yml. There is no CLI for this, and it is per package — an existing org/scope setting does not cover a new package. Skip it and the release workflow's --provenance publish dies with ERR_PNPM_AUTH_TOKEN_EXCHANGE … 404 followed by a bare {"error":"Not found"}, which reads like a transient registry outage but is not: npm 404s the OIDC token exchange when the package has no matching trusted publisher. Do this before the first release that includes the package — ui and web were both missed, so their versions had to be hand-published without provenance.
6. .github/workflows/release.yml — add @pi-archimedes/<name> to the ORDER list in the "Publish to npm" step, placed after its internal deps and before meta, and to the package list in the "Verify all packages are on npm" step
7. 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
8. 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