Init ai

init-ai

/init-ai audits an existing repository and fills only the gaps that AI coding agents need to work well — with the smallest possible diff. It is the opposite of a template generator.

Why this exists (the one idea)

create-* scaffolders emit a static tree that rots from the moment it is generated. /init analyzes the repo but stops at a one-shot CLAUDE.md. /init-ai instead audits the real repository and adds only what is missing, as a minimal diff over the files that already exist, and across a wider scope (CLAUDE.md + architecture/conventions docs + CI + lint/format + verify). The differences that matter: it audits rather than templatizes, it never overwrites without confirmation, it derives everything from what is actually present, and it makes an explicit call about what not to add.

That last point is the discipline. The most common failure of "make your repo AI-ready" tooling is adding too much — CHANGELOG, CONTRIBUTING, SECURITY.md, ADRs, issue templates, CodeQL — which is noise for a solo or small repo and dilutes the agent's context. /init-ai adds only the high-value core and tells you what it is NOT adding, and why (references/checklist.md).

Non-negotiable principles

1. Audit, never templatize. Never clobber existing files. If a target path already exists, default to not overwriting it (append, add an adjacent file, or skip) and surface it in the plan. Overwriting or deleting always requires explicit confirmation.
2. Opinionated minimalism (anti–cargo-cult). Add only the high-value core. Everything else is opt-in — only when the user explicitly asks for it.
3. Never fabricate. Derive every command, key, and fact from what is actually present (declared scripts, installed dev-deps, config files, real .env* keys). Omit any step whose tool is absent. If something can't be determined, ask — do not invent a toolchain or a value.
4. CLAUDE.md is a thin command center. Repo map, invariants, and links to docs/ — not full detail. If a parent/org CLAUDE.md exists, inherit and link rather than duplicate (rules in references/checklist.md).
5. Optimize for the real toolchain and the AI tools actually in use. Detect the stack; generate AGENTS.md only if Codex is used, copilot-instructions only if Copilot is used. Never create files for tools the repo doesn't use.
6. Compose existing review assets; do not reinvent. The verify path calls the repo's own lint/typecheck/test/build and any existing /code-review or reviewer subagent — it does not build a new checker.

Procedure

Run these steps in order. Stop where noted and wait for the user.

1. Audit (read-only)

Scan with Glob/Read — modify nothing. Inspect presence/absence of: manifest · lockfile · tsconfig · .github/workflows/* (CI) · lint/format config · test config · docs/ · .env* (read key names only, never values) · .env.example · CLAUDE.md (and any parent) · README · AGENTS.md · deno.json. Detect the stack and the AI tools in use. Full table and detection/priority rules: references/checklist.md. If the stack or target is ambiguous (polyglot/monorepo), do not guess — note it for step 2.

2. Judge

List the gaps. Present both "what to add" and "what we deliberately do NOT add, and why". If the repo is too sparse to describe a section truthfully, say so here rather than inventing content. Then wait for the user to choose how to proceed.

3. Plan → confirm

Show the minimal-diff plan. List every file that already exists and would be touched as a single overwrite list, and ask for confirmation once (the user may exclude items by number). In a non-interactive context, skip destructive changes and log them.

4. Apply (minimal diff, respect what exists)

Add only what is missing, from the high-value core (shapes in references/templates.md):

• Thin CLAUDE.md — repo map + invariants + links. Inherit a parent if present.
• docs/ARCHITECTURE.md and docs/CONVENTIONS.md.
• CI (if absent) — a GitHub Actions workflow running the verify chain, built only from steps whose tools are present (per checklist.md).
• lint + format (if absent) — the stack's standard minimal config.
• .env.example — built from real .env* key names; values never copied.

5. Verify entrypoint

Provide one verify entrypoint that chains the stack's checks: a verify script in package.json (JS) or a verify target in a Makefile (non-JS). The exact commands per stack live in references/checklist.md.

What this deliberately does NOT add

See references/checklist.md § "Opt-in only" — these are added only on explicit request, because in a small repo they dilute agent context.

References

• references/checklist.md — audit table, stack detection + verify commands, inheritance & priority rules, opt-in list.
• references/templates.md — the CLAUDE.md / docs / CI / .env.example shapes.