feat(.zeus): conventions spec — skills, memory, policy, mcp.json#23
Conversation
…json This PR introduces the `.zeus/` project-local AI configuration convention. Everything in this directory is meant to be checked into git so the team shares one set of AI behaviours, not per-developer settings. Layout: - `.zeus/skills/*.md` team-shared AI behaviours (Claude Code skill shape) - `.zeus/memory/` persistent project context - `.zeus/policy.md` constitutional rules (hard / soft) - `.zeus/mcp.json` MCP servers to connect to This PR ships only the directory, sample files, and the format spec at `docs/zeus-conventions.md`. Loaders for skills / memory / policy land in the agent SDK PR; the MCP servers list is consumed by the MCP client PR.
|
Warning Review limit reached
Your plan currently allows 1 review/hour. Refill in 8 minutes and 9 seconds. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more review capacity refills, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughAdds initial Zeus workspace artifacts: ChangesZeus Workspace Configuration and Conventions
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the .zeus/ configuration framework, establishing a standardized structure for AI skills, persistent memory, project policies, and MCP server definitions. It includes a comprehensive conventions document to ensure consistent AI behavior across the team. Review feedback focused on improving documentation clarity and consistency, specifically suggesting the addition of concrete examples for production URL patterns, aligning secret-scanning patterns between the documentation and example files, and refining the allowed-tools specification to clearly distinguish between allowing all tools versus none.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
.zeus/policy.md (1)
10-10: ⚡ Quick winConsider adding pattern examples for "production URLs".
The conventions doc (line 71) shows specific patterns like
*.prod.*andapp.example.comto clarify what constitutes a "production URL." Without examples, this rule may be interpreted inconsistently across different projects.📋 Proposed enhancement
-- Do not call write APIs against production URLs unless the user explicitly opts in for the session. +- Do not call write APIs against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session.🤖 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 @.zeus/policy.md at line 10, Update the rule "Do not call write APIs against production URLs unless the user explicitly opts in for the session" to include concrete pattern examples for what counts as a production URL (e.g., wildcard patterns and explicit hostnames). Edit .zeus/policy.md near that sentence to append examples such as "*.prod.*", "prod.example.com", "app.example.com", and "10.0.0.0/8" or similar network/hostname patterns used by your org so readers have clear, actionable patterns to match.docs/zeus-conventions.md (1)
108-108: ⚡ Quick winClarify what qualifies as "non-secret config" in
envblocks.The statement "Plain values in
envblocks are still allowed for non-secret config" might lead to confusion about what should vs. shouldn't be stored in plain text. Consider adding an example of acceptable non-secret config (e.g.,"LOG_LEVEL": "debug") to guide users.🤖 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 `@docs/zeus-conventions.md` at line 108, Clarify the phrase "non-secret config" by adding a short definition and an example: state that non-secret values are those safe for public repos (e.g., service behavior flags, log levels, feature toggles) and provide an explicit example such as `"LOG_LEVEL": "debug"` alongside the existing rule about secrets using `${env:NAME}`; update the sentence containing `Secrets are referenced via \`${env:NAME}\`` and the mention of `env` blocks to include this definition and the example so readers know what may be stored in plain text in mcp.json.
🤖 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 @.zeus/skills/example-secret-scan.md:
- Line 11: The AWS access key regex "AKIA[0-9A-Z]{16}" only matches AKIA keys;
update the pattern to include ASIA temporary credentials by replacing that token
with a combined pattern like "(AKIA|ASIA)[A-Z0-9]{16}" and optionally wrap with
word boundaries \b...\b to avoid partial matches; search for the literal
"AKIA[0-9A-Z]{16}" in the markdown and substitute it with the new pattern.
- Line 13: Update the GitHub token pattern currently shown as
"ghp_[0-9a-zA-Z]{36}" to a broader regex that includes the other current
prefixes (e.g. github_pat_, gho_, ghu_, ghs_, ghr_) and does not assume a single
fixed-length suffix; replace the literal pattern "ghp_[0-9a-zA-Z]{36}" in
.zeus/skills/example-secret-scan.md with a combined prefix alternation and a
more permissive token body (allowing alphanumeric/underscore/hyphen and a
reasonable minimum length) so the scan matches classic PATs, fine-grained PATs,
OAuth/app tokens and refresh tokens.
In `@docs/zeus-conventions.md`:
- Line 48: Clarify the allowed-tools format by updating the docs: state that
allowed-tools is a comma-separated list that may include optional spaces after
commas (format: "tool1,tool2" or "tool1, tool2"), update the example
`buffer_get, search_workspace` to match this wording, and add a note that
implementations/parsers should trim whitespace when splitting on commas;
reference the `allowed-tools` key and the example value `buffer_get,
search_workspace` so maintainers can find and normalize other examples to the
same convention.
- Around line 110-115: Update the "Reload behaviour" section in
docs/zeus-conventions.md to reflect the current implementation: replace the
claim that the entire .zeus/ tree is read and that edits under .zeus/ trigger
incremental reloads with a note that currently only the MCP dev watcher
(implemented in mcpConfiguration.ts and mcpDevMode.ts via dev.watch) restarts
MCP servers on matching file changes, and explicitly state that incremental
reloads of skills/memory/policy and selective .zeus/mcp.json-driven MCP restarts
are not yet implemented (or link to the follow-up PRs that will add this
behavior).
---
Nitpick comments:
In @.zeus/policy.md:
- Line 10: Update the rule "Do not call write APIs against production URLs
unless the user explicitly opts in for the session" to include concrete pattern
examples for what counts as a production URL (e.g., wildcard patterns and
explicit hostnames). Edit .zeus/policy.md near that sentence to append examples
such as "*.prod.*", "prod.example.com", "app.example.com", and "10.0.0.0/8" or
similar network/hostname patterns used by your org so readers have clear,
actionable patterns to match.
In `@docs/zeus-conventions.md`:
- Line 108: Clarify the phrase "non-secret config" by adding a short definition
and an example: state that non-secret values are those safe for public repos
(e.g., service behavior flags, log levels, feature toggles) and provide an
explicit example such as `"LOG_LEVEL": "debug"` alongside the existing rule
about secrets using `${env:NAME}`; update the sentence containing `Secrets are
referenced via \`${env:NAME}\`` and the mention of `env` blocks to include this
definition and the example so readers know what may be stored in plain text in
mcp.json.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 09cc5d37-aa27-4a8d-b39b-7d4b7499b003
📒 Files selected for processing (5)
.zeus/mcp.json.zeus/memory/README.md.zeus/policy.md.zeus/skills/example-secret-scan.mddocs/zeus-conventions.md
- .zeus/policy.md: add concrete patterns for production URLs - docs/zeus-conventions.md secret-scan list: include AWS ASIA prefix, expanded GitHub token prefix set (ghp_/gho_/ghu_/ghs_/ghr_/github_pat_), add *_TOKEN to vars - docs/zeus-conventions.md allowed-tools: clarify omitted (all allowed) vs present-but-empty (none allowed) - .zeus/skills/example-secret-scan.md: mirror the conventions doc
…implemented CodeRabbit caught that the 'Reload behaviour' section described incremental reloads of .zeus/ files but no implementation exists in this PR. Reframe as the planned target for feat/mcp-client and feat/agent-sdk, and call out the closest existing piece (MCP dev.watch in mcpConfiguration.ts / mcpDevMode.ts) so future readers can locate the moving parts. This PR continues to ship the on-disk format only — no loaders, no watchers.
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces the .zeus/ directory structure and documentation to define project-local AI behaviors, persistent memory, and security policies. The feedback focuses on strengthening security by defaulting allowed-tools to none for skills to follow the principle of least privilege, ensuring consistency between the policy file and its documentation, and including git push --force-with-lease as a destructive action requiring user confirmation.
- policy.md + conventions.md sample: add 'git push --force-with-lease' to the list of irreversible actions requiring confirmation. --force-with-lease is the 'safer' force-push but still rewrites remote history; treat it the same as --force for refusal-grade intent. - conventions.md: sync the policy sample block with .zeus/policy.md word-for-word so the doc and the shipped file don't drift. - allowed-tools default: flip from 'omitted = all tools' to 'omitted = no tools' (least-privilege). Explicit '*' to opt into everything; matches a principle-of-least-privilege security posture for the AI tool surface.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/zeus-conventions.md (1)
48-48: 💤 Low valueConsider clarifying the
allowed-toolsformat specification.The spec states "comma-separated list" but all examples use comma-space format (
buffer_get, search_workspace). For a format specification, explicitly stating whether spaces after commas are optional, required, or forbidden would prevent parser implementation inconsistencies.📝 Suggested clarification
-allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. +allowed-tools` (optional): comma-separated list of MCP tool names this skill may call (spaces after commas are optional and should be trimmed by parsers).🤖 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 `@docs/zeus-conventions.md` at line 48, Update the `allowed-tools` spec to explicitly state the comma separator rules: clarify whether spaces after commas are optional, required, or disallowed and provide canonical examples; mention that tool names are matched exactly and that parsers should trim surrounding whitespace (or not) accordingly so implementations of `allowed-tools` treat "buffer_get,search_workspace", "buffer_get, search_workspace", and "buffer_get , search_workspace" in the documented, unambiguous way; include one explicit allowed example and one explicit disallowed example to remove ambiguity.
🤖 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.
Nitpick comments:
In `@docs/zeus-conventions.md`:
- Line 48: Update the `allowed-tools` spec to explicitly state the comma
separator rules: clarify whether spaces after commas are optional, required, or
disallowed and provide canonical examples; mention that tool names are matched
exactly and that parsers should trim surrounding whitespace (or not) accordingly
so implementations of `allowed-tools` treat "buffer_get,search_workspace",
"buffer_get, search_workspace", and "buffer_get , search_workspace" in the
documented, unambiguous way; include one explicit allowed example and one
explicit disallowed example to remove ambiguity.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4ebb8e38-dd36-43bb-8ddd-c059a7e36d30
📒 Files selected for processing (3)
.zeus/policy.md.zeus/skills/example-secret-scan.mddocs/zeus-conventions.md
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request establishes the .zeus/ configuration directory structure, introducing foundational files for MCP server definitions, persistent AI memory, behavioral policies, and example skills. It also includes a detailed conventions document. Feedback focused on improving documentation accuracy by updating a placeholder link to the new conventions file and ensuring the directory layout example matches the actual filenames used in the PR.
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces the .zeus/ configuration directory and associated documentation to define project-local AI behaviors, including skills, persistent memory, and safety policies. Feedback suggests expanding the list of destructive actions to include git reset --hard, clarifying write APIs with specific HTTP methods in the policy file, and adding a security warning regarding the use of wildcards for tool permissions in the documentation.
…on allowed-tools '*'
This PR reserves the workbench slot at 'src/vs/workbench/contrib/mcpClient/' and lays out the design in 'docs/zeus-mcp-client.md'. When the implementation lands it will: - read '.zeus/mcp.json' from the workspace root - spawn stdio servers and open SSE connections - aggregate tool definitions for the agent runtime - reload on config change without restarting unaffected servers Depends on 'feat/zeus-conventions' (#23) for the '.zeus/mcp.json' schema. Implementation depends on '@modelcontextprotocol/sdk', which lands with the agent SDK PR.
1 participant
Goal
Introduce `.zeus/` project-local AI configuration. Everything in this directory is checked into git so the team shares one set of AI behaviours, not per-developer settings. This is the foundation that subsequent feature PRs (`feat/mcp-server`, `feat/mcp-client`, `feat/agent-sdk`, `feat/parallel-agents-ui`, `feat/prompt-cache-hud`) consume.
Scope
Not in this PR: loaders, MCP wiring, agent SDK integration. Those live in their own PRs.
Acceptance criteria
Open questions
This is part of the MCP-first vision pivot. See `zeus-internal/VISION.md` and `zeus-internal/ARCHITECTURE.md`.
Summary by CodeRabbit
Documentation
Chores