docs: document AGENTS.md/ZERO.md and plugin manifest format - #522
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds an “Extending Zero” section to the README to document how project instruction files are injected into the system prompt and how plugins are discovered/configured, addressing the documentation gap described in #521.
Changes:
- Documented the project-instructions lookup chain for
AGENTS.md/ZERO.md/.zero/AGENTS.md, including size caps. - Added a brief overview of plugin discovery paths and the
plugin.jsonextension blocks (tools,hooks,prompts,skills). - Mentioned MCP servers and standalone skills in the context of extensibility.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Plugins are discovered from `~/.config/zero/plugins/<name>/plugin.json` | ||
| (user scope) and `<repo>/.zero/plugins/<name>/plugin.json` (project scope), | ||
| and managed with `zero plugins`. A manifest can declare: | ||
|
|
| `permission` of `allow`, `prompt`, or `deny`) | ||
| - `hooks` — commands run on `beforeTool`, `afterTool`, `sessionStart`, or | ||
| `sessionEnd` | ||
| - `prompts` and `skills` — additional prompt/skill files |
| MCP servers (`zero mcp`) and standalone markdown skills (`zero skills`) use | ||
| the same extension points and can also be wired up outside of a plugin | ||
| manifest. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
WalkthroughAdds README documentation for project and personal instruction injection, plugin manifest discovery, supported manifest fields, and the shared extension points used by MCP servers and skills. ChangesExtending Zero documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Vasanthdev2004
left a comment
Vasanthdev2004
left a comment
There was a problem hiding this comment.
Fact-checked the whole thing against the code, since that's what matters for docs — and it holds up. This one was clearly written from the source, not guessed:
- The
AGENTS.md/ZERO.md/.zero/AGENTS.mdchain, git-root-down-to-cwd with first-match-per-directory, general-to-specific, 8 KiB/file and 32 KiB total — all matchsystem_prompt.goexactly. - The manifest fields (
tools/hooks/prompts/skills, and toolcommand/args/inputSchema/permission) match the structs inplugins.go. - The hook events
beforeTool/afterTool/sessionStart/sessionEndare exactly the fourHookEventconstants. (The standalonezero hookssystem has a couple more, but those aren't manifest hooks, so scoping the plugin docs to these four is correct.) - The permission nuance is right, and it's the easy one to get wrong:
allowreally is clamped topromptunless manifest auto-approval was opted into at load time —toolSafety's comment says exactly that. - Discovery paths match:
<configHome>/zero/plugins(user) and<cwd>/.zero/plugins(project).
Two trivial things, take or leave: the project path is technically <cwd>/.zero/plugins, not the repo root — only matters if someone runs from a subdirectory — and ~/.config/zero/plugins is the Linux form of the user config dir (macOS/Windows differ). #475 just documented that same location as config.UserConfigDir()/zero, so matching that phrasing would keep the two consistent. Neither blocks.
Waiving the issue-approved gate here — this documents already-shipped features rather than proposing new work, so there's nothing for the issue-first policy to gate. CI's green.
Accurate and useful. Approving.
Add an "Extending Zero" section to the README covering the AGENTS.md/ZERO.md project-instructions lookup chain and the plugin.json manifest fields, neither of which were previously documented outside the source. Closes Gitlawb#521 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
- Correct project-scope plugin discovery to <cwd>/.zero/plugins, not the repo root. - Clarify that user-scope plugin discovery always resolves under ~/.config regardless of OS, separate from config.UserConfigDir() (which is OS-aware and used for the per-user ZERO.md file). - Document the per-user ZERO.md guidelines file added in Gitlawb#475. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
ad87f29 to
3de85f3
Compare
| the git root down to your current working directory (checked in that order | ||
| per directory). Files are injected general-to-specific, capped at 8 KiB per | ||
| file and 32 KiB total. |
| scope — `$XDG_CONFIG_HOME` or `~/.config` on every OS, independent of the | ||
| `config.UserConfigDir()` path used above) and `<cwd>/.zero/plugins/<name>/plugin.json` | ||
| (project scope — resolved from the current working directory, not the repo | ||
| root), and managed with `zero plugins`. A manifest can declare: | ||
|
|
| - `tools` — custom tools (`command`, `args`, `inputSchema`, and a | ||
| `permission` of `prompt` or `deny`; `allow` is honored only when manifest tool | ||
| auto-approval is enabled) |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
@coderabbitai please do a full code review approve if its all good |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
gh pr diff 522 --repo Gitlawb/zeroLength of output: 2025 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== Search for AGENTS.md / ZERO.md loading logic ==="
rg -n "AGENTS.md|ZERO.md" --type=go -g '!README.md' -C3 | head -150
echo "=== Search for size caps (8192, 32768, KiB) ==="
rg -n "8192|32768|8 \* 1024|32 \* 1024" --type=go -C3 | head -100
echo "=== Search for plugin.json discovery ==="
rg -n "plugin.json|plugins/" --type=go -C3 | head -150
echo "=== Search for UserConfigDir usage ==="
rg -n "UserConfigDir" --type=go -C3 | head -100Length of output: 840 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== repo root listing ==="
ls -la
echo "=== find files by name ==="
fd -i 'agents.md|zero.md|plugin.json' .
echo "=== detect language ==="
fd -e go | head -5
fd -e ts | head -5
fd -e py | head -5
fd -e rs | head -5Length of output: 2310 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== AGENTS.md / ZERO.md references in Go code ==="
rg -n "AGENTS\.md|ZERO\.md" --type=go -g '!README*' || true
echo "=== size cap constants ==="
rg -n "8192|32768|8\s*\*\s*1024|32\s*\*\s*1024|MaxFileSize|MaxTotal" --type=go || true
echo "=== plugin.json ==="
rg -n "plugin\.json" --type=go || true
echo "=== UserConfigDir ==="
rg -n "UserConfigDir" --type=go || true
echo "=== plugins dir discovery ==="
rg -n '\.zero/plugins|config/zero/plugins' --type=go || trueLength of output: 694 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "--- test rg basic ---"
rg -n "package main" --type=go internal | head -5
echo "--- search AGENTS ---"
rg -n "AGENTS" -g '*.go' .
echo "--- search plugin.json in whole repo ---"
rg -n "plugin.json" .
echo "--- search ZERO.md in whole repo excluding README ---"
rg -n "ZERO.md" . -g '!README*'Length of output: 23875 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "=== system_prompt.go relevant section ==="
sed -n '1,120p' internal/agent/system_prompt.go
echo "=== size caps in system_prompt.go ==="
rg -n "8192|8\*1024|8 \* 1024|32768|32\*1024|32 \* 1024|maxBytes|MaxBytes|cap" internal/agent/system_prompt.go
echo "=== plugins.go discovery paths ==="
sed -n '1,60p' internal/plugins/plugins.go
echo "---"
rg -n "UserConfigDir|\.zero/plugins|func.*[Dd]iscover|func.*[Ll]oad" internal/plugins/plugins.goLength of output: 7698 🏁 Script executed: #!/bin/bash
set -euo pipefail
rg -n "SourceUser|SourceProject|plugins.*Root|Roots\s*:=|UserConfigDir" internal/cli --type=go -C2 | grep -i plugin -A2 -B2 | head -100
echo "---direct search---"
rg -n '\.zero.plugins|config.*plugins|plugins.*dir' internal/cli/*.go -i | head -50Length of output: 9882 🏁 Script executed: #!/bin/bash
set -euo pipefail
rg -n "func ResolveRoots" -A 40 internal/plugins/*.goLength of output: 2756 All content in the new README section checks out against the implementation.
This is a doc-only change (+33/-0) with no code touched, so no correctness/safety/test-coverage risk. Nice work — approving. [approve] |
Summary
README.mddocumenting theAGENTS.md/ZERO.md/.zero/AGENTS.mdproject-instructions lookup chain (git root → cwd, 8 KiB/file, 32 KiB total)plugin.jsonmanifest fields (tools,hooks,prompts,skills) and the two discovery paths (~/.config/zero/plugins/*/plugin.json,<repo>/.zero/plugins/*/plugin.json)Closes #521
Test plan
internal/agent/system_prompt.goandinternal/plugins/plugins.goSummary by CodeRabbit
ZERO.mdthat applies across workspaces.