# How the Agents Orchestrator Implements the Dev-QA Continuous Loop with Retry Logic

> Discover how the Agents Orchestrator implements a Dev-QA continuous loop with retry logic. Learn about task sequencing, agent interaction, and state persistence in this technical deep dive.

- Repository: [Michael Sitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents)
- Tags: internals
- Published: 2026-03-09

---

**The Agents Orchestrator implements a deterministic Dev-QA continuous loop with retry logic by sequencing tasks through developer and EvidenceQA agents, enforcing a maximum of three retry attempts before escalation, and persisting state in markdown task lists.**

The `msitarzewski/agency-agents` repository defines an autonomous pipeline manager that drives full development workflows through a rigorous quality assurance cycle. At its core, the **Agents Orchestrator** manages a continuous Dev-QA loop that ensures no code progresses to production without passing automated validation, while preventing infinite retry cycles through strict attempt limits.

## Overview of the Dev-QA Continuous Loop

The orchestrator divides the development workflow into four logical phases. The Dev-QA continuous loop resides in **Phase 3**, which follows a deterministic state machine to process each implementation task.

The workflow transitions through four primary states:

- **Idle → Development**: The orchestrator spawns a specialized developer agent (Frontend Developer, Backend Architect, or Senior Developer) with the task description and architecture context.
- **Development → Quality Validation**: Upon task completion, the orchestrator spawns an **EvidenceQA** agent that executes task-specific tests, captures screenshots, and returns a PASS/FAIL verdict with explicit feedback.
- **Quality Validation → Next Task**: If QA returns **PASS**, the orchestrator increments the task pointer, resets the retry counter, and loops back to process the next unchecked task.
- **Quality Validation → Retry / Escalate**: If QA returns **FAIL**, the orchestrator increments the retry counter. If the count remains below three, it feeds the QA feedback back to the developer agent and repeats the Development state. If the count reaches three, it generates an escalation report and blocks the task while allowing the pipeline to proceed with later phases.

## State Machine and Retry Logic

The retry logic operates as a bounded counter system designed to prevent runaway cycles while maximizing automated recovery.

When a task fails QA validation, the orchestrator performs three critical actions:

1. **Increments** the `retryCount` variable for that specific task.
2. **Compares** the current count against the maximum limit of **3 attempts**.
3. **Routes** the workflow based on the comparison: if less than 3, return to Development with feedback; if equal to 3, trigger escalation.

The retry counter **resets to zero** only when a task achieves a PASS verdict, ensuring that each new task starts with a fresh attempt budget.

## Implementation Details

### Phase 3 Specification in agents-orchestrator.md

