flow-prune-agent-setup

Prune an agent setup

Find stale or conflicting instructions and configuration, then apply only the cleanup the user authorizes. Judge by ownership, active scope, and effective behavior, not age.

Phase 1: Discover effective sources

Identify host and version, active project or profile, CLI overrides, and managed layers before attributing behavior to a file. Check the host's current official docs for locations and precedence; schemas differ between hosts and versions, and not every settings file is user-owned. Never print credentials.

• Instructions: every instruction file the host loads (for example AGENTS.md or a host-specific equivalent, rules directories) at user, project and local scope.
• Configuration: each settings layer (user, project, local, managed), including permissions, hooks, enabled plugins or extensions, and MCP server entries. Treat managed, system and CLI overrides as read-only context.
• Capabilities: skills, agents and plugins in user and project directories, plus any memory store.
• Locate skill ownership through its supported manager (plugin manager, npx skills, or the owning installer).

Phase 2: Four audits

1. Instructions: stale paths, redundant or contradictory rules, procedures that belong in a focused skill, rules tooling already enforces. Verify references first.
2. Memory: outdated facts and duplicates, with source, age, and intended consumer. Unknown relevance is not evidence for deletion. Reconcile any memory index.
3. Settings and integrations: effective values, obsolete hooks or MCP servers, conflicting scopes. Distinguish allow, ask, and deny entries; removing a protective rule changes behavior even when the tool looks unused.
4. Skills, agents, and plugins: overlap, routing quality, inactive workflows, ownership, actual discovery. Inspect the host's enabled-plugins setting (for example enabledPlugins in settings.json) where it has one; do not assume that schema elsewhere. Separate installed links from source directories and host-owned bundles.

Run parallel read-only audits only when authorized and independent. Merge into one punch list: item, source and owner, reason, evidence, consequence, confidence, proposed action. Label uncertain candidates and false positives.

Phase 3: Apply the requested scope

• Audit-only request: report the punch list and stop.
• Explicit cleanup: perform the authorized reversible edits without re-asking per item. Ask only about consequential uncertainty or unauthorized destructive actions. Never auto-delete unknown assets.
• Back up changed settings, preserve unrelated keys, and validate the resulting format and effective behavior.
• Use the owning installer or plugin manager. Unlinking an install is not deleting its source. Complete an explicitly requested user-owned skill removal through the supported mechanism instead of handing the user an unsafe shell command. Never edit managed or plugin-owned sources directly.

Phase 4: Confirm behavior

Reinspect active values and discovery. Explain removed and retained items and remaining conflicts. Distinguish disk state from cached session or UI state; do not keep rewriting correct files because the current session has not refreshed.

Anti-patterns

• Treating old or unused entries as proven obsolete.
• Auditing one settings file and claiming full effective coverage.
• Removing deny rules, plugin-owned assets, caches, or history under a vague cleanup request.
• Repeated approval questions after the user named the exact cleanup.

Done when

• Findings rest on effective scope, provenance, and a concrete behavioral consequence.
• Authorized changes validate and preserve unrelated setup; uncertain items stay explicit.
• Actual discovery and effective state are checked, or the limits are reported.

Use flow-handoff only if unresolved decisions or a later session need a continuation record.