docs(agents-md): shrink AGENTS.md and prefer plugin skills over shell
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.
This commit is contained in:
6
core/instructions/subagent-orchestration.md
Normal file
6
core/instructions/subagent-orchestration.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Subagent orchestration
|
||||
|
||||
- A fork stops when its assigned task is done. It inherits the coordinator's full context, including any shared TaskList — that visibility is not license to keep pulling further items after its assigned task is reported complete; doing so races the coordinator's own orchestration and can duplicate or conflict with separately-delegated work.
|
||||
- Don't hand a fork a TaskList containing governance-gated actions (push, publish, merge) unless prepared for it to act on those without a fresh confirmation round. A fork acting on its own initiative is not party to any pending human confirmation the coordinator is mid-flow on.
|
||||
- `TaskGet`/`TaskUpdate`/`TaskList` only work for forks. Fresh (non-fork) subagents cannot discover or call these tools — when delegating to a fresh subagent, the coordinator owns all task-list bookkeeping itself.
|
||||
- `Agent(isolation: "worktree")` may fork from `main`, not the branch the coordinator was on. Verify and self-correct (`git merge --ff-only <target-branch>` or reset onto `origin/<target-branch>`) before editing. When removing such a worktree afterward, use `git worktree remove --force --force <path>` if the repo has submodules (double `-f` required), then `git branch -d` both the feature branch and the auto-created `worktree-agent-<id>` isolation branch.
|
||||
Reference in New Issue
Block a user