AI Rulebook

AI Rulebook is a VS Code extension that installs a small set of always-on engineering rules for AI coding agents into your project's AGENTS.md. Seven topic rules cover scope, code reuse, testing, docs, Markdown, Git, and on-request code review. A sidebar lets you turn each rule on and off, and every toggle edits that rule's section of AGENTS.md in place.

The same file can be used by Cursor, Cline, opencode, Windsurf, and supported GitHub Copilot features. Support depends on the tool and its settings; see Per-tool notes. Claude Code reads CLAUDE.md, so the extension adds a one-line @AGENTS.md import there.

Get the extension

Version 4.0.0 moves the rule pack into AGENTS.md. Releases through 3.1.0 use the older per-tool layout; see Upgrading from the per-tool layout before migrating an existing workspace.

Distribution channels are:

• Open VSX — search for AI Rulebook in editors configured to use this registry, including Cursor. If other "AI" extensions bury it, search for the ID WyvernSystemsLLC.ai-rulebook instead.
• The Visual Studio Marketplace — search for AI Rulebook in stock VS Code, when the version you need has been published there.
• GitHub releases — download an attached ai-rulebook-X.Y.Z.vsix for manual installation (code --install-extension ai-rulebook-X.Y.Z.vsix, or Extensions panel → ... → Install from VSIX...). Release assets vary by version; older releases used per-tool rule ZIPs. The current release workflow attaches a standalone AGENTS.md instead.

Where it runs, and what it writes rules for

Two different compatibility lists matter, and they are independent:

• Editors it runs in — VS Code-compatible hosts supporting the extension API declared in package.json (^1.85.0), such as VS Code, Cursor, Windsurf, VSCodium, code-server / OpenVSCode Server, Eclipse Theia, and other forks. The sidebar and commands work the same in all of them.
• Tools that read the rules — anything that reads AGENTS.md: Cursor, Cline, opencode, Windsurf, supported GitHub Copilot features, and more. Claude Code reads the same file through the @AGENTS.md import in CLAUDE.md. The tool does not have to run inside the same editor: Claude Code and opencode are terminal tools, and AGENTS.md is meant to be committed so teammates get the rules without installing anything.

What gets written

Install / update rule pack writes one managed block into AGENTS.md, creating the file when the project has none and appending the block when it already exists. Updating an existing block preserves the text before and after it; first-time installation may add separating newlines.

<!-- ai-rulebook:start -->
<!-- Managed by the AI Rulebook extension. ... -->

<!-- ai-rulebook:rule scope enabled -->

## Scope

- Change only what the task requires. ...

<!-- ai-rulebook:end-rule scope -->

<!-- ai-rulebook:rule git disabled -->
<!-- ai-rulebook:end-rule git -->
<!-- ai-rulebook:end -->

Each rule has its own section. Disabling a rule removes its text and marks the section disabled; enabling it writes the text back from the bundle. A disabled rule is removed from this block rather than commented out; copies in other files and instructions already loaded into an agent session are unaffected. Re-running install refreshes the wording of every section and keeps each rule's on / off state.

Install also makes sure CLAUDE.md imports AGENTS.md, creating the file with the line @AGENTS.md when it is missing and appending the line when there is no detected import outside code fences or inline code. Existing imports in prose count. The extension does not replace your existing CLAUDE.md instructions.

Commands

The commands below are available from the command palette (Ctrl/Cmd+Shift+P) under AI Rulebook. The sidebar toolbar provides refresh, install, remove, legacy cleanup, agent mode selection, status, and whole-pack toggles; use its checkboxes or the palette for individual rules.

Install, remove, the legacy-folder cleanup, and the agent mode commands (including Select agent mode…) apply to every open workspace folder. The four enable / disable mode commands stay in the command palette; the sidebar toolbar has the single Select agent mode… entry. The sidebar, the status bar, and the rule toggles read and edit the first workspace folder's AGENTS.md.

