Architecture brief for AI agents — current and future state of Fallout #237

Why

AI tools work better with a clear, machine-readable view of the codebase's module boundaries, layering, and intended evolution. Today this is spread across docs/architecture.md, docs/rebrand-plan.md, and the roadmap — not in a form an agent can orient on without reading the whole docs tree.

A purpose-built brief would let any AI tool:

• Understand current module boundaries (Fallout.Common, Fallout.Build, Fallout.Components, Fallout.Tooling, …) and how they layer.
• Know which abstractions are stable vs in-flight (the internal middleware pipeline in v11 vs the public Fallout.Plugin.Sdk in v12).
• Understand the migration shape (the Nuke.* shim under src/Shims/, the vendored vs-solutionpersistence fork).
• Suggest where a new feature should live, not just how to write it.

Action

• Decide format and location — a dedicated docs/architecture-for-agents.md, or a restructured docs/architecture.md with explicit layer/module headers and stability annotations
• Capture current state:
  • Module layering and dependency direction
  • Public vs internal boundaries (especially the internal-only v11 middleware)
  • Shim strategy (src/Shims/Nuke.Common)
  • Vendored fork strategy (vendor/vs-solutionpersistence)
  • Source-generator surface (Fallout.SourceGenerators outputs)
• Capture future state:
  • v12 plugin SDK shape (link the open RFCs)
  • CD vision (v13)
  • Anything else explicitly in flux
• Cross-link from AGENTS.md so it's discoverable
• Add maintenance discipline — this doc decays fast; add a "last refreshed" date and an owner
• Optional: structure parts as YAML/JSON frontmatter or a sidecar file if it helps tools parse the module map

Coordinate with

• AGENTS.md adoption issue — this doc gets linked from there
• Existing docs/architecture.md and docs/rebrand-plan.md — decide whether to merge, supersede, or cross-reference

Done when

• A dedicated architecture brief for agents exists and is linked from AGENTS.md
• Current and future state both covered to the depth agents need
• A maintenance discipline (refresh date, owner) is in place