docs: rewrite AGENTS.md as user-facing 'Extending Zero' guide

[Vasanthdev2004]

Summary

Replaces the project-specific 19-line AGENTS.md with a user-facing "Extending Zero" guide. The previous file was a Go-internal instruction set; this rewrite positions AGENTS.md as the entry point for end users who want to customize Zero, the way similar files work in Claude Code, Codex, and other CLI agents.

What's in the new AGENTS.md

Nine sections, ~290 new lines:

1. Drop a project AGENTS.md — where to put it (./AGENTS.md or ./.zero/AGENTS.md), the frontmatter format, and authoring tips.
2. Custom specialists (droids) — three scopes (built-in / user / project), manifest format, the zero specialist CLI commands. Points to docs/SPECIALISTS.md for the full spec.
3. Skills — */SKILL.md discovery under ~/.local/share/zero/skills/ (or $ZERO_SKILLS_DIR), with format example.
4. Hooks — six lifecycle events (�eforeTool, �fterTool, sessionStart, sessionEnd, specialistStart, specialistStop), JSON config at ~/.config/zero/hooks.json and ./.zero/hooks.json, exit-code semantics, and a note that misbehaving hooks show up in zero doctor.
5. MCP — as a client (the mcp.servers block in config.json, both stdio and http transports, zero mcp CLI) and as a server (zero serve --mcp).
6. Plugins — plugin.json schema bundling tools / hooks / skills, zero plugins install / list / enable / disable / remove.
7. Configuration locations — the resolution order (built-in < user < project < CLI < env) and the deliberate ignore of �dditionalWriteRoots in project config.
8. End-to-end example — what a team should commit to the repo vs what each contributor keeps in their home dir.
9. Reference — links to README.md, docs/SPECIALISTS.md, docs/PRD.md, docs/STREAM_JSON_PROTOCOL.md, docs/INSTALL.md.

Why

Three previous PRs on AGENTS.md were closed because the framing kept drifting (awesome-list, then Go-specific 10-mode instructions). This rewrite keeps it as a single user-facing page that points outward to the deeper docs where they exist, and explains the rest inline where they don't.

Risk

• File rename is just a content swap; path stays AGENTS.md (case-insensitive Windows matches the existing tracked file AGENTS.MD).
• No code changes, no test impact.
• The file is referenced from description: and globs: frontmatter that the agent runtime reads, so the new description and globs: "*.go, *.js, *.md" values are the only behavior-affecting changes. They are deliberately broader than the previous Go-only globs.

Summary by CodeRabbit

• Documentation
  • Replaced AGENTS.md with a full “Extending Zero” guide, detailing guideline discovery, frontmatter fields, specialists, hooks, MCP configuration, plugins, configuration precedence, and repository examples.
• New Features
  • Project guidelines are now injected into the prompt by walking from the nearest git root to the current directory (general-to-specific), supporting AGENTS.md, ZERO.md, and .zero/AGENTS.md with truncation safeguards.
• Tests
  • Added unit tests for case-insensitive guideline resolution, traversal order, fallback behavior, and content truncation at size limits.

[github-actions]

Zero automated PR review

Verdict: No blockers found

Blockers

• None found.

Validation

• [pass] Diff hygiene: git diff --check
• [pass] Tests: go test ./...
• [pass] Build: go run ./cmd/zero-release build
• [pass] Smoke build: go run ./cmd/zero-release smoke

Scope

Head: a6ce791bc913
Changed files (3): AGENTS.MD, internal/agent/system_prompt.go, internal/agent/system_prompt_test.go

This deterministic review checks validation status and basic diff hygiene. A human reviewer still owns product judgment and design quality.

[coderabbitai]

Walkthrough

This PR implements and documents project guideline file injection into system prompts. It adds git-root-to-cwd multi-file traversal with case-insensitive discovery, byte budgeting, and truncation; documents the complete feature in AGENTS.MD; and validates behavior across integration and unit tests.

Changes

Guideline Injection Feature

