audit

# Audit Writing Guide (main thread)

You, the main thread, follow this to write the `AGENTS.md` files. ALL_CAPS placeholders are the inputs you gathered in `pre-flight` and the question rounds (listed in each phase mode file). You do the writing; the only subagent is a read only `scout` that maps a large codebase on the cheapest model.

---

You are running /audit in **PHASE** mode. Use your Read, Bash, Write, and Edit tools freely.

## Canonical context file: AGENTS.md (+ a CLAUDE.md pointer)

Durable context goes in `AGENTS.md` (root or `<area>/AGENTS.md`), tool agnostic, read by every agent. For each `AGENTS.md`, create a sibling `CLAUDE.md` importing it via Claude Code's `@` directive (other tools read AGENTS.md directly). `@AGENTS.md` resolves relative to its CLAUDE.md, so a nested CLAUDE.md imports its sibling nested AGENTS.md:

```markdown
# CLAUDE.md

This project's context for all AI tools lives in [AGENTS.md](./AGENTS.md).
Claude Code loads it via the import below:

@AGENTS.md
```

Hard rules:
- Never overwrite an existing `AGENTS.md` (possibly authored by the user or another tool). Create only when missing; otherwise propose additions via the diff format.
- `CLAUDE.md` only ever holds the pointer; never duplicate AGENTS.md content into it.
- Migration (when told `MIGRATE=yes`): copy the legacy `CLAUDE.md` content verbatim into a new `AGENTS.md`, then replace `CLAUDE.md` with the pointer above. Never discard curated content.
- A `CLAUDE.md` pointer that already points to AGENTS.md stays untouched.

## Stamp what you write, so curated content is knowable

Every `AGENTS.md` this skill creates ends with the drafted by line in the templates below, so a later run (this skill or `/sync`) can tell tool written from human written content.

- **Creating a file**: end it with the drafted by line, exactly as the template shows.
- **Gap filling a file that still carries the line**: add or fix facts surgically, leave the line in place.
- **Gap filling a file with no drafted by line**: a human took it over. Add missing facts only, never rewrite a line, route anything that would change existing prose to CONTRADICTIONS.

The stamp records provenance, not permission: it never licenses overwriting an edited line, and the "never overwrite curated prose" rule below holds either way.

## The mirrored root fields

<!-- ROOT-FIELD-CONTRACT:START (identical in /audit and /sync; edit both or neither) -->
Root `AGENTS.md` carries two mirrored fields. Each has exactly one source of truth outside the file, and no skill may invent a value for either:

- `## Stack` mirrors the architecture spec, the one under `docs/specs/` with a `## Proposed stack` section.
- `## Build approach` mirrors the scope header's build approach line, the one `/scope` records.

Three rules bind every skill that touches them. Never overwrite curated prose in either field. Fill a field only when it is missing or still a placeholder. When a field and its source disagree, flag the divergence and name the file you read the source from, rather than picking a winner.
<!-- ROOT-FIELD-CONTRACT:END -->

What `/audit` does with them (every phase that writes or audits root):

- **Creating root** (greenfield, whole-repo): populate `## Stack` from the architecture spec if it exists (source of truth, even on greenfield with no code), else the code/manifest, else `<to be filled>`. Seed `## Build approach` from the scope header if one exists (name + one line principle), else `<TBD, set by /scope>`.
- **`## Git`** (from the git integration question): write the engineer's choice as a small block, e.g. `- integration: on` / `- branch prefix: feat/` / `- commit: per-milestone`, or just `- integration: off`. Absent means off. A recorded preference, not a mirrored source of truth; `/develop` reads it to branch and commit, `/document` to gate the PR.
- **Auditing existing root** (gap-fill): either field missing or placeholder → ROOT_GAPS; either field contradicting its source → CONTRADICTIONS.

This keeps the `/architect → /audit` handoff order-independent: root absorbs the decided stack whenever audit runs.

## Phase

PHASE
<!-- one of: greenfield | whole-repo | area | gap-fill -->

## Scope / area

SCOPE_OR_AREA
<!-- "whole repo" or a specific path like "src/auth" -->

## Monorepo

MONOREPO_OR_NO
<!-- "no", or "yes, apps: web, api, …". If yes: each app/package is its own area, give each
     a nested AGENTS.md with its own stack/commands/conventions; root AGENTS.md keeps
     monorepo-wide concerns (workspace tooling, shared conventions) only. -->

## Task context

TASK_CONTEXT_OR_NONE

## Existing root AGENTS.md

ROOT_AGENTS_MD_CONTENTS_OR_MISSING
<!-- contents, or a file path for you to Read, or "MISSING" -->

## Existing area AGENTS.md

AREA_AGENTS_MD_CONTENTS_OR_MISSING
<!-- contents or a file path to Read; "MISSING" if phase is not area, or file doesn't exist -->

## Selected coding patterns (Phase 1 only)

SELECTED_PATTERNS_OR_NONE
<!-- Contents or file path(s) of the chosen pattern preset(s), or the engineer's exact "Other" text -->

## Additional standards selected (Phase 1 only)

