supi CLAUDE.md

CLAUDE.md

SuPi (Super Pi) is a curated extension repo for the pi coding agent (@earendil-works/pi-coding-agent).

It is a pnpm workspace monorepo of installable pi extensions. pi loads the extensions directly as TypeScript — there is no build step.

Development status

SuPi is pre-release and not API-stable. Intentional breaking changes to package APIs, commands, configuration formats, and extension behavior are allowed when they improve the design. Do not treat backwards compatibility as a blocker unless a task explicitly asks for it.

Pi docs-first rule

• Never assume pi harness APIs, behavior, or conventions from memory or model priors.
• Before changing code or giving guidance about pi-specific behavior, read the relevant installed pi docs (README.md, matching files in docs/, and examples/) and follow linked .md cross-references.
• Start with docs/index.md for getting an overview of PI's docs.
• For Pi context mechanics verified in this repo (request payload, prompt caching, compaction, extension hooks for context control), see docs/pi/context-architecture.md.

Documentation expectations

• docs/INDEX.md is the docs index — start there for repo documentation; add new docs per its maintenance rules.
• Add JSDoc for exported APIs, config surfaces, and non-obvious behavior; skip boilerplate for trivial private code.
• Add inline JSDoc for complex internal logic where a short explanation would help maintainers.

Package layout convention

• Follow docs/conventions/package-layout.md for repo-wide package structure.
• Standardize package boundaries with src/api.ts, src/index.ts, and src/extension.ts when the package role requires them.
• Prefer package-level tests in __tests__/unit/ and __tests__/integration/, with __tests__/helpers/ and __tests__/fixtures/ as needed.
• Prefer domain folders over catch-all names like core/, shared/, or misc/.
• Keep small packages flat; add config/, ui/, session/, or other domain folders only when the package size and responsibilities clearly justify them. Packages that register tools use the per-tool directory layout under src/tool/ (docs/conventions/tool-architecture.md § Per-tool directory layout).
• Anchor examples: the large-package model (hybrid with domain folders) and the standard package model (flat with package-level tests).
• This convention is the default for new packages and for existing packages when they receive structural work.
• Packages that should stay flat unless they grow: supi-bash-timeout, supi-context, supi-debug, supi-test-utils.
• supi-skill-patches is a private maintenance package. It owns upstream synchronization and per-file compatibility patches; generated skills live in the root skills/ catalog, and selected project-local skills link into .pi/skills/.
• supi-web should stay mostly flat, but may use src/tool/ for per-tool guidance files.