Agent guide

Agent Guide

Refactor persistent Agent instructions without silently changing the workflow they protect.

The goal is not the shortest file. The goal is the smallest instruction set that preserves the user's intended behavior, safety boundaries, and project-specific knowledge.

Boundaries

• Analyze instruction text and recommend where each rule belongs.
• Do not claim that an MCP server, hook, plugin, permission, CI rule, memory system, or other integration works unless it was separately inspected and tested.
• Treat MCP, plugins, and browsers as capability channels, not places to store prose. Keep only the short routing rule in persistent instructions; keep configuration and implementation in their native system.
• Do not invent a universal instruction-priority order. If conflict resolution depends on platform-specific loading or precedence, verify the current platform rules or state that the effective chain is unverified.
• Do not assume the current working directory is the target.
• Do not edit global or personal instructions unless the user explicitly requests the edit. Otherwise return a proposed draft or diff.
• Never remove a safety boundary, permission boundary, no-touch path, required command, or required validation step without making the change explicit.

Choose A Branch

Use Audit when the user wants findings without a rewritten file.

Use Rewrite when the user wants a lean replacement, diff, or old-versus-new comparison.

Use Guided Rebuild when the user wants instructions built around their workflow but the important preferences and boundaries are still unknown.

Load Supporting Material

• For a full audit, or when a rule's destination is unclear, read references/decision-matrix.md.
• For a rewrite or old-versus-new comparison, read templates/comparison-report-template.md.
• For a guided rebuild, read templates/guided-questions.md and ask only questions whose answers would change the design.
• When drafting a new modular instruction file, read templates/agent-block-template.md and select only blocks justified by the user's workflow.

Do not load every resource by default.

Workflow

1. Establish Scope

Identify:

• the target platform and instruction file;
• whether the task covers one file or the effective instruction chain;
• whether the user wants an audit, proposal, comparison, or file edit.

If only one file is available, audit it and state that cross-file conflicts and actual precedence were not assessed.

Completion criterion: the target, requested output, and any scope limitation are explicit.

2. Build The Intent Ledger

Before rewriting, split the source into meaningful rules and assign each rule an ID.

For every rule, record:

• source;
• original intent;
• behavior or boundary it protects;
• likely consequence if removed.

Group rules only when they are genuinely equivalent. Do not hide a safety rule inside a broad summary.

A generic aspiration with no unique observable behavior may protect no independent capability. Do not invent a replacement rule merely to preserve its sentiment.

Completion criterion: every meaningful source rule has an ID and an identified purpose.

3. Assign One Disposition Per Rule

Choose exactly one primary disposition:

• Keep here — applies broadly and must remain persistently visible.
• Keep at project level — depends on this repository, domain, architecture, command, or path.
• Rewrite — the intent matters but the wording is vague, duplicated, or too long.
• Move to a skill or reference — a conditional workflow or detailed procedure.
• Move to memory — an evolving preference or non-authoritative lesson that does not require enforcement.
• Enforce elsewhere — a behavior better guaranteed by hooks, settings, CI, permissions, or scripts.
• Document for humans — explanation, tutorial, background, examples, or source notes.
• Delete duplicate — fully represented by another rule.
• Delete no-op — generic advice that does not materially change model behavior.

Keep authoritative architecture decisions, compliance boundaries, and domain constraints in project-controlled sources rather than personal memory.

For content involving an external tool, distinguish between:

1. the short instruction that tells the Agent when to use the capability; and
2. the capability's actual configuration or implementation.

Do not describe this as moving prose “into MCP.”

Completion criterion: every rule ID has one disposition and, when moved, a concrete destination.

4. Draft Only After Classification

Rewrite retained rules as concrete trigger-action-boundary instructions:

When [specific situation], do [specific action]. Do not [relevant boundary].

Preserve observable behavior while removing:

• generic exhortations;
• duplicated explanations;
• tutorials from always-loaded context;
• platform assumptions that were not verified;
• lists included only for visual completeness.

Do not invent commands, paths, installed skills, integrations, or precedence rules.

Completion criterion: every line in the draft changes behavior or routes the Agent to information needed for the current situation.

5. Run A Regression Check

Compare the draft with the intent ledger. Check at least:

• safety and permission boundaries;
• project and no-touch boundaries;
• required commands and validation;
• task or skill routing;
• user collaboration preferences;
• reporting or handoff requirements.

Mark each protected behavior as:

• preserved;
• moved and still reachable;
• proposed for migration but not yet reachable, with the original rule retained;
• intentionally changed with user approval;
• weakened or lost.

If a critical behavior is weakened, lost, or cannot be verified, do not recommend adopting the draft as-is.

Completion criterion: every protected behavior has a regression result.

6. Deliver The Result

For an audit, return:

Scope
Intent Ledger
Keep
Move
Rewrite
Delete
Risks
Recommendation

For a rewrite, return:

Scope
Proposed Draft
Rule Disposition Ledger
Preserved Behaviors
Moved Behaviors And Destinations
Lost Or Weakened Behaviors
Unverified Platform Assumptions
Recommendation

For a guided rebuild, return:

Questions Or Confirmed Assumptions
Modular Draft
Why Each Block Exists
Content Routed Elsewhere
Regression Check

Completion Gate

Do not finish until:

• every meaningful old rule is accounted for;
• every moved rule has a concrete destination and an explicit reachability status;
• an unavailable proposed destination is never used as justification to remove the original rule;
• critical behavior has not disappeared silently;
• no cross-platform priority order was invented;
• runtime integrations are not presented as tested when only their instruction text was reviewed;
• generic aspirations are not replaced with newly invented generic rules;
• the user can see exactly what changed and why.