From 7b1d2a5cf2f694d999a37f93dd5363baa865ef00 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Fri, 22 May 2026 02:27:18 +0100 Subject: [PATCH 1/2] docs: add ADR 0006, instruction-update runbook, and MCP-plugin instructions --- .../instructions/mcp-plugins.instructions.md | 64 +++++++++++++++++++ .../0006-wiki-content-root-boundaries.md | 40 ++++++++++++ runbooks/instruction-update.md | 54 ++++++++++++++++ 3 files changed, 158 insertions(+) create mode 100644 .github/instructions/mcp-plugins.instructions.md create mode 100644 decisions/0006-wiki-content-root-boundaries.md create mode 100644 runbooks/instruction-update.md diff --git a/.github/instructions/mcp-plugins.instructions.md b/.github/instructions/mcp-plugins.instructions.md new file mode 100644 index 000000000..290f46d40 --- /dev/null +++ b/.github/instructions/mcp-plugins.instructions.md @@ -0,0 +1,64 @@ +--- +description: "When and how to use the project MCP plugins (Context7, Supabase, Cloudflare, Greptile) and Claude Code toolkits (pr-review-toolkit, hookify, security-guidance) across the Z-Shell workspace." +applyTo: "**" +--- + +# Project MCP Plugins + +Guidance for the MCP servers and Claude Code plugins enabled in the Z-Shell +maintainer workspace. Prefer these over guesswork or generic web search. + +## General rules + +- Prefer Context7 over web search for any library, framework, or API documentation. +- Treat every OAuth-gated plugin (Supabase, Cloudflare, Greptile) as touching a + **live external service**. Read-only by default; confirm with the user before + any write, deploy, secret change, or other outward-facing action. +- GitHub, the wiki, and the Z-Shell Tracker remain the source of truth. Record + plugin-derived findings in PRs and issues, not only in local agent memory. + +## Context7 (no auth) + +- **Purpose:** current docs and code examples for libraries and frameworks + (Docusaurus, Supabase JS, React, wrangler, etc.). +- **When to use:** before assuming API or config behavior; version migrations; + setup and CLI usage questions. +- **When NOT to use:** business-logic debugging, refactoring, or general + programming concepts. + +## Supabase (OAuth) + +- **Purpose:** the live Z-Shell wiki Supabase project — database, migrations, + Edge Functions, secrets, analytics. +- **When to use:** verify Edge Function env/secret names (e.g. `SB_SECRET_KEY`), + inspect schema and migrations, check the knowledge-search index. +- **When NOT to use:** never run destructive SQL or write/rotate secrets without + explicit user confirmation. Supabase stores only derived embeddings and + metadata; GitHub and the wiki are canonical. +- **Auth required:** yes (OAuth; the granted scope is broad — stay read-only by + default and confirm before any write). + +## Cloudflare (OAuth) + +- **Purpose:** Pages, Workers, R2, and observability for the wiki, which + continuously deploys from `main`. +- **When to use:** verify Pages deployments, inspect logs, R2 work (see the + `wiki-r2-proxy` spec), and debug Pages Functions. +- **When NOT to use:** no production deploys or binding changes without + confirmation. +- **Auth required:** yes (OAuth). + +## Greptile (OAuth) + +- **Purpose:** semantic code search across the **multi-repo** workspace. +- **When to use:** cross-repo reference scans before moves or renames; locating + patterns that span repositories. +- **When NOT to use:** single-file lookups where local grep or Read is faster. +- **Auth required:** yes (OAuth). Read-only. + +## Claude Code toolkits + +- **pr-review-toolkit:** reviewer, silent-failure, type-design, test, and + comment subagents. Run on a diff before requesting human review. +- **hookify:** generate Claude Code hooks from recurring conversation mistakes. +- **security-guidance:** security review of pending changes before merge. diff --git a/decisions/0006-wiki-content-root-boundaries.md b/decisions/0006-wiki-content-root-boundaries.md new file mode 100644 index 000000000..77b7aa11c --- /dev/null +++ b/decisions/0006-wiki-content-root-boundaries.md @@ -0,0 +1,40 @@ +# 6. Wiki Content-Root Boundaries + +- **Status:** PROPOSED +- **Date:** 2026-05-22 +- **Deciders:** ss-o, Claude Code +- **Supersedes:** None +- **Superseded by:** None + +## Context + +The Docusaurus wiki (`z-shell/wiki`) has three independent content roots — `docs/`, `community/`, and `ecosystem/`. The wiki `AGENTS.md` described `docs/` only as "core documentation, getting started, guides", which is ambiguous: it does not distinguish Zi end-user documentation from maintainer or operational content. + +That ambiguity caused a concrete failure. A maintainer guide (Supabase Knowledge Search) was placed under `docs/maintainers/`, then half-moved to `community/`, leaving a divergent duplicate. The `community/` copy was untracked and carried stale secret-key naming (`SUPABASE_SERVICE_ROLE_KEY`), while the canonical `docs/` copy matched the code (`SB_SECRET_KEY` / `SUPABASE_SECRET_KEY`). A literal "move" would have shipped the stale naming. + +## Decision + +The three content roots have fixed, non-overlapping scopes: + +1. `docs/` is **Zi plugin-manager user documentation only** — installation, commands, usage guides. No maintainer, operational, or infrastructure guides. +2. `community/` holds Z-Shell ecosystem community content (contributing, the Zsh handbook/plugin standard, ZUnit) and **maintainer / operational tooling guides** (e.g. `community/10_maintainers/`). +3. `ecosystem/` holds the third-party catalog: annexes, packages, plugins. + +These boundaries are recorded in the wiki `AGENTS.md` (with `CLAUDE.md` as a symlink to it) and the wiki authoring instructions (`docs-authoring.instructions.md`, `agent-docusaurus-writer.instructions.md`). + +## Consequences + +- Maintainer tooling guides live under `community/`, not `docs/`. +- Authoring instructions gain a Content Root Selection table and an explicit prohibition against maintainer/operational content in `docs/`. +- The `runbooks/instruction-update.md` runbook keeps instructions in sync when new features or content areas are added. + +## Alternatives Considered + +- **Add a fourth `maintainers/` content root.** Rejected: more navbar/config surface for a small amount of content; `community/` already fits operational/community material. +- **Leave the guide in `docs/` and document an exception.** Rejected: keeps the ambiguity that caused the incident and invites future drift. +- **CI placement guard only (no instruction change).** Deferred: automation without a documented rule is brittle; document first, automate later if manual enforcement proves insufficient. + +## References + +- `z-shell/wiki` PR #736 — move maintainer tooling to `community/` and define content-root boundaries. +- `runbooks/instruction-update.md` — the maintenance routine this ADR establishes. diff --git a/runbooks/instruction-update.md b/runbooks/instruction-update.md new file mode 100644 index 000000000..19ae7c40d --- /dev/null +++ b/runbooks/instruction-update.md @@ -0,0 +1,54 @@ +# Runbook — Instruction Update + +Use this workflow to keep agent and contributor instructions current when the +codebase gains a feature, infrastructure component, or new content area. It is +the living checklist that answers "which instruction files need updating when I +change something?" + +## When to use this + +Run this before opening a PR that: + +- adds a new content area, page section, or directory to a repository +- introduces a new feature, service, or infrastructure component +- changes a convention, boundary, or workflow that an instruction file describes + +Skip it for pure bug fixes or content edits that do not change any documented +convention. + +## Wiki (`z-shell/wiki`) checklist + +- [ ] Pick the correct content root: `docs/` = Zi user docs only; `community/` + = community + maintainer/operational; `ecosystem/` = third-party catalog. + (See ADR `decisions/0006-wiki-content-root-boundaries.md`.) +- [ ] Update `AGENTS.md` if scope or conventions changed. `CLAUDE.md` is a + symlink to `AGENTS.md`, so it updates automatically. +- [ ] Update `.github/instructions/docs-authoring.instructions.md` (Content Root + Selection, frontmatter, naming). +- [ ] Update `.github/instructions/agent-docusaurus-writer.instructions.md` + (root selection, invocation). +- [ ] Run `pnpm validate:frontmatter` and `pnpm build:en`. + +## Org (`z-shell/.github`) checklist + +- [ ] Decision-level change? Draft an ADR — see `runbooks/adr.md` (status starts + `PROPOSED`). +- [ ] Update affected runbooks and `.github/instructions/`. +- [ ] New tooling/plugin? Update + `.github/instructions/mcp-plugins.instructions.md`. + +## Other repos + +- [ ] Update the repo's `AGENTS.md` / `.github/copilot-instructions.md` and any + scoped `.github/instructions/*.instructions.md` that describe the changed area. +- [ ] Prefer linking to canonical org/wiki guidance over duplicating it. + +## Template prompt for agents + +```text +I am adding . Per runbooks/instruction-update.md: +- which content root applies (wiki)? +- which instruction files and ADRs need updating? +- does this decision warrant a new ADR? +List the files to touch before writing code. +``` From 5d1f2bc5cbfa51ee42535e41201eef2426bfd3a9 Mon Sep 17 00:00:00 2001 From: Salvydas Lukosius Date: Fri, 22 May 2026 03:09:50 +0100 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20ADR?= =?UTF-8?q?=20heading=20casing=20and=20runbook=20list=20indentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../0006-wiki-content-root-boundaries.md | 2 +- runbooks/instruction-update.md | 22 ++++++------------- 2 files changed, 8 insertions(+), 16 deletions(-) diff --git a/decisions/0006-wiki-content-root-boundaries.md b/decisions/0006-wiki-content-root-boundaries.md index 77b7aa11c..94d2e3ced 100644 --- a/decisions/0006-wiki-content-root-boundaries.md +++ b/decisions/0006-wiki-content-root-boundaries.md @@ -28,7 +28,7 @@ These boundaries are recorded in the wiki `AGENTS.md` (with `CLAUDE.md` as a sym - Authoring instructions gain a Content Root Selection table and an explicit prohibition against maintainer/operational content in `docs/`. - The `runbooks/instruction-update.md` runbook keeps instructions in sync when new features or content areas are added. -## Alternatives Considered +## Alternatives considered - **Add a fourth `maintainers/` content root.** Rejected: more navbar/config surface for a small amount of content; `community/` already fits operational/community material. - **Leave the guide in `docs/` and document an exception.** Rejected: keeps the ambiguity that caused the incident and invites future drift. diff --git a/runbooks/instruction-update.md b/runbooks/instruction-update.md index 19ae7c40d..c88b9c7db 100644 --- a/runbooks/instruction-update.md +++ b/runbooks/instruction-update.md @@ -18,29 +18,21 @@ convention. ## Wiki (`z-shell/wiki`) checklist -- [ ] Pick the correct content root: `docs/` = Zi user docs only; `community/` - = community + maintainer/operational; `ecosystem/` = third-party catalog. - (See ADR `decisions/0006-wiki-content-root-boundaries.md`.) -- [ ] Update `AGENTS.md` if scope or conventions changed. `CLAUDE.md` is a - symlink to `AGENTS.md`, so it updates automatically. -- [ ] Update `.github/instructions/docs-authoring.instructions.md` (Content Root - Selection, frontmatter, naming). -- [ ] Update `.github/instructions/agent-docusaurus-writer.instructions.md` - (root selection, invocation). +- [ ] Pick the correct content root: `docs/` = Zi user docs only; `community/` = community + maintainer/operational; `ecosystem/` = third-party catalog. (See ADR `decisions/0006-wiki-content-root-boundaries.md`.) +- [ ] Update `AGENTS.md` if scope or conventions changed. `CLAUDE.md` is a symlink to `AGENTS.md`, so it updates automatically. +- [ ] Update `.github/instructions/docs-authoring.instructions.md` (Content Root Selection, frontmatter, naming). +- [ ] Update `.github/instructions/agent-docusaurus-writer.instructions.md` (root selection, invocation). - [ ] Run `pnpm validate:frontmatter` and `pnpm build:en`. ## Org (`z-shell/.github`) checklist -- [ ] Decision-level change? Draft an ADR — see `runbooks/adr.md` (status starts - `PROPOSED`). +- [ ] Decision-level change? Draft an ADR — see `runbooks/adr.md` (status starts `PROPOSED`). - [ ] Update affected runbooks and `.github/instructions/`. -- [ ] New tooling/plugin? Update - `.github/instructions/mcp-plugins.instructions.md`. +- [ ] New tooling/plugin? Update `.github/instructions/mcp-plugins.instructions.md`. ## Other repos -- [ ] Update the repo's `AGENTS.md` / `.github/copilot-instructions.md` and any - scoped `.github/instructions/*.instructions.md` that describe the changed area. +- [ ] Update the repo's `AGENTS.md` / `.github/copilot-instructions.md` and any scoped `.github/instructions/*.instructions.md` that describe the changed area. - [ ] Prefer linking to canonical org/wiki guidance over duplicating it. ## Template prompt for agents