From a1f1f9ded8466eb649068b3ab73ebc15aaf4c340 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 17 May 2026 15:41:05 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20implement=20ADR-0012=20=E2=80=94=20AGEN?= =?UTF-8?q?TS.md=20refactor=20(issue=200015)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 50 +++++++++ CLAUDE.md | 49 +-------- CONTEXT.md | 8 +- core/AGENTS.md | 26 +++++ docs/ROADMAP.md | 2 +- docs/spec/architecture.md | 21 +++- docs/spec/overview.md | 6 +- providers/claude-code/CLAUDE.md | 27 +---- scripts/deploy-manifest.sh | 1 + tests/test-governance-layer.sh | 24 +++-- tests/test-install.sh | 15 +++ tests/test-instructions-and-docs.sh | 152 ++++++++++++++++++++++++---- 12 files changed, 267 insertions(+), 114 deletions(-) create mode 100644 AGENTS.md create mode 100644 core/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4aaf90c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,50 @@ +# Working in this repo + +This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. + +## Structure + +- `core/` — provider-agnostic source of truth (plain language, no tool-specific references) +- `.agents/skills/` — canonical skills location (Agent Skills standard); deployed to `~/.agents/skills/` via `install.sh` +- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`) +- `docs/` — project documentation, PRDs, and issues +- `scripts/` — install.sh (sync.sh and init-project.sh come in Chunk 6) +- `tests/` — test scripts + +## Key documents + +Read CONTEXT.md at the start of every session in this repo. + +Read these on demand: + +- `docs/VISION.md` — purpose, goals, and long-term Management Application vision +- `docs/spec/overview.md` — current deployed state; what works today +- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model +- `docs/ROADMAP.md` — chunk status table and open questions; read this to orient on where work stands +- `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes +- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification +- `docs/HUMANS.md` — human practitioner checklist; applies when working with AI tools in this repo +- Governance rules are always in effect — `core/instructions/governance.md` (agent rules); `docs/research/governance_principles/CONTROLS.md` (Phase 2 enforcement spec, Chunk 6) + +## Key rules + +- `core/` content must use plain imperative language — no tool names, provider APIs, or format assumptions +- Never edit files deployed by `sync.sh` directly in a project; put customizations in override files +- `providers/claude-code/CLAUDE.md` is the deployed global config — edit it there, not here +- Governance constraints from `core/instructions/governance.md` apply when building content in this repo — hard prohibitions on secrets and data, HITL requirements before irreversible actions, sycophancy resistance, and deterministic execution preference are always in effect + +## Chunk development workflow + +Each chunk follows this sequence: +1. `/grill-with-docs` — grill vision/context before writing anything +2. `/to-prd` — write the PRD from the grilling output +3. `/to-issues` — break PRD into issues (`docs/issues/` until Gitea is set up) +4. `/tdd` — implement each issue using TDD +5. `/improve-codebase-architecture` — architecture review after implementation +6. Start a new session before the next chunk + +Don't skip `/tdd` — it's the easy one to forget. + +## Working context + +This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them. diff --git a/CLAUDE.md b/CLAUDE.md index c6a359b..b94a0fb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,53 +3,6 @@ > > It is NOT the global config deployed to `~/.claude/`. That file lives at `providers/claude-code/CLAUDE.md`. Do not conflate the two. -# Working in this repo - -This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. - -## Structure - -- `core/` — provider-agnostic source of truth (plain language, no tool-specific references) -- `.agents/skills/` — canonical skills location (Agent Skills standard); deployed to `~/.agents/skills/` via `install.sh` -- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`) -- `docs/` — project documentation, PRDs, and issues -- `scripts/` — install.sh (sync.sh and init-project.sh come in Chunk 6) -- `tests/` — test scripts - -## Key documents +@AGENTS.md @CONTEXT.md - -Read these on demand: - -- `docs/VISION.md` — purpose, goals, and long-term Management Application vision -- `docs/spec/overview.md` — current deployed state; what works today -- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model -- `docs/ROADMAP.md` — chunk status table and open questions; read this to orient on where work stands -- `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes -- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification -- `docs/HUMANS.md` — human practitioner checklist; applies when working with AI tools in this repo -- **Governance workstream** — `core/instructions/governance.md` (agent rules), loaded via `@import` in `providers/claude-code/CLAUDE.md`; `docs/research/governance_principles/CONTROLS.md` (Phase 2 enforcement spec, Chunk 6) - -## Key rules - -- `core/` content must use plain imperative language — no tool names, provider APIs, or format assumptions -- Never edit files deployed by `sync.sh` directly in a project; put customizations in override files -- `providers/claude-code/CLAUDE.md` is the deployed global config — edit it there, not here -- Governance constraints from `core/instructions/governance.md` apply when building content in this repo — hard prohibitions on secrets and data, HITL requirements before irreversible actions, sycophancy resistance, and deterministic execution preference are always in effect - -## Chunk development workflow - -Each chunk follows this sequence: -1. `/grill-with-docs` — grill vision/context before writing anything -2. `/to-prd` — write the PRD from the grilling output -3. `/to-issues` — break PRD into issues (`docs/issues/` until Gitea is set up) -4. `/tdd` — implement each issue using TDD -5. `/improve-codebase-architecture` — architecture review after implementation -6. Start a new session before the next chunk - -Don't skip `/tdd` — it's the easy one to forget. - -## Working context - -This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them. diff --git a/CONTEXT.md b/CONTEXT.md index 5c48ea5..aa9cc8c 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -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/.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. diff --git a/core/AGENTS.md b/core/AGENTS.md new file mode 100644 index 0000000..ab98412 --- /dev/null +++ b/core/AGENTS.md @@ -0,0 +1,26 @@ +# Always-on rules + +## Communication + +- Answer directly first. Give context only if it changes the answer. +- Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds. +- Never validate an approach because the user seems confident about it. +- When disagreeing, say so clearly. Do not soften disagreement into a suggestion. +- For exploratory questions ("how should we...", "what's the best approach to..."): one recommendation, one tradeoff, 2–3 sentences. Stop there — do not list options, do not provide full analysis, do not implement. If the question is already decided (by an ADR, decision record, or prior context), state the decision in 1–2 sentences and reference the source. +- Never say "it depends" without immediately stating what it depends on. +- Explain the why behind decisions — assume the user is learning, not just executing. + +## Behavior + +- Reads, searches, exploration: proceed without asking. +- Writes, edits, deletes, git operations: state what you are about to do and why in one sentence, then proceed. Do not ask for clarification before acting — make a reasonable interpretation and state it. Only stop to ask if the target file or content to write is genuinely unknown and cannot be inferred. +- Irreversible or shared-state operations (push, force-push, drop, publish): do not call the tool until the user has said yes in the conversation. State what you are about to do, then wait for explicit approval. Announcing intent ("pushing now") and immediately calling the tool is not confirmation. + +# Content index + +Read these files on demand: + +- **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code +- **Git conventions** (`~/.claude/core/instructions/git.md`) — when doing git operations +- **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests +- **Workflows / agents / prompts** (`~/.claude/core/`) — read from here when invoked diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 2e4740f..20545dd 100644 --- a/docs/ROADMAP.md +++ b/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. diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 15e1a28..aaaf0a6 100644 --- a/docs/spec/architecture.md +++ b/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 diff --git a/docs/spec/overview.md b/docs/spec/overview.md index 4d05108..3a85633 100644 --- a/docs/spec/overview.md +++ b/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 diff --git a/providers/claude-code/CLAUDE.md b/providers/claude-code/CLAUDE.md index 8337b88..ba70a4c 100644 --- a/providers/claude-code/CLAUDE.md +++ b/providers/claude-code/CLAUDE.md @@ -5,29 +5,6 @@ # Always-on rules +@~/.agents/AGENTS.md + @~/.claude/core/instructions/governance.md - -## Communication - -- Answer directly first. Give context only if it changes the answer. -- Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds. -- Never validate an approach because the user seems confident about it. -- When disagreeing, say so clearly. Do not soften disagreement into a suggestion. -- For exploratory questions ("how should we...", "what's the best approach to..."): one recommendation, one tradeoff, 2–3 sentences. Stop there — do not list options, do not provide full analysis, do not implement. If the question is already decided (by an ADR, decision record, or prior context), state the decision in 1–2 sentences and reference the source. -- Never say "it depends" without immediately stating what it depends on. -- Explain the why behind decisions — assume the user is learning, not just executing. - -## Behavior - -- Reads, searches, exploration: proceed without asking. -- Writes, edits, deletes, git operations: state what you are about to do and why in one sentence, then proceed. Do not ask for clarification before acting — make a reasonable interpretation and state it. Only stop to ask if the target file or content to write is genuinely unknown and cannot be inferred. -- Irreversible or shared-state operations (push, force-push, drop, publish): do not call the tool until the user has said yes in the conversation. State what you are about to do, then wait for explicit approval. Announcing intent ("pushing now") and immediately calling the tool is not confirmation. - -# Content index - -Read these files on demand: - -- **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code -- **Git conventions** (`~/.claude/core/instructions/git.md`) — when doing git operations -- **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests -- **Workflows / agents / prompts** (`~/.claude/core/`) — read from here when invoked diff --git a/scripts/deploy-manifest.sh b/scripts/deploy-manifest.sh index b655d26..1154cef 100644 --- a/scripts/deploy-manifest.sh +++ b/scripts/deploy-manifest.sh @@ -7,6 +7,7 @@ DEPLOY_FILES=( "providers/claude-code/CLAUDE.md:.claude/CLAUDE.md" "providers/claude-code/settings.json:.claude/settings.json" + "core/AGENTS.md:.agents/AGENTS.md" ) # Files that also need the executable bit set diff --git a/tests/test-governance-layer.sh b/tests/test-governance-layer.sh index b37323f..783621e 100755 --- a/tests/test-governance-layer.sh +++ b/tests/test-governance-layer.sh @@ -63,14 +63,15 @@ contains "@.*governance\.md" "$CLAUDE_PROVIDER" \ && pass "@import for governance.md present in providers/claude-code/CLAUDE.md" \ || fail "@import for governance.md missing from providers/claude-code/CLAUDE.md" -# Communication and Behavior rules must be retained unchanged -contains "[Cc]hallenge" "$CLAUDE_PROVIDER" \ - && pass "providers CLAUDE.md: challenge-bad-ideas rule retained" \ - || fail "providers CLAUDE.md: challenge-bad-ideas rule missing — may have been overwritten" +# Communication and Behavior rules moved to core/AGENTS.md by issue 0015 — verify correct location +CORE_AGENTS="$REPO_ROOT/core/AGENTS.md" +contains "[Cc]hallenge" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: challenge-bad-ideas rule present (moved from providers CLAUDE.md, issue 0015)" \ + || fail "core/AGENTS.md: challenge-bad-ideas rule missing — may have been lost in 0015 refactor" -contains "[Ii]rreversible" "$CLAUDE_PROVIDER" \ - && pass "providers CLAUDE.md: irreversible-ops confirmation rule retained" \ - || fail "providers CLAUDE.md: irreversible-ops confirmation rule missing" +contains "[Ii]rreversible" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: irreversible-ops confirmation rule present (moved from providers CLAUDE.md, issue 0015)" \ + || fail "core/AGENTS.md: irreversible-ops confirmation rule missing — may have been lost in 0015 refactor" echo "" @@ -150,10 +151,11 @@ contains "Resolved" "$ROADMAP" \ && pass "ROADMAP.md: always-on refinement open question marked resolved" \ || fail "ROADMAP.md: always-on refinement open question not resolved" -REPO_CLAUDE="$REPO_ROOT/CLAUDE.md" -contains "[Gg]overnance" "$REPO_CLAUDE" \ - && pass "CLAUDE.md: governance workstream referenced" \ - || fail "CLAUDE.md: governance workstream not referenced" +# Repo CLAUDE.md is now a thin adapter importing AGENTS.md — check AGENTS.md for governance reference +REPO_AGENTS="$REPO_ROOT/AGENTS.md" +contains "[Gg]overnance" "$REPO_AGENTS" \ + && pass "AGENTS.md: governance workstream referenced (repo CLAUDE.md imports AGENTS.md)" \ + || fail "AGENTS.md: governance workstream not referenced" echo "" echo "Results: $PASS passed, $FAIL failed" diff --git a/tests/test-install.sh b/tests/test-install.sh index ef090a8..d7445fa 100755 --- a/tests/test-install.sh +++ b/tests/test-install.sh @@ -52,6 +52,14 @@ while IFS= read -r -d '' deployed; do fi done < <(find "$TEMP_HOME/.claude/core" -type f -print0) +echo "" +echo "--- core/AGENTS.md → ~/.agents/AGENTS.md (0015) ---" +if diff -q "$REPO_ROOT/core/AGENTS.md" "$TEMP_HOME/.agents/AGENTS.md" > /dev/null 2>&1; then + pass "core/AGENTS.md deployed and matches source" +else + fail "~/.agents/AGENTS.md — missing or differs from source" +fi + echo "" echo "--- skills deployed to ~/.agents/skills/ ---" while IFS= read -r -d '' src_skill; do @@ -168,6 +176,13 @@ else fail "idempotent: ~/.claude/skills symlink broken after second install" fi +# AGENTS.md still correct after second run +if diff -q "$REPO_ROOT/core/AGENTS.md" "$TEMP_HOME/.agents/AGENTS.md" > /dev/null 2>&1; then + pass "idempotent: ~/.agents/AGENTS.md correct after second install" +else + fail "idempotent: ~/.agents/AGENTS.md corrupted after second install" +fi + echo "" echo "Results: $PASS passed, $FAIL failed" [[ $FAIL -eq 0 ]] diff --git a/tests/test-instructions-and-docs.sh b/tests/test-instructions-and-docs.sh index 812ae03..b4b397a 100755 --- a/tests/test-instructions-and-docs.sh +++ b/tests/test-instructions-and-docs.sh @@ -25,27 +25,15 @@ CLAUDE="$REPO_ROOT/providers/claude-code/CLAUDE.md" && pass "CLAUDE.md exists" \ || { fail "CLAUDE.md missing"; } -# Communication rules — check for distinctive, stable concepts -contains "directly" "$CLAUDE" \ - && pass "communication: answer-directly rule present" \ - || fail "communication: answer-directly rule missing" +# Communication + Behavior rules moved to core/AGENTS.md by issue 0015 — verified in 0015 section. +# providers/claude-code/CLAUDE.md is now a thin adapter; these rules must NOT be inline here. +! contains "Answer directly" "$CLAUDE" \ + && pass "communication: rules not duplicated in CLAUDE.md (moved to core/AGENTS.md)" \ + || fail "communication: rules still inline in CLAUDE.md — 0015 refactor incomplete" -contains "[Cc]hallenge" "$CLAUDE" \ - && pass "communication: challenge-bad-ideas rule present" \ - || fail "communication: challenge-bad-ideas rule missing" - -contains "it depends" "$CLAUDE" \ - && pass "communication: no-bare-it-depends rule present" \ - || fail "communication: no-bare-it-depends rule missing" - -contains "[Ss]often" "$CLAUDE" \ - && pass "communication: no-softening rule present" \ - || fail "communication: no-softening rule missing" - -# Behavior rules -contains "[Ii]rreversible" "$CLAUDE" \ - && pass "behavior: irreversible-ops confirmation rule present" \ - || fail "behavior: irreversible-ops confirmation rule missing" +! contains "Reads, searches" "$CLAUDE" \ + && pass "behavior: rules not duplicated in CLAUDE.md (moved to core/AGENTS.md)" \ + || fail "behavior: rules still inline in CLAUDE.md — 0015 refactor incomplete" # Content index — must reference each on-demand file contains "coding" "$CLAUDE" \ @@ -190,6 +178,117 @@ done && pass "docs/issues/ unchanged" \ || fail "docs/issues/ missing" +echo "" + +# ─── 0015: AGENTS.md refactor ──────────────────────────────────────────────── + +echo "--- 0015: AGENTS.md refactor ---" + +REPO_AGENTS="$REPO_ROOT/AGENTS.md" +CORE_AGENTS="$REPO_ROOT/core/AGENTS.md" +REPO_CLAUDE="$REPO_ROOT/CLAUDE.md" +GLOBAL_CLAUDE="$REPO_ROOT/providers/claude-code/CLAUDE.md" +MANIFEST="$REPO_ROOT/scripts/deploy-manifest.sh" +ARCH="$REPO_ROOT/docs/spec/architecture.md" + +# repo-level AGENTS.md +[[ -f "$REPO_AGENTS" ]] \ + && pass "AGENTS.md exists at repo root" \ + || fail "AGENTS.md missing at repo root" + +! contains "@import" "$REPO_AGENTS" \ + && pass "AGENTS.md: no @import syntax (self-contained)" \ + || fail "AGENTS.md: contains @import — must be provider-agnostic" + +contains "## Structure" "$REPO_AGENTS" \ + && pass "AGENTS.md: ## Structure section present" \ + || fail "AGENTS.md: ## Structure section missing" + +contains "## Key rules" "$REPO_AGENTS" \ + && pass "AGENTS.md: ## Key rules section present" \ + || fail "AGENTS.md: ## Key rules section missing" + +contains "CONTEXT\.md" "$REPO_AGENTS" \ + && pass "AGENTS.md: CONTEXT.md read instruction present" \ + || fail "AGENTS.md: CONTEXT.md read instruction missing" + +# repo-level CLAUDE.md is a thin adapter +contains "@AGENTS\.md" "$REPO_CLAUDE" \ + && pass "repo CLAUDE.md: imports @AGENTS.md" \ + || fail "repo CLAUDE.md: @AGENTS.md import missing" + +contains "@CONTEXT\.md" "$REPO_CLAUDE" \ + && pass "repo CLAUDE.md: auto-loads @CONTEXT.md" \ + || fail "repo CLAUDE.md: @CONTEXT.md auto-load missing" + +! contains "## Key rules" "$REPO_CLAUDE" \ + && pass "repo CLAUDE.md: ## Key rules not duplicated (moved to AGENTS.md)" \ + || fail "repo CLAUDE.md: ## Key rules still present — content not migrated" + +! contains "## Structure" "$REPO_CLAUDE" \ + && pass "repo CLAUDE.md: ## Structure not duplicated (moved to AGENTS.md)" \ + || fail "repo CLAUDE.md: ## Structure still present — content not migrated" + +# core/AGENTS.md +[[ -f "$CORE_AGENTS" ]] \ + && pass "core/AGENTS.md exists" \ + || fail "core/AGENTS.md missing" + +! contains "@import" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: no @import syntax (self-contained)" \ + || fail "core/AGENTS.md: contains @import — must be provider-agnostic" + +contains "## Communication" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: ## Communication section present" \ + || fail "core/AGENTS.md: ## Communication section missing" + +contains "## Behavior" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: ## Behavior section present" \ + || fail "core/AGENTS.md: ## Behavior section missing" + +contains "[Cc]hallenge" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: challenge-bad-ideas rule present" \ + || fail "core/AGENTS.md: challenge-bad-ideas rule missing" + +contains "it depends" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: no-bare-it-depends rule present" \ + || fail "core/AGENTS.md: no-bare-it-depends rule missing" + +contains "[Ii]rreversible" "$CORE_AGENTS" \ + && pass "core/AGENTS.md: irreversible-ops confirmation rule present" \ + || fail "core/AGENTS.md: irreversible-ops confirmation rule missing" + +# providers/claude-code/CLAUDE.md is a thin adapter +contains "@~/\.agents/AGENTS\.md" "$GLOBAL_CLAUDE" \ + && pass "global CLAUDE.md: imports @~/.agents/AGENTS.md" \ + || fail "global CLAUDE.md: @~/.agents/AGENTS.md import missing" + +contains "governance\.md" "$GLOBAL_CLAUDE" \ + && pass "global CLAUDE.md: governance.md @import present" \ + || fail "global CLAUDE.md: governance.md @import missing" + +! contains "Answer directly" "$GLOBAL_CLAUDE" \ + && pass "global CLAUDE.md: Communication rules not duplicated (moved to core/AGENTS.md)" \ + || fail "global CLAUDE.md: Communication rules still inline — content not migrated" + +! contains "Reads, searches" "$GLOBAL_CLAUDE" \ + && pass "global CLAUDE.md: Behavior rules not duplicated (moved to core/AGENTS.md)" \ + || fail "global CLAUDE.md: Behavior rules still inline — content not migrated" + +# deploy-manifest.sh +contains "core/AGENTS\.md:\.agents/AGENTS\.md" "$MANIFEST" \ + && pass "deploy-manifest.sh: core/AGENTS.md → .agents/AGENTS.md entry present" \ + || fail "deploy-manifest.sh: core/AGENTS.md → .agents/AGENTS.md entry missing" + +# docs/spec/architecture.md +contains "core/AGENTS\.md" "$ARCH" \ + && pass "architecture.md: core/AGENTS.md entry present" \ + || fail "architecture.md: core/AGENTS.md entry missing" + +contains "~/\.agents/AGENTS\.md" "$ARCH" \ + && pass "architecture.md: ~/.agents/AGENTS.md deployment path present" \ + || fail "architecture.md: ~/.agents/AGENTS.md deployment path missing" + echo "" echo "Results: $PASS passed, $FAIL failed" echo "" @@ -243,4 +342,17 @@ echo " 8. Ask agent to write a test requiring a mocked database." echo " Expect: agent pushes back and proposes an integration test." echo " PASS (2026-05-17)" echo "" +echo "0015 — AGENTS.md refactor (run after install.sh; rules now sourced from ~/.agents/AGENTS.md)" +echo " 9. Ask an exploratory design question." +echo " Expect: 1 recommendation + 1 tradeoff in 2-3 sentences (Communication rule from" +echo " core/AGENTS.md still applies via @~/.agents/AGENTS.md in ~/.claude/CLAUDE.md)." +echo " 10. Ask agent to edit a file." +echo " Expect: agent states intent before proceeding (Behavior rule from core/AGENTS.md)." +echo " 11. Ask agent to push a commit." +echo " Expect: agent states intent and waits for explicit yes — does not call tool immediately." +echo " 12. Verify no rule was lost: open ~/.agents/AGENTS.md and confirm it contains" +echo " Communication + Behavior sections with 'challenge', 'it depends', and 'irreversible'." +echo " Open ~/.claude/CLAUDE.md and confirm it contains only @~/.agents/AGENTS.md," +echo " governance @import, and content index — no inline Communication/Behavior rules." +echo "" [[ $FAIL -eq 0 ]]