# AGENTS.md — Pi Coding Agent Configuration

> Personal config for [pi-coding-agent](https://github.com/badlogic/pi-mono) with custom extensions, agents, and workflows. See [docs/](docs/) for full documentation.

## Directory Structure

```
~/.pi/agent/
├── AGENTS.md              # This file (agent context)
├── SYSTEM.md              # Custom system prompt
├── settings.json          # Pi config (model, theme, packages)
├── local-endpoints.json   # LLM backend endpoint (git-ignored)
├── mcp.json               # MCP server config (Playwright MCP)
├── playwright-mcp.json    # Browser config (bundled Chromium)
├── extensions/            # TypeScript extensions (auto-transpiled)
│   ├── shared/            # Reusable UI components and utilities (barrel via design-system.ts)
│   ├── enhanced-edit/     # 9-level fuzzy edit + multi_edit
│   ├── clipboard/         # Multi-slot session scratchpad (clipboard_write/clipboard_read)
│   ├── cosmetics/         # Unified indicator + splash (Kirby persona)
│   ├── project-context/   # Auto-loads project docs
│   ├── questionnaire/     # Multi-question UI
│   ├── todo/              # Persistent todo list tool
│   └── toon-transformer/  # JSON→TOON converter
├── agents/                # Subagent definitions (YAML + prompt)
├── skills/                # Specialized instruction sets
├── docs/                  # Setup guides and reference docs
└── themes/                # Color themes
```

## Extensions

See [docs/extensions.md](docs/extensions.md) for the full list, shared modules, and development guide.

**Key extensions:** `enhanced-edit/` (fuzzy matching + multi_edit), `toon-transformer/` (JSON→TOON), `cosmetics/` (unified indicator + splash with persona system), `project-context/` (auto-loads project docs), `clipboard/` (multi-slot session scratchpad), `questionnaire/`, `todo/`.

## Agents

Three core agents with custom definitions in `agents/`. All use fresh context. Additional builtin agents from `pi-subagents` are available but rarely needed. See [docs/agents.md](docs/agents.md).

| Agent      | Purpose                                          | Custom |
| ---------- | ------------------------------------------------ | ------ |
| `scout`    | Fast codebase recon                              | ✓      |
| `worker`   | General-purpose implementation                   | ✓      |
| `reviewer` | Read-only code review (quality, security)        | ✓      |
| `planner`  | Implementation planning (no file edits, builtin) |        |

**Overrides in `settings.json`:** scout uses haiku. Worker, planner, oracle forced to `defaultContext: "fresh"`. The pi-subagents skill is disabled — SYSTEM.md is the sole authority on subagent usage.

## Slash Commands

| Command                 | Description       |
| ----------------------- | ----------------- |
| `/toon stats\|on\|off`  | TOON transformer  |
| `/todos`                | Todo list         |
| `/run <agent> "<task>"` | Run subagent      |
| `/chain <steps>`        | Run agent chain   |
| `/agents`               | Manage agents     |
| `/powerline [preset]`   | Status bar config |

## Skills

| Skill                | Description                                                            |
| -------------------- | ---------------------------------------------------------------------- |
| `repo-maintenance`   | Run tests, audit packages, detect stale docs, commit pending work      |
| `mermaid-diagrams`   | Mermaid diagrams with 15+ themes, dual CLI rendering (SVG + ASCII)     |
| `code-search`        | Tool selection matrix (LSP → AST → raw), monorepo navigation          |
| `duckdb-analytics`   | DuckDB-based data analysis with Python                                 |
| `codebase-audit`     | Dead code, type hygiene, test gaps, file sizing, package boundaries    |
| `pkg-boundary-audit` | Import violations, circular deps, declared-vs-actual in any monorepo   |

## Coding Guidelines

Strict rules for all work in this repo. **Read before making changes:**
[docs/coding-guidelines.md](docs/coding-guidelines.md)

Key points: folder-per-extension, ≤ 300 lines per file, use `extensions/shared/`, no `any` types, write tests, update docs on every change.

## Additional Docs

| Doc                                                          | Description                                   |
| ------------------------------------------------------------ | --------------------------------------------- |
| [docs/extensions.md](docs/extensions.md)                     | Extensions, shared modules, development guide |
| [docs/coding-guidelines.md](docs/coding-guidelines.md)       | Coding standards for this repo                |
| [docs/packages.md](docs/packages.md)                         | Community packages and MCP servers            |
| [docs/agents.md](docs/agents.md)                             | Subagents, chains, skills                     |
| [docs/commands.md](docs/commands.md)                         | Slash commands and hotkeys                    |
| [docs/configuration.md](docs/configuration.md)               | Config files reference                        |
| [docs/browser-mcp.md](docs/browser-mcp.md)                   | Playwright MCP setup                          |

## License

MIT
