The Mechanism for Spawning and Coordinating Multiple Agents in Agency-Agents

The Agency-Agents orchestrator spawns and coordinates multiple agents through declarative text commands interpreted by the Instagit platform, using a file-based state machine with synchronous phase gates and automatic retry logic.

The msitarzewski/agency-agents repository implements a sophisticated multi-agent system where a central Agents Orchestrator manages complex development workflows. Understanding the mechanism for spawning and coordinating multiple agents is essential for extending the pipeline or debugging agent interactions.

Understanding the Agents Orchestrator Architecture

The Agents Orchestrator serves as the central pipeline manager within the Agency-Agents framework. Unlike traditional orchestrators that execute code directly, this system operates by issuing declarative "spawn" instructions that the underlying Instagit platform interprets to launch specialist agents.

The orchestrator maintains workflow state through a deterministic, file-based state machine. It does not possess execution capabilities itself; instead, it relies on the platform to instantiate agents based on human-readable command strings embedded in markdown files.

The Core Mechanism for Spawning and Coordinating Multiple Agents

The spawning and coordination mechanism relies on six interconnected components that ensure reliable multi-agent execution.

Declarative Spawn Prompts

Agent instantiation begins with plain-text commands embedded in the orchestrator script. The orchestrator writes human-readable instructions such as:

"Please spawn a project-manager-senior agent to read the specification file at
project-specs/[project]-setup.md and create a comprehensive task list.
Save it to project-tasks/[project]-tasklist.md. Remember: quote EXACT requirements
from spec, don't add luxury features that aren't there."

Source: specialized/agents-orchestrator.md, lines 58-60

These declarative prompts allow the Instagit platform to interpret the intent and launch the appropriate specialist agent with the correct file context.

Phase-Driven Orchestration

The workflow divides into explicit phases: Project Analysis, Technical Architecture, Development-QA Loop, and Final Integration. Each phase operates as a synchronous gate where the orchestrator verifies completion before proceeding.

In the Development-QA Loop phase, the orchestrator dynamically selects appropriate specialists:

### Phase 3: Development-QA Continuous Loop

```bash

# Read task list to understand scope

TASK_COUNT=$(grep -c "^### \[ \]" project-tasks/*-tasklist.md)

echo "Pipeline: $TASK_COUNT tasks to implement and validate"

# Spawn a developer for the current task

"Please spawn appropriate developer agent (Frontend Developer, Backend Architect,
engineering-senior-developer, etc.) to implement TASK 1 ONLY from the task list
using ArchitectUX foundation. Mark task complete when implementation is finished."

# Spawn QA for the same task

"Please spawn an EvidenceQA agent to test TASK 1 implementation only.
Use screenshot tools for visual evidence. Provide PASS/FAIL decision with specific feedback."

*Source: [`specialized/agents-orchestrator.md`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md), lines 77-88*

This phase-driven approach ensures that **no phase proceeds without validated output** from the previous stage.

### Shared File-System Context

All agents operate within a **common project folder** structure that serves as the source of truth. The orchestrator directs agents to read from and write to specific directories:

- `project-specs/` – Initial requirements and setup documentation
- `project-tasks/` – Task lists and implementation tracking
- `project-docs/` – Technical documentation and architecture decisions
- `css/` – Styling and frontend assets

When spawning an agent, the orchestrator passes file paths as parameters, ensuring the new agent receives complete context without requiring direct communication with previous agents.

### Retry and Escalation Logic

The orchestrator implements robust failure handling through automatic retry mechanisms. If an agent fails to launch or complete its task, the orchestrator retries up to two additional times before escalating.

```python
def spawn_agent(command):
    for attempt in range(3):               # max 2 retries + 1 initial try

        result = run_spawn(command)
        if result.success:
            return result
        log(f"Spawn attempt {attempt+1} failed; retrying...")
    raise RuntimeError("Agent spawn failed after 3 attempts")

Concept derived from specialized/agents-orchestrator.md, line 152

This retry logic ensures transient failures do not halt the entire pipeline while preventing infinite loops through the escalation mechanism.

Quality Gates and Validation

Before advancing between phases, the orchestrator enforces quality gates that require explicit evidence of completion. The orchestrator checks for:

• Screenshots demonstrating visual implementation
• Pass/fail flags in validation files
• Completed task markers in markdown checklists
• Explicit confirmation statements in agent outputs

These gates ensure that every hand-off is synchronous and state-driven, preventing the pipeline from proceeding with incomplete or unverified work.

Key Files in the Agency-Agents Repository

Understanding the spawning mechanism requires familiarity with these critical files:

File	Purpose
specialized/agents-orchestrator.md	Central definition of spawn commands, phase structure, retry rules, and quality-gate enforcement.
README.md	Overview of the orchestrator's role among all agents and links to the orchestrator specification.
examples/workflow-startup-mvp.md	Concrete end-to-end example demonstrating multiple agent spawns in a real workflow.
strategy/QUICKSTART.md	Explanation of the NEXUS concept that relies on the orchestrator's spawning mechanism.

Summary

The mechanism for spawning and coordinating multiple agents in Agency-Agents relies on a declarative, file-based orchestration system:

• Declarative spawn prompts instruct the Instagit platform to launch specialist agents with specific file context.
• Phase-driven orchestration divides workflows into synchronous gates with verified hand-offs.
• Shared file-system context provides the source of truth between agents without direct communication.
• Retry and escalation logic handles transient failures through automatic retries and error escalation.
• Quality gates enforce validation before allowing phase transitions, ensuring reliable multi-agent coordination.

Frequently Asked Questions

How does the Agents Orchestrator actually launch an agent?

The orchestrator does not execute code directly. Instead, it writes declarative text commands such as "Please spawn a project-manager-senior agent..." into its script. The underlying Instagit platform interprets these human-readable instructions and instantiates the appropriate specialist agent with the specified file context.

What happens if an agent fails to spawn or complete its task?

The orchestrator implements automatic retry logic that attempts to spawn the agent up to three times total (initial attempt plus two retries). If all attempts fail, the orchestrator escalates the error while logging the failure details, preventing the pipeline from hanging on transient issues while maintaining error visibility.

How do agents communicate with each other without direct messaging?

Agents communicate through a shared file-system context. The orchestrator directs each spawned agent to read from specific directories (such as project-specs/ or project-tasks/) and write results to designated output files. Subsequent agents read these files as their input context, creating a deterministic, state-driven hand-off mechanism without requiring direct agent-to-agent communication.

What prevents the pipeline from proceeding with incomplete work?

Quality gates enforce synchronous validation at each phase boundary. The orchestrator checks for explicit evidence such as screenshots, pass/fail flags, and completed task markers before allowing the workflow to advance. This ensures that no phase proceeds without validated output, maintaining strict quality control throughout the multi-agent pipeline.

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