# AGENTS.md

## Scope

Applies to entire `pi-subagents` package in this repo root.

## What this package does

- Pi extension package for running subagent tasks in separate child sessions.
- Default runner: background process runner.
- Optional runner: tmux, configured via `.pi/subagents.json` or `~/.pi/agent/subagents.json`.
- Ships prompts in `prompts/` and wrapper code in `src/wrapper/`.

## Key files

- `index.ts` — extension entrypoint; registers tool, provider override, and runner selection.
- `src/process-runner.ts` — default background child-process launcher.
- `src/tmux-runner.ts` — tmux-backed launcher.
- `src/tmux.ts` — tmux helper functions only. Keep tmux requirements/comments here or other tmux-specific files.
- `src/config.ts` — runner config loading and validation.
- `src/tool.ts` / `src/schema.ts` — tool contract and parameter/result types.
- `src/wrapper/cli.mjs` — child-session wrapper that writes artifacts/results.
- `src/*.test.ts`, `src/wrapper/*.test.ts` — regression tests.
- `docs/superpowers/specs/` — design docs created during brainstorming before implementation.
- `docs/superpowers/plans/` — implementation plans and migration notes.

## Working rules

- Keep package identity and env names on `PI_SUBAGENTS_*`; do not reintroduce old `PI_TMUX_SUBAGENT_*` names.
- In wrapper/child sessions, do not register subagent tool again. Provider override may still run before child-session early return.
- Do not register tool when no models are available.
- Preserve model-list order for schema enums; if deduping for cache keys, sort a lowercase copy and do not mutate original list.
- Process runner is default. Tmux remains opt-in and must only require `tmux` on `PATH` when tmux runner is selected.
- Keep best-effort artifact appends wrapped so failures do not prevent final `writeFile(meta.resultPath, ...)`.
- Prefer changing the smallest runner-specific surface possible; keep shared behavior in shared modules.

## Commands

- Install deps: `npm install`
- Full test suite: `npm test`
- Targeted tests: `npx tsx --test src/<file>.test.ts src/**/*.test.ts`

## Repo hygiene

- Ignore `node_modules/` for edits.
- `.worktrees/` contains isolated worktrees; do not treat them as primary source unless task explicitly targets them.
- Update this file when runner behavior, env names, commands, or package structure change.