跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

ai-agents-architecture-contract

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 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rjmurillo/ai-agents --skill ai-agents-architecture-contract

技能说明


name: ai-agents-architecture-contract description: 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). version: 1.0.0 license: MIT metadata: routing: role: conditional-adjunct invoker: ai-agents-generation-and-release trigger: ai-agents-generation-and-release points here to explain why the generation seam is shaped this way user-facing: false

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 runs on observable evidence, not trust: active requirements name evidence that exists independent of any committed session log, so almost every claim below is backed by a gate you can run. (PR #5135, 2026-08-18, retired the earlier "verification-based enforcement" wording in favor of this evidence-sink framing; SESSION-PROTOCOL.md, the doc that carried that wording, was later deleted along with the session skill cluster.)

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 for the Copilot CLI and VS Code copies only; src/copilot-cli/agents/ and src/vs-code-agents/ are generated from it. src/claude/*.md is NOT: it is hand-written canonical (see the table row below).
  2. Rules, skills, hooks: .claude/ itself is canonical (Claude Code consumes it directly); generators emit mirrors for other harnesses. There is no commands class any more: ADR-064 (issue #5632) converted every command into a skill and deleted the bridge that mirrored .claude/commands/<name>.md into src/copilot-cli/skills/<name>/SKILL.md, so skills are the single user-invocable surface and check_commands_retired.py blocks a command coming back.

Source-of-truth table (verified against .agents/governance/GENERATOR-FILES.md and the build/scripts/build_all.py GENERATORS list; 7 generators: agents, agent-catalog, adr-index, skills, rules, lib, hooks):

Artifact classCanonical source (edit here)Generated or mirrored output (never edit)Mechanism
Agents (Copilot CLI, VS Code)templates/agents/*.shared.mdsrc/copilot-cli/agents/, src/vs-code-agents/build/generate_agents.py per templates/platforms/*.yaml outputDir
Agents (Claude Code)src/claude/*.md is itself canonical, hand-writtennone; .claude/agents/ is a hand-maintained sibling copyMANUAL dual edit (ADR-036, superseded in governance by ADR-052 2026-08-25, procedure still operative and unimplemented in ADR-052); templates/README.md:131: "Also edit: src/claude/{agent}.md (MANUAL - not auto-synced!)"
Rules.claude/rules/*.md.github/instructions/, src/copilot-cli/instructions/build/scripts/generate_rules.py
Skills.claude/skills/<name>/src/copilot-cli/skills/<name>/build/scripts/generate_skills.py
Hooks.claude/hooks/ plus .claude/settings.jsonsrc/copilot-cli/hooks/ plus its hooks.jsonbuild/scripts/generate_hooks.py (plus dispatcher artifacts, Phase 3)
PR-quality CI prompts.claude/skills/review/references/{role}.md.github/prompts/pr-quality-gate-{role}.mdbuild/scripts/generate_pr_quality_prompts.py
Shared Python libsscripts/hook_utilities, scripts/github_core, scripts/ai_review_commonsrc/claude/lib/{hook_utilities,github_core,ai_review_common} and src/copilot-cli/lib/{hook_utilities,github_core,ai_review_common} direct (imports rewritten to relative); .claude/lib/{hook_utilities,github_core,ai_review_common} arrives second, binplaced from src/claude/lib/build_all.py's lib step (build/scripts/lib_mirror.py, ADR-109 B5); --check is the CI dry-run
Self-host agent copiesthe sources above.claude/agents/<name>.md, .github/agents/<name>.agent.mdhand-synced, guarded by build/scripts/validate_install_parity.py

Direction rule: generators read canonical, write mirrors. They NEVER write .claude/. That invariant is enforced in code: assert_no_claude_writes (build/scripts/build_all.py:888), applied at lines 2221 to 2230 of the same file under the comment "REQ-003-010: enforce .claude/ no-write invariant"; any generator write under .claude/ prints REQ-003-010 VIOLATION and exits 2. ADR-108 carves out one class, the template-owned skill files under .claude/skills/, passed to the guard as an allowlist. When a drift check goes red, the output shows a difference, not a direction. Alway

阅读完整来源 ↗