dotbabel

@dotbabel/dotbabel

Maintained by @kaiohenricunha · Changelog · Security

An opinionated, model-agnostic governance toolkit for Claude Code, Codex, Gemini CLI, Copilot CLI, and other agentic CLIs. Ships a curated library of skills, slash commands, and cloud/IaC specialists plus a global rule floor that hardens every agent session — and an optional spec-driven-development governance CLI on top, for repos that want PR-time gates.

Who is this for?

I am…	I want…	Start here
Dotfile user	The toolkit — skills, commands, and CLAUDE.md in every Claude session	Clone & bootstrap
Consumer	The CLI in my repo — bootstrap, doctor, drift detection, optional spec-gov gates	Install the CLI
Library user	Node API in my own tooling	docs/api-reference.md
Contributor	Dev workflow, local gates	CONTRIBUTING.md

---

TL;DR — pick your path

What you want	How
Skills & commands library wired into ~/.claude/	Clone & bootstrap — 30 seconds, no npm required
Governance CLI for your own repos (bootstrap + doctor + optional spec gates)	Install the CLI — see install section (Node ≥ 20 required)

Both paths are independent. You can use one or both.

---

Clone & bootstrap

Just want the skills library, commands, and a global CLAUDE.md? Three lines:

git clone https://github.com/kaiohenricunha/dotbabel.git ~/projects/dotbabel
cd ~/projects/dotbabel
./bootstrap.sh          # symlinks commands/ + skills/ + CLAUDE.md into ~/.claude/

That’s it — the full skills and commands library is now available in every Claude Code session. To stay current:

./sync.sh pull          # pull + re-bootstrap
./sync.sh push          # secret-scan + commit + push

If you have the CLI installed, you can use it instead of the shell scripts:

dotbabel bootstrap             # same as ./bootstrap.sh
dotbabel sync pull             # same as ./sync.sh pull
dotbabel sync push             # same as ./sync.sh push
dotbabel sync status           # show installed vs latest version

Both bootstrap and sync support --source <path> (clone mode) or default to the npm package installation (npm mode). Run dotbabel bootstrap --help or dotbabel sync --help for full options.

What you get

The bootstrap wires the authored library into every Claude Code session:

• skills/ provides reusable workflows and specialists. Skills can be invoked directly with /skill-name and can also activate from natural-language requests when their metadata matches.
• commands/ keeps the existing explicit slash-command prompt templates for workflows such as /ground-first, /fix-with-evidence, and /pre-pr.
• agents/ provides specialized Claude Code subagents copied during bootstrap.
• CLAUDE.md provides the global rule floor for every session.

Do not treat this README as the catalog. The source-of-truth inventory is generated from artifact frontmatter under index/, checked in CI with dotbabel index --check, and explained in docs/taxonomy.md.

dotbabel list --type skill
dotbabel list --type command
dotbabel search handoff
dotbabel show handoff --type skill
dotbabel index --check

See CLAUDE.md for the global rules this installs.

---

Quick taste

After ./bootstrap.sh, open any repo in Claude Code and try:

# Understand existing code before touching it
/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 the issue, fixes it, verifies, opens a PR

# Get a deep AWS IAM review of this repo
/aws-specialist review IAM policies in the production account
# → structured review: least-privilege gaps, trust-policy findings, remediations

# Batch-triage all open Dependabot PRs
/dependabot-sweep
# → parallel subagents annotate each PR with risk level; safe bumps merged automatically

# Hand off mid-task context across CLIs or machines
/handoff <query>                    # local cross-agent: emit <handoff> block
/handoff push [<query>] [--tag]     # upload to transport (scrubs secrets)
/handoff pull [<query>]             # fetch and render on the other end
# <query> = short UUID, full UUID, 'latest', Claude customTitle, or Codex thread_name

These workflows are context-aware: they read your repo’s files, history, and CI state.

---

Install the CLI

Want the governance CLI in your own repos — bootstrap, doctor, drift detection, programmatic validation, and optional spec-governance gates? Install it:

# One-liner (requires Node ≥ 20)
curl -fsSL https://raw.githubusercontent.com/kaiohenricunha/dotbabel/main/install.sh | bash

Or install manually:

# Global — use dotbabel anywhere
npm install -g @dotbabel/dotbabel

# Per-project — pin it to a repo (useful for CI)
npm install -D @dotbabel/dotbabel

The one-liner installs the package globally and runs dotbabel bootstrap to wire ~/.claude/ automatically. To pin a version or skip the bootstrap step:

curl -fsSL https://raw.githubusercontent.com/kaiohenricunha/dotbabel/main/install.sh | DOTBABEL_VERSION=0.4.0 bash
curl -fsSL https://raw.githubusercontent.com/kaiohenricunha/dotbabel/main/install.sh | DOTBABEL_SKIP_BOOTSTRAP=1 bash

Then use the umbrella dispatcher or standalone bins interchangeably:

dotbabel bootstrap                # set up (or refresh) ~/.claude/ — symlinks commands, skills, CLAUDE.md
dotbabel bootstrap --all          # also force Copilot/Codex/Gemini instruction symlinks
dotbabel sync pull                # pull latest dotbabel version and re-bootstrap
dotbabel sync push                # secret-scan staged files, commit, and push (clone mode)
dotbabel sync status              # show installed vs latest version / git status
dotbabel doctor                   # self-diagnostic: env, facts, manifest, specs, bootstrap
dotbabel doctor --install-hooks   # install pre-commit freshness check for generated instructions
dotbabel validate-skills          # verify skills manifest checksums + DAG
dotbabel validate-specs           # audit spec contracts + dependency cycles
dotbabel check-spec-coverage      # PR gate: protected paths must be spec-backed
dotbabel check-instruction-drift  # detect stale CLAUDE.md / README entries
dotbabel check-instructions-fresh # verify generated cross-CLI instruction files are fresh
dotbabel check-instruction-parity # verify applicable headings are preserved per CLI
dotbabel detect-drift             # flag commands diverged from origin/main 14+ days
dotbabel init                     # scaffold specs, hooks, manifest into a repo

