audit

name	audit
compatibility	Built for Claude Code (subagents, interactive questions). Installs on any Agent Skills client.
allowed-tools	Bash, Read, Grep, Glob, Write, Edit, Task, AskUserQuestion
description	Bootstrap accurate project context by writing the AGENTS.md files. Run /audit once on a new project (after the stack is chosen and scaffolded) to capture conventions and tooling choices, or on an existing codebase to scan it and write root + nested AGENTS.md context files so every later skill and AI tool knows the real project. Gap-fills partially documented repos without clobbering curated content.

Read ../conventions.md first (once per session). It carries the session start gate, model routing (this skill: mid tier), subagent rules, panel rules, and output style. Apply the start gate before anything below.

What this skill does

The context bootstrapper. Writes the AGENTS.md files every other skill reads, for three starting points:

• Greenfield (scaffolded, no conventions on record): asks the engineer for standards and conventions (batched panels), reads the build approach from the roadmap header if /roadmap set one, and seeds root AGENTS.md so the first /develop already has ambient conventions. Runs after the stack is decided and the project scaffolded (the greenfield spine is /roadmap → /architect stack → scaffold → /audit); before that there is no real project to read.
• Brownfield, undocumented: scans the repo (subagent) and writes root AGENTS.md plus nested <area>/AGENTS.md files, judging what is global (root) vs area-specific (nested).
• Brownfield, partially documented: checks existing docs against the codebase and adds only what is missing; never clobbers curated content.

Owns: AGENTS.md files (root + nested). AGENTS.md is canonical; CLAUDE.md at root is a one-line pointer to it. Never: writes ADRs (/architect), maintains docs after later changes (/sync), or touches docs/roadmap/ content.

Execution

Pre-flight (cheap)

Detect: source files present? · root AGENTS.md / CLAUDE.md? · nested AGENTS.md files? · a roadmap header with a build approach? · a monorepo (workspaces config, apps/*/packages/*)? This classifies the run: greenfield setup · whole-repo scan · gap-fill. Ambiguous → one clarifying panel.

Greenfield setup

One or two batched panels for the un-inferable standards: architecture style leaning (e.g. functional and immutable vs OOP-leaning; suggest from the stack) · strictness (types, lint posture) · formatting taste · tooling choices to install later via /develop tooling (lint/format tool, pre-commit or not, CI or not) · anything the engineer insists every feature must honor. Then write root AGENTS.md: project one-liner · stack (from the scaffold and the stack ADR, linked) · commands (real ones from package.json/manifest) · build approach (from the roadmap header) · the rules just captured · tooling section. Keep it tight; it is read by every session forever, so every line is a recurring cost.

Whole-repo scan (brownfield)

Spawn a read-only exploration subagent (fast model, Read/Grep/Glob): map the tree, detect the stack and commands, infer the real conventions from the code (structure, error handling, naming, state, styling), identify distinct areas that deserve a nested AGENTS.md (an area with its own conventions, stack twist, or non-obvious rules; not every folder). It returns a compact map + drafted content. Main session reviews, writes root AGENTS.md and the judged nested files, and presents a short report for confirmation. In a monorepo, scan and write per workspace (each app's AGENTS.md reflects its stack), root covers only the genuinely shared.

Gap-fill (partially documented)

Same scan, but diff against the existing docs: add missing global facts to root, add nested docs only for undocumented areas, correct only what the code proves wrong, and never rewrite curated prose. Report exactly what was added or corrected.

Tool-skills and MCP sweep (greenfield after scaffold, and whole-repo)

For the stack's main tools not yet covered in AGENTS.md: detect fresh (npx skills find <tool>, or a web search; never a hardcoded table), skip installed/declined, offer per tool (skill and/or MCP, one panel, no recommended pick), act on the pick, record installs and declines in AGENTS.md so nothing re-offers.

Close

Report: files written or updated (one line each) · conventions captured · skills/MCPs installed or declined · anything flagged for /architect (a decision the scan surfaced). Close: "Next: /clear, then the roadmap's first unticked box (usually /develop tooling or the first feature's /architect)."

Reference files (lazy)

agent-prompt.md (scan subagent prompt) · patterns/*.md (convention rubrics per architecture style: functional, solid-oop, domain-driven, clean-architecture; the subagent reads only the style the repo or the engineer indicates).