Selecting a rule's name in the sidebar opens AGENTS.md at that rule's section via Open rule file, which is hidden from the command palette.

Removal decides whether to delete a file from its remaining content; it does not record who originally created it. When AGENTS.md is deleted, cleanup removes standalone @AGENTS.md lines outside fences from CLAUDE.md and deletes that file if empty. Inline prose imports and fenced examples remain. When AGENTS.md remains, its CLAUDE.md import remains too. Removal may normalize blank lines around the former block.

The rules

• scope.mdc — inspect relevant code and commands, complete and verify the task, resolve routine choices autonomously, keep changes in scope, and follow conventions without overriding safety or verification. Agents also fix small, local, check-verified defects they find along the way (bugs, dead code, stale docs, broken tests) and list them under an "Also fixed" heading; larger or behavior-changing ones are only reported. Every task ends with a report under fixed headings: Changed, Also fixed, Checks, Not done.
• code.mdc — reuse helpers, validate input where it enters, protect secrets, preserve error causes with actionable context, and check dependency maintenance and compatibility.
• tests.mdc — never report an unrun check as passing or weaken a check to pass, test observable behavior at the appropriate level, reproduce bugs with regression tests when feasible, run project tests and existing lint/type checks, recommend a suitable linter when absent and add it only when requested or approved, and inspect the final diff.
• docs.mdc — update documentation made inaccurate by the change, follow the project's layout, add user-facing release notes when appropriate, and create documentation only when requested or needed to explain changed behavior. Documentation is written densely for a reader who acts on it (human or agent), with one fact in one place, and agent-instruction files are kept shortest.
• markdown.mdc — one H1, no skipped heading levels, - bullets, language-tagged code fences, inline code for paths and commands, relative links.
• git.mdc — preserve existing work; no commits, pushes, or branches unless asked; stage only your changes (the task and its "Also fixed" items), inspect the staged diff, and never rewrite pushed history unless the user names the operation.
• review.mdc — applies only when you explicitly ask for a full code review. Covers unpushed changes (or a range you name) in passes for bugs, security, dead code, duplication and structure, improvements, tests, and docs, fixing as it goes, and reports licensing concerns without fixing them. Runs tests, lint, and type checks, reports changes by pass, then commits and pushes (asking for the review is the request to do so unless you say otherwise) and never force-pushes.

The rules are authored as Cursor .mdc files in bundled/ai-rules/. On the way into AGENTS.md the frontmatter is dropped and each rule's heading is nested one level under the file's own title. AGENTS.md has no per-file frontmatter scoping for these sections, so the Markdown rule is loaded with the pack; its text still limits its guidance to editing Markdown files.

tests.mdc names your project's own test command. On install the extension detects it from a package.json test script (using the lockfile to pick npm, pnpm, yarn, or bun), Cargo.toml, go.mod, pytest configuration, or a test target in a Makefile. When nothing is conclusive the rule says "the project's test command" instead of guessing.

Token-efficient subagent mode

This optional mode tells an agent to spend its expensive session model on judgment only (reading the request, planning, writing specs, the final report) and to delegate searching, editing, and check runs to subagents on cheaper models. It is off by default and is not part of the seven-rule pack: installing, toggling, or removing the pack never touches it, and Enable all rules does not turn it on.

Enable token-efficient subagent mode writes one block into AGENTS.md in every open folder, between <!-- ai-rulebook:subagent-mode:start --> and <!-- ai-rulebook:subagent-mode:end -->, and makes sure CLAUDE.md imports AGENTS.md. That is all it writes: no .claude/, .codex/, .cursor/, or other per-tool folders, and no tool settings. Run it again to refresh the wording and the detected test command. Disable token-efficient subagent mode removes the block, and deletes AGENTS.md (and its CLAUDE.md import) only when nothing else is left in it.

The text is written for any tool that reads AGENTS.md and has subagents, including Claude Code, ChatGPT / Codex, Cursor, opencode, and GitHub Copilot. It relies on the orchestrating model to follow it:

