Tool sp maintain agents instructions

Maintain Agents Instructions

Purpose

Guide the agent through a short maintenance wizard so top-level instruction files stay aligned with current repo workflows, skill changes, and provider support without drifting into duplicate or conflicting guidance.

When to use this skill

• The repo's workflows, commands, or package-manager defaults changed.
• Skills were added, removed, renamed, or substantially rewritten.
• AGENTS.md, GEMINI.md, or .claude/CLAUDE.md may be outdated.
• A repo added multi-provider support and needs a bridge pattern or refresh.

Scope boundaries

This tool maintains the instruction files — AGENTS.md and the provider bridges — not the skills they route to.

• tool-sp-maintain-skills — drift inside the skills themselves. The two hand off constantly: renaming a skill drifts the routing here, and a rule that outgrew an instruction file usually belongs in a skill over there.
• ref-sp-agents-instructions-authoring — the rules this tool applies: source-of-truth model, bridge pattern, persona placement.
• ref-sp-agents-mr-wolf-persona — the canonical persona text. The instruction file carries a verbatim projection of it; this tool re-syncs that copy but never rewrites the voice in place.
• Domain detail belongs in the owning skill, not in an instruction file. Moving a rule out of AGENTS.md and into its skill is a valid outcome of this pass.

First Step

Read the repo's instruction-authoring skill (ref-sp-agents-instructions-authoring here, the requires dependency), its agent-persona skill (ref-sp-agents-mr-wolf-persona here), and the provider reference files under the instruction-authoring skill's references/providers/ folder that match the files being touched.

Core Workflow

1. Inspect the current instruction files and the code or skill changes that may affect them.
2. Ask only the missing questions needed to determine the source of truth, supported providers, and any real provider-specific exceptions.
3. Update the source-of-truth instruction file first.
4. Refresh provider bridge files so they still point back to the source of truth cleanly.
5. Update skill listings, help-routing sections, quick commands, and workflow summaries that drifted.
6. Validate that the files still agree and that bridge files remain thin.

Defaults

• Prefer a single source-of-truth instruction file plus thin provider bridges.
• Prefer a root AGENTS.md as the source of truth; fall back to .github/copilot-instructions.md only when the repo is Copilot-centric or already uses that pattern.
• If the repo supports multiple providers, recommend an import bridge rather than parallel duplicated instruction bodies.
• When the repo carries a deliberate persona or working style, keep the persona core inline in the source-of-truth file — it must load on every turn — and treat the repo's agent-persona skill (ref-sp-agents-mr-wolf-persona here) as the canonical text that copy is refreshed from. Sync in that direction; never rewrite the tone ad hoc in the instruction file. See "Persona placement" in ref-sp-agents-instructions-authoring.
• When skill names or workflows change, update both the source-of-truth file and any provider routing summaries that mention them.
• If the top-level instruction file grows too large, move domain detail into the owning skill and keep only routing at the top level.

Wizard Questions

Ask only the questions that are still unanswered after inspecting the repo.

Question area	What to ask	Why	When	Expected outcome
Provider support	Which providers or entry files does this repo actively support now?	The maintenance pass should not update phantom entry points or miss live ones.	When the supported provider set is unclear.	The update scope matches the real instruction surfaces.
Source of truth	Which file should own the real repo guidance after this update?	The maintenance pass needs one authoritative file before bridges can be refreshed.	When the current source of truth is unclear or changing.	One file owns the real workflow and policy text.
Provider-specific exceptions	Does any provider need a real provider-specific note, or should the bridge stay thin?	Unnecessary provider-specific text creates drift.	When a bridge file is growing or behaving differently.	Exceptions stay narrow and justified.
Drift scope	Which commands, workflows, skills, or policies changed?	The maintenance pass should update the exact sections that drifted, not rewrite the whole file blindly.	When the triggering change is broad or loosely described.	The edit is focused on the real drift surface.

Gotchas

• Do not rewrite every instruction file independently if an import bridge already exists.
• Do not leave skill listings or quick-command sections stale after renames or workflow changes.
• Do not move framework or language detail into the top-level instructions when the owning skill should hold it.
• If the repo already uses policy-managed files such as .aiexclude or .claude/settings.json, instruction updates should still match that model.

Validation

• Check the result against the instruction-authoring skill's checklist (ref-sp-agents-instructions-authoring; in this repo, its references/checklist.md).
• Confirm the source-of-truth file and bridge files still agree.
• Confirm provider bridge files remain minimal unless a real provider-specific exception exists.
• Run a targeted error check on the touched instruction files before concluding.

References

• Read the instruction-authoring skill's provider references (ref-sp-agents-instructions-authoring; in this repo, its references/providers/copilot-instructions.md, references/providers/gemini-instructions.md, and references/providers/claude-instructions.md) for file-specific authoring rules.
• Use the repo's agent-persona skill (ref-sp-agents-mr-wolf-persona here) when the instruction changes need to preserve the repo's agent voice, interaction style, or escalation stance.
• Use the repo's skill-maintenance skill (tool-sp-maintain-skills here) when the instruction pass also needs skill consolidation or routing cleanup.
• Use the repo's agent-security skill (ref-sp-agents-security here) when instruction changes must stay aligned with generated policy files or provider restrictions.