# Risk paths that seed `## Never merges without a human` in a generated AGENTS.md.
#
# This file is the source of truth. The table in
# references/detection-tables.md is GENERATED from it by tools/gen_detection_tables.py,
# and CI fails if the two drift apart.
#
# Read `confirm` as the question you must answer by OPENING the file. A glob match
# is a candidate, never a conclusion. A wrong entry in the boundary is worse than a
# missing one: it puts a human back into merges that never needed one, and the first
# time a reader spots an obviously-wrong line they stop trusting the whole section.

version: 1

rows:
  - id: schema-data-loss
    label: Schema / data loss
    globs:
      - "**/migrations/**"
      - "**/*.sql"
      - "prisma/schema.prisma"
      - "alembic/**"
    why: Dropped columns and destructive migrations cannot be reverted by reverting the commit
    confirm: Does this run against a real database, or is it a seed or fixture that gets recreated?

  - id: api-contract
    label: API contract
    globs:
      - "**/openapi.*"
      - "**/swagger.*"
      - "**/*.proto"
      - "**/schema.graphql"
    why: Other teams and released clients already depend on the current shape
    confirm: Is this contract published to anyone outside this repo, or internal-only and versioned together?

  - id: auth-permissions
    label: Auth / permissions
    globs:
      - "**/auth/**"
      - "**/authz/**"
      - "**/*permission*"
      - "**/*role*"
      - "**/iam/**"
      - "**/*policy*.json"
    why: Widening access is silent and rarely caught by tests
    confirm: Does this code DECIDE what someone may do, or only carry a token somebody else issued?

  - id: money
    label: Money
    globs:
      - "**/billing/**"
      - "**/payment*/**"
      - "**/checkout/**"
      - "**/invoice*/**"
    why: Mistakes move real money and are visible to customers
    confirm: Does this path run in production against a real payment provider?

  - id: customer-contact
    label: Customer contact
    globs:
      - "**/email*/**"
      - "**/notification*/**"
      - "**/sms/**"
      - "**/templates/email/**"
    why: Messages cannot be unsent
    confirm: Does this send something to a person outside the team, or is it an in-app toast or log line?

  - id: infrastructure
    label: Infrastructure
    globs:
      - "infra/**"
      - "**/*.tf"
      - "**/*.bicep"
      - "k8s/**"
      - "helm/**"
    why: Blast radius is the whole environment, not one service
    confirm: Is this applied to a shared or production environment, or only to a local or ephemeral one?

  - id: secrets-config
    label: Secrets & config
    globs:
      - "**/*.env"
      - "**/*.env.*"
      - "**/secrets/**"
    why: A leaked credential is not revertible in any useful sense
    confirm: Is this file tracked in git, and does it hold a real value rather than a placeholder?

  - id: release-plumbing
    label: Release plumbing
    globs:
      - ".github/workflows/**"
      - "**/release*.sh"
      - "**/publish*.sh"
    why: A change here changes how every other change ships
    confirm: Does anything actually ship from this repo, or does the workflow only run checks?

# Globs that LOOK like a row above and usually aren't. When one of these matches,
# the `confirm` question is not optional — open the file before writing anything.
# Every entry here was a real false positive in a real repo.
false_positives:
  - id: toast-not-customer
    glob: "**/notification*.*"
    looks_like: customer-contact
    usually_is: An in-app or editor toast, not a message to a customer
    seen_in: johnpapa/vscode-peacock — src/notification.ts is window.showInformationMessage

  - id: token-not-permission
    glob: "**/auth/token*.*"
    looks_like: auth-permissions
    usually_is: Reading or refreshing a token somebody else issued, not a permission decision
    seen_in: Client libraries and SDK wrappers

  - id: seed-not-migration
    glob: "**/seeds/**/*.sql"
    looks_like: schema-data-loss
    usually_is: Seed data that is recreated, not migrated
    seen_in: Most application repos with a local dev database

  - id: fixture-not-money
    glob: "**/fixtures/**"
    looks_like: money
    usually_is: Test fixtures that never touch a payment provider
    seen_in: Any repo with payment tests

  - id: example-not-secret
    glob: "**/*.env.example"
    looks_like: secrets-config
    usually_is: A placeholder template, committed on purpose
    seen_in: Nearly every repo that has a .env at all

# AGENTS.md Reference

What belongs in `AGENTS.md`, what does not, and where the rest goes. Read this in Step 2.

## The discoverability test

Before writing any section, ask:

> **Can the agent find this by reading the code?**

If yes, **do not write it down.** It costs attention on every task and buys nothing.

| Commonly generated | Verdict |
|---|---|
| A directory tree of `src/`, `tests/`, `docs/` | **Cut.** The agent can list the directory |
| A statement of the language or framework | **Cut.** The manifest says so |
| An architecture summary restating the file layout | **Cut.** Same information, stale within a month |
| A data-model summary | **Cut.** It can read `schema.prisma` |
| Build, test and lint **commands** | **Keep.** Often buried in tooling config, and needed every task |
| *Why* the layout is unusual — a directory that is not what it looks like | **Keep.** Not discoverable |
| Conventions mined from PR reviews | **Keep.** Exists nowhere in the code |
| The maintenance matrix | **Keep.** Cross-file coupling is the hardest thing to infer |
| `## Done means` / `## Never merges without a human` | **Keep.** Decisions, not facts |

Structure and stack sections are the ones to be ruthless about: generate them only for what is **surprising**,
and skip them entirely when the layout is conventional. A repo with `src/`, `tests/` and `docs/` needs no
structure section at all.

## Two rules with no room for judgment

- **State the positive rule, never the prohibition.** Write `Use the v2 client in lib/api/`, not `Do not use
  the v1 client`. Naming a deprecated thing makes the model more likely to reach for it, not less.
- **Never state the same convention in two files. Do split by scope.** A rule that only applies to
  `packages/api/` belongs in `packages/api/AGENTS.md`.

## Where everything else goes