Every subcommand also works as a standalone bin — npx dotbabel-doctor, npx dotbabel-validate-specs, etc. All support --help, --version, --json, --verbose, --no-color.

Five-minute walkthrough: docs/quickstart.md.

Scaffold a repo

npx dotbabel-init --project-name my-project --project-type node
npx dotbabel-doctor          # verify everything wired up
npx dotbabel-validate-specs  # run first governance check

User-scope rule-floor overlay (~/.config/dotbabel/local-rules.md)

dotbabel bootstrap (npm CLI, 2.7.0+) generates ~/.claude/CLAUDE.md as a real file containing the canonical dotbabel rule floor followed by a marker-delimited overlay block. To layer your own personal rules on top without forking dotbabel’s source, drop them into ~/.config/dotbabel/local-rules.md:

mkdir -p ~/.config/dotbabel
cat > ~/.config/dotbabel/local-rules.md <<'EOF'
## My personal rules

- Default to drafts when opening PRs.
- Always link the Linear ticket in the PR body.
EOF
dotbabel bootstrap   # regenerates ~/.claude/CLAUDE.md with your overlay merged in

The overlay sits AFTER the canonical content (Claude Code’s top-to-bottom read order means your rules trump dotbabel defaults). Future dotbabel bootstrap and dotbabel sync runs preserve the overlay, regenerating the merged file on every invocation. Direct edits to ~/.claude/CLAUDE.md are backed up to ~/.claude/CLAUDE.md.bak-<timestamp> before regen — always edit local-rules.md, not the generated file.

The shell-only ./bootstrap.sh quickstart still uses the legacy symlink shape and does not support overlays. Install the npm package for overlay support.

Project-scope sync (cross-CLI per-repo wiring)

dotbabel bootstrap covers your user scope (~/.claude/, ~/.codex/, ~/.gemini/). For per-repo artifacts — a project’s own CLAUDE.md, .claude/commands/*.md, and .claude/skills/* — use project-sync to fan them out to Codex (.codex/skills/), Gemini (.gemini/skills/), and Copilot (.github/prompts/*.prompt.md + .github/instructions/*.instructions.md):

cd ~/projects/my-app
dotbabel project-init                 # one-time: writes .dotbabel.json and a starter CLAUDE.md
dotbabel project-sync --dry-run       # preview planned actions
dotbabel project-sync                 # symlink everything in place
dotbabel check-project-sync           # CI-safe drift check (read-only)

The fan-out uses symlinks — your .claude/ tree stays the single source of truth. A .dotbabel.json is optional; without one, project-sync uses sensible defaults and treats the entire CLAUDE.md as the project rule floor (or the slice between <!-- dotbabel:rule-floor:begin --> / <!-- dotbabel:rule-floor:end --> markers when present).

Node API

import {
  createHarnessContext,
  validateSpecs,
  validateManifest,
  checkSpecCoverage,
  checkInstructionDrift,
  scaffoldHarness,
  ValidationError,
  ERROR_CODES,
  EXIT_CODES,
} from "@dotbabel/dotbabel";

const ctx = createHarnessContext(); // resolves repo root via git
const { ok, errors } = validateSpecs(ctx); // errors are ValidationError instances
if (!ok) {
  for (const err of errors) {
    if (err.code === ERROR_CODES.SPEC_STATUS_INVALID) {
      // programmatic reaction to a specific failure class
    }
  }
  process.exit(EXIT_CODES.VALIDATION);
}

Full contract: docs/api-reference.md.

CLI exit codes

Every bin honors --help, --version, --json, --verbose, --no-color and exits with:

Code	Name	Meaning
0	OK	Success
1	VALIDATION	Rule failure (expected failure mode)
2	ENV	Misconfigured environment
64	USAGE	Bad CLI invocation (matches BSD sysexits.h EX_USAGE)

Per-bin details: docs/cli-reference.md.

---

Hardening decisions

Each row links to its ADR (see docs/adr/):

Decision	ADR
Monorepo dual-persona layout	0001
No TypeScript; JSDoc + zero runtime deps	0002
Structured ValidationError contract	0012
Exit-code convention {0,1,2,64}	0013
CLI ✓/✗/⚠ output format	0014

Shell-level hardening (SEC-1..4, OPS-1..2) is enforced at plugins/dotbabel/scripts/validate-settings.sh; its 12-case behavioral suite at plugins/dotbabel/tests/test_validate_settings.sh pins every contract.

---

Further reading

docs/index.md	Nav map with persona-tailored entry points
docs/quickstart.md	Install → scaffold → first green validator
docs/cli-reference.md	Every bin, flag, exit code, --json schema
docs/api-reference.md	Node API surface
docs/architecture.md	Layer diagram + PR-time sequence
docs/troubleshooting.md	Error-code → remediation index
docs/upgrade-guide.md	0.1 → 0.2 migration, forking
docs/personas.md	Who reads which file
CONTRIBUTING.md	Dev workflow + local gates
SECURITY.md	Private vulnerability disclosure
CHANGELOG.md	Keep-a-Changelog history

License

MIT — see LICENSE.

This site is open source. Improve this page.