Maintain agent instructions

Maintain Agent Instructions

Keep durable guidance scoped, verifiable, and distinct from on-demand procedures. When this package's Expert Agent Operating Contract is in scope, preserve the complete canonical contract; its size alone is not a reason to replace it with a summary.

Discover before mutation

1. Identify the clients and versions in scope.
2. Read current first-party discovery and precedence documentation when behavior may have changed.
3. Inventory global, repository, nested, override, rule, and managed-policy sources actually visible to those clients.
4. Ask each available client to summarize loaded instruction sources when a safe diagnostic exists.
5. Treat undocumented filenames as ordinary documentation unless configuration proves the client loads them.
6. Report the discovered sources, owners, precedence, conflicts, and proposed exact targets before editing.

For an installation or update of this package, read the package INSTALL_PROTOCOL.md and instruction-pack.json. Status inspection is the default. Do not mutate live user-global instructions without explicit authorization for the named clients and targets.

Use references/client-routing.md for the surface map, then verify current paths rather than assuming the reference is timeless.

Discovery and audit are read-only. Require explicit authorization for the exact files and scopes to create, merge, move, or replace. Authorization for a repository file does not imply authorization for global, managed, or sibling repository guidance.

Establish the project instruction foundation

Every maintained project requires one canonical project agent instruction file. Resolve the repository root and inspect AGENTS.md, AGENT.md, supported client adapters, and nested instruction files.

If no canonical project file exists, create root AGENTS.md unless:

• the current request is strictly read-only;
• repository policy forbids the change; or
• the repository explicitly establishes another canonical filename.

In those cases, report the missing or alternate foundation. Prefer AGENTS.md for portable project guidance. Do not maintain independent, contradictory AGENT.md and AGENTS.md bodies; when compatibility requires both, keep one as a concise router to the declared canonical file.

Include only applicable durable repository guidance:

• purpose, boundary, and important entry points;
• supported build, test, packaging, release, and deployment workflows;
• remote-only, platform-specific, or resource restrictions;
• generated, protected, private, or externally managed paths;
• architectural invariants and recurring hazards;
• project-local skills, tools, subagents, and runbooks;
• mutation, approval, documentation, and memory responsibilities.

Keep current task state, session history, large backlogs, and deep architecture in their proper artifacts. Update project instructions when durable workflow, safety, validation, architecture, or tooling rules change.

Classify every instruction

Place:

• the complete approved operator contract in supported user-global guidance
• other personal interaction preferences in supported user-global guidance
• repository-wide commands and constraints at the repository root
• subtree-specific rules near the governed code
• reusable multi-step procedures in Agent Skills
• deterministic enforcement in linters, hooks, CI, or scripts
• live external data and actions behind authorized integrations
• temporary constraints in the current prompt or thread

Do not maintain independently edited copies merely for symmetry. Use one canonical content source plus the smallest required client adapters. An adapter may contain a rendered copy when the host cannot import the canonical source; verify it against the source hash.

Preserve precedence and ownership

• Follow the host's actual precedence rather than inventing a universal order.
• Keep stronger managed and repository policy intact.
• Resolve contradictions explicitly.
• Avoid instruction loops such as two files declaring each other authoritative.
• Keep commands beside the repository that owns them.
• Do not put project-specific hosts, devices, paths, package identifiers, or release commands in a public global core.
• Never overwrite managed policy. Treat system-, administrator-, organization-, and client-managed guidance as read-only unless its own management surface is explicitly in scope.

Read references/instruction-review.md before consolidating large instruction sets.

Protect portability and privacy

Exclude from public or global instruction artifacts:

• personal names, usernames, emails, profiles, and home paths
• credentials, tokens, private keys, and environment dumps
• private hosts, IP addresses, device IDs, and internal project schemas
• assumed client-only tools without a capability fallback
• claims that an instruction file outranks system, administrator, or user policy

Use placeholders only in user-facing templates that require configuration. Prefer repository discovery over persistent placeholders when values already exist in project metadata.

Validate

• Capture original content, permissions, and hashes for every authorized target.
• Write through a same-directory temporary file and atomic replacement when the platform supports it.
• Preserve a restorable backup or version-control rollback before replacement.
• Inspect the before-and-after diff and reject unrelated instruction churn.
• Check file size, import behavior, aggregate limits, and truncation limits.
• Confirm the intended client discovers the file.
• Start a new session and test the contract identity, one representative rule, and one intended repository override.
• Verify procedures activate through skills rather than bloating every session.
• Search for duplicated, stale, contradictory, personal, and machine-specific content.
• Report clients that could not be runtime-tested.

If any selected client does not load the complete contract, classify that client as failed or installed-unverified rather than silently accepting a summary. Restore only files changed by this operation when rollback is needed. Do not discard unrelated repository or user changes. Report the recovery location and any global or managed sources left untouched.

Output

Report instruction sources, scope and precedence, rules retained or moved, conflicts resolved, client adapters, privacy scan, runtime evidence, and remaining compatibility uncertainty.