README + AGENTS prompt - generate both in a single prompt.

readme.agents.txt

Analyze this project and create or regenerate its documentation for both AI coding agents and humans in one coordinated pass:

- `AGENTS.md`: concise, authoritative entry point for tool-neutral agent guidance.
- `README.md`: concise, authoritative entry point for human-facing project documentation.
- Supporting documentation: the appropriate home for detailed policies, workflows, reference material, rationale, incident history, and information moved out of either entry point.

“Regenerate” means reconcile existing documentation against project evidence and fill useful gaps. Preserve its knowledge and intentional policies. When documentation is missing or skeletal, create a concise starting point from known purpose, approved intent, and available artifacts. Do not replace useful content with a generic template.

The task is complete only when both entry points exist and fit the project’s current state, necessary supporting documentation is written, links and symlinks are verified, and the applicable preservation check is complete.

## Primary objective: useful entry points without information loss

For mature documentation, reduce entry-point size while preserving knowledge. For missing, naive, or incomplete documentation, establish useful starting points. Add only what the project’s evidence and current needs support.

Preserve all distinct, non-sensitive information in documentation you replace, shorten, merge, or remove. Information may move, but it must remain in the resulting repository, discoverable through working links.

Git history, the PR description, the commit message, and the final response do not count as preservation. The information must exist in documentation in the resulting checkout.

Preserve, where present:

- Rules, prohibitions, preferences, requirements, and exceptions.
- Scope, applicability, prerequisites, ordering, and approval conditions.
- Commands, flags, examples, paths, identifiers, and configuration details.
- Architectural explanations, definitions, and terminology.
- Rationale, tradeoffs, incident narratives, failure modes, and lessons learned.
- Measurements, dates, versions, machine identities, citations, and evidence.
- Caveats, limitations, uncertainty, invalidated results, and historical context.
- Enforcement mechanisms, relevant tests, and references to canonical implementations.
- Intentional hand-written material, including details that seem repetitive but add a distinct qualification.

You may consolidate genuine duplicates into one authoritative explanation. Preserve every distinct detail from the combined copies.

Do not weaken a mandatory rule into a suggestion, remove an exception, broaden a rule beyond its original scope, or change an operator decision as part of cleanup.

Do not preserve actual secrets in documentation. If encountered, omit the secret value, retain safe explanatory context, and report the affected location without exposing the value.

## Secret handling

Include these requirements in the root agent guidance. Document the project's actual credential workflow when one exists.

- Never put secret values in chat, tool output that enters the transcript, documentation, examples, logs, commits, or PR text. Do not ask users to paste secrets into chat. Inspect names, paths, and metadata without displaying values. Redact values before output; redaction after output is too late.
- Explicitly ignore local files that contain secrets in the project’s applicable `.gitignore`. Include these rules in Git delivery when applicable. Global ignore rules and `.git/info/exclude` alone are insufficient. Add or repair narrowly scoped rules for known or documented secret paths. Examples include `.env`, local credential files, and private keys. Do not invent filenames or use broad patterns that hide source files or public certificates. Keep sanitized templates such as `.env.example` trackable; they must contain placeholders, never working credentials.
- Prefer a maintained secret vault or secret manager as the authoritative store. 1Password is one example; an existing cloud, team, or local secret manager is also suitable. Follow the project's established choice. Do not require a specific vendor, subscription, or account. If none exists, document the preference and leave the choice open.
- Retrieve secrets at runtime through the chosen manager's supported integration. Avoid literal secret values in command arguments, shell history, or debug output. Documentation may contain variable names and safe references to secrets, but never their values. Do not retrieve real secrets merely to verify documentation.
- Ignore rules do not protect files already tracked by Git or remove secrets from history. If exposure is found, report only the affected path and required follow-up, including revocation or rotation. Do not display the secret, rewrite history, delete credentials, or rotate them as part of this documentation task.

Minimal `.gitignore` changes for these requirements are in scope. Check applicable rules without reading or displaying secret values. Do not create secret files, provision a vault, or migrate credentials during this task.

## Delivery mode

Select a mode before making changes:

- `pr`: create a working branch, commit, push, and open a pull request.
- `direct`: commit and push to the default branch without creating a branch or PR.
- `local`: write and validate documentation in the current project directory without commits, pushes, or a PR.

Use the mode I explicitly name. Otherwise use `local` when the directory has no Git repository, Git has no commits yet, or no remote is configured. For other repositories, default to `pr`, except you may choose `direct` when all of the following are established:

