@aidemd-mcp/server 0.2.4 → 0.3.1

package/.aide/docs/.aide

@@ -1,5 +1,7 @@
 ---
 scope: .aide/docs
+description: >
+  Spec for the canonical AIDE methodology docs — governs adding the References section so synthesis agents leave auditable breadcrumb trails.
 status: aligned
 intent: >
   Add a References section to the AIDE spec template and methodology so the

package/.aide/docs/plan.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  Plan to add the References body section to the AIDE template, spec doc, and synthesis agent instructions.
 intent: >
   Add a References section to the AIDE methodology so the synthesis agent
   leaves a traceable breadcrumb trail of which brain notes informed each

package/.aide/intent.aide

@@ -1,5 +1,7 @@
 ---
 scope: .
+description: >
+  Canonical home of the AIDE methodology and the MCP server that delivers it — single source of truth for every downstream host project.
 intent: >
   This repository is the canonical home of the AIDE methodology — Autonomous
   Intent-Driven Engineering, with a deliberate second reading as AI Domain

package/.aide/plan.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  Plan to rewrite README.md into the canonical MCP installation guide with per-client config blocks and full tool documentation.
 intent: >
   Rewrite README.md to match the readme.aide spec — quick-install via
   npx @aidemd-mcp/server init as recommended primary path, per-client manual

package/.aide/readme.aide

@@ -36,9 +36,9 @@ outcomes:
       concrete first action to take inside their agent, closing the gap
       between install and first value.
   undesired:
-    - A config block that shows one client's format and expects users of
+    - "A config block that shows one client's format and expects users of
       other clients to translate — the #1 documented friction source in
-      MCP server READMEs (mcp-readme-conventions research).
+      MCP server READMEs (mcp-readme-conventions research)."
     - A tool list without parameter documentation, forcing the developer
       to install the server just to discover what inputs each tool accepts.
     - A README that teaches the full AIDE methodology instead of focusing
@@ -50,9 +50,9 @@ outcomes:
     - A config block using a bare package name without @latest, which
       silently serves a stale cached version to users who have previously
       installed any version.
-    - A PATH-troubleshooting gap: omitting the nvm/Homebrew PATH failure
+    - "A PATH-troubleshooting gap: omitting the nvm/Homebrew PATH failure
       mode for Claude Desktop, which is the single most common MCP install
-      failure and silently loses users who blame themselves and give up.
+      failure and silently loses users who blame themselves and give up."
 ---
 
 ## Context

package/.aide/todo.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  QA findings for the README.md rewrite — tracks the missing @latest on the Quick Start npx command.
 intent: >
   README.md rewrite against readme.aide spec. One outcome violated: the Quick
   Start block omits @latest from the npx command, which can serve a stale

package/.claude/.aide

@@ -23,12 +23,12 @@ outcomes:
     - 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
+    - "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
+      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.
+      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

package/.claude/agents/aide/aide-explorer.md

@@ -0,0 +1,63 @@
+---
+name: aide-explorer
+description: "Use this agent for read-only investigation of the AIDE codebase — finding code, tracing bugs, answering questions about how modules work, or understanding the cascading intent tree. This agent understands the AIDE methodology, uses aide_discover for .aide file lookups, and navigates code using progressive disclosure. It does NOT write code, edit files, or delegate to other agents.\n\nExamples:\n\n- Orchestrator delegates: \"Why does aide_init not scaffold the top-level /aide command?\"\n  [Explorer runs aide_discover, reads the scaffolding module's .aide and orchestrator, traces the issue, returns findings]\n\n- Orchestrator delegates: \"What does the scoring module's pipeline look like?\"\n  [Explorer runs aide_discover to find the module, reads .aide spec, reads orchestrator imports, returns a summary]\n\n- Orchestrator delegates: \"Find where command templates are registered and check if aide.md is in the list\"\n  [Explorer uses discover + targeted code reads to trace the registration flow and report back]"
+model: sonnet
+color: cyan
+memory: user
+mcpServers:
+  - aide
+---
+
+You are the AIDE-aware codebase explorer — a read-only investigator that understands the AIDE methodology and uses its tools to navigate codebases efficiently. You trace bugs, answer questions about how modules work, and find code — but you never modify anything.
+
+## Your Role
+
+You receive a delegation from the orchestrator with a question or investigation task, along with the current `aide_discover` output (the cascading intent tree). You use this context to navigate the codebase intelligently, then return your findings to the caller.
+
+**You do NOT write code, edit files, or delegate to other agents.** You investigate and report.
+
+## Cascading Intent — What It Means
+
+AIDE projects organize code into a tree of `.aide` spec files. Each spec declares the *intent* of its module — what it's supposed to do, what success looks like, what to avoid. Intent **cascades**: a child module's intent must align with its parent's intent, which must align with the root's intent. This ancestor chain is the "why" behind every module.
+
+When you investigate code, you are not looking at isolated files. You are looking at nodes in an intent tree. Understanding *why* a module exists (its cascading intent) comes before understanding *how* it works (its code).
+
+## Mandatory First Action
+
+**Your very first tool call MUST be `aide_discover` with the target module's path.** This returns:
+
+- The **ancestor chain** — every `.aide` spec from root down to the target, with descriptions and alignment status. This is the cascading intent context.
+- The **detailed subtree** — summaries of specs and files in the target directory, plus anomaly warnings.
+
+If the orchestrator already passed you rich discover output (with ancestor chain), you may skip this call. But if you only received a lightweight map (paths and types), you MUST call `aide_discover(path)` yourself before reading any code.
+
+**Never use Glob, Grep, find, or Bash to search for `.aide` files.** `aide_discover` is the only tool for `.aide` navigation.
+
+## How You Navigate Code
+
+After you have the cascading intent context:
+
+### Progressive Disclosure
+
+1. **Folder structure first.** Every service module is a folder named after its default export. An `ls` of a service directory tells you what it does. Start here.
+2. **Orchestrator imports + JSDoc.** If folder names aren't enough, open the orchestrator's `index.ts`. The import list + JSDoc gives you the data flow.
+3. **Function bodies.** Only drill into a helper's implementation when your task requires understanding *how* it works, not just *what* it does.
+
+### .aide Specs — Read Before Code
+
+If a module has a `.aide` spec, read it before reading the code. The spec captures domain context the code alone doesn't show — strategy, intent, implementation contracts.
+
+## Investigation Process
+
+1. **Understand cascading intent.** Use the `aide_discover(path)` output to understand the ancestor chain — why this module exists in the context of the larger system.
+2. **Read the .aide spec** for the target module to understand its specific intent, outcomes, and contracts.
+3. **Read the orchestrator** (`index.ts`) to understand the module's structure and data flow.
+4. **Drill into specific helpers** only as needed to answer the question.
+5. **Return findings** with file paths, line numbers, and a clear explanation.
+
+## What You Return
+
+Your response to the orchestrator should include:
+- **The answer** to the question or investigation
+- **Evidence** — file paths and relevant code snippets that support your finding
+- **Recommendations** (if applicable) — what should be done next, phrased as suggestions for the orchestrator to act on

package/.claude/agents/aide/aide-spec-writer.md

@@ -30,12 +30,14 @@ The orchestrator owns the user conversation. Your job is to take the context it
    - Use `intent.aide` if `research.aide` exists (co-located research triggers the rename)
 3. Fill the frontmatter ONLY:
    - `scope` — the module path this spec governs
+   - `description` — one-line purpose statement, used by `aide_discover` ancestor chains so agents understand what this spec governs without opening it
    - `intent` — one paragraph, plain language, ten-second north star
    - `outcomes.desired` — concrete, falsifiable success criteria (2-5 bullets)
    - `outcomes.undesired` — failure modes, especially the almost-right-but-wrong kind
 4. Leave body sections (`## Context`, `## Strategy`, `## Good examples`, `## Bad examples`) as empty placeholders
 5. No code in the spec — no file paths, no type signatures, no function names
 6. Every `outcomes` entry must trace back to the `intent` paragraph
+7. **Quote outcomes that contain colons.** Multi-line YAML list items whose continuation lines contain `key: value` patterns (e.g., `status: aligned`, `scope: src/tools`) break the YAML parser — it reads the colon as a map key delimiter. Wrap any outcome item that contains a colon-space (`: `) in its text in double quotes: `- "The aligner sets status: aligned on verified specs"`. Single-line items without colons don't need quoting.
 
 ## Return Format
 