ADDITIONAL_STANDARDS_OR_NONE
<!-- e.g. "Strict types, Conventional commits" -->

---

## Instructions by phase

---

### GREENFIELD phase

New project, possibly just scaffolded from its chosen stack (there may be a manifest and scaffold source, but no real feature code yet, and usually an architecture spec that decided the stack). Create a root AGENTS.md encoding the engineer's chosen standards.

**Step 1: Minimal discovery**

With your file tools, list the top couple of project levels (excluding `.git`); read the manifest if present (language, package manager). Check `docs/specs/` for numbered specs (`NNNN-*.md`); if an architecture spec exists (`## Proposed stack` section), read it: the stack is decided, use it for `## Stack`, no placeholders, never contradict it. Check `docs/scope/` (or `.workflow/scope/`): if the scope header records a build approach, capture it verbatim as the `## Build approach` seed; else `<TBD, set by /scope>`.

**Step 2: Create root AGENTS.md**

Use the template below. `## Stack`: spec, else findings, else `<to be filled>`. `## Build approach`: scope header, else `<TBD, set by /scope>`. `## Rules`: base on SELECTED_PATTERNS (Read it if given as a path); if "Other" free text was chosen, include it verbatim, never interpret or reformat it; append ADDITIONAL_STANDARDS as extra bullets at the end.

If `INSTALLED_SKILLS_OR_NONE` is provided, write a `## Agent skills` section (template above): ONE bullet per skill, `- [<skill>](<skills-dir>/<skill>/): `<owner>/<repo>`, <what it covers>`, so a later skill loads only the ones it needs, never a dense line of names. Detect the project's real skills directory (`.claude/skills/` on Claude Code, `.agents/skills/` on other agents, or plain `skills/`) for the link; never hardcode a Claude only path, since every tool reads this file. Keep `<owner>/<repo>` on each bullet as the tool agnostic identity. If `DECLINED_TOOLS_OR_NONE`, add a compact `Declined: <tool>, <tool>` line (nothing to load, so no location; stops a later `/audit` or `/architect` offering again it). If `MCP_SERVERS_OR_NONE`, add a compact `MCP servers: <server> (connected|recommended)` line. Project wide tech at root; area specific at that area's nested doc.

Monorepo: keep root to monorepo wide concerns (the workspace tooling, meaning the monorepo's package manager and task runner, shared standards, a `## Context files` section pointing at each workspace's nested doc); per app stack does not go in root.

**Step 2b: Per workspace nested AGENTS.md (monorepo only)**

If `MONOREPO_OR_NO` is `yes`: for each workspace (`apps/*`, `packages/*`), read its manifest. Even with no features built, the scaffold declares the workspace's stack and commands; capture them so `/architect` and `/develop` read them from the workspace's own doc (not root). Write `<workspace>/AGENTS.md` with the nested template (`## Stack` from its manifest, `## Commands` from its scripts, scoped to the workspace, e.g. a filtered dev command like `<pkgmgr> --filter <name> dev`, root `## Rules` inherited by reference), the sibling `<workspace>/CLAUDE.md` pointer, and a pointer under root's `## Context files`. Skip an empty workspace with no manifest.

**Step 3: Report** (format at the bottom); list every per workspace doc created.

---

### WHOLE-REPO phase

A codebase exists but no AGENTS.md. Explore enough to write an accurate root AGENTS.md.

**Step 1: Discover**

With your file tools, list the project tree a few levels deep, skipping vendored/generated dirs (`.git`, `node_modules`, `.next`, `dist`, `build`). Read whichever exist:
- `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`: stack and deps
- `.github/workflows/`: CI and deploy patterns
- Main entry point (`src/index.*`, `main.*`, `app.*`, `server.*`)
- Test config (`jest.config.*`, `pytest.ini`, `vitest.config.*`)
- All existing `AGENTS.md` (excluding `.git`); for each nested one found (not the root), add a pointer line under `## Context files` when writing root: `- [<path>](<path>): <one-line description inferred from the file's ## Overview section>`.

**Step 2: Extract durable knowledge**

Stack, runtime, framework; daily commands (install, dev, build, test); conventions visible in the code (naming, file structure, patterns); what would trip up a new developer in week one. Discard implementation details, TODO comments, anything that changes frequently.

**Step 3: Create root AGENTS.md** with the template below; global and short (≤60 lines), area detail goes in nested docs (next step).

**Step 4: Create nested AGENTS.md**

Monorepo (`MONOREPO_OR_NO` = yes): don't judge or deep scan. Every workspace (`apps/*`, `packages/*`) gets a light stub `AGENTS.md` at its root (`## Stack` + `## Commands` from its manifest, scoped, e.g. `<pkgmgr> -F <name> …`, plus a one line overview), the sibling `CLAUDE.md` pointer, and a root `## Context files` pointer. Deep conventions come later via `/audit <workspace>`. A doc buried below a workspace root with no root doc: follow the relocation rule the main agent surfaced. Skip the judgment step below.