Layer / File(s)	Summary
"Extending Zero" feature documentation AGENTS.MD	Updated frontmatter with broader globs patterns. Replaced brief Go-command note with ~290-line reference guide covering project guideline discovery mechanics, specialist droid creation and CLI management, skill directory conventions and SKILL.md format, hook lifecycle events and exit-code blocking, MCP client/server setup and config merge precedence, plugin manifest and install/enable/disable cycle, configuration precedence hierarchy (built-in → user → project → CLI → environment), end-to-end repository example, and reference links.
System prompt multi-file guideline injection internal/agent/system_prompt.go	Constants define per-file and cumulative byte caps for guideline content. workspaceContext now calls projectGuidelines(cwd, findProjectGitRoot(cwd)) to walk from git root down to cwd, collecting and injecting matching guideline files in general-to-specific order. Core projectGuidelines orchestrates directory chain construction, case-insensitive file discovery per level, content reading with rune-boundary truncation, and labeled prompt injection. Helper functions: projectGuidelineDirs builds root-to-leaf directory chain; projectGuidelineLabel computes relative path labels; findProjectContextFile resolves target directory case-insensitively and selects first matching guideline filename; resolveDirCaseInsensitive walks path segments with case-insensitive matching; findProjectGitRoot locates nearest ancestor .git entry.
Guideline injection test suite internal/agent/system_prompt_test.go	Integration tests verify case-insensitive filename resolution (AGENTS.MD), monorepo path-walking order and block placement, fallback to ZERO.md and .zero/AGENTS.md, and truncation markers at byte-cap boundaries. Unit tests verify projectGuidelineDirs orders directories root-to-leaf and collapses to cwd when git root unavailable, and findProjectContextFile selects case-insensitive basename matches.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Gitlawb/zero#129: Both PRs modify internal/agent/system_prompt.go to inject project guidelines into system prompts—main PR expands initial single-directory logic to multi-file git-root-to-cwd traversal with stricter budgeting.
• Gitlawb/zero#139: Both PRs modify project-guideline loading and truncation logic in internal/agent/system_prompt.go used by buildSystemPrompt and context reporting paths.

Suggested reviewers

