How to Configure Auto-Retry and Quality Gates in Prime Agent Autonomous Mode

Configure auto-retry and quality gates in Prime Agent by setting autonomous.gates.commands for validation checks and autonomous.gates.maxRetries to automatically re-run failed turns up to a specified limit.

Prime Agent's autonomous mode enables the agent to execute multiple turns without human intervention until configured limits or quality gates trigger a stop. Understanding how to configure auto-retry behavior and quality gate validation ensures reliable, self-correcting automation workflows. This configuration is managed through the AutonomousConfig interface and runtime state in packages/coding-agent/src/core/autonomous.ts.

Understanding Quality Gates in Prime Agent

Quality gates are shell commands executed after each autonomous turn that validate the agent's work. The agent invokes these commands and inspects the exit code to determine whether to continue or halt.

How Quality Gates Work

In packages/coding-agent/src/core/autonomous.ts, the refreshAutonomousQualityGates function manages gate execution:

• Gates must exit with status 0 to permit continuation
• Non-zero exits trigger retry evaluation (if maxRetries > 0)
• Gates run with a configurable timeout (timeoutMs)

Quality gates typically include:

• Linting: npm run lint, eslint ., flake8
• Type checking: tsc --noEmit, mypy
• Tests: npm test, pytest
• Custom validation scripts: project-specific checks

Configuring Auto-Retry Behavior

Auto-retry is controlled by the maxRetries field within autonomous.gates. When a gate fails, Prime Agent automatically re-executes the turn provided the workspace has changed, tracked in AutonomousRuntimeState.gateAttempts.

Retry Mechanics

The retry flow in nextAutonomousContinuation (from autonomous.ts) follows these steps:

1. Compare current retry count (state.gateAttempts[gateId]) against maxRetries
2. Check if workspace state changed since last attempt
3. If both conditions pass, inject a new autonomous continuation via addAutonomousContinuation
4. If retries exhausted, set limit reason to "retry_exhausted" and stop

Critical distinction: Retries consume autonomous continuations but do not increment the turn counter until the retry budget is exhausted.

Complete Configuration Reference

Setting	Path	Description	Default
enabled	autonomous.enabled	Master switch for autonomous mode	false
commands	autonomous.gates.commands	Array of shell commands to run post-turn	[]
maxRetries	autonomous.gates.maxRetries	Retry attempts per gate failure	0
timeoutMs	autonomous.gates.timeoutMs	Per-gate execution timeout	30000
maxContinuations	autonomous.limits.maxContinuations	Total autonomous continuations allowed	Infinity
maxTurns	autonomous.limits.maxTurns	Maximum turns before auto-stop	Infinity
maxTokens	autonomous.limits.maxTokens	Token budget for autonomous runs	Infinity
timeoutMs	autonomous.limits.timeoutMs	Global timeout for entire run	Infinity

These defaults are defined in DEFAULT_AUTONOMOUS_GATES and merged via mergeAutonomousConfig in packages/coding-agent/src/core/agent-session-config.ts.

Configuration Methods

Prime Agent supports three configuration pathways, all converging on the same runtime structure.

Method 1: JavaScript/TypeScript API

import { mergeAutonomousConfig } from 'packages/coding-agent/src/core/agent-session-config';

const autonomousConfig = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['npm run lint', 'npm run test'],
    maxRetries: 2,
    timeoutMs: 15000
  },
  limits: {
    maxContinuations: 10,
    maxTurns: 50,
    maxTokens: 100_000,
    timeoutMs: 5 * 60_000
  }
});

Method 2: CLI Flags

Parsed in runtimeAutonomousConfigFromArgs within packages/coding-agent/src/main.ts:

prime-agent \
  --autonomous \
  --autonomous-gates="npm run lint" \
  --autonomous-gates="pytest" \
  --autonomous-gate-retries=3 \
  --autonomous-gate-timeout=20000 \
  --autonomous-max-continuations=20 \
  --autonomous-max-turns=100 \
  --autonomous-timeout=600000

Method 3: Runtime Slash Commands