package/.claude/commands/aide.md

@@ -0,0 +1,299 @@
+# /aide — Orchestrator
+
+Conversational entry point for the full AIDE pipeline. Gathers context from the user, then drives each phase by delegating to specialized agents — spinning up fresh context for every stage and handing off via files.
+
+---
+
+## MANDATORY BOOT SEQUENCE
+
+**STOP. Do not respond to the user's request yet. Do not analyze it. Do not classify it. Do not decide whether it's a "pipeline request" or a "bug report" or anything else.**
+
+This boot sequence fires on EVERY `/aide` invocation — no exceptions, no matter what the user said. It applies whether the user wants to run the pipeline, report a bug, ask a question, do a refactor, or anything else. You cannot know the correct response until you have booted.
+
+Your first tool calls MUST be these 5 calls and NOTHING else. No Bash, no Glob, no Grep, no Explore, no Agent — only these:
+
+1. `Read` → `.aide/docs/index.md`
+2. `Read` → `.aide/docs/aide-spec.md`
+3. `Read` → `.aide/docs/plan-aide.md`
+4. `Read` → `.aide/docs/todo-aide.md`
+5. `aide_discover` (MCP tool) → to get the full intent tree
+
+Calls 1–4 can run in parallel. Call 5 can run in parallel with them or after.
+
+**Only after all 5 calls return** may you read the user's request, consult the sections below, and decide what to do.
+
+**Why this is unconditional:** You are an orchestrator for a methodology you don't inherently know. Without booting, you don't understand the file formats, pipeline phases, agent routing, or project state. Even "simple" requests require this context — a bug report about `aide_init` requires knowing what `aide_init` should produce, which the docs and discover output tell you. Skipping boot means guessing, and guessing produces wrong answers.
+
+After booting, three hard constraints govern everything you do:
+- **Delegation Only** — you never write files, edit code, or do substantive work; you delegate to subagents
+- **Learn the Methodology First** — the 4 docs you just read are your reference for what each phase produces
+- **Discover First** — the `aide_discover` output you just received tells you pipeline state; do not use Glob/Grep/Read to find `.aide` files
+
+These constraints are detailed in full in the sections below. Read them now before proceeding.
+
+---
+
+## HARD CONSTRAINT — Delegation Only
+
+**You are a dispatcher. You do NOT do work. You delegate ALL work to subagents.**
+
+This is non-negotiable. No exceptions. No "this is simple enough to handle directly." No "I have enough context to do this myself." The orchestrator's ONLY jobs are:
+
+1. **Interview** — ask the user questions to gather intent
+2. **Detect state** — check which `.aide`/`plan.aide`/`todo.aide` files exist
+3. **Delegate** — spawn the correct specialized agent for each phase
+4. **Relay** — present agent results to the user and collect approvals
+5. **Advance** — move to the next pipeline stage after approval
+
+**You MUST NOT:**
+- Write or edit `.aide`, `plan.aide`, `todo.aide`, or any code files yourself
+- Fill in spec frontmatter, body sections, plans, or fixes yourself
+- Make architectural, implementation, or domain decisions
+- Run builds, tests, or validation yourself (agents do this)
+- Skip a phase because you think you already know the answer
+- Combine multiple phases into a single action
+
+**Why this matters:** Each subagent has specialized context, model selection, and instructions that you lack. When you bypass delegation, you lose that context, burn tokens going down rabbit holes, produce drift from the methodology, and force expensive QA realignment. The cascading intent structure only works when each agent handles its own phase.
+
+**Delegation means using the Agent tool** with the correct `subagent_type` for each phase:
+- Stage 1 (Spec): `aide-spec-writer`
+- Stage 2 (Research): `aide-domain-expert`
+- Stage 3 (Synthesize): `aide-strategist`
+- Stage 4 (Plan): `aide-architect`
+- Stage 5 (Build): `aide-implementor`
+- Stage 6 (QA): `aide-qa`
+- Stage 7 (Fix): `aide-implementor` then `aide-qa`
+- Refactor: `aide-auditor` (one per `.aide` section, then `aide-implementor` + `aide-qa`)
+- Align: `aide-aligner`
+- Bug investigation / non-pipeline work: `aide-explorer` (read-only) or `general-purpose` (if it needs to write files)
+
+**Never use the generic `Explore` subagent type.** Use `aide-explorer` instead — it understands the AIDE methodology, uses `aide_discover` for `.aide` file lookups, and follows progressive disclosure. The generic `Explore` agent has no methodology context and will fall back to blind file searching.
+
+**Every delegation prompt MUST include the rich discover context.** The boot sequence runs `aide_discover` without a path — that gives you the lightweight project map (locations and types only). But before delegating, you MUST also call `aide_discover` WITH the target module's path. This returns the rich output:
+
+- The **ancestor chain** — the cascading intent lineage from root to target, with each ancestor's description and alignment status
+- The **detailed subtree** — summaries extracted from file content, anomaly warnings
+
+This rich output is what the agent needs to understand *what the module is supposed to do* before investigating *how it works*.
+
+When you spawn any agent, include in the prompt:
+1. The rich `aide_discover(path)` output for the target module — ancestor chain + subtree details
+2. The specific task to perform
+
+Without the ancestor chain, the agent has no cascading intent context and will treat files as isolated code instead of parts of a connected intent tree.
+
+If you catch yourself about to write a file, edit code, or produce spec content — STOP. That is a subagent's job. Spawn the agent instead.
+
+## HARD CONSTRAINT — Learn the Methodology First
+
+You already read the 4 methodology docs during boot (calls 1–4). This section explains what you learned and why it matters.
+
+You are an orchestrator for a methodology you do not inherently know. The `.aide/docs/` directory contains the canonical definition. The 4 files you read give you:
+
+- **`index.md`** — the doc hub with the **Pipeline Agents** table (which agent handles which phase, what model, brain access). This is your delegation reference.
+- **`aide-spec.md`** — what a `.aide` spec looks like. Tells you what the spec-writer produces and what "frontmatter only" vs "body sections filled" means in the Resume Protocol.
+- **`plan-aide.md`** — what a `plan.aide` looks like. Tells you what the architect produces and what "unchecked items" means.
+- **`todo-aide.md`** — what a `todo.aide` looks like. Tells you what the QA agent produces.
+
+**You do NOT need to read** `progressive-disclosure.md`, `agent-readable-code.md`, `automated-qa.md`, or `aide-template.md` — those are implementation details for the subagents, not for you.
+
+## HARD CONSTRAINT — Discover First
+
+You already called `aide_discover` during boot (call 5). This section explains how to use what it returned.
+
+**You MUST NOT** use Glob, Grep, Read, or any native file-searching tool to find or inspect `.aide` files — `aide_discover` gives you everything you need in a richer, methodology-aware format.
+
+**What discover gave you:**
+- The full cascading intent tree from root to leaves
+- The current state of every `.aide`, `plan.aide`, and `todo.aide` file
+- Which node in the tree the user's request maps to
+- Enough context to route to the correct pipeline stage without additional file reads
+
+**Use the discover output to:**
+1. Understand what the user is talking about and which part of the tree it refers to
+2. Determine the current pipeline state (see Resume Protocol below)
+3. Route to the correct stage
+
+## Routing — Explicit Intent Beats File State
+
+**Before consulting the Resume Protocol, check whether the user explicitly requested a specific phase or flow.** If they did, route directly to that phase — the Resume Protocol does not apply.
+
+Explicit requests override file state. Examples:
+- "run an alignment check" → **Align**, even if file state says QA is next
+- "do a refactor on src/tools/" → **Refactor**, even if no `plan.aide` exists
+- "start the spec for this module" → **Stage 1 (Spec)**, even if a prior spec exists
+- "plan this" → **Stage 4 (Plan)**, even if the spec has no body sections yet
+- "run QA" → **Stage 6 (QA)**, even if `plan.aide` has unchecked items
+- "build it" → **Stage 5 (Build)**, even if no plan exists yet (ask for one first)
+
+**The Resume Protocol only fires when the user's request is ambiguous** — when they invoke `/aide` without specifying a phase, or describe what they want to do without naming a specific pipeline stage. In those cases, use file state to infer where to pick up.
+
+## Resume Protocol
+
+When the user's request does not map to a specific phase, the discover output tells you the current state. The file state IS the pipeline state:
+
+| State detected | Resume from |
+|----------------|-------------|
+| No `.aide` in target module | **Interview** — start from scratch |
+| `.aide` exists with frontmatter only (no body sections) | **Research** or **Synthesize** — check if brain has research |
+| `.aide` exists with body sections filled | **Plan** — spec is complete |
+| `plan.aide` exists with unchecked items | **Build** — plan is ready |
+| `plan.aide` fully checked, no `todo.aide` | **QA** — build is done |
+| `todo.aide` exists with unchecked items | **Fix** — QA found issues |
+| `todo.aide` fully checked | **Done** — promote retro to brain, report completion |
+
+## Pipeline
+
+### Stage 1: Interview → `aide:spec`
+
+**Your job (orchestrator):** Gather just enough context from the user to give the spec-writer a clear delegation prompt. Ask the user:
+- What module or feature is this for? Where does it live?
+- A sentence or two about what they want to build
+- Any domain knowledge already available in the brain? (Determines whether to skip research later)
+
+You do NOT need a complete requirements interview — the `aide-spec-writer` agent conducts its own deep interview with the user. Your goal is to know enough to write a good delegation prompt.
+
+**Then delegate** to the `aide-spec-writer` agent (via Agent tool, `subagent_type: aide-spec-writer`). The agent will:
+- Interview the user about intent, success criteria, and failure modes
+- Write the `.aide` frontmatter only (`scope`, `intent`, `outcomes.desired`, `outcomes.undesired`)
+- Present the frontmatter to the user for confirmation
+
+After the agent returns, relay the result and confirm the user is satisfied before advancing.
+
+### Stage 2: Research → `aide:research`
+
+**Your job (orchestrator):** Ask the user whether domain knowledge already exists in the brain. If yes, skip to Stage 3. If no, delegate.
+
+**Then delegate** to the `aide-domain-expert` agent (via Agent tool, `subagent_type: aide-domain-expert`). The agent will:
+- Search web, vault, MCP memory for relevant domain sources
+- Persist findings to the brain filed by **domain** (e.g., `research/email-marketing/`), not by project
+
+Do NOT research anything yourself. The domain expert agent has specialized tools and context for this.
+
+### Stage 3: Synthesize → `aide:synthesize`
+
+**Your job (orchestrator):** Confirm research is complete, then delegate.
+
+**Then delegate** to the `aide-strategist` agent (via Agent tool, `subagent_type: aide-strategist`). The agent will:
+- Use `aide_discover` to understand the intent tree
+- Read the `.aide` frontmatter for intent
+- Read the brain's research notes for domain knowledge
+- Fill: `## Context`, `## Strategy`, `## Good examples`, `## Bad examples`
+
+After the agent returns, present the completed spec to the user for review before advancing.
+
+### Stage 4: Plan → `aide:plan`
+
+**Your job (orchestrator):** Confirm the spec is approved, then delegate.
+
+**Then delegate** to the `aide-architect` agent (via Agent tool, `subagent_type: aide-architect`). The agent will:
+- Read the complete `.aide` spec
+- Pull the coding playbook from the brain
+- Scan the codebase for existing patterns and helpers
+- Write `plan.aide` next to the `.aide` — checkboxed steps, decisions documented
+
+**PAUSE for user approval.** After the agent returns, present the plan to the user. Do not proceed to build until the user explicitly approves. If the user requests changes, re-delegate to the architect agent — do NOT edit the plan yourself.
+
+### Stage 5: Build → `aide:build`
+
+**Your job (orchestrator):** Confirm the plan is approved, then read `plan.aide` and execute it step-by-step — one fresh implementor agent per numbered step.
+
+**How to iterate:**
+1. Read `plan.aide` to identify the next unchecked numbered step
+2. Delegate to a fresh `aide-implementor` agent (via Agent tool, `subagent_type: aide-implementor`) with a prompt that includes:
+   - The path to the `.aide` spec and `plan.aide`
+   - Which numbered step to execute (quote it from the plan)
+   - If the step has lettered sub-steps (2a, 2b, 2c), include ALL of them — the agent executes the entire numbered group in one session
+
+   **Do NOT include** generic instructions to consult the coding playbook or load conventions from the brain. Each plan step already has a `Read:` list pointing the implementor to the specific playbook notes it needs — the implementor will load those notes itself. Do not duplicate or override the Read list in your delegation prompt.
+3. After the agent returns, verify the step's checkbox is checked
+4. Repeat from step 1 until all numbered steps are checked
+
+**Lettered sub-steps:** When a plan step has lettered sub-steps (e.g., 3a, 3b, 3c), these are tightly coupled actions that share one agent session. Delegate ALL sub-steps of that number to a single implementor. Do NOT split lettered sub-steps across agents.
+
+Do NOT write any code yourself. Do NOT run builds or tests yourself. The implementor handles all of this.
+
+### Stage 6: QA → `aide:qa`
+
+**Your job (orchestrator):** Confirm the build is complete, then delegate.
+
+**Then delegate** to the `aide-qa` agent (via Agent tool, `subagent_type: aide-qa`). The agent will:
+- Compare actual output against `outcomes.desired`
+- Check for `outcomes.undesired` violations
+- Produce `todo.aide` with issues, misalignment tags, and retro
+
+If the agent reports no issues, skip to completion.
+
+### Stage 7: Fix loop → `aide:fix`
+
+**Your job (orchestrator):** Read `todo.aide` to identify unchecked items, then delegate each fix one at a time.
+
+For each unchecked item:
+1. **Delegate** to the `aide-implementor` agent (via Agent tool, `subagent_type: aide-implementor`) to fix exactly ONE item
+2. **Delegate** to the `aide-qa` agent (via Agent tool, `subagent_type: aide-qa`) to re-validate
+
+Repeat until `todo.aide` is clear. Do NOT fix anything yourself — always delegate to the implementor.
+
+### Completion
+
+When all issues are resolved:
+- Promote retro findings from `todo.aide` to the brain at `process/retro/`
+- Report completion to the user with a summary of what was built
+
+### Refactor → `aide:refactor`
+
+**This is NOT part of the feature pipeline.** Refactor is a separate flow that runs on code that already works and already passed QA. It audits existing code against the coding playbook and fixes convention drift.
+
+**Detecting refactor intent:** If the user mentions refactoring, convention drift, playbook conformance, code style alignment, or "cleaning up" existing code — this is a refactor task, not a feature pipeline. Do NOT start the spec→research→plan→build flow. Route to the refactor flow instead.
+
+**Refactor requires a path argument.** If the user doesn't provide one, ask for it. Never run a full-app refactor.
+
+**How the refactor flow works:**
+
+1. **Discover sections.** Run `aide_discover` with the user's path to find all `.aide` specs in the subtree.
+
+2. **Audit each section.** For each `.aide` spec found, delegate to a fresh `aide-auditor` agent (via Agent tool, `subagent_type: aide-auditor`). The prompt must include:
+   - The path to the `.aide` spec to audit
+   - That this is a refactor audit, not a new feature plan
+
+   Each auditor reads the implementation, consults the coding playbook, and produces `plan.aide` with refactoring steps. You can run multiple auditors in parallel since they operate on independent sections.
+
+3. **Pause for approval.** Present ALL plans to the user. Do not proceed to execution until the user approves. If the user wants changes to a plan, re-delegate to the auditor for that section — do NOT edit plans yourself.
+
+4. **Execute refactoring.** For each approved `plan.aide`, delegate to `aide-implementor` agents — one fresh agent per numbered step, same as the build phase. Multiple sections can be executed in parallel since they are independent.
+
+5. **Re-validate.** After all plans are executed, delegate to `aide-qa` per section to verify that the refactoring didn't break spec conformance (the `outcomes` block must still hold).
+
+6. **Report completion.** Summarize drift items found, fixed, and verified across all sections.
+
+### Align → `aide:align`
+
+**This is NOT part of the feature pipeline.** Align is a standalone operation that can run at any time — before, during, or after the feature pipeline. It checks whether specs across the intent tree are internally consistent, comparing child outcomes against ancestor outcomes to detect intent drift.
+
+**Detecting alignment intent:** If the user mentions alignment checking, spec consistency, intent drift, cascading outcomes, or whether child specs contradict ancestor specs — this is an align task. Do NOT start the spec→research→plan→build flow. Route to the align flow instead.
+
+**How the align flow works:**
+
+1. **Confirm the target path.** If the user doesn't provide a path, ask for one. Never run alignment on the full repository root without explicit intent.
+
+2. **Delegate to the aligner.** Delegate to a fresh `aide-aligner` agent (via Agent tool, `subagent_type: aide-aligner`). The prompt must include:
+   - The target path to align
+   - That this is a spec-vs-spec alignment check, not a code-vs-spec QA check
+
+3. **Relay results.** The aligner returns a verdict (ALIGNED/MISALIGNED), counts of specs checked and misalignments found, and `todo.aide` paths for any misaligned nodes. Present this to the user. If misalignments were found, suggest running `/aide:spec` on the flagged specs to resolve them.
+
+**Suggesting alignment (proactive guidance):** The orchestrator should suggest `/aide:align` in two situations — it is a suggestion, not automatic invocation:
+- When `aide_discover` output shows `status: misaligned` on any spec in the tree
+- When a spec edit (Stage 1) modifies `outcomes.desired` or `outcomes.undesired` — a changed outcome may now conflict with a child or ancestor spec
+
+## Rules
+
+- **DELEGATE EVERYTHING.** The orchestrator NEVER writes files, edits code, fills specs, creates plans, runs tests, or does any substantive work. Every phase is handled by its specialized agent via the Agent tool. This is the single most important rule. If you are tempted to "just do it quickly" — don't. Spawn the agent.
+- **Every stage gets fresh context.** No agent carries conversation from a prior stage. Handoff is via files only: `.aide`, `plan.aide`, `todo.aide`, brain notes.
+- **`aide_discover` is mandatory, not optional.** The orchestrator MUST run `aide_discover` as its very first action on every `/aide` invocation. Do not use native file-search tools (Glob, Grep, Read) to find `.aide` files — the discover tool provides richer, methodology-aware context.
+- **Pause for approval twice:** after spec frontmatter (Stage 1) and after plan (Stage 4). These are the two points where the user's input shapes the work.
+- **Detect and resume.** If the user runs `/aide` mid-pipeline, detect state from existing files and resume from the correct stage. Never restart from scratch if prior work exists.
+- **Research is filed by domain.** Brain notes go to `research/<domain>/`, not `research/<project>/`. The knowledge is reusable across projects.
+- **Retro is promoted.** When the fix loop closes, extract the `## Retro` section and persist it to `process/retro/` in the brain. This is how the pipeline learns.
+- **No shortcuts.** Even if the task seems trivial, the pipeline exists to maintain intent alignment. A "simple" task handled outside the pipeline is how drift starts. Always delegate.
+- **Suggest alignment, don't force it.** When discover output shows `status: misaligned` on any spec, or when a spec edit touches outcomes, suggest `/aide:align` to the user. Do not invoke it automatically — misalignment is informational, not a pipeline gate. The user decides whether to act.

