# pi-mainagent

pi extension providing agent personas: `/mainagent` command to switch between Markdown-defined personas (model, thinking level, tool filters), with persisted selection across sessions.

## Tech Stack

- TypeScript (pi extension, no build step — loaded as source by pi)
- Runtime APIs: `@earendil-works/pi-coding-agent` (`ExtensionAPI`, `ExtensionContext`), `pi-tui` dialogs, `pi-ai` model catalog
- No dependencies bundled: core pi packages are `peerDependencies`

## Architecture

- Single extension file: `extensions/pi-mainagent.ts` (entry point: `export default function piMainagentExtension`)
- State: `~/.pi/agent/agents/*.md` (persona definitions) + `~/.pi/agent/agent-state.json` (active persona name)
- Flow: `registerCommand("mainagent")` → picker dialog → `applySelection()` mutates session (model, thinking, tool policy, appended prompt) and updates the `main-agent-status` widget
- Events used: `session_start` (re-apply persisted selection), `before_agent_start` (persona prompt), `session_shutdown`

## Commands

- No build/test/lint configured. Verify changes by loading the extension: `pi -e D:/source/pi-mainagent`

## Code Style

- ES modules, 2-space indent, double quotes
- Constants in SCREAMING_SNAKE_CASE at top of file; helpers as plain functions
- UI strings via pi TUI components (`showSelectDialog`, theme-aware)

## Coding Rules

- Do NOT replace the minimal frontmatter parser with a YAML library — see @specs/persona-frontmatter.md for the exact supported grammar
- Persona prompts are APPENDED to pi's system prompt; never strip base prompt or skills
- `/mainagent off` must restore previous session settings exactly (saved in memory, not re-derived)
- Prompt files > 64 KB (`MAX_PROMPT_FILE_BYTES`) are rejected
- Publish hygiene: only `extensions/` ships to npm (`"files"` in package.json); docs and drafts stay out

## Constraints / What to avoid

- No new runtime dependencies (keep `peerDependencies` only)
- Do not persist tool/model changes globally — they are session-scoped; only the persona *name* is persisted
- Never write outside `~/.pi/agent/` (agents dir, state file, prompt files referenced by definitions)

## Workflow

1. Edit `extensions/pi-mainagent.ts`
2. Verify: `pi -e D:/source/pi-mainagent` → run `/mainagent` in the TUI
3. Commit; to release: bump version in `package.json`, `npm publish`

Self-maintenance rule:
> When you modify code, update the relevant file in `specs/`

## References

- @specs/module-index.md — modules and criticality tiers
- @specs/persona-frontmatter.md — persona file grammar and editing rules