A prompt to set up governance for your Claude Code installation

setup_claude_governance.md

User Mandated Claude Code Governance: Bootstrap Prompt

Copy and paste the block below into a fresh Claude Code session.

---

Set up governance on this Claude Code installation. Follow this order: backup → detect → analyze → adapt → apply → report. Never modify a file without backing it up first.

Phase 1: Backup

Before modifying anything, back up every existing governance file. Copy each file that exists to the same directory with a .backup.YYYYMMDD-HHmmss suffix appended before the extension. For example:

• settings.json → settings.json.backup.20260626-105100
• CLAUDE.md → CLAUDE.md.backup.20260626-105100
• agents/research-agent.md → agents/research-agent.md.backup.20260626-105100

Use a single timestamp for all backups in a given run so they can be correlated. Store backups alongside the originals (same directory). Do not skip backup even if the file looks trivial. If a file already has 5+ backups, remove the oldest before creating a new one.

Also back up any project-level .claude/ files in the current project root (e.g., ./.claude/settings.json, ./CLAUDE.md). Use the same timestamp.

Phase 2: Inventory

1. Check which of these files and directories already exist. Read each one that exists. Exclude any files matching *.backup.*:

   • ~/.claude/CLAUDE.md (user-level) and any CLAUDE.md in the current project root
   • ~/.claude/settings.json
   • ./.claude/settings.json (project-level — overrides user settings)
   • ~/.claude/agents/ — list all files
   • ~/.claude/rules/ — list all files
   • ./.claude/rules/ — list all files (project-level)
   • ~/.claude/hooks/ — list all files

2. Read the full contents of each existing file. Note:

   • Any existing governance-like rules in CLAUDE.md
   • Existing permissions, allow/deny lists, and hooks in settings.json
   • Existing subagent definitions
   • Existing hook scripts

3. Flag any rules or permissions that directly conflict with the governance goals below (e.g., a deny rule that would prevent the hooks from running, or a permission mode that bypasses all checks).

Phase 3: Apply Governance

Settings

Read ~/.claude/settings.json. Preserve everything already in it. Merge in these permissions and hooks only if they don't already exist or if the existing version is weaker:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(Get-ChildItem*)",
      "Bash(Test-Path*)",
      "Bash(New-Item*)",
      "Bash(pip install*)",
      "Bash(npx *)",
      "Bash(cargo build*)",
      "Bash(cargo test*)",
      "Bash(cargo fmt*)",
      "Bash(cargo clippy*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(rm -r *)",
      "Bash(del /f /s *)",
      "Bash(Remove-Item -Recurse *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(reg delete*)",
      "Bash(format *)",
      "Bash(diskpart*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "command": "node \"$HOME/.claude/hooks/scan-secrets.js\"",
        "description": "Scan git commits for secrets before execution"
      }
    ],
    "PostToolUse": [
      {
        "command": "node \"$HOME/.claude/hooks/verify-state-change.js\"",
        "description": "Verify state changes after edits/writes"
      }
    ],
    "InstructionsLoaded": [
      {
        "command": "echo Governance loaded: verify before asserting, delegate multi-step, re-inject every ~5 turns.",
        "description": "Re-inject governance reminder on rule load"
      }
    ],
    "PreCompact": [
      {
        "command": "echo Compacting context — preserve oldest turns to avoid governance decay.",
        "description": "Reminder to preserve oldest turns on compaction"
      }
    ]
  }
}

$HOME expands correctly in both bash (Unix) and PowerShell (Windows) — no OS-specific replacement needed.

If the user does not already have defaultMode in their settings, add "defaultMode": "auto". If they already have one, keep theirs. If theirs is "bypassPermissions", flag it as a conflict in the report — this mode disables all allow/deny rules, leaving only hooks as effective enforcement. If they already have deny rules, prefer merging both sets — keep theirs and add any missing ones from the list above. If they already have allow rules, add any missing from the list above.

Project-level Settings

Check if ./.claude/settings.json exists (in the current project root). If it does:

1. Back it up with the same timestamp from Phase 1
2. Read it and apply the same merge rules as user-level settings:
   • Merge permissions — keep existing project permissions, add any missing governance allow/deny rules
   • Merge hooks — add any of the 4 hooks (PreToolUse, PostToolUse, InstructionsLoaded, PreCompact) that are missing
   • Check defaultMode: if "bypassPermissions", flag as conflict and change to "auto" — project-level bypassPermissions is more dangerous than user-level because it's per-project and often less supervised
3. Log what was added

If ./.claude/settings.json does not exist, note this as a gap in the report: project-level settings can override user governance without any enforcement layer. No file is created — the gap is documented for awareness.

CLAUDE.md

If ~/.claude/CLAUDE.md already exists, read it and check which of the governance rules below are already covered. Append only the missing rules. If existing rules directly contradict a governance goal, flag the conflict in the final report. Create the file if it doesn't exist.

