0015 — AGENTS.md refactor (prerequisite) #22

New Issue

Claude · 2026-06-28T17:09:19Z

Claude commented

2026-06-28 17:09:19 +00:00

Type: HITL
Parent PRD: docs/prd/chunk-3-skills-library.md

What to build

Implement ADR-0012: create two AGENTS.md files and slim both CLAUDE.md files to thin adapters. As much provider-agnostic content as possible migrates to each respective AGENTS.md; only Claude Code-specific syntax (@import, inline @file directives) stays in the adapters.

Repo-level AGENTS.md (new, at repo root):

Receives all provider-agnostic content from repo-level CLAUDE.md: working context, structure description, key rules (provider-agnostic core, sync model, edit discipline), the key documents list expressed in plain prose (no @import syntax)
Repo-level CLAUDE.md becomes: @AGENTS.md + Claude Code-specific additions (@CONTEXT.md auto-load, any @import directives)

Global core/AGENTS.md (new, deployed to ~/.agents/AGENTS.md via install.sh):

Receives all provider-agnostic content from providers/claude-code/CLAUDE.md: Communication rules, Behavior rules
providers/claude-code/CLAUDE.md becomes: @~/.agents/AGENTS.md + Claude Code-specific additions (@import for governance.md, content index @import directives)

AGENTS.md files must be self-contained — no @import syntax. Where a file was previously auto-loaded via @file in CLAUDE.md, the AGENTS.md equivalent states the same instruction in plain prose.

docs/spec/architecture.md is updated in this PR (per "updated in same PR as structural change" convention).

HITL gate: human reviews both content splits, runs a fresh-session behavioral test to confirm all previously always-on rules still apply, and approves before committing.

Acceptance criteria

AGENTS.md exists at repo root; contains all provider-agnostic content from repo-level CLAUDE.md; no @import syntax
Repo-level CLAUDE.md contains @AGENTS.md + Claude Code-specific additions only; no duplicated always-on content
core/AGENTS.md exists; contains Communication and Behavior rules from providers/claude-code/CLAUDE.md; no @import syntax
providers/claude-code/CLAUDE.md contains @~/.agents/AGENTS.md + @import directives only; no duplicated always-on content
install.sh deploys core/AGENTS.md → ~/.agents/AGENTS.md
docs/spec/architecture.md updated with AGENTS.md entries in the file structure
HITL: human confirms no always-on rule was lost or duplicated across the split
HITL: human runs fresh-session behavioral test confirming governance, communication, and behavior rules all apply without any manual load step

Blocked by

None — can start immediately.

**Type:** HITL **Parent PRD:** `docs/prd/chunk-3-skills-library.md` ## What to build Implement ADR-0012: create two AGENTS.md files and slim both CLAUDE.md files to thin adapters. As much provider-agnostic content as possible migrates to each respective AGENTS.md; only Claude Code-specific syntax (`@import`, inline `@file` directives) stays in the adapters. **Repo-level** `AGENTS.md` (new, at repo root): - Receives all provider-agnostic content from repo-level `CLAUDE.md`: working context, structure description, key rules (provider-agnostic core, sync model, edit discipline), the key documents list expressed in plain prose (no `@import` syntax) - Repo-level `CLAUDE.md` becomes: `@AGENTS.md` + Claude Code-specific additions (`@CONTEXT.md` auto-load, any `@import` directives) **Global** `core/AGENTS.md` (new, deployed to `~/.agents/AGENTS.md` via `install.sh`): - Receives all provider-agnostic content from `providers/claude-code/CLAUDE.md`: Communication rules, Behavior rules - `providers/claude-code/CLAUDE.md` becomes: `@~/.agents/AGENTS.md` + Claude Code-specific additions (`@import` for `governance.md`, content index `@import` directives) AGENTS.md files must be self-contained — no `@import` syntax. Where a file was previously auto-loaded via `@file` in CLAUDE.md, the AGENTS.md equivalent states the same instruction in plain prose. `docs/spec/architecture.md` is updated in this PR (per "updated in same PR as structural change" convention). HITL gate: human reviews both content splits, runs a fresh-session behavioral test to confirm all previously always-on rules still apply, and approves before committing. ## Acceptance criteria - [ ] `AGENTS.md` exists at repo root; contains all provider-agnostic content from repo-level `CLAUDE.md`; no `@import` syntax - [ ] Repo-level `CLAUDE.md` contains `@AGENTS.md` + Claude Code-specific additions only; no duplicated always-on content - [x] `core/AGENTS.md` exists; contains Communication and Behavior rules from `providers/claude-code/CLAUDE.md`; no `@import` syntax - [x] `providers/claude-code/CLAUDE.md` contains `@~/.agents/AGENTS.md` + `@import` directives only; no duplicated always-on content - [x] `install.sh` deploys `core/AGENTS.md` → `~/.agents/AGENTS.md` - [x] `docs/spec/architecture.md` updated with AGENTS.md entries in the file structure - [x] **HITL:** human confirms no always-on rule was lost or duplicated across the split - [x] **HITL:** human runs fresh-session behavioral test confirming governance, communication, and behavior rules all apply without any manual load step ## Blocked by None — can start immediately.

Claude added this to the Legacy / Triage milestone 2026-06-28 17:09:19 +00:00

Claude added the Kind/Feature

Priority

Medium

3

labels 2026-06-28 17:09:19 +00:00

Claude closed this issue

2026-06-28 17:13:41 +00:00

Claude referenced this issue

2026-06-28 17:14:45 +00:00

refactor: align repo with marketplace/plugin model — migrate docs and issues to Gitea, rewrite specs, clean up stale artifacts #15

Sign in to join this conversation.