DEV Community: Kaio Cunha

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

Kaio Cunha — Sat, 18 Apr 2026 22:58:04 +0000

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.

Why Istio's Metrics Merging Breaks in Multi-Container Pods (And How to Fix It)

Kaio Cunha — Tue, 17 Mar 2026 00:07:31 +0000

If you run multi-container pods under Istio with STRICT mTLS, you're probably missing metrics

And you might not know it. The containers are healthy. The scrape job shows no errors. But half your metrics are just... absent from Prometheus. No alert, no obvious explanation.

I spent a while debugging this before I understood what was going on, so here's the full picture.

The problem

Istio has a built-in metrics-merging feature that lets Prometheus scrape a pod through the Istio proxy without reaching each container directly. It's useful. But it has a hard limitation that the docs mention only in passing:

Istio's metrics-merge only supports one port per pod.

The Superorbital team wrote the definitive explanation of why this is the case. The short version: Istio's proxy forwards the scrape to a single application port. If you have three containers each exposing /metrics on different ports, Istio picks one and ignores the rest.

Someone opened a feature request for multi-port support back in 2022. It was labeled lifecycle/stale and auto-closed. There are several other issues from people hitting variations of this same problem. None of them were resolved.

Here's what it looks like in practice:

# Pod with api container (:8080) and worker container (:9100)

up{pod="my-app-abc123", container="api"}    = 1   ✓ scraped through Istio proxy

# worker metrics? absent. no error, just gone.

The worker container is perfectly healthy. Its metrics just never reach Prometheus. No scrape failure gets recorded because Prometheus never even tries. It only knows about the one port Istio advertises.

The workarounds you'll try (and why they don't work)

"Just scrape each container port directly." Works if mTLS is in permissive mode. In STRICT mode, every connection must go through the Istio proxy, which only forwards to one port. Direct port scraping gets rejected at the mTLS layer.

"Use multiple PodMonitor entries pointing at different ports." Same problem. The proxy is the bottleneck, not the scrape configuration.

"Push metrics to a Pushgateway." Technically works, but now you've broken the pull model everything else in your stack depends on, added a component that becomes a single point of failure, and introduced staleness semantics that are genuinely confusing to debug.

What about ambient mode?

Before I get to my solution, I should be upfront: if you're running Istio in ambient mode (GA since Istio 1.24), this problem doesn't apply to you. Ambient replaces the per-pod sidecar with a per-node L4 proxy (ztunnel), so there's no sidecar sitting inside your pod intercepting scrapes. Prometheus can reach your container ports directly, and mTLS is handled transparently at the node level. Howard John from the Istio team wrote about this — the TL;DR is "it just works."

But most production Istio deployments are still running sidecar mode. Migrating to ambient is a significant undertaking, and the Istio project itself says they expect many users to stay on sidecars for years. If that's you, keep reading.

What actually works in sidecar mode: one sidecar, one port

The idea is simple. Add a small sidecar container that scrapes all your other containers over localhost (where mTLS doesn't apply, because it's all inside the same pod) and exposes the merged result on a single port. Istio sees one port, Prometheus scrapes one port, and you get everything.

┌──────────────────────────────────────────────────────┐
│  Pod                                                 │
│                                                      │
│  ┌────────┐  localhost:8080/metrics                  │
│  │  api   ├──────────────────┐                       │
│  └────────┘                  │                       │
│                         ┌────▼──────────┐            │
│  ┌────────┐             │  aggregator   │            │
│  │ worker ├────────────►│  :9090/metrics│◄── Prometheus
│  └────────┘             └───────────────┘            │
│             localhost:9100/metrics                   │
└──────────────────────────────────────────────────────┘

This is what metrics-aggregator does. I built it because I kept hitting this problem and none of the existing tools solved it cleanly.

Configuration

Add it as a sidecar to any pod:

containers:
  - name: metrics-aggregator
    image: ghcr.io/kaiohenricunha/metrics-aggregator:latest
    ports:
      - containerPort: 9090
    env:
      - name: METRICS_ENDPOINTS
        # JSON map (recommended), or comma-separated URLs
        value: '{"api":"http://localhost:8080/metrics","worker":"http://localhost:9100/metrics"}'

Point Prometheus at port 9090:

annotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "9090"

That's it. No extra service, no push gateway, no changes to your app containers.

Here's what Prometheus sees after:

# Same pod, same containers, all metrics present now

http_requests_total{method="GET", status="200", origin_container="api"}    1027
http_requests_total{method="GET", status="200", origin_container="worker"}  843

go_goroutines{origin_container="api"}    42
go_goroutines{origin_container="worker"} 17

Every metric line gets an origin_container label injected automatically so you can tell which container produced it. # TYPE and # HELP lines are deduplicated so the output is valid Prometheus exposition format.

How it works under the hood

Endpoints are scraped concurrently with best-effort semantics. If one container is down, the others still report. The request only fails if every source fails.

The repo has the full details: self-instrumentation metrics, optional OpenTelemetry tracing, alerting rules, and a Grafana dashboard. I won't rehash all of that here.

Does it actually work under STRICT mTLS?

Yes. The CI suite deploys a 4-container pod (three app containers plus istio-proxy) under PeerAuthentication mode STRICT and asserts that Prometheus sustains up == 1 over 60 seconds. The scrape goes through the proxy; the internal localhost scrapes bypass it entirely.

I wanted this to be tested in CI, not just "it works on my cluster."

Supply chain security

The image is signed with Cosign, scanned with Trivy on every release, and ships with SBOM and SLSA provenance. Releases use semantic versioning via Conventional Commits. This is infrastructure tooling that goes into your production pods, so I wanted to get this part right.

Getting started

Full manifests (plain Deployment, PodMonitor, Helm, Kustomize) are in the examples/ directory.

Quickest path:

kubectl apply -f https://raw.githubusercontent.com/kaiohenricunha/metrics-aggregator/main/examples/deployment.yaml

The repo is here: kaiohenricunha/metrics-aggregator

If you're on sidecar mode with STRICT mTLS and wondering why half your metrics are missing, give it a try. And if you're planning a migration to ambient mode down the road but need something that works today, this bridges the gap. Open an issue if something doesn't work or if you have a use case I haven't thought of.

Update: I wrote a follow-up post exploring the broader question of whether Istio should extend metrics merging or sunset it entirely: Istio's metrics merging was built for a simpler world. What should replace it?