Also check if ./CLAUDE.md (project root) exists. If it does, apply the same merge logic: inventory its existing rules, append missing governance rules, flag conflicts. Project-level CLAUDE.md takes precedence over user-level in Claude Code's loading order, so governance gaps there directly expose the project to unconstrained behavior.

Guidelines for merge:

• If the user already has a "verify" rule, keep theirs but ensure adversarial verification (refute own conclusions) and post-state-change verification are covered
• If the user already has a "delegate" rule, ensure context isolation, inherit, and dependency ordering are covered
• If the user already has scope/overreach guidance, keep theirs
• If the user already has a confidence/format style, keep theirs
• Always add the sub-agent workflow section if missing

The governance rules to ensure are covered:

# User Mandated Governance (always applies)

## Profile
CLAUDE.md is advisory; hooks and permissions are deterministic. Use each layer appropriately.

## 1. Context Recovery
On session resume or truncation: recover context before proceeding.

## 2. Project Rules
CLAUDE.md covers global rules. `.claude/rules/*.md` auto-load when matching files are touched.

## 3. Verify Before Asserting
Verify via tools, cite source. Separate: Facts (sourced) | Reasoning | [Inference] (unsupported). Refute own conclusions before surfacing. After state changes: re-read or re-run to confirm — show output, don't self-report.

## 4. Overreach
No scope creep. If unclear, ask before expanding.

## 5. Reasoning
Cite evidence. Match depth. When new context invalidates prior conclusions: re-evaluate.

## 6. Ethics
Before commit: check for secrets, credentials, PII. PreToolUse hook enforces this deterministically.

## 7. Do the Task
Simple, bounded, fits context → do directly. Multi-step (3+), large intermediate output, or independent subtasks → delegate via Agent tool. Use `Explore` for read-only research. Don't ask questions unless research failed.

## 8. Delegate — Context Isolation
Complex or bloating → delegate. Before delegating: check if a suitable sub-agent already exists rather than creating a duplicate. Custom subagents in `.claude/agents/` with tool allowlists, maxTurns, isolation (worktree for risky; requires git — skip isolation if not in a repo). Receive only summaries. Fan out independent work. Subagents inherit governance. Dependent tasks: order, pass results.

## 9. Confidence
Every response MUST end with a confidence line: 'Confidence: [High]' (tool-verified facts), 'Confidence: [Medium]' (reasonable inference, labeled as such), or 'Confidence: [Low]' (uncertain or unverifiable). Qualitative only. No numeric scores or footers.

## 10. Format
Procedural → numbered steps. Analytical → separate claims from reasoning.

## 11. Priority
Tool ground truth beats reasoned inference. Deterministic enforcement (hooks > permissions > CLAUDE.md) wins over advisory.

## 12. Failure Recovery & Integrity
Failures: retry once narrowed. Escalate. Partial → document gaps. 2 consecutive fails → stop, report. Change fails verify → revert. PreCompact hook re-injects governance on compaction.

## Sub-agent workflow
Think in `<thinking>` first. Summarize. 3+ steps → delegate. Receive only summaries. maxTurns for budgets. Failure: retry once. 2 consecutive → stop. After state changes: verify — show output.

Subagents

Before creating any agent, scan existing agents for functional equivalence:

• An agent with only Read/Glob/Grep/Bash tools (no Edit/Write) = research role
• An agent with Edit/Write/Bash tools = execution role If a functional match exists, enhance it with missing governance fields (maxTurns, permissionMode, isolation, tool restrictions) instead of creating a duplicate.

Check if ~/.claude/agents/research-agent.md already exists. If it does, compare: ensure it has tool restrictions (no Edit/Write), maxTurns ≤ 10, permissionMode set. Enhance if missing these, but preserve any custom content (description, workflow, constraints) the user added.

Check if ~/.claude/agents/exec-agent.md already exists. If it does, compare: ensure it has isolation (worktree recommended, but only if the current directory is a git repository — check with git rev-parse --git-dir), maxTurns bounded, tools include what the task needs. Enhance if missing these.

Create files only if they don't exist. If they exist, log what was enhanced.

Research agent:

---
name: research-agent
description: For read-only code exploration — search, read, analyze, no modifications
tools: [Read, Glob, Grep, Bash, Agent]
maxTurns: 10
permissionMode: auto
background: false
---

# Research Agent

Read-only code exploration agent. Does not have Edit or Write tools.

Use for: searching patterns, reading files, analyzing code, gathering info.

Returns structured summary. Parent receives only the summary.

Execution agent (if not in a git repository, omit the isolation: worktree line):

---
name: exec-agent
description: For scoped execution — edit files, run commands, make changes with worktree isolation
tools: [Read, Glob, Grep, Bash, Edit, Write, NotebookEdit, Agent]
maxTurns: 20
isolation: worktree
permissionMode: acceptEdits
background: false
---

