Adding an architectural context layer

[juanpabloaj]

Writing this up as a discussion — conceptual proposal, not a finished design, curious whether it resonates.

---

The core idea

Symphony today manages work. This proposal is about giving that work a shared context: a living model of the system being built, maintained by agents, supervised by humans.

Concretely: imagine a Figma/Miro-style canvas representing the architecture of a software system — components, dependencies, contracts, implementation status. The key difference from any existing diagramming tool is who writes it and when:

• Agents are the primary authors. The canvas is not documentation that someone creates after the fact. It is written by the same agents doing the work, as part of doing the work.
• The canvas is input, not just output. Before an agent plans its implementation, it queries the canvas to understand what already exists. Before it writes code, it publishes what it intends to build. The canvas shapes decisions, it doesn't just record them.
• Humans supervise, correct, and refine. They don't create the canvas — they review it, fix what agents got wrong, and validate that what was promised matches what was built.

The mental model is a multilayer CAD for software development. In mechanical engineering, a CAD file is a living specification with separate layers for different concerns — geometry, tolerances, manufacturing notes — that different stakeholders read depending on their role. Each layer adds information without obscuring the others. The whole file is version-controlled and linked to specific production runs. That's the model: not a diagram, but a structured, authoritative, continuously updated representation of the system that everyone — agents and humans — works from.

---

The gap Symphony doesn't yet address

Symphony's existing workflow is excellent at the ticket level: an agent receives a work item, implements it in isolation, and delivers proof of work. What it doesn't provide is an answer to the question every agent implicitly needs before starting: what does the rest of the system look like, and how does my work fit into it?

Without that shared context, three problems compound as teams and codebases grow:

Structural blindness. An agent implementing a payment service doesn't know whether a payment abstraction already exists in a neighboring service, or whether another team's agent is already building against an assumed interface. Each agent reasons about its local slice without a system-level view. The result is duplication, misalignment, and integration surprises at PR review time.

Contract drift. Agents define interfaces implicitly by writing code. Other agents discover those interfaces by reading the code — or worse, by failing against them. There is no layer where a backend agent can declare "I will expose this interface" before implementing, and where a frontend agent can begin building against that declaration in parallel. Today that negotiation happens in Slack, in PR comments, or not at all.

Lost institutional memory. When work is merged and issues close, the architectural intent behind those decisions disappears. Future agents — and engineers — have no way to query "what was the system shape when subscriptions shipped?" without reconstructing it from Git blame and closed tickets. Onboarding a new agent to an existing codebase has no better starting point than onboarding a new human: read the code and hope the comments are accurate.

The canvas addresses all three directly.

---

The canvas

The canvas is a persistent architecture model that lives alongside the Symphony workflow. It is organized into five layers, each representing a different dimension of the system. Layers can be read independently or together, depending on what a given stakeholder needs.

Layer 1 — Structural (the skeleton)
Components, their types, dependencies, and hierarchy. What most architecture diagrams show — but here written continuously by agents, not by humans once. Every time an agent creates or modifies a component, the structural layer updates.

Layer 2 — Semantic (the purpose)
Each component carries a business purpose extracted by the agent from the specification it received. Not "PaymentService depends on StripeClient" but "PaymentService enables monthly recurring billing for subscriptions." This layer is what makes the canvas readable by product managers and non-technical stakeholders. It connects technical structure to business capability.

Layer 3 — Contract (the interfaces)
Before an agent implements, it publishes the interfaces it commits to expose: endpoints, events, data types. Other agents can begin working against these contracts immediately, in parallel, without waiting for implementation to complete. This layer distinguishes between planned contracts and implemented ones, making gaps visible across teams before they become integration failures.

Layer 4 — Status (the implementation state)
Each component has a lifecycle: planned → in-progress → implemented → merged. This layer is where Symphony's existing workflow connects most directly: when an agent completes a run, it reports which scenarios are done and which are pending. The canvas makes that status visible to everyone — not as a ticket state, but as a capability state of the system.

Layer 5 — History (the audit trail)
Immutable snapshots linked to Git commits. Every state the canvas has been in is preserved and queryable by date, commit, or feature. Three months after a feature ships, anyone — or any agent — can query "what did the architecture look like when this was built?" and get a precise answer linked to the exact code.

---

How the human role changes

Symphony's insight is that humans should manage work, not supervise agents. The canvas extends that principle to architecture.

Today, a tech lead or architect spends significant time on activities that are fundamentally about maintaining shared understanding: writing architecture documents that go stale, running alignment meetings, reviewing PRs to catch structural misalignments that could have been caught earlier. The canvas shifts most of that work to agents, leaving humans with three specific interventions:

Layout refinement. The canvas calculates spatial positioning automatically. Humans adjust when the automatic layout doesn't reflect their mental model of the system — grouping related components, clarifying boundaries. These manual adjustments persist and take precedence over future automatic calculations.

Gap validation. When an agent marks scenarios as pending, a human decides what that means: next sprint, future version, out of scope, or reassigned to a different component. The decision is recorded with a timestamp and becomes part of the canvas history.

Semantic correction. If an agent extracted the wrong business purpose from a spec, a human corrects it. Agents write the first draft of every component's purpose; humans are the editors, not the authors.

