0001 — Agentic project foundation: 9-layer infrastructure

Status: Accepted Date: 2026-04-27 Deciders: TwoMore mobile team

Context

TwoMore is being developed primarily through agentic workflows — most code changes are authored by AI agents (Claude Code, etc.) and reviewed by humans. This is the primary contribution model going forward, not a temporary phase.

Empirical research on agentic coding (arXiv:2604.04990 "Architecture Without Architects", arXiv:2604.14228 "Dive into Claude Code", ICPC 2021 architecture-erosion practitioner study) demonstrates that:

• Agents scale prompt-driven complexity faster than human review can catch (5.9× LoC growth observed for identical tasks varying only prompt specificity)
• The "paradox of supervision": auto-approve rates climb from 20% (early sessions) to 40%+ (750+ sessions), so trust accumulates while supervision atrophies
• Architectural violations get buried under code-level noise in code review (62.5% of practitioners agree automated detection helps locate them)
• Agents fabricate success claims undetectably at the prompt level (we've experienced this in this project specifically — Wave A/B incidents where agents claimed success without persisting changes)

Existing project infrastructure was sufficient for human-only contribution but inadequate for agentic-first work. Specific gaps:

• ESLint is documented in CLAUDE.md but not actually wired up (workspace lint scripts are noop placeholders)
• No mechanical enforcement of CLAUDE.md rules — they exist only in narrative form
• No per-task agent prompt templates — every session reinvents context
• No verify-no-stale-claims — false success claims are undetected
• No machine-readable atomic constraints file — CLAUDE.md mixes policy with rationale

Options considered

Option A: Patch documentation; rely on agents to follow CLAUDE.md

• Pros: zero infrastructure work
• Cons: research shows this fails — agents read docs differently than humans, hallucinate compliance, drift accumulates invisibly. Already failed multiple times in this project.
• Effort: 0
• Reversibility: high (status quo)

Option B: Adopt mechanical enforcement only at a single layer (e.g., add ESLint custom rules)

• Pros: targeted improvement; ~1 week effort
• Cons: layer-by-layer enforcement leaves gaps. Without code generation (L1), agents still write boilerplate manually and drift. Without observability (L7), enforcement gaps go undetected. Without ADRs (L9), institutional memory is lost.
• Effort: ~5 days
• Reversibility: medium

Option C: 9-layer agentic-first foundation, phased over weeks

• Pros: comprehensive defense in depth. Each layer addresses a distinct drift mode. Validated against industry practice (Google Bazel, Shopify Packwerk, Nx, ArchUnitTS) and academic research on architecture erosion. Each layer is independently shippable so the project is in a strictly better state after each phase.
• Cons: ~39 hours of phased work + ~8 weeks of bake time before networking foundation begins. Significant calendar investment.
• Effort: ~5 working days of implementation + sequential bake gates
• Reversibility: per-phase (each phase rolls back independently)

Decision

Option C — adopt the 9-layer agentic-first foundation, phased per the master plan.

Primary reason: the project is committed to long-term agentic workflows. Patching the lower layers (Option B) would require returning to redo upper layers within months. Option A is empirically known to fail. The cost of Option C is real but bounded; the cost of inaction compounds over time as drift accumulates.

Dissenting consideration: ~8 weeks of calendar time before networking work begins is significant. Mitigated by: each phase leaves the project strictly improved, so even if the full plan is paused, partial completion is valuable.

Consequences

Positive

• Mechanical enforcement at every layer above documentation (L4 fitness tests, L5 hooks, L6 CI checks)
• Drift becomes a measurable signal, not a code-review-time discovery
• Code generation (L1) makes the right thing easier than the wrong thing
• AGENTS.md gives agents a curated atomic constraint file
• ADR directory captures institutional memory for future contributors
• Future architectural decisions (e.g., schema migrations, framework upgrades) operate inside the substrate this foundation provides

Negative

• ~5 working days of work before any user-visible feature shipping resumes
• ~8 weeks of total calendar time including bake gates
• Adds tooling complexity (ESLint plugin, ArchUnitTS, Hygen) that contributors must learn
• Each phase requires its own validation; cumulative validation effort is real

Neutral

• The 9-layer structure mirrors industry conventions, so contributors with experience at companies that adopt similar patterns (Google, Shopify, Spotify) will recognize it
• Establishes a pattern for future infrastructure work (well-defined phases, bake gates, sub-plans)

Implementation notes

Master plan: docs/architecture/agentic-project-foundation.md

Sub-plans:

• docs/architecture/networking-foundation-plan.md (Phase 14, follows infrastructure)
• docs/architecture/drift-prevention.md (enforcement strategy v2)

Phased rollout (P0 through P7):

Phase	Layers	Effort	Bake gate
P0	L0 + L9	4h	1 day
P1	L3 baseline	4h	3 days
P2	L3 plugin	3h	1 day
P3	L3 + L8 ratchet	6h	3 days
P4	L4 ArchUnitTS	4h	3 days
P5	L1 + L2	8h	5 days
P6	L5 + L6	6h	5 days
P7	L7 observability	4h	3 days

Phase 14a (MMKV) does not begin until all P0–P7 gates pass.

References

• Ford, Parsons, Kua, Sadalage. Building Evolutionary Architectures (O'Reilly 2022, 2nd ed.)
• Martin. Clean Architecture (2017)
• Skelton, Pais. Team Topologies (2019)
• arXiv:2604.04990 — "Architecture Without Architects: How AI Coding Agents Shape Software Architecture" (April 2026)
• arXiv:2604.14228 — "Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems" (April 2026)
• arXiv:2103.11392 — "Understanding Architecture Erosion: The Practitioners' Perspective" (ICPC 2021)
• arXiv:2306.08616 — "Towards Automated Identification of Violation Symptoms of Architecture Erosion" (2023)
• Shopify Engineering — "A Packwerk Retrospective" (4-year report)
• InfoQ — "Architectural Governance at AI Speed"
• Linux Foundation — AGENTS.md specification (Dec 2025, donated by OpenAI)
• ArchUnitTS — TypeScript port of ArchUnit canonical fitness function library
• Drift GitHub Action — AI-generated code structural-degradation detector