• gnanam1990

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.18% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary change: rewriting AGENTS.md documentation as a user-facing guide titled 'Extending Zero'.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agents-md-extension-guide

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.MD`:
- Around line 102-108: The fenced code block in AGENTS.MD displaying the skill
directory structure is missing a language identifier on the opening fence. Add
the language specifier "plaintext" to the opening triple backticks (the fence at
the start of the directory listing example) to comply with markdown linting
standards and enable proper syntax highlighting.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a0dd9375-ea83-4d36-b834-1782db8adadd

📥 Commits

Reviewing files that changed from the base of the PR and between 6df5c2b and 67e10b7.

📒 Files selected for processing (1)

• AGENTS.MD

[Vasanthdev2004]

Follow-up: two more commits since the original opening

4a22259 docs(AGENTS): align Extending Zero with actual loader behavior + D-style features

The first version of this PR made six claims that were wrong about Zero itself. This commit fixes them and surfaces the new behavior introduced in 6fb0eb2:

• Section 1 rewritten to match the real priority order [AGENTS.md, ZERO.md, .zero/AGENTS.md], the case-insensitive basename callout, the per-file (8 KiB) and total (32 KiB) caps, the eager-load + restart-required caveat, and the new monorepo path-walking ("walks from cwd up to git root, general-to-specific order").
• Section 2 (Specialists): roadmap note about the planned /droids in-UI manager.
• Section 3 (Skills): corrected the discovery-root chain (ZERO_SKILLS_DIR → XDG_DATA_HOME/zero/skills → ~/.local/share/zero/skills/), noted that project-level skills aren't supported yet, and called out the plugin-declared-skill gap.
• Section 4 (Hooks) and Section 6 (Plugins): roadmap notes about the planned /hooks and /plugins in-UI managers.
• Frontmatter globs broadened to *.go, *.js, *.md, *.json, *.toml, *.yaml, *.yml to match the actual file types Zero reads.

6fb0eb2 feat(agent): make AGENTS.md loader case-insensitive + add path-walking

Two changes to the loader in internal/agent/system_prompt.go that bring Zero closer to D's DynamicContextDiscovery model and fix a real bug.

1. Case-insensitive basename matching. The git-tracked filename is AGENTS.MD (uppercase MD), but the loader was looking for AGENTS.md (lowercase md). On a case-sensitive filesystem (Linux, WSL, or a CI runner) this made the file invisible to the loader. The new indProjectContextFile uses ReadDir + ToLower to resolve the on-disk filename and matches AGENTS.MD, Agents.md, �gents.md, etc. to the same entry. The visible filename in the prompt label is now the actual on-disk name (AGENTS.MD), not the lookup name.

2. Upward path-walking. The loader previously did a single first-match-wins lookup at cwd. The new projectGuidelines walks from cwd up to the nearest git root, finds the first matching project context file at each level, and injects them in general-to-specific order (git root first, cwd last). A monorepo with a root AGENTS.md and per-service AGENTS.md files now sees both, with the most specific rules last. This mirrors D's per-Read dynamic path discovery, just at session start.

Cap behavior:

• Per-file cap unchanged: 8 KiB.
• New total cap of 32 KiB across all matched files, enforced via a rolling counter; when the budget is exhausted, further files are dropped.
• Truncation marker unchanged: \n… (truncated).

New helpers: projectGuidelineDirs, projectGuidelineLabel, indProjectContextFile,
esolveDirCaseInsensitive, indProjectGitRoot.

New tests (all passing, full go test ./internal/agent/ suite still green):

• TestBuildSystemPromptInjectsProjectGuidelinesCaseInsensitive — verifies AGENTS.MD resolves on a case-sensitive FS.
• TestBuildSystemPromptProjectGuidelinesPathWalkingMonorepo — verifies root + leaf both injected, root first.
• TestBuildSystemPromptProjectGuidelinesZeroFallback — verifies ZERO.md is the second-priority name.
• TestBuildSystemPromptProjectGuidelinesProjectLocalFallback — verifies .zero/AGENTS.md is the third-priority fallback.
• TestBuildSystemPromptProjectGuidelinesTruncatesAtTotalCap — verifies the 32 KiB total cap is enforced with the truncation marker.
• TestProjectGuidelineDirsOrdersRootToLeaf and TestProjectGuidelineDirsCollapsesToCwdWithoutGitRoot — helper unit tests.
• TestFindProjectContextFileCaseInsensitiveBasename — helper unit test.

The existing TestBuildSystemPromptInjectsWorkspaceContext still passes; for a single-file repo the label is AGENTS.md / AGENTS.MD matching the on-disk name.

What I deliberately did NOT change

• Per-Read dynamic discovery like D. D injects AGENTS.md content as a system reminder on each Read tool call, which keeps the prompt cache valid. Zero's loader is eager at session start, and changing that model would invalidate a much larger refactor. Worth a follow-up PR if you want it.
• In-UI managers (/droids, /hooks, /plugins). Each is a multi-file feature on its own; flagged in the doc as roadmap.
• Project-level skills. The skills loader (internal/skills/skills.go) explicitly notes that plugin-declared skills are not yet merged. Documented as a gap; the fix is a separate PR.

[gnanam1990]

Review: AGENTS.md → "Extending Zero" guide

The structure and writing are a real improvement — user-facing, well-organized, good copy-paste examples. But the guide documents several commands/flags/behaviors that don't exist in the current code, which will mislead users. I grep-verified each against the tree:

1. Plugin verbs (§6): zero plugins install / enable / disable aren't implemented — runPlugins (internal/cli/extensions.go) only dispatches list / add / remove(rm). Use zero plugins add <path>; drop enable/disable for plugins (those exist for hooks/mcp, but not plugins).
2. Specialist prompt (§2): zero specialist create ... --prompt-file api-reviewer.md — there is no --prompt-file flag (internal/cli/specialist.go). It's --prompt "<text>" (inline).
3. ${env:...} (§5): "Authorization": "Bearer ${env:GITHUB_TOKEN}" — there is no ${env:} expansion anywhere; MCP header/env values are sent verbatim (internal/mcp/config.go, client.go mergeProcessEnv). A user following this would transmit the literal string ${env:GITHUB_TOKEN}.
4. Hook arg placeholders (§4): "args": ["${tool}", "${input}"] — hook args are passed verbatim to exec.CommandContext; the tool/input payload reaches hooks as JSON on stdin, not via arg substitution (internal/hooks/dispatch.go). No ${...} expansion occurs.
5. zero doctor (§4): "use zero doctor to surface [hooks]" — doctor has no hook check (internal/doctor/): its checks are runtime / config / provider / connectivity / sandbox / lsp.

Secondary (non-blocking): the globs: / alwaysApply: frontmatter described in §1 is currently inert — the loader injects the whole file (frontmatter included) as prompt text and does no frontmatter parsing, so globs: doesn't scope anything yet. Also the README/CLI use "specialists" throughout, so the "droids" synonym reads inconsistently.

Everything else checks out — serve --mcp, mcp add … -- <cmd>, the hook event names, skills dir order, specialist/plugin paths, and the byte caps are all accurate. Requesting changes only on the items above; once the non-existent syntax is removed or fixed, this is a strong guide.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

AGENTS.MD (1)

107-113: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language identifier to fenced code block.

The code block displaying the skill directory structure lacks a language specifier. Add plaintext to the opening fence to comply with Markdown linting standards.

🔧 Proposed fix

-```
+```plaintext
 ~/.local/share/zero/skills/
   run-benchmarks/
     SKILL.md
   write-changelog/
     SKILL.md

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @AGENTS.MD around lines 107 - 113, The fenced code block displaying the
directory structure starting with ~/.local/share/zero/skills/ is missing a
language identifier. Add plaintext as the language specifier immediately after
the opening fence (change toplaintext) to comply with Markdown linting
standards.

</details>

<!-- cr-comment:v1:bd4a272bd718f9f05f7c3b28 -->

_Source: Linters/SAST tools_

</blockquote></details>

</blockquote></details>

🧹 Nitpick comments (1)

AGENTS.MD (1)

226-230: 💤 Low value

Consider restructuring for clarity on line 230.

The phrase "the env var your MCP server reads" is grammatically awkward. While "that" is technically correct for an object, consider restructuring for clarity—for instance: "A secret manager that injects the env var that your MCP server reads on its own" or simply "A secret manager that injects the secret your MCP server reads."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.MD` around lines 226 - 230, The phrase "the env var your MCP server
reads" on line 230 lacks clarity due to awkward phrasing. Restructure this third
bullet point to improve readability by inserting "that" before "your" to read
"the env var that your MCP server reads" or alternatively simplify it to "the
secret your MCP server reads" to make the relationship between the secret
manager and the MCP server's behavior more explicit and grammatically clear.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@AGENTS.MD`:
- Around line 107-113: The fenced code block displaying the directory structure
starting with ~/.local/share/zero/skills/ is missing a language identifier. Add
plaintext as the language specifier immediately after the opening fence (change
``` to ```plaintext) to comply with Markdown linting standards.

