claude-charter

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

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.

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

Boundaries and version compatibility are defined canonically in ecosystem-contract.md. This section summarizes; the contract governs. To install the toolkit together, see the claude-engineering-suite marketplace (charter installs separately as a template).

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.