From 86efce1b6bb5a708b68e241dabdf991e1ac61914 Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 20:04:48 +0900 Subject: [PATCH 1/6] feat(.zeus): add conventions spec, sample skill, memory, policy, mcp.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. --- .zeus/mcp.json | 4 + .zeus/memory/README.md | 15 ++++ .zeus/policy.md | 14 ++++ .zeus/skills/example-secret-scan.md | 16 ++++ docs/zeus-conventions.md | 120 ++++++++++++++++++++++++++++ 5 files changed, 169 insertions(+) create mode 100644 .zeus/mcp.json create mode 100644 .zeus/memory/README.md create mode 100644 .zeus/policy.md create mode 100644 .zeus/skills/example-secret-scan.md create mode 100644 docs/zeus-conventions.md diff --git a/.zeus/mcp.json b/.zeus/mcp.json new file mode 100644 index 00000000..cbb8aead --- /dev/null +++ b/.zeus/mcp.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://zeus.dev/schemas/mcp.json", + "servers": {} +} diff --git a/.zeus/memory/README.md b/.zeus/memory/README.md new file mode 100644 index 00000000..fe38dd09 --- /dev/null +++ b/.zeus/memory/README.md @@ -0,0 +1,15 @@ +# Project memory + +Persistent context Zeus injects at the start of every AI session. This is the entry point — keep it short and link out to other files in `.zeus/memory/` for detail. + +Anything in this directory is shared with the project's AI. Treat it like documentation that the model reads, not a secrets store. + +## Quick orientation + +- **What this project is**: (one or two sentences) +- **Where to start reading the code**: (a path or two) +- **Conventions worth knowing**: (link to `conventions.md` if you make one) + +## Recent decisions + +Link to ADR-style notes in `decisions/` here, newest first. diff --git a/.zeus/policy.md b/.zeus/policy.md new file mode 100644 index 00000000..e68c6953 --- /dev/null +++ b/.zeus/policy.md @@ -0,0 +1,14 @@ +# Zeus policy for this project + +Constitutional rules Zeus injects into every AI call as system context. Hard rules are refusal-grade; soft preferences are style guidance. + +## Hard rules + +- Never write secrets, tokens, or passwords back into a buffer. +- Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, or any destructive irreversible action. +- Do not auto-run database migrations. Generating them is fine; applying them requires explicit user approval. +- Do not call write APIs against production URLs unless the user explicitly opts in for the session. + +## Soft preferences + +- (replace with your project's style preferences) diff --git a/.zeus/skills/example-secret-scan.md b/.zeus/skills/example-secret-scan.md new file mode 100644 index 00000000..a614e111 --- /dev/null +++ b/.zeus/skills/example-secret-scan.md @@ -0,0 +1,16 @@ +--- +name: secret-scan +description: Scan the buffer for secrets and propose .env.example replacements +allowed-tools: buffer_get, search_workspace +--- + +This is an example skill. Delete or replace as you set up `.zeus/` for your own project. + +Scan recent edits for: + +- AWS access keys (`AKIA[0-9A-Z]{16}`) +- Private key headers (`-----BEGIN.*PRIVATE KEY-----`) +- GitHub tokens (`ghp_[0-9a-zA-Z]{36}`) +- Long alphanumeric values assigned to `*_KEY` / `*_SECRET` / `*_TOKEN` variables + +When something matches, annotate the line and propose a `.env.example` placeholder. diff --git a/docs/zeus-conventions.md b/docs/zeus-conventions.md new file mode 100644 index 00000000..b7f11203 --- /dev/null +++ b/docs/zeus-conventions.md @@ -0,0 +1,120 @@ +# `.zeus/` conventions + +Zeus reads project-local AI configuration from `.zeus/` at the workspace root. Everything in this directory is meant to be checked into git so the team shares one set of AI behaviours, not per-developer settings. + +This document is the format spec. Implementation lands in [`feat/mcp-client`](https://github.com/0-draft/zeus/pulls?q=is%3Apr+head%3Afeat/mcp-client) and the agent SDK PR. + +## Directory layout + +```text +.zeus/ +├── skills/ # team-shared AI behaviours +│ ├── secret-scan.md +│ └── commit-msg.md +├── memory/ # persistent project context +│ ├── README.md +│ ├── architecture.md +│ └── decisions/ +│ └── 0001-mcp-first.md +├── policy.md # constitutional rules (hard / soft) +└── mcp.json # MCP servers to connect to +``` + +## `.zeus/skills/*.md` + +Skill files share the same shape as Claude Code skills: a frontmatter block, then prose that becomes the skill's system prompt. + +```markdown +--- +name: secret-scan +description: Scan the buffer for secrets and propose .env.example replacements +allowed-tools: buffer_get, search_workspace +--- + +Scan recent edits for: + +- AWS access keys (`AKIA[0-9A-Z]{16}`) +- Private key headers (`-----BEGIN.*PRIVATE KEY-----`) +- GitHub tokens (`ghp_[0-9a-zA-Z]{36}`) +- Long alphanumeric values assigned to `*_KEY` / `*_SECRET` variables + +When something matches, annotate the line and propose a `.env.example` placeholder. +``` + +Frontmatter fields: + +- `name` (required): unique identifier within `.zeus/skills/`. Duplicates fail loading. +- `description` (required): one-line summary used by the model to decide when to invoke the skill. +- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. Empty means all. + +## `.zeus/memory/` + +Persistent context that survives across sessions and developers. + +- `README.md`: the entry point. Always injected at the start of an AI session. +- Free-form markdown files alongside: architecture notes, conventions, ADRs. + +The AI may propose writes to memory via a diff that the user reviews. Manual edits are encouraged. + +## `.zeus/policy.md` + +Constitutional rules. Two sections: + +```markdown +# Zeus policy for this project + +## Hard rules + +- Never write secrets or tokens back into a buffer. +- Confirm before `rm -rf`, `DROP TABLE`, or `git push --force`. +- Do not auto-run database migrations; generate them, ask before applying. +- Do not call write APIs against production URLs (`*.prod.*`, `app.example.com`). + +## Soft preferences + +- Imports are alphabetical. +- TypeScript function return types are explicit. +- Prefer `Result` over throwing. +``` + +Hard rules become refusal-grade constraints. Soft preferences become style guidance. + +## `.zeus/mcp.json` + +MCP servers to connect to. Same shape as Claude Code's `mcp.json` for compatibility: + +```json +{ + "$schema": "https://zeus.dev/schemas/mcp.json", + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" } + }, + "postgres-staging": { + "command": "uvx", + "args": ["mcp-server-postgres"], + "env": { "POSTGRES_URL": "${env:POSTGRES_STAGING_URL}" } + }, + "linear": { + "transport": "sse", + "url": "https://mcp.linear.app/sse" + } + } +} +``` + +Secrets are referenced via `${env:NAME}` only. Plain values in `env` blocks are still allowed for non-secret config, but `mcp.json` is meant to live in git so don't commit secrets there. + +## Reload behaviour + +- On Zeus start, the entire `.zeus/` tree is read. +- Editing any file under `.zeus/` triggers an incremental reload of the affected piece (skill / memory / policy / mcp.json). +- `mcp.json` reload restarts only the affected MCP server connections, not all of them. + +## Open questions + +- Should `.zeus/skills/` allow nested directories (e.g., `skills/team-a/`)? Default: no, keep flat for simplicity. +- Symlinks: support or refuse? Default: refuse, to keep behaviour predictable across OSes. +- Per-user override layer (`~/.config/zeus/`) — separate spec, not part of this PR. From 5d3cd07e4589c0cf865e7a4f67105203416626c7 Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 21:11:31 +0900 Subject: [PATCH 2/6] docs(zeus-conventions): address review feedback - .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 --- .zeus/policy.md | 2 +- .zeus/skills/example-secret-scan.md | 4 ++-- docs/zeus-conventions.md | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.zeus/policy.md b/.zeus/policy.md index e68c6953..56c058e3 100644 --- a/.zeus/policy.md +++ b/.zeus/policy.md @@ -7,7 +7,7 @@ Constitutional rules Zeus injects into every AI call as system context. Hard rul - Never write secrets, tokens, or passwords back into a buffer. - Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, or any destructive irreversible action. - Do not auto-run database migrations. Generating them is fine; applying them requires explicit user approval. -- 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. ## Soft preferences diff --git a/.zeus/skills/example-secret-scan.md b/.zeus/skills/example-secret-scan.md index a614e111..f651e440 100644 --- a/.zeus/skills/example-secret-scan.md +++ b/.zeus/skills/example-secret-scan.md @@ -8,9 +8,9 @@ This is an example skill. Delete or replace as you set up `.zeus/` for your own Scan recent edits for: -- AWS access keys (`AKIA[0-9A-Z]{16}`) +- AWS access keys (`\b(AKIA|ASIA)[A-Z0-9]{16}\b`) - Private key headers (`-----BEGIN.*PRIVATE KEY-----`) -- GitHub tokens (`ghp_[0-9a-zA-Z]{36}`) +- GitHub tokens (prefixes `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_`) - Long alphanumeric values assigned to `*_KEY` / `*_SECRET` / `*_TOKEN` variables When something matches, annotate the line and propose a `.env.example` placeholder. diff --git a/docs/zeus-conventions.md b/docs/zeus-conventions.md index b7f11203..3dd53511 100644 --- a/docs/zeus-conventions.md +++ b/docs/zeus-conventions.md @@ -33,10 +33,10 @@ allowed-tools: buffer_get, search_workspace Scan recent edits for: -- AWS access keys (`AKIA[0-9A-Z]{16}`) +- AWS access keys (`\b(AKIA|ASIA)[A-Z0-9]{16}\b`) - Private key headers (`-----BEGIN.*PRIVATE KEY-----`) -- GitHub tokens (`ghp_[0-9a-zA-Z]{36}`) -- Long alphanumeric values assigned to `*_KEY` / `*_SECRET` variables +- GitHub tokens (prefixes `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_`) +- Long alphanumeric values assigned to `*_KEY` / `*_SECRET` / `*_TOKEN` variables When something matches, annotate the line and propose a `.env.example` placeholder. ``` @@ -45,7 +45,7 @@ Frontmatter fields: - `name` (required): unique identifier within `.zeus/skills/`. Duplicates fail loading. - `description` (required): one-line summary used by the model to decide when to invoke the skill. -- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. Empty means all. +- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. **Omitted** = all tools allowed; **present but empty** = no tools allowed. ## `.zeus/memory/` From 145f0f0c01a00f77b24b4bc42205cfaad4285e1c Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 23:18:39 +0900 Subject: [PATCH 3/6] docs(zeus-conventions): clarify reload behaviour is target spec, not implemented MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/zeus-conventions.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/zeus-conventions.md b/docs/zeus-conventions.md index 3dd53511..205c200c 100644 --- a/docs/zeus-conventions.md +++ b/docs/zeus-conventions.md @@ -107,12 +107,18 @@ MCP servers to connect to. Same shape as Claude Code's `mcp.json` for compatibil Secrets are referenced via `${env:NAME}` only. Plain values in `env` blocks are still allowed for non-secret config, but `mcp.json` is meant to live in git so don't commit secrets there. -## Reload behaviour +## Reload behaviour (planned) + +This is the target behaviour for the loaders in [`feat/mcp-client`](https://github.com/0-draft/zeus/pulls?q=is%3Apr+head%3Afeat/mcp-client) and [`feat/agent-sdk`](https://github.com/0-draft/zeus/pulls?q=is%3Apr+head%3Afeat/agent-sdk). **None of it is implemented in this PR**; this PR ships the on-disk format only. + +What we plan to ship: - On Zeus start, the entire `.zeus/` tree is read. - Editing any file under `.zeus/` triggers an incremental reload of the affected piece (skill / memory / policy / mcp.json). - `mcp.json` reload restarts only the affected MCP server connections, not all of them. +The closest existing piece in the inherited vscode codebase is the MCP `dev.watch` restart logic in `src/vs/workbench/contrib/mcp/common/mcpConfiguration.ts` and `mcpDevMode.ts`. That watches arbitrary file globs declared per-server, not `.zeus/mcp.json` itself. Zeus's reload spec sits one layer above it. + ## Open questions - Should `.zeus/skills/` allow nested directories (e.g., `skills/team-a/`)? Default: no, keep flat for simplicity. From e728e299010ecc6e75d4b11a066a2d0d4cadab9f Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 23:31:30 +0900 Subject: [PATCH 4/6] docs(zeus-conventions): tighten policy + least-privilege allowed-tools - 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. --- .zeus/policy.md | 2 +- docs/zeus-conventions.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.zeus/policy.md b/.zeus/policy.md index 56c058e3..626bc19d 100644 --- a/.zeus/policy.md +++ b/.zeus/policy.md @@ -5,7 +5,7 @@ Constitutional rules Zeus injects into every AI call as system context. Hard rul ## Hard rules - Never write secrets, tokens, or passwords back into a buffer. -- Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, or any destructive irreversible action. +- Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, `git push --force-with-lease`, or any destructive irreversible action. - Do not auto-run database migrations. Generating them is fine; applying them requires explicit user approval. - Do not call write APIs against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session. diff --git a/docs/zeus-conventions.md b/docs/zeus-conventions.md index 205c200c..197e58f9 100644 --- a/docs/zeus-conventions.md +++ b/docs/zeus-conventions.md @@ -45,7 +45,7 @@ Frontmatter fields: - `name` (required): unique identifier within `.zeus/skills/`. Duplicates fail loading. - `description` (required): one-line summary used by the model to decide when to invoke the skill. -- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. **Omitted** = all tools allowed; **present but empty** = no tools allowed. +- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. **Omitted** = no tools allowed (least-privilege default — the skill is read-only unless it explicitly opts in); **present but empty** = also no tools allowed; **present with names** = exactly those tools. Use `'*'` to mean "all tools" if you really want that. ## `.zeus/memory/` @@ -65,10 +65,10 @@ Constitutional rules. Two sections: ## Hard rules -- Never write secrets or tokens back into a buffer. -- Confirm before `rm -rf`, `DROP TABLE`, or `git push --force`. -- Do not auto-run database migrations; generate them, ask before applying. -- Do not call write APIs against production URLs (`*.prod.*`, `app.example.com`). +- Never write secrets, tokens, or passwords back into a buffer. +- Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, `git push --force-with-lease`, or any destructive irreversible action. +- Do not auto-run database migrations. Generating them is fine; applying them requires explicit user approval. +- Do not call write APIs against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session. ## Soft preferences From 94e5d03094de70a676ddd67602fbcb608df09d10 Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 23:59:06 +0900 Subject: [PATCH 5/6] docs(.zeus): wire memory/README to conventions, fix example filename in layout --- .zeus/memory/README.md | 2 +- docs/zeus-conventions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.zeus/memory/README.md b/.zeus/memory/README.md index fe38dd09..08e9b25f 100644 --- a/.zeus/memory/README.md +++ b/.zeus/memory/README.md @@ -8,7 +8,7 @@ Anything in this directory is shared with the project's AI. Treat it like docume - **What this project is**: (one or two sentences) - **Where to start reading the code**: (a path or two) -- **Conventions worth knowing**: (link to `conventions.md` if you make one) +- **Conventions worth knowing**: [`docs/zeus-conventions.md`](../../docs/zeus-conventions.md) ## Recent decisions diff --git a/docs/zeus-conventions.md b/docs/zeus-conventions.md index 197e58f9..e9da2de9 100644 --- a/docs/zeus-conventions.md +++ b/docs/zeus-conventions.md @@ -9,7 +9,7 @@ This document is the format spec. Implementation lands in [`feat/mcp-client`](ht ```text .zeus/ ├── skills/ # team-shared AI behaviours -│ ├── secret-scan.md +│ ├── example-secret-scan.md │ └── commit-msg.md ├── memory/ # persistent project context │ ├── README.md From 51d5a3614a825fa2da1c07c7bd66e91a96e78a89 Mon Sep 17 00:00:00 2001 From: kanywst Date: Mon, 25 May 2026 00:23:21 +0900 Subject: [PATCH 6/6] docs(policy): add git reset --hard, list POST/PUT/PATCH/DELETE, warn on allowed-tools '*' --- .zeus/policy.md | 4 ++-- docs/zeus-conventions.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.zeus/policy.md b/.zeus/policy.md index 626bc19d..3d37ec3f 100644 --- a/.zeus/policy.md +++ b/.zeus/policy.md @@ -5,9 +5,9 @@ Constitutional rules Zeus injects into every AI call as system context. Hard rul ## Hard rules - Never write secrets, tokens, or passwords back into a buffer. -- Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, `git push --force-with-lease`, or any destructive irreversible action. +- Confirm before `rm -rf`, `DROP TABLE`, `git reset --hard`, `git push --force`, `git push --force-with-lease`, or any destructive irreversible action. - Do not auto-run database migrations. Generating them is fine; applying them requires explicit user approval. -- Do not call write APIs against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session. +- Do not call write APIs (`POST`, `PUT`, `PATCH`, `DELETE`) against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session. ## Soft preferences diff --git a/docs/zeus-conventions.md b/docs/zeus-conventions.md index e9da2de9..816f73a0 100644 --- a/docs/zeus-conventions.md +++ b/docs/zeus-conventions.md @@ -45,7 +45,7 @@ Frontmatter fields: - `name` (required): unique identifier within `.zeus/skills/`. Duplicates fail loading. - `description` (required): one-line summary used by the model to decide when to invoke the skill. -- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. **Omitted** = no tools allowed (least-privilege default — the skill is read-only unless it explicitly opts in); **present but empty** = also no tools allowed; **present with names** = exactly those tools. Use `'*'` to mean "all tools" if you really want that. +- `allowed-tools` (optional): comma-separated list of MCP tool names this skill may call. **Omitted** = no tools allowed (least-privilege default — the skill is read-only unless it explicitly opts in); **present but empty** = also no tools allowed; **present with names** = exactly those tools. A literal `'*'` is **discouraged**: it bypasses the least-privilege guarantee and the loader logs a warning at startup naming each skill that uses it. Prefer listing the tools by name; use `'*'` only for skills you are sure should be able to call anything Zeus can. ## `.zeus/memory/` @@ -66,9 +66,9 @@ Constitutional rules. Two sections: ## Hard rules - Never write secrets, tokens, or passwords back into a buffer. -- Confirm before `rm -rf`, `DROP TABLE`, `git push --force`, `git push --force-with-lease`, or any destructive irreversible action. +- Confirm before `rm -rf`, `DROP TABLE`, `git reset --hard`, `git push --force`, `git push --force-with-lease`, or any destructive irreversible action. - Do not auto-run database migrations. Generating them is fine; applying them requires explicit user approval. -- Do not call write APIs against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session. +- Do not call write APIs (`POST`, `PUT`, `PATCH`, `DELETE`) against production URLs (e.g., `*.prod.*`, `app.example.com`) unless the user explicitly opts in for the session. ## Soft preferences