Playbook & rules
A rule is a standard your team already says in code review, written down once and enforced everywhere.
Anatomy of a rule
| Field | Semantics |
|---|---|
| Title | Short and specific — it's what appears in violations and dashboards. |
| Statement | The rule in plain language (GitHub-flavored markdown). Write it in the imperative and explain the why — the model judges better when it knows the intent. |
| Severity | error blocks the merge · warning and info surface without blocking. Reserve error for real dangers. |
| Scope globs | Where the rule applies: src/**, apps/api/**… Empty = the whole repo. A rule is only checked against files its globs match. |
| Tags | Free-form labels (security, api…) for categorizing and filtering. Organizational only — they don't affect analysis. |
| Examples | Optional compliant / non-compliant snippets, served to agents on demand when a statement alone is ambiguous. |
What makes a rule enforceable
The test: could a senior reviewer judge pass/fail by looking at a diff? If yes, the model can too.
- ✅ “HTTP calls go through
lib/http.ts— it handles retry, timeout and tracing. Never callfetchdirectly.” - ✅ “Every DB migration ships a rollback in the same PR.”
- ❌ “Write clean, maintainable code.” — not judgeable on a diff; it will produce noise.
No idea where to start? The playbook library has seven ready-made playbooks — API security, Next.js App Router, Terraform, migrations, multi-tenant isolation and more — each rule written against that same test, and copyable as markdown to keep beside you while you enter the ones you want (rules are added one at a time; there is no bulk import).
Normik only flags lines actually added in the diff, and only cites rules that exist — a hallucinated line number or rule id is dropped before you ever see it.
Workspaces and inheritance
Root rules apply to the whole organization. Rules placed in a workspace apply in addition, for that workspace's tokens only. Drag rules between folders in the Playbook page; deleting a workspace asks whether its rules migrate to root or go with it.
Versioning & restore
Every content change snapshots the previous state — the last 10 versions are kept. Restoring re-applies an old version and snapshots the current one first, so a restore is itself undoable.
Bootstrapping from an existing repo
A connected agent can call the bootstrap_playbook capability, or you can click Bootstrap from repo directly on the Playbook page and pick files or a folder — same generation either way. Normik derives 3–10 specific, verifiable rules on your key, always written in English regardless of the language the submitted files are in. They arrive as AI-proposed, pending review — nothing activates without a human(see Governance).
Exports for agents without MCP
The Export button on the Playbook page generates an AGENTS.md or CLAUDE.md from your active rules — deterministic, sorted by severity, scoped to the current folder. Commit it to repos whose tooling doesn't speak MCP.
Skills
Skills are reusable how-tos (markdown instructions) with the same hierarchy, versioning and governance as rules. Agents list them, load them on demand, and usage is tracked. You can also generate a skill draft from a prompt — reviewed in the form before saving.