package/.claude/skills/brain/.aide

@@ -1,5 +1,7 @@
 ---
 scope: .claude/skills/brain
+description: >
+  Spec for the /brain skill — a thin dispatcher that reads the vault CLAUDE.md and defers all navigation to it, giving agents general-purpose vault access.
 intent: >
   The /brain skill gives agents in host projects a general-purpose interface
   to the user's Obsidian vault. The skill prompt is deliberately minimal: it
@@ -26,11 +28,11 @@ outcomes:
       installSkills pipeline — registered in DOC_PATHS and SKILL_DOCS,
       installed to the host's skill directory, subject to the same
       idempotency and upgrade contracts as study-playbook.
-    - The skill prompt distinguishes itself from study-playbook by scope:
+    - "The skill prompt distinguishes itself from study-playbook by scope:
       study-playbook is limited to the coding playbook hub, while /brain
       is the general-purpose entry point for any vault query — research,
       project context, environment, identity, references, or any other
-      vault content the user has organized.
+      vault content the user has organized."
   undesired:
     - A skill prompt that hardcodes vault navigation rules, directory
       paths, hub locations, or routing tables. This creates two sources

package/.claude/skills/brain/plan.aide

@@ -1,4 +1,6 @@
 ---
+description: >
+  Plan to ship the /brain skill — create the SKILL.md template, register it in initContent, update the doc hub, and add a regression test.
 intent: >
   Ship the /brain skill — a thin-dispatcher SKILL.md template that tells
   agents to read the vault's root CLAUDE.md via the Obsidian MCP and follow

