Defame1297
05bb9d6e9f
Complete ADR refactoring for issue #15: ## Changes 1. **Triage archival** — deleted chunk-era ADRs (0001–0003, 0006–0011, 0013); kept active decisions (0004, 0005, 0012, 0014+) 2. **ADR-0004 rewrite** — now reflects plugin-based skill distribution (`plugins/<name>/skills/` + `claude plugin install`) instead of monolithic `.agents/skills/` deployment 3. **Renumber to 0001–0009** — sequential clean slate after archival; all cross-references updated 4. **Content audit** — verified all 9 remaining ADRs for alignment with plugin model, removed stale chunk/deployment language Kept ADRs: 0001–0009 - 0001: Skills distributed via plugins - 0002: Two-tier CLAUDE.md (always-on + on-demand) - 0003: AGENTS.md as provider-agnostic entry point - 0004: INFO finding level in skill-audit - 0005: agent-author dual provider scaffold - 0006: Plugin version parity (version in both manifests) - 0007: Gitea as exclusive issue tracker - 0008: agent-audit single-file invocation - 0009: agent-audit field inventory reference All decisions are active and aligned with current repository state (marketplace/plugin model). Closes #15 (ADR section of acceptance criteria) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2.1 KiB
AGENTS.md as provider-agnostic governance entry point; CLAUDE.md as thin adapter
AGENTS.md is the single source of truth for always-on agent instructions. It lives at the repo root (project-level) and at core/AGENTS.md deployed to ~/.agents/AGENTS.md (global). It contains all universal rules in plain markdown with no provider-specific syntax. Provider-specific files (CLAUDE.md) become thin adapters that import it — the repo-level CLAUDE.md contains @AGENTS.md plus any Claude Code-specific additions; the global ~/.claude/CLAUDE.md imports ~/.agents/AGENTS.md similarly.
Claude Code reads CLAUDE.md natively, not AGENTS.md. The Anthropic documentation explicitly recommends the import pattern for repos that use AGENTS.md for other tools: CLAUDE.md contains @AGENTS.md and appends Claude Code-specific content below. This means CLAUDE.md continues to exist as the Claude Code entry point but carries no original content — it is purely an adapter.
AGENTS.md must be self-contained: no @import syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via @import stays in the Claude Code adapter (CLAUDE.md), pointing to core/instructions/ as today. The core/ deployment path (~/.claude/core/) reflects the current provider deployment model.
This partially supersedes ADR-0002 (two-tier CLAUDE.md model). ADR-0002 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in providers/claude-code/CLAUDE.md, now in AGENTS.md. The adapter layer ADR-0002 described still exists; CLAUDE.md is now the adapter rather than the source.
The alternative — keeping always-on content in providers/claude-code/CLAUDE.md — was rejected because it violates the provider-agnostic principle: content that applies to all agents regardless of provider has no business living in a provider-specific file. When multiple providers exist, duplicating that content into a separate adapter or maintaining two sources of the same rules creates drift and inconsistency.