Init

Init

Scan the current project and generate (or update) an AGENTS.md file that gives AI agents full context about the codebase.

When to Use

• User says "init", "generate AGENTS.md", "set up agents", or "create context file"
• User asks to update an existing AGENTS.md or CLAUDE.md
• Starting work on an unfamiliar project and need structured context

Workflow

Phase 1 — Project Detection

Dispatch a scout subagent to scan for:

1. Language & framework indicators: package.json, tsconfig.json, Cargo.toml, pyproject.toml, setup.py, go.mod, pom.xml, build.gradle, Gemfile, composer.json, mix.exs
2. Framework configs: next.config.*, nuxt.config.*, vite.config.*, astro.config.*, svelte.config.*, tailwind.config.*, Django, Flask, FastAPI, Rails, Spring, Actix, Axum
3. Lockfiles (determines package manager): package-lock.json (npm), pnpm-lock.yaml (pnpm), yarn.lock (yarn), bun.lockb (bun), uv.lock (uv), Cargo.lock (cargo), go.sum (go)
4. Monorepo indicators: pnpm-workspace.yaml, lerna.json, turbo.json, nx.json, workspaces in package.json

Phase 2 — Command Detection

Extract build/test/lint commands from:

• package.json scripts — build, test, lint, dev, start, format, check, typecheck
• Makefile targets — list the main ones
• pyproject.toml [tool] sections — pytest, ruff, mypy, black, isort
• Cargo.toml — workspace members, build targets
• go.mod — module name
• CI configs — .github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile
• Docker — Dockerfile, docker-compose.yml

Phase 3 — Convention Detection

Check for:

• Linter configs: .eslintrc*, eslint.config.*, .prettierrc*, prettier.config.*, ruff.toml, .flake8, .pylintrc, clippy.toml, .rubocop.yml
• Editor config: .editorconfig, .vscode/settings.json
• Git hooks: .husky/, .pre-commit-config.yaml
• Commit conventions: commitlint.config.*, recent git log --oneline -n 20
• Contribution guides: CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md
• Existing context files: CLAUDE.md, AGENTS.md, CODE_STYLE.md

Phase 4 — Structure Mapping

• List top-level directories and their purposes
• Identify key entry points (main files, index files, app files)
• Identify test directories and patterns
• Identify config vs source vs docs separation
• Limit to top 2-3 levels for large projects

Phase 5 — Generate AGENTS.md

Read the existing AGENTS.md or CLAUDE.md if present. Then write AGENTS.md using this structure:

# {Project Name}

> {One-line description from README or package.json}

## Tech Stack

- **Language:** {language + version}
- **Framework:** {framework}
- **Package Manager:** {pm}
- **Runtime:** {runtime if applicable}

## Project Structure

\`\`\`
{directory tree — top 2 levels, annotated}
\`\`\`

## Commands

### Setup
\`\`\`bash
{install command}
\`\`\`

### Development
\`\`\`bash
{dev/start command}
\`\`\`

### Build
\`\`\`bash
{build command}
\`\`\`

### Test
\`\`\`bash
{test command}
\`\`\`

### Lint & Format
\`\`\`bash
{lint command}
{format command}
\`\`\`

## Code Style

- {conventions detected from linter configs, editorconfig, etc.}
- {commit message format if detectable}
- {naming conventions if evident}

## Key Files

- `{path}` — {purpose}
- `{path}` — {purpose}

## Conventions

- {any CONTRIBUTING.md rules}
- {PR/branch naming if detectable}
- {testing patterns — where tests live, how they're structured}

## Anti-Patterns

- {things to avoid, from CONTRIBUTING.md or detected patterns}

Phase 6 — Merge Strategy

When updating an existing AGENTS.md:

1. Read the existing file first
2. Preserve sections with custom content that the scan wouldn't detect
3. Update sections where fresh scan data is more accurate
4. Never overwrite project-specific custom rules
5. If user said "generate" without "update", ask whether to overwrite or merge

Edge Cases

Output

The generated AGENTS.md should be 80-200 lines for a typical project. It must be:

• Immediately useful to any AI agent working on the project
• Self-contained — no external references needed to understand the project
• Actionable — commands should be copy-pasteable