---
name: agents-init
description: Autonomously explore a repository and write practical AGENTS.md guidance. Use when asked to create, initialize, or refresh repository instructions.
license: MIT
---
# Initialize Repository Guidance

Run `/agents-init` when a repository needs new or refreshed `AGENTS.md` guidance.

The command is autonomous: explore the repository, generate concise guidance for the root and meaningful local scopes, then apply every generated file. Do not ask the user to review drafts or provide plan IDs.

## Workflow

1. Explore the repository before writing. Inspect the tree, manifests, build and test configuration, CI, existing instructions, entry points, core modules, representative tests, and important local boundaries. Use read, search, code navigation, project analysis, and shell inspection commands when useful.
2. Call `agents_finalize_init_discovery` with concise findings that cite files read in this initialization. Write natural summaries that help future agents work correctly; do not mechanically quote source code.
3. Use the returned fact packs only to choose scopes. Render useful, concise Markdown in the style that fits this repository. Trace metadata is optional.
4. Stage every scope through `agents_stage_managed`, then immediately call `agents_apply_initialized`. The package writes all validated scopes without user confirmation.

## Guardrails

- Keep guidance specific and operational: commands, architecture, local conventions, tests, and boundaries that matter to work in that directory.
- Do not write `AGENTS.md` through ordinary `edit` or `write` tools while initialization is active. The package-owned apply step preserves text outside its markers and never generates `AGENTS.override.md`.
- Stop on malformed markers, stale previews, out-of-repository paths, missing source reads, or failed writes. Use `/agents-cancel` only when initialization cannot finish.

After applying, report the written paths and any scope that could not be generated.