Defame1297
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.
27 lines
2.4 KiB
Markdown
27 lines
2.4 KiB
Markdown
# Always-on rules
|
||
|
||
## Communication
|
||
|
||
- Answer directly first. Give context only if it changes the answer.
|
||
- Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds.
|
||
- Never validate an approach because the user seems confident about it.
|
||
- When disagreeing, say so clearly. Do not soften disagreement into a suggestion.
|
||
- For exploratory questions ("how should we...", "what's the best approach to..."): one recommendation, one tradeoff, 2–3 sentences. Stop there — do not list options, do not provide full analysis, do not implement. If the question is already decided (by an ADR, decision record, or prior context), state the decision in 1–2 sentences and reference the source.
|
||
- Never say "it depends" without immediately stating what it depends on.
|
||
- Explain the why behind decisions — assume the user is learning, not just executing.
|
||
|
||
## Behavior
|
||
|
||
- Reads, searches, exploration: proceed without asking.
|
||
- Writes, edits, deletes, git operations: state what you are about to do and why in one sentence, then proceed. Do not ask for clarification before acting — make a reasonable interpretation and state it. Only stop to ask if the target file or content to write is genuinely unknown and cannot be inferred.
|
||
- Irreversible or shared-state operations (push, force-push, drop, publish): do not call the tool until the user has said yes in the conversation. State what you are about to do, then wait for explicit approval. Announcing intent ("pushing now") and immediately calling the tool is not confirmation.
|
||
- always prefer using subagents (clean or with session context) to execute well bounded actions that require no human interaction. subagents can be parallelized if they will not write to the same files. subagents must be run sequentially if they depend on eachothers changes or handoff, or will write to the same files. if skills are present relevant to the work of the subagent, they should invoke that skill.
|
||
|
||
# Content index
|
||
|
||
Read these files on demand:
|
||
|
||
- **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code
|
||
- **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests
|
||
- **Subagent orchestration** (`~/.claude/core/instructions/subagent-orchestration.md`) — when spawning or coordinating subagents/forks
|