Four placements, in order. Ask "how often is this needed?" and put it at the first one that fits.

| Needed | Goes in | Why |
|---|---|---|
| On **every** task | Root `AGENTS.md` | This is what the root file is for, and the only thing it is for |
| Only in one area of the repo | A **nested `AGENTS.md`** in that directory | Loaded only when work happens there |
| Only when performing one procedure | A **skill** (`.github/skills/`, Step 4d) | Loaded when its description matches the task |
| Rarely, or as lookup material | A linked doc in `docs/` | Read on demand, costs nothing until then |

**Nested `AGENTS.md` is part of the standard, not a workaround.** Agents walk up the directory tree from the
file being edited and combine every `AGENTS.md` they find, with the **closest one winning** on conflicts. This
is the intended way to scale: OpenAI's main repository carries dozens of them.

So for a monorepo, per-area conventions belong in `packages/<area>/AGENTS.md`, not in a growing root file. The
root keeps only what is true everywhere.

## Length

Start at **20–30 lines** and grow only when a real agent mistake proves something is missing. Treat **150** as
a ceiling rather than a target: past it, move something. Never delete something load-bearing to hit a number.

The difference between a target and a ceiling matters here. A target invites filling. This file gets *worse*
as it gets longer, because the rules compete with each other for a finite instruction budget.

When it grows past that, work down the placement table above. If a section cannot move because it genuinely
applies to every task, it stays — and the file is longer than the target, which is fine and worth saying in the
report rather than quietly trimming something useful.

## Report this honestly

If the repo's existing `AGENTS.md` is well past the target, say so with the number and name the sections that
could move. Do not rewrite it unasked — the same Do No Harm rule applies here as everywhere else.

## Generating the two sections

**`## Done means`** — the conditions a change must meet before it is finished.

**There is no template. Derive all three to five lines from this repo**, in this order:

1. **The verify command.** Find the command a maintainer runs before pushing — in this repo's task runner,
   script block, or CI workflow, whichever it uses. Name it exactly as it is written there. If the repo runs
   several, name them in order. If it has none, skip this line rather than inventing one.
2. **The test condition.** *Any behavior change ships with a test that fails without the change.* This is the
   only line that applies to every repo that has tests, so include it wherever tests exist.
3. **The contract line, only if this repo publishes something others depend on.** A schema, an interface
   definition, a public type — whatever this repo's consumers build against. Most repos publish nothing of the
   kind. Omit rather than invent.

Stop at five. A longer list is a checklist nobody finishes.

**`## Never merges without a human`** — the boundary.

**Always write the definition into the generated file**, directly under the heading, exactly as in the template
below. The phrase is ambiguous alone and it *will* be challenged — "I tell agents to merge when they're done,
is that banned?" is the first question anyone asks. It is not banned: the definition draws the line at whether
a person read *this diff*, so standing approval stays fine everywhere off the list. 

Seed the list from the risk paths actually present in this repo (see [detection-tables.md](detection-tables.md) § Risk path detection, generated
from [../data/risk-paths.yml](../data/risk-paths.yml)), then state each as a path or a condition rather than a
category.

**Before you write a line, check it against [`../data/risk-paths.yml`](../data/risk-paths.yml) § `false_positives`.** Those are not
hypothetical — every entry is a line this skill actually got wrong in a real repo. If what you matched appears
there, answer the row's `confirm` question by opening the file, and drop the line unless the answer holds up.
That list is the one part of this step with a regression test behind it
(`tests/fixtures/`), so treat a match as a stop sign rather than a hint:

```markdown
## Never merges without a human

A person has to have **read this diff** before it lands. Telling an agent "merge it when you're done" is
approving a goal, not this change — so it does not count for anything on this list. Everywhere else it counts
fine, which is the point of having a list.

- Anything under `db/migrations/`
- Anything that changes the shape of an existing API response
- Anything that sends messages to customers
- Anything that grants or changes permissions
```

Only list risk paths this repo actually has — a static site has no migrations, and inventing categories to
fill the section is the noise this skill exists to avoid. If the analysis finds none, say so explicitly in one
line rather than omitting the heading.


## Defining `## Never merges without a human`

The heading is ambiguous on its own, and it will be challenged the first time someone who works with agents
reads it. Every generated file must carry the definition directly under the heading:

> A person has to have **read this diff** before it lands. Telling an agent "merge it when you're done" is
> approving a goal, not this change — so it does not count for anything on this list. Everywhere else it counts
> fine, which is the point of having a list.

### What this means for the rest of the file

`## Done means` is the other half and is often mistaken for the same thing. `## Done means` is what a change
must satisfy to be **finished**; `## Never merges without a human` is what it cannot decide **alone**. A change
can be done and still be on the list.

# Detection Tables Reference

Detailed detection heuristics for Step 1 — codebase analysis.

## Manifest detection

| Manifest | Language | What to extract |
|----------|----------|-----------------|
| `package.json` | JavaScript/TypeScript | dependencies, devDependencies, scripts (build, test, lint, typecheck), engines.node |
| `Cargo.toml` | Rust | workspace members, dependencies, build/test profile |
| `go.mod` | Go | module name, Go version |
| `pyproject.toml` or `requirements.txt` | Python | dependencies, build system, scripts, python version |
| `*.csproj` or `*.sln` | C# / .NET | target framework, package references, test SDK |
| `Gemfile` | Ruby | dependencies, ruby version |
| `pom.xml` or `build.gradle` | Java | dependencies, plugins, build tasks |

Also check for:
- **Lockfiles** — `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`, `Cargo.lock`, `go.sum`, `poetry.lock`, `Pipfile.lock`
- **Runtime version files** — `.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `.ruby-version`, `rust-toolchain.toml`
- **Monorepo markers** — `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, Cargo workspace, Go workspace. Also check for **large library monorepos**: Maven aggregator (`pom.xml` with `<modules>`), Python multi-package (`libs/` directory with multiple `pyproject.toml`), or Turborepo + Changesets (`turbo.json` + `.changeset/`).

  *Why?*: Large open-source libraries like LangChain organize code as multi-package monorepos — dozens of independently published packages under one repo. Treating them as a single package misses cross-package dependencies, per-package build commands, and module-specific conventions.
