Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
be2910f8f6613a91518e4636feb1ff890c962966
holocron/docs/issues/0015-agents-md-refactor.md
Defame1297 9457efff36 docs: Chunk 3 issues 0015-0028 and doc updates 
14 issues created covering AGENTS.md refactor prerequisite, skill
implementation workflow grill, bootstrap skills (write-eval, write-skill),
remaining factory skills, and one issue per skill category group through
to chunk closure. All HITL; acceptance criteria for 0017-0028 to be
refined after 0016 grill session.

Doc updates: CONTEXT.md PRD/issue scope clarified (HOW distribution
across architecture-review and issue design notes); ROADMAP.md housekeeping
updated with bootstrap order and issue range; spec/overview.md recent
changes entry added; PRD updated (skills-index: delete → update).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-17 15:18:36 +00:00

2.6 KiB
Raw Blame History

0015 — AGENTS.md refactor (prerequisite)

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.

Reference in New Issue View Git Blame Copy Permalink