Single repo: identify the major areas/modules (e.g. `src/auth`, `src/payments`, `src/api`); judge each. Warrants a nested doc: distinct conventions, not obvious rules, local commands, external integrations, or gotchas a developer must know before touching it. Does not: a simple module with no surprises, or root already covers it (skip; never one per folder). For each warranted area: write `<area>/AGENTS.md` with the nested template, its sibling `<area>/CLAUDE.md` pointer, and one pointer line in root's `## Context files` via Edit:
```
- [<area>/AGENTS.md](<area>/AGENTS.md): <one-line description>
```
Global facts in root; area knowledge kept alongside the area's code (it loads automatically when that code is edited).

**Step 5: Report** (format at the bottom); list every nested doc created.

---

### AREA phase

Root AGENTS.md exists. Job: (1) check whether root AGENTS.md has what this area needs, (2) create or update the nested AGENTS.md.

**Step 1: Explore the area**

With your file tools, list all files under `SCOPE_OR_AREA`. Read: key source files (entry points, main modules, not every file, use judgement); test files in this area; any local config (tsconfig, .env.example, etc.); the existing root and area AGENTS.md (provided above; Read them if given as paths).

**Step 2: Gap check root AGENTS.md**

Flag a gap only if it is: a command engineers working in this area need but root doesn't mention; a stack element, runtime, or major dependency relevant to this area but absent from root; a hard project wide rule the area makes visible (e.g. "all DB calls go through the repository layer"). Do NOT flag area specific file lists, local conventions, or anything that belongs in a nested file.

Collect gaps in this format for the final report under `Root gaps flagged`:

```
ROOT_GAPS:
- <exact markdown line to add>, target section: `## <section>`, reason: <one line>
```

If no gaps: `ROOT_GAPS: none`. Keep the exact text to insert so you can apply it with Edit without paraphrasing.

**Step 3: Nested AGENTS.md**

Warrant (own patterns, not obvious rules, local commands, or constraints a developer needs to know first) vs not (a simple CRUD module with no surprises, or already well covered by root AGENTS.md).

- Missing + warranted → create with the nested template, then add a pointer to root AGENTS.md (all root modifications via Edit): `## Context files` holding only a placeholder comment (`<!-- ... -->`) → replace the comment line with the pointer; existing entries → append the pointer line; section absent → add the section and pointer before `## specs` (or at the end if no specs section).
- Missing + not warranted → note why in the report and skip.
- Exists → propose additions only (never overwrite), via the diff format below.

**Step 4: Report** (format at the bottom).

---

### GAP-FILL phase

Root AGENTS.md already exists; the codebase is partially documented. Audit the whole codebase against the existing docs and fill only what's genuinely missing; never rewrite curated content.

**Step 1: Read what's documented**

Read the existing root AGENTS.md (provided above; Read it if given as a path) and every nested AGENTS.md (paths provided above).

**Step 2: Scan the codebase**

With your file tools, list the project tree a few levels deep, skipping vendored/generated dirs (`.git`, `node_modules`, `.next`, `dist`, `build`). Read the manifest(s), CI config, entry points, and a sample of each major area; build a picture of the real stack, commands, conventions, and major areas.

**Step 3: Find four kinds of finding**

- (a) Global facts missing from root: a daily command, stack element, project wide rule, or the build approach (in the scope header but absent from root) that's true but unrecorded. Collect each as a `ROOT_GAPS` line (exact markdown + target section); apply only with the engineer's permission (the gap handling step in `modes/gapfill.md`), never silently, since a root line may be curated.
- (b) Undocumented areas: a major area with distinct conventions/gotchas and no nested AGENTS.md. Create the nested doc (nested template + sibling CLAUDE.md pointer) and add its root pointer line via Edit (safe to do directly: creating, not overwriting).
- (c) Stale/incomplete nested docs: an existing nested AGENTS.md missing something now true of its area. Return as `PROPOSED_ADDITIONS`; do NOT edit it yourself.
- (d) Contradictions: a doc states something the codebase or its governing records disprove (documented test runner or framework isn't the one used; `## Stack` conflicts with the architecture spec; `## Build approach` differs from the scope header; a documented command no longer exists). Worse than a gap: the docs are actively wrong. Collect each as a `CONTRADICTIONS` entry naming the doc, what it says, and what the code/spec/scope actually shows; surface to the human, never fix automatically (the line may be curated).

Be conservative: flag only durable findings you're confident about; when unsure, leave it. Do not flag implementation detail, TODOs, or anything that churns.

**Step 4: Report** (format at the bottom). Put (a) under `Root gaps flagged`, (c) under `Proposed`, (d) under `Contradictions`, and list (b), the nested docs you created, under `Written`.

---

## Root AGENTS.md template

=== ROOT AGENTS.md TEMPLATE START ===
# <Project name>

## Stack

- **Language / Runtime**: <e.g. TypeScript, Node 20>
- **Framework**: <e.g. Next.js 14, Express>
- **Key dependencies**: <3 to 5 most important>
- **Package manager**: <npm / pnpm / yarn / pip / cargo>

## Build approach

<The project's default build strategy, a short line: name + one line principle. A project wide
 convention every skill reads (like the stack). Seeded from the scope header; `<TBD, set by
 /scope>` if none is set yet. The approach is one of:
 - **Tracer Bullet**, vertical end to end slices, thin but complete through every layer
 - **Skateboard**, ship the thinnest usable whole, then grow it
 - **Facade**, UI first shell, then wire the real behavior behind it (prototype led)
 - **Journey**, build the full user path, one phase at a time>

## Commands

```bash
# Install
<command>

# Dev server
<command>

# Build
<command>

# Test
<command>
```

## Specs

Stored in `docs/specs/`. Format: `docs/specs/NNNN-title.md`.

## Rules

<Conventions that apply everywhere, from pattern presets and/or discovered from code.
  For greenfield: paste the selected pattern conventions here.
  For whole-repo: extract what you observe in the code.
  Keep this to 5 to 10 bullet points max.>

## Agent skills

<Installed Agent Skills carrying this project's tool conventions, ONE bullet each (rules in
  greenfield Step 2), omit the section if none. Only project wide skills here; an area specific
  skill goes in that area's nested AGENTS.md.>
