pi-subagents AGENTS.md

Development Rules

Conversational Style

• Keep answers short and concise
• No emojis in issues, PR comments, or code
• No fluff or cheerful filler text (e.g., "Thanks @user" not "Thanks so much @user!")
• Technical prose only, be direct
• When the user asks a question, answer it first before making edits or running implementation commands.
• When responding to user feedback or an analysis, explicitly say whether you agree or disagree before saying what you changed.

Code Quality

• Read files in full before wide-ranging changes, before editing files you have not fully inspected, and when asked to investigate or audit. Do not rely on search snippets for broad changes.
• No any unless absolutely necessary.
• Inline single-line helpers that have only one call site.
• Check node_modules for external API types (@earendil-works/pi-*, @sinclair/typebox, etc.); don't guess.
• No inline imports (await import(), import("pkg").Type, dynamic type imports). Top-level imports only.
• Never remove or downgrade code to fix type errors from outdated deps; upgrade the dep instead.
• Match the surrounding code style — it is enforced by biome (biome.json).
• Always ask before removing functionality or code that appears intentional.
• Do not preserve backward compatibility unless the user asks for it.
• This is a pi extension. Respect the Claude Code-compatible tool names, calling conventions, and UI patterns the extension deliberately mirrors; don't diverge from them without a stated reason.
• When reviewing a diff, favor solutions that are elegant, not overengineered — flag needless abstraction, layering, or defensive code that the change doesn't warrant.

Documentation

Read the file that covers a surface before changing its behavior; update it in the same change.

File	Covers
README.md	User-facing reference: features, install, tool parameter tables, commands, settings and defaults, the event table, the RPC channel list, and the src/ file map (## Architecture). Source of truth for defaults and setting names.
docs/workflows.md	SubagentWorkflow in depth — how the model writes a script, editing and re-running it, saving a named workflow, agent() options, recipes, troubleshooting. Examples in examples/workflows/.
docs/rpc.md	Calling this extension from another pi extension — pi.events lifecycle events (subagents:completed, subagents:ready, …), the subagents:rpc:* channels (ping, spawn, stop, consume), spawn options, error strings, and the Symbol.for("pi-subagents:manager") registry. Source: src/cross-extension-rpc.ts.
CONTRIBUTING.md	Contributor guidelines and quality bar.
SECURITY.md	Vulnerability reporting.