AGENTS.md

Scope

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

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/.

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.

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.

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.