package/dist/cli/App/index.js

@@ -38,15 +38,17 @@ export default function App({ root, initialNodes }) {
     const [drillCache] = useState(new Map());
     // Single expanded section in drill-in mode; Tab cycles through sections.
     const [expandedSection, setExpandedSection] = useState(null);
-    // --- Detail panel frontmatter (for currently selected file) ---
+    // --- Detail panel frontmatter + body (for currently selected file) ---
     const [selectedFrontmatter, setSelectedFrontmatter] = useState(null);
+    const [selectedBody, setSelectedBody] = useState("");
     const [fmCache] = useState(new Map());
     /** Returns true if any file descendant of node matches the search filter. */
     function hasMatchingDescendant(node, filter) {
         if (node.kind === "file") {
             const lower = filter.toLowerCase();
             return (node.file.relativePath.toLowerCase().includes(lower) ||
-                (node.file.summary ?? "").toLowerCase().includes(lower));
+                (node.file.summary ?? "").toLowerCase().includes(lower) ||
+                (node.file.description ?? "").toLowerCase().includes(lower));
         }
         return node.children.some((child) => hasMatchingDescendant(child, filter));
     }
@@ -58,8 +60,10 @@ export default function App({ root, initialNodes }) {
             if (fn.node.kind === "dir") {
                 return hasMatchingDescendant(fn.node, searchFilter);
             }
-            return (fn.node.file.relativePath.toLowerCase().includes(searchFilter.toLowerCase()) ||
-                (fn.node.file.summary ?? "").toLowerCase().includes(searchFilter.toLowerCase()));
+            const lower = searchFilter.toLowerCase();
+            return (fn.node.file.relativePath.toLowerCase().includes(lower) ||
+                (fn.node.file.summary ?? "").toLowerCase().includes(lower) ||
+                (fn.node.file.description ?? "").toLowerCase().includes(lower));
         })
         : flatNodes;
     // Clamp cursor within visible range.
@@ -75,25 +79,30 @@ export default function App({ root, initialNodes }) {
     // Computed booleans for the cursor's current position.
     const cursorOnDir = cursorNode?.node.kind === "dir";
     const cursorDirExpanded = cursorOnDir && cursorNode.node.kind === "dir" && expandedDirs.has(cursorNode.node.path);
-    // Load frontmatter for the detail panel whenever selectedFile changes.
+    // Load frontmatter + body for the detail panel whenever selectedFile changes.
     useEffect(() => {
         if (!selectedFile) {
             setSelectedFrontmatter(null);
+            setSelectedBody("");
             return;
         }
         if (fmCache.has(selectedFile.path)) {
-            setSelectedFrontmatter(fmCache.get(selectedFile.path) ?? null);
+            const cached = fmCache.get(selectedFile.path);
+            setSelectedFrontmatter(cached.frontmatter);
+            setSelectedBody(cached.body);
             return;
         }
         readFile(selectedFile.path, "utf-8")
             .then((content) => {
-            const { frontmatter } = parseFrontmatter(content);
-            fmCache.set(selectedFile.path, frontmatter);
+            const { frontmatter, body } = parseFrontmatter(content);
+            fmCache.set(selectedFile.path, { frontmatter, body });
             setSelectedFrontmatter(frontmatter);
+            setSelectedBody(body);
         })
             .catch(() => {
-            fmCache.set(selectedFile.path, null);
+            fmCache.set(selectedFile.path, { frontmatter: null, body: "" });
             setSelectedFrontmatter(null);
+            setSelectedBody("");
         });
     }, [selectedFile?.path]);
     /** Load and parse a file for drill-in view. */
@@ -109,12 +118,12 @@ export default function App({ root, initialNodes }) {
             const content = await readFile(file.path, "utf-8");
             const { frontmatter, body } = parseFrontmatter(content);
             const sections = parseBody(body);
-            const data = { frontmatter, sections };
+            const data = { frontmatter, body, sections };
             drillCache.set(file.path, data);
             setDrillData(data);
         }
         catch {
-            setDrillData({ frontmatter: null, sections: [] });
+            setDrillData({ frontmatter: null, body: "", sections: [] });
         }
     }, [drillCache]);
     /** Toggle deep view on/off, caching shallow results for instant restore. */