- **Notebooks** — `*.ipynb` files. If found, note the count and locations. Notebooks are common in course repos, data science projects, and tutorials.

## VS Code extension detection

Check for `contributes` in root `package.json` (commands, themes, snippets, views, menus). If present, this is a **VS Code extension**, not a regular app. Also check for `vsce` or `@vscode/vsce` in devDependencies, and `vscode:prepublish` in scripts. Extensions come in three flavors:
- **Functional extensions** — TypeScript code with activation events, commands, webpack/esbuild bundling, tests
- **Theme extensions** — JSON theme files, no runtime code, published via `vsce`
- **Snippet extensions** — JSON snippet definitions, language-scoped, content-driven not logic-driven

*Why?*: VS Code extensions look like npm packages but have completely different conventions. The `package.json` IS the product spec — commands, menus, settings, keybindings. Treating them like a web app misses what matters.

## Multi-app collection detection

Multiple independent apps in subdirectories (e.g., `angular/`, `react/`, `svelte/`), each with its own `package.json`, but **no workspace config** tying them together. This is different from a monorepo — there's no shared build or dependency graph. Each app builds and runs independently.

*Why?*: Not every repo with multiple folders is a monorepo. Some are "collections" — the same concept implemented in different frameworks for comparison or learning. Don't invent workspace tooling where none exists.

## Demo app pattern detection

A frontend app + mock backend (`json-server`, `db.json`) + proxy config (`proxy.conf.json`, `vite.config.ts` proxy). Common in demo/tutorial repos. If detected, document the mock API setup in AGENTS.md so agents know to start both frontend and backend.

## Course/tutorial repo detection

*Why?*: Course repos are fundamentally different from application repos. The "product" is markdown lessons and code samples — not a running application. Generating CI, setup steps, or a build pipeline for a course repo misses the point. Detecting this early shapes every later step.

Check for **multiple signals** — no single check is definitive:

1. **Numbered folders** — glob for top-level directories matching `NN-*` (e.g., `00-intro`, `01-setup`, `05-advanced`), `N-topic` (e.g., `1-Introduction`, `6-Data-Science-In-Wild`), `Chapter N`, `Module N`, or `Unit N`. 3+ matches is a strong signal.
2. **README content** — scan the root README for course/tutorial language: "lesson", "chapter", "module", "unit", "what you'll learn", "prerequisites", "course structure", "hands-on", "assignment", "quiz", "curriculum", "week". Multiple matches strengthen the signal.
3. **Repo description/topics** — check the GitHub description and topics (from Step 0b) for terms like "beginners", "course", "tutorial", "workshop", "learn", "curriculum", "lessons".
4. **Lesson structure** — check if numbered folders each contain a `README.md` (lesson content) and optionally `assignment.md`, `solution/`, `code/`, `quiz/`, or `notebook/` subdirectories.
5. **No primary application** — the repo has no root-level `package.json`, `Cargo.toml`, `go.mod`, or other manifest that would indicate a buildable application (individual lesson folders may have their own manifests for code samples).
6. **Devcontainer** — check for `.devcontainer/` directory. Common in course repos to provide a ready-to-go development environment.

**A repo is a course if 3+ of these signals are present.** Record it in the findings table as `Repo type: course` with evidence.

### Course repo adaptations

When a repo is a course, the following steps adapt:
- **Step 5** (CI workflow) — skip build/test CI. Suggest markdown validation (link checking, spell check) instead if not already present.
- **Step 3** (copilot-instructions.md) — include lesson structure conventions: expected folder contents, naming patterns, how to add a new lesson. If lessons have quizzes or assignments, document the expected structure (e.g., each lesson needs `README.md` + `assignment.md` + `solution/`).
- **Step 2** (AGENTS.md) — "Adding a New Lesson" section instead of "Adding a New Feature". Include the lesson template (what files/folders each lesson should contain).
- **Report** — mark skipped assets as "N/A — course repo" instead of "Missing". Credit `.devcontainer/` in the "Nailed It" section if present.

## Findings table template

Before proceeding from Step 1, produce a structured summary combining GitHub context (Step 0) and codebase analysis (Step 1). Include file-path evidence for each finding:

| Category | Finding | Evidence (source) |
|----------|---------|-------------------|
| Repo | e.g., johnpapa/ai-ready | `git remote -v` |
| Description | e.g., "Copilot CLI skill..." | GitHub API / repo metadata |
| Topics | e.g., copilot, skills, ai-ready | GitHub API |
| Language | e.g., TypeScript (65%), Rust (30%) | GitHub API language breakdown |
| Multi-language | yes/no — if no single language exceeds 50%, flag as multi-language | GitHub API |
| Repo type | app / course / docs-only / VS Code extension / npm package / collection | Step 1a-ii detection |
| VS Code extension type | functional / theme / snippets (if applicable) | `package.json` contributes field |
| Notebooks | e.g., 12 `.ipynb` files in `lessons/` | glob for `*.ipynb` |
| Mock backend | e.g., json-server on port 3000 | `db.json`, proxy config |
| Framework | e.g., React, Phaser | `package.json` dependencies |
| Test runner | e.g., Vitest | `package.json` devDependencies |
| Test command | e.g., `npm test` | `package.json` scripts.test |
| Build command | e.g., `npm run build` | `package.json` scripts.build |
| Runtime version | e.g., Node 22 | `.nvmrc` or `package.json` engines |
| Package manager | e.g., pnpm | `pnpm-lock.yaml` exists |
| Contributors | e.g., 3 contributors | GitHub API |
| Team size | e.g., solo / small / large | Contributor count |
| PR CI exists | yes/no | `.github/workflows/` or GitHub Actions API |
| Community health | e.g., 71% | GitHub API community/profile |
| PR review patterns | e.g., "maintainer often asks for tests" | Mined from recent PR review comments |
| Release cadence | e.g., monthly, tagged releases | GitHub Releases API |
| AGENTS.md | exists / missing | repo root |
| copilot-instructions.md | exists / missing | `.github/` |
| Changelog | exists / pointer / missing | `CHANGELOG.md`, Releases |
| Changelog freshness | current / stale | latest entry vs latest git tag |
| Docs exist | yes / no | `docs/`, config file |
| Docs framework | Docsify / Docusaurus / etc. | config file path |
| Docs deploy pipeline | yes / no | workflow file path |
| README links to docs | yes / no | README.md link |
| Default branch | e.g., `main`, `dev`, `master` | `gh repo view --json defaultBranchRef` |
| Push access | yes / no | `gh api repos/{owner}/{repo} --jq '.permissions.push'` |
| Custom agents | e.g., 2 agents: migration guide, orchestrator | `.github/agents/` |
| Custom skills | e.g., 6 skills: bunit-test, component-dev, ... | `.github/skills/` |
| Devcontainer | yes/no | `.devcontainer/` |
| Monorepo | yes/no | workspace config file |
| Areas | e.g., frontend (React), backend (Express), shared (TypeScript) | workspace config paths |

