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

docs(agents-md): shrink AGENTS.md and prefer plugin skills over shell #86

Merged
Defame1297 merged 1 commits from refactor/agents-md-prefer-plugin-skills into main 2026-07-24 21:24:28 +00:00
Conversation 1 Commits 1 Files Changed 4 +23 -26
Claude commented 2026-07-24 21:21:10 +00:00
Collaborator
Copy Link

Summary

  • Reduced AGENTS.md 50 → 40 lines by cutting content already owned elsewhere: behavioral rules duplicated from global ~/.agents/AGENTS.md, a docs/VISION.md on-demand entry already covered by CONTEXT.md's session-start read, and separate Setup/Testing/Commit-conventions sections collapsed into one.
  • Added a "Prefer plugin skills over raw shell" section mapping operations to the skill that owns them: git:git-commits, git:git-branches, git:git-history, git:git-worktrees, git:git-remotes, git:pc-run/git:pc-author, bin:gitea, lint:vale-config/lint:vale-run, core:agentsmd-author/core:agentsmd-audit.
  • Moved the "Subagent orchestration" section out of AGENTS.md into core/instructions/subagent-orchestration.md (deployed globally via install.sh, referenced from core/AGENTS.md's content index) — most of that content (fork-stop discipline, TaskList fork-only tools, worktree-isolation-forks-from-main) was universal Agent/Task/worktree-tool knowledge, not specific to working in this repo.
  • Removed agentsmd-author's "not this repo's own" self-hosting exclusion in CONTEXT.md — confirmed ADR-0012 never mandated it — since this task needed to route through the skill on this repo's own AGENTS.md. Folded the kyberforge:forge-routing rule (previously only in root AGENTS.md) into CONTEXT.md's existing "Skill composition" entry.

Test plan

  • bash tests/run-tests.sh — 7/7 passed
  • scripts/check-manifests.sh — clean
  • agentsmd-audit on the rewritten AGENTS.md — PASS, 0 fails (info-only findings, none applicable to this file)
## Summary - Reduced `AGENTS.md` 50 → 40 lines by cutting content already owned elsewhere: behavioral rules duplicated from global `~/.agents/AGENTS.md`, a `docs/VISION.md` on-demand entry already covered by `CONTEXT.md`'s session-start read, and separate Setup/Testing/Commit-conventions sections collapsed into one. - Added a **"Prefer plugin skills over raw shell"** section mapping operations to the skill that owns them: `git:git-commits`, `git:git-branches`, `git:git-history`, `git:git-worktrees`, `git:git-remotes`, `git:pc-run`/`git:pc-author`, `bin:gitea`, `lint:vale-config`/`lint:vale-run`, `core:agentsmd-author`/`core:agentsmd-audit`. - Moved the "Subagent orchestration" section out of `AGENTS.md` into `core/instructions/subagent-orchestration.md` (deployed globally via `install.sh`, referenced from `core/AGENTS.md`'s content index) — most of that content (fork-stop discipline, TaskList fork-only tools, worktree-isolation-forks-from-`main`) was universal Agent/Task/worktree-tool knowledge, not specific to working in this repo. - Removed `agentsmd-author`'s "not this repo's own" self-hosting exclusion in `CONTEXT.md` — confirmed ADR-0012 never mandated it — since this task needed to route through the skill on this repo's own `AGENTS.md`. Folded the `kyberforge:forge`-routing rule (previously only in root `AGENTS.md`) into `CONTEXT.md`'s existing "Skill composition" entry. ## Test plan - [x] `bash tests/run-tests.sh` — 7/7 passed - [x] `scripts/check-manifests.sh` — clean - [x] `agentsmd-audit` on the rewritten `AGENTS.md` — PASS, 0 fails (info-only findings, none applicable to this file)
Claude added 1 commit 2026-07-24 21:21:11 +00:00
docs(agents-md): shrink AGENTS.md and prefer plugin skills over shell 533364029a 
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.
Defame1297 approved these changes 2026-07-24 21:24:25 +00:00
Defame1297 merged commit 0ba8a95188 into main 2026-07-24 21:24:28 +00:00
Defame1297 deleted branch refactor/agents-md-prefer-plugin-skills 2026-07-24 21:24:28 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Defame1297
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#86
Delete Branch "refactor/agents-md-prefer-plugin-skills"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?