agents.mdx

July 30, 2026 ยท View on GitHub

Source of truth and precedence

Agent behavior is resolved in this order:

  1. AGENTS.md
  2. agentplane quickstart and agentplane role <ROLE>
  3. .agentplane/WORKFLOW.md
  4. .agentplane/agents/*.json

Profiles live under .agentplane/agents/*.json, but they cannot override higher-level policy. agentplane role <ROLE> now renders one unified role-help surface: installed profile content first, then narrow CLI/runtime supplements for that role. The Quickstart is the public startup path for installed repositories.

Managed ownership remains framework-first:

  • AGENTS.md and .agentplane/policy/** are framework-managed.
  • .agentplane/policy/incidents.md is the sanctioned local place for situational directives.
  • Agents should not read incidents.md during the normal startup path; use it only for recovery, incident response, or tasks that directly modify the file.

Prompt design principles

Bundled agent profiles are intentionally narrow overlays, not a second policy gateway.

  • Each profile should own one clear decision boundary and one dominant deliverable type.
  • Agent IDs should be one word in uppercase. Use role descriptions for specialization instead of compound IDs.
  • Profiles should prefer explicit assumptions, stop conditions, and escalation rules over long narrative guidance.
  • Outputs should be evidence-oriented: changed files, checks run, remaining risks, and follow-up boundaries.
  • Task-local observations belong in task ## Findings; reusable external ones can be promoted into .agentplane/policy/incidents.md by recording Observation / Impact / Resolution plus Fixability: external (or IncidentExternal: true), with optional Incident* overrides when the inferred advice needs refinement.
  • When a profile conflicts with AGENTS.md, CLI enforcement, or policy modules, the higher-priority source wins.

Startup path

Use this order when an agent enters a repository:

  1. Read AGENTS.md.
  2. Run agentplane quickstart.
  3. Use agentplane role <ROLE> for the unified role-specific surface built from the installed profile plus CLI/runtime deltas.
  4. If you are browsing the docs site, use the Quickstart as the expanded reference page for the same startup model.

ORCHESTRATOR

  • Starts every run.
  • Translates a goal into a plan and requests approval.
  • Creates no non-executable tasks.

INTAKE

  • Classifies incoming work into task kind, mutation scope, risk flags, owner, and blueprint recommendation.
  • Produces bounded routing proposals; deterministic code still validates allowed commands, policy gates, and workflow mode.

PLANNER

  • Owns executable task creation and dependency graph updates.
  • Owns task-specific Verify Steps generation from requested outcome, tags, touched areas, and blueprint summary.
  • Treats deterministic verify-step scaffolds as fallback only.
  • For a single work item, creates exactly one task.
  • Reuses matching open tasks when scope and owner align.
  • Splits tasks only at real ownership/dependency boundaries.
  • Assigns owners from existing agent IDs.
  • If a role is missing, creates a CREATOR task first.

CODER

  • Implements changes with tight diffs.
  • Executes required checks and records concrete outcomes.

TESTER

  • Verifies behavior and regression safety.
  • Prioritizes reproducible checks and failure diagnostics.

DOCS

  • Updates user-facing documentation and task artifacts.
  • Keeps docs aligned with runtime behavior and CLI output.

REVIEWER

  • Reviews risk, regressions, and policy compliance.
  • Records findings with severity and exact file references.
  • May provide optional bounded reviewer_summary text for PR artifacts, but does not replace canonical sections, raw evidence, or freshness checks.

INTEGRATOR

  • Required closer in branch_pr.
  • Integrates task branches and performs final finish/export on base branch only after the hosted PR gate is green.

CREATOR

  • CREATOR adds new agents when no existing role fits the need.

CURATOR

  • Owns semantic decisions for selected context proposals, including durable knowledge, duplicates, consolidation, conflicts, capability proposals, and reusable incident advice.
  • Returns the bounded semantic result only; CLI supervision owns application, indexes, validation, evaluation, ACR, and task finalization.

EXTRACTOR

  • Mines repeated completed-task evidence into repo-local skills when the pattern is proven reusable.

UPGRADER

  • Verifies replace-first framework updates and plan-only upgrade reports.
  • Does not own semantic human edits to managed agent files during upgrade.
  • Ensures incident history in .agentplane/policy/incidents.md remains append-only during upgrades.
  • Role command guidance is available via agentplane role <ROLE> and is derived from the installed profile when one exists.
  • The canonical installed startup path lives in agentplane quickstart; the Quickstart is the docs-site expansion of the same flow.
  • For policy details, read AGENTS.md.
  • For task artifacts, keep Verify Steps as the acceptance contract and use ## Findings for task-local observations.