## Drift detection for existing assets

For existing AI-ready assets, read their current contents and compare against your analysis. Flag drift in any of these dimensions:

| Asset | What to compare |
|-------|----------------|
| `AGENTS.md` | Repo structure still accurate? Build/test commands still correct? Tech stack changed? |
| `copilot-instructions.md` | New conventions from recent PR reviews? Maintenance matrix still covers current file relationships? |
| CI workflow | Build/test/lint commands still match the project? New tools added? |
| Issue templates | Still relevant to the project type? |
| README Contributing | Links still valid? Commands still correct? |

For each existing asset where you find drift, classify it as **"Could Be Better"** in the report with a specific suggestion (e.g., "AGENTS.md lists Node 18 but `.nvmrc` now says Node 22"). Do not silently skip existing files — always evaluate them.

## Monorepo area detection

If a workspace config was found in Step 1a, read it to find package/project paths (e.g., `packages/*`, `apps/*`, `libs/*`). List each area — name, path glob, and primary stack — and note which areas have conventions that differ from root.

**For large library monorepos** (Maven aggregator, Python `libs/`, pnpm workspace with many packages):
- List each published package/module separately with its purpose (e.g., `langchain4j-core`, `langchain4j-open-ai`, `langchain4j-ollama`)
- Note the module taxonomy if one exists (core vs providers vs integrations vs experimental)
- Identify **cross-package dependencies** — which packages depend on which. Changes to core packages ripple to all dependents.
- Detect **release tooling** — Changesets (`.changeset/`), semantic-release, Maven release plugin, or manual versioning. Document in the maintenance matrix.
- Detect **conditional modules** — JDK-specific modules (`jdk21`), platform-specific builds, or optional integrations that only build under certain conditions.

*Why?*: A fix in `langchain4j-core` affects 30+ downstream modules. Without mapping cross-package dependencies, agents make changes to one package and miss the ripple effects.

## Risk path detection

Used by Step 2 to seed the `## Never merges without a human` section of `AGENTS.md`.

**A glob match is a candidate, not a conclusion.** Open what matched and confirm it does what the row claims
before writing it into the boundary. A wrong entry is worse than a missing one: it puts a human back into
merges that never needed one, and it teaches the reader the section can't be trusted.

<!-- BEGIN GENERATED: risk-paths -->
<!-- Generated from skills/ai-ready/data/risk-paths.yml — edit that file, then run
     python3 tools/gen_detection_tables.py -->

Known false positives, every one of them seen in a real repo. When one of these matches, the
confirm question is not optional:

| Match | Looks like | Usually is | Seen in |
|---|---|---|---|
| `**/notification*.*` | Customer contact | An in-app or editor toast, not a message to a customer | johnpapa/vscode-peacock — src/notification.ts is window.showInformationMessage |
| `**/auth/token*.*` | Auth / permissions | Reading or refreshing a token somebody else issued, not a permission decision | Client libraries and SDK wrappers |
| `**/seeds/**/*.sql` | Schema / data loss | Seed data that is recreated, not migrated | Most application repos with a local dev database |
| `**/fixtures/**` | Money | Test fixtures that never touch a payment provider | Any repo with payment tests |
| `**/*.env.example` | Secrets & config | A placeholder template, committed on purpose | Nearly every repo that has a .env at all |

Order matters less than honesty — a section listing risks the repo does not have is worse than a
short one.

| Risk | Look for | Why a human | Confirm by opening it |
|---|---|---|---|
| Schema / data loss | `**/migrations/**`, `**/*.sql`, `prisma/schema.prisma`, `alembic/**` | Dropped columns and destructive migrations cannot be reverted by reverting the commit | Does this run against a real database, or is it a seed or fixture that gets recreated? |
| API contract | `**/openapi.*`, `**/swagger.*`, `**/*.proto`, `**/schema.graphql` | Other teams and released clients already depend on the current shape | Is this contract published to anyone outside this repo, or internal-only and versioned together? |
| Auth / permissions | `**/auth/**`, `**/authz/**`, `**/*permission*`, `**/*role*`, `**/iam/**`, `**/*policy*.json` | Widening access is silent and rarely caught by tests | Does this code DECIDE what someone may do, or only carry a token somebody else issued? |
| Money | `**/billing/**`, `**/payment*/**`, `**/checkout/**`, `**/invoice*/**` | Mistakes move real money and are visible to customers | Does this path run in production against a real payment provider? |
| Customer contact | `**/email*/**`, `**/notification*/**`, `**/sms/**`, `**/templates/email/**` | Messages cannot be unsent | Does this send something to a person outside the team, or is it an in-app toast or log line? |
| Infrastructure | `infra/**`, `**/*.tf`, `**/*.bicep`, `k8s/**`, `helm/**` | Blast radius is the whole environment, not one service | Is this applied to a shared or production environment, or only to a local or ephemeral one? |
| Secrets & config | `**/*.env`, `**/*.env.*`, `**/secrets/**` | A leaked credential is not revertible in any useful sense | Is this file tracked in git, and does it hold a real value rather than a placeholder? |
| Release plumbing | `.github/workflows/**`, `**/release*.sh`, `**/publish*.sh` | A change here changes how every other change ships | Does anything actually ship from this repo, or does the workflow only run checks? |