---

Nitpick comments:
In `@AGENTS.MD`:
- Around line 226-230: The phrase "the env var your MCP server reads" on line
230 lacks clarity due to awkward phrasing. Restructure this third bullet point
to improve readability by inserting "that" before "your" to read "the env var
that your MCP server reads" or alternatively simplify it to "the secret your MCP
server reads" to make the relationship between the secret manager and the MCP
server's behavior more explicit and grammatically clear.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d154ac9-1a3e-4c42-b81e-98a89582fa92

📥 Commits

Reviewing files that changed from the base of the PR and between 6fb0eb2 and a6ce791.

📒 Files selected for processing (1)

• AGENTS.MD

[gnanam1990]

Re-review (after a6ce791)

The follow-up commit resolves every must-fix item from the previous review — I re-verified each against the current code and the updated AGENTS.MD:

1. Plugins — now zero plugins add ./github-pr-review; the non-existent install/enable/disable verbs are gone, with an accurate note that a plugin is enabled by being present (or "enabled": false in its manifest). ✓
2. Specialist prompt — --prompt-file replaced with --prompt "$(cat api-reviewer.md)", plus a useful zero specialist path. ✓
3. ${env:...} — now states plainly there is no env expansion (values sent verbatim) and documents the real ways to keep a token out of the file. ✓
4. Hook args — ${tool}/${input} dropped; correctly explains the payload arrives as JSON on stdin, with a stdin-reading handler example. ✓
5. zero doctor — reworded to point at the audit log; no longer claims a doctor hook check. ✓

Secondary items also handled: the inert globs:/alwaysApply: frontmatter example is replaced with an accurate "preserved verbatim, not parsed today" note, and the (droids) synonym plus the non-existent /droids /hooks /plugins slash-command roadmaps are gone.

All clean corrections, no new claims that don't match the code. Thorough turnaround — approving.

[Vasanthdev2004]

@coderabbitai approve

[coderabbitai]

✅ Action performed

Comments resolved and changes approved.

[Vasanthdev2004]

Pushed a6ce791 to address the review. Walked each item against the tree, then re-checked the rewritten sections after editing:

• §6 plugin verbs: replaced install / enable / disable with add and noted that enable/disable are not CLI verbs today (the plugin is on/off by presence or by the manifest's "enabled": false, mirroring the runPlugins switch in internal/cli/extensions.go).
• §2 specialist prompt: dropped the --prompt-file api-reviewer.md line, switched to --prompt "$(cat api-reviewer.md)" (the flag is inline per runSpecialistCreate), and added zero specialist path to the example.
• §5 MCP env vars: removed the ${env:GITHUB_TOKEN} line and the "token-bearing values come from env vars" phrasing. Headers are sent verbatim (internal/mcp/permissions.go, client.go mergeProcessEnv), so the section now lists the three real ways to keep tokens out of the file (wrapper script, command substitution, server reading its own env) instead.
• §4 hook args: dropped the ["${tool}", "${input}"] placeholders, called out that the payload is JSON on stdin (internal/hooks/dispatch.go execCommandRunner), and added a short bash handler that reads stdin and blocks rm -rf.
• §4 doctor: removed the zero doctor line; doctor's checks are runtime / config / provider / connectivity / sandbox / lsp (internal/doctor/doctor.go). Repointed to the audit log.

Secondary: dropped the globs: / alwaysApply: example and the "Use globs: to scope" tip — the loader injects the whole file as prompt text and does not parse those keys (greped for frontmatter parsing in internal/agent, nothing). Added a one-liner noting the frontmatter is preserved verbatim. Also dropped the (droids) parenthetical on §2 and the §2/§4/§6 roadmap slash commands (/droids, /hooks, /plugins are not implemented — only /mcp is, per internal/tui/commands.go) and rephrased the roadmaps to "in-UI … manager is on the backlog".