AI Rulebook — Cursor / VS Code extension

One-line: This extension drops a curated set of AI agent rules into your project so Cursor (and Cline) reply more consistently — write cleaner code, keep docs current, frame answers for the right audience, and write proper tests when you ask for them.

• Display name: AI Rulebook
• Package id: WyvernSystemsLLC.ai-rulebook
• License: MIT
• Source of truth for rules: .cursor/rules/ai-rules/ (the VSIX ships a byte-identical copy under bundled/ai-rules/)

What are AI rules and why use them?

A "rule" is a short Markdown file you give the AI assistant. It tells the assistant how you want it to behave in this project — coding style, security defaults, doc-keeping habits, who the answer is for, what to test, etc.

Cursor and Cline both load rules automatically when you chat with them, so the assistant follows your team's conventions without you having to remind it every message.

This extension ships 27 ready-made rules grouped into 5 folders, plus a sidebar to turn them on and off, plus four modes (Plan / Build / Test / Role) that flip presets in one click. You don't have to write any rules yourself to get value — install, click "Install / update rules in workspace", and start chatting.

.cursor/rules/ai-rules/
├── ABOUT_RULES.md
├── coding-rules/            ← how to write and ship code
├── documentation-rules/     ← how to maintain docs and changelogs
├── role-rules/              ← how to frame replies for a given audience
├── rules-for-rules/         ← how the rule pack itself is authored and announced
└── test-rules/              ← how to design and write tests

Quickstart

1. Install AI Rulebook in Cursor or VS Code.
2. Open the project you want the rules to apply to. The first time the extension sees a project, it drops the bundled rule pack into .cursor/rules/ai-rules/ and starts it in Build mode (developer role on, tests off). Existing .cursor/rules/ai-rules/ folders are never overwritten.
3. Click the checklist icon in the activity bar (left side) to open the AI Rulebook sidebar.
4. Toggle individual rules with the checkboxes in the sidebar, or pick a preset with the Mode — Plan / Build / Test / Role… buttons at the top of the sidebar.
5. Start chatting. The AI now follows the rules you have turned on.

To opt out of the first-time auto-install, set aiRules.autoInstallOnOpenWorkspace to false and run AI Rulebook: Install / update rules in workspace when you want it.

Sidebar tree view — turn rules on and off

The AI Rulebook sidebar (activity-bar icon, looks like a checklist) is the primary place to enable / disable rules. It shows every shipped rule grouped by subfolder and uses color so the on / off state is obvious at a glance:

• Green label + filled circle icon — rule is active (<name>.mdc on disk, loaded by Cursor).
• Dimmed gray label + empty circle icon — rule is off (<name>.mdc.disabled on disk, ignored by Cursor).

What you can do from the sidebar:

Switching modes from the sidebar buttons only flips role and test rules — your always-on coding, documentation, and meta rules stay enabled. Manual changes you make via the checkboxes always win until the next mode switch.

Same colors in the workbench Explorer

The same color scheme also applies to rule files in VS Code's built-in Explorer view: any <name>.mdc under .cursor/rules/ai-rules/ shows up green, and any <name>.mdc.disabled shows up muted gray. So you can browse your rules folder like a normal folder and still see at a glance which rules are active. Set aiRules.colorRulesInExplorer to false (or run AI Rules: Hide active rules) to opt out; AI Rulebook: Show active rules turns it back on. The sidebar tree always shows on / off colors regardless of this setting.

All commands

Every command lives under the AI Rulebook: prefix in the command palette.

Install / update

Turn rules on or off

Modes

Global mirror (cross-project)

The "global mirror" is a per-extension copy under VS Code / Cursor's global storage. You can populate it once and then push it into any project.

Inspect / refresh

Modes

A "mode" is a one-click preset that turns specific rules on and others off. Always-on coding, documentation, and meta rules are not touched by modes — they keep running across every mode.

You can also flip individual rules manually any time, in the sidebar or via the command palette.

Settings

Every rule that ships with this extension

For longer descriptions read bundled/ai-rules/ABOUT_RULES.md.

coding-rules/ — always on

documentation-rules/

role-rules/ — off by default; turned on by mode commands

