Skip to main content
Agent Army ships with three presets that form a complete team. Each preset defines the agent’s personality, tools, and workflow through a set of workspace files.

​
Built-In Presets

PresetAgentRoleVolume
pmJunoProduct Manager — breaks down tickets, coordinates work, communicates via Slack30 GB
engTitusEngineer — writes code, opens PRs, iterates on review feedback50 GB
testerScoutQA Tester — reviews PRs, tests changes, files bugs back to Linear30 GB
For full role descriptions, see the Introduction.

​
How Agents Coordinate

Agents coordinate asynchronously through Linear and GitHub — there’s no direct agent-to-agent communication: 
Linear Ticket
     │
     ▼
Juno (PM) ── breaks down into sub-tasks
     │
     ▼
Titus (Eng) ── picks up engineering tickets, opens PRs
     │
     ▼
Scout (QA) ── reviews PRs, tests changes, files bugs
     │
     ▼
Titus (Eng) ── fixes bugs, iterates until approved
Each agent runs a heartbeat every minute that checks for new work:
  • Juno checks Linear for unrefined tickets to break down
  • Titus checks Linear for assigned engineering tickets, then checks GitHub for PR review comments
  • Scout checks GitHub for PRs ready for review, then checks Linear for verification tasks

​
Workspace Files

Each agent’s behavior is defined by workspace files injected into ~/.openclaw/workspace/ during bootstrap.

​
Per-Preset Files

FileWhat It Does
SOUL.mdCore personality — approach, values, superpowers, boundaries, vibe. This is who the agent is.
IDENTITY.mdName, role label, emoji, avatar. Short identification metadata.
HEARTBEAT.mdState machine logic executed every minute. Defines what the agent checks for and how it transitions between states (idle → working → blocked → done).
TOOLS.mdTool-specific notes and common commands. Cheat sheet for the agent’s toolchain.

​
Shared Base Files

These files are shared across all presets:
FileWhat It Does
USER.mdOwner information — name, timezone, working hours, custom notes. Personalized from template variables.
AGENTS.mdOperational instructions shared by all agents — memory management, safety rules, group chat etiquette, heartbeat protocol.
BOOTSTRAP.mdFirst-run checklist — verifies integrations (Linear, GitHub, Claude Code) work, then deletes itself.

​
Skills

Reusable skill files provide specialized workflows:
SkillUsed ByPurpose
linear-ticket-prepPMMulti-phase ticket preparation — sizing, research, context gathering, prompt generation
eng-ticket-workflowEngineerStructured ticket implementation workflow
eng-pr-testerEngineerPR testing workflow
pr-review-resolverEngineerPR review comment resolution

​
Heartbeat Logic

The heartbeat is the core loop that drives each agent. It fires every minute as a checklist — the agent walks through it top to bottom, takes any actions needed, then waits for the next tick. On first boot, the heartbeat detects BOOTSTRAP.md and runs first-time setup instead of the normal checklist — once bootstrap completes, it deletes the file and the regular heartbeat takes over. The three agents have completely different heartbeats, each tailored to their role.

​
Juno (PM)

Juno’s heartbeat is the simplest — it’s focused on ticket preparation:
  1. Check Linear for assigned tickets in “Todo” or “Backlog” that haven’t been prepped yet
  2. For each unprepped ticket, run the linear-ticket-prep skill — a multi-phase workflow that sizes the ticket, researches context, and generates an implementation prompt
  3. If any ticket is missing a description or acceptance criteria, flag it and ask the assigner for clarification
  4. Once a ticket is prepped, assign it to Titus and move it to “To Do”

​
Titus (Eng)

Titus runs a state machine that tracks multiple tickets in parallel via memory/agent-state.json:
  1. Circuit breaker — if 3+ consecutive errors have occurred, notify the owner on Slack and stop. This prevents runaway failures
  2. Process active work — loop through each item in activeWork and act based on its state:
    • AGENT_RUNNING — Claude Code is implementing the ticket. If stuck for 3+ cycles, comment on Linear and alert the owner. If finished, transition to BUILD_CHECK
    • BUILD_CHECK — run typecheck, build, and e2e tests. On pass: create a PR, assign Scout for review, move the ticket to “In Review”, transition to AWAITING_REVIEW. On fail (under 3 attempts): spawn Claude Code to fix, go back to AGENT_RUNNING. On fail (3+ attempts): create a draft PR with the failure summary
    • AWAITING_REVIEW — check if the PR is merged. If yes, rebase dependent branches and remove from active work. Otherwise, do nothing
    • IDLE_BLOCKED — waiting on a dependency. If the blocking ticket’s PR is merged, rebase and transition to AGENT_RUNNING
  3. Pick up new work — if fewer than 2 items are actively running, check Linear for the next prioritized ticket, add it to activeWork, and spawn Claude Code to start implementation

​
Scout (QA)

Scout’s heartbeat covers two jobs — resolving review comments and testing PRs:
  1. Resolve review comments — scan all open PRs for unresolved review comments. For each one, use the pr-review-resolver skill to parse comments, apply fixes via Claude Code, and push
  2. Find PRs to test — query Linear for tickets in “In Review” or “In Review by Agent” with a linked PR. Skip any ticket already tested at the same PR head commit
  3. Review against acceptance criteria — for each untested ticket, check out the PR branch and review the diff against the Linear ticket’s acceptance criteria. If requirements are unmet, comment on Linear with specific gaps and label needs-work
  4. Run build and tests — auto-detect the package manager, run install, build, and test suites. On pass: comment on Linear with a checkmark and label qa-passed
  5. Auto-fix failures — on build or test failure, invoke Claude Code with the error context to apply a minimal fix, commit, push, and re-run once. If still failing after retry, comment on Linear with the error summary and label qa-failed

​
Template Variables

Workspace files with .tpl extensions support template variables that get replaced at deploy time:
VariableDescriptionExample Value
{{OWNER_NAME}}Your nameBoss
{{TIMEZONE}}Your timezonePST (America/Los_Angeles)
{{WORKING_HOURS}}Your working hours9am-6pm
{{USER_NOTES}}Custom notes for agentsNo additional notes provided yet.
{{LINEAR_TEAM}}Linear team identifierAGE
{{GITHUB_REPO}}Target repositoryorg/repo
These are set during agent-army init and stored in the manifest.

​
Customization

All preset files live in the presets/ directory. If you clone the repo locally, you can edit any .md file directly — change an agent’s personality, tweak its heartbeat logic, or adjust its tool notes. Your changes will be picked up on the next deploy. You can also customize agents in the manifest: 
interface AgentDefinition {
  name: string;          // Resource name (e.g., "agent-pm")
  displayName: string;   // Human name (e.g., "Juno")
  role: string;          // Role identifier
  preset: string | null; // Preset name or null for custom
  volumeSize: number;    // Persistent storage in GB
  instanceType?: string; // Override instance type
  envVars?: Record<string, string>; // Extra env vars
}

​
What You Can Change

  • Volume size — Adjust persistent storage per agent (e.g., engineers may need more for large repos)
  • Instance type — Override the default server size (e.g., t3.large for compute-heavy agents)
  • Environment variables — Add agent-specific config via envVars

​
Custom Agents

To create an agent with a completely custom role, set preset: null and provide custom content:
  • soulContent — Your custom SOUL.md content defining the agent’s personality and role
  • identityContent — Your custom IDENTITY.md content with name and metadata
The agent still gets the shared base files (USER.md, AGENTS.md, BOOTSTRAP.md) and the full bootstrap stack (Docker, Node.js, Claude Code, etc.). You’re customizing who the agent is, not how it’s provisioned.