---
name: ad-bootstrap
description: Generate AGENTS.md at the repo root by scanning the codebase first, pre-filling placeholders from observed signals, and asking only the genuine gaps. Use whenever the user wants to bootstrap, scaffold, generate, create, set up, or audit AGENTS.md / agents.md / CLAUDE.md (the operational guide for agents working on this project). Covers greenfield (empty repo), brownfield (code exists, no AGENTS.md), and audit (drift report against existing AGENTS.md).
summary: Generate or audit `AGENTS.md` at the repo root.
allowed-tools: Read, Write, Glob, Grep, Bash
---

# /ad-bootstrap

Produces `AGENTS.md` at the repo root, ≤150 lines, every line operational. Generic agent behavior (think-before-coding, verify-before-claiming-done, etc.) does **not** belong here — that lives in the `ad-philosophy` skill.

## Step 0 — Detect mode

Inspect the repo:

* `AGENTS.md` exists at the repo root → **audit** mode. **Do not rewrite it.** Stop after producing a drift list (see Step 4).
* `AGENTS.md` absent and the directory only holds trivial entries (`.git`, `node_modules`, `.gitignore`, `.gitattributes`, `.DS_Store`, `.env*`, `.idea`, `.vscode`, `LICENSE*`, `README.md`) → **greenfield** mode. There is nothing to scan; walk the template's `<placeholders>` with the user one at a time and skip Step 1.
* `AGENTS.md` absent and meaningful code is present → **brownfield** mode. Scan first, pre-fill, ask only the gaps.

## Step 1 — Scan (brownfield only)

Read in this order, taking the first that exists for each category:

* Manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, `pubspec.yaml`.
* `README.md`, plus any `doc/` or `docs/` directory.
* Top-level directory listing.
* `doc/adr/` — binding decisions; read every ADR.
* `GUIDELINES.md` at repo root — if present, the AGENTS.md sections that have a corresponding GUIDELINES.md section (Code Style → §2; Quality Gates → §8; Commit & PR → §10; Security & Privacy → §12) emit as pointer stubs instead of inline rules' ' reciprocity and ADR-0030 §1.
* `.claude/`, `.cursor/`, `.openai/`, `.agents/` — existing agent config.
* Hook configs: `.husky/`, `.pre-commit-config.yaml`, `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`.
* Lockfiles: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `poetry.lock`, `Cargo.lock`.
* `git remote -v` for the repo URL.

Build a model of: stack (languages and versions), entry points, build / test / lint commands, conventions, quality gates, security boundaries, gotchas confirmed by code.

## Step 2 — Pre-fill

For every `<placeholder>` in the template below, fill from observed signals. **No fabrication.** If a section has no signal, write `<TODO: not yet wired>` in one line and move on. Do not write meta-prose explaining the gap.

## Step 3 — Show only the gaps

Print to the user:

* (a) placeholders that could not be filled from repo signals;
* (b) signals that conflict (two test commands, two style configs, README contradicts code, etc.).

One question per gap. Skip everything filled confidently. Do **not** ask philosophical questions ("is this doc for agents or humans?", "what is the most important quality bar?") — those are decisions, not interview material.

When the host exposes Plan Mode, the agent may render the proposed `AGENTS.md` body inside the plan (the user reviews and approves before write) instead of writing-then-presenting. Plan Mode is opt-in — skip for incremental edits where the user already saw the prior content.

## Step 4 — Write the file

On user confirmation, write `AGENTS.md` at the repo root. Cut every line that does not change agent behavior. No "External Resources" section (URLs are derivable from `git remote` and the manifest). No appended Universal Agent Behavior block. No marketing prose.

**Audit mode override:** do **not** write the file. Produce a drift list. Format each line as:

```
[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.
```

If something the user says contradicts what the code shows, surface the conflict. Don't silently trust the user; don't silently trust the code.

## Template — `AGENTS.md`

````markdown
# AGENTS.md

## Project Overview

`<one sentence: what it does, who runs it, the constraint a wrong change would violate>`

**Stack:** `<languages + versions, runtimes, frameworks, database>`
**Entry points:** `<main services and where to find them>`

## Setup, Build, Test

```bash
# Install
<command>

# Build
<command>

# Test (single file preferred over full suite)
<single test command>
<full suite command>

# Run before any commit
<lint>
<format>
<typecheck>
```

Document non-obvious flags or env vars inline.

## Quality Gates

<when-no-guidelines>
Deterministic enforcement — agent cannot skip.

* Pre-commit hook (fast): `<lint, format, secret-scan>`
* Pre-push hook (thorough): `<build + unit + integration>`
* Visual/E2E for UI (if applicable): `<e.g., Cypress, Playwright, Claude in Chrome — leave blank for non-UI projects>`
* Hook config lives in: `<.husky/, .pre-commit-config.yaml, .claude/settings.json — see code.claude.com/docs/en/hooks>`
* CI blocks on: `<list>`
</when-no-guidelines>

