Skip to main content

Agent Roles

APM coordinates three agent roles that work together to execute a project. Each agent has a distinct role with carefully scoped context designed for its responsibilities.

APM specialises its agents by scoping their context: each agent sees only the information relevant to its role. Task Prompts are self-contained, and agents have no reason to look beyond them. The mechanisms the roles share are covered in Agent Orchestration.

Comparison​

RoleContext ScopeInstancesActive Phase
PlannerFull project vision and requirementsOnePlanning Phase
ManagerPlanning documents and MemorySuccessive (via Handoff)Implementation Phase
WorkerTask Prompt and working contextOne per domain, successive via HandoffImplementation Phase

Planner​

The Planner operates once, at the start of a session, to turn your requirements into planning documents. It conducts structured discovery with you and decomposes the gathered context into the documents that guide all subsequent work.

The overview diagram with the Planner, you, and the planning documents highlighted.The overview diagram with the Planner, you, and the planning documents highlighted.
The Planner explores your codebase and questions you about purpose, requirements, and constraints. Once you approve its understanding, it writes the Spec (what to build), the Plan (how the work is divided), and the Rules (how the work is carried out), each for your review.

Core Responsibilities:

  • Context Gathering - Assesses the workspace and conducts structured discovery to gather project context, producing an Understanding Summary for your review and approval. See Context Gathering for the full procedure.

  • Work Breakdown - Decomposes gathered context into three planning documents (Spec, Plan, and Rules), each reviewed with you before proceeding. The Planner may include notes in the Spec and Plan headers to pass context on to the Manager. Initialises the Message Bus for all Workers defined in the Plan. See Work Breakdown for the full procedure.

Manager​

The Manager coordinates execution using the three planning documents and the Tracker, recording Stage summaries and durable observations in the Index. It operates throughout the project, assigning Tasks to Workers based on the Plan, extracting context from the Spec into Task assignments, and reviewing completed work.

The overview diagram with the Manager and its Tracker highlighted.The overview diagram with the Manager and its Tracker highlighted.
The Manager hands out self-contained assignments, reviews what comes back, and records the session's progress and work history.

Operational Context: Sees the planning documents, the Tracker, the Index, and Task Logs, at a coordination level, going deeper when an investigation requires it or you ask.

Core Responsibilities:

  • Task Assignment - Assesses Task readiness, constructs self-contained Task Prompts, determines dispatch mode, and writes each prompt to the Task Bus for you to deliver. See Task Assignment for the full procedure.

  • Task Review - Reviews completed work from Task Reports and Task Logs, then decides whether to proceed, issue follow-ups, or modify planning documents. See Task Review for the full procedure.

  • Planning Document Maintenance - Updates the Spec, Plan, or Rules when execution shows the original design needs to change.

  • Memory Maintenance - Updates the Tracker and Index after each Task Review and at Stage boundaries.

  • Version Control Coordination - Owns the version control lifecycle: sets conventions with your approval, manages branches and worktrees, and merges every accepted branch before a Stage closes.

Workers​

Workers execute Tasks assigned by the Manager. Each Worker is defined in the Plan with a specific domain (frontend, backend, API, infrastructure, etc.) and follows the Rules during execution. Multiple Workers operate in parallel when dependencies allow.

The overview diagram with the Workers and Memory highlighted.The overview diagram with the Workers and Memory highlighted.
Each Worker takes the assignments of one area of the project, completes and validates them, logs the outcome, and reports back.

Operational Context: Sees its Task Prompt, the working context from its earlier Tasks, and the Rules. It sees other agents' work or the planning documents only when the Manager includes them in a Task Prompt.

Core Responsibilities:

  • Task Execution - Executes assigned Tasks following the Task Prompt instructions, validates results against its criteria, and iterates on failure, with a debug subagent when needed. See Task Execution for the full procedure.

  • Task Logging - Documents execution results in a structured Task Log and writes a Task Report to the Report Bus. See Task Logging for contents and procedure.

  • Rules Proposals - When you correct a Worker or give it a directive that could benefit all Workers, the Worker asks you after reporting whether the directive should become a Rule. The Rules change only with your approval.

Next Steps​