47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# 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.
|