arch-dotfiles/.pi/agent/extensions/subagent

Subagent roles for pi

Installed roles:

• reviewer — review changes, bugs, risks, maintainability
• librarian — explore and map a codebase
• design-engineer — frontend-aware UI/UX direction, design systems, and implementation-ready recommendations
• executor — implement ordered coding tasks from a defined todo list
• planner — interactive planning specialist that can ask clarifying questions and return an ordered executor-ready todo list

Commands

• /subagents — list discovered user-level agents
• /subagents both — include project-local .pi/agents

Example prompts

• Use the subagent tool with reviewer to inspect the auth refactor.
• Use subagent in parallel: librarian maps the settings flow, design-engineer proposes an improved UX direction, reviewer lists product and implementation risks.
• Chain librarian -> design-engineer to redesign onboarding. Use {previous} in the second task.
• Use executor to implement this ordered todo list exactly as written, then summarize what was completed and validated.
• Use planner to clarify ambiguity only when needed and output an ordered implementation todo list for executor handoff.

Interactive planner + ask_user

planner is marked interactive: true and runs through an RPC-backed child agent path.

• Interactive child agents use a helper extension tool: ask_user
• ask_user supports input, confirm, and select modes (plus editor)
• Child tool activation is applied on session_start via PI_SUBAGENT_TOOLS so custom tools like ask_user are reliably active

Notes

• User agents live in ~/.pi/agent/agents
• Project-local agents can live in .pi/agents
• Project agents require agentScope: "project" or "both"
• Parallel mode allows up to 8 tasks and runs up to 4 concurrently
• reviewer uses openai-codex/gpt-5.4:xhigh
• librarian uses anthropic/claude-sonnet-4-6
• design-engineer uses google-antigravity/gemini-3-flash
• executor uses openai-codex/gpt-5.3-codex:high
• planner uses anthropic/claude-sonnet-4-6

Current interactive limitations

• Interactive subagents are currently supported only in single mode ({ agent, task })
• Interactive subagents are currently rejected in parallel and chain modes
• Interactive subagents require ctx.hasUI (interactive TUI or RPC mode with extension UI handling)