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

A developer created an adoption-audit command for Claude Code that scores usage against Boris Cherny's 5-step AI-adoption ladder. The tool runs locally and read-only, analyzing session transcripts under ~/.claude/projects to produce an evidence-first report with a bottleneck and a 2-week improvement plan.

| 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.