0xrsydn/arch-dotfiles
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
arch-dotfiles/.pi/agent/extensions/subagent/README.md

2.3 KiB
Raw Blame History

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)