<!-- END GENERATED: risk-paths -->

## Security surface detection

Used by Step 4e. **Generate a security skill only if at least one row matches.** As with risk paths, a glob
match is a candidate — open it and confirm before writing a rule about it.

| Surface | Look for | The rule worth capturing |
|---|---|---|
| Web views / embedded content | `webview`, `iframe`, `Content-Security-Policy`, `dangerouslySetInnerHTML`, `innerHTML` | What may be rendered, and what must be escaped or sandboxed |
| Trust boundary input | HTTP handlers, message listeners, deserialization, file upload, CLI arg parsing | What is validated where, and what is never trusted |
| Secrets | `.env` handling, key vaults, credential files, `process.env` reads near network calls | Where secrets come from and where they must never go |
| Auth / permissions | auth middleware, scope and role checks, extension or OAuth permission manifests | Which paths require which check, and who may widen a scope |
| Crypto | hashing, signing, token generation, random number use | Which primitives are approved here and which are banned |
| Query construction | string-built SQL, raw query calls, ORM escape hatches | What must be parameterised |

### The skeleton Step 4e fills

```markdown
---
name: security-review
description: The security rules specific to this repo — trust boundaries, what must never be trusted, and what to check before merging. Use when touching <the real surfaces found>.
---

# Security review

## Trust boundaries in this repo
<real paths, and what crosses them>

## Never
<the repo's real invariants — from SECURITY.md, AGENTS.md, or reviewer comments>

## Before merging a change to <real path>
<the actual checklist>
```

Every line must name something real in this repo. If a section would only restate general good practice, drop
the section — a security skill that reads like a blog post dilutes the rules that actually matter here.

**When nothing matches**, say so explicitly rather than generating a placeholder:
_"No repo-specific security surface detected — skipping the security skill. Generic security advice would add
noise without adding knowledge."_

# GitHub Discovery Reference

Detailed API calls and techniques for Step 0 — GitHub-native context discovery.

## 0b. Fetch repo metadata from GitHub

Use the GitHub MCP tools (if available) or `gh` CLI to pull rich context the user should never have to explain:

| What to fetch | Tool / Command | What you learn |
|---------------|---------------|----------------|
| Repo description, topics, visibility, default branch | `github-mcp-server-get_file_contents` on `/` or `gh repo view --json description,topics,isPrivate,primaryLanguage,defaultBranchRef --jq '.' | cat` | What this project is about, how it's categorized, default branch name |
| Language breakdown | `gh api repos/{owner}/{repo}/languages | cat` (bash) | Accurate language percentages (better than guessing from files) |
| Community health | `gh api repos/{owner}/{repo}/community/profile | cat` (bash) | Which community files exist (CONTRIBUTING, CODE_OF_CONDUCT, license, issue templates) — GitHub already knows this |
| Contributors | `gh api repos/{owner}/{repo}/contributors --jq '.[].login' | cat` (bash) | Team size, contribution patterns |
| Open issues | `github-mcp-server-list_issues` or `gh issue list | cat` | Active problems, what the project cares about |
| Recent merged PRs | `gh pr list --state merged --limit 10 --json title,body,files | cat` (bash) | Contribution patterns — what files get touched together, what a typical PR looks like |
| PR review comments | `github-mcp-server-pull_request_read` on recent PRs | **Repeated review feedback = conventions that should be in copilot-instructions.md** |
| Releases | `gh release list --limit 5 | cat` (bash) | Release cadence, versioning scheme |
| GitHub Actions workflows | `github-mcp-server-actions_list` or read `.github/workflows/` | CI/CD setup, what runs on PRs |
| Branch protection | `github-mcp-server-list_branches` | Default branch, protection rules |
| Push permissions | `gh api repos/{owner}/{repo} --jq '.permissions.push' | cat` (bash) | Whether the user can push directly or needs to fork |

## 0c. PR review mining details

This is the **highest-value** GitHub-native insight. Look at the 5-10 most recent merged PRs.

*Why?*: If a maintainer leaves the same review comment on 5 different PRs, that's a convention waiting to be documented. Mining PR reviews turns reviewer fatigue into automated guidance.

**Mine agent review comments too, not just human ones.** Review threads are no longer only humans correcting
humans. Coding agents open pull requests and review agents comment on them, and both are part of how this
repo's standards actually get applied now. Treat every reviewer as a source, and record which kind each rule
came from — an agent repeating itself means a rule is missing from `AGENTS.md`, which is a slightly different
signal than a human repeating themselves.

1. Use `github-mcp-server-list_pull_requests` (state: closed, sort: updated) to find recent merged PRs
2. For each, use `github-mcp-server-pull_request_read` (method: get_review_comments) to read review threads
3. Look for **repeated patterns** — the same feedback given across multiple PRs becomes a convention:
   - "Please add tests for this" → add to test conventions
   - "Use X pattern instead of Y" → add to coding conventions
   - "Update the docs when you change this" → add to maintenance matrix
   - "Don't forget to update the changelog" → add to maintenance matrix