- `git shortlog -sne` shows a single author.
- No CI workflow is triggered on `pull_request`.
- No branch protection or CODEOWNERS file exists.

If any condition for `direct` is unknown, use `pr`. If a requested Git delivery mode is unavailable, follow the `local` rules to prepare and validate the files. Report the requested delivery as incomplete. Do not initialize Git, choose an initial branch, create a remote, or publish a new repository without a separate request.

State the selected mode and evidence for it before editing. The mode applies to every documentation, `.gitignore`, and symlink change in this task.

## Repository analysis

Inspect the project before writing. Assess documentation completeness separately from implementation maturity; a short README does not prove a young project.

Choose an approach for each entry point and component:

- **Reconcile:** substantial documentation exists. Preserve and reorganize it against evidence.
- **Bootstrap:** documentation is absent, boilerplate, naive, or too incomplete to guide its readers. Retain useful details and write the missing essentials.
- **Mixed:** apply both approaches where needed, including mature code with weak docs or detailed plans without code.

Do not use word count alone to select an approach. State the approach and whether implementation is absent, partial, or established.

Determine whether the existing project is:

- A simple repository containing one cohesive application, library, service, script collection, infrastructure project, or similar system.
- A monorepo containing independently built, tested, deployed, or maintained components.

When structure is not established, use root entry points. Do not invent components or a directory tree from a proposed architecture.

Review, as applicable:

- All existing `AGENTS.md`, `README.md`, `CLAUDE.md`, and `GEMINI.md` files, including symlink targets.
- Documentation indexes, policies, conventions, operational guides, archives, and contribution documents.
- Project structure and relevant source code.
- Dependency manifests and lockfiles.
- Build, test, lint, formatting, and type-checking configuration.
- CI/CD workflows.
- Scripts, Makefiles, Taskfiles, and Justfiles.
- Container, deployment, and infrastructure configuration.
- Environment/configuration files, without exposing secrets.
- Tests, schemas, and license files.
- Project briefs, accepted requirements, decision records, and explicit project-specific instructions from the user.

Absence is evidence too: record when code, setup, tests, or deployment do not yet exist. Do not require software artifacts for documentation, research, design, or other non-code projects.

Read the full existing files you will restructure. Do not base the rewrite on excerpts or only their headings.

For a simple repository, use a root `AGENTS.md` and root `README.md`, with supporting documentation as needed.

For a monorepo:

- Keep cross-cutting agent rules and a component map at the root.
- Create or retain short component `AGENTS.md` files only where distinct workflows or conventions justify them.
- Create component READMEs only where a distinct product surface or independently useful documentation justifies them.
- Component guidance supplements applicable ancestor guidance and contains only subtree-specific information.
- Do not duplicate root content or create one documentation file per directory.
- Do not move a cross-cutting rule into a subtree where agents working elsewhere would miss it.

## Evidence and policy

Support factual claims with project evidence: source, manifests, scripts, CI, help text, tests, schemas, documentation, approved briefs, explicit user requirements, or other artifacts. A brief supports intended behavior; it does not prove implementation.

Distinguish four things:

1. Current implementation: what the code and configuration do.
2. Intentional policy: what the operator or project requires.
3. Historical evidence: what happened under a particular date, version, or configuration.
4. Approved intent: what the project plans to build or produce, but has not implemented. Label it as planned. Keep unapproved ideas and open decisions separate.

Existing explicit policies are evidence of intended behavior even when the implementation does not fully enforce them. A mismatch does not authorize changing the policy to match the code. Preserve the policy and document the discrepancy.

Do not invent commands, flags, architecture, workflows, conventions, features, endpoints, configuration, dependencies, examples, or deployment procedures.

Mark necessary inferences explicitly. Do not present a command found in an old document as current when the implementation contradicts it.

Correct demonstrably stale factual guidance. Preserve its distinct historical information in an appropriately labeled historical section, including the correction, evidence, and applicable date/version where available.

When a claim cannot be verified, preserve it with an explicit uncertainty label in the appropriate supporting document rather than silently deleting it or presenting it as verified.

When instructions conflict, use explicit supersession or other clear evidence to resolve them. Preserve the previous policy as historical when relevant. If precedence is unresolved, document the conflict; do not silently choose a new policy.

Do not add marketing language, speculative roadmap promises, or generic engineering advice. Preserve existing roadmap or decision history when moving it, clearly labeled with its status.

