# Claude Code /adoption-audit — score your usage on the 5-step AI-adoption ladder (evidence-first, local, read-only). Save to ~/.claude/commands/adoption-audit.md

> Source: <https://gist.github.com/batou9150/5df83474911b946a451be0074fb766cd>
> Published: 2026-07-18 09:36:16+00:00

| description | Audit your Claude Code usage against the 5-step AI-adoption ladder and produce a scored, evidence-first report (+ optional artifact). |
|---|---|
| argument-hint | [extra exclude-regex for repos to ignore] |
| allowed-tools | Bash, Read, Write, Edit, Artifact, Agent |

Audit **my own** Claude Code usage against Boris Cherny's 5-step AI-adoption ladder,
place me on a step from measured evidence, name my #1 bottleneck, and give a
prioritized 2-week plan to reach the next step. Be rigorous and evidence-first — no
flattery. State the number you found for every dimension. If a dimension can't be
measured, say so and name what to enable.

Install:save this file as`~/.claude/commands/adoption-audit.md`

(user-global, works in any project) or`.claude/commands/adoption-audit.md`

(per-project). Run`/adoption-audit`

.Privacy:everything below is local and read-only — it reads your session transcripts under`~/.claude/projects`

. Nothing leaves your machine unlessyouchoose to publish an artifact.Method:aggregate with shell tools; do NOT read every transcript into context. For a huge project, spawn a subagent to extract counts, then merge.

`EXCLUDE`

— regex of project/folder names that are**not your work**(repos you cloned to study, templates, vendored code). Anything provided as`$ARGUMENTS`

is added to this. Default: none.`ARTIFACT_URL`

— leave empty on first run. If you publish the optional artifact, paste its URL back here so future runs**update it in place** instead of minting a new one.

```
EXCLUDE_REGEX=""     # e.g. "some-template|vendored-repo"  ($ARGUMENTS is appended)
ARTIFACT_URL=""      # e.g. https://claude.ai/code/artifact/xxxxxxxx
```

**0 Gated**— 0 agents / chat only, no approved tooling or infra.** 1 Assisted**— ~1 / one supervised session at a time; you review almost every change; work is synchronous.** 2 Parallel**— ~10 / 5–10 concurrent agents on their own worktrees; auto mode always on; Claude self-verifies (test/build/lint) before you look; automated code + security review; you review final diffs.**3 Supervised autonomy**— ~100 / Claude writes nearly all code; fan-out via subagents, /loop, /batch, /goal, routines, workflows; Claude kicks off Claude; standards encoded in CLAUDE.md + Skills; cost managed via OTel/analytics.**4 AI-native**— ~1000+ / loop closed, most agents kicked off by Claude; Agent SDK schedules fleets; you monitor by exception.

