agents-md-generator

AGENTS.md generator

Create high-signal, repository-grounded instructions with a host-neutral semantic core for coding-agent hosts that support AGENTS.md. Treat tool-specific instruction files as adapters when a host requires them.

Scope and side effects

• findings and draft do not authorize instruction-file edits. Only apply authorizes those edits, limited to the requested files; validation side effects require separate authorization under the rule below.
• The default target is the root AGENTS.md. Create or revise a nested target only when the user names or approves that path and selects apply.
• Repository inspection is read-only. Validation commands may write caches or artifacts, install dependencies, use the network, or trigger external systems. Assess them first, run the smallest safe check, and get authorization before consequential validation.
• Before editing, inspect the target file and any existing worktree diff. Preserve unrelated and pre-existing changes.
• Never delete or overwrite source instruction files such as CLAUDE.md without explicit authorization covering those files. Reuse authorization already granted for the same action. Report any validation artifacts that cannot be safely cleaned up.

Core workflow

1. Define the task, output, and target independently so mixed requests remain representable.
2. Inspect the repository, existing instruction files, and target-file worktree state.
3. Resolve operational facts, policy, host compatibility, and source conflicts using the rules below.
4. Ask only the missing questions that materially affect the result.
5. Produce findings, a draft, or authorized edits for the selected root or nested target.
6. Decide whether nested files or host-specific adapters are justified.
7. Validate claims and, after writes, review the resulting diff.
8. Tighten the instructions and hand off evidence, assumptions, and residual uncertainty.

Do not skip repository inspection unless the user supplies the complete relevant context.