Agent Team

Agent Definitions

Definitions live in .apm/agents/ and are routed by the Orchestrator.

Orchestrator

Coordinates the Phase 0-4 workflow, delegates work, tracks state, and enforces verification gates. It classifies from supplied evidence and never executes specialist work directly. Classifies failures into retry, fixable, replan, flaky, regression, platform-specific, and test-bug categories so each routes to the right agent. Applies relational invariant fallbacks when agent outputs miss conditional fields - inferring intent and filling safe defaults instead of rejecting valid work. Loads task scope from the persisted plan.yaml on resume, propagates each specialist's typed handoff output into dependent tasks' handoff.relevant_context, and fills cluster shared_context verbatim from producer returns so downstream payloads stay byte-identical. Promotes stable research findings to repo memory and injects relevant memory into planning context.

Core Agents

Quality & Review Agents

Specialized Agents

Reviewer routing

gem-reviewer uses three axes:

• review_mode: standard, high, or critic controls review intensity.
• review_target: plan, task, code, decision, docs, config, or integration selects the target.
• review_scope: changed, affected, or full limits how much supplied evidence is examined. It is not permission to gather more: plan/task/decision reviews evaluate what they were handed, while code/config/integration reviews read the target as their subject.

Single bounded, low-risk work uses the direct specialist fast path. Other TRIVIAL/LOW work uses ephemeral planning without Planner or Reviewer calls. For MEDIUM/HIGH work, the Orchestrator supplies bounded discovery in planning_context; the Planner owns waves and handoffs, while the Orchestrator owns state, retries, approvals, review, and replan limits. MEDIUM/HIGH plans receive a mechanical self-check from the Planner before they are written (owners, waves, dependencies, criteria, cluster consistency); routine MEDIUM plans need nothing further. Explicit requests, insufficient evidence, HIGH complexity, and high-risk or critic signals require independent review.

Critic mode is read-only. It evaluates assumptions, counterexamples, risks, alternatives, reversibility, and decision blockers without changing files or claiming completion. Results include critic_verdict, challenges, alternatives, and decision_blockers, each with evidence, impact, and action. There is no standalone gem-critic agent.

Critic requests carry these objects under handoff:

review_mode: critic
review_target: decision
review_scope: full
handoff:
  critic_subject:
    objective: str
    proposal: str
    constraints:
      - str
    alternatives:
      - str
    evidence:
      - str
    decision_needed: str
  critic_context:
    audience: str
    time_horizon: str
    success_criteria:
      - str
    known_unknowns:
      - str

Model Compatibility

All agent definitions use valid YAML contracts and consolidated output fields so they work across commercial and open models without prompt-engineering workarounds. The Orchestrator applies relational invariant fallbacks - when an agent output violates a conditional requirement, it infers the most likely intent and fills the gap instead of rejecting valid work.

Model Routing

The Orchestrator supports two configurable model tiers through model_routing in .gem-team.yaml:

When enabled, the Orchestrator passes the configured tier model to each delegated agent. The Orchestrator itself is not routed through these tiers.

Configurable in .gem-team.yaml. Swap with equivalent models from your provider.

Packaged Skills

Reusable, task-specific guidance lives separately from agent definitions in .apm/skills/:

Skills are loaded for matching tasks and keep specialist agent definitions focused.