```
P=~/.claude/projects
EX="${EXCLUDE_REGEX:-}"; [ -n "$1" ] && EX="${EX:+$EX|}$1"   # merge $ARGUMENTS into excludes
exf(){ if [ -n "$EX" ]; then grep -vE "$EX"; else cat; fi; }

# ---- Inventory ----
echo "top-level sessions:"; find $P -mindepth 2 -maxdepth 2 -name '*.jsonl' | wc -l
echo "workflow runs:";      find $P -type d -name 'wf_*' | wc -l
echo "subagent transcripts:"; find $P -path '*/subagents/*' -name 'agent-*.jsonl' | wc -l

# ---- Date range + sessions-per-ISO-week trend (is usage growing?) ----
find $P -mindepth 2 -maxdepth 2 -name '*.jsonl' | while read f; do
  jq -rc '.timestamp//empty' "$f" 2>/dev/null | sort | head -1; done | cut -c1-10 | \
  while read d; do date -j -f '%Y-%m-%d' "$d" '+%Y-W%V' 2>/dev/null || date -d "$d" '+%Y-W%V' 2>/dev/null; done | sort | uniq -c

# ---- Tool-use frequency: top-level = your direct work; mindepth 3 = subagents/workflows ----
find $P -mindepth 2 -maxdepth 2 -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \
  jq -rc 'select(.type=="assistant")|.message.content[]?|select(.type=="tool_use")|.name' 2>/dev/null | sort | uniq -c | sort -rn
find $P -mindepth 3 -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \
  jq -rc 'select(.type=="assistant")|.message.content[]?|select(.type=="tool_use")|.name' 2>/dev/null | sort | uniq -c | sort -rn | head

# ---- Permission posture: auto mode always on? ----
find $P -mindepth 2 -maxdepth 2 -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \
  jq -rc '..|.permissionMode?//empty' 2>/dev/null | sort | uniq -c | sort -rn

# ---- Self-verification: does Claude run tests/build/lint/typecheck itself? ----
find $P -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \
  jq -rc 'select(.type=="assistant")|.message.content[]?|select(.type=="tool_use" and .name=="Bash")|.input.command' 2>/dev/null | \
  grep -oiE '\b(pytest|npm run build|npm test|yarn test|vitest|jest|eslint|ruff|mypy|tsc|go test|cargo test|black|prettier|playwright test|typecheck)\b' | sort | uniq -c | sort -rn

# ---- Concurrency: max overlapping top-level sessions (wall-clock) ----
find $P -mindepth 2 -maxdepth 2 -name '*.jsonl' | while read f; do
  ts=$(jq -rc '.timestamp//empty' "$f" 2>/dev/null | sort); s=$(echo "$ts"|head -1); e=$(echo "$ts"|tail -1)
  [ -n "$s" ] && echo "$s|$e"; done | awk -F'|' '{print $1" S";print $2" E"}' | sort | \
  awk '{if($2=="S"){c++;if(c>m)m=c}else c--}END{print "max concurrent sessions:",m}'
# Peak concurrent subagents in the busiest session (true parallel fan-out):
BIG=$(find $P -path '*/subagents/*' -name 'agent-*.jsonl' | awk -F/ '{print $1"/"$2"/"$3"/"$4"/"$5"/"$6"/"$7}' | sort | uniq -c | sort -rn | head -1 | awk '{print $2}')
[ -n "$BIG" ] && find "$BIG" -name 'agent-*.jsonl' | while read f; do ts=$(jq -rc '.timestamp//empty' "$f" 2>/dev/null|sort); s=$(echo "$ts"|head -1); e=$(echo "$ts"|tail -1); [ -n "$s" ]&&echo "$s|$e"; done | \
  awk -F'|' '{print $1" S";print $2" E"}' | sort | awk '{if($2=="S"){c++;if(c>m)m=c}else c--}END{print "peak concurrent subagents:",m}'

# ---- Orchestration / proactivity / automated review — ACTUAL tool_use only ----
# (WARNING: a plain grep for "code-review"/"worktree" is polluted by system-prompt text;
#  count real invocations by matching tool_use .name.)
find $P -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \
  jq -rc 'select(.type=="assistant")|.message.content[]?|select(.type=="tool_use")|.name' 2>/dev/null | \
  grep -iE 'Workflow|^Agent$|Task|Monitor|SendMessage|Worktree|review|Cron|Remote|Push|Schedule' | sort | uniq -c | sort -rn

# ---- Context engineering: your CLAUDE.md / skills / agents / MCP (excludes non-your-work) ----
CODE_ROOT="${CODE_ROOT:-$HOME/projects}"   # set to where your repos live
echo "your skills:";   find "$CODE_ROOT" ~/.claude -maxdepth 6 -path '*/skills/*/SKILL.md' 2>/dev/null | exf | wc -l
echo "your CLAUDE.md:"; find "$CODE_ROOT" -maxdepth 4 \( -iname 'CLAUDE.md' -o -iname 'AGENTS.md' \) 2>/dev/null | exf | wc -l
echo "your subagents:"; find "$CODE_ROOT" -maxdepth 5 -path '*/.claude/agents/*.md' 2>/dev/null | exf | wc -l
echo "hooks configured:"; find "$CODE_ROOT" ~/.claude -maxdepth 4 -name 'settings*.json' 2>/dev/null | exf | xargs grep -l '"hooks"' 2>/dev/null | wc -l
echo "settings signals:"; grep -E 'defaultMode|effortLevel|"model"|OTEL|ENABLE_TELEMETRY' ~/.claude/settings.json 2>/dev/null
```

For each, cite the number found and mark whether it **leads** or **lags** your overall step:
**Concurrency** (typical & max overlap; peak parallel subagents) ·
**Permission posture** (auto vs default rate) ·
**Self-verification** (test/build/lint runs; any enforcing hook/verify skill?) ·
**Isolation** (worktrees + subagent fan-out) ·
**Orchestration** (Workflow / Agent / Task / /loop / /batch / routines) ·
**Automated review** (code-review + security-review actually invoked? hooks/CI?) ·
**Context engineering** (CLAUDE.md, Skills, agents, memory, MCP servers wired in) ·
**Proactivity** (does Claude kick off Claude — cron/routines/remote?) ·
**Cost & observability** (OTel export, analytics, deliberate model/effort) ·
**Review depth** (read every diff vs final diffs vs monitor by exception).

**Verdict**(one line): "You are at Step X (confidence …), leaning X+1 on ."** Scorecard table**: dimension | measured signal | step 0–4.** Evidence appendix**: brief, with counts/paths.**#1 bottleneck** keeping you at your step (match the framework's bottleneck for that step).**Climb to Step X+1**— 3–5 highest-leverage, specific actions (exact command/config/skill + why it moves the needle). Relevant docs: auto mode[https://code.claude.com/docs/en/auto-mode-config](https://code.claude.com/docs/en/auto-mode-config)· code review[https://code.claude.com/docs/en/code-review](https://code.claude.com/docs/en/code-review)· security review[https://github.com/anthropics/claude-code-security-review](https://github.com/anthropics/claude-code-security-review)· remote control[https://code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control)· workflows[https://code.claude.com/docs/en/workflows](https://code.claude.com/docs/en/workflows)· sandboxing[https://code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing)· costs[https://code.claude.com/docs/en/costs](https://code.claude.com/docs/en/costs)

Print the report as markdown (the primary deliverable — works everywhere, incl. headless).

**Optional artifact:** if you want a visual dashboard, build a self-contained HTML page and
publish it with the `Artifact`

tool. Suggested treatment: a compact "instrument panel" — a
5-step ascent-ladder hero marking your current step, a metrics readout strip, a scorecard with
0–4 segmented meters colored by severity (lag/dev/lead), and a sessions-per-week trend. Design
both light and dark themes; use monospace for data/labels. If `ARTIFACT_URL`

is set above, pass
it as the `url`

parameter to update in place; otherwise publish fresh, then paste the returned
URL into `ARTIFACT_URL`

so next time updates the same page.