AGENTS.md Improvement Loop
A project-context loop for repositories that use AGENTS.md, CLAUDE.md, or similar instruction files.
Use loop copies the kickoff prompt. Copy Markdown and Download loop include the complete Markdown page with context, source attribution, anchors, and guardrails. Cursor / Claude Code buttons prepare the shorter kickoff prompt only.
Supported agents
Goal
Make repository instructions accurate, actionable, and verification-oriented.
Feedback gate
ls -la && rg -n "build|test|lint|deploy" README.md package.json AGENTS.md CLAUDE.mdStop condition
Agent instructions state stack, commands, architecture rules, and verification expectations accurately.
Give the agent these inputs before it starts the loop. This keeps discovery bounded and prevents vague retries.
The loop assumes these commands or integrations are available. Missing tools should be reported as blockers, not ignored.
Two separate pieces: the kickoff prompt starts the loop, while the downloaded Markdown carries the complete reference page.
1. Copy or download
Use the kickoff for a fast agent run. Download the full Markdown when you need source, context, and attribution in one file.
2. Paste into the agent
Start a fresh agent session in the target repo and provide the requested project context if the loop asks for it.
3. Let it self-pace
The agent should act, check evidence, retry only when the gate fails, and stop at the stated exit condition.
The diagram shows the order. This checklist keeps only the action, command, and failure handling needed during a real pass.
1. Inspect project facts
Read package scripts, docs, and structure before editing instructions.
2. Find instruction gaps
Look for missing commands, wrong framework claims, or unsafe shortcuts.
3. Patch instructions
Add concise rules for architecture, tools, tests, and security.
4. Verify no fiction
Ensure every instruction is supported by project files.
This is the text copied by Use loop. It is intentionally shorter than the Markdown export.
Audit repository agent instructions against actual project files, then improve them with accurate commands, architecture rules, and verification expectations.
Goal: Make repository instructions accurate, actionable, and verification-oriented.
Check command: ls -la && rg -n "build|test|lint|deploy" README.md package.json AGENTS.md CLAUDE.md
Exit condition: Agent instructions state stack, commands, architecture rules, and verification expectations accurately.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not invent commands, tools, or architecture claims that are not present in the repository.Quality
88/100
Safety
93/100
Expected output
A concise, accurate AGENTS.md improvement or audit report.
Related loops
Browse allDocs Sync After Edits
After behavior or API changes, update README, docs, examples, and project instructions to match the code.
Kickoff preview
Review code changes for documentation impact, update relevant docs/examples/instructions, and report evidence or why no docs update is needed. Goal: Keep documentation aligned with code changes. Check command: git diff --name-only HEAD Exit condition: Docs are updated for relevant changes or the no-docs-needed decision is justified. Max iterations: 3 Guardrails: - Do not weaken, skip, delete, or rewrite the validation command to force success. - Do not claim completion until the stated exit condition is actually satisfied. - If blocked, report the blocker, evidence, and next safest action instead of gaming the metric. - Do not update docs with behavior that the code does not actually implement.
Codex Project Context Loop
Build a clear Codex task goal from project files, constraints, done criteria, and stop conditions.
Kickoff preview
Inspect the project context and write a strict, audit-friendly implementation objective with scope, constraints, done criteria, verification, and stop-if rules. Goal: Create an audit-friendly agent objective before implementation. Check command: find . -maxdepth 2 -type f | sort | head -100 Exit condition: The goal is concrete enough for an agent to execute and for a reviewer to audit. Max iterations: 2 Guardrails: - Do not weaken, skip, delete, or rewrite the validation command to force success. - Do not claim completion until the stated exit condition is actually satisfied. - If blocked, report the blocker, evidence, and next safest action instead of gaming the metric. - Do not write a goal that allows vague completion or unverified claims.
Claude Code Hooks Setup
Plan and validate Claude Code hook rules for post-edit verification, pre-commit scanning, and safe stop behavior.
Kickoff preview
Design Claude Code hooks for this repository. Define hook goals, allowed commands, risks, and manual verification before enabling them. Goal: Design Claude Code hooks that improve safety without blocking legitimate work. Check command: rg -n "hooks|PostToolUse|PreToolUse|Stop" .claude AGENTS.md CLAUDE.md Exit condition: Hook behavior is documented, scoped, safe, and testable. Max iterations: 3 Guardrails: - Do not weaken, skip, delete, or rewrite the validation command to force success. - Do not claim completion until the stated exit condition is actually satisfied. - If blocked, report the blocker, evidence, and next safest action instead of gaming the metric. - Do not enable hooks that run destructive commands without explicit human approval.
Ship PR Until Green
Implement a scoped change, open or update a pull request, inspect CI, and continue until all required PR checks pass.
Kickoff preview
Take this branch to a green pull request. Implement the requested change, run local verification, open or update the PR, run `gh pr checks`, inspect failures, fix root causes, and repeat until every required check passes or you hit the iteration cap. Goal: Open or update a pull request and stop only when all required PR checks are green. Check command: gh pr checks Exit condition: All required pull request checks are successful and the PR is ready for review or merge. Max iterations: 10 Guardrails: - Do not weaken, skip, delete, or rewrite the validation command to force success. - Do not claim completion until the stated exit condition is actually satisfied. - If blocked, report the blocker, evidence, and next safest action instead of gaming the metric. - Do not disable required checks, edit loops to skip jobs, or remove tests to make CI green. - Do not merge the PR unless the user explicitly asked for merge authority.