OpenSpec Across Stacks

Give an agent the whole monorepo as context and it will confidently call the wrong half of it. It finds an API endpoint with the right name, the right path, the right method signature, and wires it into the new filter component without hesitation. Code review catches what the agent did not: it called the back-end service API, not the Backend for Frontend (BFF) API the front-end was supposed to use. The back-end API skipped the authorization checks the BFF enforced.

The spec never said which API to call. With every tier's specs in reach and no signal about which tier it was working in, the agent resolved the ambiguity the wrong way, and felt certain doing it.

The problem is upstream. A single openspec/ directory shared across three tiers of a system gives every agent access to every tier's specs, and no signal about which tier it is working in.

One openspec/ per stack

The fix is structural. Each stack (front-end, BFF, back-end) gets its own openspec/ directory at the root of its repository or sub-directory. The front-end agent never sees the back-end specs. It knows its contracts, its acceptance criteria, its pending changes. The back-end specs are not its context.

front-end/
  openspec/
    changes/
      add-filter-component/
        proposal.md
        design.md
        specs/
          filter-component/
            spec.md
        tasks.md

bff/
  openspec/
    changes/
      add-filter-endpoint/
        proposal.md
        design.md
        specs/
          filter-endpoint/
            spec.md
        tasks.md

back-end/
  openspec/
    changes/  # (unchanged by this feature)

A unified openspec/ across stacks gives the agent three codebases of context it does not need and three sets of canonical specs it should not all trust. Every ambiguity resolution gets harder. Keeping stacks separate makes each agent's context legible and bounded.

This is book synthesis. There is no widely-adopted standard for multi-tier spec organization. The pattern here follows from the general principle that context should be scoped to the work being done.

Sources: Fission AI, OpenSpec (ongoing), the change-folder model this per-stack layout builds on. The multi-tier split itself is this book's synthesis.

Front-end context belongs outside the stack spec

The spec pattern for front-end work is identical to the pattern for back-end work. What changes is the permanent context the agent reads before implementation.

A back-end agent reads docs/architecture/, the API contract, and the test strategy. A front-end agent reads the design system document: component conventions, accessibility requirements, and state management patterns. Figma or another design source supplies visual context. The design system document supplies durable convention.

The spec should still cover behavior: states, validation, edge cases, loading, error, and empty states. User flows and navigation logic belong in docs/architecture/, referenced by the spec. The design system doc answers how the component should look when it renders correctly.

Sources: Framelink, Figma-Context-MCP (ongoing), Figma files as extractable design context for coding agents. The split between front-end behavior specs and docs/design/ convention briefs is this book's workflow mapping.

The integration contract belongs in an ADR

A change in the front-end spec that depends on a new BFF endpoint needs a source of truth shared by both stacks. That source of truth is not a spec, because specs are scoped to a single change folder and a single stack. The shared source is an Architectural Decision Record (ADR).

The ADR in docs/decisions/ records the API contract: endpoint path, request shape, response shape, error handling, authentication boundary. Both stacks reference the same ADR in their respective change folders. The front-end spec says "see ADR-0042 for the BFF contract", while the BFF spec says "implements the contract in ADR-0042". When the contract changes, one ADR update is the source of truth. The specs do not need to repeat the contract details.

The ADR is permanent, while the change folders are temporary and archived after implementation. The contract outlives both.

Sources: Michael Nygard, "Documenting Architecture Decisions", Cognitect blog, Nov 15, 2011, ADRs as the cross-stack contract of record that outlives the change folders.

When a change spans tiers

Most features touch multiple tiers. A new filter endpoint requires front-end work, BFF work, and possibly back-end work. The temptation is to create one change folder that covers all three.

That temptation compounds every problem described above. The front-end agent does not need the back-end implementation details, and the BFF reviewer does not need to read the front-end acceptance criteria. The archive of the change becomes three times as large and three times as hard to search.

When a change spans tiers, each tier gets its own change folder referencing the same cross-cutting ADR. Coordination happens at the ADR level, while implementation stays separate. Each PR is one tier, one spec, one reviewer context.

The rare exception: infrastructure changes that have no clean tier boundary. A change to how authentication tokens are propagated through the stack affects all three tiers simultaneously. These are genuinely cross-cutting and warrant a cross-cutting spec, but they are rare enough that the exception should be labeled as such, not treated as the default.

This is book synthesis, not a field standard

Multi-tier spec organization is not a field standard. This pattern is the book's synthesis, derived from the OpenSpec change-folder model applied to multi-repo realities. Teams should expect to adapt it. A monorepo with shared libraries between front-end and back-end often needs a different boundary than the one described here. The principle is to scope context to the work being done. The directory layout is one way to enforce that principle.

Multi-tier layout settles where the specs live. It says nothing about where they fit. The team already has Jira, PR review, a changelog, and an architecture board, and now a directory of change folders that has to coexist with all of it. Knowing which existing slot each artifact belongs in is the difference between OpenSpec fitting the workflow and fighting it.