@@ -277,6 +286,6 @@ export default function App({ root, initialNodes }) {
         // Enter is a no-op in drill-in mode.
     });
     // --- Layout ---
-    const treeWidth = Math.floor(columns * 0.38);
-    return (_jsxs(Box, { flexDirection: "row", width: columns, children: [_jsxs(Box, { flexDirection: "column", width: treeWidth, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Intent Tree" }), deepLoading && _jsx(Text, { color: "yellow", children: "  Loading summaries..." }), _jsx(TreePanel, { visibleNodes: visibleNodes, cursorIndex: clampedCursor, searchFilter: searchFilter, isDeepView: isDeepView, expandedDirs: expandedDirs, cursorOnDir: cursorOnDir, cursorDirExpanded: cursorDirExpanded, width: treeWidth - 2 })] }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Detail" }), _jsx(DetailPanel, { file: selectedFile, frontmatter: mode === "drill-in" ? (drillData?.frontmatter ?? null) : selectedFrontmatter, mode: mode === "drill-in" ? "drill-in" : "preview", sections: drillData?.sections ?? [], expandedSection: expandedSection, drilledFilePath: drilledFile?.relativePath ?? null })] })] }));
+    const treeWidth = Math.floor(columns * 0.57);
+    return (_jsxs(Box, { flexDirection: "row", width: columns, children: [_jsxs(Box, { flexDirection: "column", width: treeWidth, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Intent Tree" }), deepLoading && _jsx(Text, { color: "yellow", children: "  Loading summaries..." }), _jsx(TreePanel, { visibleNodes: visibleNodes, cursorIndex: clampedCursor, searchFilter: searchFilter, isDeepView: isDeepView, expandedDirs: expandedDirs, cursorOnDir: cursorOnDir, cursorDirExpanded: cursorDirExpanded, width: treeWidth - 2 })] }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, borderStyle: "single", borderColor: "white", children: [_jsx(Text, { bold: true, children: " Detail" }), _jsx(DetailPanel, { file: selectedFile, frontmatter: mode === "drill-in" ? (drillData?.frontmatter ?? null) : selectedFrontmatter, body: mode === "drill-in" ? (drillData?.body ?? "") : selectedBody, mode: mode === "drill-in" ? "drill-in" : "preview", sections: drillData?.sections ?? [], expandedSection: expandedSection, drilledFilePath: drilledFile?.relativePath ?? null })] })] }));
 }

package/dist/cli/DetailPanel/index.d.ts

@@ -3,6 +3,8 @@ import type { AideFile, AideFrontmatter, BodySection } from "../../types/index.j
 interface DetailPanelProps {
     file: AideFile | null;
     frontmatter: AideFrontmatter | null;
+    /** Raw body content of the selected or drilled-in file. Used by plan/todo renderers. */
+    body: string;
     /** Controls which rendering mode is active in the right panel. */
     mode: "preview" | "drill-in";
     /** Body sections from the drilled-in file. */
@@ -16,9 +18,11 @@ interface DetailPanelProps {
  * Right-panel component that handles both preview mode (tree navigation) and
  * drill-in mode (formatted frontmatter card with expandable body sections).
  *
- * In preview mode: scope, truncated intent, and outcome counts.
- * In drill-in mode: full frontmatter card (scope heading, full intent, side-by-side
- * outcomes) plus expandable body sections cycled with Tab.
+ * Delegates to RenderPlanDetail for plan files and RenderTodoDetail for todo files.
+ * Intent and research files use the intent-card layout (scope, intent, outcomes).
+ *
+ * In preview mode: scope, truncated intent, and outcome counts (or plan/todo summary).
+ * In drill-in mode: full frontmatter card or plan/todo detail view.
  */
-export default function DetailPanel({ file, frontmatter, mode, sections, expandedSection, drilledFilePath, }: DetailPanelProps): React.ReactElement;
+export default function DetailPanel({ file, frontmatter, body, mode, sections, expandedSection, drilledFilePath, }: DetailPanelProps): React.ReactElement;
 export {};

package/dist/cli/DetailPanel/index.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text, useStdout } from "ink";
+import RenderPlanDetail from "./renderPlanDetail/index.js";
+import RenderTodoDetail from "./renderTodoDetail/index.js";
 /** Truncate a string to maxLen chars, appending "..." if trimmed. */
 function truncate(s, maxLen) {
     if (s.length <= maxLen)
@@ -21,11 +23,13 @@ function OutcomesDisplay({ desired, undesired, wide, }) {
  * Right-panel component that handles both preview mode (tree navigation) and
  * drill-in mode (formatted frontmatter card with expandable body sections).
  *
- * In preview mode: scope, truncated intent, and outcome counts.
- * In drill-in mode: full frontmatter card (scope heading, full intent, side-by-side
- * outcomes) plus expandable body sections cycled with Tab.
+ * Delegates to RenderPlanDetail for plan files and RenderTodoDetail for todo files.
+ * Intent and research files use the intent-card layout (scope, intent, outcomes).
+ *
+ * In preview mode: scope, truncated intent, and outcome counts (or plan/todo summary).
+ * In drill-in mode: full frontmatter card or plan/todo detail view.
  */
-export default function DetailPanel({ file, frontmatter, mode, sections, expandedSection, drilledFilePath, }) {
+export default function DetailPanel({ file, frontmatter, body, mode, sections, expandedSection, drilledFilePath, }) {
     const { stdout } = useStdout();
     const columns = stdout?.columns ?? 80;
     const wide = columns >= 80;
@@ -34,6 +38,14 @@ export default function DetailPanel({ file, frontmatter, mode, sections, expande
         if (!file) {
             return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "gray", children: "Select a file to preview" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "Type to search, [tab] for deep view" }) })] }));
         }
+        // Delegate to type-specific renderers for plan and todo files.
+        if (file.type === "plan") {
+            return _jsx(RenderPlanDetail, { file: file, frontmatter: frontmatter, mode: "preview", body: body, drilledFilePath: null });
+        }
+        if (file.type === "todo") {
+            const description = frontmatter?.description ?? file.description ?? "";
+            return _jsx(RenderTodoDetail, { description: description, body: body, mode: "preview", filePath: file.relativePath });
+        }
         if (!frontmatter) {
             return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "red", children: "[FAILED TO PARSE]" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: file.relativePath }) })] }));
         }
@@ -44,6 +56,14 @@ export default function DetailPanel({ file, frontmatter, mode, sections, expande
         return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [_jsxs(Text, { bold: true, children: ["scope: ", scope] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { wrap: "wrap", children: intent }) }), (desiredCount > 0 || undesiredCount > 0) && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { color: "green", children: ["\u2713 desired (", desiredCount, ")"] }), _jsxs(Text, { color: "red", children: ["\u2717 undesired (", undesiredCount, ")"] })] })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[\u2191\u2193] navigate  [enter] drill in  [tab] deep view" }) })] }));
     }
     // --- Drill-in mode ---
+    // Delegate to type-specific renderers for plan and todo files.
+    if (file?.type === "plan") {
+        return _jsx(RenderPlanDetail, { file: file, frontmatter: frontmatter, mode: "drill-in", body: body, drilledFilePath: drilledFilePath });
+    }
+    if (file?.type === "todo") {
+        const description = frontmatter?.description ?? file?.description ?? "";
+        return _jsx(RenderTodoDetail, { description: description, body: body, mode: "drill-in", filePath: drilledFilePath ?? file?.relativePath ?? "" });
+    }
     const title = drilledFilePath ?? "[unknown]";
     const scope = frontmatter?.scope ?? "[FAILED TO PARSE]";
     const intent = frontmatter?.intent ?? "[FAILED TO PARSE]";