- [<skill>](<skills-dir>/<skill>/): `<owner>/<repo>`, <one line: what it governs>

<Then, only if present, a compact line each (a declined tool has nothing to load, and an MCP
  server is a connected service with no local file, so both stay lines, not bullets):
  `Declined: <tool>, <tool>` (offered before, not wanted; keep so a later /audit or /architect
  does not offer it again) · `MCP servers: <server> (connected), <server> (recommended)`>

## Context files

<!-- Nested AGENTS.md files are listed here as they are created -->

_Drafted by /audit from the repo, worth a quick human pass. Edit freely: once a line stops matching this draft, later runs treat it as curated and will flag rather than overwrite it._

=== ROOT AGENTS.md TEMPLATE END ===

---

## Nested AGENTS.md template

```markdown
# <Area name>

## Overview

<2 to 3 sentences: what this area does and why it exists>

## Key files

| File | Owns |
|---|---|
| <path> | <what it does, one line> |

## Commands

<Local commands if different from root, omit section if identical>

## Conventions

<Bullet list of area-specific conventions, constraints, and non-obvious rules>

## Gotchas

<Non-obvious invariants that would trip a developer, omit section if none>

## Agent skills

<Area specific skills, same bullet format as root, omit if none:
  - [<skill>](<skills-dir>/<skill>/): `<owner>/<repo>`, <what it governs for this area>
  A declined tool or MCP server stays a compact `Declined:` / `MCP servers:` line, as in root.>

## Related specs

<Links once specs exist, omit section if none yet>

_Drafted by /audit from the repo, worth a quick human pass. Edit freely: once a line stops matching this draft, later runs treat it as curated and will flag rather than overwrite it._
```

---

## Proposed diff format (when a file already exists)

Do not overwrite. Output this block and stop:

```
PROPOSED_ADDITIONS for <file path>:

Under `## <section>`, add:

<exact markdown to insert>

Reason: <one line>
```

Only propose what is absent and genuinely useful. Do not rewrite existing content.

---

## Report format (end of every phase)

Lead with what was written and the next step; list only what needs the engineer (per `docs/conventions.md`). The AGENTS.md contents are in the files, not the chat. Template:

```
## /audit complete · <greenfield | whole-repo | area | gap-fill>

**Wrote <AGENTS.md files: created / updated / pointer added>, capturing <stack · conventions · tooling · git setting>.**
Next: <the first unticked scope box, usually `/develop tooling`, or `/develop <first feature>`>
Heads up (need you):
- Root gap: <ROOT_GAPS, one line each>   (area / gap-fill only)
- Proposed additions to an existing file, apply? <PROPOSED_ADDITIONS, one line each>
- Contradiction, docs the code disproves, resolve: <CONTRADICTIONS, one line each>
```

Drop any Heads up bullet with no items, and the whole block if there are none.

---

## Rules you must not break

- Write the `AGENTS.md` files with your file tools; don't paste their full contents back into the chat. When the phase is done, produce the report block at the end as your working summary for the relay.
- ROOT_GAPS goes under `Root gaps flagged` in that summary. Keep the exact markdown text to insert so you apply it (with the engineer's permission) without paraphrasing.
- Do not create a nested AGENTS.md unless the area genuinely warrants it.
- Root AGENTS.md must stay under ~60 lines. Cut ruthlessly.
- Never overwrite an existing AGENTS.md, propose additions only via the diff format.
- Do not create specs. Do not write plans. Stay in your lane.
- Proposed additions must be additions only, no rewrites of existing sections.
- When the engineer selected "Other" for architecture style, use their free text verbatim in `## Rules`. Do not interpret or paraphrase it.

# OpenAI Codex adapter. This file supplies the interface metadata Codex shows in
# its agent picker. The skill's actual instructions live in ../SKILL.md, which the
# Agent Skills client installs alongside this file and loads when the skill runs.
interface:
  display_name: "Audit"
  short_description: "Bootstrap project AI context files"
  default_prompt: "Run the audit skill: read its SKILL.md, then create or refresh the AGENTS.md context files for this project."

