eliasoulkadi/shokunin/init

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

Anti-Patterns

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)