/audit

name: audit
allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion
description: "Run /audit on a greenfield project, an existing codebase with missing docs, or one area (/audit src/auth) to bootstrap the project's AI context, the AGENTS.md files every later skill reads. Writes tool agnostic AGENTS.md plus thin CLAUDE.md pointers, adding only what is missing; never overwrites curated content."

Output style (plain words, no dashes, no hyphens)

<!-- OUTPUT-STYLE:START --> Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as `you`, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write `read only`, not `read-only`. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever. <!-- OUTPUT-STYLE:END -->

What this skill does

The context bootstrapper: writes the `AGENTS.md` files every later skill and AI tool reads.

• Greenfield (no code yet): ask for coding standards, seed root `AGENTS.md` from the answers plus the build approach (name and one line principle) from the scope header if `/scope` set one. Runs after the project is scaffolded with its chosen stack (`/scope` → `/architect` decides the stack → scaffold → `/audit`); earlier is premature.
• Brownfield, undocumented (code, no `AGENTS.md`): scan the whole project, write root `AGENTS.md` and nested `<area>/AGENTS.md` files, judging what is global (root) vs area specific (nested).
• Brownfield, partially documented: check existing root and nested docs against the whole codebase; add only what is missing (new global facts, nested docs for undocumented areas); never clobber curated content.

Does not create specs (/architect owns those), maintain files after changes (/sync owns that), or write the feature scope (/scope owns `docs/scope/`).

Context file convention (AGENTS.md is canonical)

Durable context lives in the tool agnostic `AGENTS.md` (root and nested); every agent (Codex, Cursor, Claude Code, and others) reads it. `CLAUDE.md` is only a one line pointer whose entire body imports the sibling `AGENTS.md` via Claude Code's `@` import (exact pointer body in `agent-prompt.md`); content is never duplicated across the two.

• Write knowledge into `AGENTS.md`. Create it when missing. Never overwrite an existing `AGENTS.md` (it may be user or tool authored); gap fill conservatively, with permission.
• Migrate legacy content: a `CLAUDE.md` with content but no `AGENTS.md` → ask permission, move its content into a new `AGENTS.md`, replace `CLAUDE.md` with the pointer. Never silently discard curated content.
• Root stays short and global; nested `AGENTS.md` only for meaningful areas with real conventions (same root/nested rules as previously applied to `CLAUDE.md`).

Scope

An area path argument (e.g. `auth`, `src/payments`) triggers Phase 3. With no argument, the `Pre-flight` signals below route to Phase 0 (ambiguous: ask new vs existing), Phase 1 (greenfield: ask standards, seed root), Phase 2 (established, no root AGENTS.md: whole-repo scan), or Phase 4 (root AGENTS.md exists: gap-fill). A legacy `CLAUDE.md` with content but no `AGENTS.md` is migrated, then treated as Phase 4.

Acts vs asks

Phase 1 asks coding standards questions via MCQ before creating root AGENTS.md. Phase 2 acts immediately, no questions; it writes root and the nested docs it judges warranted. Phases 3 and 4 act to explore but ask permission before modifying an existing root AGENTS.md or migrating a legacy CLAUDE.md; Phase 4 reports nested doc creation for undocumented areas first, then applies on confirmation.

Artifact ownership

The `AGENTS.md` files hold the content: create root if missing (Phase 1, 2) and `<area>/AGENTS.md` if missing and warranted, by judgment (Phase 2, 3, 4); when one exists, gap-fill or propose additions with permission; never overwrite. The `CLAUDE.md` files are pointers only (root and area), created if missing; a legacy one with content is migrated into `AGENTS.md` with permission. When creating a nested `AGENTS.md`, add exactly one pointer line to root `AGENTS.md` under `## Context files`: `- [<area>/AGENTS.md](<area>/AGENTS.md) (<one-line description>)`. Never one per subfolder, only where distinct conventions exist.

Portability (any OS, any agent)

• Commands: `git` is the only required CLI, same on every OS. Other shell snippets (file counts, `find`, `[ -f ]`) are POSIX reference, not literal scripts; use your agent's cross platform file tools (search/glob, read, write) to list, count, and check existence.
• Bundled files live in this skill's folder: `agent-prompt.md`, the phase mode files (`modes/*.md`), and the pattern presets (`patterns/*.md`). Resolve the folder to an absolute path. Read the matching phase mode file when routing, then `agent-prompt.md` plus the SELECTED pattern preset at write time. Its ALL_CAPS placeholders (PHASE, AREA, ADDITIONAL_STANDARDS, MONOREPO_OR_NO, INSTALLED_SKILLS, DECLINED_TOOLS, and so on) are the inputs you gathered in pre-flight and the question rounds; apply each as you read.
• No interactive question support? Ask any multiple choice question as plain text with the same options.

Execution

The main thread does the writing in every phase; it never hands `AGENTS.md` writing to a subagent. The only subagent is a read only `scout` (cheapest model, Claude Code: `haiku`, never the session model), spawned only for a large scan; it returns a compact map the main thread writes from. A small scaffold or single area needs no scout; read it directly. Right before writing, read `agent-prompt.md` (persona, per phase instructions, temp