AGENTS.md had grown to duplicate content owned elsewhere: behavioral
rules already active globally via ~/.agents/AGENTS.md, a VISION.md
read-on-demand entry CONTEXT.md already covers at session start, and
setup/testing/commit instructions that explained hook mechanics the
git plugin's pc-run/git-commits skills already own. It also gave no
explicit steer toward using installed plugin skills over raw shell
commands, so agents defaulted to shelling out to git directly.
- Added a "Prefer plugin skills over raw shell" section mapping
operations (commits, branches, hooks, issues/PRs, linting, AGENTS.md
itself) to the skill that owns them.
- Collapsed Setup/Testing/Commit-conventions into one section, keeping
only the two genuinely non-obvious gotchas (missing
default_install_hook_types, bats submodule auto-init).
- Removed the "Subagent orchestration" section: its content was mostly
universal Agent/Task/worktree-tool facts, not specific to working in
this repo, so it moves to core/instructions/subagent-orchestration.md
(deployed globally via install.sh, referenced from core/AGENTS.md's
content index) rather than staying repo-local.
- Removed agentsmd-author's "not this repo's own" scope exclusion in
CONTEXT.md (ADR-0012 never mandated it) so this task could route
through it, and folded the forge-routing rule it left behind into
CONTEXT.md's existing Skill composition entry.
AGENTS.md: 50 -> 40 lines. Full test suite and manifest check pass.
## Why
The original rule said "prefer subagents" but gave no guidance on when to
run them in parallel vs. sequentially, or when to invoke a relevant skill.
This closes the ambiguity so agents make correct scheduling decisions without
having to reason it out from first principles each time.
## Why
`core/AGENTS.md` referenced a non-existent path (`~/.claude/core/commits.md`)
instead of the correct `~/.claude/core/instructions/commits.md`, and contained a
typo ("commiting" → "committing"). `core/instructions/commits.md` was wrapped in
an erroneous markdown code fence that caused agents reading the file to see it as
a raw text block rather than a live template with usable HTML comment sections.
## Impact
Agents following the content index in AGENTS.md will now resolve the correct path
for commit conventions. The commits template is now properly structured so its
comment-gated sections render as intended.
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Why
The existing git.md was thin — missing atomicity, working-state, and
trailer guidance that belong in any professional git workflow. No commit
message template existed, making the expected format implicit and
inconsistent across sessions.
## Impact
- git.md is now the canonical reference for commit hygiene rules
- commits.md provides a structured template (Why / Implementation Notes /
Impact / Git Trailers) that agents and humans can follow
- AGENTS.md cross-references commits.md so it is discoverable at session
start
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds behavior rule to always prefer subagents (clean or with session context)
for well-bounded actions that require no human interaction, keeping the parent
context lean and enabling parallel execution.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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>
