server

AIDE — Autonomous Intent-Driven Engineering

This project uses the AIDE methodology. AIDE treats a short .aide intent spec living next to orchestrator code as the contract every downstream agent (architect, implementor, QA) works from — when the intent changes, the code changes.

The full canonical methodology is installed in this project at .aide/docs/. Start at .aide/docs/index.md for the doc list, then crawl into the specific canonical doc your current task requires. Read only what the task actually needs — the doc directory is organized for progressive disclosure, not for front-loading.

Before writing, editing, or acting on any .aide file, crawl the doc directory and read the canonical doc that governs the work you are about to do. Never guess AIDE rules from memory: the files under .aide/docs/ are the authoritative source, and any decision that disagrees with them is wrong by definition.

AIDE tools quick-reference:

• aide_discover — map where .aide specs live in the project
• aide_read — read a specific .aide file with context
• aide_scaffold — create a new .aide file
• aide_validate — check spec layout for drift or issues
• aide_init — bootstrap AIDE into a new project (first-time setup)
• aide_upgrade — update/sync/refresh AIDE docs, commands, agents, and skills to the latest canonical versions (use this when asked to "update AIDE", "update the docs", or "sync the methodology")

Invoking /aide and /aide:*: when the user invokes any AIDE slash command, your first action must be to invoke the matching skill via the Skill tool — for /aide, that is Skill(skill="aide", args=...). The slash-command file at .claude/commands/aide.md is a thin signpost; the orchestrator prose and the MANDATORY BOOT SEQUENCE live in the aide skill (.claude/skills/aide/SKILL.md). Do NOT attempt to handle the request from the command file alone, do NOT skip the skill, and do NOT respond to the user's request before the boot sequence completes — skipping boot means orchestrating a methodology you don't know.

Publishing

This package publishes to npm and the MCP Registry (registry.modelcontextprotocol.io). A GitHub Actions workflow (.github/workflows/publish.yml) handles both automatically on v* tags.

To publish a new version:

node scripts/publish.mjs <patch|minor|major> [message]

This bumps package.json, syncs server.json, commits (e.g. 0.3.16: fix scoring tool), tags v0.3.16, and pushes — the CI does the rest (npm publish + MCP Registry publish).

Before publishing, check git status: the script's commit includes everything already staged, so stage nothing but what the release should ship. Then move the changelog's ## [Unreleased] entries under the new version heading (see "Changelog" below) and stage that with the release.

Changelog

CHANGELOG.md at the repo root follows Keep a Changelog: newest version first, an ## [Unreleased] section on top, and the standard Added / Changed / Deprecated / Removed / Fixed / Security headings. It ships to every host project (install and upgrade copy it to .aide/docs/changelog.md), and the aide-upgrader agent reads it there to bring old projects up to date.

Keep it current as you work, unprompted. Whenever a change lands that a user of the package would notice (a tool, a behavior, an agent, a command, a skill, a doc), add a bullet under ## [Unreleased] in the same piece of work. Don't batch them up for release time.

Any change to an AIDE file format needs a [migration] entry. A format change is anything that makes an existing host file out of date: a frontmatter field renamed, added or given new values, a section required or retired, a file moved or renamed. Start the bullet with [migration] (the upgrader reads only those bullets) and give it exactly three sub-bullets:

- [migration] Intent specs record `alignment` instead of `status`.
  - Detect: an intent spec with `status:` and no `alignment:`.
  - Migrate: rename the field, keeping the value; a spec with neither gets `unreviewed`.
  - Confirm: once, as a batch.

• Detect: how to recognize a file still on the old form, checkable from the file alone.
• Migrate: what the new form is, and which tool writes it (never a hand edit where an AIDE tool owns the field).
• Confirm: once, as a batch for mechanical changes, or per file when the right value needs the user's judgment. Name the evidence the upgrader should offer (checkboxes, git history).

Write the entry so it is safe to apply twice: a file already on the new form must not match Detect. A release with a format change and no [migration] entry is not shippable, because projects that upgrade would be left on the old form with nothing telling the upgrader to fix it.

After every publish, keep the aidemd.dev site in sync — the agent does this every time, unprompted. The publish always comes first and must succeed. Then:

1. Update the globally installed server: npm i -g @aidemd-mcp/server@<version> (the site runs aide from the global install).
2. Run a headless Claude session from inside the site's checkout (claude -p) that calls aide_info (expecting the new version), applies every drifted package-owned category with aide_upgrade — never mcp or brain — then commits chore(aide): sync methodology to <version> and pushes to main. Limit its --allowedTools to aide_info, aide_upgrade, read tools and git status/add/commit/push/diff/log.
3. The push deploys the site (GitHub Pages workflow). Confirm the deploy run succeeds.
4. If the headless run reports brainMigration, tell the user — /aide:brain config needs their consent and is not run headless.

