Scan for .aide spec files in this project. Returns a tree map of where specs live, following progressive disclosure.

Without a path: returns a lightweight project-wide map — file locations, type tags and each spec's one-line description; a plan or todo tag carries its status, e.g. [plan: approved]. Only the head of each file is read. Use this once to understand the project's spec architecture.

With a path: the response opens with the ancestor chain — the cascading intent lineage from project root down to the target directory, with each ancestor showing its description and alignment status (aligned/misaligned when set). The ancestor chain gives you the full inherited context before you read a single spec body. After the ancestor chain comes the detailed subtree of the target directory — summaries extracted from file content and anomaly warnings. Use this to drill into the area you're working on.

.aide files are progressive disclosure specs that live next to orchestrator code — they contain intent (strategy, implementation contracts, anti-patterns), research (sources, data, patterns), or QA checklists (todo). Read .aide files BEFORE reading code — they are the context layer between folder structure and implementation details.

File types (.aide, intent.aide, research.aide, plan.aide, todo.aide):

• .aide — Intent spec (default). Strategy, contracts, anti-patterns.

• intent.aide — Same as .aide, used only when research.aide exists in the same folder.

• research.aide — Raw research. Sources, data points, pattern synthesis.

• plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor.

• todo.aide — QA re-alignment document. Captures where implementation drifted from intent.

Never have both .aide and intent.aide in the same folder.

Read an .aide spec file with full context. Returns the file content, its classified type (intent/research/plan/todo), related specs in the same directory, and links found in the content (relative paths, inline references, URLs). Use this after aide_discover to drill into a specific spec.

