init

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)