## Bootstrap content

Use this guidance where evidence or documentation is sparse. It supplements the content rules below; it does not weaken preservation.

If the purpose or intended outcome is unknown, first inspect available project context. Ask one concise question only when that answer is needed for useful docs. Continue independent work. If no answer is available, state what is unknown without inventing a product from a directory name.

Create the smallest useful pair of entry points:

- `README.md`: known purpose and audience, explicit current status, what exists today, and the first supported action a reader can take. If nothing runs yet, say so. Describe the next approved milestone or essential open decision when known.
- `AGENTS.md`: known scope, established constraints and decisions, the four baseline policies below, and the workflow or checks that actually exist. Identify consequential decisions that remain open. Do not select a stack, architecture, tooling, or deployment platform on the user’s behalf.

Use project-specific requirements from the user as intentional policy. Do not copy unrelated machine-wide preferences into a project merely to fill space. Label planned structure and workflows as planned; do not put hypothetical commands into a runnable quickstart.

Omit unsupported sections, empty tables, stock badges, placeholder commands, and long TODO lists. A brief status sentence can explain that setup or tests do not yet exist. Do not create supporting files solely to fill a template. A concise starter pair can remain well below the size targets.

A documentation task does not authorize scaffolding code, package manifests, CI, test suites, or deployment infrastructure. Record an approved next step when appropriate.

## Preservation workflow

Before rewriting, inventory the existing material and assign destinations. Missing source files contain nothing to migrate. Read even a tiny or boilerplate file before deciding that it has no distinct information.

Create a persistent migration audit when existing information moves, consolidates, changes meaning, or receives a factual correction. Scale it to the material: a short mapping is enough for a few items; substantial restructuring requires the detailed audit below. For new files or content retained in place without semantic changes, the final report can record the preservation check; do not create an empty audit file.

Record the original source revision when available. For uncommitted source material, record that fact and identify the source precisely enough to review the migration.

When a migration audit is required, record each original section and distinct item within it:

- Original file and heading or other stable identifier.
- Disposition: retained, moved, consolidated, corrected with history retained, or unresolved and preserved.
- Destination file and section.
- Any meaningful wording, scope, or factual correction.

A section containing multiple independent rules or facts needs enough audit detail to account for each. A single row saying “everything moved to docs” is insufficient.

Write or update destination material before removing it from its original location.

Prefer existing authoritative documents. Integrate information into relevant sections rather than appending another copy of the same policy.

Create a small, coherent set of topic documents where needed. There is no arbitrary 2–3-file cap: preservation and clear organization determine the number. Avoid both one giant overflow document and dozens of tiny fragments.

A verbatim archive may supplement the migration, but it does not replace organizing current guidance into usable documentation. Do not satisfy preservation by dumping the old AGENTS.md into an archive and leaving active rules buried there.

Complete the audit by comparing original material with final destinations, including examples, exceptions, rationale, and evidence—not merely matching headings.

## AGENTS.md word budget

For a complex project with substantial established guidance, target 2,000–3,000 words for the root `AGENTS.md`, with a hard maximum of 4,000 words. These are not minimums. A young or simple project may need only a few hundred words.

Count with `wc -w`, including headings, tables, and code blocks. Use the same counting method before and after. Do not install or use a tokenizer for this task.

Shorter is welcome when necessary guidance remains clear. Do not pad to the target.

The 4,000-word ceiling applies to the combined text of the root `AGENTS.md` and any companion documents that every agent must read for every task. Moving content into universally required reading does not reduce the effective budget. Count each distinct document once; symlink aliases do not add another copy.

Specialized documents read only for explicitly identified tasks are outside that universal budget. Make their reading triggers clear and keep them focused enough to be useful.

Component `AGENTS.md` files should generally stay under 750 words. They supplement applicable ancestor guidance, so consider the combined reading burden for work in each component. Do not create component files merely to evade the root budget.

Preserve readable formatting, normal line lengths, and useful whitespace. Do not meet the budget by compressing unrelated instructions into dense paragraphs or tables.

Report before/after word counts; mark a missing original as “absent (0 words).” Line counts are optional context, not an acceptance criterion.

## AGENTS.md content

The root file should let an agent identify:

- What the project does and its important boundaries.
- Where major functionality and component guidance live.
- Essential environment assumptions and common verified development commands.
- Cross-cutting policies that affect ordinary work.
- Critical safety, data-integrity, and workflow constraints.
- Which additional document must be read before a particular kind of task.

