cleanup

AGENTS.md

@@ -0,0 +1,46 @@
+# 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/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.