The core logic for the Dev-QA continuous loop is defined in [`specialized/agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md) at lines 77-94. The specification uses explicit Bash-style command descriptions and decision logic:

```markdown

# Phase 3: Development-QA Continuous Loop

...

# For each task, run Dev‑QA loop until PASS

# Task 1 implementation

"Please spawn appropriate developer agent … to implement TASK 1 ONLY …"

# Task 1 QA validation

"Please spawn an EvidenceQA agent to test TASK 1 implementation only …"

# Decision logic:

# IF QA = PASS: Move to Task 2

# IF QA = FAIL: Loop back to developer with QA feedback

# Repeat until all tasks PASS QA validation

```

This specification instructs the orchestrator to process tasks sequentially, enforcing the loop structure through explicit conditional commands.

### Retry Counter and Limits

The maximum retry policy is codified in multiple sections of the orchestrator specification:

- **Line 42**: "Maximum 3 attempts per task before escalation"
- **Lines 136-140**: The Task-by-Task Quality Loop table defines the increment, reset, and escalation steps
- **Line 157**: "Maximum 3 retry attempts per task"

The logic follows a strict pattern: increment on failure, reset on success, escalate on exhaustion.

### State Management Variables

The orchestrator tracks three critical state variables for each task, persisted in the tasklist files:

| Variable | Purpose |
|----------|---------|
| `currentTask` | Identifier of the task being processed |
| `retryCount` | Number of QA-failed cycles for the current task (resets on PASS) |
| `taskStatus` | `[x]`-checked flag in the markdown task list (`project-tasks/*-tasklist.md`) |

State persistence in markdown files enables the orchestrator to resume processing after interruptions without losing retry context.

### Escalation Path

When a task exhausts its three retry attempts, the orchestrator executes a structured escalation sequence:

1. **Emits a failure report** containing screenshots, QA feedback, and a "blocked" marker
2. **Continues processing** remaining tasks to surface additional issues in downstream phases
3. **Triggers final integration check** that flags blocked tasks for manual review

This escalation logic appears in the **Error Handling & Recovery** section (lines 51-60) and the **Failure Management** table (lines 56-60) of [`agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/agents-orchestrator.md).

## Code-Level Implementation

The following Bash-style script illustrates the orchestrator's internal logic. In production, these commands translate to prompts sent to the underlying agent platform:

```bash

# ----- Dev‑QA Loop (simplified) -----

TASKS=$(grep -n '^### \[ \]' project-tasks/*-tasklist.md | cut -d: -f1)   # line numbers of unchecked tasks

for line in $TASKS; do
  retry=0
  while (( retry < 3 )); do
    # 1️⃣ Spawn developer for the current task

    dev_msg="Please spawn a developer agent to implement task at line $line."
    spawn_agent "$dev_msg"

    # 2️⃣ Run EvidenceQA on the same task

    qa_msg="Please spawn EvidenceQA to test task at line $line and return PASS/FAIL."
    qa_result=$(spawn_agent "$qa_msg")

    if [[ "$qa_result" == "PASS" ]]; then
      # Mark task as done

      sed -i "${line}s/\[ \]/[x]/" project-tasks/*-tasklist.md
      break   # move to next task

    else
      ((retry++))
      # Feed feedback back to developer

      feedback_msg="QA feedback: $qa_result – retry $retry of 3."
      spawn_agent "$feedback_msg"
    fi
  done

  # ----- Escalation if max retries reached -----

  if (( retry == 3 )); then
    echo "Task $line failed after 3 attempts – generating escalation report."
    generate_escalation_report "$line"
    # Keep task unchecked so final integration flags it

  fi
done

```

The `spawn_agent` and `generate_escalation_report` functions represent internal helpers that translate textual prompts into actual agent spawns. This loop mirrors the orchestrator's **retry-increment → PASS check → reset/escalation** flow exactly as specified in the repository.

## Key Files in the Repository

| File | Role in the Dev‑QA Loop |
|------|-------------------------|
| [`specialized/agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md) | Full orchestrator specification defining phases, retry limits, and decision tables (lines 77‑94, 136‑158). |
| [`strategy/QUICKSTART.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/QUICKSTART.md) | High‑level overview of the Dev‑QA loop and retry caps (line 147). |
| [`strategy/nexus-strategy.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md) | Policy table defining "task exceeds 3 retry attempts" and escalation routing (line 670). |
| `project‑tasks/*‑tasklist.md` | Concrete markdown task lists where `[ ]`/`[x]` statuses and retry counters persist at runtime. |
| [`testing/evidenceqa.md`](https://github.com/msitarzewski/agency-agents/blob/main/testing/evidenceqa.md) | Specification for the EvidenceQA agent that supplies PASS/FAIL decisions and visual evidence. |

## Summary

- The **Agents Orchestrator** drives a deterministic **Dev-QA continuous loop** that sequences every task through developer and EvidenceQA agents.
- **Retry logic** enforces a hard limit of **three attempts** per task; the `retryCount` increments on failure and resets only on PASS.
- **State persistence** uses markdown task lists (`project-tasks/*-tasklist.md`) to track `currentTask`, `retryCount`, and `taskStatus` across interruptions.
- **Escalation** triggers after three failures, generating a detailed failure report while allowing the pipeline to continue processing other tasks.
- The loop specification resides in [`specialized/agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md) (lines 77-94), with retry policies defined at lines 136-158.

## Frequently Asked Questions

### How does the Agents Orchestrator track retry attempts across the Dev-QA loop?

The orchestrator maintains a `retryCount` variable for each active task, incrementing it each time the EvidenceQA agent returns a FAIL verdict. This counter persists in the markdown task list files (`project-tasks/*-tasklist.md`) alongside the `currentTask` identifier and `taskStatus` checkbox. The counter resets to zero only when a task achieves a PASS status, ensuring each new task begins with a fresh budget of three attempts.

### What happens when a task fails QA validation three times?

After the third failed attempt, the orchestrator triggers a structured escalation sequence. It generates a detailed failure report containing screenshots, QA feedback, and a "blocked" marker for the task. The task remains unchecked in the tasklist to flag it for manual review during the final integration check. Meanwhile, the orchestrator continues processing subsequent tasks to surface additional issues, ensuring the pipeline does not halt completely due to a single blocked item.

### Which agent performs the QA validation in the continuous loop?

The **EvidenceQA** agent performs the validation step in the Dev-QA continuous loop. After a developer agent marks a task as complete, the orchestrator spawns an EvidenceQA agent to run task-specific tests, capture screenshots, and return a binary PASS/FAIL verdict with explicit feedback. This agent is defined in the testing specifications and serves as the quality gate that determines whether the task advances or triggers a retry cycle.

### Where is the retry logic defined in the repository?

The retry logic is primarily defined in [`specialized/agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md). Lines 42 and 157 specify the "Maximum 3 attempts per task before escalation" policy. The detailed state-machine logic appears in the Task-by-Task Quality Loop table at lines 136-140, which defines the increment, reset, and escalation steps. Additional policy context appears in [`strategy/nexus-strategy.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md) at line 670, which defines the escalation routing for tasks exceeding three retry attempts.