agent-instructions · diff
git:20260807.975fe85 to git:20260807.fac9f85
83 added, 71 removed. Audit B to A.
---
name: agent-instructions
- description: Inspect a codebase and create or improve AGENTS.md, CLAUDE.md, or Cursor instructions with verified commands and boundaries. Use when configuring coding agents.
+ description: Create or reconcile scoped AGENTS.md, CLAUDE.md, and Cursor rules from repository evidence. Use when coding-agent guidance is missing, stale, duplicated, or conflicting.
license: MIT
---
# Agent instructions
- Read the project and write the instruction file used by the requested coding agent:
+ Create the smallest set of instruction files that helps the requested coding agent work safely and accurately in this repository. Recover facts from the repository before asking questions, and distinguish commands you executed from commands you only found in documentation.
- - `AGENTS.md` for Codex and other agents that follow the open convention;
- - `CLAUDE.md` for Claude Code;
- - `.cursor/rules/*.mdc` or the project's existing Cursor convention;
- - more than one target only when the user asks, with shared facts kept consistent.
+ ## Choose the task and target
- Do not copy one vendor file blindly into another. Preserve existing instructions, resolve conflicts by scope, and include only facts verified from the repository.
+ Determine whether the request is to:
- ## Steps
+ - create instructions where none exist;
+ - improve one existing file;
+ - reconcile duplicated or conflicting instruction files;
+ - add scoped instructions for a package or subtree; or
+ - translate shared repository facts for more than one agent runtime.
- ### 1. Read the project
+ Infer the target from the request and existing conventions. Ask only when the choice changes installation scope or runtime behavior. Do not create parallel vendor files unless the user asks for them.
+ Use the target's native form:
+
+ - `AGENTS.md` for agents that follow directory-scoped AGENTS instructions;
+ - `CLAUDE.md` for Claude Code project memory;
+ - `.cursor/rules/*.mdc` or the repository's existing Cursor convention;
+ - nested files only when a subtree needs meaningfully different commands, ownership, or boundaries.
+
+ ## Inventory instruction scope
+
+ Before writing, locate all existing agent instructions and relevant repository guidance:
+
```bash
- ls -la
- cat package.json 2>/dev/null
- cat README.md 2>/dev/null | head -60
- cat .env.example 2>/dev/null
- ls src/ app/ lib/ backend/ frontend/ api/ 2>/dev/null
+ pwd
+ rg --files -g 'AGENTS.md' -g 'CLAUDE.md' -g '.cursor/**' -g 'README*' -g 'CONTRIBUTING*' -g 'Makefile' -g 'justfile' -g 'package.json' -g 'pyproject.toml' -g 'Cargo.toml' -g 'go.mod'
```
- Identify: language, framework, entry points, project type (web app, API, CLI, library, mobile).
+ For each instruction file, record its directory, intended runtime, inherited scope, and any statements that conflict with a nearer file or repository evidence. Respect the nearest scoped instruction. Do not duplicate root guidance in every nested file.
- ### 2. Detect the target and stack
+ Preserve valid project-specific constraints. Remove stale facts and redundant prose only when the replacement retains their intent.
- Read the dependency manifests:
- - `package.json` — Node/React/Next.js. Note major versions. Next.js 15 vs 14 is a breaking difference.
- - `Cargo.toml` — Rust
- - `requirements.txt` / `pyproject.toml` — Python
- - `go.mod` — Go
- - `src-tauri/` — Tauri (Rust + web frontend)
+ ## Build an evidence map
- List framework, ORM/database client, auth provider, and key external services.
+ Read the minimum repository evidence needed to establish:
- ### 3. Verify the commands
+ - project purpose, language, framework, and runtime versions;
+ - package or workspace boundaries;
+ - install, development, build, lint, typecheck, test, and release commands;
+ - entry points and locations of domain logic;
+ - generated files, migrations, credentials, deployment configuration, and other high-risk areas;
+ - naming, testing, formatting, and architectural conventions visible in representative code;
+ - required services, environment variables, ports, and setup order.
- Do not assume `npm run dev`. Check `package.json` scripts, `Makefile`, `justfile`, or README:
+ Prefer manifests, scripts, CI workflows, and executable configuration over prose. When sources disagree, report the conflict and use the source that controls actual execution.
- ```bash
- cat package.json | grep -A 20 '"scripts"'
- cat Makefile 2>/dev/null | grep "^[a-z]"
- ```
+ Do not paste an exhaustive directory map. Include a path only when it changes how an agent should navigate, edit, or verify work.
- For each command, note the expected port, any required environment variables, and whether a venv or specific runtime version is needed.
+ ## Verify commands proportionately
- ### 4. Map key files
+ Classify each command as one of:
- Walk the directory structure. Note:
- - Main entry point
- - Core business logic
- - Config files that change behavior (auth config, DB schema, billing)
- - Files that are easy to break (migrations, webhooks, payment handlers)
- - Non-obvious locations (e.g. `src-tauri/src/lib.rs` for Tauri backend)
+ - **executed** — ran successfully in the current environment;
+ - **partially verified** — syntax or a narrow target ran, but dependencies or services prevented full verification;
+ - **documented only** — found in a trusted project source but not run;
+ - **stale or conflicting** — contradicted by configuration or failed for a repository reason.
- ### 5. Find the gotchas
+ Run safe, relevant checks when feasible. Do not start long-lived services, mutate external systems, install dependencies, or run destructive commands merely to upgrade a verification label. State prerequisites beside commands that need them.
- Look for:
- - Comments like `// DO NOT MODIFY`, `// IMPORTANT`, or `// WARNING`
- - Non-standard conventions or patterns unique to this project
- - Monorepo or multi-package structure
- - External services that require API keys to run locally
- - Known issues, TODOs, or WIP branches
+ ## Write for the target runtime
- ### 6. Write CLAUDE.md
+ Keep shared repository facts consistent, but adapt runtime-specific mechanics rather than copying one vendor file verbatim.
- ```markdown
- # Project Name
+ ### AGENTS.md
- One sentence on what this is.
+ Express directory-scoped instructions, commands, boundaries, and verification expectations. Put specialized guidance in the nearest directory that owns it.
- ## Commands
- \`\`\`bash
- # dev (runs on port XXXX)
- command here
+ ### CLAUDE.md
- # build
- command here
+ Write durable project memory: commands, architecture landmarks, conventions, and hazards. Avoid unsupported runtime features or generic advice already supplied by Claude Code.
- # test
- command here
- \`\`\`
+ ### Cursor rules
- ## Key Files
- - `path/to/entry.ts` — what it does
- - `path/to/config.ts` — what it controls
+ Follow the repository's current rule-file format and globs. If the repository has no Cursor rules, confirm the current supported format in Cursor's official documentation before creating one; do not infer a schema from memory or another runtime. Split rules only when activation scope differs. Verify frontmatter and glob coverage against the files the rule should govern.
- ## Stack
- - Framework + version
- - Database + ORM
- - Auth provider
- - Key external services
+ ## Resolve conflicts explicitly
- ## Gotchas
- - Non-obvious things that would trip someone up
- - What not to touch without reading X first
- - Any invariants the code depends on
- ```
+ For each conflict, choose one action:
- Keep it under 60 lines. Leave out sections that don't apply. A short accurate CLAUDE.md beats a long padded one every time.
+ 1. retain the nearer scoped rule;
+ 2. replace stale guidance with verified repository behavior;
+ 3. separate runtime-specific instructions from shared facts;
+ 4. ask the user when two live policies express different intent that the repository cannot resolve.
+
+ Do not silently choose between policy statements about deployment, generated files, security, data handling, or ownership.
+
+ ## Output contract
+
+ When editing, deliver:
+
+ 1. the requested instruction file or files;
+ 2. a short scope summary naming which directories and runtimes they govern;
+ 3. a command table with verification labels;
+ 4. conflicts resolved, preserved, or still requiring a decision;
+ 5. any facts deliberately omitted because they were unverified or too volatile.
+
+ Keep files concise enough to scan, but let repository complexity determine length. Prefer concrete imperatives and paths over explanatory essays.
+
+ ## Verify
+
+ After writing:
+
+ 1. Re-read every instruction file that applies to each edited location and confirm precedence is coherent.
+ 2. Confirm every path, script name, package name, port, and environment-variable name exists in repository evidence.
+ 3. Re-run the safe commands used as acceptance checks, or label them accurately when full execution was unavailable.
+ 4. Confirm nested files contain only scope-specific differences and do not contradict inherited rules.
+ 5. Check runtime-specific syntax against an existing valid file, an installed validator, or current official runtime documentation. If none is available, label syntax as unverified rather than presenting it as established.
+ 6. Compare the final file with the evidence map and remove unsupported claims, generic agent advice, and duplicated repository documentation.
+ 7. Report verification results and limitations; do not describe a documented-only command as tested.