init

name: init description: Use when the user wants to create, update, or review an AGENTS.md context file for their codebase, or when starting a new project that needs agent instructions

Generate AGENTS.md

Core Principles

1. Default is empty. Only include information whose absence causes agent failure.
2. Detect, don't generate. Extract facts from config/CI files. Never fabricate content.
3. Ask, don't assume. Use AskUserQuestion for what files cannot reveal.
4. Format, don't narrate. Bullet points only. No prose, no rationale, no architecture descriptions.
5. Differential Context. Include = (project practice - language/framework default) + prohibitions

Workflow

Phase 1: Scan (automatic)

Detect build/test/lint commands from these sources (priority order):

1. .github/workflows/*.yml / .gitlab-ci.yml — CI is the source of truth
2. Makefile / justfile — task runner targets
3. package.json scripts / pyproject.toml [tool.*] / Cargo.toml
4. Linter config existence: .eslintrc, ruff.toml, .prettierrc, biome.json

Only extract: command strings, tool names, runtime versions. Do NOT read source files.

Phase 2: Ask (3 questions via AskUserQuestion)

Q1 (required): Present detected commands for confirmation. "I detected these commands. Please confirm or correct:"

• Test: {detected}
• Lint: {detected}
• Build: {detected}

Q2 (required): "Are there files or directories that must never be modified? (e.g., generated code, vendored deps, contract files)"

Q3 (required): "Are there project practices that deviate from language/framework defaults? Only things agents would likely get wrong. (e.g., 'use Zustand not Redux', 'Result type for errors — no throw', 'Repository pattern only — no direct ORM in handlers'). Answer 'none' if not applicable."

Phase 3: Generate

Combine scan results + user answers. Rules:

• Only Commands section is always present (if any commands exist)
• Constraints and Conventions sections appear only if user provided content
• No content beyond what was detected or user-confirmed
• Target: 100-250 words. Hard limit: 300 words.

Output Template

# AGENTS.md

## Commands
- Test: `{command}`
- Lint: `{command}`
- Build: `{command}`
- Type check: `{command}`

## Constraints
- {protected_file_or_dir_with_reason}

## Conventions
- {deviation_from_framework_defaults}

Anti-patterns