Keep broadly applicable and consequential instructions directly visible. Move detailed procedures, specialized reference material, long examples, incident narratives, and extended rationale into supporting documents.

For a moved operational rule, retain a concise actionable rule or task-specific reading instruction at the appropriate entry point. A bare “see docs” link is insufficient.

When supporting documents exist and task-specific reading is useful, include a compact reading map with specific triggers, for example:

| Before doing this | Read |
| --- | --- |
| Running or comparing measurements | Relevant methodology and execution guide |
| Changing data or publishing results | Relevant integrity and reporting policy |
| Managing models or services | Relevant operational guide |

Use only categories supported by the repository. Link directly to useful sections where practical.

Do not require every agent to read every supporting document on every task. State when each document applies. Linked policies remain mandatory within their stated scope.

Include these topics where useful, combining sections as appropriate:

- Brief overview, important architecture, and runtime model.
- Essential tech stack, versions, and domain terminology.
- Environment and dependencies, including how credentials are obtained without documenting their values.
- Verified setup, execution, test, single-test, lint, format, type-check, and build commands.
- Project/component map.
- Repository-specific coding patterns, naming, error handling, typing, testing, and dependency management.
- Change workflow and contribution expectations.
- Mandatory practices, prohibited patterns, caution areas, and deprecations.
- Recurring troubleshooting requirements.
- Links to detailed guidance and tool-neutral symlink notes.

Preserve these four baseline policies verbatim in the applicable root guidance:

* 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.

These four bullets are intentional policy, not inferred conventions.

Keep instructions applicable to any coding agent. Tool-neutral wording does not require deleting documentation about a named tool that the repository builds, tests, or operates.

## README.md size and content

Keep the root README approximately 300 lines or fewer as a human-usability target. Move extensive reference material into supporting docs and link to it. Component READMEs should generally stay under 80 lines. These are readability targets, not substitutes for preserving information.

The README is primarily for humans. Link to `AGENTS.md` once; do not reproduce agent-specific instructions.

Organize around these priorities where the project supports them. For a project without runnable implementation, lead with purpose, current status, and a supported next step instead of an invented usage or setup guide:

1. What this is: 2–4 sentences covering purpose, product surface, and runtime/deployment model.
2. Usage: the main help section, adapted to every material product surface.
3. Build and run: prerequisites, tools, containers, services, environment variables, installation, local execution, tests, and builds where applicable.
4. Useful reference: configuration, layout, brief architecture, troubleshooting, and operational notes.
5. Existing project information: license, contribution guidance, supporting documentation, and relevant links.

Adapt usage to the project:

- CLI: commands, flags, examples, and documented exit codes.
- Web application: access URLs, main flows, authentication, and exposed APIs with supported examples.
- Library/SDK: installation, imports, a minimal example, and key APIs.
- Mobile application: main screens/flows and simulator/device execution.
- Script/tool collection: purposes and invocations.
- Infrastructure/automation: managed resources and clearly distinguished inspection versus destructive operations.
- Documentation, research, design, or other non-code work: intended readers, available material, how to use or contribute to it, and applicable review or validation steps.

Derive examples from repository evidence and label inferences. Document multiple surfaces when they materially matter.

Preserve accurate hand-written explanations and useful examples. Reorganize them for usability; retain distinct information in supporting documentation when shortening them.

## Documentation ownership and discoverability

Give each detailed policy, procedure, or reference topic one authoritative home. Entry-point summaries may repeat the essential action and link to that home, but must not become competing full versions.

Supporting documentation may serve agents, humans, or both. Agent-oriented detail is explicitly allowed outside `AGENTS.md`.

Separate current policy, operational procedures, reference material, and historical explanations clearly enough that readers cannot mistake an old command or invalidated result for current guidance.

Preserve exact technical identifiers and citations unless evidence supports a correction. Follow existing repository conventions for timestamps, source revisions, machine names, evidence, and links.

Repair links and anchors affected by relocation throughout the repository where applicable. Preserve compatibility anchors or provide a clear replacement where feasible.

Add a short maintenance rule to the appropriate entry point: update existing authoritative sections; place new long explanations and incident narratives in supporting documents; keep entry-point instructions concise and within budget.

## Git and symlink handling

Before modifying files, inspect the directory and, when Git exists, its status, commits, current branch, remotes, and identifiable default branch.