package/dist/cli/DetailPanel/renderPlanDetail/index.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import type { AideFile, AideFrontmatter } from "../../../types/index.js";
+interface RenderPlanDetailProps {
+    file: AideFile;
+    frontmatter: AideFrontmatter | null;
+    /** Controls which rendering mode is active in the right panel. */
+    mode: "preview" | "drill-in";
+    /** Raw body content of the plan file. */
+    body: string;
+    /** File path shown as the panel title during drill-in, or null in preview mode. */
+    drilledFilePath: string | null;
+}
+/**
+ * Detail panel renderer for plan files (.aide files of type "plan").
+ *
+ * Preview mode: description from frontmatter, progress fraction, remaining count.
+ * Drill-in mode: grouped checklist items by step heading, completion summary at top.
+ */
+export default function RenderPlanDetail({ file, frontmatter, mode, body, drilledFilePath, }: RenderPlanDetailProps): React.ReactElement;
+export {};

package/dist/cli/DetailPanel/renderPlanDetail/index.js

@@ -0,0 +1,30 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import parsePlanItems from "./parsePlanItems/index.js";
+/** Renders a compact ASCII progress bar of fixed width. */
+function ProgressBar({ done, total, width }) {
+    const filled = total > 0 ? Math.round((done / total) * width) : 0;
+    const bar = "█".repeat(filled) + "░".repeat(width - filled);
+    return _jsxs(Text, { color: "cyan", children: ["[", bar, "]"] });
+}
+/**
+ * Detail panel renderer for plan files (.aide files of type "plan").
+ *
+ * Preview mode: description from frontmatter, progress fraction, remaining count.
+ * Drill-in mode: grouped checklist items by step heading, completion summary at top.
+ */
+export default function RenderPlanDetail({ file, frontmatter, mode, body, drilledFilePath, }) {
+    const steps = parsePlanItems(body);
+    const allItems = steps.flatMap((s) => s.items);
+    const doneCount = allItems.filter((i) => i.done).length;
+    const totalCount = allItems.length;
+    const remainingCount = totalCount - doneCount;
+    // --- Preview mode ---
+    if (mode === "preview") {
+        const description = frontmatter?.description ?? file.description ?? "";
+        return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [description !== "" && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { wrap: "wrap", children: description }) })), _jsxs(Box, { flexDirection: "row", gap: 1, alignItems: "center", children: [_jsx(ProgressBar, { done: doneCount, total: totalCount, width: 20 }), _jsxs(Text, { children: [doneCount, "/", totalCount, " complete"] })] }), remainingCount > 0 && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "gray", children: [remainingCount, " item", remainingCount !== 1 ? "s" : "", " remaining"] }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[\u2191\u2193] navigate  [enter] drill in  [tab] deep view" }) })] }));
+    }
+    // --- Drill-in mode ---
+    const title = drilledFilePath ?? file.relativePath;
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, flexGrow: 1, children: [_jsx(Text, { bold: true, children: title }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { bold: true, color: doneCount === totalCount && totalCount > 0 ? "green" : "cyan", children: ["Progress: ", doneCount, "/", totalCount, " step", totalCount !== 1 ? "s" : "", " complete"] }) }), steps.length > 0 && (_jsx(Box, { flexDirection: "column", marginTop: 1, children: steps.map((s, si) => (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [s.step !== "" && (_jsx(Text, { bold: true, children: s.step })), s.items.map((item, ii) => (_jsxs(Box, { flexDirection: "row", marginLeft: s.step !== "" ? 2 : 0, children: [item.done ? (_jsx(Text, { color: "green", children: "\u2713 " })) : (_jsx(Text, { color: "gray", children: "\u25CB " })), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { color: item.done ? "gray" : undefined, wrap: "wrap", children: item.text }) })] }, ii)))] }, si))) })), totalCount === 0 && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "No checklist items found." }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[esc] back  [e] open in editor" }) })] }));
+}

package/dist/cli/DetailPanel/renderPlanDetail/parsePlanItems/index.d.ts

@@ -0,0 +1,32 @@
+/** A single checklist item within a plan step. */
+export interface PlanItem {
+    text: string;
+    done: boolean;
+}
+/** A plan step grouping with its heading label and checklist items. */
+export interface PlanStep {
+    step: string;
+    done: boolean;
+    items: PlanItem[];
+}
+/**
+ * Parse a plan file body string into structured step groups with checklist items.
+ *
+ * Recognises three heading formats found in this project's plan files:
+ *
+ * 1. `### N. [x] Step title`  — numbered with inline checkbox (cli/plan.aide)
+ * 2. `### N. Step title`       — numbered without inline checkbox
+ * 3. `### Phase N — Title`     — Phase-prefixed with em-dash (init/plan.aide)
+ *
+ * Checklist items below a heading are lines matching `- [x]` or `- [ ]`.
+ * Prose items (non-checklist bullet lines) and all other non-heading lines
+ * are ignored. Items that appear before any heading are grouped under an
+ * empty-string step.
+ *
+ * The `done` field on a `PlanStep` is determined as follows:
+ * - If the heading carries an inline `[x]`/`[ ]` marker (format 1), that
+ *   marker is authoritative — `done` is not overridden by item states.
+ * - Otherwise `done` is derived: true when all contained items are done,
+ *   false when any item is undone or the step has no items.
+ */
+export default function parsePlanItems(body: string): PlanStep[];

package/dist/cli/DetailPanel/renderPlanDetail/parsePlanItems/index.js

