Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Defame1297
2026-05-17 15:41:05 +00:00
parent 9457efff36
commit a1f1f9ded8
12 changed files with 267 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
CONTEXT.md
View File

@@ -11,7 +11,7 @@ description: Domain language and decisions for the global AI development config
`core/` content uses plain imperative language — no tool names, provider APIs, or format assumptions. Anything referencing a specific tool belongs in `providers/`, not `core/`. Providers translate core content into the tool's expected format and language.
### CLAUDE.md index model
`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `AGENTS.md` via `@AGENTS.md` and appends Claude Code-specific additions (e.g. `@import` directives for on-demand files in `~/.claude/core/`). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0012. (Pending implementation in Chunk 3 prerequisite issue — current deployed state still uses `providers/claude-code/CLAUDE.md` as the content source.)
`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `~/.agents/AGENTS.md` via `@~/.agents/AGENTS.md` and appends Claude Code-specific additions (`@import` for governance.md, content index). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0012.
### Instruction file format
`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
@@ -101,7 +101,11 @@ Defined in full in `docs/ai-constitution.md` Section 3. Agent-actionable rules i
The failure mode where RLHF-trained models prioritise approval over accuracy. Treated as a first-class reliability risk: models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Designing against sycophancy is an explicit obligation, not a quality-of-life concern. Countermeasures: explicit pushback resistance instructions, prompting for dissent, cross-validating against independent sources. Never interpret AI agreement as AI accuracy.
### AGENTS.md
The provider-agnostic governance and instruction entry point. Lives at the repo root (project-level) and at `core/AGENTS.md` → deployed to `~/.agents/AGENTS.md` (global). Contains all always-on rules in plain markdown with no provider-specific syntax. Provider-specific files (`CLAUDE.md`) become thin adapters that import it. Claude Code reads `CLAUDE.md` natively (not `AGENTS.md` directly); `CLAUDE.md` imports `AGENTS.md` via `@AGENTS.md`. This pattern means a single source of truth can serve multiple providers without duplication.
The provider-agnostic always-on instruction entry point. Two files:
- **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`.
Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0012.
### Skill composition
A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology. Composition chains are formalised as workflows in Chunk 4.