Audit Finding: No Architecture Decision Records (ADRs) Exist

Source: Cross-repo audit (2026-02-22)

Problem

None of the 8 active repos have a docs/adr/ or docs/decisions/ directory. Significant architectural decisions (e.g., monorepo → meso-repo migration, .specify/ speckit framework, Gas Tank economic model) have no recorded rationale.

Impact

Future contributors (human or AI) cannot understand why decisions were made, only what was done. This leads to accidental reversals of intentional design choices.

Recommendation

1. Establish a docs/adr/ directory in every repo following the Michael Nygard ADR format.
2. Bootstrap with 0001-record-architecture-decisions.md.
3. Add an ADR template to this .github org repo (under .specify/templates/ or ISSUE_TEMPLATE/).
4. Agent workflow rule: Any change that introduces a new dependency, alters project structure, changes CI/CD patterns, or modifies cross-repo contracts MUST include a new ADR in the same PR.

Repos Affected

• All 8 active repos