How Agents Maintain State and Context Across Pipeline Phases in NEXUS

Agents maintain state and context across pipeline phases by using a centralized orchestrator that persists phase, task, and quality-gate data to a shared JSON state file, while standardized handoff documents inject this state into every inter-agent transition.

The msitarzewski/agency-agents repository implements a robust state management architecture that ensures continuity across the NEXUS pipeline's five phases: Discovery, Foundation, Build, Launch, and Operate. Understanding how agents maintain state and context across pipeline phases reveals the mechanisms that prevent context loss during complex multi-agent workflows.

Centralized Orchestrator State Management

The Agents Orchestrator serves as the single source of truth for pipeline progression. According to specialized/agents-orchestrator.md, the orchestrator's personality file explicitly mandates: "Track progress: maintain state of current task, phase, and completion status" and "Context preservation: pass relevant information between agents"【/cache/repos/github.com/msitarzewski/agency-agents/main/specialized/agents-orchestrator.md#L45-L48】.

State Structure and Persistence

The orchestrator maintains a structured state object containing:

• Current phase (Discovery, Foundation, Build, Launch, or Operate)
• Active task identifier and description
• Retry counters for failed operations
• Quality-gate outcomes (PASS/FAIL verdicts)

This state persists to a JSON file that all agents access before execution.

State Manager Implementation

The following state_manager.py utility demonstrates how agents interact with the shared state file:

# state_manager.py – shared utility used by every agent

import json
from pathlib import Path

STATE_FILE = Path("pipeline_state.json")

def load_state() -> dict:
    if STATE_FILE.exists():
        return json.loads(STATE_FILE.read_text())
    # initial state for a fresh run

    return {
        "phase": "Discovery",
        "current_task": None,
        "task_attempts": {},
        "qa_results": {}
    }

def save_state(state: dict) -> None:
    STATE_FILE.write_text(json.dumps(state, indent=2))

def update_phase(state: dict, new_phase: str) -> None:
    state["phase"] = new_phase
    save_state(state)

def record_task_attempt(state: dict, task_id: str) -> None:
    state["task_attempts"][task_id] = state["task_attempts"].get(task_id, 0) + 1
    save_state(state)

def record_qa_result(state: dict, task_id: str, passed: bool) -> None:
    state["qa_results"][task_id] = {"passed": passed}
    save_state(state)

Every agent calls load_state() at initialization and save_state() after modifications, ensuring the single source of truth remains synchronized across the pipeline.

Standardized Handoff Documents for Context Preservation

While the state file provides persistence, handoff documents ensure context transfers correctly between specific agent pairs. The strategy/coordination/handoff-templates.md file defines the NEXUS Handoff Template, which includes a mandatory Context section listing the project, current state, and relevant files【/cache/repos/github.com/msitarzewski/agency-agents/main/strategy/coordination/handoff-templates.md#L24-L30】.

NEXUS Handoff Template Structure

Handoff documents embed the orchestrator state directly into the transfer payload:

# NEXUS Handoff Document

## Metadata

| Field | Value |
|-------|-------|
| **From** | AgentsOrchestrator (Orchestration) |
| **To**   | Frontend Developer (Engineering) |
| **Phase**| {{ load_state().phase }} — Development |
| **Task Reference** | task-42 |
| **Timestamp** | {{ now_iso() }} |

## Context

**Project**: {{ project_name }}
**Current State**: {{ load_state() }}
**Relevant Files**:
- project-specs/{{ project_name }}-setup.md — full product brief
- architecture/{{ project_name }}-ux.md — UI foundations

By templating {{ load_state() }} into the handoff, the receiving agent inherits the exact same dictionary the orchestrator holds, including phase, task attempts, and QA results.

Phase-Aware Prompts and Feedback Loops

The NEXUS pipeline progresses through five distinct phases: Discovery, Foundation, Build, Launch, and Operate. Each phase has dedicated prompts that begin with a "Current Phase" token injected from the orchestrator state.

Current Phase Tokens

When spawning agents, the orchestrator injects phase context directly into system prompts:

# agents-orchestrator prompt (excerpt)

Please spawn an agents-orchestrator to execute the complete development pipeline.
Current Phase: {{ load_state().phase }}
Project: {{ project_name }}

This ensures that agents spawned during Phase 3 – Development automatically know they are in the Build loop rather than Discovery, preventing phase-inappropriate actions.

Evidence-Based State Updates

QA agents such as evidence-QA and reality-checker return structured verdicts that update the orchestrator state. The record_qa_result() function writes PASS/FAIL outcomes to pipeline_state.json, which the orchestrator evaluates before the next handoff.

According to testing/testing-workflow-optimizer.md, specialized agents use self.current_state and self.future_state to reason about bottlenecks, demonstrating how state persistence enables sophisticated workflow analysis【/cache/repos/github.com/msitarzewski/agency-agents/main/testing/testing-workflow-optimizer.md】.

Summary

• Centralized orchestrator state in specialized/agents-orchestrator.md mandates tracking phase, task, and completion status through a shared JSON state file.
• Standardized handoff documents defined in strategy/coordination/handoff-templates.md embed the full state object via templating, ensuring context preservation between agents.
• Phase-aware prompts inject the current pipeline phase directly into agent instructions, preventing context confusion across Discovery, Foundation, Build, Launch, and Operate stages.
• Evidence-based feedback loops write QA verdicts back to the state file, creating a reliable single source of truth that travels with every agent invocation.

Frequently Asked Questions

How does the orchestrator handle state persistence?

The orchestrator persists state to a JSON file (typically pipeline_state.json) using atomic read-write operations. Every agent calls load_state() at initialization and save_state() after modifications, ensuring that phase, task attempts, and QA results remain synchronized across the entire pipeline.

What information is included in a NEXUS handoff document?

A NEXUS handoff document includes metadata (From/To agents, phase, task reference, timestamp), a Context section with the project name and full current state object, and a list of relevant files. The template uses Jinja-style templating ({{ load_state() }}) to inject live state data directly into the Markdown.

How do QA agents update the pipeline state?

QA agents such as evidence-QA and reality-checker return structured PASS/FAIL verdicts. The orchestrator calls record_qa_result() to write these outcomes to the state file under the qa_results key. The orchestrator then evaluates these results to decide whether to advance to the next phase, retry the current task, or escalate to human oversight.

Where is the pipeline phase defined in the codebase?

The pipeline phase is defined in the orchestrator's state object under the "phase" key, as specified in specialized/agents-orchestrator.md and implemented in state_manager.py. The five valid phases—Discovery, Foundation, Build, Launch, and Operate—are also documented in strategy/nexus-strategy.md and enforced through phase-specific playbooks like strategy/playbooks/phase-3-build.md.

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