Skip to content

The FCC Three-Layer Documentation Convention

This project organizes its top-level root-of-repo design documents into three reinforcing layers. Each layer answers a different "what kind of change is this?" question, and each is owned by a single file so cross-project consumers (PAOM, AOME, CONSTEL, Distiller, ice_ext, LYRA, and the constellation verticals) can find the right artifact without spelunking.

The convention was first adopted informally in our sibling repositories l2_mnemosyne and ice_ext during their Phase-2 and Phase-3 redesigns, respectively. FCC v1.4.1 formalizes the pattern across all three root-of-repo governance documents, adds short header labels that make the layer obvious on first skim, and wires the cross-links so each document points at its two companions.

Layer 1 — Emergent Design (ROADMAP.md)

The Roadmap captures work that is about to happen or is in flight. It answers questions like "what's in the next minor?", "what slipped from the last one?", and "which big ideas are still upstream of a decision?" Roadmap entries are short-lived by design — they move out of the file when they ship, when they are deferred with cause, or when they get absorbed into a Strategic Architecture Review decision.

You should treat the Roadmap as a working document. Drift is fine; drift here does not break consumers. Entries are welcome as bullet points, as markdown tables of stage-gated features, or as simple inline todo notes — whichever communicates intent fastest.

Layer 2 — Intentional Architecture (STRATEGIC_ARCHITECTURE_REVIEW.md)

The Strategic Architecture Review captures load-bearing decisions and the current-state inventory those decisions produce. Whereas the Roadmap is about change, Layer 2 is about state. Typical contents:

  • Canonical-authority declarations (this project owns FCC; consumer repos are listed here).
  • Current-state inventory tables (persona counts by category, plugin interop matrices, test-coverage gate targets, coverage ratchet records).
  • Phase-level milestone summaries that have actually shipped.
  • Cross-project alignment notes — the why behind a consumer repo's contract obligations.

A Strategic Architecture Review entry should survive for at least one major version. When it changes, consumers notice, so prefer adding an ADR in docs/decisions/ and pointing at it from Layer 2 rather than rewriting Layer 2 in-place.

Layer 3 — Protocol Architecture (AGENTS.md)

The AGENTS.md file captures the runtime-callable surface of FCC: one entry per agent/persona that participates in agent-to-agent protocols (A2A, MCP, REST/WS), with the endpoint, capabilities, and input/output shapes that remote callers rely on.

Layer 3 is the contract for anyone writing clients against FCC. Breaking changes to AGENTS.md are breaking changes to the ecosystem. The file is the authoritative source for:

  • A2A skill-card generation (fcc protocol a2a-cards).
  • MCP server tool manifests (fcc protocol mcp-tools).
  • Federation router discovery (cross-project NamespaceRegistry lookups).
  • The sister-repo integration tests (ecosystem-integration-tests, ice-ext-integration).

Because Layer 3 is load-bearing at runtime, every change MUST be accompanied by a matching test update and — for major structural changes — an ADR in docs/decisions/. See the reusable-governance.yml CI workflow for the gates that enforce this.

When to edit which file

Change type Layer Example
"I'm planning to add ..." Layer 1 A new persona domain pack on the shortlist for v1.5.
"I shipped and this is the new state." Layer 2 "v1.4.1 moves the persona count from 148 → 149 with IP Evaluation Analyst."
"I added a new callable agent surface." Layer 3 A new Model Governance Reviewer agent exposed on /agents/mgr.

A change is often both Layer 1 and Layer 2 — it's on the Roadmap until it ships, then moves to the Strategic Review. A change that touches Layer 3 will usually also leave traces in the other two.

Precedent repositories

The convention was refined during these sibling deployments:

  • ice_ext — introduced the three-layer split during its US20250272473A1 structural model redesign; uses the same file names and header labels this project adopts.
  • l2_mnemosyne — uses the same split with slightly different emphasis (Layer 3 is heavier because Mnemosyne is a memory-service provider).

For a detailed rationale on why three layers (vs. one monolithic ARCHITECTURE.md or a sprawling docs/), see ADR-003 and the commit history on STRATEGIC_ARCHITECTURE_REVIEW.md from v1.3.5 onwards.