---
name: init
description: "Use when the user asks to initialize a repo, create AGENTS.md, generate contributor guidelines, or set up agent-oriented documentation for a codebase."
triggers:
  - "initialize repo"
  - "init repo"
  - "create AGENTS.md"
  - "contributor guidelines"
  - "set up project"
  - "repository setup"
  - "project initialization"
  - "new project setup"
negatives:
  - "build tool"
  - "template"
  - "boilerplate"
  - "scaffold component"
  - "scaffold project"
license: MIT
compatibility: opencode
disable-model-invocation: true
metadata:
  version: 1.3.0

  workflow: system
  audience: developers
---


# AGENTS.md Generator

Analyze a codebase and generate a concise, accurate `AGENTS.md` contributor guide.

**Target:** the current working directory, unless user provided another folder as input.

---

## Gather Information

Collect facts about the repository. **Only record what is actually found — never invent information.**

These probes are independent — run them in parallel (e.g., dispatch subagents) when the tooling supports it.

### Repository structure

Map the repo structure (3 levels deep, excluding .git, node_modules, dist, build, __pycache__, .venv and other autogenerated folders). This is analysis input — the output AGENTS.md should describe non-obvious architecture, not list directories. Focus on the "big picture" that requires reading multiple files to understand.

### Build & dev commands

Extract actual command definitions from the project's build system: `package.json` scripts, `Makefile` targets, `pyproject.toml` scripts, `Cargo.toml` bins/workspace members, `go.mod` module path, `docker-compose.yml` services, etc.

### Coding conventions

Check for and record key settings of:

- Linter configs
- Formatter configs
- Type checking (note strict mode if applicable)
- Agent rules: `.cursorrules`, `.cursor/rules/`, `.github/copilot-instructions.md`
- Pre-commit hooks

If agent rules files exist, read and extract the important parts — focus on conventions that matter for code generation, not verbatim content.

### Git history

Review the last 20 commits to identify commit message conventions and patterns. If this fails (not a git repo or shallow clone), note the limitation and skip.

### Existing documentation

- If `README.md` exists, read it for context about the repo's purpose and setup.
- If `AGENTS.md` already exists, read it — you'll be improving it rather than starting fresh.
- If `CLAUDE.md` exists, read it for additional context.

---

## Generate AGENTS.md

### Document requirements

- Title: `# Repository Guidelines`
- 200-400 words (exceed only if complexity genuinely demands it)
- Direct, instructional tone
- No repetition across sections

### Sections to include (omit any that lack evidence)

**## Project Structure & Module Organization**
Architecture that requires reading multiple files to understand. Omit anything obvious from opening a single file.

**## Build, Test, and Development Commands**
Actual commands from the build system. Include how to run a single test.

**## Coding Style & Naming Conventions**
Enforced rules from linter/formatter configs. Include tool names.

**## Testing Guidelines**
Test framework, how to run tests, coverage requirements if any.

**## Commit & Pull Request Guidelines**
Commit conventions derived from actual git history. Note any PR templates.

Add other sections only if facts strongly support them (e.g., Architecture Overview, Agent Instructions).

### What to never include

Do not include generic development practices such as:
- "Write unit tests for all new utilities"
- "Use meaningful variable names"

Do not invent sections like "Common Development Tasks" or "Tips for Development" unless the repo's own documentation expressly contains them. Do not list every file — only document what is non-obvious.

### New vs existing

- **Existing AGENTS.md:** Fix inaccuracies, fill gaps, remove generic advice, ensure commands are current. Preserve correct, specific content. Present the diff and ask to confirm before overwriting.
- **New AGENTS.md:** Write directly to the repository root. No confirmation needed.

---

## Validate

Before finalizing, verify:

- Every command mentioned actually exists in the build system
- Every file path mentioned exists in the repo
- No generic advice slipped in
- No repeated information across sections
- The document stays within the target word count
- Agent rules are incorporated (woven into relevant sections, not dumped verbatim)

---

## Principles

- **Never fabricate** — if a section has no evidence, omit it entirely
- **Prefer commands over prose** — `npm test` over "run the test suite"
- **Big picture only** — architecture that spans multiple files, skip the obvious
- **Incorporate agent rules** — weave important parts of .cursorrules or copilot instructions into relevant sections
- **Respect existing work** — in improvement mode, preserve correct specific content
- **Conciseness is quality** — every sentence must earn its place

---

## Workflow

1. **Probe repository structure** — map 3 levels deep, exclude generated dirs. Identify build system, language, and framework.
2. **Extract commands** — read package.json scripts, Makefile targets, pyproject.toml, Cargo.toml, docker-compose.yml.
3. **Collect conventions** — linter configs (.eslintrc, .prettierrc, pyproject.toml), formatter settings, type checking mode, agent rules files (.cursorrules, .cursor/rules/).
4. **Review git history** — last 20 commits for commit convention patterns (conventional commits, custom formats). Skip if not a git repo.
5. **Read existing documentation** — README.md for context. Existing AGENTS.md or CLAUDE.md for improvement baseline.
6. **Draft AGENTS.md** — 200-400 words, direct tone. Include project structure, build commands, coding style, testing, commit conventions. Omit generic advice.
7. **Validate output** — every command mentioned exists in build system. Every path exists in repo. No fabricated content. No repetition.

## Error Handling

| Cause | Fix |
|-------|-----|
| Not a git repository | Skip git history section. Note limitation explicitly in output. |
| Shallow clone with limited commit history | Use available commits. Note "limited history available." |
| No build system detected | Skip build commands section. Document that no formal build system was found. |
| Existing AGENTS.md has inaccuracies | Fix errors, fill gaps, remove generic advice. Show diff before overwriting. |
| Agent rules files not found | Skip agent rules integration. Never invent conventions. |
| Mixed or ambiguous conventions across files | Note the inconsistency. Default to the dominant convention in the majority of files. |
| Empty repository with no source files | Generate minimal AGENTS.md with project name only. Add "populate as project grows." |

## Anti-Patterns

| Pattern | Problem | Fix |
|---------|---------|-----|
| Including generic advice ("write unit tests") | Not actionable, not project-specific | Only include conventions actually enforced in the codebase |
| Listing every directory in the repo | Adds noise, not architecture insight | Document only non-obvious structure that spans multiple files |
| Copying agent rules verbatim into AGENTS.md | Redundant and bloated | Weave important rules into relevant sections only |
| Inventing commands not in the build system | Build breaks when user tries them | Extract commands only from actual build system files |
| Missing sections where evidence exists | Incomplete onboarding guide | Include all sections that have supporting evidence |
| Overwriting correct, specific existing content | Loses institutional knowledge | Preserve correct content. Fix only inaccuracies and gaps. |
| Exceeding 400 words with filler prose | Too long to scan; loses utility | Cut every sentence that doesn't convey a specific convention |

## Checklist

- [ ] Project type identified (lib, app, monorepo, etc.)
- [ ] AGENTS.md created with profile, behavior, and tools sections
- [ ] .gitignore includes platform-relevant entries (node_modules, .env, etc.)
- [ ] License file created matching project requirements
- [ ] CI/CD scaffolding included if project will be deployed

## Sources

- GitHub Docs — "About READMEs" (docs.github.com)
- Keep a Changelog — keepachangelog.com
- Conventional Commits — conventionalcommits.org
- Google Open Source — "README.md guidelines" (opensource.google)
- Daniele Procida — "Diátaxis documentation framework" (diataxis.fr)
- Write the Docs Guide — writethedocs.org
- Eric Holscher — "Documentation Principles" (ericholscher.com)