istm-audit

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

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

Write everything this skill produces, files and messages alike, in plain simple language. 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.

What this skill does

The context bootstrapper: writes the .istm-context/agents.md files every later skill and AI tool reads.

• Greenfield (no code yet): ask for coding standards, seed root .istm-context/agents.md from the answers plus the build approach (name and one line principle) from the scope header if /istm-scope set one. Runs after the project is scaffolded with its chosen stack (/istm-scope → /architect decides the stack → scaffold → /istm-audit); earlier is premature.
• Brownfield, undocumented (code, no .istm-context/agents.md): scan the whole project, write root .istm-context/agents.md and nested <area>/.istm-context/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 (/istm-sync owns that), or write the feature scope (/istm-scope owns .istm-context/istm-scope/).

Context file convention (.istm-context/agents.md is canonical)

Durable context lives in the tool agnostic .istm-context/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 .istm-context/agents.md via Claude Code's @ import (exact pointer body in agent-prompt.md); content is never duplicated across the two.

• Write knowledge into .istm-context/agents.md. Create it when missing. Never overwrite an existing .istm-context/agents.md (it may be user or tool authored); gap fill conservatively, with permission.
• Migrate legacy content: a CLAUDE.md with content but no .istm-context/agents.md → ask permission, move its content into a new .istm-context/agents.md, replace CLAUDE.md with the pointer. Never silently discard curated content.
• Root stays short and global; nested .istm-context/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 .istm-context/agents.md: whole-repo scan), or Phase 4 (root .istm-context/agents.md exists: gap-fill). A legacy CLAUDE.md with content but no .istm-context/agents.md is migrated, then treated as Phase 4.

Acts vs asks

Phase 1 asks coding standards questions via MCQ before creating root .istm-context/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 .istm-context/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 .istm-context/agents.md files hold the content: create root if missing (Phase 1, 2) and <area>/.istm-context/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 .istm-context/agents.md with permission. When creating a nested .istm-context/agents.md, add exactly one pointer line to root .istm-context/agents.md under ## Context files: - [<area>/.istm-context/agents.md](<area>/.istm-context/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 itself in every phase; it never hands the .istm-context/agents.md writing to a subagent. The only subagent this skill spawns reads the codebase, and only when the scan is large: a read only scout on the cheapest model (Claude Code: haiku, never inheriting the session model) that returns a compact map, from which the main thread writes. A small greenfield scaffold or a single area needs no scout; the main thread reads it directly. Right before writing, the main thread reads agent-prompt.md (its persona, per phase instructions, and the .istm-context/agents.md templates) plus, in Phase 1, the one selected pattern preset file; it then writes following that guide. Read agent-prompt.md only at write time, not during pre-flight.

Pre-flight (main thread does this before anything else)

Gather several signals (a file count alone misleads: a scaffold inflates it, an unfamiliar language zeroes it):

