38 lines
1.6 KiB
Markdown
38 lines
1.6 KiB
Markdown
# Repo Guidelines
|
|
|
|
## Scope
|
|
|
|
This repo implements the `subagent` pi extension in `index.ts`.
|
|
|
|
## Key Behavior
|
|
|
|
- Parent-facing tool: `subagent`.
|
|
- Internal child-only tool: `subagent_finalize`.
|
|
- Never register `subagent_finalize` in the parent context; only when `PI_SUBAGENT_CHILD=1`.
|
|
- Subagents are loaded from `~/.pi/agent/subagents/*.md` (user config only).
|
|
- The `subagent` tool is only registered when at least one subagent exists.
|
|
- Subagent sessions are sticky and persisted at:
|
|
`~/.pi/subagent-sessions/<cwd-hash>/<agent>_<sessionId>.jsonl`.
|
|
- Omitting `sessionId` creates a new UUID-backed session.
|
|
- Passing `sessionId` resumes the same agent/cwd child session.
|
|
- A prompt's `.md` body **replaces** pi's default system prompt (passed via `--system-prompt`). It is the entire system prompt; do not write it as an appendage. Pi still tacks on AGENTS.md/skills/date/cwd.
|
|
- Retries reuse the same session and append a new user message nudging the child to finalize. The system prompt is stable across attempts (cache-friendly).
|
|
|
|
## Validation
|
|
|
|
- Child agents must finish by calling `subagent_finalize`.
|
|
- Valid success: `status=SUCCESS` with non-empty `result`.
|
|
- Valid error: `status=ERROR` with non-empty `error`; `result` is optional partial findings.
|
|
- If finalization is missing/invalid, retry by continuing the same sticky session, capped by `MAX_FINALIZE_RETRIES`.
|
|
|
|
## Commands
|
|
|
|
- Typecheck: `npm run typecheck`
|
|
- Lint: `npm run lint`
|
|
|
|
## Style
|
|
|
|
- Keep the extension simple; avoid debug metadata unless needed.
|
|
- Do not expose retry internals to the parent by default.
|
|
- Prefer precise tool/context isolation over prompt-only enforcement.
|