Symphony Context Engineering for Agents

Symphony context engineering is the practice of giving each agent role the smallest verifiable repository packet it needs before a complex change. It is not an OpenAI Symphony feature: Symphony is an orchestration specification and engineering preview, so teams must design, version, and govern their own context layer.

Map Context to Each Agent Role

The Symphony SPEC describes components such as an issue adapter, per-issue workspace, agent runner, workflow policy, and structured observability. It does not prescribe a general context-engineering system. Treat the following role map as an operating pattern around that specification, not a promise of native agent memory.

The practical test is simple: can an agent explain each decision-driving fact with a source and a revision? If not, the team has a prompt artifact, not reliable repository context. This distinction protects the workflow from confident summaries that happen to be obsolete.

Planner context

Give the planner the issue, acceptance criteria, architecture boundary, affected ownership area, known dependencies, release constraints, and the current base revision. The planner's job is to identify a bounded change surface and questions that need human answers. It should not receive broad credentials merely because it is reading more context.

Implementer context

Give an implementer the approved plan, owned files, interface contracts, relevant tests and fixtures, and exact environment commands. Keep source links with every summary. The goal is not to paste an entire repository into a prompt; it is to make the next edit explainable.

Test agent context

Give a test role the expected behavior, negative cases, test commands, environment limits, and the diff under review. A test run cannot establish correctness when its fixtures, integrations, or skipped platform jobs are unknown. Record the command, revision, result, and the parts that were not executed.

Reviewer context

Give a reviewer the ticket, plan, diff, evidence packet, CI output, and unresolved assumptions. Reviewers need a clear distinction between source-backed repository facts and an agent's temporary interpretation. That distinction is more valuable than a long transcript.

For the wider lifecycle in which these roles operate, see Symphony Large Codebase Agents.

Separate Shared Repository Facts From Private Task State

Shared facts include module ownership, interface contracts, dependency edges, test locations, and validated design decisions. They should have a source, revision, owner, and freshness rule. Private task state includes an agent's scratch reasoning, half-finished plans, runtime logs with sensitive values, and credentials. It should stay in the task boundary and expire or be redacted according to policy.

Give the two layers different update paths. A maintainer may update a module map after a merge; an agent may update its own task receipt; neither action should silently modify the other layer. This prevents a private experimentation log from becoming a de facto architecture record just because another run can retrieve it.

This split avoids a common failure: treating every message produced by an agent as durable repository knowledge. It also makes a later handoff auditable. An optional relationship-aware store can support the shared-fact layer, but Symphony Knowledge Graph is a design companion, not a Symphony integration claim.

Build the Task Intake Package

An intake package should fit on one screen before it expands into source links. Start with: the task outcome, explicit non-goals, base revision, affected components, dependency and test evidence, acceptance criteria, environment constraints, and the human escalation path.

Scope, constraints, dependencies, and acceptance criteria

Use a simple rule: every included fact must change a decision the agent can make. A component map is useful when it points to a current source. A generic architecture essay is not. Dependencies should name both direction and evidence: “service A calls API B through client C at this revision,” not “these services are related.” Acceptance criteria should define observable behavior, including no-change constraints.

Before dispatch, ask a maintainer to read the packet as if they had never seen the ticket. They should be able to identify the expected change, the boundaries, the mandatory evidence, and the escalation path in a few minutes. If not, the packet is not ready for autonomous implementation.

Design a Reliable Agent Handoff Package

At handoff, create a receipt rather than a narrative. Include the input revision; issue state; files changed and files inspected; commands and results; links to CI or reviews; source-backed facts used; decisions deferred; and redactions made. A recipient should be able to decide whether the packet is sufficient without rerunning the entire conversation.

Use stable identifiers for the ticket, base commit, and resulting pull request. If a result is rebased, record both the original and replacement revisions. If a command only ran locally, say so. A reliable handoff does not maximize detail; it makes verification cheap for the person who must take responsibility next.

The OpenAI materials describe workflow policy and observability, and the reference implementation uses provider adapters and a Codex App Server run. Exact integration behavior, tool permissions, and recovery policy remain implementation-specific. Link this receipt to the neutral contract in Share Repo Context Across Coding Agents rather than coupling it to one agent's private prompt format.

Feed Pull Request Outcomes Back Into Future Tasks

Only merge-verified outcomes should update shared guidance. If a reviewer finds an omitted dependency, add a source-backed correction with the revision and owner. If a change is reverted, mark the related fact as invalidated rather than leaving a plausible-looking success note. This converts review from a final gate into a measured feedback loop without preserving unverified agent opinions as truth.

Use an explicit change record for shared context: what changed, which source changed, which open tasks may be affected, the effective revision, and the person who approved it. Agents can subscribe to a narrow change feed for their owned modules instead of rereading a repository-wide instruction file after every merge.

Context cost should be measured as well as model cost. Track how much evidence was supplied, how much was actually cited in the resulting plan or diff, how often agents requested information already present, and how often reviewers discovered an omitted dependency. These measures reveal waste without treating shorter prompts as automatically better.

Stop Context Drift During Long-Running Work

Context drifts when the base branch moves, an interface changes, a task is split, or CI reveals a new condition. Attach expiry triggers: a changed base revision, closed dependency issue, changed generated artifact, or failed assumption. On a trigger, refresh only the affected packet and record why. Do not let context caching turn an older summary into silent authority.

Teams should review drift after every blocked or reverted task. Those cases expose the facts that were missing at intake and the facts that should not have been shared. Improve the packet schema only after that review, rather than adding a larger generic prompt to every agent.

Guardrails for Autonomous Repository Access

The specification treats trust boundaries as implementation-defined, and the Elixir reference implementation documents prototype-specific configuration and safety defaults. Therefore teams should set their own minimal scopes for repository write access, tracker updates, CI access, network use, and secret references. Give agents access to references rather than raw secrets where possible; require a human approval boundary before privileged or irreversible actions.

Make guardrails testable: deny an unnecessary credential in the pilot, verify that the task fails safely, and record who was notified. A policy that exists only in a design document will not reliably constrain a long-running agent workflow.

FAQ

Who should approve changes to shared context?

Assign a human steward for each context class: code ownership for module facts, security for access policy, and engineering leadership for cross-team design records. The owner should approve both additions and invalidations, because stale knowledge is a change too.

Which agent observations are safe to persist?

Persist observations only after they are tied to source evidence and reviewed outcome: a current dependency edge, a confirmed test requirement, or a merged decision record. Keep raw reasoning and unredacted logs task-local.

What should happen after a partially failed run?

Freeze the receipt, capture the revision and observable state, redact secrets, and classify the task as blocked, retryable, or human-owned. Reuse only source-backed facts that remain current after reconciliation.

How should secrets be excluded from agent handoffs?

Use references, allowlisted environment interfaces, and redacted logs. Do not include tokens, copied credentials, private customer data, or unfiltered command history in a reusable context packet.

Can one context layer support multiple repositories?

Yes, if each fact retains repository identity, revision, scope, owner, and access policy. Cross-repository context should be retrieved deliberately, not merged into a single undifferentiated memory.