These change who the assistant is talking to.

rules-for-rules/

test-rules/ — off by default; turned on by Mode — Test

Limitations — read this before you blame the rules

Rules are instructions to the model, not enforcement. The assistant chooses how to weigh them on every reply. In practice this means:

• Context is limited. Every active rule eats space in the model's context window. If you turn on 27 rules and include large files and a long chat history, the model may quietly drop or compress some rules. Symptom: rules you turned on don't appear to fire.
• Some rules are stronger than others. Always-on rules are loaded every turn; glob-scoped rules only when matching files are open; @-mentioned rules only on the turn you mention them. If a rule isn't firing, check the scope.
• Models drift between turns. A rule may apply on the first reply and not on the third. Re-mention it (@write-clean-code) or restate the relevant expectation.
• Different products read rules differently. Cursor and Cline don't have identical engines; Cline mirrors are best-effort.
• The "Active project rules" header is not guaranteed. Cursor depends on the model to honor state-active-project-rules-in-prompt-response.mdc. If the model skips it, mention @state-active-project-rules-in-prompt-response once in the chat.

Practical advice:

• Don't enable everything by default. Use Mode — Plan / Build / Test to match the work you're actually doing.
• For a big or complex task, turn off the rules you don't need that turn.
• If you want a rule to fire definitely, @-mention it in your message.
• If a rule keeps getting ignored, shorten it. Compressed rules survive truncation better.

Security model

This extension only writes inside three well-known locations:

• the open workspace folder, under .cursor/rules/ai-rules/ and (if Cline is installed) .clinerules/ai-rules/;
• the extension's global storage under <globalStorage>/ai-rules-mirror/ai-rules/ — used by the global mirror commands;
• nothing outside those paths.

Defenses applied:

• Manifest validation at activation. Each entry in bundled/manifest.json must be a forward-slash relative path matching ^[A-Za-z0-9_./-]+$, with no .. segments, no leading / or ./, and ≤ 200 chars. A tampered or malformed manifest aborts activation with a clear error.
• Path containment. Every operation that resolves a manifest entry under a base directory re-checks that the resolved path stays inside that base. Out-of-tree paths throw before any filesystem call.
• Destructive operations are gated by an explicit suffix check. The workspace rules folder must end with .cursor/rules/ai-rules; the global mirror with ai-rules-mirror/ai-rules. A misconfigured constant cannot widen the blast radius of rm -rf.
• No symlinks during recursive copies. The fs.cp calls used to mirror the bundle filter out symbolic links; the directory walker skips them too.
• No network access. The extension never makes outbound HTTP calls.
• No runtime dependencies. package.json has zero dependencies. The VSIX ships only compiled JS, the bundled rule files, an icon, the readme, changelog, and license.
• No secret material. The extension never reads or writes credentials, environment variables, or anything outside the rule files listed above.

If you find a security issue, please open a private report on the issues tracker (linked in package.json → bugs).

Develop

npm install
npm run sync-bundled    # copy .cursor/rules/ai-rules → bundled/ai-rules
npm run verify:bundled  # fail if bundled ≠ source (run after sync)
npm run compile         # tsc → out/

Press F5 with this repo open in VS Code (or Cursor) to launch the Extension Development Host with the dev build.

The source of truth for rule text is .cursor/rules/ai-rules/. The VSIX ships bundled/ai-rules/; the vscode:prepublish script runs sync → verify → compile to keep them identical.

Package the VSIX (for the marketplace)

npm install
npm run sync-bundled
npm run verify:bundled
npm run compile
npx --no-install vsce package

This produces ai-rulebook-<version>.vsix in the repo root. To upload it to the VS Code Marketplace:

1. Sign in as the publisher (WyvernSystemsLLC).
2. Choose New extension → Visual Studio Code.
3. Upload the .vsix.

For the Open VSX registry (used by Cursor's gallery), follow their publishing guide.

Notes

• Cursor user rules (app-wide) still live in Cursor Settings → Rules; this extension's "global mirror" is separate per-extension storage unless you copy it into a workspace.
• Cline may interpret YAML (globs vs paths) differently from Cursor; treat Cline output as best-effort.