1. Context files: root .istm-context/agents.md present → ROOT_EXISTS; a CLAUDE.md with content only → ROOT_LEGACY; neither → ROOT_MISSING.
2. Source count across common ecosystems (extensions like .ts/.tsx/.js/.jsx/.py/.go/.rs/.java/.rb/.swift/.kt/.php/.cs/.dart/.ex/.exs/.scala/.c/.cpp/.h/.lua/.clj), excluding vendored/generated dirs (node_modules, .git, dist, build) and config files (*.config.*).
3. Established signals: git log --oneline for commit history depth; a real manifest (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, *.csproj, pubspec.yaml, mix.exs, Gemfile).
4. Monorepo signal: workspace markers (pnpm-workspace.yaml, turbo.json, a "workspaces" field in package.json) or any apps/*/package.json / packages/*/package.json near the root.
5. Workflow setup signal (WORKFLOW_SETUP): root .istm-context/agents.md is MISSING while the workflow has already decided the stack, i.e. a .istm-context/specs/ architecture spec exists (a file with a ## Proposed stack section), and/or .istm-context/istm-scope/ has a "Stack and architecture" (or similar foundational scaffold) feature. This is the intended greenfield order (/istm-scope → /architect decides the stack → /istm-develop scaffolds it → /istm-audit): the project is freshly scaffolded from its chosen stack and still needs its coding standards captured. When this signal fires, the manifest and scaffold source that now exist are the scaffold, not a codebase that already existed.

Pick the phase. The order of checks matters: the workflow setup signal outranks the raw code count, because a fresh scaffold has a manifest and source files yet is still greenfield.

Condition	Phase
Area path given as argument	Phase 3
ROOT_EXISTS (or ROOT_LEGACY after migration)	Phase 4
ROOT_MISSING and WORKFLOW_SETUP (stack spec and/or scope stack feature)	Phase 1, even though a manifest and scaffold source now exist. Ask the coding standards; seed root from the spec's stack. Never treat a just scaffolded workflow project as brownfield.
ROOT_MISSING, no WORKFLOW_SETUP, no source files AND no manifest	Phase 1
ROOT_MISSING, no WORKFLOW_SETUP, has code (source ≥ 10 or a manifest), ≥ 2 commits and clearly real feature code (not just scaffold)	Phase 2, any language
ROOT_MISSING, no WORKFLOW_SETUP, has code but it looks like untouched scaffold, or ≤ 1 commit, or you can't tell greenfield from brownfield	Phase 0, ask

Why this order: the workflow scaffolds a greenfield project (manifest + starter files) BEFORE /istm-audit runs, so a raw code count alone would wrongly read a fresh scaffold as an existing codebase and skip the coding standards questions. The workflow setup signal (a stack spec with no root .istm-context/agents.md) catches exactly that case and routes it to greenfield. Only when there is real feature code, real history, and no in-progress workflow setup is it truly brownfield (Phase 2). Anything ambiguous falls to Phase 0 and asks; never default a maybe greenfield project to brownfield.

Monorepo (MONOREPO=yes): root plus a light stub per workspace, deepen on demand. Each workspace (apps/*, packages/*) is a first class area; its primary doc lives at the workspace root (packages/api/.istm-context/agents.md), never buried deeper. A whole-repo run does not deep scan every workspace (too expensive, premature); write the repo root .istm-context/agents.md (monorepo wide tooling, shared conventions) plus a light stub .istm-context/agents.md per workspace from its manifest, no code scan, with root pointers. The full conventions/gotchas/key files scan happens when the engineer runs /istm-audit packages/api (Phase 3) or first builds there, never all upfront. A spot inside a workspace that warrants its own doc (packages/ui/src/mdx/) gets one in addition to the workspace root doc, linked from it. A doc already there, buried in a workspace with no workspace root doc: ask: "packages/ui has a context file at src/mdx/ but none at its root. Move it up to packages/ui/.istm-context/agents.md, or keep it as a nested doc under a new packages/ui/.istm-context/agents.md?" On move: relocate it to the workspace root. On keep nested: create the workspace root .istm-context/agents.md AND keep the deep one, linking it from the root doc. Migrate legacy CLAUDE.md content per the convention above. Apply MONOREPO=yes plus the workspace list as you write.

Legacy migration (any phase): on ROOT_LEGACY, before proceeding ask permission: "I found a CLAUDE.md with project context but no .istm-context/agents.md. I'll move its content into a new .istm-context/agents.md (so all tools read it) and replace CLAUDE.md with a pointer. Proceed?" On yes: copy the content verbatim into .istm-context/agents.md, then replace CLAUDE.md with the pointer; .istm-context/agents.md now exists, so continue as Phase 4 (gap-fill). On no: leave both untouched and continue without migrating. Same for any nested <area>/CLAUDE.md.

Route to the selected phase

Phase 0 (ambiguous) is handled inline below. For Phases 1 to 4, read only the matching mode file, then follow it:

• Phase 1 (greenfield setup) → modes/greenfield.md
• Phase 2 (whole-repo scan) → modes/whole-repo.md
• Phase 3 (area scan) → modes/area.md
• Phase 4 (gap-fill) → modes/gapfill.md

Do not read the other mode files. The greenfield and whole-repo modes additionally read modes/tool-skills.md for the Agent Skills / MCP sweep (skip it for area and gap-fill runs).

Phase 0: Classify (only when pre-flight is ambiguous)

Don't guess. Ask once via your agent's interactive option picker (AskUserQuestion on Claude Code), or plain text with the same options. Mark one option (recommended) by whichever signal is stronger (a scaffold like tree with a manifest but little history leans New; real feature code and deep history leans Existing), and the picker adds a free text custom slot last:

• question: "I can't tell if this is a new project or an existing codebase (<state why: e.g. 'a manifest exists but I see no source in a language I recognise', or 'files look like untouched scaffolding'>). Which is it?"
• header: "Project state"
• options: 1. New project, "I'll ask for your coding standards and seed the context." → Phase 1 (read the manifest/scaffold for the stack; still ask standards). 2. Existing codebase, "I'll scan what's here and document it." → Phase 2.

After all phases

If no .istm-context/agents.md was written when it should have been (the file is missing/empty), report the failure and do it again; don't relay success it didn't produce. Otherwise relay the report: what was discovered (2 to 4 bullets), what was written (file paths), what was proposed or skipped (if existing files were found).

Pattern presets

See patterns/ for the four coding style presets used in Phase 1 (greenfield mode).

Writing guide

See agent-prompt.md (the main thread reads it at write time; its per phase instructions and .istm-context/agents.md templates).