Create a new AIDE working file from its blank template, under its canonical name. It never overwrites: a request for a file that already exists, filled or empty, is a no-op reported as a skip line — remove a file first with aide_cleanup to replace it. New files start with their starting value: an intent spec alignment: unreviewed, a plan or todo list status: proposed. Handles the naming rules, so never pick a name yourself: in a module folder, intent specs are .aide by default, but become intent.aide when research.aide exists in the same folder. Creating a research.aide auto-renames any existing .aide to intent.aide. The project root intent spec always lands at .aide/intent.aide: pass directory ".aide" or "." (both mean the project's .aide folder for intent, research and both). A bare .aide/.aide left by an older project, with no intent.aide beside it, is renamed to .aide/intent.aide with its content kept; if .aide/intent.aide exists, nothing changes. Folders are never treated as spec files. A plan needs an intent spec beside it: scaffolding a plan in a folder with no intent spec (.aide or intent.aide; a research.aide alone does not count) is refused and creates nothing — write the folder's intent spec first. For a root-level plan, pass directory ".aide".

Types:

• intent — Strategy, contracts, anti-patterns

• research — Sources, data, patterns (triggers rename of existing .aide)

• both — Creates research.aide + intent.aide pair

• todo — QA re-alignment document for QA agents

• plan — Architect's implementation plan; refused unless the folder already holds an intent spec

• session — The project's session record, always at .aide/session.aide whatever directory you pass: the empty placeholder with every section heading. Its single source; never write the placeholder by hand.

Remove a module's pipeline ephemerals (plan.aide, todo.aide, brief.aide) once that module's cycle has closed, leaving the code and the intent specs as the durable record. It never removes, rewrites or reads anything else: intent specs, research specs, code, and .aide/session.aide are all out of reach.

Each file it would remove must record a closed status: completed (re-checked — every checkbox really checked) or abandoned. A file from before statuses existed, with no status but every checkbox checked, also passes. It refuses anything still proposed or approved, a completed file with an open item, a brief.aide with no plan.aide beside it, and a folder with no ephemerals. An abandoned plan takes its brief with it, and where there is no plan.aide a closed todo.aide is removed on its own. A refusal names each open file or item with its file and line, and nothing is removed. Record a closing status with aide_frontmatter first; this tool never sets or infers one.

Call it directly, because the real call is already safe. dryRun is an optional preview for inspection only and is never a required step before the real call.

This is the cross-platform replacement for a shell delete, so it can be permitted by name.

Read or change one governed frontmatter value of an AIDE file, leaving every other byte untouched. Intent specs carry alignment (unreviewed, aligned, misaligned). plan.aide, brief.aide and todo.aide carry one status lifecycle: proposed, approved, completed, abandoned. Only allowed moves are accepted, completed is refused while any item is unchecked or, for a brief, until its plan is completed, and a refusal names the allowed next values. Call with path alone to read a file's governed value without changing it. The session record, research specs and brain.aide carry no governed values. The tool never chooses a value; the caller decides.

Health check for .aide spec files in the project. Detects orphaned specs (a spec whose folder, subfolders included, holds no code — only AIDE files, Markdown and dot-files; the project root intent spec in .aide/ is never orphaned, and a plan's presence never decides it), plans with no intent spec beside them (plan-without-spec — write the folder's spec, never delete the plan), missing specs (orchestrators with 3+ helper imports but no .aide), naming conflicts (.aide + intent.aide in same folder), broken links, orphaned research (research.aide without intent spec), missing descriptions (specs with no description field in frontmatter), files whose frontmatter cannot be parsed, and intent specs whose alignment is missing (missing-alignment) or not one of unreviewed, aligned, misaligned (invalid-alignment).

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.

Boot-time reporter called by the orchestrator at startup. Returns independent top-level fields that the orchestrator must branch on separately:

outdated (array of stale artifact keys) — soft notification. Compares the host's .aide/versions.json against the canonical manifest shipped with this running server — never against the latest published version, so files that match the version the project runs are current even when a newer release exists. Each element names an artifact key that is behind. An empty array means everything is current. A missing .aide/versions.json (old install predating version tracking) silently collapses to []. Staleness is informational — the orchestrator continues with a heads-up to the user.

behind ({ installed, latest, launch, versionsBehind, highlights } or null) — soft notification. Non-null when the running server is older than the latest published version, whatever launch the project's aide entry uses — a global install or npx, pinned or not. installed is the running server's version. launch (global or local) picks the remedy: global → npm i -g @aidemd-mcp/server@{latest}; local → first install latest into the npx cache, then move the project's aide pin to it with aide_upgrade({ category: "mcp", targetVersion: latest }), never a hand edit of .mcp.json; if the install fails, switch nothing; once the newer server runs, /aide:upgrade offers to switch the entry to the global command. versionsBehind (1 or more) counts the published releases after installed up to latest; highlights holds 0–3 one-line notes of what they added or fixed (empty when the release notes were unavailable). Show the count and highlights briefly, never the changelog. Either upgrade takes effect only in a new session. It never gates the pipeline. Null when there is no aide entry, the running version is unknown, the server is current, or the version check could not run (offline checks pass silently).

brainMigration ({ staleSections, legacyLauncher } or null) — soft notification. Non-null when the brain config has sections whose text matches an earlier template version, or a legacy brain launcher (legacyLauncher lists the reasons: npx-launch, unpinned, unversioned, older-pin, missing-auto-confirm). Mention it once and suggest /aide:brain config; it never gates the pipeline and never changes brain.status.

brain (precondition state) — hard gate. Reports whether the host's brain MCP entry is wired and consistent. Shape: { status, name?, fault?, hints } — name is absent on no-brain-aide and brain-aide-invalid; fault is present only on brain-aide-invalid. The orchestrator must halt and direct the user to resolve the issue before continuing if status is not 'ok'. No path validation is performed — the package never stats any directory on disk; state derives entirely from comparing .aide/config/brain.aide against .mcp.json.

The five brain.status values:

• ok — .aide/config/brain.aide exists, satisfies the required-section contract, and the host's .mcp.json brain entry matches the parsed mcpServerConfig. name is the user-declared descriptive label from brain.aide. The pipeline may proceed.

• no-brain-aide — .aide/config/brain.aide is absent. No name field. Remediation: run /aide:brain config, which creates the config.

• brain-aide-invalid — the file exists but falls short. fault.kind is missing-sections (with fault.sections naming each missing required section) or malformed (with fault.reason). No name field. Remediation: run /aide:brain config.

• no-mcp-entry — brain.aide parsed successfully but the host's .mcp.json is absent, malformed, or has no mcpServers.brain key. name is present. Remediation: run sync with the same launcher the project's aide MCP entry uses — aidemd-mcp sync when the project's aide MCP entry runs the globally installed aidemd-mcp, or npx -y @aidemd-mcp/server@<version> sync with the version that entry pins when it runs through npx.

• mcp-drift — brain.aide and .mcp.json both exist but their brain entries disagree on command or args. name is present. Remediation: run sync with the same launcher the project's aide MCP entry uses — aidemd-mcp sync when the project's aide MCP entry runs the globally installed aidemd-mcp, or npx -y @aidemd-mcp/server@<version> sync with the version that entry pins when it runs through npx.

hints is always present on every status — an array of candidate brain root paths the orchestrator can surface during recovery.

No parameters needed — uses the server's working directory.

On-demand brain entry-point tool. Call this when you need to reach the brain mid-task — do NOT call it on every /aide boot. Boot-time brain precondition state is already reported by aide_info.brain.status; firing aide_brain at boot duplicates that work unnecessarily. It is also how a brain config is set up, repaired or written for any backend, one decision at a time. Every mode is read-only: no call writes to disk.

Optional source parameter — which read runs. Omitted means "host".

• "host" — one section of the host's .aide/config/brain.aide, described below.

• "template" — { template, purpose }: one section of the bundled template (or its launcher, with kind: "launcher") as verbatim bytes, and that section's one-line purpose from the published contract. The answer is the same whatever state the host's config is in. Use it as a worked example when writing that section for another backend.

• "contract" — { sections }: every contract section in order, each with marker, role (live or seed) and purpose, and no section text.

• "draft" — a structural check of the draft config at path, with the same rules and fault vocabulary as the host config check, so a draft that passes is ready to swap in. Returns { outcome, instructions }: valid; invalid with fault (missing-sections and its sections, or malformed and its reason); absent when no file is at path; refused when path is outside the project, and nothing is read. It checks structure, never content.

Optional kind parameter — host and template reads only: any section marker of the published brain contract (see the enum), live or seed; "launcher" only with source: "template". Omitting it means "orientation", the runtime briefing for reaching the brain mid-task. "config" is the integration's wiring flow that /aide:brain config runs. Seed sections are fetched one per call while seeding. path is required with source: "draft" and accepted nowhere else; any other combination is rejected before the tool runs.

Host read response shape: exactly { status, instructions, found, purpose? }. No backend, no connector, no name, no kind.

• found: true — instructions is that section's verbatim bytes from the host's .aide/config/brain.aide: no trimming, no normalization, no ${...} substitution. purpose is that section's one-line purpose from the published contract; use it when adapting the section for another backend.

• found: false — instructions is remediation, and purpose is absent. An absent file → run /aide:brain config. A requested section missing from the file → with the user's consent, call aide_upgrade with category: "brain". A malformed or unreadable file → the exact fault, a hand fix with the user, then re-check with aide_info. Do not proceed as if the section were available.

The section is returned on every status where the config exists and is well-formed, including brain-aide-invalid with missing sections, no-mcp-entry and mcp-drift.

status mirrors the BrainState tagged union from buildBrainState, with five values: ok, no-brain-aide, brain-aide-invalid, no-mcp-entry, mcp-drift. Branch on found for "did I get the section" and on status for "is the brain healthy".

Bootstrap the AIDE development environment into a project. Returns structured JSON for agent consumption — not prose.

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

First call (no category param): Returns a lightweight summary — every step with name, status (would-create/would-overwrite/would-skip/exists), category, and filePath, but NO content fields. Also returns brainHints (brain root candidates) and detected framework. Use this to understand what needs to be done and which categories require user prompts.

Second call (with category param): The tool writes all would-create AND approved would-overwrite files directly to disk itself and returns a manifest — steps with filePath, status (created, overwritten, or exists), and name, but NO content. would-skip steps stay would-skip in the manifest (tool writes nothing for them). The agent never sees file content and never uses the Write tool for new files.

Exception — MCP steps: For MCP steps, the manifest includes prescription data (key name and entry object) so the agent can read the existing config, merge, and write. The tool never touches MCP config directly.

Exception — brain category: The Brain config (brain.aide) step carries brainSummary on every call, including the summary: sections (each section's marker, role, seedPath for seeds, and templateBytes), missingSections, staleSections, legacyLauncher reasons and templateIntegration. It never carries section text, purposes, repair blocks or before/after bodies. Missing sections are inserted with aide_upgrade category: "brain", seeds are read one at a time with aide_brain, and migrations are previewed and applied one at a time through aide_upgrade. Sections the user edited and custom launchers are never offered. The tool creates .aide/config/brain.aide when it is absent and never overwrites an existing one.

Exception — session record: The Session record (session.aide) step never carries content and the tool never writes it. When it is would-create, its instructions tell you to call aide_scaffold with directory "." and type "session" — do that, unprompted. When .aide/session.aide exists it is exists and is never overwritten.

Exception — IDE VS Code steps: IDE steps that need external tooling (VS Code CLI) return instructions for the agent to execute, since those aren't simple file writes.

Agent branch logic — silent-on-create, prompt-on-overwrite:

After the first call, walk the categories using this rule:

• Pure-create category (all steps are would-create, would-skip, or exists): apply silently by calling with category=X immediately — no AskUserQuestion. A category with nothing on disk to overwrite has no decision the user can inform.

• Overwrite-bearing category (any step is would-overwrite): pause and use AskUserQuestion with structured options. Name the files that would be overwritten. If the user approves, call with category=X — the tool overwrites and returns overwritten in the manifest. If the user declines an overwrite but wants the new files, call with category=X — the tool writes only would-create steps; the would-overwrite step stays would-overwrite in the manifest.

• Inherent-decision categories (framework, brain root path, MCP config merge, IDE choice): always use AskUserQuestion regardless of disk state. These are not file-write decisions — filesystem contents cannot resolve them.

IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion: Do NOT present a summary table of all categories. Do NOT offer "all" as an option. Do NOT ask conversational questions — use the AskUserQuestion tool with structured options at every pause point.

1. Call without category first to get the metadata

2. Present ONLY the detected framework — use AskUserQuestion with Yes/{alternatives} options. STOP.

3. Walk categories in order: methodology, commands, agents, skills, mcp, brain, ide, readme. For each:

   • Pure-create: apply silently (call with category=X), report results, move to next.

   • Overwrite-bearing: use AskUserQuestion naming the would-overwrite files. STOP. Wait for selection, then call with category=X. Report manifest (created N, overwrote M). Move to next.

   • Inherent decision: always use AskUserQuestion. STOP.

4. For brain: read brainSummary from the step, then direct the user to /aide:brain config. Call with category=brain only to receive the manifest; the tool creates .aide/config/brain.aide only when absent and never overwrites an existing one.

5. For MCP: when the aide step is would-create, its globalPackage names the aide server's global package. If installed is false, the step also carries instructions: act on them before merging — run its installCommand via Bash first — running AIDE's setup is the consent. If the install fails, tell the user plainly and stop: never merge an entry whose command is not installed. Then use AskUserQuestion with Merge/Skip and merge the prescription entry (the global aidemd-mcp command) into the existing config yourself (read → merge → write). Never replace an existing aide entry. STOP.

6. For IDE: use AskUserQuestion with multiSelect for Zed/VS Code/Neither. STOP.

Each pause point is ONE AskUserQuestion → wait for selection → then proceed. Never show multiple categories at once. Never ask open-ended conversational questions.

Return JSDoc, signature, and kind for a named symbol without opening the full file — Tier 2 progressive disclosure for code. When an agent knows a function name from an import list or orchestrator file, call inspect to learn what the symbol does, what it accepts, and what it returns, based on its contract alone. Searches across TypeScript and JavaScript source files (ts, tsx, js, jsx, mjs, cjs). Use the optional file parameter to narrow the search to a single file when the location is already known.