@dotclaude/dotclaude

v1.2.1

Published

19 hours ago

An opinionated Claude Code toolkit: skills, slash commands, cloud/IaC specialists, and an optional spec-governance CLI.

0High
0Medium
0Low

claude-code claude-code-toolkit skills slash-commands cloud-specialists claude dotclaude sdd spec-driven validator linter governance cli

`@dotclaude/dotclaude`

Maintained by @kaiohenricunha · Changelog · Security

An opinionated Claude Code toolkit. Ships a curated library of skills, slash commands, and cloud/IaC specialists plus a global rule floor that hardens every Claude Code 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/dotclaude.git ~/projects/dotclaude
cd ~/projects/dotclaude
./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:

dotclaude bootstrap             # same as ./bootstrap.sh
dotclaude sync pull             # same as ./sync.sh pull
dotclaude sync push             # same as ./sync.sh push
dotclaude 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 dotclaude bootstrap --help or dotclaude sync --help for full options.

What you get

30 skills and commands are wired into every Claude Code session:

Cloud, IaC & Container specialists — activate automatically when you mention the relevant technology:

| Skill / Agent | Triggers on | What it does | | ---------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | aws-specialist | "AWS", "IAM role", "Lambda", "ECS", "S3"… | Deep-dive AWS architecture review, IAM audits, multi-service debugging | | azure-specialist | "Azure", "AKS", "Managed Identity", "Bicep"… | Azure workload review, identity audits, ARM/Bicep guidance | | gcp-specialist | "GCP", "GKE", "Cloud Run", "Workload Identity"… | GCP architecture review, IAM hierarchy, serverless guidance | | kubernetes-specialist | "kubernetes", "k8s", "pod", "helm chart"… | Cluster troubleshooting, workload design, network policy review | | crossplane-specialist | "Crossplane", "XRD", "Composition", "Claim"… | XRD design, Composition correctness, provider config audit | | terraform-specialist | "Terraform", "state file", "IaC module"… | Module design, state management, workspace review | | terragrunt-specialist | "Terragrunt", "run-all", "DRY Terraform"… | DRY hierarchy review, dependency graph, env layout | | pulumi-specialist | "Pulumi", "ComponentResource", "stack"… | Stack review, Automation API audit, secrets management | | docker-engineer | "docker compose", "docker exec", "container logs", "docker stats"… | Multi-service Compose orchestration, runtime container ops, supply chain analysis |

Engineering workflow — slash commands:

| Command | Invoke | What it does | | -------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | git | /git | Conventional commits, PR creation, branch naming | | changelog | /changelog | Generate changelog entry from git history | | merge-pr | /merge-pr <N> | Full local verification gate before merge | | pre-pr ¹ | /pre-pr [base-branch] | Quality gate before opening a PR: simplify, security-review, test suite | | review-pr | /review-pr <N> | Fetch comments, apply fixes, resolve threads | | review-prs ¹ | /review-prs <N1> [N2 N3 ...] | Batch-review multiple PRs in parallel with one sub-agent per PR | | audit-and-fix | /audit-and-fix <domain> | Audit → cluster findings → spawn parallel fix PRs | | dependabot-sweep | /dependabot-sweep | Batch-triage all open Dependabot PRs | | handoff | /handoff <sub-command> | Transfer session context between AI agents (Claude Code, Copilot CLI, Codex) and across machines via a user-owned private git repo |

¹ maturity: draft — functional but not yet tested across all project types.

Debugging & quality:

| Command | Invoke | What it does | | ---------------------------------------------------- | ---------------------------- | ---------------------------------------------- | | ground-first | /ground-first <subject> | Code-grounded analysis before any edit | | fix-with-evidence | /fix-with-evidence <issue> | Reproduce → Fix → Verify → PR loop | | detect-flaky | /detect-flaky <test-cmd> | Find and fix flaky tests by repeated execution | | security-review | /security-review | Scan changed files for OWASP vulnerabilities |

Analysis & documentation:

| Command | Invoke | What it does | | ---------------------------------------------------- | ------------------------------ | --------------------------------------------------------- | | create-audit | /create-audit <subject> | Evidence-based audit doc → docs/audits/ | | create-inspection | /create-inspection <problem> | Investigate and surface fix options → docs/inspections/ | | create-assessment | /create-assessment <target> | 0–10 graded assessment doc → docs/assessments/ | | markdown | /markdown <path> | Fix markdown formatting and structure |

Spec & governance — one optional pillar of the toolkit. Skip this section if you're not adopting spec-driven workflows.

| Command / Skill | Invoke | What it does | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | spec | /spec <id> "<title>" | Interactive spec authoring → docs/specs/ | | validate-spec | /validate-spec <id> | Audit an implemented spec against the codebase | | agents-search | /agents-search list | Discover, search, and manage Claude Code agents | | veracity-audit | /veracity-audit audit --config <config> --quality-config <quality-config> --pipeline-dir <pipeline-dir> --scoring-dir <scoring-dir> | Audit a data pipeline for veracity and value |

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

Every command is context-aware — it reads 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/dotclaude/main/install.sh | bash

Or install manually:

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

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

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

curl -fsSL https://raw.githubusercontent.com/kaiohenricunha/dotclaude/main/install.sh | DOTCLAUDE_VERSION=0.4.0 bash
curl -fsSL https://raw.githubusercontent.com/kaiohenricunha/dotclaude/main/install.sh | DOTCLAUDE_SKIP_BOOTSTRAP=1 bash

Then use the umbrella dispatcher or standalone bins interchangeably:

dotclaude bootstrap                # set up (or refresh) ~/.claude/ — symlinks commands, skills, CLAUDE.md
dotclaude sync pull                # pull latest dotclaude version and re-bootstrap
dotclaude sync push                # secret-scan staged files, commit, and push (clone mode)
dotclaude sync status              # show installed vs latest version / git status
dotclaude doctor                   # self-diagnostic: env, facts, manifest, specs, bootstrap
dotclaude validate-skills          # verify skills manifest checksums + DAG
dotclaude validate-specs           # audit spec contracts + dependency cycles
dotclaude check-spec-coverage      # PR gate: protected paths must be spec-backed
dotclaude check-instruction-drift  # detect stale CLAUDE.md / README entries
dotclaude detect-drift             # flag commands diverged from origin/main 14+ days
dotclaude init                     # scaffold specs, hooks, manifest into a repo

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

Five-minute walkthrough: docs/quickstart.md.

Scaffold a repo

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

Node API

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

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/dotclaude/scripts/validate-settings.sh; its 12-case behavioral suite at plugins/dotclaude/tests/test_validate_settings.sh pins every contract.

License

MIT — see LICENSE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme