aide-brain-author — Write a Brain Config for Any Backend

The brain config tells every AIDE agent how to reach the project's brain: the launcher that starts the brain's MCP server, and a fixed set of contract sections, each with a published purpose. The bundled template fills them for its own default backend. This skill writes them for the user's backend instead.

Every section list, role, purpose and template text comes from aide_brain. Never write a section list or a purpose from memory, and never copy one from another config.

Hard constraints

• Structure is checked; content is the user's. The draft check confirms every required field and section is present and well-formed. Whether the prose works for the backend is the user's call. Confirm each section with the user before moving on.
• One section at a time. Read one section, write it with the user, confirm, then read the next. Never fetch the whole template up front.
• Draft first when writing a whole config. Write the new config to .aide/config/brain.aide.draft. The live config at .aide/config/brain.aide changes only at the swap step, and only on the user's yes. The one exception is adding missing sections (below), which edits the live config in place because the user already chose to repair it.
• Never invent backend tool names. Ask the user how their backend's MCP server is launched and which tools it exposes, or read its documentation with them. If they don't know yet, leave a clearly marked TODO in that section and tell them.

The tool calls

aide_brain is read-only in every mode below. None of them reads or depends on the project's current brain config.

• aide_brain({ source: "contract" }) returns { sections }: every contract section in order, each with its marker, role (live or seed) and purpose, and no text.
• aide_brain({ source: "template", kind: "launcher" }) returns { template, purpose }: the bundled template's frontmatter lines (between the two --- fences) and what the launcher must do.
• aide_brain({ source: "template", kind: <marker> }) returns { template, purpose }: the bundled template's text for that one section and what the section must do.
• aide_brain({ source: "draft", path: ".aide/config/brain.aide.draft" }) returns { outcome, instructions }. outcome is valid, invalid (with a fault: missing-sections naming the sections, or malformed with a reason), absent, or refused (the path is outside the project). It uses the same rules and fault wording as the live config check, so a valid draft is structurally ready to swap in.

Steps

1. Ask about the backend

Use AskUserQuestion:

1. Which backend holds the brain, and how its MCP server is launched (package or command, and the argument that points it at the brain's location).
2. The launch mode, with these two options exactly as worded:
   • Global (recommended) — personal machine, reliable startup; stays on its installed version; one-time npm i -g.
   • Local — shared repos, cloud/CI; pinned to one version that /aide:brain config moves forward; flaky cold start.

2. Check for an existing config

Call aide_info and read brain.status.

• no-brain-aide: there is no config. The draft becomes the config at the end.
• Any other status: a config exists. Ask with AskUserQuestion:
  • Replace it. Write the draft, then swap it in at step 7. The current file is kept as .aide/config/brain.aide.bak.
  • Write it beside. Write the draft and stop at step 7, leaving .aide/config/brain.aide.draft for the user to swap in later.

If .aide/config/brain.aide.draft already exists, ask whether to overwrite it or stop.

3. Read the contract

Call aide_brain({ source: "contract" }). Its sections are the work list, in order. Show the user how many sections there are and which are live and which are seed:

• Live sections are read at runtime by agents and by /aide:brain config: how to reach the brain, and how to wire it.
• Seed sections are written into the brain once, at their seed paths, the first time it is wired: the playbook, research and kanban guides the agents rely on.

4. Write the launcher

Call aide_brain({ source: "template", kind: "launcher" }). Show the user the purpose and the template's frontmatter, then write the draft's frontmatter for their backend:

• name: a short descriptive label for the brain.
• mcpServerConfig: command and args that start the backend's MCP server. Leave YAML null at the one args slot the brain's location fills; /aide:brain config fills it during wiring.
  • Global mode: the command is the backend's bare command name, never an absolute path. Run the backend's global-install check (for an npm package, npm ls -g <package> --depth=0). If it is missing, offer npm i -g <package> and run it only on the user's yes.
  • On a decline or a failed install, write the pinned local form instead (npx -y <package>@<version>, through cmd /c on Windows) and tell the user.
  • Local mode: write the pinned local form directly.
• Add no other frontmatter field. The parser rejects extra fields.

Write the draft file with the frontmatter between its two --- fences.

5. Write each section

For each section from step 3, in order:

1. Call aide_brain({ source: "template", kind: <marker> }).
2. Show the user the marker, the purpose and the template text. The template is a worked example for the bundled backend: its tool names, link syntax, file formats and board layout belong to that backend and do not carry over.
3. Write the section with the user so it fulfills its purpose on their backend: their tool names, entry points, link syntax, frontmatter and task format. For a seed section, also keep the structure the template's prose gives agents (the steps, the rules, what to read first), translated to the backend.
4. Confirm with the user, then append it to the draft between its two marker lines, <!-- aide-<marker>-start --> and <!-- aide-<marker>-end --> with the section's real marker name. Leave one blank line between sections.

6. Check the draft

Call aide_brain({ source: "draft", path: ".aide/config/brain.aide.draft" }).

• valid: go to step 7.
• invalid: show the fault and instructions, fix exactly what it names with the user, and check again.
• absent or refused: show instructions and fix the path.

7. Swap in or leave beside

• No config existed: rename .aide/config/brain.aide.draft to .aide/config/brain.aide.
• Replace: on the user's yes, rename the current .aide/config/brain.aide to .aide/config/brain.aide.bak, then rename the draft into its place.
• Beside: stop. Tell the user where the draft is, and that swapping it in means renaming it to .aide/config/brain.aide and then running /aide:brain config.

After a swap, call aide_info and confirm brain.status is no longer no-brain-aide or brain-aide-invalid. If /aide:brain config handed off here, return to it; it continues with validation and wiring. Otherwise tell the user to run /aide:brain config: it wires the brain location into the launcher, syncs .mcp.json and writes the seed sections into the brain.

Adding missing sections to an existing config

/aide:brain config hands off here when a config written for another backend is missing contract sections (the upgrade tool answered adapt with the missing markers). This mode only adds those sections. It edits the live .aide/config/brain.aide in place, because the user already chose to repair it, and changes no other byte.

For each missing marker, one at a time:

1. Call aide_brain({ source: "template", kind: <marker> }) and write the section with the user, as in step 5. Use the existing sections of their config as the guide to their backend's tool names and conventions.
2. Insert it with its two marker lines right after the end marker of the section that comes before it in contract order (from aide_brain({ source: "contract" })). Leave one blank line between sections and keep the file's line endings.

Then call aide_info and confirm brain.status is not brain-aide-invalid, and return to /aide:brain config.

Anti-patterns

• Listing, restating or inventing the contract's sections or purposes instead of reading them from aide_brain.
• When writing a whole config, editing .aide/config/brain.aide before the draft checks valid and the user says yes.
• Copying the template's tool names, link syntax or board format into a section for another backend.
• Writing several sections before the user confirms the first.
• Running sync or seeding the brain yourself. /aide:brain config owns wiring and seeding.