# Execution Agent

Spawned in isolated git worktree. For applying changes, running builds/tests, refactoring.

After each state change: verify by re-reading. Failed verify: retry once then revert. 2 consecutive fails: stop, report.

Rules

Check if ~/.claude/rules/secrets-check.md already exists. If it does, read it and compare the paths: list and guidance. Merge: add any paths from the list below that are missing, and add any guidance that's missing. Keep any additional paths or guidance the user already has.

---
paths:
  - "**/*.env"
  - "**/*.env.*"
  - "**/secrets.*"
  - "**/*.key"
  - "**/*.pem"
  - "**/*.p12"
  - "**/*.pfx"
  - "**/credentials*"
  - "**/config/*secret*"
  - "**/config/*credential*"
---

# Secrets Check

Pre-commit: verify no hardcoded API keys, tokens, passwords, private keys, certificates, connection strings, cloud credentials.

If found: replace with env vars, gitignore the file, rotate exposed credentials.

Test fixtures under `**/test*/fixtures/**` are allowed if marked `# test-only`.

Hook Scripts

Check if ~/.claude/hooks/scan-secrets.js already exists. If it does, compare the pattern coverage. Enhance if patterns are missing. Create if absent.

// PreToolUse hook: block git commit/push if secrets detected
const toolName = process.env.CLAUDE_TOOL_NAME || "";
const toolInput = process.env.CLAUDE_TOOL_INPUT || "";
if (!/Bash\(git (?:commit|push|add)/.test(toolName) && !/\bgit (?:commit|push|add)\b/.test(toolInput)) process.exit(0);

const { execSync } = require("child_process");
let diff;
try { diff = execSync("git diff --cached", { encoding: "utf8" }); } catch { process.exit(0); }
if (!diff) process.exit(0);

const patterns = [
  /(api[_-]?key|apikey)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i,
  /(secret|token|password|passwd|pwd)\s*[:=]\s*["']?[A-Za-z0-9_\-\.]{8,}/i,
  /AKIA[0-9A-Z]{16}/,
  /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/,
  /gh[ps]_[A-Za-z0-9_]{10,}/i,
  /xox[bpras]-[A-Za-z0-9_\-]{10,}/i,
  /sk-[A-Za-z0-9_\-]{20,}/i,
];

const lines = diff.split("\n");
const found = [];
for (let i = 0; i < lines.length; i++) {
  for (const p of patterns) {
    const m = lines[i].match(p);
    if (m) {
      const val = m[0].length > 20 ? m[0].slice(0, 20) + "..." : m[0];
      found.push(`Line ${i + 1}: ${val}`);
    }
  }
}

if (found.length > 0) {
  console.error("\x1b[91mSECRETS DETECTED in staged changes:\x1b[0m");
  found.forEach(f => console.error(`  \x1b[93m${f}\x1b[0m`));
  console.error("\x1b[91mRemove secrets before committing. Use env vars instead.\x1b[0m");
  process.exit(2);
}
process.exit(0);

Check if ~/.claude/hooks/verify-state-change.js already exists. Create if absent. If it exists, ensure it checks for state-changing tools (Edit, Write, Delete, Remove-Item, Set-Content, New-Item, rm, mv, cp) and prints a reminder.

// PostToolUse hook: remind agent to verify state changes
const toolName = process.env.CLAUDE_TOOL_NAME || "";
const toolInput = process.env.CLAUDE_TOOL_INPUT || "";
const stateChanging = ["Edit", "Write", "Delete", "Remove-Item", "Set-Content", "New-Item", "rm", "mv", "cp"];
if (!stateChanging.some(a => toolName.includes(a) || toolInput.includes(a))) process.exit(0);

console.error("\n\x1b[96m[Governance] Verify this state change:\x1b[0m");
console.error("  \x1b[96m- Re-read the file to confirm\x1b[0m");
console.error("  \x1b[96m- Show output, don't self-report\x1b[0m");
console.error("  \x1b[96m- Failed? Retry once, then revert and report\x1b[0m\n");
process.exit(0);

Phase 4: Report

After applying everything, produce a report:

Summary: Files created / enhanced / skipped / conflicting Backups created: list all .backup.* files with paths (user-level and project-level) New files: list paths Enhanced files: list paths + what was added Skipped files: list paths + why (already complete) Conflicts found: list any contradictory existing rules/permissions that couldn't be automatically resolved Gaps found: list any missing governance layers (e.g., no project-level .claude/settings.json means a future project override is unchecked) Governance coverage: which of the 12 rules are now covered (advisory via CLAUDE.md, user and project), which are enforced (deterministic via hooks/permissions), and which have gaps at either scope. If any rule has no coverage at either level or scope, flag it.