block / block/buzz

Nest AGENTS.md never reaches Claude Code agents — orientation and commit sign-off rules are silently inert

Open
#5,367 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.