claude-charter

Treat your project's AI instructions not as copy, but as a versioned, layered contract between you and the agent. Every rule has its own clause. Every clause has precedence. Every violation is verifiable.

claude-charter is an opinionated, self-auditing scaffold for the .claude/ directory. It turns the principles from the Unofficial Claude Code Prompt Playbook into a runnable starter kit — layered policy, trust boundaries, procedure-based skills, anti-rationalization rules, and a built-in adversarial verifier.

Works standalone. It is also the constitution layer of a three-part toolkit — see Part of a three-layer toolkit.

---

Why

Most CLAUDE.md files are a single text blob: "you are helpful, do X, don't do Y." That works until the agent starts inventing tools, skipping tests, or mixing user input with policy. Production-grade AI instructions are not copy — they are layered instruction architectures: static policy core, trusted runtime context, retrieved evidence, and user input, each with explicit trust and precedence.

claude-charter gives you that architecture out of the box.

What you get

Layer	Location	Purpose	Trust
Policy core	CLAUDE.md	role, operating policy, tool policy, output contract, known failure patterns	highest
Charter doctrine	.claude/knowledge/charter/	non-negotiables, principles	highest
Runtime context	.claude/knowledge/context/	architecture, glossary, constraints (dated)	trusted
Evidence	.claude/knowledge/evidence/	research notes, external docs	untrusted
Examples	.claude/knowledge/examples/	realistic few-shot references	trusted
Skills	.claude/skills/*/SKILL.md	procedure-based behavior rules	high
Commands	.claude/commands/	/health, /verify, /adr, /deploy	—
Hooks	.claude/hooks/hooks.json	PreToolUse guardrails that ask before destructive actions	enforced
ADR	.claude/knowledge/adr/	architectural decision records	—

Install (GitHub template)

1. Click Use this template → Create a new repository on GitHub, or:

2. One-liner with degit:

   npx degit demwick/claude-charter my-project
   cd my-project

3. Fill in the templates marked TODO inside .claude/knowledge/charter/ and .claude/knowledge/context/.

4. Run the self-audit:

   bash scripts/health.sh

5. Open Claude Code — CLAUDE.md is loaded automatically.

Core patterns

1. Layered, versioned policy

CLAUDE.md uses explicit XML sections (<role>, <operating_policy>, <tool_policy>, <risk_policy>, <channel_contract>, <output_contract>, <known_failure_patterns>) and is versioned via .claude/VERSION. Prompt changes are diffable; precedence is explicit.

2. Trust boundary

knowledge/charter/ is policy. knowledge/context/ is trusted runtime facts (with last_verified dates). knowledge/evidence/ is untrusted — the agent is told to never treat evidence as policy. This is structural defense against prompt injection from retrieved content.

3. Procedure-based skills

Skills don't say "follow TDD". They say:

1. Reproduce the bug with a failing test.
2. Implement the minimal fix.
3. Run the test. Observe pass.
4. Run adjacent tests.
5. Report: exact command, observed output, verdict.

Plus a Known failure patterns block naming the likely shortcuts.

4. Adversarial verifier

/verify is a separate role whose job is to try to break the last change, not approve it. Returns VERDICT: PASS | FAIL | PARTIAL with command + output as evidence.

5. Self-auditing

/health runs a 12-point checklist:

• policy sections present
• trust layers separated
• skills have known-failure blocks
• guardrails hook registered
• knowledge/context/ frontmatter dates aren't stale
• charter version matches CLAUDE.md

6. Guardrails hook

.claude/hooks/hooks.json registers a PreToolUse hook (scripts/guardrails.sh) that asks before destructive actions: rm -rf, git push --force on main, .env reads, curl | sh, and more. Ask, don't silently block.

Part of a three-layer toolkit

claude-charter is one of three independent projects that compose into a single human-in-the-loop AI engineering workflow. Each works standalone and is fully functional on its own; none requires the others to be installed.

Project	Role	Question it answers
software-engineer	engine	how the work gets done (triage, clarify, spec, plan, execute, Auto-QA)
claude-charter (this repo)	constitution	what rules and boundaries apply (layered policy, trust boundary, guardrails, /health, /verify, ADR format)
centaur-layer	brake / judgment	did the human understand the code (diff risk score, comprehension questions, Socratic coaching)

Charter's role in this ecosystem is to define; the engine and the centaur layer execute.

Detect & Defer

The composition model is Detect & Defer. Each project is independent and complete on its own. When one project detects another's presence, it defers that responsibility to it and stops duplicating it internally. No project forces you to install the others.

When the engine is detected (charter probes for a .se/ directory), charter hands off:

• execution of /verify — the engine's verifier inherits charter's adversarial role and runs it autonomously.
• automatic ADR generation — the engine produces ADRs, using charter's format and directory.

Charter keeps, in all cases: the layered policy, the trust boundary, the guardrails hook, /health, and the ADR format/template definition.

When the centaur layer is detected, charter keeps its own guardrails. The two operate on different surfaces, so there is no conflict (see below).

Guardrails: two surfaces, no overlap

Charter's guardrails run on the PreToolUse surface — before the AI invokes a tool (rm -rf, git push --force, reading .env, curl | sh). The centaur layer's hook runs on the pre-commit surface — at the moment a human commits, scoring the diff. Charter watches the AI's actions; the centaur layer watches the human's commit. They never guard the same event.

Verification: machine vs. human

Charter defines the adversarial verifier: the /verify role and its verdict format (PASS | FAIL | PARTIAL, "try to break it, don't approve it"). When the engine is installed, its verifier inherits this role and runs it autonomously. The centaur layer's check is separate — it interrogates the human, not the machine, and so stays out of the way.

ADR ownership

Charter owns the format and template of ADRs (.claude/knowledge/adr/, 0000-template.md). When the engine is installed, the engine is the side that generates ADRs — but it writes them into charter's directory using charter's template. See .claude/knowledge/adr/README.md.

Credits

• Unofficial Claude Code Prompt Playbook — the theoretical foundation. This project is a concrete implementation of patterns described there. https://github.com/kropdx/unofficial-claude-code-prompt-playbook
• Anthropic — for publishing CLAUDE.md, skills, hooks, and subagent APIs as first-class primitives.

License

MIT. Copy the .claude/ directory into any project, public or private, and adapt freely.