# How Agents Maintain State and Context Across Pipeline Phases in NEXUS

> Discover how agents maintain state and context across pipeline phases in NEXUS. Learn about centralized orchestrators, JSON state files, and standardized handoff documents for seamless inter-agent transitions.

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

---

**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`](https://github.com/msitarzewski/agency-agents/blob/main/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`](https://github.com/msitarzewski/agency-agents/blob/main/state_manager.py) utility demonstrates how agents interact with the shared state file:

```python

# 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`](https://github.com/msitarzewski/agency-agents/blob/main/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:

```markdown

# 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:

```bash

# 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`](https://github.com/msitarzewski/agency-agents/blob/main/pipeline_state.json), which the orchestrator evaluates before the next handoff.

According to [`testing/testing-workflow-optimizer.md`](https://github.com/msitarzewski/agency-agents/blob/main/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`](https://github.com/msitarzewski/agency-agents/blob/main/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`](https://github.com/msitarzewski/agency-agents/blob/main/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`](https://github.com/msitarzewski/agency-agents/blob/main/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`](https://github.com/msitarzewski/agency-agents/blob/main/specialized/agents-orchestrator.md) and implemented in [`state_manager.py`](https://github.com/msitarzewski/agency-agents/blob/main/state_manager.py). The five valid phases—Discovery, Foundation, Build, Launch, and Operate—are also documented in [`strategy/nexus-strategy.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/nexus-strategy.md) and enforced through phase-specific playbooks like [`strategy/playbooks/phase-3-build.md`](https://github.com/msitarzewski/agency-agents/blob/main/strategy/playbooks/phase-3-build.md).