Intelligent sync of Claude instructions with enforcement hooks for security and consistency.

The default rules are opinionated - like Prettier for code formatting, the default source repository enforces specific rules and conventions. It has opinions about AI traces, German umlauts, git workflows, and more. You can use these defaults, customize them, or point dogma at your own source with completely different rules.

Claude Code is powerful, but without guardrails it's YOLO mode - and many developers (or their employers) don't want that.

Single Source of Truth: Define your coding standards, security rules, and AI guidelines once. Use the default source repository or create your own - every team member syncs from the same source, ensuring consistency across the organization.

Custom Rules, Your Way: dogma doesn't force you to use anyone's defaults. Point it at your own private repository with your company's specific guidelines. The only requirement: a similar structure to the default source repository.

No AI Traces in Code: Many companies prohibit AI-generated artifacts in their codebase. dogma's hooks and cleanup commands help detect and remove typical AI patterns (curly quotes, em-dashes, AI phrases) before they reach your commits.

Smart Merging: When syncing rules, dogma doesn't blindly overwrite your local customizations. It handles merging intelligently, so project-specific rules stay intact while shared standards get updated.

Sync Across Projects: Same rules everywhere. Whether you have 5 or 50 repositories, one /dogma:sync keeps them all aligned with your personal standards.

Sync Across Devices: Work on multiple machines? Your rules live in a source repository - sync them wherever you need them.

The default source repository is actively developed and used by the author across all personal and professional projects. Strong self-interest ensures it stays functional and up-to-date.