4. **Read the history as an evolution, not a flat list.** Conventions change, and a rule mined from two years
   ago may have been deliberately abandoned. Weight what you find:
   - Comments from the **most recent third** of the PRs you read count double.
   - A pattern that appears **early and then stops** is a candidate for *superseded* — do not write it as a
     current rule. Note it in the findings so the user can confirm, e.g. _"Reviewers asked for X until
     March and stopped — dropped, confirm if still wanted."_
   - A pattern that appears **only recently** is worth capturing even with fewer occurrences. New conventions
     are exactly the ones nobody has written down yet.
   - If human and agent reviewers **disagree** on the same point, surface it rather than picking a side — an
     unresolved disagreement is a convention that was never actually settled.

**If few or no review comments are found** (e.g., PRs are self-merged or auto-merged), expand the search to up to 20 merged PRs. If there are still no review patterns, note this in the findings: _"No PR review patterns found — consider adding conventions as the team grows."_ Never silently skip this section.

These mined conventions go into `AGENTS.md`, where every tool reads them — turning repeated review feedback, from humans and agents alike, into guidance that applies before the next pull request is written instead of after.

## 0d. Community health gap mapping

GitHub's community health API tells you exactly what's missing. Map it to the assets this skill generates:

| GitHub says missing | Skill generates |
|-------------------|-----------------|
| No issue templates | `.github/ISSUE_TEMPLATE/` (Step 6) |
| No pull request template | `.github/PULL_REQUEST_TEMPLATE.md` (Step 6) |
| No CONTRIBUTING guide | README Contributing section (Step 7) |
| No CODE_OF_CONDUCT | Can suggest adding one |
| No license | Flag in the report |
| No README | Flag in the report |

# Report Template Reference

Display format for the AI-Readiness Report (Step 11), HTML report, badge, and PR creation.

## Scoring

Count how many of the 11 assets (SKILL.md § The 11 tracked assets) have **Nailed It** status. That count sets
the medal — then **apply the prerequisites**, which can only lower it.

| Medal | Name | Count | Also required | What it means |
|-------|------|-------|---------------|---------------|
| 🥉 | **Getting Started** | 1–3 | — | A few of the files exist. Nothing in the repo tells an agent how it works |
| 🥈 | **On Track** | 4–6 | — | Real scaffolding is in place, but the conventions are still in people's heads |
| 🥇 | **Solid** | 7–9 | `AGENTS.md` nailed | The conventions are written down, in the one file every tool reads |
| 🏆 | **AI-Ready** | 10–11 | every 🤖 AI Context asset nailed | Conventions, boundaries, reviewers and procedures all live in the repo |

**The prerequisites are not decoration.** A repo can reach seven nailed assets on a changelog, docs, issue
templates, a PR template, CI, and two reviewer agents — with no `AGENTS.md` at all. That repo is well maintained. It is not AI-ready, and a plain count would hand it 🥇. So the count is a
ceiling, not a score: without `AGENTS.md` nailed the repo stops at 🥈 however high the count goes, and if any
🤖 AI Context asset is short it stops at 🥇.

**What the score does not measure.** It measures what is *in place*. It does not measure whether agents write
better pull requests in this repo, because nothing here has measured that.

Build the progress bar using 🟩 for nailed, 🟨 for could-be-better, and ⬜ for missing — always 11 squares.

**When a prerequisite caps the medal, say so on the score line** and name what would lift it — a capped medal
with no explanation reads like a bug. For example:

```
📊 **Your Repo Today** · 🥈 **On Track** · 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟨 · 9 of 11 nailed
↳ held below 🥇 — `AGENTS.md` has no `## Never merges without a human` section
```

**Never quote a time saving.** No "45-minute review becomes 5 minutes", no percentage, no multiplier. Nothing
in this skill measures review time, and a maintainer who does track it will spot the invented number and stop
trusting the rest of the report.

## AI-Readiness Report format

Display this report:

```
🎯 **AI-Readiness Report**

Here's what an AI agent can learn about this repo from the repo
itself today — and what it still has to guess.

**{repo-name}**

---

📊 **Your Repo Today** · {medal} **{level-name}** · {progress-bar} · {nailed} of 11 nailed
{languages} · {frameworks} · {test-runner} ({test-count}) · `{build-command}`

🤖 **Existing AI Config (detected)**

_Include this section only if the repo already has AI configuration (copilot-instructions.md, custom agents, custom skills). Omit it entirely if there is no pre-existing AI config._

| Asset | Detail |
|-------|--------|
| {asset-name} | {detail — e.g., "542 lines — components, testing, shims, docs"} |
| {.github/agents/} | {count} agents: {names} |
| {.github/skills/} | {count} skills: {names} |

⚠️ **Instruction Consistency**

_Show this section when consistency issues are found — skip it when everything lines up._

| Issue | Files | Detail |
|-------|-------|--------|
| {issue-type} | {file1} ↔ {file2} | {specific contradiction or duplication} |

✅ **Nailed It ({count})**

| Asset | Detail |
|-------|--------|
| {asset-name} | {one-line detail} |
| ... | ... |

💡 **Could Be Better ({count})**

| Asset | Suggestion |
|-------|-----------|
| {asset-name} | {suggestion} |
| ... | ... |

_Why these matter:_ {brief explanation of why the could-be-better items are worth improving}

⭕ **Missing ({count})**

| Asset | Why it matters |
|-------|---------------|
| {asset-name} | {why it matters} |
| ... | ... |

_Why these matter:_ {brief explanation of what the missing items cost the repo}

---

🛠️ **What I'd Like To Do** — proposed changes to close the gaps:

| Action | Detail |
|--------|--------|
| ➕ Create | `{filename}` — {what it will contain} |
| 🔍 Audit | `{filename}` — {what drifted and suggested fix} |
| ⏭️ Skip | `{filename}` — skipped (user requested) |
| 💬 Suggest | {suggestion} |
| ✅ Skip | {count} files already in great shape |

_For monorepos: list each `.github/instructions/{area}.instructions.md` file created as a separate ➕ Create row._

---

🏆 **If You Accept** · {after-progress-bar} · {after-nailed} of 11 nailed → {after-medal} **{after-level}**

🤖 AI Context        {6 status indicators}
🔧 Dev Workflow      {3 status indicators}
📖 Onboarding        {2 status indicators}