• Model tiers, not model names. Work is assigned to a fast, standard, or deep tier, with examples from several vendors, so each tool uses its own models. Tools without subagents are told to skip the section.
• Substitutes. When a tier's model is not offered, blocked by policy, failing, or rate-limited, the agent substitutes in a fixed order: fast falls back to standard and then the session model, standard to the session model, deep to the session model or standard at high effort. It never picks a model more expensive than the session model, tells you once, and keeps the substitute for the rest of the session.
• Delegate contracts. The block states what an implementer, test runner, and reviewer must do and how each replies, so no agent definition files are needed.
• No retry loops. When a delegate's edit is wrong or its check fails, the orchestrator fixes it itself. An incomplete spec is resent once, and the same change never gets a third delegate.
• Accuracy checks. High-risk diffs (concurrency, security, auth, credentials, persistence, migrations) get one read-only review on the strongest model after the checks pass, and the orchestrator reads the final diff itself before reporting.

Because these are instructions rather than configuration, a tool only runs a subagent on a cheaper model when its spawn call lets the agent choose one (Claude Code's does). Where it does not, delegation still keeps file contents and command output out of the session context, which is the larger saving.

It cannot be on at the same time as fast parallel agent mode, because the two pull in opposite directions: enabling either one fails while the other is on.

Fast parallel agent mode

This optional mode tells an agent to finish sooner by splitting the work into units, running them at the same time, and then integrating and verifying the result itself. It is off by default and is not part of the seven-rule pack: installing, toggling, or removing the pack never touches it, and Enable all rules does not turn it on.

It uses more tokens than working alone: it trades cost for wall-clock speed, the opposite of token-efficient subagent mode. It is not related to Claude Code's own /fast toggle, which speeds up the output of one model; the two can be used together.

Enable fast parallel agent mode writes one block into AGENTS.md in every open folder, between <!-- ai-rulebook:parallel-mode:start --> and <!-- ai-rulebook:parallel-mode:end -->, and makes sure CLAUDE.md imports AGENTS.md. That is all it writes: no per-tool folders and no tool settings. Run it again to refresh the wording and the detected test command. Disable fast parallel agent mode removes the block, and deletes AGENTS.md (and its CLAUDE.md import) only when nothing else is left in it.

The text is written for any tool that reads AGENTS.md and can run subagents in parallel; other tools are told to skip it. It relies on the orchestrating agent to follow it:

• Scale to the task. A change in one file, or steps that each depend on the last, is done directly without fan-out.
• Units by file ownership. Every file that will change belongs to exactly one unit, and a shared contract (names, signatures, types, paths, behavior) is written before fan-out so units build to it. Ready units are spawned in one message.
• No downgraded implementers. Implementers get a model at least as capable as their unit needs; smaller models are fine for searches and check runs.
• At most five units at once. More units hit rate limits and make integration harder than the time they save, so small related changes are folded into one unit.
• No shared files. Two units never edit the same file in the same checkout: use git worktrees or run them in sequence.
• Fall back to working alone. If splitting proves harder than the work, or units keep waiting on each other, the agent stops spawning and finishes the rest itself.
• Integrate and fix. The orchestrator brings the units together, runs the full test, lint, and type checks on the combined result, and fixes integration failures itself, with at most two repair rounds before it reports what still fails. Worktree units are merged into the main checkout one at a time: it reads each diff, applies it, checks it, resolves conflicts against the contract without dropping either side, and removes the worktree.
• One required review. The combined diff gets one read-only review on the strongest model, then the orchestrator reads the final diff itself.
• Delegate contracts. The block states what an implementer, researcher, and reviewer must do and how each replies.

Mutual exclusion. The mode cannot be enabled while token-efficient subagent mode is on, and token-efficient subagent mode cannot be enabled while this mode is on. The enable command checks every open folder first; if any folder has the other mode, it shows an error naming Select agent mode… and the disable command, and writes nothing in any folder. Select agent mode… is the one-step way to switch.

As with subagent mode, these are instructions rather than configuration: the mode cannot force parallelism or pick models, and it cannot guarantee that your tool supports git worktrees.

Just want the rules?

You don't need the extension to use these rules. bundled/standalone/AGENTS.md is the file the extension writes into a fresh workspace. The current release workflow also attaches it to GitHub releases. Copy it to your project root, or paste the block between the ai-rulebook:start and ai-rulebook:end markers into an existing AGENTS.md, then replace "the project's test command" in the Tests rule with your real command. Keep both outer markers when pasting. Do not overwrite an existing file or append a second managed block. For Claude Code, create CLAUDE.md with @AGENTS.md, or append that line to the existing file.

VS Code and other hosts

Install

Search for AI Rulebook in the Extensions panel, or install the VSIX from a GitHub release — see Get the extension. To build it yourself: npm ci && npm test && npm run package (see Development for prerequisites).

Use

1. Open a project folder.
2. If the project already shows signs of AI-agent use (an AGENTS.md, CLAUDE.md, .cursor/, .clinerules/, .opencode/, .windsurf/, or .github/instructions/ entry, among others), or the host is Cursor, or the Cline extension is installed, the rule pack installs automatically on activation if its block is missing and auto-install is enabled. Otherwise run AI Rulebook: Install / update rule pack. When auto-install skips a project for lack of agent evidence, it shows a one-time hint.
3. Toggle rules with the AI Rulebook sidebar checkboxes or the command-palette commands. Each toggle edits AGENTS.md.
4. Commit AGENTS.md and CLAUDE.md so teammates and terminal tools get the same rules.

Per-tool notes

• Cursor — supports root and nested AGENTS.md files; this extension manages only the workspace-root file. See Cursor rules.
• Cline — recognizes AGENTS.md alongside its other rule sources. Check Cline's own Rules panel if the file is disabled there. An installed Cline extension is evidence for AI Rulebook's auto-install. See Cline rules.
• opencode — reads AGENTS.md as project instructions; no extra config entry is needed. See opencode rules.
• Windsurf / Cascade — the root AGENTS.md applies across the workspace; nested files can have narrower scope. The Windsurf documentation now redirects to Devin Desktop's AGENTS.md guide.
• GitHub Copilot — support varies by client and feature; see GitHub's support matrix. In VS Code, chat.useAgentsMdFile controls loading; see VS Code custom instructions. AI Rulebook does not change that setting.
• Claude Code — imports the shared file through @AGENTS.md in CLAUDE.md. See Claude Code memory. AI Rulebook leaves detected prose imports alone and ignores examples in code fences or inline code when checking for an import.

Upgrading from the per-tool layout

Earlier releases mirrored the rules into a folder per tool. Those folders are no longer written or updated. After installing this version:

1. Run AI Rulebook: Install / update rule pack to write AGENTS.md.
2. Run AI Rulebook: Remove legacy per-tool rule folders… to delete the old mirrors, and drop the .opencode/rules/ai-rules/*.md entry from your opencode config if you had one.
3. Reapply any rules you previously disabled: the new block starts with all bundled rules enabled and does not import state from the old folders.

Notes

• The extension never edits .gitignore. AGENTS.md and CLAUDE.md are meant to be committed.
• Disable automatic installation with aiRules.autoInstallOnOpenWorkspace: false.
• Disable version-change prompts with aiRules.promptInstallOnUpdate: false. Both settings default to true. The prompt is tracked per extension installation, not separately for every workspace.
• Everything outside the managed block in AGENTS.md is yours. The extension preserves it when updating an existing block and refuses to overwrite a block whose markers are damaged. Fix the markers manually; the removal command also requires a valid block.
• A status bar item shows the enabled-rule count and the agent mode (AI 7/7 · parallel or AI 7/7 · subagent; the tooltip names the mode); click it to show the rule pack status. If both mode blocks are present (a hand edit or merge), it shows a warning (AI 7/7 · 2 modes), the sidebar Agent mode row shows the conflict, and the status output prints a warning; pick a mode with Select agent mode… to fix it.
• The sidebar has an Agent mode row after the rules showing Off, the active mode, or Conflict: more than one on; selecting it opens the picker.
• The sidebar and status bar refresh after every command that edits AGENTS.md and automatically when each workspace folder's root AGENTS.md changes on disk (git pull, branch switch, hand edit). Refresh sidebar remains available.
• If the sidebar cannot read or parse AGENTS.md, rules show Unable to read with details in the tooltip. Fix the file and refresh the sidebar to restore the checkboxes.
• The rule toggles edit sections inside the managed block, so they need the pack to be installed. Without it the sidebar checkboxes and the enable / disable commands report that the rule pack is not installed yet.

Development

Use Node.js 24 for development, linting, and packaging. ESLint requires Node.js 20.19+, 22.13+, or 24+. The extension still declares Node.js >=18.18.0; CI tests Node 18 and 20 and runs lint on Node 24.

npm ci
npm run lint
npm test
npm run package

npm test cleans and compiles TypeScript, verifies the bundle, and runs node:test, including temporary-workspace and build-script tests. npm run lint checks src/**/*.ts with the recommended ESLint and typescript-eslint rules and rejects warnings. npm run test:coverage adds coverage reporting. For extension-host debugging, run npm run compile (or npm run watch) before launching Run Extension with F5; the launch configuration does not build automatically.

Rule text is edited in bundled/ai-rules/, the tracked source of truth that ships in the VSIX. Only .mdc source files are accepted; .mdc.disabled files and other non-rule files are rejected. Run npm run sync-bundled after adding, removing, or editing a rule file to regenerate bundled/manifest.json and the standalone bundled/standalone/AGENTS.md and its README — commit changed generated files alongside the rule change. The subagent mode text lives in bundled/subagent-mode/section.md and the fast parallel agent mode text in bundled/parallel-mode/section.md; both are rendered the same way as a rule. Edit the standalone README template in scripts/build-standalone.mjs, not the generated file.

Source rules hold the {{TEST_COMMAND}} token verbatim; the extension substitutes the project's real command on the way into AGENTS.md. This repo's own AGENTS.md carries the rendered block as a dogfooded install; change a rule in bundled/ai-rules/, then re-run the install command to regenerate it. It also has token-efficient subagent mode enabled; after editing bundled/subagent-mode/section.md, re-run the enable command. Fast parallel agent mode is not enabled here, so its block is not dogfooded.

Requirements are tracked in docs/REQUIREMENTS.md. Cutting a release is documented in docs/RELEASING.md. The repository's installed rule pack is in AGENTS.md; it contains only what the extension generates: the rule pack from a fresh install and the token-efficient subagent mode block.

Limitations

• Rules are instructions, not enforcement. An AI agent can still misread or ignore a rule, and models tend to drop rules under context pressure in long sessions — re-state the rule that matters when that happens.
• Rules only load in tools that read AGENTS.md (or, for Claude Code, CLAUDE.md). A tool that reads neither never sees them.
• File mutations are queued per workspace within one extension host. They are not coordinated across editor windows or with external writers; save pending edits before using rule commands.
• Subagent mode is guidance only. It cannot pin a subagent's model, verify that a model is available to your account, or stop an agent from doing the work itself on the session model.
• Fast parallel agent mode is guidance only. It cannot force an agent to run work in parallel, pick the models it uses, or guarantee that your tool supports git worktrees. It spends more tokens than working alone.
• Token-efficient subagent mode and fast parallel agent mode are mutually exclusive; enabling one fails while the other is on. Use Select agent mode… to switch.
• Removing a block does not turn off auto-install. To keep it removed on later activation, also disable aiRules.autoInstallOnOpenWorkspace.
• The extension manages the rule text itself; it does not verify that code changes actually followed it.

License

MIT

Built by Ron Picard at Wyvern Systems.