| name | spec-audit |
| description | Lint the spec-driven Claude Code ecosystem in this project — checks spec/, CLAUDE.md, and .claude/ for integration issues without rewriting anything. Use when the user runs /adam:spec-audit, /spec-audit (in this plugin's namespace), or asks to "lint specs", "check spec ecosystem", "verify CLAUDE.md is wired up", "audit my claude code setup", or "is my spec-driven workflow healthy?". Read-only — reports issues but does not modify files. For drift fixing, point users at /adam:spec-update. |
spec-audit
Read-only health check of the spec-driven workflow. Distinct from spec-update: that one fixes; this one reports.
Scope
This audit covers markdown specs only — spec/**/*.md, CLAUDE.md, and .claude/. Pipeline-specs under spec/pipelines/*.html and the viewer spec/pipelines.html are purely for user comprehension and are deliberately exempt:
- The
spec-lint MCP filters to *.md and skips subdirectories of spec/ other than the ones it knows about.
spec-graph-xref.sh uses find -name '*.md', so HTML files are never seen.check-anchors.sh (used by spec-update) also walks *.md only.
If a pipeline-spec looks wrong, open it in a browser — that's the validation surface. To regenerate the viewer's sidebar after manual edits, run bash ${CLAUDE_PLUGIN_ROOT}/scripts/tools/update-pipelines-manifest.sh "$PWD".
Process
-
Invoke the spec-lint MCP tool (lint) with the project root as the path argument. The lint result already includes a token summary for every spec.
-
Run the graph cross-check. Do not interpret these steps yourself; call the script.
bash ${CLAUDE_PLUGIN_ROOT}/scripts/validators/spec-graph-xref.sh "$PWD"
The script walks spec/**/*.md and reports two distinct classes of dangling references:
- Errors (
kind: "path") — backticked file paths in spec bodies that don't exist on disk (e.g. spec mentions src/foo.ts but the file moved or was deleted).
- Warnings (
kind: "symbol") — symbol names from the ## Anchors markdown table that don't resolve in the GitNexus graph (e.g. spec lists a class that's been renamed).
If gitnexus is missing or the repo isn't indexed, the script exits non-zero with a single env error — surface that, but still surface the spec-lint MCP result from step 1.
-
If you need raw counts for a specific file (e.g. to weigh whether to split it), use the token-count MCP tool (count).
-
Format the combined output as a readable report — first the spec-lint MCP issues, then the xref errors/warnings, then a token-count summary table.
Report format
Spec ecosystem audit — <repo name>
Errors (must fix):
- <issue> (from spec-lint or xref kind:"path")
Warnings:
- <issue> (from spec-lint or xref kind:"symbol")
Token counts:
| Spec | Tokens |
|-------------------------|--------|
| spec/overview.md | N |
| … | … |
| CLAUDE.md | N |
Cross-references:
paths checked: N symbols checked: N
dangling paths: N unresolved symbols: N
Summary: <one-line health verdict>
What the lint MCP checks
(See mcps/spec-lint/server.js for authoritative rules.)
spec/INDEX.md exists.CLAUDE.md has a spec index table with one row per spec/*.md.- No spec file is missing from the index (and no index row points to a missing file).
- Cross-references between specs (
[link](./other.md) style) all resolve.
- Each spec has standard frontmatter (
name, description, updated at minimum).
- No spec exceeds the configured token ceiling (default ~5000 tokens — flag at 4000, error at 6000).
.claude/ exists at project root if the spec table mentions tailored agents.CLAUDE.md itself is under ~2000 tokens (it's a brief, not a spec).
When to recommend a follow-up
- Errors → tell the user to run
/adam:spec-update (which uses the agent to actually rewrite).
- A spec over the token ceiling → tell them to run
/adam:spec-update <path> (the agent will split it).
- Missing
.claude/ agents/hooks the user expects → tell them to run /adam:setup --force or add by hand.
Guardrails
- This skill is read-only. Do not write or edit any file.
- Do not invoke the
adam sub-agent — this is a quick health check, not a refactor.
