Analyze this repository and create or update its AGENTS.md files. Each AGENTS.md is symlinked to CLAUDE.md and GEMINI.md, so all guidance must be tool-neutral and apply to any AI coding agent.
First determine the repository structure from evidence. It may be:
- A simple repository containing one application, library, service, collection of scripts, infrastructure configuration, or other cohesive project.
- A monorepo containing multiple independently built, tested, deployed, or maintained components.
For a simple repository, produce a single root AGENTS.md.
For a monorepo, produce a root AGENTS.md with cross-cutting rules and a map of components, plus a short AGENTS.md for each component that has a distinct build, test, lint, deployment, or development workflow. Do not create one per directory. Do not create nested files where the root guidance is sufficient, and do not duplicate root content in component files. A component-level AGENTS.md should contain only guidance that is specific to its subtree.
If an AGENTS.md already exists, UPDATE it: reconcile against current code, preserve intentional hand-written content, fix stale claims, and only restructure where evidence requires it. Do not regenerate from scratch. If hand-written content is stale, correctness wins: fix it, and note the change in the PR description. If CLAUDE.md or GEMINI.md exist as regular files rather than symlinks, reconcile their content into the applicable AGENTS.md first, then replace them with symlinks.
Before writing, inspect the repository and derive all guidance from evidence. Review, as applicable: README and docs, project structure, dependency manifests, build/test/lint/format/typecheck configuration, CI/CD workflows, scripts/Makefiles/Taskfiles/Justfiles, container/deployment/infrastructure config, and existing code patterns.
Requirements:
- Every statement must be supported by repository evidence. Do not invent commands, architecture, conventions, workflows, or tooling.
- "Verified" means the command appears in a manifest, script, Makefile, or CI config. Do not execute commands to verify them, except read-only checks such as --version or --help. Do not install dependencies or run test suites.
- If something cannot be verified, omit it or explicitly mark it as inferred.
- Capture conventions actually present in the codebase, not recommendations.
- Be concise and high-signal: every line should change agent behavior. No generic software-engineering advice. Omit sections that do not apply.
- Target under approximately 150 lines for the root file and 60 lines per component file. If you are padding to fill a section, cut the section.
- Guidance in the nearest AGENTS.md applies to its subtree and supplements the root file. Component files should not restate root-level guidance.
Structure (omit inapplicable sections; component files use only the relevant subset):
1–3 sentences: what it does, major architectural characteristics, and primary runtime or deployment model.
Languages and versions, frameworks and major libraries, data stores, infrastructure context, and external services or integrations.
Domain-specific concepts and acronyms used throughout the code.
Required local tools, services, databases, containers, environment files, credentials, or infrastructure assumptions needed to develop or test.
Verified commands for install/setup, local execution, tests, a single test, linting, formatting, type-checking, and building.
Important directories and where major functionality lives. In a monorepo, the root file should also identify independently operated components and point to any component-level AGENTS.md files.
Observed conventions only: architectural patterns, error handling, typing and safety, file naming, testing conventions, and dependency management.
- Make minimal, focused changes; avoid broad refactors unless requested.
- Preserve existing architecture and patterns.
- Don't introduce new dependencies without justification.
- Update tests when behavior changes; update docs when user-visible behavior, configuration, or workflows change.
Plus any repository-specific workflow expectations found during analysis. The four bullets above are intentional baseline policy; keep them verbatim.
Mandatory repository-specific practices.
Repository-specific anti-patterns. Include only if evidenced by code comments, lint rules, CI checks, or documentation. Do not invent them.
Generated files, migrations, deployment manifests, infrastructure configuration, secrets, vendored code, and lockfiles.
Legacy patterns, libraries, APIs, or directories that new code must avoid.
Include only if repository evidence shows recurring issues or non-obvious requirements.
This file is symlinked to CLAUDE.md and GEMINI.md; keep all instructions tool-neutral.
Before modifying files, create a working branch from the repository's default branch. If the repository is not a Git repository, has no identifiable default branch, or has unrelated uncommitted changes that make this unsafe, do not discard or overwrite anything; report the limitation clearly.
After writing the files, create or update the symlinks at every level containing an AGENTS.md:
ln -sfn AGENTS.md CLAUDE.md ln -sfn AGENTS.md GEMINI.md
Handle any pre-existing regular files as described above before replacing them.
Commit all changes with a clear message. If gh is available and authenticated,
push the branch and open a PR titled:
docs: add/update AGENTS.md agent guidance
Otherwise, push the branch when possible and print the suggested PR title and body. The PR description must:
- Summarize what was added or changed.
- Explain whether the repository was treated as a simple repository or a monorepo and why.
- List anything marked as inferred or uncertain.
- Note any hand-written content that was corrected.
- Identify any requested Git, push, or PR action that could not be completed.