@@ -0,0 +1,80 @@
+/**
+ * Parse a plan file body string into structured step groups with checklist items.
+ *
+ * Recognises three heading formats found in this project's plan files:
+ *
+ * 1. `### N. [x] Step title`  — numbered with inline checkbox (cli/plan.aide)
+ * 2. `### N. Step title`       — numbered without inline checkbox
+ * 3. `### Phase N — Title`     — Phase-prefixed with em-dash (init/plan.aide)
+ *
+ * Checklist items below a heading are lines matching `- [x]` or `- [ ]`.
+ * Prose items (non-checklist bullet lines) and all other non-heading lines
+ * are ignored. Items that appear before any heading are grouped under an
+ * empty-string step.
+ *
+ * The `done` field on a `PlanStep` is determined as follows:
+ * - If the heading carries an inline `[x]`/`[ ]` marker (format 1), that
+ *   marker is authoritative — `done` is not overridden by item states.
+ * - Otherwise `done` is derived: true when all contained items are done,
+ *   false when any item is undone or the step has no items.
+ */
+export default function parsePlanItems(body) {
+    const lines = body.split("\n");
+    const steps = [];
+    let current = null;
+    for (const raw of lines) {
+        const line = raw.trim();
+        // Format 1: ### N. [x] Step title  (inline checkbox in heading)
+        const inlineCheckHeading = line.match(/^###\s+\d+\.\s+\[(x| )\]\s+(.+)$/i);
+        if (inlineCheckHeading) {
+            current = {
+                step: inlineCheckHeading[2].trim(),
+                done: inlineCheckHeading[1].toLowerCase() === "x",
+                items: [],
+                _headingCheckbox: true,
+            };
+            steps.push(current);
+            continue;
+        }
+        // Format 2: ### N. Step title  (no inline checkbox)
+        const numberedHeading = line.match(/^###\s+\d+\.\s+(.+)$/);
+        if (numberedHeading) {
+            current = { step: numberedHeading[1].trim(), done: false, items: [], _headingCheckbox: false };
+            steps.push(current);
+            continue;
+        }
+        // Format 3: ### Phase N — Title  (Phase prefix with em-dash, en-dash, or hyphen)
+        const phaseHeading = line.match(/^###\s+Phase\s+\d+\s+[—–-]+\s+(.+)$/i);
+        if (phaseHeading) {
+            current = { step: phaseHeading[1].trim(), done: false, items: [], _headingCheckbox: false };
+            steps.push(current);
+            continue;
+        }
+        const checkedMatch = line.match(/^-\s+\[x\]\s+(.+)$/i);
+        if (checkedMatch) {
+            if (!current) {
+                current = { step: "", done: false, items: [], _headingCheckbox: false };
+                steps.push(current);
+            }
+            current.items.push({ text: checkedMatch[1].trim(), done: true });
+            continue;
+        }
+        const uncheckedMatch = line.match(/^-\s+\[ \]\s+(.+)$/);
+        if (uncheckedMatch) {
+            if (!current) {
+                current = { step: "", done: false, items: [], _headingCheckbox: false };
+                steps.push(current);
+            }
+            current.items.push({ text: uncheckedMatch[1].trim(), done: false });
+        }
+    }
+    // Derive done for steps whose heading had no inline checkbox:
+    // true only when all items are done and at least one item exists.
+    for (const step of steps) {
+        if (!step._headingCheckbox && step.items.length > 0) {
+            step.done = step.items.every((item) => item.done);
+        }
+    }
+    // Strip the internal field before returning.
+    return steps.map(({ _headingCheckbox: _hc, ...rest }) => rest);
+}

package/dist/cli/DetailPanel/renderTodoDetail/index.d.ts

@@ -0,0 +1,17 @@
+import React from "react";
+interface RenderTodoDetailProps {
+    /** Frontmatter description field, shown as the preview summary. */
+    description: string;
+    /** Raw body content of the todo file. */
+    body: string;
+    /** Controls which rendering mode is active. */
+    mode: "preview" | "drill-in";
+    /** File path, used as the drill-in panel title. */
+    filePath: string;
+}
+/**
+ * Renders a todo.aide file in preview mode (summary counts) or drill-in mode
+ * (full issue list with misalignment annotations highlighted and completion state).
+ */
+export default function RenderTodoDetail({ description, body, mode, filePath, }: RenderTodoDetailProps): React.ReactElement;
+export {};

package/dist/cli/DetailPanel/renderTodoDetail/index.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import parseTodoItems from "./parseTodoItems/index.js";
+/**
+ * Renders a todo.aide file in preview mode (summary counts) or drill-in mode
+ * (full issue list with misalignment annotations highlighted and completion state).
+ */
+export default function RenderTodoDetail({ description, body, mode, filePath, }) {
+    const items = parseTodoItems(body);
+    const totalCount = items.length;
+    const doneCount = items.filter((item) => item.done).length;
+    const openCount = totalCount - doneCount;
+    const misalignmentCount = items.filter((item) => item.misalignment !== undefined).length;
+    if (mode === "preview") {
+        return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, children: [description ? (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { wrap: "wrap", children: description }) })) : null, _jsxs(Text, { children: ["Issues:", " ", _jsxs(Text, { color: openCount > 0 ? "yellow" : "green", children: [openCount, " open"] }), ", ", _jsxs(Text, { color: "green", children: [doneCount, " resolved"] }), " (", _jsxs(Text, { children: [totalCount, " total"] }), ")"] }), misalignmentCount > 0 && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["\u2691 ", misalignmentCount, " misalignment annotation", misalignmentCount !== 1 ? "s" : ""] }) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[\u2191\u2193] navigate  [enter] drill in  [tab] deep view" }) })] }));
+    }
+    // Drill-in mode — full issue list
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 2, paddingY: 1, flexGrow: 1, children: [_jsx(Text, { bold: true, children: filePath }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { children: ["Issues:", " ", _jsxs(Text, { color: openCount > 0 ? "yellow" : "green", children: [openCount, " open"] }), ", ", _jsxs(Text, { color: "green", children: [doneCount, " resolved"] }), " (", _jsxs(Text, { children: [totalCount, " total"] }), ")"] }) }), items.length === 0 ? (_jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "No checklist items found." }) })) : (_jsx(Box, { flexDirection: "column", marginTop: 1, children: items.map((item, i) => (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { flexDirection: "row", children: [item.done ? (_jsx(Text, { color: "green", children: "\u2713 " })) : (_jsx(Text, { color: "gray", children: "\u25CB " })), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { color: item.misalignment !== undefined ? "yellow" : undefined, wrap: "wrap", children: item.text }) })] }), item.misalignment !== undefined && (_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { color: "red", children: ["\u2691 Misalignment: ", item.misalignment] }) }))] }, i))) })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "[esc] back  [e] open in editor" }) })] }));
+}

package/dist/cli/DetailPanel/renderTodoDetail/parseTodoItems/index.d.ts

@@ -0,0 +1,26 @@
+/** A single parsed checklist item from a todo.aide body. */
+export interface TodoItem {
+    /** The main text of the checklist item (first line only, not continuation lines). */
+    text: string;
+    /** Whether the item is checked (`- [x]`). */
+    done: boolean;
+    /**
+     * The Misalignment annotation extracted from a continuation line, if present.
+     * e.g. "implementation-drift" from a line like "  Misalignment: implementation-drift"
+     */
+    misalignment?: string;
+}
+/**
+ * Parses the body of a todo.aide file into a structured array of checklist items.
+ *
+ * Format recognised:
+ *   - `- [x] item text`   — completed item
+ *   - `- [ ] item text`   — open item
+ *   Continuation lines (indented lines that follow a checklist item) are scanned
+ *   for a `Misalignment:` annotation. The first such annotation found is attached
+ *   to the preceding item. All other continuation lines are ignored.
+ *
+ * Lines that are not checklist items and not continuations of a checklist item
+ * (e.g. `##` headings, blank lines, Retro sections) are ignored.
+ */
+export default function parseTodoItems(body: string): TodoItem[];

package/dist/cli/DetailPanel/renderTodoDetail/parseTodoItems/index.js

@@ -0,0 +1,48 @@
+/**
+ * Parses the body of a todo.aide file into a structured array of checklist items.
+ *
+ * Format recognised:
+ *   - `- [x] item text`   — completed item
+ *   - `- [ ] item text`   — open item
+ *   Continuation lines (indented lines that follow a checklist item) are scanned
+ *   for a `Misalignment:` annotation. The first such annotation found is attached
+ *   to the preceding item. All other continuation lines are ignored.
+ *
+ * Lines that are not checklist items and not continuations of a checklist item
+ * (e.g. `##` headings, blank lines, Retro sections) are ignored.
+ */
+export default function parseTodoItems(body) {
+    const lines = body.split("\n");
+    const items = [];
+    let current = null;
+    for (const line of lines) {
+        const checkboxMatch = line.match(/^- \[(x| )\] (.+)/);
+        if (checkboxMatch) {
+            // Flush previous item before starting a new one
+            if (current)
+                items.push(current);
+            current = {
+                text: checkboxMatch[2].trim(),
+                done: checkboxMatch[1] === "x",
+            };
+            continue;
+        }
+        // Continuation line — only meaningful after a checklist item
+        if (current && line.match(/^\s+/)) {
+            const misalignmentMatch = line.match(/\bMisalignment:\s*(.+)/);
+            if (misalignmentMatch && !current.misalignment) {
+                current.misalignment = misalignmentMatch[1].trim();
+            }
+            continue;
+        }
+        // Non-item, non-continuation line — flush any pending item
+        if (current) {
+            items.push(current);
+            current = null;
+        }
+    }
+    // Flush the last item if body ended while an item was open
+    if (current)
+        items.push(current);
+    return items;
+}

package/dist/cli/TreePanel/index.js

@@ -1,4 +1,4 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from "ink";
 /** Type-tag display labels keyed by AideFileType. */
 const TYPE_TAG = {
@@ -22,7 +22,24 @@ function renderRow(flatNode, index, cursorIndex, isDeepView, expandedDirs, width
     if (node.kind === "dir") {
         const label = node.path === "." ? ". /" : `${node.path}/`;
         const expandIndicator = expandedDirs.has(node.path) ? "v " : "> ";
-        return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, color: isCursor ? "white" : "gray", children: [indent, expandIndicator, label] }) }, `dir-${node.path}-${index}`));
+        // Find the first intent child to surface its status and description on the dir row.
+        const intentChild = node.children.find((c) => c.kind === "file" && c.file.type === "intent");
+        const intentFile = intentChild?.kind === "file" ? intentChild.file : null;
+        const dirStatusBadge = intentFile?.status === "aligned"
+            ? { text: " [aligned]", color: "green" }
+            : intentFile?.status === "misaligned"
+                ? { text: " [misaligned]", color: "red" }
+                : null;
+        const dirDescription = intentFile?.description ?? "";
+        // Truncate description to fit within available panel width.
+        const dirFixedLen = indent.length + expandIndicator.length + label.length + (dirStatusBadge?.text.length ?? 0);
+        const dirRemaining = width - dirFixedLen;
+        let dirSummaryText = "";
+        if (dirDescription && dirRemaining > 10) {
+            const full = ` — ${dirDescription}`;
+            dirSummaryText = full.length <= dirRemaining ? full : `${full.slice(0, dirRemaining - 3)}…`;
+        }
+        return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, color: isCursor ? "white" : "gray", wrap: "truncate", children: [indent, expandIndicator, label, dirStatusBadge ? _jsx(Text, { color: dirStatusBadge.color, children: dirStatusBadge.text }) : null, dirSummaryText ? _jsx(Text, { color: "gray", children: dirSummaryText }) : null] }) }, `dir-${node.path}-${index}`));
     }
     // File node — render as a single <Text> to prevent Ink from wrapping mid-element.
     const { file } = node;