Dogma is primarily based on markdown instruction files (CLAUDE.md, CLAUDE/*.md) that Claude reads at session start. Like all LLM instructions, these are suggestions that agents may occasionally ignore.

The enforcement hooks add a technical layer that blocks or warns about specific actions, making compliance more reliable - but even hooks cannot guarantee 100% adherence for all rules.

What dogma provides:

• Significantly more reliable rule-following than without
• Technical enforcement where possible (git, secrets, dependencies)
• Automatic reminders at key moments
• Quick correction: just tell Claude "check @CLAUDE/CLAUDE.xyz.md" instead of writing long correction prompts

What dogma cannot guarantee:

• Stylistic rules (language, formatting) may still be violated occasionally
• Complex behavioral rules depend on the agent's interpretation

The plugin includes hooks that enforce rules at the technical level:

The hooks add minimal overhead:

• Most hooks produce no output when everything is fine (early exit)
• UserPromptSubmit reminders add a short summary at each prompt (~100-200 tokens)
• Warnings appear only when needed (rule violations, open checklists, etc.)

The reminder output is intentionally compact. You can disable individual hooks via environment variables if needed (see Configuration).

To use only sync without hooks, disable all hooks via environment variables or uninstall after syncing.

Fetches Claude instructions from a source and merges them interactively.

/dogma:sync                                  # Sync from your configured source (CLAUDE_MB_DOGMA_SOURCE)
/dogma:sync https://github.com/user/repo     # Sync from GitHub repo
/dogma:sync git@github-work:owner/repo.git   # Sync via ssh (SSH host aliases work)
/dogma:sync ./my-standards                   # Sync from local path

Which source: an argument wins, then CLAUDE_MB_DOGMA_SOURCE, then the built-in default. When CLAUDE_MB_DOGMA_SOURCE is unset, /dogma:sync asks once (Ask tool) for the source and where to store it: global (default, env in ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json), this project only (.claude/settings.local.json) or not at all. Only the env key is changed, all other settings are preserved, and an invalid settings file is never overwritten. The same variable is what source broadcasts read.

• CLAUDE.md - Main Claude instructions
• CLAUDE.*.md - Additional instruction files
• .claude/ - Claude configuration (each file reviewed individually, including settings.json)

For each file, you decide what happens:

• New file: Add it? Skip? Show full content?
• Different file: Keep current? Replace? Merge?
• Identical: Automatically skipped

Files stay untracked - they won't reveal AI usage.

Dogma does not require any specific markdown files. You can:

• Delete files you don't need - Hooks simply skip checks for missing files
• Modify any file - Adapt rules to your preferences
• Use dogma as a template - Start with the default rules and customize
• Use any source - Point /dogma:sync to local paths or remote repos
• Merge multiple sources - Sync from different projects interactively

The sync command never overwrites without asking. For each file difference, you choose:

• Keep your local version
• Replace with source version
• Merge both versions
• Skip the file entirely
• Write your own prompt for special handling

This means you can maintain your own customized ruleset while still pulling updates from any source when you want them.

Example workflows:

# Sync from a local folder (no repo needed)
/dogma:sync ~/my-claude-rules
/dogma:sync ./shared-standards
/dogma:sync /home/user/projects/team-config

# Sync from a GitHub repo (default source)
/dogma:sync https://github.com/Marcel-Bich/marcel-bich-claude-dogma

# Combine rules from multiple local and remote sources
/dogma:sync ~/company-rules
/dogma:sync ./project-specific
/dogma:sync https://github.com/someone/security-rules

Interactively applies CLAUDE rules to your project with full control.

/dogma:force              # Apply to entire project
/dogma:force src/         # Apply to specific path

The command follows a collect-then-execute pattern:

1. Select Categories - Multiple choice of rule categories (Language Rules, Git & AI-Traces, Code Formatting, etc.)
2. Review Rules - Each rule explained with what it does and whether it's enforceable
3. Summary - Full overview of planned changes before any execution
4. Execute - Only after explicit confirmation

• No changes until final confirmation - Safe to explore
• Human-friendly names - "Language Rules" not "CLAUDE.language.md"
• Explanations for everything - What each rule means and what will change
• Review mode - Optionally inspect each fix individually before applying
• Cancel at any point - Full user control throughout

Finds and fixes AI-typical patterns in your code.

/dogma:cleanup           # Scan working directory
/dogma:cleanup src/      # Scan specific directory

• Typography: Curly quotes " " (U+201C, U+201D), em-dashes -- -- (U+2014, U+2013), ellipsis ... (U+2026)
• Emojis: In code files where they don't belong
• AI Phrases: "Let me...", "I'll...", "Sure!", "Certainly!"
• German (German text only): ASCII umlauts instead of proper ones (fuer -> für); text in any other language is left alone

Interactive 5-step setup for Prettier and related linting tools.

/dogma:lint:setup

1. NVM/Node Check - Verifies Node.js installation, suggests nvm if needed
2. Project Analysis - Detects file types (PHP, Vue, TypeScript, etc.) to determine required plugins
3. Dependencies - Security check for each package before installation (npm audit, TBD: additional security scanning)
4. Config Files - Creates .editorconfig, .prettierrc, .prettierignore based on detected languages
5. IDE Configuration - Configures PhpStorm/WebStorm or VS Code for format-on-save

Before installing any package, the command:

• Runs npm audit to check for vulnerabilities
• (TBD) Checks package on security scanning service
• Verifies download counts, maintainers, last update
• (TBD) Checks for known supply chain risks
• Asks for confirmation before each install

Project-agnostic linting and formatting on staged files.

/dogma:lint              # Lint and format staged files
/dogma:lint src/         # Lint specific path

• Non-interactive: Skips missing tools silently, no questions asked
• Staged files only: Protects legacy code from unexpected changes
• Lint first, format second: Finds errors before fixing style
• Re-stages files: Keeps git staging intact after formatting

1. git add stages files
2. git commit is blocked by pre-commit hook
3. Run /dogma:lint to lint and format staged files
4. Commit with: CLAUDE_MB_DOGMA_SKIP_LINT_CHECK=true git commit -m "..."

Manage AI/tool ignore patterns across multiple locations at once.

Add patterns to .gitignore and .git/info/exclude interactively.

/dogma:ignore .aider*                       # Single pattern
/dogma:ignore ".aider* .continue* .codeium*" # Multiple patterns

Workflow:

1. Confirm pattern(s) with user
2. Ask for each location: .git/info/exclude (local, unversioned), .gitignore (versioned)
3. Optionally search for parallel repos and add patterns there too
4. Show summary of all changes

Example session:

User: /dogma:ignore .aider*

Claude: Ich werde folgendes Pattern hinzufuegen:
- .aider*

Soll ich ".aider*" zu .git/info/exclude hinzufuegen? [J/n]
User: j

Soll ich ".aider*" zu .gitignore hinzufuegen? [J/n]
User: n

Soll ich in benachbarten Pfaden nach weiteren Git-Repos suchen? [1/2/3]
User: 3

Fertig! Pattern .aider* hinzugefuegt zu:
  [OK] .git/info/exclude
  [--] .gitignore (uebersprungen)

Show which AI patterns are missing from ignore files.

/dogma:ignore:audit

Output:

Pattern-Audit:

.aider*
  [OK] .git/info/exclude
  [!!] .gitignore (FEHLT)

.continue*
  [!!] .git/info/exclude (FEHLT)
  [!!] .gitignore (FEHLT)

.codeium*
  [OK] .git/info/exclude
  [OK] .gitignore

Zusammenfassung: 3 fehlende Eintraege

Tipp: /dogma:ignore .aider* .continue* zum Hinzufuegen

Status indicators:

• [OK] - Pattern is present
• [!!] - Pattern is MISSING
• [--] - File does not exist

Optionally scans parallel repos in the same parent directory.

Sync all AI/tool patterns from sync.md to selected local repositories.

/dogma:ignore:sync-all

Note: This command is only available in the marketplace repository where plugins/dogma/commands/sync.md exists.

Workflow:

1. Load patterns from sync.md (categorized: Claude Code, Cursor, Windsurf, Aider, etc.)
2. Select target repositories (all siblings, specific selection, or custom path)
3. Add missing patterns to each repo's .gitignore
4. Show summary of changes

Output:

Sync von 45 Patterns aus sync.md

../marcel-bich-claude-ideas:
  + .aider* (.gitignore)
  + .continue* (.gitignore)
  = 2 hinzugefuegt

../web-selecta-7850:
  = Alle Patterns bereits vorhanden

Gesamt: 2 Patterns zu 1 Repo hinzugefuegt

Runs at the START of every prompt. Reminds Claude of:

• Git permissions (from DOGMA-PERMISSIONS.md)
• Language rules (@CLAUDE/CLAUDE.language.md)
• AI traces rules (@GUIDES/ai-traces.md)
• Honesty rules (@CLAUDE/CLAUDE.honesty.md)
• Planning rules (@CLAUDE/CLAUDE.planning.md)
• Philosophy rules (@CLAUDE/CLAUDE.philosophy.md)
• Versioning rules (@CLAUDE/CLAUDE.versioning.md)
• File protection reminder

Only shows reminders for files that actually exist in your project.

Reminds Claude to proactively suggest skills before diving into work:

• Complex/multi-step task? -> /create-plan
• Need to prioritize? -> /consider:eisenhower-matrix
• Debugging issue? -> /debug or /debug-like-expert
• Decision needed? -> /consider:* (first-principles, swot, etc.)

Only active if CLAUDE.prompt-intervention.md exists in your project.

Scans for open checklists (- [ ]) in:

• Root: PLAN.md, TODO.md, ROADMAP.md, README.md, TO-DOS.md, BRIEF.md, MILESTONES.md, whats-next.md, TO-DELETE.md
• docs/.md, .claude/.md, .planning/*.md
• .planning/phases//.md (for taches-cc-resources create-plans)

When open tasks are found, reminds Claude to:

1. Ask user before marking tasks as done
2. Never silently check off tasks
3. Wait for explicit confirmation

Blocks git add for:

• AI instruction files: CLAUDE.md, CLAUDE.*.md, .claude/
• Secret files: .env*, *.pem, *.key, *credentials*, id_rsa
• Files in .git/info/exclude (locally ignored files are intentional)

Reminds Claude to delegate work to subagents instead of doing it directly. Triggers on UserPromptSubmit.

The reminder includes:

• Decision flow: user interaction? -> specialized agent? -> general-purpose
• SUBAGENT CONTEXT RULES for spawning Task:
  1. Announce before spawning
  2. Include user's goal/intent
  3. Specify what is TEST vs REAL work
  4. List what should NOT be committed
  5. "Read CLAUDE.md first"
  6. "NO git push - report back"
  7. Handoff chain instructions
  8. "NEVER add/commit .gitignore-d files"

Toggle: CLAUDE_MB_DOGMA_SUBAGENT_SUGGESTION=false

Blocks direct implementation work (Bash/Write/Edit) and enforces delegation to subagents. Triggers on PreToolUse for Bash, Write, Edit.

Unlike Subagent Suggestion (which only reminds), this hook actively blocks tool use until delegation is confirmed.

Toggle: CLAUDE_MB_DOGMA_SUBAGENT_ENFORCEMENT=false

Plan-file exception: Write and Edit operations targeting ~/.claude/plans/*.md are always allowed through subagent enforcement. This ensures Claude Code plan mode can create and update plan files without being blocked.

Reset interval: The enforcement state resets periodically based on CLAUDE_MB_DOGMA_RESET_INTERVAL (default: 2). This controls the number of user prompts between state resets. Set to 0 to disable enforcement entirely.

Ensures subagents run at the correct model tier. Triggers on Task tool calls.

Toggle: CLAUDE_MB_DOGMA_MODEL_POLICY=false disables the entire model enforcement hook.

Model detection checks settings in priority order:

1. Project-local settings (.claude/settings.local.json)
2. Project settings (.claude/settings.json)
3. Global settings (~/.claude/settings.json)
4. Fallback: opus (safest default -- never downgrade by accident)

Three enforcement behaviors:

1. Built-in Agent Inheritance (CLAUDE_MB_DOGMA_BUILTIN_INHERIT_MODEL=true, default) Built-in agents (Explore, Plan, Bash, etc. - those without a colon in agent type) inherit the parent model instead of using their default.

2. Downgrade Protection (CLAUDE_MB_DOGMA_ALLOW_MODEL_DOWNGRADE=false, default) When a subagent explicitly specifies a lower-tier model than the parent, the explicit model is overridden to match the parent. Prevents cost-saving downgrades that contradict user configuration.

3. Force Parent Model for All Plugins (CLAUDE_MB_DOGMA_FORCE_PARENT_MODEL=true, default) When enabled, ALL plugins (not just Anthropic) use the parent model. This guarantees your model preference overrides any plan file recommendations or plugin defaults.

Model Ranking (highest to lowest):

1. opus
2. sonnet
3. haiku

Toggles:

• CLAUDE_MB_DOGMA_MODEL_POLICY=false - Disable entire model enforcement hook
• CLAUDE_MB_DOGMA_FORCE_PARENT_MODEL=false - Only enforce for Anthropic plugins (old behavior)
• CLAUDE_MB_DOGMA_BUILTIN_INHERIT_MODEL=false - Skip model enforcement for built-in agents
• CLAUDE_MB_DOGMA_ALLOW_MODEL_DOWNGRADE=true - Allow explicit downgrades below parent model

Reminds about open checklists when a session ends. Triggers on Stop.

Scans the project for files containing unchecked items ([ ]) in .md, .txt, and .todo files. If found, suggests spawning a checklist-manager agent to scan and update them.

Toggle: CLAUDE_MB_DOGMA_CHECKLIST_REMINDER=false

Reminds to spawn a code reviewer after Write/Edit operations. Triggers as PostToolUse on Write and Edit.

Only activates when DOGMA-PERMISSIONS.md has review configured:

• [x] nach Umsetzung or [x] after implementation
• Or a ## Workflow section with [x].*review

Suggests spawning a review agent - whatever specialized reviewer your environment actually lists (verify the name first), else general-purpose.

Toggle: CLAUDE_MB_DOGMA_REVIEW_TRIGGER=false

Checks the permissions section in DOGMA-PERMISSIONS.md:

<permissions>
- [x] (§6gpt) May run `git add` autonomously
- [x] (§2w1t) May run `git commit` autonomously
- [?] (§bww9) May run `git push` autonomously
- [?] (§0lgy) May delete files autonomously (rm, unlink, git clean)
</permissions>

The first three are enforced by the Git Permissions hook. The last one is enforced by the File Protection hook.

Checkbox meanings (3-state system):

• [x] = auto (Claude does it automatically)
• [?] = ask (Claude asks for confirmation first)
• [ ] = deny (blocked, manual only)

File search:

• Picks the file by the target of the command first (git -C <dir> ..., a leading cd <dir> && ...), then the credo pinned project, then upward from the session folder - see Which DOGMA-PERMISSIONS.md applies (and inheritance)
• Use /dogma:permissions to create the file interactively

Default behavior:

• If no DOGMA-PERMISSIONS.md found: all git operations allowed
• If no <permissions> section found: all git operations allowed

Chained commands (v1.28.8+): Also catches git commands in chained expressions:

• sed -i ... && git push - blocked if push not permitted
• echo foo ; git commit -m "msg" - blocked if commit not permitted
• test -f file || git add file - blocked if add not permitted

Note: If specific permission not listed, that operation is allowed.

A session is often started in a parent or workspace folder (with its own DOGMA-PERMISSIONS.md) while the actual work happens in another repo. dogma (and credo's credo-dogma-mode.sh) therefore choose the file in this order:

1. The target of the action, when it is recognisable: a Bash command's git -C <dir> ..., a leading cd <dir> && ... or cd <dir>; ... (also inside ( ... )), or the edited file's own path (Write/Edit).
2. The credo pinned project (/credo:project, resolved like credo-config.sh resolve-project), when credo is installed. dogma does not need credo - without it this step is skipped. It is also skipped when the session folder lies inside that project anyway.
3. Upward from the current folder (normally the folder the session was started in) - the behaviour before this existed.

From the chosen folder the nearest DOGMA-PERMISSIONS.md upward counts (for a linked git worktree also the main checkout's file). A target, pinned project or current folder without a file of its own gets the session folder's file. The session folder is recorded at session start by the session-dir-record.sh SessionStart hook (per session id under ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/dogma/session-dirs/, found again through $CLAUDE_CODE_SESSION_ID; records older than 30 days are pruned), so inheritance still works when a Bash command ran cd <project> && ... first; without a record, or when the recorded folder is gone, $PWD counts as before.

Inheritance is a checkbox at the top of the <permissions> block, default on:

<permissions>
## Inheritance
- [x] (§r3nx) inherit permissions
...

When Claude works in this project from another folder (a parent or workspace folder with its own DOGMA-PERMISSIONS.md), every setting this file does not define is taken from that folder's file. Settings defined here always win. With [ ] only this file counts. A file without the checkbox behaves like [x].

Example: the session starts in ~/workspace (which has its own DOGMA-PERMISSIONS.md), and Claude runs git -C ~/workspace-projects/app commit -m .... Then app's file applies. If app's file allows git push but says nothing about git commit, the commit setting comes from ~/workspace's file (for example [?] = ask), and the hook message names that file. With - [ ] (§r3nx) inherit permissions in app's file only app's file counts, and the missing commit setting falls back to dogma's default (allowed).

Details:

• Inheritance goes per setting id: the applied file wins for every id it carries. A line without an id is matched by its old text within its own file, so an old file without ids still overrides the inherited setting it mentions.
• Test Commands are inherited per stage (a stage the file defines wins, a missing stage comes from the session folder's file). The Worktree files list is inherited as a whole when the file has none; otherwise the default list applies.
• permissions-summary.sh (and the dogma band) shows the effective, merged view; its JSON output carries an optional "source": {"<label>": "<file>"} key for inherited entries. The ## Inheritance switch itself is never listed.
• Env overrides for tests: DOGMA_SESSION_DIR (session folder and current folder; default the recorded session folder, else $PWD), DOGMA_CREDO_CONFIG (path to credo's credo-config.sh, or none to skip the pinned project).

Every setting in DOGMA-PERMISSIONS.md carries a fixed short id (§xxxx) (4 lowercase base36 characters) right after its checkbox, for example - [ ] (§8eyz) run ALL tests only at release. Parsed headings and list labels carry one too: ### Test Commands (§ly5v) and Worktree files (§47p9) (...). The id is the setting, the text is free:

• The same setting has the same id in every repo (fixed in the template, never random per repo).
• dogma's hooks and scripts and credo match the id first, anywhere in the <permissions> block - the subsection does not matter.
• Only when no line carries the id they fall back to the old heading + text match, so files without ids keep working unchanged.
• So a line can be reworded, translated or merged by /dogma:sync without the reader silently treating the setting as missing. Keep the id when you edit a line; /dogma:permissions adds missing ids when it updates an existing file.
• permissions-summary.sh (and the dogma band) never shows an id in its labels.

The registry with the reading script per id is plugins/dogma/docs/permission-ids.md. Script API: get_permission_mode and check_permission in scripts/lib-permissions.sh accept a spec "§xxxx|text pattern" (or "§xxxx" alone) wherever they accept a pattern; credo reads checkboxes without dogma via credo-dogma-mode.sh --id <id> <subsection> <pattern>.

Creates or updates DOGMA-PERMISSIONS.md interactively:

/dogma:permissions

The command asks about each permission with explanations and creates the file with your choices. This is the recommended way to configure dogma permissions, as it keeps them separate from your CLAUDE.md files.

scripts/permissions-summary.sh [--json] [dir] lists only the entries of the nearest DOGMA-PERMISSIONS.md that restrict Claude: [?] ask and [ ] / [0] deny ([x] auto entries are implicit and left out). The search starts in dir (default: the current directory) and walks upward. Each entry is labelled by its first code span (git add), else by its text without "May", "autonomously" and parentheses (for example delete files); a (§xxxx) id is never part of a label. Read-only; any renderer (a terminal, a status line, a Claude Code mod, another harness) can show the restrictions without parsing the file.

scripts/permissions-summary.sh --json
# {"file": "/path/to/DOGMA-PERMISSIONS.md", "ask": ["delete files"], "deny": []}

Exit codes: 0 summary printed, 4 no DOGMA-PERMISSIONS.md found (prints nothing), 1 bad argument.

The Testing and Final Verification checkboxes say WHEN tests run. An optional ### Test Commands subsection (inside <permissions>, under ## Workflow Permissions, after ### Final Verification) says WHICH command runs at which stage. It is language-agnostic and fully optional: a repo without it, or a stage without a line, behaves exactly as before (Claude decides).

### Test Commands (§ly5v)

Per-stage commands, all optional (missing line = Claude decides as before).
Optional branch filter in brackets: the stage only applies when its branch is listed
(commit: the branch committed on; push: the push target; build/all: the branch the work
is integrated into - local merge, push, or PR/MR into it). No filter = every branch.
- commit: `npm run lint`
- push [main, develop, stage]: `npx vitest related --run`
- relevant: `npx vitest related --run`
- build: `npm run build`
- all [main, stage]: `npm test`

The command is the first backtick span on the line. Only lines under the Test Commands heading count (until the next ##/### heading or </permissions>). The heading is found by its id (§ly5v) first (any heading level, any wording); only when no heading carries the id, by the text ### Test Commands. /dogma:permissions asks for each stage, suggesting commands detected from the repo's own files (package.json scripts, pytest/pyproject, .csproj/.sln, pubspec.yaml, go.mod, Makefile, git hooks, CI config) and branch filters from git branch -a; every stage may stay empty. The Final Verification checkbox run ALL tests only at release (default off) skips all on each merge and runs it once in the release commit, the normal commit that bundles several items with the version bump (never a tag or hosted release; those stay with the user).

Changelog fragments (changelog.d/): when the repo has a versioned changelog.d/ directory at its root, /dogma:versioning assembles the fragments at release - the bundling commit with the version bump, never a tag. It prepends a ## [X.Y.Z] - YYYY-MM-DD section built from the fragments to the existing CHANGELOG (CHANGELOG.md, CHANGELOG, CHANGES.md or HISTORY.md), keeping the repo's existing heading and subsection format (for example Keep a Changelog ### Added / ### Fixed; a towncrier-style type in the fragment name such as 42.fixed.md picks the subsection). When the format is unclear it asks first. The consumed fragments are removed in the same commit (README, .gitkeep and templates stay), respecting the delete setting §0lgy. A pure version-mismatch fix without a bump is not a release and leaves the fragments alone. Language-agnostic; without a versioned changelog.d/ nothing changes.

dogma never runs these commands automatically. Claude (and other tools such as credo) read them and run them at the stage:

scripts/test-commands.sh                 # file=..., commit=npm run lint, all=npm test, all_branches=main,stage, ...
scripts/test-commands.sh --json          # {"file": "...", "stages": {"commit": {"command": "npm run lint", "branches": null}, ...}}
scripts/test-commands.sh get all main    # npm test
scripts/test-commands.sh get all feature/x; echo $?   # 4 (filter does not match)

get <stage> [branch] [--dir dir] prints the command when the stage is defined and applies (no filter, the branch is in the filter, or no branch given). Exit codes: 0 ok, 4 no DOGMA-PERMISSIONS.md / no section / stage not applicable (prints nothing), 1 bad argument or unknown stage. permissions-summary.sh is unaffected (the section has no checkboxes).

Blocks destructive file operations: rm, del, unlink, rmdir, git clean

Always allowed (safe operations):

• git rm --cached (untrack but keep local file)
• git reset (unstage changes)

Three modes based on permission marker:

TO-DELETE.md format: Entries are written as checklist items (- [ ]), so Checklist Tracking automatically reminds about pending deletions.

BLOCKS package installation until verified:

npm install some-package

BLOCKED by dogma: dependency verification required

REQUIRED: Verify packages BEFORE installation!
1. Run: npm audit
2. (TBD) WebFetch: security scanning service URL

Worktree Mode (Hydra Integration):

When running in a Git worktree (e.g., via /hydra:spawn), different rules apply:

• Packages can only be installed if they exist in the main repo's lockfile
• Version must match exactly what's in the main repo
• Supports: npm/pnpm/yarn (package-lock.json, pnpm-lock.yaml, yarn.lock), pip (requirements.lock, poetry.lock, Pipfile.lock), cargo (Cargo.lock)

If lockfile not found or version mismatch:

BLOCKED in worktree: Package version mismatch with main repo.
Ask the main agent or user for approval.

BLOCKS bash commands, file reads, AND code searches that could expose tokens/credentials:

Blocked Bash commands:

• git remote -v / git remote --verbose / git remote show - tokens can be embedded in remote URLs
• env / printenv / export / set - dumps all environment variables
• Direct access to $GITHUB_TOKEN, $API_KEY, etc.
• Reading credential files via cat/head/tail (~/.netrc, .git-credentials, .env)
• git credential commands
• curl/wget with authorization headers

Also catches variations (v1.28.8+):

• Absolute paths: /usr/bin/env, /usr/bin/git remote -v
• Prefixed commands: sudo env, command env
• Subshells: bash -c "env"
• Piped commands: env | head, env | grep
• Chained commands: echo foo && git remote -v

Blocked Grep operations (v1.34.3+):

• Searching in sensitive files: .env, .netrc, .git-credentials, .npmrc, .pypirc, id_rsa, *.pem, *.key
• Prevents using the Grep tool to extract secrets from credential files

Blocked Read operations:

• Files with sensitive names: .env, .netrc, .git-credentials, .npmrc, .pypirc, id_rsa, *.pem, *.key
• Files containing token patterns (scanned before reading):
  • GitHub tokens (ghp_...)
  • OpenAI keys (sk-...)
  • Anthropic keys (sk-ant-...)
  • AWS keys (AKIA...)
  • Embedded URL tokens (x-access-token:...@)
  • Private keys: a -----BEGIN ... PRIVATE KEY----- line followed by the key body (a lone header line in docs or code is not a key)

Safe alternatives:

• Use git remote (without -v) to list remote names
• Use scripts/git-scope.sh for the owner/repo scope check: it prints only <host>/<owner>/<repo>, never the URL or credentials (the block message names its full path)
• scripts/git-remote-safe.sh url prints the remote URL without userinfo (no user:token@)
• Use [ -n "$VAR" ] to check if a variable is set without exposing its value
• Check credential file existence with [ -f ~/.netrc ]

Directory allowlist (v1.34.4+):

Set CLAUDE_MB_DOGMA_TOKEN_ALLOW_DIRS to a comma-separated list of directories whose files skip path-based name checks. Content scanning still applies - files are still checked for actual token patterns before reading.

{
  "env": {
    "CLAUDE_MB_DOGMA_TOKEN_ALLOW_DIRS": "/path/to/trusted-dir,/another/dir"
  }
}

CLAUDE_PLUGIN_ROOT is always allowed automatically (the plugin's own directory).

Safe dotenv variants (v1.34.4+):

These files are excluded from both secret detection and git-add protection:

• .env.example
• .env.sample
• .env.template

These are safe to commit as they contain placeholder values, not real secrets.

Blocks writing secrets to files:

• OpenAI API keys (sk-...)
• Anthropic API keys (sk-ant-...)
• AWS keys (AKIA...)
• JWT tokens
• Private keys
• Database connection strings
• GitHub tokens, Slack tokens, Stripe keys

Before Write/Edit operations, shows @-references to relevant rule files:

• @CLAUDE/CLAUDE.language.md - for all text files
• @GUIDES/ai-traces.md - for all files

Automatic language detection: If the file already exists, the hook detects whether it's in German or English and reminds Claude to maintain the existing language. The detection is a conservative heuristic. Quoted text and code (code blocks, code spans, quoted strings) are ignored, and German is only reported when several distinct German function words make up a meaningful share of the words and clearly outweigh English ones. An English file that quotes German examples stays English, and a bilingual file gets no language note rather than a wrong one. Being a heuristic, it can still misjudge very short or unusual texts.

After Write/Edit, warns about AI traces:

• Curly quotes: " " (U+201C, U+201D) - should be straight " (U+0022)
• Em-dashes: -- -- (U+2014, U+2013) - should be normal - (U+002D)
• Ellipsis: ... (U+2026) - should be three dots ...
• Smart apostrophes: ' ' ‚ (U+2018, U+2019, U+201A) - should be straight ' (U+0027)
• Emojis in code
• AI phrases in comments
• ASCII umlauts (fuer, koennen, ...) in .md / .txt / .rst files - German text only: the check runs only when the written content (or, for a short Edit snippet, the file) is detected as German by the same conservative heuristic; English, bilingual and other-language text is left alone

After WebFetch/WebSearch, warns about:

• "Ignore previous instructions" patterns
• "You are now..." role changes
• Fake system messages
• Override/jailbreak attempts
• Hidden/zero-width characters

Runs at the END of Claude's response (Stop Hook). Helps keep versions in sync.

Three modes:

Generic fallback features:

• Detects version mismatches across files
• Hints if versions were never bumped (still at 0.0.0, 1.0.0, etc.)
• Suggests creating CLAUDE.versioning.md for custom rules
• Supports: .yaml, .json, .toml, .py, .txt

Example CLAUDE.versioning.md:

When bumping versions, update BOTH files:
- `plugins/dogma/plugin.yaml`
- `plugins/dogma/.claude-plugin/plugin.json`

After a dogma update that adds something the user should act on, the user is told ONCE per repo, so nobody has to remember to look. Nothing in the repo is ever changed by the notice mechanism itself.

Two relevance layers:

1. The plugin author only adds a notice entry for changes that need user action. Most version bumps add none.
2. Each entry has an applies check script that decides whether it fits THIS repo. Repos where it does not apply never see it.

Adding a notice (plugin authors): append an entry to notices.json in the plugin root and ship a small read-only check script:

{
  "id": "dogma-test-commands",
  "since": "1.37.0",
  "text": "One or two sentences on what is new and why it matters.",
  "action": "/dogma:permissions",
  "applies": "scripts/notice-applies-test-commands.sh"
}

applies is a path relative to the plugin root; it runs with the repo directory as working directory and exits 0 when the notice applies (the example applies when a DOGMA-PERMISSIONS.md exists without a ### Test Commands heading). id uses only letters, digits, ., _, -.

Flow: the SessionStart hook hooks/notices-inject.sh runs scripts/notices-pending.sh --json and, when notices are pending, tells Claude about them (silent otherwise). Claude does not interrupt urgent work and asks at the first natural pause - via its Ask tool (AskUserQuestion), one question per notice, or in plain text when no Ask tool exists:

• Run - Claude runs the action and, after it completed, marks the notice seen.
• Later - nothing happens; the notice comes back next session.
• Never - the notice is marked seen and does not come back for this repo.

Running unattended/autonomously (no human present), Claude does not ask and leaves the notice pending.

Seen state is per repo and per profile: ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/dogma/notices-seen/<key>/<id> (empty files), where <key> is the first 16 hex chars of the sha256 of the absolute directory the notices are keyed to. Notices apply wherever an effective DOGMA-PERMISSIONS.md resolves (same resolution as the permission hooks: git toplevel of the session folder, else the credo pinned project, else the session folder itself - also outside git; own file, else the inherited session-folder file) and are keyed to that file's directory: the git toplevel for a repo with its own file (unchanged key), otherwise the file's directory, e.g. the session folder whose file a pinned project without its own file inherits, so the notice is shown once across both. The hook context and the mark command name that directory; run the action there.

scripts/notices-pending.sh [--json] [dir]   # pending notices (exit 4 = none)
scripts/notices-pending.sh mark <id> [dir]  # mark one seen for that repo

Optional toast: with the Claude Code band, a toast dogma: N update notice(s) - Claude will ask you shows for 12 s at session start while notices are pending (plugin notices and source broadcasts together).

Disable with CLAUDE_MB_DOGMA_NOTICES=false (also disables source broadcasts).

The owner of a dogma source (the template repo /dogma:sync pulls from: CLAUDE/, GUIDES/, DOGMA-PERMISSIONS.md, ...) can tell every repo that syncs from it something important ONCE, for example "the permissions now carry stable setting ids, run /dogma:sync". Nobody has to remember to look. Only hand-written entries in NOTICES.md at the source root are announced - there are no generic "files changed" notices.

NOTICES.md format (for source owners):

# Notices

Optional free text before the first entry (ignored).

## 2026-10-02 (§n001) Stable setting ids
Action: /dogma:sync
Every setting in DOGMA-PERMISSIONS.md now carries a fixed id (§xxxx).
Run a sync once so this repo gets them.

## 2026-10-20 (§n002) New review guide
GUIDES/review.md explains the new review flow. Nothing to run.

• One entry per ## heading. The heading needs a date YYYY-MM-DD and an id (§...) (letters, digits, ., _, -, up to 64 chars); their order in the heading is free, the remaining words are the title.
• Parsing is id-first: a heading without an id or without a valid date is ignored, and so is everything before the first entry. When an id appears twice, the first entry wins. Never reuse or renumber an id - a repo that marked n001 seen never sees an entry with that id again.
• Action: (optional, first one counts) names the command Claude offers to run, usually /dogma:sync. Without it the notice is information only (Claude offers "Got it" / "Later").
• All other lines are the text; they are joined into one paragraph, so keep it to a few sentences.
• Newest entries anywhere in the file are fine; old entries can stay - entries older than 90 days are skipped anyway.
• NOTICES.md is never synced into projects by /dogma:sync.

Delivery is identical to the plugin's update notices: the SessionStart hook tells Claude, Claude asks at the first natural pause with Run <action> / Later / Never (plain text without an Ask tool, never in autonomous mode), and the band toast (12 s) counts both kinds. Source notice ids carry the prefix src: (src:n001) so they never collide with plugin notice ids; notices-pending.sh mark src:n001 [dir] marks one seen. In notices-pending.sh output they have kind=source (plugin notices kind=plugin).

Which repos: only contexts that use dogma - an effective DOGMA-PERMISSIONS.md (own or inherited, also in non-git folders, see Seen state above) or a CLAUDE/ dir at the git toplevel - and never the source repo itself (when the source is a local path). Every entry the repo has not marked seen is shown, except entries older than CLAUDE_MB_DOGMA_NOTICES_MAX_AGE_DAYS (default 90, 0 = no limit), so a freshly set up repo is not flooded with history. A completed /dogma:sync marks pending broadcasts whose action is /dogma:sync seen.

Source and cache:

• The source is CLAUDE_MB_DOGMA_SOURCE: an https or ssh URL (including SSH host aliases such as git@github-work:owner/repo.git), a file:// URL, or an absolute local path. Unset means no broadcasts (the built-in default source is not polled).
• A local path is read directly, no clone.
• A URL is read through a shallow clone in ${CLAUDE_CONFIG_DIR:-~/.claude}/dogma/source-cache/<hash>/ (<hash> = first 16 hex chars of the sha256 of the source string; git hooks are off in that clone). It is refreshed with git fetch when the last check is older than 24 h - at most once a day per source, successful or not.
• The refresh runs in the background, so a session start never waits for the network; a new entry appears from the session after the fetch. CLAUDE_MB_DOGMA_SOURCE_FETCH=sync waits instead (max 15 s), off never fetches.
• A fetch can never block on credentials: 15 s timeout, GIT_TERMINAL_PROMPT=0, empty askpass, credential.interactive=never, ssh BatchMode=yes. Your normal git configuration (credential helpers, ssh config, host aliases) is used unchanged.
• Several git accounts (identity per folder): folder-based rules (includeIf "gitdir:...", per-account url.<alias>.insteadOf, core.sshCommand with an account key) would not match the cache dir. So the fetch reads exactly these keys from the effective config of the repo the session runs in - url.*.insteadOf and core.sshCommand (not pushInsteadOf, never credential.* or anything token-like) - and passes them to the cache git via GIT_CONFIG_COUNT/GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n; they are never printed or written into the cache clone. The cache, the daily throttle and the hint are per (source, identity), so a repo with a different identity gets its own daily attempt.
• Unreachable source (network, auth, missing path): silent. At most once a day per source Claude gets a short hint that the source is not reachable with the current git access and suggests a URL git reaches without prompts (e.g. an SSH host alias) or a local path. The hint never echoes the user info of a scheme URL (https://user@host/...).

scripts/source-cache.sh notices          # parsed NOTICES.md entries (TSV: id, action, date, text)
scripts/source-cache.sh refresh --force  # fetch now
scripts/source-cache.sh state-dir        # cache/state dir for (source, identity of the current repo)

In Claude Code builds with mods support, dogma ships hooks/band.tsx (listed under modules in hooks/hooks.json, state contract in types/index.d.ts). It draws a band above the prompt. It is optional and only a renderer: it runs permissions-summary.sh --json in the session's directory and shows the result. The enforcement hooks work exactly the same without it and in other harnesses.

• ◆ dogma (red with deny entries, yellow with only ask entries, green when nothing restricts) and one block per kind - deny (red) and ask (yellow) in a fixed column, the entries packed beside it; all auto when nothing restricts. Hidden when no DOGMA-PERMISSIONS.md is found.
• Changes flash for 6 s: an entry that switched kind in fuchsia, a newly restricted one in white, a removed one dimmed and struck through.
• When a dogma hook blocks a tool call, a ⛔ blocked <tool>: <reason> row shows for 15 s (blinking for the first 6 s), plus a toast (6 s). dogma's hook made the decision; the band only shows it.
• With the credo band installed, the dogma band sits below credo's and hides at credo's open only preset. dogma does not depend on credo: without credo the band always shows.
• Refresh: on session start, after every tool call, at turn end and every 10 s.
• At session start a toast hints at pending update notices and source broadcasts (12 s).

Dogma hooks are worktree-aware and work seamlessly with the Hydra Plugin for parallel agent execution.

Hooks with special worktree behavior:

Rationale:

• Worktrees are isolated environments - git conflicts are impossible
• Agents in worktrees should work autonomously without blocking
• Security-critical checks (secrets, AI files) remain active everywhere
• Dependency lockfile matching ensures reproducible builds

A fresh git worktree only contains versioned files. Excluded files that agents need - CLAUDE.md, CLAUDE/, GUIDES/, DOGMA-PERMISSIONS.md, the .credo/ tree - are missing there, so agents would miss rules and items. The ### Hydra subsection of the <permissions> block configures this:

### Hydra

Parallel work (only if Hydra available, otherwise sequential):
- [x] (§xw1i) use Hydra for 2+ independent tasks

Worktree cleanup at item close ([x] = remove without asking, [?] = ask each time, [ ] = never):
- [x] (§36ch) clean up merged worktrees automatically

Worktree files (§47p9) (excluded files only; versioned files come with git checkout):
- link: CLAUDE.md
- link: .credo/
- copy: .env.local

• Worktree files - found by its id (§47p9) first (anywhere in <permissions>, any wording), else by the text "Worktree files" inside ### Hydra. link (symlink to the main checkout) is the default kind; a line without a kind is a link. copy only where given, for files that must differ per worktree. Paths are relative to the repo root; absolute paths and .. are rejected. When the list is missing or empty, the default applies: link CLAUDE.md, CLAUDE/, GUIDES/, DOGMA-PERMISSIONS.md and .credo/.
• Applying the list is done by hydra's scripts/worktree-setup.sh (and credo's identical credo-worktree-setup.sh) right after git worktree add: paths missing in the main checkout are skipped, versioned paths are skipped with a warning, untracked paths that are not ignored in the main checkout are skipped too (a git add -A in the worktree would commit the link; read them in the main checkout), a directory with tracked files inside is recursed into and only its untracked, ignored entries are linked, and an existing path is never overwritten.
• clean up merged worktrees automatically - default [x] in the template (set-and-forget). credo removes worktrees whose branch is fully merged and that have no changes to tracked files whenever an item is closed. [?] asks each time, [ ] never. A file without this checkbox behaves as [?], because older files predate the setting.
• use Hydra for 2+ independent tasks - with credo installed, [x] (and hydra installed) makes credo use hydra's worktree flow for parallel code tracks automatically, [?] asks once per batch, [ ] uses plain git worktree add.

dogma only reads the list:

scripts/worktree-files.sh            # link CLAUDE.md / link .credo/ / copy .env.local (one "<kind> <path>" per line)
scripts/worktree-files.sh --json     # {"file": "...", "source": "configured", "entries": [{"kind": "link", "path": "CLAUDE.md"}, ...]}

dir (optional last argument) is where the upward search for DOGMA-PERMISSIONS.md starts. Exit codes: 0 list printed (configured or default), 1 bad argument. Invalid entries are skipped with a warning on stderr. permissions-summary.sh is unaffected: the lines live under ## Workflow Permissions, where checkboxes are switches.

• jq - JSON processor (install: sudo apt install jq)

claude plugin marketplace add Marcel-Bich/marcel-bich-claude-marketplace
claude plugin install dogma@marcel-bich-claude-marketplace

All hooks can be disabled via environment variables. Default is true (enabled).

# Master switch - disable ALL dogma hooks at once
export CLAUDE_MB_DOGMA_ENABLED=false

# Disable specific hooks
export CLAUDE_MB_DOGMA_PROMPT_REMINDER=false
export CLAUDE_MB_DOGMA_CHECKLIST_TRACKING=false
export CLAUDE_MB_DOGMA_GIT_ADD_PROTECTION=false
export CLAUDE_MB_DOGMA_GIT_PERMISSIONS=false
export CLAUDE_MB_DOGMA_FILE_PROTECTION=false
export CLAUDE_MB_DOGMA_DEPENDENCY_VERIFICATION=false
export CLAUDE_MB_DOGMA_TOKEN_PROTECTION=false
export CLAUDE_MB_DOGMA_SECRETS_DETECTION=false
export CLAUDE_MB_DOGMA_WRITE_EDIT_REMINDER=false
export CLAUDE_MB_DOGMA_POST_WRITE_VALIDATE=false
export CLAUDE_MB_DOGMA_PROMPT_INJECTION=false
export CLAUDE_MB_DOGMA_PROMPT_INTERVENTION=false
export CLAUDE_MB_DOGMA_VERSION_SYNC=false
export CLAUDE_MB_DOGMA_PRE_COMMIT_LINT=false
export CLAUDE_MB_DOGMA_LINT_ON_STOP=false

# Feature flags (not hooks)
export CLAUDE_MB_DOGMA_SKIP_LINT_CHECK=true   # Skip pre-commit lint (set after running /dogma:lint)
export CLAUDE_MB_DOGMA_AUTO_FORMAT=false      # Disable auto-formatting in /dogma:lint

# Additional toggles
export CLAUDE_MB_DOGMA_SUBAGENT_SUGGESTION=false
export CLAUDE_MB_DOGMA_SUBAGENT_ENFORCEMENT=false
export CLAUDE_MB_DOGMA_RESET_INTERVAL=2              # Prompts between state resets (0 = disable)
export CLAUDE_MB_DOGMA_PULL_BEFORE_PUSH=false
export CLAUDE_MB_DOGMA_CHECKLIST_REMINDER=false
export CLAUDE_MB_DOGMA_REVIEW_TRIGGER=false
export CLAUDE_MB_DOGMA_MODEL_POLICY=false
export CLAUDE_MB_DOGMA_NOTICES=false          # No update notices / source broadcasts at session start

# Dogma source (see Sync Command and Source broadcasts)
export CLAUDE_MB_DOGMA_SOURCE=git@github-work:owner/dogma-source.git  # or https URL, file:// URL, absolute path
export CLAUDE_MB_DOGMA_NOTICES_MAX_AGE_DAYS=90       # Skip older source broadcasts (0 = no limit)
export CLAUDE_MB_DOGMA_SOURCE_FETCH=background       # background (default) | sync | off

# Model Policy behavior (these control HOW model enforcement works, not IF)
export CLAUDE_MB_DOGMA_FORCE_PARENT_MODEL=false     # Only enforce for Anthropic plugins (default: true = all plugins)
export CLAUDE_MB_DOGMA_BUILTIN_INHERIT_MODEL=false  # Don't force parent model on built-in agents
export CLAUDE_MB_DOGMA_ALLOW_MODEL_DOWNGRADE=true   # Allow explicit model downgrades below parent

# Enable debug logging to /tmp/dogma-debug.log
export CLAUDE_MB_DOGMA_DEBUG=true

When hooks cause errors, enable debug logging:

CLAUDE_MB_DOGMA_DEBUG=true claude

All hook executions are logged to /tmp/dogma-debug.log with full bash trace (set -x). View logs: tail -f /tmp/dogma-debug.log

Edit commands/sync.md and update DEFAULT_SOURCE to set your default repository.

The plugin uses a differentiated enforcement strategy:

1. Run /plugin in Claude Code
2. Go to Marketplaces tab and select "Update marketplace"
3. Go to Installed tab and update the dogma plugin
4. Restart Claude Code

This software is provided "as is", without warranty of any kind. Use at your own risk.

• The author is not responsible for any issues arising from use of this plugin
• You are solely responsible for ensuring this plugin works with your setup
• No support or maintenance is guaranteed

MIT - See LICENSE for full terms.

See also: Signal | Limit | All Plugins