Handled in packages/coding-agent/src/core/slash-commands.ts:

// Enable autonomous mode
await session.prompt('/autonomous on');

// Check current configuration and limits
await session.prompt('/autonomous status');

// Disable autonomous mode
await session.prompt('/autonomous off');

Practical Configuration Examples

Example: Type-Safe Development with Retry

import { mergeAutonomousConfig } from 'packages/coding-agent/src/core/agent-session-config';

const config = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['tsc --noEmit', 'npm run lint:fix -- --max-warnings=0'],
    maxRetries: 3,        // Allow 3 attempts to fix type/lint errors
    timeoutMs: 30000
  },
  limits: {
    maxContinuations: 15, // Hard stop after 15 continuation attempts
    maxTurns: 75
  }
});

Example: Test-Driven Autonomous Development

const tddConfig = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['npm test -- --watch=false --bail'],
    maxRetries: 5,        // Generous retries for iterative test fixing
    timeoutMs: 60000      // Longer timeout for test suites
  },
  limits: {
    maxContinuations: 25,
    maxTokens: 250_000    // Higher token budget for test generation
  }
});

Example: Strict Mode (No Retries)

For safety-critical edits where any failure requires human review:

const strictConfig = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['make verify'],  // Comprehensive verification
    maxRetries: 0,              // No auto-retry on failure
    timeoutMs: 120000
  },
  limits: {
    maxContinuations: 5,
    maxTurns: 20
  }
});

Internal Runtime Flow

The autonomous execution loop in packages/coding-agent/src/core/autonomous.ts coordinates these components:

Function	Purpose
nextAutonomousContinuation	Determines if another turn should run based on gates, limits, and retry state
refreshAutonomousQualityGates	Executes configured gate commands and evaluates exit codes
addAutonomousContinuation	Injects a new autonomous continuation into the session
autonomousLimitReason	Returns string reason when limits trigger stop ("maxContinuations", "retry_exhausted", etc.)

Status display is handled in packages/coding-agent/src/modes/print-mode.ts, which renders current gate status, retry counts, and limit reasons in the TUI.

Key Implementation Files

• packages/coding-agent/src/core/autonomous.ts — Core runtime state, gate execution, retry logic
• packages/coding-agent/src/core/agent-session-config.ts — Configuration merging and defaults
• packages/coding-agent/src/main.ts — CLI argument parsing
• packages/coding-agent/src/core/slash-commands.ts — /autonomous command handlers
• packages/coding-agent/src/modes/print-mode.ts — TUI status display

Summary

• Quality gates are shell commands configured via autonomous.gates.commands that validate each turn's output
• Auto-retry is enabled by setting autonomous.gates.maxRetries > 0, allowing re-execution when gates fail
• Retries only proceed when workspace changes are detected, preventing infinite loops on unfixable errors
• Configure via JavaScript API, CLI flags, or runtime slash commands depending on your workflow
• Combine maxRetries with maxContinuations and maxTurns to create reliable bounded autonomy

Frequently Asked Questions

What happens when all retries are exhausted?

When gateAttempts[gateId] reaches maxRetries, the runtime sets the limit reason to "retry_exhausted" and stops injecting autonomous continuations. The session remains active for manual interaction but will not auto-continue. You can inspect the final gate output to diagnose why recovery failed.

Can different gates have different retry limits?

The current implementation in autonomous.ts applies a single maxRetries value to all gates in the commands array. Retry tracking is per-gate-ID, but the limit is shared. For asymmetric retry policies, wrap commands in external scripts that implement custom logic.

How does Prime Agent detect workspace changes between retries?

Between retry attempts, the runtime compares workspace snapshots. If no changes occurred, the retry is not granted to prevent infinite loops. This check happens in nextAutonomousContinuation before calling addAutonomousContinuation.

Do retries count against continuation and turn limits?

Retries consume autonomous continuations from maxContinuations but do not increment the turn counter until the retry budget is exhausted. This design allows iterative fixing without rapidly depleting the turn budget.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}