aide_upgrade

Compare the AIDE methodology artifacts in this project against the canonical versions and return structured JSON results grouped by category. Use this when the user asks to update AIDE, sync AIDE, refresh AIDE, check for AIDE updates, or bring AIDE up to date. This is NOT for editing user .aide specs — it inspects methodology infrastructure only.

The tool uses a two-call pattern for progressive disclosure:

First call (no category param): Returns a lightweight summary — every category with file names, statuses, and counts, but NO file content. Use this to understand what has drifted and present a summary to the user. Ask which categories they want to apply.

Second call (with category param): The tool writes all differs/missing files directly to disk itself and returns a manifest — file results with filePath, status ("updated", "created", or "unchanged"), and name, but NO canonicalContent. The agent never sees file content and never uses the Write tool for methodology files.

Repeat the second call for each category the user confirms.

As the calling agent, you must:

1. Call without category first to get the summary

2. Present each drifted category (differs/missing) and ask the user which to apply

3. For each confirmed category, call again with category=X — the tool writes the files and returns a manifest. Report what was updated/created to the user.

4. For the mcp category, a result that carries prescription is merged into the existing MCP config by you (read → merge → write). A result that carries pinMove or globalSwitch is never merged by hand: the tool writes it (see the MCP step). If malformed, tell the user — do not overwrite.

5. For ide, the manifest may include instructions for VS Code extension install — execute that command for the user. Zed config is written directly by the tool.

6. For brain, the summary reports missingSections, outdated section text as staleSections and a legacy brain launcher as legacyLauncher (its reasons), each named separately. The brain category then works through three calls, each one decision at a time: a. category: "brain" (after the user's yes) inserts every missing section from the latest bundled template — byte-identical, in the file's line endings — only when the config launches the template's own brain server. It returns { outcome: "inserted", inserted } (markers only; empty when nothing is missing) or { outcome: "adapt", adapt, instructions } naming the sections the user must write for their backend. b. category: "brain" with brainChange: <marker | "launcher"> returns one { outcome: "change", target, before, after, beforeHash } diff to show the user. It is read-only. For a non-template config it returns missing with the template's version of an absent section instead. c. The same call plus that beforeHash, only on the user's yes to that one diff, returns applied, or a refused re-fetch instruction when the bytes changed since the preview. Never batch changes under one yes. Every refusal's instructions names the next step.

IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion: Do NOT present all categories at once. Walk the user through ONE category at a time using AskUserQuestion with Yes/Skip options. Stop after each question and wait for confirmation before calling with that category.

Categories: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide, readme, brain.

Upgrade surface (user code and user .aide specs are never touched):

• AIDE pointer stub in the agent config file

• Canonical methodology docs under .aide/docs/

• versions.json metadata under .aide/docs/

• Slash commands for all pipeline phases

• Pipeline agent files, skill templates

• MCP server entry in the project's MCP config

• IDE file association config (Zed settings, VS Code extension)

• The user-owned brain config, only through the brain category: missing sections and confirmed migrations, one consented change at a time

Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects the framework or accepts an override.

MCP step: the canonical aide entry runs the global command aidemd-mcp. The entry is read under the aide key, or under aidemd-mcp when there is no aide key; the key is never renamed. Without targetVersion, an entry that launches through npx reports differs with globalSwitch: { key, name, installed, installCommand } and no prescription. Tell the user npx launches time out at session start and ask; on yes, run installCommand via Bash first unless installed is true (a failed install: say so and stop). Then category: "mcp" makes the tool rewrite only that entry's command and args to the global command, every other byte unchanged; it re-checks the global install and, while the package is missing, keeps differs and returns instructions naming the install command — install, then call again. A missing aide entry returns the global prescription plus globalPackage; when the package is not installed it also carries instructions — act on them: install first, then merge, and never merge after a failed install. An older server cannot switch itself, so a pinned project first moves its pin to a newer version with targetVersion (only under the aide key; an npx entry under aidemd-mcp gets instructions to call without targetVersion and switch instead) — an exact published x.y.z, normally aide_info's behind.latest, valid only with no category or with category: "mcp". With it, a local (npx) aide entry is judged by its version pin alone: an older, missing or non-exact pin reports differs with pinMove: { from, to } (from is null when unpinned) and no prescription; a pin at or ahead of the target matches and is never moved back. Install the target first (npx -y @aidemd-mcp/server@{to} sync --help prints help starting Usage: and exits 2 by design; anything else means the install failed — then stop and move nothing). Then category: "mcp" with the same targetVersion makes the tool write the move itself, changing only the version inside the package argument — the command form, cmd /c, -y, other servers, formatting and line endings stay byte-identical — and returns status: "updated" with pinMove. A result that keeps status: "differs" with instructions means nothing was written (the pin changed since it was checked, the config cannot be edited byte-safely, or the entry is not a locatable @aidemd-mcp/server spec): relay the instructions. A global entry is never moved; the target is ignored for it. A moved pin takes effect only in a new session — tell the user to start one. An aidemd-mcp entry matches as the bare command or an absolute-path shim of it; a path-launched one may carry tip, an informational remark to mention once — never drift, never a merge question. Any other (custom) command under the aide key is left alone and reports matches. The brain entry is not part of the mcp step; a legacy brain launcher is changed only through the brain category's brainChange: "launcher" preview and apply, on the user's yes.