@@ -32,15 +49,26 @@ function renderRow(flatNode, index, cursorIndex, isDeepView, expandedDirs, width
     const tagColor = TYPE_COLOR[file.type] ?? "white";
     const prefix = `${indent}${connector}${filename} `;
     const tagStr = `[${tag}]`;
-    // Truncate summary to fit within available panel width.
-    const fixedLen = prefix.length + tagStr.length;
+    // Determine status badge text and color when a status flag is present.
+    const statusBadge = file.status
+        ? file.status === "aligned"
+            ? { text: " [aligned]", color: "green" }
+            : { text: " [misaligned]", color: "red" }
+        : null;
+    // Truncate summary/description to fit within available panel width.
+    const statusLen = statusBadge ? statusBadge.text.length : 0;
+    const fixedLen = prefix.length + tagStr.length + statusLen;
     const remaining = width - fixedLen;
-    let summary = "";
-    if (isDeepView && file.summary && remaining > 10) {
+    let summaryText = "";
+    if (file.description && remaining > 10) {
+        const full = ` — ${file.description}`;
+        summaryText = full.length <= remaining ? full : `${full.slice(0, remaining - 3)}…`;
+    }
+    else if (!file.description && isDeepView && file.summary && remaining > 10) {
         const full = ` — ${file.summary}`;
-        summary = full.length <= remaining ? full : `${full.slice(0, remaining - 3)}…`;
+        summaryText = full.length <= remaining ? full : `${full.slice(0, remaining - 3)}…`;
     }
-    return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, backgroundColor: isCursor ? "blue" : undefined, wrap: "truncate", children: [prefix, _jsx(Text, { color: tagColor, children: tagStr }), summary ? _jsx(Text, { color: "gray", children: summary }) : null] }) }, `file-${file.relativePath}-${index}`));
+    return (_jsx(Box, { children: _jsxs(Text, { bold: isCursor, backgroundColor: isCursor ? "blue" : undefined, wrap: "truncate", children: [prefix, _jsx(Text, { color: tagColor, children: tagStr }), statusBadge ? _jsx(Text, { color: statusBadge.color, children: statusBadge.text }) : null, summaryText ? _jsx(Text, { color: "gray", children: summaryText }) : null] }) }, `file-${file.relativePath}-${index}`));
 }
 /**
  * Renders the left-panel tree of .aide files with cursor highlighting and optional summaries.

package/dist/tools/discover/buildAncestorChain/index.js

@@ -76,7 +76,7 @@ export default async function buildAncestorChain(root, targetPath) {
         if (!spec)
             continue;
         const { frontmatter } = parseFrontmatter(spec.content);
-        const description = frontmatter?.description;
+        const description = frontmatter?.description || (frontmatter?.intent ? frontmatter.intent.split(/[.\n]/)[0] : undefined);
         const status = frontmatter?.status;
         // Compute a display path relative to the project root
         const rel = relative(absRoot, spec.specPath).replace(/\\/g, "/");

package/dist/types/index.d.ts

@@ -39,6 +39,10 @@ export interface AideFile {
     type: AideFileType;
     /** First ~80 chars of the first paragraph, for tree summaries. */
     summary: string;
+    /** Frontmatter description field — one-line human-readable summary. Empty string when absent. */
+    description?: string;
+    /** Alignment status from frontmatter — present only when explicitly set. */
+    status?: "aligned" | "misaligned";
 }
 /** Result of scanning a directory tree for .aide files. */
 export interface ScanResult {

package/dist/util/scan/index.d.ts

@@ -2,6 +2,8 @@ import type { ScanResult } from "../../types/index.js";
 /**
  * Recursively walk the filesystem from `root` and collect all .aide files.
  * Skips node_modules, .git, dist, build, .next, coverage, __pycache__.
- * Reads the first ~1000 bytes of each file to extract the first meaningful body line as summary.
+ * In deep mode: reads full content to extract summary, description, and status.
+ * In shallow mode: reads only the first ~500 bytes per file to extract frontmatter
+ * description and status — summary stays empty but descriptions appear unconditionally.
  */
 export default function scan(root: string, path?: string, shallow?: boolean): Promise<ScanResult>;

package/dist/util/scan/index.js

@@ -2,6 +2,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { classifyFile } from "../../util/classify/index.js";
 import { SKIP_DIRS } from "../../types/index.js";
+import parseFrontmatter from "../../util/parseFrontmatter/index.js";
 /** Extract the first meaningful body line as the summary, truncated to ~80 chars. */
 function extractSummary(content) {
     const lines = content.split("\n");
@@ -32,6 +33,17 @@ function extractSummary(content) {
 function toPosix(p) {
     return p.split("\\").join("/");
 }
+/**
+ * Derive a description from frontmatter, falling back to the first sentence of
+ * `intent` when `description` is absent — matching the logic in buildAncestorChain.
+ */
+function deriveDescription(frontmatter) {
+    if (frontmatter?.description)
+        return frontmatter.description;
+    if (frontmatter?.intent)
+        return frontmatter.intent.split(/[.\n]/)[0] ?? "";
+    return "";
+}
 /** Recursively walk a directory and collect all .aide files. */
 async function walk(dir, root, files, shallow) {
     let entries;
@@ -52,10 +64,31 @@ async function walk(dir, root, files, shallow) {
         if (!entry.name.endsWith(".aide"))
             continue;
         let summary = "";
+        let description = "";
+        let status;
         if (!shallow) {
             try {
                 const buf = await readFile(fullPath, { encoding: "utf-8" });
                 summary = extractSummary(buf.slice(0, 1000));
+                const { frontmatter } = parseFrontmatter(buf);
+                description = deriveDescription(frontmatter);
+                if (frontmatter?.status)
+                    status = frontmatter.status;
+            }
+            catch {
+                // skip unreadable files
+            }
+        }
+        else {
+            // In shallow mode, read only the first ~500 bytes to capture frontmatter
+            // without loading the full body — keeps startup fast for large projects.
+            try {
+                const buf = await readFile(fullPath, { encoding: "utf-8" });
+                const head = buf.slice(0, 500);
+                const { frontmatter } = parseFrontmatter(head);
+                description = deriveDescription(frontmatter);
+                if (frontmatter?.status)
+                    status = frontmatter.status;
             }
             catch {
                 // skip unreadable files
@@ -66,13 +99,17 @@ async function walk(dir, root, files, shallow) {
             relativePath: toPosix(relative(root, fullPath)),
             type: classifyFile(entry.name),
             summary,
+            description,
+            status,
         });
     }
 }
 /**
  * Recursively walk the filesystem from `root` and collect all .aide files.
  * Skips node_modules, .git, dist, build, .next, coverage, __pycache__.
- * Reads the first ~1000 bytes of each file to extract the first meaningful body line as summary.
+ * In deep mode: reads full content to extract summary, description, and status.
+ * In shallow mode: reads only the first ~500 bytes per file to extract frontmatter
+ * description and status — summary stays empty but descriptions appear unconditionally.
  */
 export default async function scan(root, path, shallow) {
     const scanRoot = path ? join(root, path) : root;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aidemd-mcp/server",
-	"version": "0.2.4",
+	"version": "0.3.1",
 	"description": "MCP server that teaches any agent the AIDE methodology through tool descriptions and progressive disclosure tooling",
 	"type": "module",
 	"bin": {
@@ -32,6 +32,7 @@
 		"README.md",
 		".aide",
 		".aide/bin",
+		".claude/commands/aide.md",
 		".claude/commands/aide",
 		".claude/agents/aide",
 		".claude/skills"