ai-agents-architecture-contractlisted

Load-bearing design decisions for this repo as a contract you check before changing anything. Covers the asymmetric generation seam, source-of-truth per tree, hook runtime failure policy, memory tiers, plugin surfaces, invariants, and known-weak points. Use when you say `which tree is canonical`, `architecture contract`, `why is this designed this way`. Do NOT use for operating the build pipeline (use `ai-agents-generation-and-release`) or CI triage (use `ai-agents-debugging-playbook`).
rjmurillo/ai-agents · ★ 38 · AI & Automation · score 77

Install: claude install-skill rjmurillo/ai-agents

# AI Agents Architecture Contract  This skill is the map of design decisions that hold this repository up: what is canonical, what is generated, which invariants are enforced by gates, and where the structure is honestly weak. Read it before any change that touches more than one tree, any hook, any plugin surface, or any generated file. The repo's governance is verification-based, not trust-based (`.agents/SESSION-PROTOCOL.md:30`: "This protocol uses **verification-based enforcement**"), so almost every claim below is backed by a gate you can run. ## Triggers - `which tree is canonical` - `architecture contract` - `why is this designed this way` - `what invariant am I about to break` - `where is the source of truth for this file` ## Process ### Phase 1: Locate the source of truth before touching any file The generation seam is ASYMMETRIC. There is no single "templates in, everything out" pipeline. Two seams coexist (ADR-072, status Proposed, corrected this premise explicitly: "the seam is asymmetric"): 1. Agents: `templates/agents/*.shared.md` is canonical; the outputs under `src/` are generated. 2. Rules, skills, commands, hooks: `.claude/` itself is canonical (Claude Code consumes it directly); generators emit m