Architecture

Contract Graph requires software to have explicit, recursively decomposed responsibilities, with a truthful contract graph that lets an agent find where a change belongs. That is the framework’s central opinion. The contract graph is the map used before reading implementation. Its rules protect the usefulness of that map.

This page describes the current shipped defaults for 0.6.0. It does not reconstruct every intention behind older versions of architecture.yaml. After cg init, the source of truth is the installed architecture catalog at .agents/cg/principles/architecture.yaml.

It is written for framework adopters and reviewers deciding what architecture a repository must preserve.

What is mandatory?

There are two kinds of architectural obligation, plus optional engineering advice:

Architecture, engineering, and product share a schema, not authority. Keeping the protocol in architecture.yaml also prevents a workflow edit from accidentally removing the structural instructions. The delivery sequence lives separately in the skills and repository workflow.

Organize around responsibilities

A boundary answers four questions:

1. What one responsibility does it own?
2. How does its parent use it?
3. Where can callers enter, and what may they rely on?
4. Which children or dependencies explain the next level down?

The repository decomposes into product or domain capabilities such as billing, inventory, or identity. The shipped hierarchy does not use horizontal top-level modules such as controllers, services, and repositories. Those implementation roles can exist inside a capability.

Each governed boundary has one canonical file:

<unit>/.agents/cg/contract.yaml

The root contract is .agents/cg/contract.yaml. A child lives beneath its parent unit and both contracts declare the relationship.

Allowed nesting

Depth is not fixed. A module can be a leaf; another module can need several levels. A component can decompose further. A library is a leaf in the shipped hierarchy.

A new node needs a distinct responsibility and a coherent surface. Conversely, do not hide a distinct responsibility inside an existing node simply because its files are already open. When several packages form one boundary, name them and explain why they are inseparable.

Every change has a placement decision

Apply this reasoning recursively, starting from the contract that owns the relevant capability. Finding a module is the start of routing; it is not proof that the module is the smallest unit.

Use add-child when the new responsibility is part of how this parent fulfills its own. Use elsewhere when it belongs to a different owner. Existing code may need restructuring before those declarations can truthfully describe it.

Changed ownership, allowed or forbidden behavior, surface, invariants, verification, relationships, or routes requires an affected contract amendment. The implementation and its map change together.

Declare how a boundary is used

Callers enter through the surface named by the contract. That surface explains the observable promise; implementation details remain behind it unless deliberately part of the promise.

“Declared surface” does not necessarily mean an HTTP endpoint, a public class, or a customer UI. A function, command, event, schema, service, or asynchronous interface may express the promise. There is no requirement for one or two classes, synchronous completion, or a service wrapper.

For example, callers of billing can depend on a declared createInvoice operation. They should not discover and mutate its private invoice cache. A storage library may intentionally expose storage concepts when those concepts are its actual promise; the framework does not forbid all technology-specific interfaces.

If access bypasses the surface, correct the caller, deliberately amend the promise, or change placement. A bypass does not automatically mean “create another node.”

The parent owns the cross-child orchestration needed for its responsibility. Each child owns its internal flow. Children do not coordinate one another’s internals.

Optional resources and consumer-specific behavior

The retained protocol uses a parent-owned port for an optional external resource or consumer-specific implementation. A port is the promise the owning capability needs from that implementation. An adapter supplies the vendor or consumer-specific behavior behind that promise.

Separate adapters are an E recommendation. Contract decomposition still follows responsibility. Do not put a consumer-specific branch into a consumer-independent core when its existing promise already supports the behavior. If the promise is insufficient, amend it with an owned, consumer-independent concept and update affected consumers.

What A01–A16 actually enforce

Run cg verify to check the authored graph and installed structure. These are the current A checks:

A15 rejects the reserved controller, service, repository, and model labels, including their listed plurals. A16 rejects common, shared, utils, helpers, util, and helper. The checks examine the node ID, name, and unit basename. They do not ban using those words in ordinary prose or as every internal filename.

Other installed checks also validate identity uniqueness, route targets, product references, and prohibited references to transient plans. A passing verification result is evidence of declared graph consistency, not a certificate of complete implementation correspondence.

Which architectural choices remain yours?

These are recommendations or product decisions, not universal A requirements:

• Classes versus functions, service facades, and a fixed number of entry types.
• A separate contract for every adapter or vendor.
• Constructor injection for every object or construction only at application bootstrap.
• One deployable, one physical database, or one physical writer process.
• Exactly two consumers before creating a reusable library.
• An integer version on every persisted record as the only compatibility strategy.
• A universal ban on configurable authorization policy or customer-initiated account removal.
• Confirmation before every external side effect regardless of existing authorization.
• One UI, tenancy model, billing model, or solo-maintainer operating model.

E offers advice about these decisions. Shipped phase defaults require reading E as context; reading a recommendation does not adopt it as a binding. Retained repository phase policy can choose different loading. P is the place for deliberately adopted product-specific bindings.

What changes after installation?

cg init installs opinionated defaults, then preserves the repository’s catalogs, contracts, workflow, and phase policy. An upgrade does not silently replace the team’s architectural choices. This page describes the shipped policy; an existing installation may retain an older or amended one.

Repository ownership does not make installed detector behavior editable through prose. Amendments must remain within registered semantics. Changing YAML or removing an entry does not create a new detector or prove that an existing verifier check has been disabled.

A generic practice becomes A only through a verifier-owning change that supplies all four:

1. A concrete effect on graph routing, ownership, boundaries, or structural truth.
2. One deterministic pass/fail measure.
3. A registered blocking detector.
4. A negative fixture proving that a violation fails.

That change assigns a permanent A ID and removes the overlapping E practice. Until then, an important recommendation remains advice, an explicit repository requirement, or a proposed promotion.

A short review checklist

Before accepting a structural change, ask:

• Can a new session route from the root to the responsible unit without searching unrelated code?
• Does each affected node explain one coherent responsibility and how its parent uses it?
• Are entry points and cross-boundary dependencies explicit?
• Does composition reflect responsibility rather than directory count or technology count?
• Have changed promises and relationships been amended alongside the implementation?
• Which guarantees were verified mechanically, and which still depend on review or missing detectors?
• Are any E preferences being treated as requirements without deliberate adoption?

For field details, read Contracts. For stage behavior, read Lifecycle.