feat: implement ADR-0012 — AGENTS.md refactor (issue 0015)

Create AGENTS.md at repo root and core/AGENTS.md as provider-agnostic
sources of always-on rules. Slim both CLAUDE.md files to thin adapters.
Deploy core/AGENTS.md → ~/.agents/AGENTS.md via deploy-manifest.sh.
Update three test suites to check correct locations post-refactor.
All automated tests pass (57 instructions, 106 install, 25 governance).
HITL behavioral test plan in test-instructions-and-docs.sh scenarios 9–12.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/ROADMAP.md

@@ -98,4 +98,4 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or
 - **Chunk 2 behavioral tests** — run and fully resolved 2026-05-17. 7/8 pass; scenario 4 (push confirmation) inconclusive — no remote in test environment, rule tightened but unverified. All fixable failures addressed: rule specificity in `providers/claude-code/CLAUDE.md`; context-loading guarantee via `@import CONTEXT.md` in repo CLAUDE.md; standing rule in CONTEXT.md to check `docs/adr/` and ROADMAP resolved entries before answering design questions. Chunk 2 ✅ complete.
 - **Governance Phase 1 behavioral tests** — run 2026-05-17. 3/4 testable scenarios pass. Secrets rule gap fixed (2026-05-17): extended to cover credential reproduction in response text and examples, with placeholder requirement added to `core/instructions/governance.md`. HITL scenario not testable in this environment (Nginx not installed); HITL gap evidenced by instructions test scenario 4 — push confirmation rule fix addresses the same root cause. Governance Phase 1 ✅ complete.
 - **AI ethics/security workstream** — `docs/notes/ai-ethics-security-principles.md` exploration note is superseded. Governance Phase 1 (`core/instructions/governance.md`) covers all planned scope: credentials, data classification, HITL, scope discipline, agent autonomy, transparency, and security code review. Tier-placement architectural question resolved by the `@import` always-on model. No separate workstream needed.
-- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-chunk start + quarterly post-roadmap. **Issues created 0015–0028** — all HITL; 0015 (AGENTS.md refactor, prerequisite), 0016 (skill workflow grill, produces conventions for 0017–0028), 0017–0018 (bootstrap skills: write-eval, write-skill), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). Acceptance criteria for 0017–0028 to be refined after 0016 grill session.
+- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-chunk start + quarterly post-roadmap. **Issues created 0015–0028** — all HITL; ~~0015 (AGENTS.md refactor, prerequisite)~~ ✅, 0016 (skill workflow grill, produces conventions for 0017–0028), 0017–0018 (bootstrap skills: write-eval, write-skill), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). Acceptance criteria for 0017–0028 to be refined after 0016 grill session.

docs/spec/architecture.md

@@ -20,16 +20,19 @@ Projects consume from this repo by pulling updates via `sync.sh` (Chunk 6). Unti
 
 ```
 ai-development/
+├── AGENTS.md                    # Provider-agnostic always-on rules for this repo; imported by repo CLAUDE.md
+├── CONTEXT.md                   # Domain language, principles, glossary; auto-loaded at session start
 ├── docs/                        # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/, spec/) + research/ (raw research audit trail)
 ├── .agents/                     # Agent Skills standard location (provider-agnostic)
 │   └── skills/                  # SKILL.md files — canonical source, deployed to ~/.agents/skills/
 ├── core/                        # Provider-agnostic source of truth
+│   ├── AGENTS.md                # Global always-on rules (Communication + Behavior); deployed to ~/.agents/AGENTS.md
 │   ├── instructions/            # AI behavior definitions (plain markdown)
 │   ├── agents/                  # Agent role definitions
 │   ├── workflows/               # Workflow definitions
 │   └── prompts/                 # Reusable prompt templates
 ├── providers/                   # Provider-specific adapters
-│   ├── claude-code/             # CLAUDE.md, settings.json, provider-manifest.sh
+│   ├── claude-code/             # CLAUDE.md (thin adapter), settings.json, provider-manifest.sh
 │   └── copilot/                 # copilot-instructions.md, hooks, agents adapter
 ├── templates/                   # Project scaffolding templates
 └── scripts/
@@ -44,12 +47,13 @@ ai-development/
 `install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead:
 
 - `.agents/skills/` → `~/.agents/skills/` — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved)
+- `core/AGENTS.md` → `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`
 - Provider adapters declared in `providers/*/provider-manifest.sh` — symlinks from the provider's skill path to `~/.agents/skills/`; e.g. Claude Code gets `~/.claude/skills/ → ~/.agents/skills/` because it reads `~/.claude/skills/` natively. Providers that read `~/.agents/skills/` directly need no adapter.
 - `core/` → `~/.claude/core/` — workflows, prompts, agent definitions; agent reads on demand
 - `providers/claude-code/settings.json` → `~/.claude/settings.json`
-- Writes a lean `~/.claude/CLAUDE.md` — universal rules only, plus pointers to where detailed content lives
+- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md` — thin adapter: imports `~/.agents/AGENTS.md` and `governance.md`; no original content
 
-`~/.claude/CLAUDE.md` is an index, not a content dump. It tells the agent where things are; the agent pulls what it needs using its Read tool. This keeps context size minimal — only what is needed for every session is loaded upfront.
+`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
 
 ## Governance layer
 
@@ -59,9 +63,16 @@ The governance layer has two phases:
 - **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
 - **Phase 2** (Chunk 6): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
 
-## This repo's own CLAUDE.md
+## AGENTS.md pattern
 
-This repo has a `CLAUDE.md` at its root — a meta file that tells Claude how to work *in this repo itself* (structure, conventions, how to add skills/workflows/providers). This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/` for use across all projects. Do not conflate the two.
+This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012):
+
+- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules, chunk workflow). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
+- **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects. Deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`.
+
+Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content.
+
+This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for working in this repo. It imports `AGENTS.md` and `CONTEXT.md`, nothing more. This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/`.
 
 ## Provider model
 

docs/spec/overview.md

@@ -2,7 +2,7 @@
 
 Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change.
 
-*Last updated: 2026-05-17*
+*Last updated: 2026-05-17 (issue 0015)*
 
 ## What is deployed
 
@@ -16,7 +16,8 @@ Current skills: `caveman`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-c
 **Prerequisite:** AGENTS.md refactor must complete before Chunk 3 skill implementation begins — both `CLAUDE.md` files (repo-level and global) become thin adapters importing `AGENTS.md`. See ADR-0012 (to be written during implementation).
 
 ### Claude Code configuration
-- `~/.claude/CLAUDE.md` — global config index; always-on rules + content index pointers
+- `~/.claude/CLAUDE.md` — thin adapter; imports `~/.agents/AGENTS.md` (Communication + Behavior) and `governance.md`; content index pointers only
+- `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); provider-agnostic source of truth
 - `~/.claude/core/instructions/` — coding, git, testing, governance instruction files
 - `~/.claude/settings.json` — Claude Code settings
 
@@ -41,6 +42,7 @@ For chunk planning and open questions, see `docs/ROADMAP.md`.
 
 ## Recent changes
 
+- 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (`AGENTS.md` at repo root, `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`). Both CLAUDE.md files slimmed to thin adapters. `deploy-manifest.sh` updated. `docs/spec/architecture.md` updated with new structure. ADR-0012 in effect.
 - 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session
 - 2026-05-17 — behavioral tests fully resolved: `CONTEXT.md` now always-loaded via `@import` in repo `CLAUDE.md`; standing rule added to check `docs/adr/` and ROADMAP resolved entries before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete
 - 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only