@aidemd-mcp/server 0.2.0

package/.claude/.aide

@@ -0,0 +1,246 @@
+---
+scope: .claude
+status: aligned
+description: AIDE harness — agents, commands, skills, and methodology docs that drive the intent pipeline
+intent: >
+  The AIDE harness gains cascading alignment — the ability for agents to verify
+  that every spec in a tree honors the intent of its ancestors, and for drift
+  to be detected, flagged, and repaired without blocking the pipeline. A new
+  aide-aligner agent walks the spec tree top-down comparing each spec's
+  outcomes against its ancestors' outcomes, producing realignment items where
+  drift is found. The /aide:align command invokes this agent. Existing agent
+  definitions are simplified by removing verbose tree-walking instructions —
+  the enhanced discover tool's ancestor chain output teaches the protocol
+  directly, so agents learn by calling the tool, not by reading paragraphs
+  of instruction. A new methodology doc captures the cascading alignment
+  protocol as canonical doctrine.
+outcomes:
+  desired:
+    - An aide-aligner agent exists, distinct from the QA agent, whose sole
+      job is spec-vs-spec alignment — comparing a child spec's outcomes
+      against every ancestor's outcomes to detect intent drift. QA checks
+      code-vs-spec; the aligner checks spec-vs-spec.
+    - The aligner walks the tree top-down using the discover tool's ancestor
+      chain, compares outcomes at each level, and produces a todo.aide at
+      each misaligned node listing concrete realignment items.
+    - The aligner sets status: misaligned on specs where it finds drift and
+      status: aligned on specs it has verified. It is the only agent that
+      can confirm alignment through a deliberate full-tree walk.
+    - The QA agent can set status: misaligned incidentally while reviewing
+      code-vs-spec, but cannot set aligned — only the aligner confirms
+      alignment.
+    - A /aide:align command exists that invokes the aligner agent, callable
+      by the user or suggestable by the orchestrator when drift is suspected.
+    - Agent definitions across the harness no longer contain verbose
+      tree-walking instructions. Agents call discover, the tool's output
+      teaches the protocol, and agents report misalignment flags they
+      encounter. If an agent needs paragraphs of instruction to use
+      discover correctly, that is a discover design failure, not an agent
+      instruction gap.
+    - A cascading-alignment.md methodology doc exists under .aide/docs/
+      documenting the protocol, the status field semantics, the aligner's
+      role, and how misalignment flows through the pipeline.
+  undesired:
+    - The aligner conflated with the QA agent. QA validates code against
+      spec outcomes; the aligner validates spec outcomes against ancestor
+      spec outcomes. Merging them produces an agent that does neither job
+      well and confuses which contract it is checking.
+    - Misalignment that blocks the pipeline. The status flag is
+      informational — it surfaces drift for human or agent judgment, not
+      a gate that stops work. A team may intentionally diverge a child
+      from its parent; blocking would make that impossible.
+    - Agent definitions that duplicate the discover tool's teaching by
+      including multi-paragraph instructions on how to walk the intent
+      tree. If agents need those instructions, the tool's description
+      and output are not doing their job — fix the tool, not the agents.
+    - An aligner that modifies spec intent or outcomes directly. The
+      aligner detects and flags; it does not rewrite. Realignment items
+      go into todo.aide for a human or spec-writer to resolve.
+    - A cascading-alignment doc that describes aspirational behavior the
+      tooling does not actually support. The doc must describe what the
+      discover tool, validate tool, and aligner agent actually do, not
+      what they might do someday.
+---
+
+## Context
+
+The AIDE pipeline has agents that read specs, agents that write code, and
+agents that validate results — but no agent whose job is to verify that
+the specs themselves are internally consistent across the tree. A child
+spec can contradict its parent's outcomes and no one catches it until QA
+fails in a confusing way, or worse, the implementation faithfully serves
+a child intent that violates the root intent. This is the cascading
+alignment problem: intent trees grow, specs multiply, and drift between
+levels accumulates silently.
+
+The existing agents each contain a "walk the intent tree" instruction
+telling them to call discover and consider ancestor outcomes. These
+instructions are short (one line each) but they represent duplicated
+responsibility — every agent is told to watch for alignment, yet none
+of them owns it. The result is diffuse accountability: alignment is
+everyone's side job and no one's primary job.
+
+The harness also lacks a canonical doc explaining how alignment works,
+what the status field means, and how misalignment flows through the
+pipeline. Without that doc, every new agent or contributor re-derives
+the protocol from scattered instructions across six agent definitions.
+
+## Strategy
+
+**Separate spec-vs-spec from code-vs-spec.** The aligner agent checks
+one thing: does a child spec's outcomes contradict or undermine any
+ancestor's outcomes? QA checks a different thing: does the implementation
+satisfy the spec's outcomes? These are different contracts requiring
+different verification strategies. Merging them into one agent forces
+the agent to context-switch between reading code and reading specs,
+and makes it unclear which contract a finding refers to. The aligner
+owns alignment; QA owns conformance. Each agent's findings are
+unambiguous because each agent checks exactly one relationship.
+(Traces to: desired #1, undesired #1)
+
+**Walk top-down, flag at the leaf.** The aligner uses discover's
+ancestor chain to walk from root to the target spec, comparing
+outcomes at each level. When drift is found, the misalignment flag
+goes on the leaf that deviated, not the ancestor that set the rule.
+This preserves the ancestor as the source of truth and makes it
+clear which spec needs revision. The aligner produces a todo.aide at
+each misaligned node with concrete realignment items — what
+specifically conflicts and which ancestor outcome it violates. It
+never rewrites the spec's intent or outcomes directly; that is the
+spec-writer's job, informed by the todo.aide.
+(Traces to: desired #2, undesired #4)
+
+**Status is informational, not a gate.** The status field has three
+states: pending (implicit default, no field needed), aligned (set by
+the aligner after a deliberate full-tree walk), and misaligned (set
+by the aligner when drift is found, or by QA incidentally). The
+aligner is the only agent that can confirm alignment — setting
+aligned requires a deliberate full-tree walk, not an incidental
+observation. QA can set misaligned when it notices spec-level
+contradictions during code review, but it cannot confirm alignment
+because it never performs a full tree walk. Misalignment is
+non-blocking: it surfaces drift for human judgment without stopping
+the pipeline. A team may intentionally diverge a child from its
+parent; a blocking gate would make that impossible.
+(Traces to: desired #3, desired #4, undesired #2)
+
+**The /aide:align command is user-invoked, not automatic.** Alignment
+checking is expensive — it walks the full tree and compares outcomes at
+every level. Running it automatically on every spec change would slow
+the pipeline and produce noise during active development when specs are
+still being drafted. Instead, the orchestrator can suggest running
+/aide:align when discover output shows misalignment flags or when a
+spec edit touches outcomes, but the user decides when to invoke it.
+(Traces to: desired #5)
+
+**Agents learn discover by calling it, not by reading instructions
+about it.** The current agent definitions each contain a one-line
+"walk the intent tree" instruction. While these are not the
+multi-paragraph instructions the spec warns against, they represent
+duplicated responsibility that belongs in the tool, not in six agent
+files. The discover tool's enhanced output — ancestor chain with
+descriptions, misalignment flags — should teach the protocol directly.
+Agents should still report misalignment flags they encounter in
+discover output, but the instruction to do so should be minimal:
+acknowledge what discover tells you, not re-derive how to use it.
+If removing these instructions causes agents to misuse discover,
+that signals a discover output design problem to fix at the tool
+level.
+(Traces to: desired #6, undesired #3)
+
+**The methodology doc describes actual behavior.** The
+cascading-alignment.md doc under .aide/docs/ documents what the
+discover tool, validate tool, and aligner agent actually do — not
+what they might do someday. It covers the status field lifecycle,
+the aligner's role, how QA interacts with alignment, and how
+misalignment flows through the pipeline. If the doc names a
+capability the tooling does not support, the doc is wrong.
+(Traces to: desired #7, undesired #5)
+
+## Good examples
+
+The user runs /aide:align targeting a module three levels deep. The
+aligner calls discover, receives the ancestor chain: root spec,
+mid-level spec, leaf spec. It compares the leaf's outcomes against the
+mid-level's outcomes — no conflicts. It compares the leaf's outcomes
+against the root's outcomes — one desired outcome in the leaf
+contradicts an undesired outcome in the root. The aligner produces a
+todo.aide at the leaf with one item: "Leaf desired outcome #3 conflicts
+with root undesired outcome #2 — leaf says X should always happen, root
+says X is a failure mode." It sets the leaf's status to misaligned.
+The mid-level and root specs are untouched. The pipeline continues;
+nothing is blocked.
+
+QA is reviewing an implementation and notices that the spec it is
+validating against has an outcome that contradicts the parent spec's
+intent. QA sets status: misaligned on the leaf and notes the
+contradiction in its todo.aide under a "spec-gap" misalignment tag.
+QA does not attempt to resolve the contradiction or set anything to
+aligned — it finishes its code-vs-spec review and returns its verdict.
+The user later runs /aide:align to get a full alignment assessment.
+
+An agent calls discover on a module. The output includes the ancestor
+chain with a one-line description of each ancestor's intent. The agent
+reads this output and understands exactly where this module sits in the
+tree and what constraints it inherits — without any instruction in its
+agent definition telling it how to interpret discover's output. The
+tool's output was self-teaching.
+
+After the aligner confirms alignment across a subtree, a contributor
+adds a new child spec. Its status is implicitly pending — no status
+field in the frontmatter. The parent's status remains aligned because
+alignment was confirmed before the child existed. The next /aide:align
+run picks up the new child, compares it against ancestors, and either
+confirms it as aligned or flags it as misaligned. The parent's status
+is not retroactively changed by the child's addition.
+
+## Bad examples
+
+An aligner agent that reads a misaligned child spec and rewrites its
+outcomes to match the parent. The aligner's job is to detect and flag,
+not to resolve. The spec-writer resolves, informed by the todo.aide
+the aligner produced. An aligner that rewrites specs is an agent that
+makes intent decisions it was never authorized to make.
+
+A QA agent that runs a full tree walk and sets status: aligned on every
+spec it touches. QA's job is code-vs-spec. It encounters alignment
+issues incidentally — it can flag misaligned, but confirming alignment
+requires a deliberate full-tree walk that only the aligner performs.
+A QA agent setting aligned conflates the two contracts and gives false
+confidence that spec-vs-spec alignment was checked when it was not.
+
+An agent definition that contains three paragraphs explaining how to
+call discover, what the ancestor chain means, how to interpret
+misalignment flags, and when to escalate. If the agent needs this
+much instruction, discover's output is not doing its job. The fix is
+to improve discover's output format and descriptions, not to
+compensate with verbose agent instructions.
+
+A cascading-alignment.md doc that describes a "deep alignment mode"
+where the aligner recursively verifies every transitive descendant
+of a spec, but the aligner agent and discover tool have no such
+capability. The doc described aspirational behavior and will mislead
+every agent that reads it into expecting features that do not exist.
+
+Misalignment that blocks the pipeline: a status: misaligned flag on a
+spec causes the orchestrator to refuse to plan or build against it.
+A contributor who intentionally diverged a child spec from its parent
+for good reasons is now unable to proceed until they undo the
+divergence or get the aligner to approve it. The status field became
+a gate instead of an informational signal.
+
+An aligner that flags misalignment on the parent spec rather than
+the leaf. The root spec says "no X." A child spec says "always X."
+The aligner marks the root as misaligned. Now the root — which set
+the original rule — carries a flag suggesting it is the one that
+drifted. The flag belongs on the child that deviated from the
+ancestor's constraint.
+
+## References
+
+- `.aide/intent.aide` -- Root spec establishing that canonical docs must describe actual behavior, not aspirational behavior, and that cascading intent must flow faithfully from root to leaf.
+- `.claude/agents/aide/aide-qa.md` -- Current QA agent definition showing the one-line "walk the intent tree" instruction pattern and QA's code-vs-spec scope, which the aligner must not duplicate.
+- `.claude/agents/aide/aide-architect.md` -- Architect agent showing the same one-line tree-walking instruction pattern and how agents currently receive discover context.
+- `.claude/agents/aide/aide-implementor.md` -- Implementor agent confirming the tree-walking instruction is a single sentence across all agents, not the multi-paragraph duplication the spec warns against.
+- `.claude/agents/aide/aide-spec-writer.md` -- Spec writer agent showing how discover is referenced for inherited context, confirming agents already use discover but each carries its own instruction to do so.
+- `.aide/docs/aide-spec.md` -- Canonical AIDE methodology doc defining the intent tree, inheritance model, and file type semantics that the aligner and alignment doc must be consistent with.

package/.claude/commands/aide/align.md

@@ -0,0 +1,15 @@
+# /aide:align — Alignment Phase
+
+> **Agent:** This command is executed by the `aide-aligner` agent.
+
+Verify spec-vs-spec alignment across the intent tree. This is NOT QA — QA checks code against a spec; alignment checks whether a spec's outcomes are consistent with every ancestor spec's outcomes. When a child spec contradicts, undermines, or silently omits an ancestor outcome, the aligner detects the drift and produces a `todo.aide` at the misaligned node with concrete realignment items. It never rewrites spec outcomes — it flags only.
+
+## Checklist
+
+- [ ] Call `aide_discover` on the target path to get the full ancestor chain
+- [ ] Read each spec in the ancestor chain top-down via `aide_read` — load intent and outcomes at every level
+- [ ] Compare each child's `outcomes.desired` and `outcomes.undesired` against every ancestor's outcomes — look for contradictions, undermining, and critical omissions
+- [ ] For misaligned specs: set `status: misaligned` on the leaf spec's frontmatter and produce `todo.aide` at the leaf with items naming the specific conflict (e.g., "Leaf desired outcome #N conflicts with ancestor [path] undesired outcome #M")
+- [ ] For aligned specs: set `status: aligned` on the spec's frontmatter
+- [ ] Report results with verdict (ALIGNED/MISALIGNED), count of specs checked, count of misalignments found, paths of any `todo.aide` files created, and recommended next step (`/aide:spec` to revise misaligned specs)
+- [ ] Do NOT rewrite spec outcomes — flag only

package/.claude/commands/aide/build.md

@@ -0,0 +1,17 @@
+# /aide:build — Build Phase
+
+> **Agent:** This command is executed by the `aide-implementor` agent.
+
+Execute the architect's implementation plan. This is the implementor phase in build mode — the session that turns `plan.aide` into working, tested code without making architectural decisions mid-session.
+
+## Checklist
+
+- [ ] Read `plan.aide` in the target module. This is the primary input — it names files, sequencing, contracts, and which existing helpers to reuse
+- [ ] Read the intent spec (`.aide` or `intent.aide`) for the target module. The plan tells you what to build; the spec tells you what counts as correct
+- [ ] Execute the plan steps top-to-bottom. Check each checkbox in `plan.aide` as you complete it. Do not reorder steps, skip steps, or add steps. If a step is ambiguous, stop and escalate back to the architect via `/aide:plan` rather than inventing an answer
+- [ ] Write the code. No architectural improvisation — if a decision is not in the plan or the spec, it is out of scope for this session
+- [ ] Write tests covering every behavior the spec's `outcomes.desired` names, plus regression coverage for anything in `outcomes.undesired`
+- [ ] Run the tests until green
+- [ ] Run the type checker (`tsc --noEmit` or the project's equivalent)
+- [ ] Run `aide_validate` to check for spec issues introduced during the build
+- [ ] Hand off to `/aide:qa` — the QA agent will compare actual output against the spec's `outcomes` block

package/.claude/commands/aide/fix.md

@@ -0,0 +1,20 @@
+# /aide:fix — Fix Phase
+
+> **Agent:** This command is executed by the `aide-implementor` agent.
+
+Work one unchecked item from the `todo.aide` checklist. This is the implementor phase in fix mode — the same agent that runs `/aide:build`, invoked with a narrower scope and a stricter one-session-per-item protocol. See [todo.aide spec](../../.aide/docs/todo-aide.md) for the file format.
+
+## Checklist
+
+- [ ] Read the intent spec (`.aide` or `intent.aide`) in the target module
+- [ ] Read `todo.aide` and pick the next unchecked item. Do not pick ahead, do not bundle. Read the item's `Misalignment` tag to understand where intent was lost
+- [ ] Fix exactly ONE issue. Do not fix adjacent issues discovered during the session — add them to the `todo.aide` checklist instead, unchecked, for future sessions
+- [ ] Base the fix on the spec, not on the one-line issue description. The description points at the problem; the spec is the source of truth for what correct looks like
+- [ ] Run the generation command (or equivalent) to produce fresh output after the fix
+- [ ] Compare the new output against the baseline from before the fix:
+  - Is the targeted issue resolved?
+  - Did anything else regress? The fix may have moved unrelated output further from the spec
+- [ ] Run tests and the type checker to catch structural regressions
+- [ ] Check the item off in `todo.aide` only if both the targeted fix landed and no regression was introduced. Otherwise revert, leave the item unchecked, and end the session
+- [ ] Commit the fix in its own commit — one checkbox, one commit, one diff
+- [ ] End the session. The next item starts in a fresh session with clean context — do not continue working additional items in the same session

package/.claude/commands/aide/init.md

@@ -0,0 +1,171 @@
+# /aide:init — Interactive Project Bootstrap
+
+> **Agent:** You are the orchestrator for this command. Do NOT delegate to a subagent.
+
+> **CRITICAL — read this before doing anything:**
+> This is a step-by-step wizard. You show ONE thing at a time, ask ONE question using the `AskUserQuestion` tool with structured options, then STOP and wait.
+>
+> **Rules:**
+> - Never show a summary table of all categories
+> - Never offer "all" as an option
+> - Never present more than one category at a time
+> - Every pause point MUST use the `AskUserQuestion` tool with defined options — never ask the user to respond conversationally
+> - After every `AskUserQuestion`, STOP. Do not continue until the user responds.
+> - Your first message should be SHORT — just the framework detection + AskUserQuestion
+
+Bootstrap AIDE into this project by calling `aide_init` and walking the user through each step interactively. The tool returns structured JSON — you interpret it and drive the conversation.
+
+## Two-call pattern
+
+The tool uses a **two-call pattern** for progressive disclosure. The first call (no `category`) returns a lightweight metadata-only summary (no file content). After the user confirms a category, call again with `category=X` to get the actual content to write.
+
+## Wizard flow
+
+Work through these steps in order. Each step is ONE interaction — you do the action, present a brief description, then call `AskUserQuestion` with structured options and STOP.
+
+---
+
+### Step 1: Detect framework
+
+Call `aide_init` with no arguments (or with a `framework` override if the user specified one). Store the full response — you'll use it across all subsequent steps.
+
+Present a brief line about the detected framework, then call `AskUserQuestion`:
+
+```
+question: "I detected {framework}. Is that correct?"
+header: "Framework"
+options:
+  - label: "Yes, {framework}" / description: "Continue with the detected framework"
+  - label: "Cursor" / description: "Target Cursor instead"
+  - label: "Windsurf" / description: "Target Windsurf instead"
+  - label: "Copilot" / description: "Target Copilot instead"
+```
+
+(Omit the detected framework from the alternative options. Always include "Yes" as the first option.)
+
+STOP. Wait for user response.
+
+---
+
+### Step 2–N: Walk through categories one at a time
+
+The categories are processed in this order: `methodology`, `commands`, `agents`, `skills`.
+
+For each category that has at least one `would-create` step, present ONLY that category with a brief description of what it contains and the file count, then call `AskUserQuestion`:
+
+```
+question: "{Category} — {count} files in {path}. Set it up?"
+header: "{Category}"
+options:
+  - label: "Yes, create them" / description: "Create the {count} files for {category}"
+  - label: "Skip" / description: "Skip {category} for now"
+```
+
+STOP. Wait for user response.
+
+**If the user selects "Yes":**
+1. Call `aide_init` with `category` set to that category name
+2. Apply the `would-create` steps using the **Write tool** for each file individually
+3. Create parent directories as needed (`mkdir -p`)
+4. Skip `exists` and `would-skip` steps
+5. Briefly confirm what was created (e.g., "Done — created 8 files in .aide/docs/")
+
+Then move to the NEXT category. Present it the same way and call `AskUserQuestion`.
+
+**If the user selects "Skip":** Move to the next category immediately.
+
+**If a category is all `exists`:** Skip it silently — don't ask about it.
+
+**Important:** Always use the Write tool to create files one at a time. Do NOT batch-write files via Bash scripts, Node scripts, or shell loops. If the tool response was large and got persisted to a JSON file on disk, use the Read tool to load it, then Write each file individually.
+
+---
+
+### Brain vault step
+
+**The brain is required — there is no skip option.**
+
+Present any `brainHints` from the initial response as named options in `AskUserQuestion`:
+
+```
+question: "AIDE needs a brain vault for research and retros. Where is yours?"
+header: "Brain"
+options (built dynamically from brainHints):
+  - label: "Use {hint.path}" / description: "{hint.reason} ({hint.type} hint)"
+  - label: "Use {hint2.path}" / description: "{hint2.reason} ({hint2.type} hint)"
+  (... up to 3 hints. User can always select "Other" to type a custom path.)
+```
+
+If there are no hints, use:
+```
+options:
+  - label: "Create new vault" / description: "I'll ask you for a path to create a new vault"
+  - label: "Connect existing" / description: "I have an existing Obsidian vault to connect"
+```
+
+STOP. Wait for user response.
+
+Once the path is resolved:
+- If `status: "would-create"`, create the vault directories: `research/`, `process/retro/`, `coding-playbook/`
+- If `status: "exists"`, tell the user it's already set up
+
+---
+
+### MCP config step
+
+Read the project's MCP config file (`.mcp.json` or equivalent) first. Each mcp step has a `prescription` with `key` and `entry`.
+
+Present what servers already exist and what would be added, then call `AskUserQuestion`:
+
+```
+question: "Your .mcp.json has {existing servers}. I need to add {new servers}. Merge them in?"
+header: "MCP"
+options:
+  - label: "Yes, merge" / description: "Add the AIDE server entries alongside your existing config"
+  - label: "Skip" / description: "Don't modify MCP config"
+```
+
+STOP. Wait for user response.
+
+On confirmation, merge each prescription's `entry` under its `key` in the `mcpServers` object and write the updated config. If the file doesn't exist, create it with `{ "mcpServers": { ... } }`. **Never overwrite the entire config** — always read, merge, write.
+
+If a step has `configMalformed: true`:
+
+```
+question: "Your .mcp.json has a JSON syntax error. How should I handle it?"
+header: "MCP"
+options:
+  - label: "Show contents" / description: "Show me the raw file so I can fix it manually"
+  - label: "Create fresh" / description: "Create a new .mcp.json with just the AIDE entries"
+```
+
+---
+
+### IDE config step
+
+These are optional. Use `AskUserQuestion` with `multiSelect: true`:
+
+```
+question: "Want any IDE integrations? These are optional."
+header: "IDE"
+multiSelect: true
+options:
+  - label: "Zed" / description: "Add .aide file type association to Zed settings"
+  - label: "VS Code" / description: "Install aide-markdown extension for VS Code"
+  - label: "Neither" / description: "Skip IDE configuration"
+```
+
+STOP. Wait for user response.
+
+Only apply what they select.
+
+---
+
+### Final step: Summary
+
+After all categories are done, give a brief summary:
+- Files created (count by category)
+- MCP entries merged
+- Brain vault location
+- IDE configuration applied (if any)
+
+Suggest next steps: "Run `aide_discover` to see existing specs, or `/aide` to start a new pipeline."

package/.claude/commands/aide/plan.md

@@ -0,0 +1,25 @@
+# /aide:plan — Plan Phase
+
+> **Agent:** This command is executed by the `aide-architect` agent.
+
+Translate the intent spec into a step-by-step implementation plan. Output is a `plan.aide` file next to the `.aide` spec — checkboxed steps the implementor executes without making architectural decisions. See [plan.aide spec](../../.aide/docs/plan-aide.md) for the file format.
+
+## Checklist
+
+- [ ] Read the complete intent spec (`.aide` or `intent.aide`) in the target module — frontmatter AND body sections must be filled. If body sections are empty, stop and escalate back to `/aide:synthesize`
+- [ ] Pull the coding playbook from the brain using the `study-playbook` skill — naming conventions, folder structure, patterns to follow and anti-patterns to avoid
+- [ ] Scan the target module and its neighbors to understand what already exists — existing helpers to reuse, existing patterns to match, folders already in place
+- [ ] Write `plan.aide` next to the `.aide` spec with:
+  - **Frontmatter:** `intent` — one-line summary of what this plan delivers
+  - **`## Plan`** — checkboxed steps the implementor executes top-to-bottom:
+    - Which files to create and where they live
+    - Which existing helpers to reuse instead of writing new ones
+    - Function boundaries and the contract between each step
+    - Sequencing — what must exist before the next step can start
+    - Tests to write for each behavior the spec's `outcomes.desired` names
+  - **`## Decisions`** — architectural choices made: why X over Y, naming rationale, tradeoffs
+- [ ] No code in the plan — no function bodies, no worked examples, no copy-paste snippets. The plan describes decisions; the implementor writes the code and loads conventions directly from the playbook via each step's `Read:` list
+- [ ] Every step must be traceable back to a line in the `.aide` spec or a rule in the coding playbook. If a step has no source, cut it or find the rule that justifies it
+- [ ] If the spec is ambiguous, stop and escalate back to the spec writer (via the orchestrator) rather than inventing an answer
+- [ ] **PAUSE for user approval.** Present the plan and do not proceed until the user approves it. Iterate if the user requests changes
+- [ ] Hand the approved plan to the implementor via `/aide:build`

package/.claude/commands/aide/qa.md

@@ -0,0 +1,25 @@
+# /aide:qa — QA Phase
+
+> **Agent:** This command is executed by the `aide-qa` agent.
+
+Verify actual output against the intent spec. This is the QA agent phase — the session that compares the spec's `outcomes` block against actual implementation and produces a `todo.aide` re-alignment document. See [todo.aide spec](../../.aide/docs/todo-aide.md) for the file format.
+
+## Checklist
+
+- [ ] Read the intent spec (`.aide` or `intent.aide`) in the target module
+- [ ] Focus on the `outcomes` block specifically:
+  - Does the actual output satisfy every item in `outcomes.desired`?
+  - Does the actual output trip any item in `outcomes.undesired`?
+- [ ] Check for hidden failures — outputs that pass tests but violate intent, missing edge cases the spec names, anti-patterns the spec warned against
+- [ ] Use judgement. If an output sounds wrong, reads wrong, or misses the point of the intent paragraph, flag it even when no specific outcome rule is named
+- [ ] Produce a `todo.aide` next to the spec. Use `aide_scaffold` with type `todo` if none exists yet. Format:
+  - **Frontmatter:** `intent` (which outcomes are violated), `misalignment` (array of pipeline stages where intent was lost — `spec-gap`, `research-gap`, `strategy-gap`, `plan-gap`, `implementation-drift`, `test-gap`)
+  - **`## Issues`** — each issue gets:
+    - A checkbox
+    - A file path and line reference where the problem appears
+    - A one-line description of what's wrong
+    - `Traces to:` which `outcomes` field (desired or undesired) it violates
+    - `Misalignment:` which pipeline stage lost the intent for this specific issue
+  - **`## Retro`** — what would have caught this earlier? Which stage needs strengthening?
+- [ ] Do NOT propose solutions. The checklist says *what's wrong and where* — the implementor, invoked via `/aide:fix`, decides *how*
+- [ ] Hand off to `/aide:fix` — the implementor will work the checklist one item per session

package/.claude/commands/aide/refactor.md

@@ -0,0 +1,29 @@
+# /aide:refactor — Refactor Phase
+
+> **Agent:** This command is orchestrated by the `/aide` orchestrator, which delegates to the `aide-auditor` agent (one per `.aide` section) and then to `aide-implementor` agents for execution.
+
+Audit existing code against the coding playbook and refactor to close convention drift. This is a post-QA phase — it runs on code that already works and already passed QA. The goal is conformance, not new functionality.
+
+**This command requires a path argument.** It does NOT perform full-app refactoring in one pass. Scope it to a directory (e.g., `src/tools/score/`) and it will audit every `.aide`-defined section within that path.
+
+## Flow
+
+1. **Discover sections** — run `aide_discover` with the given path to find all `.aide` specs in the subtree
+2. **Audit each section** — spawn one `aide-auditor` agent per `.aide` spec found. Each auditor:
+   - Reads the implementation
+   - Consults the coding playbook via `study-playbook`
+   - Compares against progressive disclosure conventions
+   - Produces `plan.aide` with refactoring steps
+3. **Pause for approval** — present all plans to the user. Do not proceed until approved
+4. **Execute refactoring** — for each approved `plan.aide`, delegate to `aide-implementor` agents (one per numbered step, same as build phase)
+5. **Re-validate** — delegate to `aide-qa` per section to verify the refactoring didn't break spec conformance
+
+## Checklist
+
+- [ ] Require a path argument — refuse to run without one
+- [ ] Run `aide_discover` scoped to the provided path
+- [ ] For each `.aide` spec found, spawn one `aide-auditor` agent
+- [ ] Collect all `plan.aide` outputs and present to user for review
+- [ ] After approval, execute each plan using `aide-implementor` agents (one per numbered step)
+- [ ] After all plans are executed, run `aide-qa` per section to verify spec outcomes still hold
+- [ ] Report completion with a summary of drift items found, fixed, and verified

package/.claude/commands/aide/research.md

@@ -0,0 +1,21 @@
+# /aide:research — Research Phase (Optional)
+
+> **Agent:** This command is executed by the `aide-domain-expert` agent.
+
+Fill the brain with durable domain knowledge the synthesizer can later draw from. Run this phase only when the module requires domain expertise the team does not already have — skip it when the domain is already understood.
+
+## Checklist
+
+- [ ] Confirm research is actually needed. If the user or the brain already has the domain knowledge, stop and go directly to `/aide:synthesize`
+- [ ] Identify the domain being researched — name it specifically enough that the brain can file the output under a stable topic
+- [ ] Check the brain first for existing research on the topic. If coverage is already sufficient, stop — do not re-fetch what the brain already holds
+- [ ] Gather sources: vault notes, transcripts, external articles, web search, MCP memory stores
+- [ ] Synthesize findings and persist them to the brain **filed by domain** (e.g., `research/email-marketing/`, `research/local-seo/`), not by project. Domain knowledge is reusable across projects
+- [ ] If no external brain is available, write findings to a co-located `research.aide` file next to the intent spec as a fallback. This is not ideal — recommend enabling an external memory store
+- [ ] Each persisted note should include:
+  - Sources with ratings and dates
+  - Data points with attribution
+  - Patterns observed across sources
+  - Conflicts resolved (where sources disagreed, which direction chosen and why)
+- [ ] Stop when coverage is sufficient for the synthesizer to fill the `.aide` body sections, not when all sources are exhausted
+- [ ] Hand off to `/aide:synthesize` — the strategist (fresh session) will read your research and fill the spec's body sections

package/.claude/commands/aide/spec.md

@@ -0,0 +1,24 @@
+# /aide:spec — Spec Phase
+
+> **Agent:** This command is executed by the `aide-spec-writer` agent.
+
+Produce the `.aide` intent spec **frontmatter only**. This is the spec-writing phase — the session that distills the orchestrator's delegation context into a falsifiable intent contract. The orchestrator owns the user conversation and passes the gathered context in the delegation prompt. Body sections (Context, Strategy, examples) are filled later by the strategist in `/aide:synthesize` after research is complete.
+
+## Checklist
+
+- [ ] Read the delegation context from the orchestrator. If insufficient to write specific outcomes (missing: what the module is for, who consumes its output, what success looks like, what failure looks like), return to the orchestrator listing what's missing
+- [ ] Read the AIDE template before writing — copy the fenced template block from the canonical template doc into the new file
+- [ ] Decide filename:
+  - Use `.aide` if no `research.aide` exists in the target folder
+  - Use `intent.aide` if `research.aide` exists in the same folder (co-located research is an escape hatch — prefer the brain)
+- [ ] Fill the frontmatter ONLY:
+  - `scope` — the module path this spec governs
+  - `intent` — one paragraph, plain language, ten-second north star
+  - `outcomes.desired` — concrete, falsifiable success criteria
+  - `outcomes.undesired` — failure modes, especially the almost-right-but-wrong kind
+- [ ] Leave body sections (`## Context`, `## Strategy`, `## Good examples`, `## Bad examples`) as empty placeholders — the strategist fills these in `/aide:synthesize`
+- [ ] No code in the spec — no file paths, no type signatures, no function names
+- [ ] Every `outcomes` entry must trace back to the `intent` paragraph. Cut any outcome that doesn't
+- [ ] Present the frontmatter to the orchestrator for relay to the user
+- [ ] Run `aide_validate` to check the spec for structural issues
+- [ ] Hand off to `/aide:research` if domain knowledge is needed, or `/aide:synthesize` if the brain already has sufficient research

package/.claude/commands/aide/synthesize.md

@@ -0,0 +1,20 @@
+# /aide:synthesize — Synthesize Phase
+
+> **Agent:** This command is executed by the `aide-strategist` agent.
+
+Read the intent spec's frontmatter and the brain's research, then fill in the `.aide` body sections (Context, Strategy, Good examples, Bad examples). This is a fresh strategist session — it did not run the research phase and carries no prior context.
+
+## Checklist
+
+- [ ] Read the target `.aide` file. Confirm frontmatter is complete (scope, intent, outcomes.desired, outcomes.undesired). If frontmatter is missing or incomplete, stop and escalate back to `/aide:spec`
+- [ ] Identify the domain from the intent. Search the brain for research notes filed under that domain (e.g., `research/email-marketing/`, `research/local-seo/`)
+- [ ] If no brain is available, check for a co-located `research.aide` in the same folder as the intent spec
+- [ ] If neither brain research nor `research.aide` exists, stop — research must run first via `/aide:research`
+- [ ] Read all relevant research notes. Cross-reference findings against the intent's `outcomes.desired` and `outcomes.undesired` — the research serves the intent, not the other way around
+- [ ] Fill `## Context` — why this module exists, the domain-level problem, constraints that shape it. Write for a generalist engineer. No code. Do not restate context already carried by a parent `.aide`
+- [ ] Fill `## Strategy` — distill research into decisions. Each paragraph names a concrete choice (tactic, threshold, structural decision) and the reasoning or data that justifies it. Cite sources inline. Write in decision form, not description form. No code
+- [ ] Fill `## Good examples` — concrete domain output that illustrates success. Real output, not code. Pattern material for QA
+- [ ] Fill `## Bad examples` — the almost-right failures. Output that looks valid but violates intent. Recognizable failure modes, not enumeration
+- [ ] Verify every strategy decision traces back to an `outcomes.desired` or guards against an `outcomes.undesired`. Cut anything that doesn't serve the intent
+- [ ] Run `aide_validate` to check the completed spec for structural issues
+- [ ] Hand off to `/aide:plan` — the architect is the next phase

package/.claude/commands/aide/update-playbook.md

@@ -0,0 +1,18 @@
+# /aide:update-playbook — Playbook Maintenance
+
+> **Agent:** You are the orchestrator for this command. Do NOT delegate to a subagent.
+
+Help the user add new conventions, modify existing ones, or reorganize sections in their coding playbook. Every invocation ends with a required drift-detection step that keeps the playbook hub's task routing table in sync with the actual section structure.
+
+## Checklist
+
+- [ ] Ask the user what they want to change — new convention, modification to an existing one, section rename, section removal, or a general audit with no specific change
+- [ ] Use the `study-playbook` skill to read the hub and identify the relevant section (or confirm no section yet exists for the new convention)
+- [ ] Make the requested change: add the new content, edit the existing section, rename or remove the section as directed
+- [ ] If a section was added, renamed, or removed, offer to reorganize adjacent sections under a new or updated domain grouping if it would improve navigability
+- [ ] **Housekeeping step (required — do not skip):** Compare the playbook hub's task routing table against the actual sections that now exist:
+  - For each row in the routing table: does the section it points to still exist under that name? Flag stale rows where the target section was renamed or removed
+  - For each section now in the playbook: does the routing table have at least one row covering it? Flag new sections with no routing entry
+  - Offer to reconcile all drift found — add missing rows, remove or update stale rows, suggest domain regroupings where the table has shifted
+- [ ] Apply any routing table changes the user approves
+- [ ] Confirm the final state: what was changed in the playbook, what was changed in the routing table