/self-audit

name: self-audit
description: Self-audit this skills repo against CLAUDE.md invariants, the artifact contract, failure-path robustness, README/CLAUDE.md/docs/website sync, and machinery that does not earn its place, via five parallel read-only subagents. Local meta-skill — independent of the /task:* pipeline.
disable-model-invocation: true
user-invocable: true
argument-hint: '[skill-name]'

Audit **this repository** (the task-pipeline skills repo itself) for drift between skills, the artifact contract, and the docs, for failure paths that end nowhere, and for machinery nothing needs. Five lenses run in parallel as named subagents: **Invariants**, **Contract**, **Robustness**, **Docs-sync**, **Leanness**.

This is a **meta-skill**. It operates on the repo's own files, not on `.task/*` artifacts. It asks one question — *does the repo obey its own declared rules?* — and each lens has an oracle: `CLAUDE.md` § "Invariants — don't break these when editing skills" and § "Editing protocol — quick rules" with the `docs/contract.md` sections their bullets link, `docs/contract.md`, the documented outputs and exit codes in `docs/contract.md` together with each skill's own declared flow, and what is actually on disk. The Leanness lens asks the inverse — *does every mechanism earn its place?* — and its oracle is proof of need: a caller on disk, a sentence in `CLAUDE.md` or `docs/contract.md` that requires it, or the fix commit that introduced it. The skill can be invoked at any time.

**Input:** Optional scope hint: $ARGUMENTS — a skill name (e.g. `to-task`) or one or more repo paths; default: full repo.

**Precondition (hard-stop):** This skill is local to the task-pipeline repo. Verify the working directory contains `skills/to-task/`, `skills/validate/`, and `CLAUDE.md` at the repo root. If not, stop with: "This skill is local and only works inside the task-pipeline repository."

**Communication language:** mirror the language the user writes in for all prose (headings, summaries, the final report). Findings text stays in English — it grounds in English source files and quotes them.

**Derive, never recall.** The roster of skills, `_lib/` helpers, agents and docs changes often. Neither this skill nor its agents carry a copy of it: every roster comes from the disk at run time (`ls`, frontmatter), and every rule comes from `CLAUDE.md` / `docs/contract.md` as they read today. A hardcoded list here would itself become the drift this skill exists to catch.

Architecture

| Lens | Local agent | Oracle | What it checks | |------|-------------|--------|---------------| | Invariants | `self-invariants-auditor` | `CLAUDE.md` § Invariants + § Editing protocol, and the `docs/contract.md` sections their bullets link | Skills, `_lib/` helpers, the driver, and `agents/code-reviewer.md` don't violate a declared invariant. | | Contract | `self-contract-auditor` | `docs/contract.md` | Producer↔consumer artifact protocol is symmetric: `write-task.sh` / capture flows ↔ `validate.sh` / `roadmap*.sh` parsers ↔ consumer rules, plus the driver contract and the plugin manifest. | | Robustness | `self-robustness-auditor` | `docs/contract.md` § Bash layer (§ validate.sh, § Helpers), § Agent layer and § execution shape (driver contract), plus each skill's own declared flow | Every failure, decline, rerun and no-op path ends in a defined output; success lines only after a checked operation; documented exit codes reachable and tested; shell constructs safe on bash 3.2 and 5.x, BSD and GNU tools, any locale; no term used for two things across sibling steps. | | Docs-sync | `self-docs-sync-auditor` | `ls skills/`, `ls skills/_lib/`, `ls agents/`, frontmatter | `README.md`, `CLAUDE.md`, `docs/`, `CONTRIBUTING.md`, `website/` and any `.claude/rules/*.md` reflect what is on disk. | | Leanness | `self-leanness-auditor` | Proof of need: `git grep` for callers, `CLAUDE.md` and `docs/contract.md` for a sentence that requires it, `git log -S` / `git blame` for the fix that introduced it | Nothing in the skills, `_lib/` helpers, the driver or `agents/code-reviewer.md` lacks a need: no branch, option or function nothing reaches, no thin wrapper with one caller, no guard for a state the callers rule out, no rule restated in full where a pointer to its owner would do, no mode that adds branches but no capability, no state or output nobody reads. |

All five are **read-only** named agents at `.claude/agents/self-{invariants,contract,robustness,docs-sync,leanness}-auditor.md`, with `tools: Read, Grep, Glob, Bash`. They carry no `Edit`/`Write` tools, and Bash is theirs for reading and searching only — that rule is an instruction in each agent's prompt, not a runtime guarantee: nothing stops a Bash command from writing. They read the repo themselves; the main thread does not paste file contents into their prompts.

The deliverable is the **report**. The skill edits nothing on its own: after the report it asks the user what to fix (Step 4), and only the findings the user picked are fixed — by Sonnet subagents, never by the lenses or the main thread (Step 5). The main thread's only edits undo a fix that breaks the suite or the re-audit (Step 6).

Instructions

Step 1: Gather context

In one parallel batch:

• `ls skills/ skills/_lib/ agents/ .claude/agents/` — the live roster (folder names are canonical slugs) and a sanity check that the five self-* auditor files exist.
• `git status --porcelain` — flag a dirty tree to the user before starting (findings against working state may diverge from `HEAD`).
• Read `CLAUDE.md` in full (the main thread needs it to merge findings, and in Step 5 to batch each fix with the files its Editing protocol ties to it).

Do not pre-read the skill bundle, the helpers, or the docs — each agent reads its own set, and the main thread reads a file only when merging a finding in it, or after the fixes, to check or undo one.

Step 2: Run five agents in parallel

Send **one tool message** with f