Nest AGENTS.md never reaches Claude Code agents — orientation and commit sign-off rules are silently inert
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
**Describe the bug**
The nest's `AGENTS.md` never reaches agents running on the `claude-agent-acp` runtime. Claude Code auto-loads `CLAUDE.md`, not `AGENTS.md`, and `buzz-acp` only *names* `AGENTS.md` in the system prompt without injecting its contents. Nothing written in `AGENTS.md` is applied unless the agent independently decides to `Read` the file.
The two halves:
1. `managed_agents/nest.rs` writes `AGENTS.md` as the nest's orientation document and refreshes its static content on version bumps.
2. `workspace_section()` in `crates/buzz-acp/src/pool.rs` tells the agent the file exists:
> All workspace files — `AGENTS.md`, `RESEARCH/`, `PLANS/`, … — live here.
but the contents are never added to the prompt. Grepping `crates/buzz-acp` for `AGENTS.md` returns only this one string.
By contrast, `crates/buzz-agent/tests/hints_integration.rs` explicitly covers "AGENTS.md in cwd is loaded into the system prompt" — so the behavior exists for the `buzz-agent` runtime but not for the Claude Code path.
**Impact**
Everything in the shipped `AGENTS.md` template is silently inert for Claude Code agents, including the **Git Commit Identity** section — the mandatory `Signed-off-by` and `Co-authored-by` trailers naming the human operator. That is an accountability requirement that quietly is not delivered to the agent making the commits. The knowledge-file frontmatter conventions, the directory layout, and "cite sources" are inert for the same reason.
This is easy to miss because everything *looks* configured: the file exists, the system prompt references it by name, and the agent will cheerfully read it if you ask it to.
**Steps to reproduce**
1. In an empty directory, create `AGENTS.md` containing `The project codeword is XYZZY-7741.`
2. Run, with tools forbidden so the model cannot simply read the file:
```
claude --print --permission-mode dontAsk \
"Without using any tools, what is the project codeword?"
```
3. The codeword is not in context.
4. Rename the file to `CLAUDE.md` and repeat — the codeword is returned.
5. Replace `CLAUDE.md` with `@./AGENTS.md` (restoring `AGENTS.md`) and repeat — the codeword is returned.
Equivalently, from a real nest: ask a Buzz agent to state a rule from `AGENTS.md` without using tools. It does not know it.
**Expected behavior**
Conventions written to the nest's orientation file are actually in the agent's context.
**Version and platform**
- Buzz version: 0.5.7 (self-built from `main`, x86_64)
- OS: macOS 12.7.6 (Darwin 21.6.0), Intel
- Runtime: `claude-agent-acp`, Claude Code 2.1.221
**Logs / additional context**
Workaround, verified — write a `CLAUDE.md` next to `AGENTS.md` containing:
```markdown
@./AGENTS.md
```
Claude Code resolves the `@` import relative to `CLAUDE.md`, so `AGENTS.md` stays the single source of truth for the other runtimes (codex, goose, `buzz-agent`) with no duplicated rules. After adding it, the same "without using any tools" question returns the conventions correctly.
Suggested fix: have nest init write that one-line `CLAUDE.md` alongside `AGENTS.md` and `SKILL.md`, or inject the `AGENTS.md` contents into the system prompt the way `buzz-agent` does.
Related: #3371 covers agents inheriting the owner's *global* `CLAUDE.md`; a nest-local `CLAUDE.md` would sit below that in Claude Code's hierarchy, so the two interact and may be worth designing together.
Contributor guide
Research direction
Start with managed_agents/nest.rs and workspace_section() in crates/buzz-acp/src/pool.rs, then compare the existing behavior covered by crates/buzz-agent/tests/hints_integration.rs. Investigate the suggested nest-local CLAUDE.md import or system-prompt injection, and verify completion with the no-tools reproduction: AGENTS.md conventions should reach claude-agent-acp agents without an explicit file read.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 67/100