Do not discard, overwrite, or include unrelated work. Missing Git metadata or an unborn branch does not prevent local documentation work. In an established repository, an unresolved default branch prevents branch-based delivery, not otherwise safe local edits. If unrelated changes prevent safe edits, complete unaffected work and report the blocked files.

In `local` mode, edit in place. Do not stage or commit files, switch branches, initialize Git, or configure remotes.

In `pr` mode, create a working branch from the default branch before editing.

In `direct` mode, work on the default branch. Do not rebase, amend, or force-push. If branch protection or a rejected push prevents delivery, retain the local commit, report the failure, and offer `pr` mode.

At every level containing an `AGENTS.md`, ensure `CLAUDE.md` is a relative symlink to `AGENTS.md`.

Before replacing a regular `CLAUDE.md` or `GEMINI.md`, preserve and reconcile all its distinct information using the same migration process. Preserve or repair existing GEMINI aliases where applicable; do not create them without repository precedent or a request.

Verify symlink targets. Never replace a regular file before its information has been accounted for.

## Validation and execution limits

This is a documentation task, with the narrow `.gitignore` exception above. Do not install dependencies, modify the runtime environment, run application test suites or builds, launch services, run benchmarks, or execute documented procedures merely to verify them.

Read-only inspection and safe `--help`/`--version` checks are permitted. Static checks of documentation word counts, links, anchors, symlinks, and diffs are permitted. Inspect a command first if even its help path might have side effects.

“Verified from repository evidence” does not mean “executed successfully.” Report the distinction accurately.

Before delivery, and before committing when applicable:

1. Complete the applicable preservation check or audit: every distinct original item has a real destination.
2. Check relocated content for lost qualifiers, exceptions, examples, rationale, measurements, and citations.
3. Check that active rules remain discoverable before the actions they govern.
4. Check that historical and uncertain material is clearly labeled.
5. Verify links and anchors in all changed documentation and affected references.
6. Verify documented commands against repository evidence.
7. Count words with `wc -w`. Confirm the root AGENTS.md plus all universally required companion reading totals no more than 4,000 words.
8. Check component guidance, README readability, and the combined instruction burden for common tasks.
9. Verify tool-neutral guidance and symlink targets.
10. Review the diff, or compare saved originals when Git is absent, for unrelated changes, secret values, and accidental policy changes. Keep secret values out of review output.
11. For bootstrap content, confirm that current state, approved plans, and open decisions are distinct. Check that no command, feature, path, or policy was invented.
12. Confirm each entry point gives its reader a useful next action at the project’s current stage, without filler or unnecessary supporting files.
13. Check that known secret paths have explicit `.gitignore` rules and sanitized templates remain trackable. Use static inspection or `git check-ignore --no-index` for rule coverage. Check tracked status separately; ignore coverage does not prove a file is untracked. Report limitations without exposing values.

If the universal instruction set exceeds its budget, continue reorganizing specialized detail into documents with explicit task-based reading triggers. Do not solve the limit by deleting information, disguising universally required reading as optional, or hiding active guidance in an archive.

## Commit and delivery

In `local` mode, leave the validated files in place and report their paths. Do not commit or push.

In `pr` or `direct` mode, commit all intended documentation, preservation-audit, `.gitignore`, and symlink changes with this subject:

docs: add/update AGENTS.md agent guidance

In `pr` mode:

- Push the working branch.
- If `gh` is available and authenticated, open a PR titled:
  `Docs: add/update repository documentation`
- If PR creation is unavailable, push when possible and provide a suggested PR title and body.
- Do not open a PR if pushing failed.

In `direct` mode:

- Push the commit to the default branch.
- Do not create a branch or PR.
- If pushing fails, retain the local commit and report the failure.
- Include the change summary in the commit body and final output.

The final report, and the PR body or direct-mode summary where applicable, must include:

- What changed and why.
- Selected delivery mode, documentation approach, implementation maturity, and project structure, with reasons.
- Before/after word counts for AGENTS.md and README.md.
- The combined word count of the final universally required agent instructions, identifying every included document.
- Supporting documents created or updated and the location of the preservation audit, or why no separate audit was needed.
- Significant relocations and consolidations.
- Corrections to hand-written content, with historical information retained.
- Inferences, unresolved conflicts, and verification limitations.
- Static checks performed; state that application tests and builds were not run.
- Any Git, push, or PR action that could not be completed.

Do not claim that no information was lost unless the completed preservation check or audit supports that claim.