feat: Gemini subagent personas (pm-agent, doer-agent, reviewer-agent)

[kumaakh]

Summary

Gemini CLI has native subagent support via .gemini/agents/*.md. This enables defining distinct pm, doer, and reviewer personas with isolated context windows, tool sets, and behavioral rules — selected by prefixing the dispatched prompt with @agent-name.

Motivation

Current pain points with Gemini fleet members:

• Single GEMINI.md context is shared across all roles — PM, doer, and reviewer all get the same instructions
• Gemini ignores embedded STOP instructions at verify checkpoints and continues executing tasks (observed in feat: compress skill files using caveman mode to reduce per-session token cost #204 sprint — blew through V1–V5 without halting)
• No clean way to enforce role-specific tool restrictions (reviewer should be read-only, doer should not orchestrate)

Proposed Design

Agent files (committed to repo, shipped via send_files for remote members)

.gemini/agents/
├── pm-agent.md        # Orchestrates only — no code writing, dispatches work via fleet tools
├── doer-agent.md      # Executes tasks — stops at VERIFY, never self-continues past phase boundary
└── reviewer-agent.md  # Read-only — writes feedback.md, never modifies source files

Dispatch pattern

# Fleet PM sends:
execute_prompt(member, "@doer-agent\nT4 — compress batch 1...")
execute_prompt(member, "@reviewer-agent\nReview PR #204...")

Selection mechanism

No CLI flag needed. Gemini CLI routes to the named subagent automatically when @agent-name appears at the start of the prompt.

Open Questions

1. Does the pm skill become redundant? If Gemini members have a pm-agent persona, PM orchestration could move into the fleet skill itself with agent personas replacing the current pm skill structure. Or does the pm skill remain as the Claude-side orchestrator that dispatches Gemini members? Needs design thinking.

2. Remote member deployment: Unlike GEMINI.md (which is already sent via send_files before each dispatch), agent files need to land in .gemini/agents/ on the member. This is a one-time send_files per member rather than a true installation — PM can push agent files before first dispatch. But this adds a pre-flight step to the onboarding sequence.

3. Checkpoint enforcement: Will a well-crafted doer-agent.md with explicit STOP-at-VERIFY behavior actually halt the session? Needs validation — Gemini's tendency to continue may override even persona-level instructions.

4. Tool scoping per agent: Each agent .md can list allowed tools. This is a natural fit for reviewer (read-only) vs doer (full build/test/commit). Define the right tool profiles per role.

5. User-level vs project-level agents: ~/.gemini/agents/ is user-level (persists across repos), .gemini/agents/ is project-level (shipped with repo). For fleet members on remote machines, project-level + send_files is cleaner.

References

• Gemini CLI subagents docs
• Subagents announcement — Google Developers Blog
• Related: apra-fleet GEMINI member checkpoint-stop behavior observed in feat: compress skill files using caveman mode to reduce per-session token cost #204