# Audit Mode: area scan (Phase 3)

Trigger: a path or area name was given (e.g. `/audit src/auth`).

Pre-flight additionally:
1. Check the area path exists. If not: stop immediately, tell the engineer "Path `<area>` not found. Check the path and try again.", and do nothing further.
2. Root `AGENTS.md` (the canonical file): missing, with no legacy CLAUDE.md to migrate → run the whole-repo scan (`modes/whole-repo.md`) fully first (write root AGENTS.md + CLAUDE.md pointer), then continue with the area scan. Only a legacy root `CLAUDE.md` → run the legacy migration first. Exists → proceed directly.
3. Check if `<area>/AGENTS.md` exists; note present or missing.

The main thread writes the area's `AGENTS.md` itself, following the AREA phase in `agent-prompt.md`. Reading the area is the expensive part: for a large area, offload it to a read only `scout` subagent on the cheapest model (Claude Code: `haiku`, not inheriting the session model) that returns a compact map, then write from it; a small area, read directly. Read `agent-prompt.md` at write time. The inputs to apply: `PHASE=area`, `AREA=<path>`, root AGENTS.md path, area AGENTS.md path or MISSING. Add the nested pointer line to root `AGENTS.md` via the Edit tool; do not create root again. The AREA phase produces its `Root gaps flagged` output for you to handle below.

After writing, handle the `Root gaps flagged` section:
- `ROOT_GAPS: none` → relay the full report, done.
- Gaps exist → ask (one option marked recommended, the picker adds a free text custom slot last): Question: "I found things in `<area>` not reflected in root AGENTS.md. What should I do?" Option 1: `Add them now (recommended)`, description: "I'll apply the additions immediately". Option 2: `Show me the diff`, description: "Print exactly what would change; I'll apply it manually". Option 3: `Skip for now`, description: "Leave root AGENTS.md as is".
- On `Add them now`: locate the `ROOT_GAPS:` block and extract each line starting with `- ` (each holds the exact markdown to insert and the target section, `target section: ## <section>`). Apply one Edit call per gap into root `AGENTS.md`. Do not paraphrase.
- On `Show me the diff`: print each addition as a fenced markdown block with the target section labelled. Do not write.
- On `Skip for now`: do nothing.

Relay the full report after the choice is applied.

# Audit Mode: gap-fill (Phase 4: root AGENTS.md already exists)

Trigger: no area argument, codebase exists, AND root AGENTS.md already exists (including right after a legacy `CLAUDE.md` migration). Audit the whole codebase against what's written and fill the holes, conservatively.

Pre-flight additionally: note root `AGENTS.md`'s path, and list all nested `AGENTS.md` paths (excluding `node_modules` and `.git`) to pass inline.

The main thread does the gap-fill itself, following the GAP-FILL phase in `agent-prompt.md`. The scan reads the whole codebase against the existing docs: for a large repo, offload the reading to a read only `scout` subagent on the cheapest model (Claude Code: `haiku`, not inheriting the session model) that returns a compact map, then work from it; a small repo, read directly. Read `agent-prompt.md` at write time. The inputs to apply: `PHASE=gap-fill`, root AGENTS.md path, nested AGENTS.md paths list.

After the scan, handle proposals before applying:
- Nested docs you created for clearly undocumented areas → already written; list them in the relay.
- `ROOT_GAPS` and `PROPOSED_ADDITIONS` to existing files → ask (`Add them now` / `Show me the diff` / `Skip for now`) exactly as in the area scan; apply with `Edit` (verbatim, no paraphrase) on `Add them now`.
- `CONTRADICTIONS` (docs the code disproves) → surface to the engineer, do not auto fix (these touch possibly curated lines). Relay each as "`<doc>` says *X*, but the code/spec shows *Y*" and let them decide (correct it, or update the code). Never silently overwrite.

# Audit Mode: greenfield setup (Phase 1)

Trigger: greenfield, including the workflow setup case (a stack spec exists but no root AGENTS.md), or Phase 0 → `New project`. A manifest and scaffold source may exist; that is the scaffold, not a existing codebase, so still ask the standards.

