Refresh Agents.prompt

---
description: "Refresh and surgically update an existing Apple-platform agent kit: re-analyze the evolved codebase, detect drift, and update only the affected agents, instructions, and skills."
agent: "Agent Builder"
---

# Refresh Agents

Re-analyze the codebase and surgically update the existing agent ecosystem to match the current project state. This is for maintenance — not full regeneration.

## When to Use

- After major refactors, module restructuring, or file reorganization
- After dependency version upgrades (Swift, SwiftUI, Xcode)
- After team convention changes
- When agents produce consistently wrong or outdated output
- Periodic maintenance (quarterly review)

## Standard User-Facing Progress

1. Re-analyze the codebase
2. Detect drift across five dimensions
3. Compare analysis against existing agents
4. Present drift findings and proposed changes
5. Surgically update affected files
6. Audit updated bundle
7. Deliver refreshed bundle

Complete the entire workflow in this session. Use `vscode_askQuestions` when user input is needed.

## Execution Steps

1. **Re-analyze** — Run full codebase analysis. Compare with existing agent ecosystem. Identify what changed in the project since agents were generated.
2. **Detect drift** — Check all five drift dimensions from SKILL.md:
   - File references: agents referencing files/modules that have been renamed, moved, or deleted
   - Convention drift: agents enforcing abandoned or changed conventions
   - API pattern drift: agents suggesting deprecated or removed API patterns
   - Architecture drift: agents assuming restructured architecture
   - Ecosystem drift: agent-to-agent references broken (renamed/removed agents)
3. **Diff report** — Present a structured drift report:
   - Which files are affected
   - What specific content is stale
   - What the current state is
   - Proposed fix for each drift signal
   - Severity: cosmetic / misleading / harmful
4. **Confirm changes** — Use `vscode_askQuestions` to present the drift report and let the user approve, modify, or skip proposed changes.
5. **Surgical update** — Update only the affected files. Do not regenerate files that are still accurate. Preserve any manual customizations the user has made to generated files.
6. **Verify markers** — Ensure all modified files have the `<!-- Generated by Apple Agent Builder Kit -->` marker immediately after the YAML frontmatter closing `---`. Add the marker if missing.
7. **Audit** — Run full audit on the updated bundle. Fix any findings. Iterate until PASS.
8. **Deliver** — Summary of changes made, files updated, drift signals resolved, and any remaining risks.

## Constraints

- Surgical updates only — do not regenerate the entire bundle
- Preserve manual customizations in generated files (changes between the marker and the end of the file that differ from original generation)
- Update only what has drifted — leave accurate content untouched
- When drift is severe (>50% of agents affected), recommend full regeneration via `/generate-workflow-agents` instead
- Generated file markers must be present on all files to enable refresh — warn if markers are missing