Never hand-edit the site's files from this repo's session and never copy files from this repo's local build — the files come from the published package through the site's own aide tools. The site's checkout location and the exact command live in the maintainer's private notes, not here.

Fixes Go in Canonical Docs, Not Memory

This project ships agent definitions (.claude/agents/), command prompts (.claude/commands/), and methodology docs (.aide/docs/) that get installed into other projects. When you discover a behavioral fix, pattern, or constraint that should apply to all agents or all projects using AIDE:

• Write it into the canonical source — the agent definition, command prompt, or methodology doc that governs the behavior.
• Do NOT save it as a feedback memory. Memory is private to this machine. Canonical docs ship with the package and apply everywhere.

The test: "Will other projects benefit from this fix?" If yes → canonical doc. If it's purely about how this user wants to interact → memory.

AIDE First: Never Change a Shipped Copy Directly

Some of what AIDE ships also lives outside this repo: the brain's seeded notes (the kanban index and guides, the playbook and research indexes, written from the bundled brain template), the user's global copies of the kanban skill and kanban-maintainer agent, and every host project's installed .claude/ and .aide/docs/ files. A change to any of them starts here, never in the copy.

1. Change the canonical source in this repo first: the bundled brain template section (append its old fingerprint to the outdated-sections record and update the drift pin), the .claude/ file, or the .aide/docs/ doc.
2. Log it in CHANGELOG.md under ## [Unreleased], with a [migration] entry when an existing file goes out of date, so the upgrader can bring every project and brain up to date.
3. Only then update the copies, through the tools that own them: /aide:upgrade and /aide:brain config for host files and brain configs, and a byte-for-byte copy of the canonical file for the global skill and agent.

If a copy has to change first, because the user needs the fix right away, make the same change here in the same piece of work and log it before the turn ends. A rule that lives only in the brain, a global skill or one host project is drift: the next install or upgrade erases it, and no other project gets it.

Local .mcp.json for the aide Server

This repo IS the @aidemd-mcp/server package. That breaks the obvious-looking npx form in local dev.

Do NOT use npx @aidemd-mcp/server as the aide server's launch command in this repo's .mcp.json. When npm exec runs from inside the package's own source directory, it sees the local package.json (whose name matches), treats the package as "already installed locally," skips the install step, and tries to invoke a bin from ./node_modules/.bin/ — which doesn't exist because THIS project IS the package. The failure surfaces as 'aidemd-mcp' is not recognized as an internal or external command, which looks like a Windows PATH or scoped-package bin bug but isn't. It's an npm-exec-from-source-dir bug that only manifests in this one repo. Consumer projects running the same npx form work fine.

Two working forms for this repo's .mcp.json:

// Option A — dev form, runs the local build
"aide": { "command": "node", "args": ["./dist/index.js"] }

// Option B — pulls from npm; cwd MUST be outside the project root
"aide": {
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@aidemd-mcp/server@latest"],
  "cwd": "C:\\Users\\<you>"
}

If aide MCP fails to register on this repo, check .mcp.json matches one of the two forms above before debugging anything else.

Don't Run the Pipeline on the Agent Harness

This repo's primary work is editing .claude/agents/, .claude/commands/, and .claude/skills/ — those ARE the canonical agent definitions, command prompts, and skill prompts that ship to host projects via aide_init. They are the runtime of the AIDE pipeline; running the pipeline against them is a circular dependency.

Do NOT spawn /aide (spec → research → synthesize → plan → build → QA → fix) on .claude/ files. No per-agent or per-command .aide specs (e.g., .claude/commands/aide/aide.aide). When agent, command, or skill behavior needs to change, edit the canonical file directly.

"Directly" means the main agent makes the edit, not a subagent — the /aide skill's "Edit prose" rule.

Prose never goes through the pipeline — ever. That covers agent instructions under .claude/, the methodology docs under .aide/docs/, README.md, and wording-only changes to user-facing text such as CLI help strings. No plan, no build, no QA: the main agent edits them directly. Only code that changes behavior goes through the pipeline. .aide specs (.aide/intent.aide, module specs) still go through their writer agents, and .aide/config/brain.aide changes go through /aide:brain config.

Kanban

Kanban project tag: aidemd-mcp