---

🚀 **What's Next?**

👉 **Create the PR now** — just say:
\```
create a branch and open a PR with these changes
\```

👉 **Tweak first** — tell me what to change:
\```
update the AGENTS.md to include more detail about the command registration pattern
\```

👉 **Share the report** — want a visual version for your team?
\```
generate an HTML report I can share
\```

👉 **Skip for now** — no worries, the analysis is done. Come back anytime and say `make this repo ai-ready` to pick up where you left off.
```

## Report template rules

- **Nailed It** = asset exists and is well-customized to the repo
- **Could Be Better** = asset exists but has gaps or could be enhanced
- **Missing** = asset does not exist and should be created
- If a section has 0 items (e.g., nothing missing), omit that section entirely
- The tech profile table should only include rows that apply (e.g., skip "Frameworks" if none detected)
- Keep each detail to one short line — no multi-line descriptions
- The "What I Did" section should list every file that was created, suggested, or skipped
- **Show an updated progress bar** after the "What I Did" section — recount nailed assets (counting all created files as now "Nailed It"), determine the new medal, and show the category breakdown. This shows the user the improvement visually (e.g., going from 🥈 On Track · 🟩🟩🟩🟩🟩🟨⬜⬜⬜⬜⬜ · 5 of 11 → 🏆 AI-Ready · 🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩 · 11 of 11)
- The "What To Do Next" section should include only the bullet points that are relevant — e.g., if no files were created, skip "review generated files" and instead say something like "Your repo is already AI-ready — nice work!"
- **Issue/PR provenance is mandatory** — every issue comment, PR comment, or PR body update generated by this skill must include `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)`.
- **Documentation sync is mandatory** — when changing generated guidance, templates, or PR behavior, update related documentation to match the repository's documented standards and maintenance matrix.

## HTML report (optional)

*Why?*: Terminal reports are great for the developer running the skill. But when you need to share results with a manager, post to a wiki, or attach to an email — you need something visual.

If the user asks for an HTML report (e.g., "generate a report I can share", "make an HTML report"), generate a self-contained `ai-ready-report.html` in the repo root.

The HTML report mirrors the terminal summary — same sections, same data, same structure:

1. **Header** — repo name, maturity level with emoji medal (🥉🥈🥇🏆), weighted score percentage, progress bar, generation date
2. **Tech profile** — languages, frameworks, test runner, build command
3. **Existing AI config** — if detected (copilot-instructions.md, custom agents/skills)
4. **Instruction consistency** — if issues found
5. **Asset status** — three groups: ✅ Nailed It, 💡 Could Be Better, ⭕ Missing — with one-line details per asset
6. **What was generated** — action table (➕ Create, 🔍 Audit, ⏭️ Skip, 💬 Suggest)
7. **Updated score** — before/after with maturity level change
8. **What to do next** — remaining recommendations

The file must be self-contained (inline CSS, no external dependencies) and shareable — one file you can open in any browser or drop into an email. Use green/amber/gray status colors, system fonts, and a responsive layout. Keep it simple — this is a summary, not a dashboard.

Generate the HTML report only when the user asks for it. The terminal output is always the default.

## 11a. AI-Ready badge

Check if the README already contains an `AI--Ready` badge. If it does not, **automatically** insert this badge at the top of the README, after any existing title or badge row — do not ask, just add it:

```markdown
[![AI Ready](https://img.shields.io/badge/AI--Ready-yes-brightgreen?style=flat)](https://github.com/johnpapa/ai-ready)
```

The badge is a static Shields.io image with zero dependencies. It links back to the ai-ready repo so others can discover it. Include this in the "What I Did" section of the report as a `➕ Create` action.

## 11b. PR creation flow

After displaying the report and handling the badge, **ask the user** if they want to create a branch and open a PR. Do not tell them to type a command — ask them directly:

_"Would you like me to create a branch and open a PR with these changes?"_

If the user agrees:

1. **Check push permissions** from Step 0b.
2. **If the user has push access**: create a feature branch (e.g., `feat/ai-ready-config`), commit all new/modified files (including the badge), push, and open a PR targeting the **default branch** (detected in Step 0b — never assume `main`).
3. **If the user does NOT have push access**: use a fork-based flow automatically — fork the repo (`gh repo fork --clone=false`), add the fork as a remote, push the branch to the fork, then open a cross-fork PR (`gh pr create --head {user}:feat/ai-ready-config`). Handle it end-to-end — never ask the user to figure out the fork workflow.
4. **Before opening the PR**: sync with the target branch and attempt to resolve merge conflicts. If conflicts cannot be resolved confidently, ask the user whether to proceed with help resolving conflicts or pause for manual intervention.

Include a summary of what was added and the before/after score in the PR body, and include `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)` in that PR body summary. If the user declines, end the session gracefully.

**Always add exactly one consolidated report comment to the PR.** After creating the PR, post a single comment with a condensed version of the AI-Readiness Report and include all immediate asks/clarifications in that same comment:

```
## 🎯 AI-Readiness Report

**{repo-name}**

**Before:** {before-medal} **{before-level}** · {before-nailed} of 11 nailed
**After this PR:** {after-medal} **{after-level}** · {after-nailed} of 11 nailed

🤖 AI Context        {status indicators}
🔧 Dev Workflow      {status indicators}
📖 Onboarding        {status indicators}

| Action | File |
|--------|------|
| ➕ Create | `{filename}` |
| ... | ... |

Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)
```

If additional clarification is needed right away, **update the same comment** (or include it in the PR body update) instead of posting serial "quick/final clarification" follow-up comments. Only add a new comment later when there is truly new information (e.g., user asked a new question, CI status changed, or scope changed).

*Why?*: The PR body is written once, but the report comment is what reviewers see first. A single, scannable summary avoids notification spam and makes it easy to understand impact at a glance.

# Reviewer Agents Reference

