Agent Roles

Agent Roles

Orchestrator

Implementation: LoopEngine class

The orchestrator owns the complete loop, enforces invariants, delegates stages, and decides whether to continue, ship, or hand off.

Responsibilities

• Load durable loop state
• Validate budgets and permissions
• Select the next legal state transition
• Delegate to one role at a time
• Require verifier evidence before completion
• Detect repeated/no-progress cycles
• Persist state after every transition
• Enforce terminal conditions

Discoverer

Role name: "discoverer"

Builds a compact, evidence-backed working set before planning.

Inputs

• Goal, repository/project state, memory, constraints, available tools

Outputs

• Relevant files/systems
• Existing tests and quality gates
• Current failures/blockers
• Prior attempts from memory
• Dependencies and external assumptions
• Unknowns that materially affect correctness

Planner

Role name: "planner"

Converts discovery evidence into a finite, testable execution plan.

Plan requirements

Every step must include:

• action, scope, preconditions, expected result
• validation, rollback, mutation risk, responsible agent

Rules

• Prefer smallest vertical slice
• Do not create speculative work
• Separate mandatory work from optional improvements
• Define a concrete stop condition before execution

Executor

Role name: "executor"

Implements an approved plan in an isolated workspace.

Rules

• Execute only approved steps
• Use worktree/branch isolation for concurrent changes
• Record commands/actions and resulting evidence
• Use idempotency keys for external mutations
• Never self-certify completion

Verifier

Role name: "verifier"

Independently determines whether acceptance criteria are satisfied.

Verification priority

1. Deterministic tests/build/type checks
2. Security and policy checks
3. Behavioral/integration checks
4. Evidence consistency
5. Regression checks

Result

Return PASS, FAIL, or INCONCLUSIVE per criterion.

Reviewer

Role name: "reviewer"

Performs independent engineering review after implementation and verification.

Review dimensions

• Correctness, security, reliability, performance
• Maintainability, backward compatibility, observability
• Operational cost, test adequacy, scope discipline

Finding classifications

blocking, major, minor, note

Repairer

Role name: "repairer"

Resolves verifier/reviewer findings using the smallest bounded change.

Rules

• Repair only evidenced failures
• Do not redesign unrelated components
• Track repair attempt number
• Compare new failure against prior failures
• Stop and escalate on repeated no-progress patterns