Step 1, ask coding patterns AND tooling. The main thread asks as decision panels, up to 4 per round, as many rounds as it takes. Every panel has exactly one `(recommended)` option and ends with a free text custom slot (Claude Code's picker adds "Other" automatically; in a plain text fallback add it as the last option). Be thorough: this is the one place conventions and tooling get set, so grill the engineer on every choice rather than assuming a default. First read the real scaffolded project (manifest, config, installed tools), then tailor every question: skip one the stack already settles, list an already installed tool first as recommended, phrase options for the actual language and framework. `/audit` records the choices, installs nothing; installing (packages, config, `pre-commit` hooks, CI) is the `/develop tooling` sub task that follows, but ask the tooling questions here where the choice is recorded.

Architecture & code conventions:
- Architecture style: present all four preset options without reading their files into context yet: Clean Architecture (`patterns/clean-architecture.md`), Functional (`patterns/functional.md`), Domain Driven Design (`patterns/domain-driven.md`), and SOLID OOP (`patterns/solid-oop.md`). At write time (Step 3) you read only the chosen preset file.
- Type strictness (typed languages only; skip if untyped): `strict` (no `any`, exhaustive types) · `gradual` (strict for new code) · `loose`.
- Module & folder structure: `folder-by-feature` (colocate by feature) · `by-layer` (controllers/services/repos) · match what the scaffold already set.
- Additional code standards (multi select): documented public APIs · a consistent error handling pattern · validate env vars at startup · named exports only (no default exports) · consistent naming conventions · accessibility baseline on UI (WCAG AA) · conventional commit messages.

Tooling (asked here, installed by `/develop tooling`):
- Linting & formatting (adaptive): the standard linter + formatter for this stack (suggested; list an already installed one first) · a specific alternative · minimal for now.
- Checks before commit: lint + format + typecheck on every commit (suggested) · format only · none.
- Testing gate (captured as the convention, the runner is set up by `/test`): unit + integration with a framework (suggested) · typecheck + manual `/check verify` only · tests first (TDD).
- Continuous integration: a basic CI check on push (lint, typecheck, test) (suggested) · not yet · already configured.
- Git integration (recorded as the `## Git` block in AGENTS.md): let the workflow branch per feature, commit as milestones land, and drive PRs (`on`, suggested for solo/most) · manage git yourself (`off`). If `on`, also capture `branch prefix` (default `feat/`) and `commit` granularity (`per-milestone` (suggested) · `end-of-build` · `manual`). Push and PRs always confirm regardless. **On `on`, if the project is not yet a git repo (`git rev-parse` fails), run `git init` now and offer an initial commit of the scaffold and docs, so the repo exists from the moment integration is enabled.** On `off`, never init; the engineer owns git.

Adapt the list: drop what doesn't apply (no CI question for a throwaway prototype, no type strictness for an untyped language); add any stack specific convention worth pinning.

Step 2, resolve SELECTED_PATTERNS: a named pattern → the absolute path of the matching `patterns/*.md` file (path only, do not inline its contents). "Other" (free text) → the engineer's exact typed text, passed inline (no file).

Step 3, run the Tool skills sweep (`modes/tool-skills.md`, whose web/registry discovery runs in a `researcher` subagent), then write the files yourself. Read `agent-prompt.md` and the selected pattern preset file now, and follow the GREENFIELD phase instructions to write root `AGENTS.md` + its `CLAUDE.md` pointer. The inputs to apply: `PHASE=greenfield`; `SELECTED_PATTERNS=<pattern file path, or the Other free text>`; `ADDITIONAL_STANDARDS=<all the other Step 1 selections: code standards, type strictness, folder structure, AND the tooling choices (lint/format, pre-commit, testing gate, CI), AND the git integration choice written as a `## Git` block (`integration`, `branch prefix`, `commit`)>`; `MONOREPO_OR_NO` (`yes, apps: web, api, …` if detected); plus the sweep's `INSTALLED_SKILLS` / `DECLINED_TOOLS` for the `## Agent skills` section (one bullet per skill with its location, per `agent-prompt.md`). Capture the tooling choices clearly (a short `## Tooling` note or explicit Rules lines) so `/develop tooling` installs exactly what was chosen. Per `agent-prompt.md`, seed `## Stack` from the architecture spec (the workflow setup case always has one), seed `## Build approach` from the scope header (else `<TBD, set by /scope>`), and add per workspace nested docs if `MONOREPO=yes`.

# Tool skills & MCP sweep (offer matching Agent Skills and MCP servers)

Read this from the greenfield mode (after scaffold) and the whole-repo mode, once the real stack is known (greenfield: from the scaffolded manifests read in Step 1; brownfield: from the repo scan). `/architect` offers when a tool is chosen; this covers whatever is already installed.

## Step 1: Ask first (the consent gate)

<!-- TOOL-CONSENT:START (identical in /architect, /audit and /sync; edit all or none) -->
**Asking is mandatory. Searching is not.** Nothing is searched, fetched, installed, or spawned for Agent Skill and MCP discovery until the engineer has picked. Offer four choices: find them for me, I will name the ones I want, no and record the decline, or not now. Only the first may run a search command. Never silently skip the offer, and never run a search before the engineer agrees to one.
<!-- TOOL-CONSENT:END -->

Say in your own words why it is worth doing: an Agent Skill teaches the agent a tool's real conventions so the build follows them, and an MCP server gives live access to the real system rather than assumptions. Then ask (capability first: `AskUserQuestion` on Claude Code, else the same options as plain text; exactly one recommended; the picker adds its own free text option):

- **question**: "Want me to find Agent Skills and MCP servers for this project's stack?"
- **header**: "Agent skills"
- **options**:
  1. `Yes, find them for me` (recommended): "I'll search the registry for what this project already uses, then show you what I find. Nothing installs without your pick."
  2. `I'll name the ones I want`: "Tell me which skills or servers, and I'll add exactly those. No searching."
  3. `No, skip it`: "Build without them. I'll record the decline so nothing offers them again."
  4. `Not now, later`: "I'll note the candidates in the report so you can add them when you want."

Act on the pick. `Yes` → Step 2, then Step 3. `I'll name the ones I want` → no search: take the list, confirm each with `npx skills add <owner>/<repo> --list` where practical, install per Step 3, record per Step 4. `No, skip it` → run nothing, record the decline per Step 4. `Not now, later` → run nothing, name the candidate tools in the report.

## Step 2: Discover (only after `Yes, find them for me`)

- Build a `TOOL_DISCOVERY_SET` first, covering every layer the project really uses: runtime, framework, router, styling or UI kit, database, ORM, auth, payments, email, storage, search, queues, AI or vector DB, testing, observability, hosting. Include package names and common aliases from the manifests. Do not stop after the first technology.
- **Run it in the background, keep working.** Hand the set to a read only discovery subagent and do NOT wait on it. Set its model explicitly to a fast, low cost tier, never the session model (Claude Code: the `researcher` type, which pins the model and carries the registry CLI plus web tools). It returns ONLY the compact candidate list, grouped by technology, minus installed and declined. Greenfield: start it right after the consent pick so searches overlap the standards questions; collect the result just before the offer. Fallbacks: no background support → same subagent, blocking; no subagent → search inline; no search capability → skip and note in the report. The offer panel stays on the main thread, since a subagent cannot prompt the engineer.
- For each item not already covered by an installed skill or connected MCP (`npx skills list`, your connector list) or recorded as declined in `AGENTS.md`: detect Agent Skills with `npx skills find <tool-or-package>`; if weak, retry aliases from package or org names; collect every credible candidate and confirm with `npx skills add <owner>/<repo> --list` when practical. Detect MCP servers from the connector list first, else search `"<tool>" "MCP server"`. Never hardcode a list of which tools have skills or servers.
- Keep discovery capped and cacheable: the discovery subagent does the searches (not one subagent per tool). Max 5 web searches and 8 fetched pages total, official registry and docs first. Reuse `docs/.agent-cache/tool-discovery/<slug>.md` if under 30 days old, after filtering installed and declined items.

## Step 3: Offer what you found, then install what is picked

- Offer Agent Skills as one panel allowing several picks: "Install relevant Agent Skills for this stack?", every found skill grouped by technology, plus skip and decline. Then MCPs separately, as optional: "Optional MCP servers that could help this stack", plus skip and decline. Never install or connect automatically. Found nothing? Say so and move on; never invent a candidate to fill the panel.
- Install each selected skill: `npx skills add <owner>/<repo> -y`. Connecting an MCP is a user config step (their MCP or connector settings, e.g. `claude mcp add …`); you can't do it for them, so point them there. Once connected the tools are used automatically.

## Step 4: Record

Carry `INSTALLED_SKILLS` / `MCP_SERVERS` / `DECLINED_TOOLS` into the `## Agent skills` section of the `AGENTS.md` you write, in the exact format `agent-prompt.md` gives: one bullet per installed skill, plus compact `Declined:` and `MCP servers:` lines. Use the project's real skills dir, never a hardcoded Claude only path. Declines stop a later run offering again them. Project wide tech at root; area specific in the nested area doc.

No search, install, or connect capability? Skip the offer; note in the report which tools might have a skill or MCP worth a manual look.

# Audit Mode: whole-repo scan (Phase 2: root + judged nested)

Trigger: pre-flight classified the repo as clearly established (real feature code, real history, no in-progress workflow setup), or Phase 0 → `Existing codebase`. Run the Tool skills sweep (`modes/tool-skills.md`, web/registry discovery in a `researcher` subagent) once the scan has identified the stack, before/with writing `AGENTS.md`.

The main thread writes root + nested `AGENTS.md` itself, following the WHOLE-REPO phase in `agent-prompt.md`. The scan reads across the codebase, the one expensive part: for a large repo, offload just the reading to a read only `scout` subagent on the cheapest model (Claude Code: `haiku`, not inheriting the session model), briefed to return a compact map (stack, commands, major areas, conventions, gotchas), and write from that map; for a small repo, read it directly. The inputs to apply: `PHASE=whole-repo`, root AGENTS.md noted as MISSING, `MONOREPO_OR_NO`. Read `agent-prompt.md` at write time.

# Clean Architecture

**MCQ label**: Clean Architecture
**MCQ description**: Strict layer separation, domain logic never touches frameworks or I/O. Scales well for complex business rules.

## Conventions

- Code is organized in four layers: `domain` (entities, value objects), `application` (use cases), `infrastructure` (DB, APIs, frameworks), `presentation` (UI, controllers).
- Dependency rule: outer layers depend on inner layers, never the reverse. Domain has zero external imports.
- Use cases are thin orchestrators. They call domain logic and infrastructure interfaces, never implement business rules themselves.
- Infrastructure implements interfaces defined in the domain or application layer (dependency inversion).
- No framework or ORM code (web framework, ORM, HTTP client, etc.) appears inside `domain/` or `application/`.
- Entities contain business rules and enforce their own invariants. They are plain objects with no ORM decorators.
- All cross boundary communication uses DTOs or plain objects. No domain entities leak into the presentation layer.
- Tests: domain and application layers are unit tested with no mocks of infrastructure. Infrastructure is integration tested against real systems.

# Domain Driven Design

**MCQ label**: Domain Driven Design (DDD)
**MCQ description**: Model the business domain explicitly. Bounded contexts, aggregates, and domain events. Best for complex, evolving business logic.

## Conventions

- The codebase is organized around bounded contexts. Each context owns its model and does not share domain objects with other contexts.
- Aggregates are the consistency boundary. Only aggregate roots are referenced by ID across context lines.
- Domain events model things that happened (`UserRegistered`, `OrderPlaced`). They are immutable facts, past tense, named after business occurrences.
- The ubiquitous language of the business domain is used in code. Class names, method names, and variables mirror terms the domain expert uses.
- Value objects represent domain concepts with no identity (e.g. `Money`, `Email`, `Address`). They are immutable and validated on construction.
- Repositories abstract persistence. The domain layer defines the repository interface; infrastructure implements it.
- Application services coordinate use cases. They do not contain domain logic. That belongs in aggregates and domain services.
- Anti corruption layers isolate external systems (third party APIs, legacy services) from the domain model.
- Context maps document how bounded contexts relate: shared kernel, customer supplier, conformist, anti corruption layer.

# Functional & Immutable

**MCQ label**: Functional / Immutable
**MCQ description**: Pure functions, no shared mutable state. Predictable, easy to test, composable.

## Conventions

- Functions are pure by default: same input always produces same output, no side effects.
- Data is immutable. Use `const`, `Object.freeze`, `readonly`, or immutable data structures. Never mutate in place.
- Side effects (I/O, network, state changes) are pushed to the edges of the system and kept explicit.
- Prefer function composition over inheritance. Avoid classes where a plain function works.
- No shared mutable state. Module level variables are constants only.
- Transformations use `map`, `filter`, `reduce` over imperative loops where it improves readability.
- Avoid `null`. Use `Option`/`Maybe` types or explicit `undefined` with union types.
- Error handling uses `Result`/`Either` types or explicit error returns rather than exceptions for expected failures.
- Tests are trivial: pure functions need no mocks, just input/output assertions.

# SOLID OOP

**MCQ label**: SOLID + OOP
**MCQ description**: Classic object oriented design with SOLID principles. Dependency injection, interfaces, and single responsibility classes.

## Conventions

- **Single Responsibility**: each class has one reason to change. Split classes that do more than one job.
- **Open/Closed**: classes are open for extension, closed for modification. Add behaviour via new classes or composition, not by editing existing ones.
- **Liskov Substitution**: subclasses must be substitutable for their base class without changing program correctness. Prefer composition over deep inheritance.
- **Interface Segregation**: prefer small, focused interfaces over large ones. Callers depend only on methods they use.
- **Dependency Inversion**: high level modules depend on abstractions, not concretions. Wire dependencies at the composition root via constructor injection.
- No service locator or global registry. Dependencies are explicit in constructors.
- Classes are small (aim for under 200 lines). If a class grows beyond that, look for a responsibility to extract.
- Favour composition over inheritance beyond one level deep.
- Name classes after what they do, not what they extend (`UserRepository`, not `AbstractBaseUserImpl`).
- Tests inject fakes or stubs via constructor. No patching of globals or module internals.

---
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, templates) plus, in Phase 1, the selected pattern preset; then write following it. 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 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 AGENTS.md is MISSING while the workflow has already decided the stack, i.e. a `docs/specs/` architecture spec exists (a `## Proposed stack` section), and/or `docs/scope/` has a "Stack and architecture" (or similar foundational scaffold) feature. This is the intended greenfield order (`/scope` → `/architect` decides the stack → `/develop` scaffolds it → `/audit`): freshly scaffolded, still needs coding standards captured. When it fires, the manifest and scaffold source that now exist are the scaffold, not a existing codebase.

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: a fresh scaffold has a manifest and starter files but is still greenfield, so a raw code count alone would misread it as brownfield and skip the standards questions; the workflow setup signal catches that and routes to greenfield. Truly brownfield (Phase 2) means real feature code, real history, and no workflow setup in progress. Anything ambiguous falls to Phase 0; 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/AGENTS.md`), never buried deeper. A whole-repo run does not deep scan every workspace; write the repo root `AGENTS.md` (monorepo wide tooling, shared conventions) plus a light stub per workspace from its manifest, no code scan, with root pointers. The full conventions/gotchas/key files scan happens when the engineer runs `/audit packages/api` (Phase 3) or first builds there. 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 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/AGENTS.md`, or keep it as a nested doc under a new `packages/ui/AGENTS.md`?" On move: relocate it to the workspace root. On keep nested: create the workspace root `AGENTS.md` AND keep the deep one, linked from root. 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 `AGENTS.md`. I'll move its content into a new `AGENTS.md` (so all tools read it) and replace `CLAUDE.md` with a pointer. Proceed?" On yes: copy the content verbatim into `AGENTS.md`, then replace `CLAUDE.md` with the pointer; `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 `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 `AGENTS.md` templates).