Agent Md Improver

Agent Instruction Files Improver

Treat instruction files as a minimal decision layer, not a project manual. Prefer deleting, consolidating, or moving instructions over adding prose.

Workflow

0. Establish project risk profile and default safe posture

Resolve the target directory, then before auditing, classifying, deleting, rewriting, or moving any instruction, identify whether it is an experimental/side project, internal application, production service, public API/SDK/plugin ecosystem, migration/rollback-sensitive system, or subject to security, privacy, compliance, or release controls.

Use repository and user evidence such as deployment/hosting and CI/CD files, published API schemas or packages, migration/backup/rollback scripts, authentication/permission configuration, privacy/compliance documents, and explicit owner statements. Record each risk as confirmed, inferred, or unknown.

When the risk profile is unknown, use the conservative default: do not propose deleting or weakening safeguards for external compatibility, data migration or rollback, security or permissions, data integrity, release/deployment, privacy, compliance, destructive operations, or secrets. Mark the item needs owner confirmation.

Apply aggressive cleanup only when evidence supports an experimental or side-project context and no external contract or high-risk control is affected. Express every risk-sensitive recommendation as trigger → action → verification.

Example: same rule, different risk

• Original: Do not preserve backward compatibility.
• Side project: Remove obsolete internal paths instead of adding new compatibility layers.
• Public API or production: Do not add compatibility layers unless compatibility is required by an external contract. Before removing an existing path, verify callers, migration requirements, and rollback coverage.

1. Establish scope before judging content

1. Find instruction files with rg --files -g 'AGENTS.md' -g 'AGENTS.local.md' -g '.agents.md' -g 'CLAUDE.md' -g '.claude.md' -g '.claude.local.md'.
2. Identify the files that actually govern the target. Record parent-to-child precedence and local overrides.
3. Do not inspect or change global instruction files unless the user explicitly includes them.
4. Do not treat every nested instruction file as a candidate for expansion. A nested file should exist only for a real domain or workflow boundary.

2. Build an evidence-backed instruction inventory

Read each applicable file completely. For every instruction, verify it against the codebase, configuration, scripts, and recent task evidence.

Classify each item before proposing a change:

Preserve explicit high-risk guardrails identified in Step 0 and any other high-cost failure controls; do not weaken them merely to make a file shorter.

3. Audit derivability and conflicts

For each candidate addition or retained line, ask:

1. Can an agent infer this from package.json, scripts, CI, directory names, tests, tool help, or nearby code?
2. Is it already stated by a parent, child, tool description, or another source of truth?
3. Is it needed for most tasks in this scope, or only a specialized workflow?
4. Does it specify a condition, action, and verifiable outcome?

If the answer to 1 or 2 is yes, remove or link instead of repeating it. If the answer to 3 is no, move it behind progressive disclosure. Resolve a conflict by choosing one source of truth; never preserve contradictory wording to be "safe."

4. Report before editing

Always present a Minimal Context Report and wait for approval before writing. Use references/templates.md for the report and diff structure. Include:

• files that govern the requested scope and their precedence;
• the risk profile, evidence status, and items needing owner confirmation;
• evidence-backed keep, remove, move, add, and rewrite decisions;
• must-fix conflicts or stale instructions separately from optional polish;
• the expected effect on agent decisions, not a chapter-completeness score.

Use references/quality-criteria.md when a scored assessment is useful or requested. Do not reward a file merely for listing commands, architecture, or every key file.

5. Propose and apply the smallest safe diff

1. Show exact diffs, with deletions before additions.
2. Add only verified repository-specific facts. Cite the configuration, code, test, or command that supports each addition.
3. Keep low-frequency procedures in a skill or one-level-deep reference; the instruction file should state when to load it.
4. Do not create an instruction file simply because none exists. Create one only when verified non-inferable constraints recur in the requested scope.
5. After approval, preserve the existing structure where possible and apply the diff.

6. Verify the result

After editing, re-check the affected scope:

• every path and command is real and current;
• no child file repeats or contradicts its parent;
• no retained line is obvious from the repository alone;
• high-risk guardrails remain explicit, and unknown risk was not treated as low risk;
• referenced skills and documents exist and are loaded only when relevant.

Report what changed and any facts that still require owner confirmation.

Writing rules

• State project-specific constraints, not generic agent advice.
• Put instructions at the narrowest scope that reliably governs the affected work.
• Prefer conditional instructions: trigger → action → expected verification.
• Treat code, tests, CI, and tool schemas as primary evidence; instruction files should describe the exceptions those artifacts cannot express.
• Use concise tables or bullets only when they reduce ambiguity.