<when-guidelines-md-exists>
See [`GUIDELINES.md`](GUIDELINES.md) §8 for the full reference. Non-negotiable subset:

* `<distilled pre-push hook line>`
* `<distilled pre-commit hook line — or "intentionally absent" if not wired>`
* Never bypass: no `--no-verify`, no skipped hooks, no deleted failing tests.
</when-guidelines-md-exists>

## Code Style

<when-no-guidelines>
Only what differs from language defaults.

* `<e.g., ES modules, not CommonJS>`
* `<e.g., destructure imports>`
* `<e.g., no `any` outside `internal/types/`>`
* `<e.g., Pydantic for all request/response shapes>`
</when-no-guidelines>

<when-guidelines-md-exists>
See [`GUIDELINES.md`](GUIDELINES.md) §2 for the full reference. Non-negotiable subset:

* `<language-specific naming convention line>`
* `<error-handling pattern line>`
* `<module-surface line — ESM vs CommonJS, named-vs-default exports, etc.>`
</when-guidelines-md-exists>

## Architectural Principles

Binding decisions live in [`doc/adr/`](doc/adr/). Do not reinvent.

## Repository Layout

`<where logic, tests, docs, infra live — only if not obvious from the tree>`
`<.claude/skills/ — list of available skills, if any>`
`<.claude/agents/ — list of custom subagents, if any>`
`<doc/adr/ — list of binding ADRs, if any>`
`<doc/tasks/ — task tracking convention, if used>`

## Commit & PR Conventions

<when-no-guidelines>
* Commits: `<conventional / project-specific>`
* Branches: `<feat/, fix/, chore/>`
* PRs require: `<green CI, one review, linked issue>`
* Never push to `<main>` directly.
</when-no-guidelines>

<when-guidelines-md-exists>
See [`GUIDELINES.md`](GUIDELINES.md) §10 for the full reference. Non-negotiable subset:

* `<commit-format line — Conventional Commits + DCO sign-off>`
* `<branch-strategy line — main / feature-branch policy>`
* Never push to `<main>` directly.
</when-guidelines-md-exists>

## Security & Privacy

<when-no-guidelines>
* Secrets: `<location — never committed>`
* Files the agent must not read or modify: `<list>`
* Data classification: `<e.g., no PII in logs>`
* Pre-approved commands (no prompt): `<e.g., gh, npm test, npm run lint>`
* MCP servers approved: `<list>`
</when-no-guidelines>

<when-guidelines-md-exists>
See [`GUIDELINES.md`](GUIDELINES.md) §12 for the full reference. Non-negotiable subset:

* `<secret-handling line — env files gitignored>`
* `<files-not-to-read line — .env, .npmrc, etc>`
* `<pre-approved commands line — agent-allowed no-prompt list>`
</when-guidelines-md-exists>

## Gotchas

Real traps. Each one should map to an incident or to specific code.

* `<e.g., migrations not idempotent — never edit, always create new>`
* `<e.g., DB is UTC, app displays America/Sao_Paulo>`
````

## Output contract

A single `AGENTS.md` at the repo root, ≤150 lines, every line operational. No "External Resources" section. No appended Universal Agent Behavior block — that lives in the `ad-philosophy` skill. No meta-prose explaining gaps. In audit mode: a drift list, no file written.

`AGENTS.md` is a narrative document, so the Documentation Discipline rules in `WORKFLOW.md` §2 apply at write time:

- No emoji anywhere in the file.
- No dates, version stamps, `DRAFT` markers, or changelog blocks. Stack versions are facts (`Node ≥18`); release timelines are not.
- `Project Overview` is the business-context-first paragraph — *why* the project exists before *what* it does.
- One scope: this file is the operational guide for agents. Do not duplicate `ARCHITECTURE.md` patterns or ADR rationale here; link instead.
- No speculation. If a section has no signal, write `<TODO: not yet wired>` once; do not narrate "this could be added later".

## Next

- In `team` / `mature`: run `/ad-architecture` once load-bearing patterns emerge in the code.
- When you scope a product (multi-feature, target user, success metrics): `/ad-prd` (Layer 3 of the six-layer artifact stack; excluded from `poc`).
- When you start your first feature: `/ad-spec` (Layer 4 of the six-layer artifact stack; references parent PRD for product-scope inheritance).
- Skip both above in `poc` / `solo` until the project genuinely needs them — the WORKFLOW §1 prune principle applies.
- `ad-philosophy` auto-loads on non-trivial work; no explicit invocation needed.