dotclaude: The Open-Source Governance Layer for AI-Assisted Development

You finish a great Claude Code session. A solid PR-review workflow. A debugging loop that actually finds root causes. A deploy checklist you trust. You close the terminal.

Next week, starting fresh, you've lost all of it. The assistant has no memory of how you like to work. You re-explain the worktree convention. You re-explain the test-plan format. You re-explain why --force-push on main is never OK.

Now scale that problem to a team. Five engineers using Claude Code, each with their own tricks, no shared floor of discipline. PRs land with different review depths. Audits have no structure. Some sessions produce hallucinated "fixes" that never touched the real code path. Specs drift from implementation and nobody notices until something breaks in prod.

dotclaude is an MIT-licensed project that solves both problems from the same codebase.

Two problems, one repo

The project has a dual-persona monorepo layout (ADR-0001). That sounds architectural, but it maps to two very different users:

• The individual developer who wants a portable skills library wired into every Claude Code session on their laptop.
• The engineering team that wants a governance CLI enforcing spec-backed PRs, skill-manifest integrity, and drift detection in CI.

Both paths are backed by the same skills, the same slash commands, the same CLAUDE.md rules. Neither path requires the other. You can use one, both, or swap from one to the other as your needs change.

Path 1: skills & commands in every session

For the individual path, the install is three lines:

git clone https://github.com/kaiohenricunha/dotclaude.git ~/projects/dotclaude
cd ~/projects/dotclaude
./bootstrap.sh

bootstrap.sh symlinks commands/, skills/, and CLAUDE.md into ~/.claude/. From that point, every Claude Code session in every repo has access to the full library. The highlights:

• Cloud & IaC specialists — the aws-specialist, gcp-specialist, azure-specialist, kubernetes-specialist, terraform-specialist, terragrunt-specialist, pulumi-specialist, and crossplane-specialist skills auto-trigger when you mention the relevant technology. Saying "review the IAM trust policy on the prod account" is enough.
• Slash commands for real PR work — /pre-pr runs a simplify + security-review + full-test-suite gate before you open the PR. /review-pr <N> walks 14 steps: fetch comments, validate each one, apply fixes in an isolated worktree, run the test plan, resolve threads. /review-prs <N1> <N2> ... dispatches one sub-agent per PR in parallel, up to six concurrent, and aggregates results into a table.
• Debugging disciplines — /ground-first <subject> forces a read-before-edit pass with file:line citations before any change is proposed. /fix-with-evidence <issue> enforces a Reproduce → Fix → Verify → PR loop.
• Analysis docs — /create-audit, /create-inspection, and /create-assessment produce evidence-backed markdown documents in docs/audits/, docs/inspections/, and docs/assessments/ respectively. Every claim cites a file, a line, or command output.
• Cross-machine handoff — /handoff push claude latest scrubs secrets and uploads a digest to a private GitHub gist. On another machine: /handoff pull latest. Your Windows/WSL session continues on Linux without re-explaining context.

The CLAUDE.md file installs a global rule floor alongside the skills: no pushing to main without explicit instruction, no force-pushing another session's branch, no --no-verify or --no-gpg-sign, full test suite before merges that touch protected paths, and a spec-coverage contract enforced at PR time.

To stay current: ./sync.sh pull (bootstrap path) or dotclaude sync pull (npm path) re-bootstraps from the latest main. No npm required for the bootstrap path.

Path 2: the governance CLI

For the team path, there's a zero-runtime-dependency npm package:

npm install -g @dotclaude/dotclaude
dotclaude bootstrap

That installs the same skills library but also gives you a set of validators designed for CI:

• dotclaude-validate-specs — audits spec contracts, catches dependency cycles.
• dotclaude-check-spec-coverage — the PR-time gate. Any PR that touches a protected path (defined in docs/repo-facts.json) must carry a Spec ID: header or a ## No-spec rationale section. No loophole.
• dotclaude-check-instruction-drift — detects stale CLAUDE.md and README entries.
• dotclaude-detect-drift — flags commands that have diverged from origin/main for 14+ days.
• dotclaude-doctor — self-diagnostic across env, facts, manifest, specs, drift, hooks.

Every bin honors --help, --version, --json, --verbose, --no-color. Exit codes follow the {0, 1, 2, 64} convention (ADR-0013), with 64 matching BSD EX_USAGE. Every failure surfaces as a structured ValidationError with a stable .code (ADR-0012), so your CI scripts branch on classes of failure instead of grepping strings.

There's also a Node API for teams that want to build their own gates:

import {
  createHarnessContext,
  validateSpecs,
  ERROR_CODES,
  EXIT_CODES,
} from "@dotclaude/dotclaude";

const ctx = createHarnessContext();
const { ok, errors } = validateSpecs(ctx);
if (!ok) process.exit(EXIT_CODES.VALIDATION);

Need a scaffold for a fresh repo?

npx dotclaude-init --project-name my-project --project-type node

That writes .claude/settings.json, the skills manifest, a destructive-git guard hook, three GitHub Actions workflows (validate-skills, detect-drift, ai-review), and a spec stub. A green dotclaude-doctor from a cold start.

A quick taste

After bootstrap, pick a real repo and try:

# Read before you touch anything.
/ground-first auth token refresh race condition
# → grounded analysis with file:line citations, no edits proposed

# Fix a reported bug with a full evidence loop.
/fix-with-evidence 140
# → reproduces, fixes, verifies, opens a PR — all with proof

# Deep AWS IAM review.
/aws-specialist review IAM policies in the production account
# → structured report: least-privilege gaps, trust-policy findings, remediations

# Batch-triage every open Dependabot PR.
/dependabot-sweep
# → parallel sub-agents annotate risk; safe bumps merged automatically

Every command is context-aware. It reads your repo's files, git history, CI state, and PR body. It cites evidence. It never pushes without permission.

Why bother with governance at all

The case for spec-driven development gets stronger the more AI you put into the loop. An assistant that writes code fast enough to outrun human review is a liability unless the rules of the game are encoded somewhere machine-readable. docs/specs/ becomes the contract. Protected paths become the enforcement surface. A PR gate that says "touched this path → show me the Spec ID" turns AI speed into a feature instead of a foot-gun.

dotclaude isn't opinionated about which workflow you adopt. It's opinionated that some workflow must exist — and that the same tools should serve both the person writing the code and the team shipping it.

Where to go next

• README — both install paths, full skills catalog.
• docs/quickstart.md — install to first green validator in under 10 minutes.
• docs/architecture.md — layer diagram and PR-time sequence.
• docs/adr/ — every hardening decision, with rationale.

MIT licensed. Issues and PRs welcome.