The net result: fewer alignment meetings, because the canvas is the alignment. It is always current, always linked to code, and readable by engineers and product managers without a translation layer.

---

How it fits into the Symphony workflow

The canvas integrates as a side-channel at each phase of the existing workflow, not as a replacement for any part of it.

Phase 0: Repository initialization

When Symphony sets up a workspace, the agent scans the codebase and pushes an initial structural snapshot to the canvas. This baseline is what makes every subsequent query meaningful.

• Agent identifies components, dependencies, and hierarchy from the existing code
• Sends the structural model to the canvas via MCP
• Canvas renders the initial diagram and links the snapshot to the current HEAD commit
• All future agents now have a starting point to query before planning

Phase 1: Before writing code

This is the key intervention point. Before planning its implementation, an agent queries the canvas for context. Before writing any code, it publishes what it intends to build. Both steps happen before implementation begins.

• Agent queries canvas: "what components exist in this domain?"
• Canvas returns existing components, their purposes, and available contracts
• Agent reasons about how its work fits into the existing system — avoiding duplication, respecting existing patterns
• Agent publishes its planned components and interface contracts with status planned
• Other agents working on dependent parts of the system can begin immediately against these declared contracts
• A human can review the architectural proposal and catch structural problems before any code exists

Contract negotiation moves from Slack and PR comments to a structured layer that agents write and read automatically, before implementation, every time.

Phase 2: After completing the run

When Symphony validates the proof of work, the agent also reports to the canvas what was actually built versus what was planned.

• Agent compares implemented code to its published contracts
• Reports which scenarios are complete and which remain pending
• Canvas updates component status from planned to implemented
• Gaps between what was promised and what was delivered are visible immediately, not discovered at integration time

Phase 3: Merge and consolidation

When Symphony lands a PR, the canvas seals the relevant components to the merge commit.

• Canvas links component state to the specific commit hash
• Immutable snapshot generated for the merged state
• Snapshot indexed and queryable — this is the entry point for the historical audit trail

---

Integration with Symphony's existing architecture

MCP as the communication protocol

Symphony already uses Codex in app-server mode with custom MCP tools for tracker operations. The canvas follows the same pattern: a set of MCP tools that agents call during their workflow, requiring no changes to Symphony's core orchestration logic.

canvas_query(domain)
  → Returns components related to a domain with their purposes and contracts

canvas_publish_plan(component_definition)
  → Publishes a planned component with interface contracts before implementation

canvas_report_implementation(component_id, scenarios, evidence)
  → Updates a component's status with proof of implementation after a run

canvas_consolidate(component_id, commit_hash, branch)
  → Seals a component to a specific merge commit

WORKFLOW.md integration

The canvas interactions embed naturally in the WORKFLOW.md prompt template:

Before planning your implementation, query the architecture canvas for
context related to your issue domain. Publish your planned components and
interface contracts before writing code. After completing your implementation,
report to the canvas which scenarios are now available and which are pending.

Canvas as a separate service

The canvas is a lightweight service — accessible via web and API — that Symphony agents write to and humans read from. It doesn't need to be bundled into the Symphony binary. The Elixir reference implementation could expose the canvas MCP tools via its existing app-server mechanism.

---

Why this is different from existing tools

Structurizr, Backstage, and similar tools have a well-known failure mode: they are accurate when created and obsolete within weeks because updating them is a manual step that gets skipped under deadline pressure. Auto-generated dependency graphs solve the staleness problem but are semantically empty — they show what calls what, not what anything is for.

The canvas is different on three dimensions simultaneously, which no existing tool combines:

Agent-native. The canvas is written by the same agents that write the code, as part of writing the code. There is no separate documentation step to skip.

Business-semantic. The canvas carries business purpose alongside technical structure. "This component enables monthly recurring billing" is a different kind of information than "this service has three dependencies." It makes the canvas useful to a product manager reviewing scope, not just an engineer reviewing architecture.

Commit-traceable. Every state of the canvas is linked to a specific Git commit. It is a time series, not a snapshot — queryable as "what did the system look like when this bug was introduced?" with a precise, verifiable answer.

---

Closing

Symphony's core bet is that the right abstraction for agentic development is managing work, not managing agents. This proposal extends that bet one level up: the right abstraction for architectural knowledge is a living canvas that agents maintain, not documentation that humans write and forget.

The CAD metaphor is precise, not decorative. A CAD file is authoritative, layered, version-controlled, and continuously updated by the people doing the actual work. It is the source of truth for everyone involved — engineers, reviewers, manufacturing — each reading the layer relevant to their role. That is exactly what's missing in agentic software development today.

Happy to hear whether this direction makes sense, whether similar thinking is already happening internally, or whether there are reasons this approach wouldn't work in practice.

[simonbrowndotje]

Structurizr, Backstage, and similar tools have a well-known failure mode: they are accurate when created and obsolete within weeks because updating them is a manual step that gets skipped under deadline pressure.

Author of Structurizr here ... this statement is true if the Structurizr DSL definition is written by hand. There's nothing preventing teams using static analysis techniques, observability data, or AI to generate the DSL so that it remains in sync with reality.