spec-audit

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

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

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

3. If you need raw counts for a specific file (e.g. to weigh whether to split it), use the token-count MCP tool (count).

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