Generated by Step 4c into `.github/agents/`. **Reviewer agents** — narrow, single-question reviewers that apply
to **any** repository, regardless of language or stack.

**Not the same thing as adversarial agents.** A reviewer agent is a file this skill generates into the repo,
assigned to a pull request, that answers one fixed question. Adversarial agents are a separate practice: a
human, on their own, checking one AI tool's output with a genuinely different AI tool. See
[README.md](../../../README.md) § Adversarial agents. A reviewer agent can be *part of* an adversarial-agents
workflow — assigning it on a different model than the one that wrote the code — but the two ideas are not
interchangeable, and this file is only about the first one.

## What makes these reviewers work

Four mechanics, and all four are design decisions in the agents below.

**1. A question with a wrong answer.** Ask an agent to "review this pull request" and it will find it good —
you have handed it the author's goal, so it completes the author's work. Every agent here instead asks
something that can come back *no*: would this test have failed against the old code? What did the issue ask for
that this does not do?

**2. Fresh context.** An agent that wrote the code and then reviews it is marking its own homework. It still
holds the reasoning that produced the change, so it defends the change. A reviewer agent starts from the
diff and nothing else — which is also why these are separate agents and not a second pass by the author.

**3. No authority to approve.** These agents find things. None of them can say the change is fine, and none of
them emits a verdict a merge can be gated on by itself. A reviewer that can approve will eventually approve to
be agreeable.

**4. A narrow remit.** A reviewer with a broad remit gets muted, the same way a human who comments on
everything gets muted. Each answers one question and is explicitly told to ignore everything else, so it cannot
trade one concern off against another to reach a comfortable overall opinion.

## Why three, and when it should not be three

**Three is a starting set, not a principle.** The principle is that each reviewer answers **one** question — a
reviewer with a broad remit gets muted, the same way a human who comments on everything gets muted. The count
follows from how many questions this repo actually needs answered.

Three is the default because these three questions apply to any repo regardless of language or stack. A repo
with no tests does not need `test-integrity`. A repo where nothing is hard to undo does not need
`blast-radius`. **Generate only the ones that can come back *no* in this repo, and say which you skipped and
why.**

Each maps to a question a repo has to answer before a change merges without a person:

| Agent | The question it answers |
|-------|------------------------|
| `spec-conformance` | Did we build the thing that was asked for? |
| `test-integrity` | Do the tests actually prove this change works? |
| `blast-radius` | How hard is this to undo if it's wrong? |

## Frontmatter

Generate `name` and `description` only. `tools`, `model`, and `mcp-servers` are supported but their accepted
values move between tool versions — leave them out rather than generating something that may not validate. Note
in the report that the user can pin a model or restrict tools per agent.

## The three agents

### `.github/agents/spec-conformance.agent.md`

```markdown
---
name: spec-conformance
description: Checks a pull request against what was actually asked for, not how it was written.
---

You are given the linked issue (or the pull request description, if there is no issue) and the diff.

Answer exactly two questions:

1. What did the issue ask for that this diff does not do?
2. What does this diff do that nobody asked for?

If the issue is too vague to answer either question, say that instead of guessing — an unclear request is
itself a finding.

Do not comment on style, naming, structure, performance, or test quality. Other reviewers own those.
```

### `.github/agents/test-integrity.agent.md`

```markdown
---
name: test-integrity
description: Checks whether the tests in a pull request actually prove the change works.
---

You are given the diff, including test files.

Answer these, and nothing else:

1. Does this change alter behavior? If yes, is there a new or modified test that covers the new behavior?
2. Would each new test have FAILED against the old code? If a test would pass either way, it does not test
   this change — say so and name it.
3. Do the tests assert on outcomes, or do they only execute code without checking anything?
4. Were any existing tests deleted, skipped, or weakened in this diff? List every one, with the reason given
   in the diff if there is one.

Point 4 matters most. A change that makes a test less strict deserves more attention than the code change
itself.

Do not comment on style, naming, or structure.
```

### `.github/agents/blast-radius.agent.md`

```markdown
---
name: blast-radius
description: Flags changes that are hard or impossible to undo after they ship.
---

You are given the diff and the repository's `AGENTS.md`.

Answer one question: **if this turns out to be wrong after it ships, how hard is it to take back?**

Flag anything in this diff that a revert would not undo:

- Schema changes that drop or rewrite data
- Changes to the shape of an existing API response, or to a published contract
- Anything that sends messages, charges money, or provisions resources
- Anything that grants or widens permissions
- Deletions of data, files, or infrastructure

For each, state what specifically cannot be undone. If nothing in the diff is irreversible, say so in one line.

Then check the diff against the `## Never merges without a human` section of `AGENTS.md` and report any match.

Do not comment on correctness, style, or test coverage.
```

## Generation rules

- **Never overwrite.** If `.github/agents/` already contains an agent with the same purpose, leave it and flag
  drift in the report.
- **Keep them narrow.** Do not merge these into one reviewer, and do not add repo-specific concerns to them —
  a repo-specific reviewer is a fourth, separate file.
- **Tailor the examples, not the remit.** `blast-radius` may name this repo's real risk paths; its question
  stays the same.

## Writing a fourth one

A repo-specific reviewer is a separate file, and it has to pass the same four tests as the three above:

1. **Can its question come back *no*?** If the honest answer is always "looks fine", it is not a reviewer, it
   is a formality. "Does this follow our conventions?" fails this. "Which convention in `AGENTS.md` does this
   diff violate?" passes.
2. **Does it work from the diff alone?** If it needs the author's intent explained to it, it is not a
   reviewer — it is a collaborator.
3. **Is it unable to approve?** It should have no way to say *ship it*. Finding nothing is a silent pass, not a
   blessing.
4. **Does it own exactly one concern?** If it overlaps the three above, it will duplicate their findings and
   get muted with them.

Good candidates come from the repo's own history: the question a maintainer keeps asking in review threads, the
category of bug that keeps shipping, the invariant nobody has written down. Step 0c already mined those.