---
name: aide
description: >
  AIDE pipeline orchestrator — entry point for the conversational
  spec → research → synthesize → plan → build → QA → fix flow. Drives each
  phase by delegating to specialized subagents (aide-spec-writer,
  aide-architect, aide-implementor, aide-qa, etc.). Invoked when the user
  types /aide, asks to start an AIDE feature pipeline, asks to resume an
  in-flight pipeline, or asks to align/refactor specs across the intent
  tree. **MANDATORY**: this skill begins with a non-skippable boot sequence
  — call `aide_info`, gate on brain status, read 6 methodology docs in
  parallel, run `aide_discover`, read `.aide/session.aide` if it exists.
  You MUST execute boot before reading or acting on the user's request,
  even when you think you have enough context. Skipping boot means
  orchestrating a methodology you don't know — you will guess at file
  formats, agent routing, and pipeline state, and produce drift.
---

# /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.

This skill is the source of truth for the orchestrator. The `/aide` slash command (in `.claude/commands/aide.md`) is a thin signpost that routes to this skill — the prose lives here so the methodology, boot sequence, and constraints surface together with the skill's frontmatter description in the available-skills listing.

---

## MANDATORY BOOT SEQUENCE

**STOP. Do not respond to the user's request yet. Do not analyze it. Do not classify it.**

Boot fires on EVERY invocation of this skill — no exceptions. It is **sequential, not parallel** — brain status gates everything else. There is no point loading docs and the intent tree if the brain isn't wired.

### Step 1 — Call `aide_info`

This is your only first call. No `Read`, no `aide_discover`, no other tool.

### Step 2 — Brain status (hard gate)

The brain is the pipeline's durable memory. If it isn't wired, the pipeline can't run.

`aide_info` returns one of four `brain.status` values. Branch on them exactly:

- **`ok`** — continue to Step 3.

- **`no-brain-aide`** — the `brain.aide` config file is missing. STOP boot. Do NOT read docs. Do NOT call `aide_discover`. Tell the user in one line, conversational tone — e.g.:

  > The brain config file (`brain.aide`) is missing — let's set that up first.

  Then invoke the config flow:

  ```
  Skill(skill="aide:brain", args="config")
  ```

  The config flow scaffolds `brain.aide` and syncs it into `.mcp.json`. After it returns, halt — the user must run `npx @aidemd-mcp/server@latest sync` and then re-run `/aide`.

- **`no-mcp-entry`** — the brain backend is not wired into `.mcp.json`. STOP boot. Do NOT read docs. Do NOT call `aide_discover`. Tell the user in one line — e.g.:

  > The brain isn't wired up yet — let's fix that first.

  Then invoke the config flow:

  ```
  Skill(skill="aide:brain", args="config")
  ```

  After the skill returns, halt — the skill itself handles the sync and asks the user to restart.

- **`mcp-drift`** — `brain.aide` and `.mcp.json` disagree about the brain entry. STOP boot. Do NOT read docs. Do NOT call `aide_discover`. Tell the user in one line — e.g.:

  > Brain config is out of sync — let's fix that first.

  Then invoke the config flow:

  ```
  Skill(skill="aide:brain", args="config")
  ```

  After the skill returns, halt — the skill itself handles the sync and asks the user to restart.

### Step 3 — Outdated artifacts (passive notification)

If `outdated` from `aide_info` is non-empty, mention it once and continue:

> `N` AIDE artifact(s) are outdated — run `/aide:upgrade` when you'd like to update.

Outdated is informational, not a gate.

### Step 4 — Load methodology + intent tree (parallel)

Now — and only now — run these 8 calls in parallel:

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. `Read` → `.aide/docs/brief-aide.md`
6. `Read` → `.aide/docs/session-aide.md`
7. `aide_discover` (MCP tool, no arguments)
8. `Read` → `.aide/session.aide` (only if it exists — the project-root pipeline-position log; if absent, no feature pipeline is in flight)

**Only after all calls return** may you read the user's request, consult the sections below, and decide what to do.

**Why this matters:** 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. Skipping boot means guessing.

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 6 methodology 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`, `brief.aide`, `session.aide`, or any code files yourself
- Create or update `.aide/session.aide` yourself — even though you know the pipeline-state content, the orchestrator delegates the write to `aide-spec-writer` (the same agent that writes `.aide` frontmatter); the orchestrator decides WHEN and WHAT, the spec-writer transcribes into canonical form
- 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, **conditional**): `aide-domain-expert` — only when the spec-writer signals "Research needed"
- Stage 3 (Synthesize, **conditional**): `aide-strategist` — only when the spec-writer signals "Strategy needed"
- Stage 4 (Plan): `aide-architect` — runs against either filled body + `brief.aide` (Shape A) OR frontmatter-only spec + user implementation context the orchestrator passes in (Shape B)
- 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`
- `.aide/session.aide` CREATE and UPDATE: `aide-spec-writer` (same structured-file writer that owns `.aide` frontmatter — see "Session state management" below)
- Completion cleanup (delete per-module ephemerals; delete `session.aide` at feature close): `aide-maintainer` (post-QA, after retro promotion)
- Bug investigation / non-pipeline work: `aide-explorer` (read-only) or `general-purpose` (if it needs to write files)

**Stages 2 and 3 are skipped by default.** Most modules are navigation stubs whose intent and outcomes alone are sufficient for planning. Research runs only when the domain is genuinely unknown territory; synthesize runs only when the *domain* (not the implementation) has non-obvious decisions worth persisting alongside the spec. The spec-writer signals both needs in its return; the user confirms; the orchestrator routes accordingly. When both are skipped, the orchestrator passes the user's implementation instructions directly to the architect — the architect plans against frontmatter + user context + coding playbook.

**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 6 methodology docs during boot (calls 1–6). 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 docs you read at boot 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.
- **`brief-aide.md`** — what a per-module `brief.aide` looks like. Tells you what the strategist authors during synthesize and the architect refines during plan.
- **`session-aide.md`** — what the project-root `.aide/session.aide` looks like. Tells you the pipeline-position log format if a feature is in flight.

You also read **`brief-aide.md`** at boot — `brief.aide` files are per-module pipeline state you detect during resume. The strategist authors them during synthesize; the architect refines them during plan; the implementor and QA consume them; the maintainer agent deletes them after QA passes.

You also read **`session-aide.md`** at boot — `session.aide` is a single project-root pipeline-position log at `.aide/session.aide` (replacing the legacy `handoff.aide` pattern). It tracks the in-flight feature's state, settled architectural decisions, and where the cycle paused. If it exists, read it during boot (Step 4 call 8) — it tells you exactly where to resume. It is deleted only when the feature is fully completed.

**You do NOT need to read** `progressive-disclosure.md`, `agent-readable-code.md`, `automated-qa.md`, `cascading-alignment.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 7). 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" or "just plan it" → **Stage 4 (Plan)**, skipping research and synthesize. The spec is treated as a frontmatter-only navigation stub; the user's request itself is the implementation context the architect needs.
- "synthesize" or "fill the body" → **Stage 3 (Synthesize)** — explicit opt-in even when defaults would skip it
- "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)
- "handoff", "save session state", "record where we are", "/aide:handoff" → **Session Handoff** — delegate to `aide-spec-writer` to write `.aide/session.aide`. CREATE if file is missing, UPDATE if it exists. The Session state management section below covers what content to gather and supply in the delegation prompt.

**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), no `plan.aide` | **Decision gate** — body sections being absent is valid (synthesize was skipped). Ask the user: "Do you want me to plan this directly, or run synthesize first to fill body sections?" Default: route to **Plan** (gather user implementation context, hand to architect). Route to **Synthesize** only on explicit user request. |
| `.aide` exists with body sections filled, no `brief.aide` | **Synthesize** — body landed without brief, route back to strategist to author the brief |
| `.aide` (any shape) and `plan.aide` does not yet exist | **Plan** — spec ready, no plan written yet |
| `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, hand off to maintainer to delete `brief.aide` (if present)/`plan.aide`/`todo.aide`, report completion. Also: if this was the last in-flight feature, the maintainer deletes `.aide/session.aide` |

## Session state management — `.aide/session.aide`

`.aide/session.aide` is the project-wide pipeline-position log. It is durable across cycles within a single feature, deleted only at feature close. **You decide WHEN to write it; the `aide-spec-writer` agent transcribes the content you supply into the canonical format.** You never write the file yourself — that violates the Delegation-Only constraint — but you ARE the source of truth for its content, because you hold the conversation context that knows what stage paused, what was settled, and where to resume.

The user-facing entry point is **`/aide:handoff`** — the command they (or you) invoke to trigger a session.aide write. The command file at `.claude/commands/aide/handoff.md` describes the operation. You can delegate to the spec-writer either proactively (you decide a transition is worth recording) or reactively (the user explicitly invokes `/aide:handoff`). Same agent, same flow either way.

Why the spec-writer owns this: it is already the "format orchestrator-supplied context into a canonical AIDE file" agent (the same role it plays for `.aide` frontmatter). `session.aide` is a different file type with different rules (no Brevity Contract, no domain reasoning, operational state) but the same operation shape: receive content from the orchestrator, transcribe into canonical sections, write. The maintainer is the cleanup agent — it owns deletion of pipeline ephemerals, including `session.aide` at feature close, but it does NOT write.

### When to delegate a CREATE

Delegate `aide-spec-writer` to CREATE `.aide/session.aide` when ALL of these are true:

- The feature is large enough to span multiple build/QA/fix cycles, multiple architectural reworks, or multiple sessions of conversation — single-cycle builds never need a session.aide
- You can name at least: the feature intent (one line), the current pipeline stage, and what the next agent must do (the `## Where this cycle stopped` content)

Common trigger points:

- A multi-plan feature has just finished Stage 4 (Plan) and is about to enter a multi-cycle build
- The user has just paused the pipeline for review and the conversation will resume in a future session
- An architectural rework has been settled that downstream agents must not re-debate
- An anti-regression invariant has been added that every future build phase must check

### When to delegate an UPDATE

Delegate `aide-spec-writer` to UPDATE `.aide/session.aide` whenever a meaningful pipeline-state transition occurs:

- A pipeline stage completes for the in-flight feature
- A new architectural decision is settled and downstream agents need to honor it (append at the next stable decision number — the spec-writer will preserve numbering)
- A new anti-regression invariant is added
- The cycle pauses for user review and the `## Where this cycle stopped` content needs to change
- An open question resolves or a new one surfaces

### What you supply in the delegation prompt

The spec-writer is a transcriber, not an author. Your CREATE/UPDATE delegation prompts MUST supply the content; the spec-writer never invents. Include:

- **For CREATE:** feature intent (one line); state summary prose (current stage, what was just done, what is paused); architectural intent decisions (numbered list of what's settled, if any); anti-regression invariants (bullet list, if any); `## Where this cycle stopped` content (the next agent's instructions); process discipline notes (optional); open questions (optional). **Be explicit that this is a `session.aide` CREATE** — the spec-writer's default operation is `.aide` frontmatter; you must name the operation type so it dispatches correctly.
- **For UPDATE:** a change description (what transition occurred); section-targeted edits (e.g., "append decision #3: ..."; "rewrite `## Where this cycle stopped` to: ..."); numbered references to preserve. **Be explicit that this is a `session.aide` UPDATE.**

If you don't have the content, don't delegate yet — that's a sign you haven't gathered enough conversation context to make the write meaningful.

### What the spec-writer rejects

- Silent overwrites of an existing `session.aide` (use UPDATE, not CREATE)
- Updates against a non-existent `session.aide` (use CREATE, not UPDATE)
- Ambiguous prompts that don't name the operation type (`.aide` write vs. `session.aide` CREATE/UPDATE), the section target, or the content source
- CREATE prompts missing feature intent or `## Where this cycle stopped` content

If the spec-writer REFUSES, fix your prompt and re-delegate — never try to write the file yourself.

## Pipeline

### Stage 1: Interview → `aide:spec`

**Your job (orchestrator):** YOU own the user interview. The spec-writer does NOT talk to the user — it formats the context you pass it into canonical `.aide` frontmatter. Interview the user thoroughly enough to give the spec-writer everything it needs:

- What module or feature is this for? Where does it live?
- What is the module's purpose, in domain terms? (Drives `description` and `intent`.)
- What does success look like? What does failure look like? Especially the almost-right-but-wrong kind. (Drives `outcomes.desired` and `outcomes.undesired`.)
- **Implementation context, if any.** If the user already has a clear picture of how this should be built (helpers to reuse, libraries, sequencing, type shapes), capture it verbatim — you'll pass it to the architect later if synthesize is skipped. If the user wants to think aloud about the *domain* but doesn't have implementation details, that's a signal that synthesize may be warranted.
- Any domain knowledge already available in the brain? (Determines whether to skip research later.)

If the interview leaves gaps, the spec-writer will return to you listing what's missing — you re-interview the user and re-delegate.

**Then delegate** to the `aide-spec-writer` agent (via Agent tool, `subagent_type: aide-spec-writer`). The agent will:
- Format the intent context you supplied into `.aide` frontmatter only (`scope`, `intent`, `outcomes.desired`, `outcomes.undesired`)
- Enforce brevity caps and forbidden-content rules
- Present the frontmatter to the user for confirmation
- Return two routing signals: **Research needed** (yes/no) and **Strategy needed** (yes/no)

After the agent returns, relay the frontmatter to the user, confirm satisfaction, and use the spec-writer's signals to decide what stage runs next.

### Routing decision after Stage 1

The spec-writer's two signals plus the user's confirmation determine the next stage:

| Research needed | Strategy needed | Next stage |
|---|---|---|
| no | no | **Skip to Stage 4 (Plan).** Pass the user's implementation context to the architect. The spec is a frontmatter-only navigation stub. |
| no | yes | **Skip to Stage 3 (Synthesize).** Brain already has the research; strategist fills body sections. |
| yes | yes | **Stage 2 (Research) → Stage 3 (Synthesize) → Stage 4 (Plan).** Full pipeline. |
| yes | no | Unusual. Confirm with the user — research without strategy means we're filling the brain but not the spec body. Only proceed if the user wants the brain entry without persisting domain reasoning in the spec itself. |

**Default expectation: most modules are "no, no" → straight to Plan.** Synthesize earns its place only when the *domain* — not the implementation — has decisions worth persisting alongside the spec. If the user is uncertain, ask: "Is there domain reasoning here that you'd want to read in 6 months, beyond what intent + outcomes already say?" If no, skip synthesize.

### Stage 2: Research → `aide:research` (conditional)

**Run only if Stage 1 returned "Research needed: yes".** Otherwise skip.

**Your job (orchestrator):** Confirm with the user that research should run, then delegate.

**Then delegate** to the `aide-domain-expert` agent (via Agent tool, `subagent_type: aide-domain-expert`). The agent will:
- Search web, brain, 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` (conditional)

**Run only if Stage 1 returned "Strategy needed: yes".** Otherwise skip.

**Your job (orchestrator):** Confirm research is complete (or that the brain already has it), 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 entries for domain knowledge
- Fill ALL FIVE body sections — `## Context`, `## Strategy`, `## Good examples`, `## Bad examples`, `## References` (partial bodies are forbidden)
- Author the sibling `brief.aide` carrying implementation commitments

After the agent returns, present the completed spec AND the new `brief.aide` to the user for review before advancing.

### Stage 4: Plan → `aide:plan`

**Your job (orchestrator):** Confirm any prior stages are complete, then delegate to the architect with the right context for whichever shape the spec is in.

**Shape A delegation (synthesize ran):** The spec has filled body sections and a sibling `brief.aide`. Delegation prompt: path to `.aide` and `brief.aide`, plus the rich `aide_discover(path)` output for the target module. The architect reads both, pulls the playbook, scans the codebase, writes `plan.aide`, updates `brief.aide`.

**Shape B delegation (synthesize was skipped):** The spec is frontmatter-only with no `brief.aide`. Delegation prompt MUST include:
- Path to the `.aide` spec
- The rich `aide_discover(path)` output for the target module
- **The user's implementation instructions verbatim** — whatever they told you during the Stage 1 interview about how this should be built (helpers to reuse, libraries, sequencing, type shapes, constraints). This is the architectural context the strategist would otherwise have provided. Quote it; do not paraphrase.

The architect reads the spec, pulls the playbook, scans the codebase, writes `plan.aide`, and creates `brief.aide` only if planning surfaces commitments worth recording (Shape B usually doesn't need one).

**PAUSE for user approval.** After the agent returns, present `plan.aide` (and `brief.aide` if it exists) to the user. Do not proceed to build until the user explicitly approves. If the user requests changes, re-delegate to the architect — do NOT edit any file 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 entries it needs — the implementor will load those entries 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:

1. **Promote retro findings from `todo.aide` to the brain at `process/retro/`** BEFORE any deletion. Use the brain MCP write tool. The promoted entry's path is the receipt the maintainer verifies in the next step.

2. **Determine whether this is the last in-flight feature.** If `.aide/session.aide` exists, its `## Where this cycle stopped` section should already indicate closure for this feature. Run `aide_discover` to confirm no other module has a `brief.aide`/`plan.aide`/`todo.aide` outside the one being closed. If yes, the maintainer will also delete `.aide/session.aide` in this delegation; if no, leave `session.aide` for the next feature to consume.

3. **Delegate to the `aide-maintainer` agent** (via Agent tool, `subagent_type: aide-maintainer`). The delegation prompt MUST include:
   - The **target module path** (where `brief.aide`/`plan.aide`/`todo.aide` live)
   - The **brain path of the promoted retro** (e.g. `process/retro/2026-05-08-<module>.md`) — the maintainer reads it back to verify the promotion landed before deleting the source `todo.aide`
   - **Whether to also delete `.aide/session.aide`** — explicitly authorize it only when this is the last in-flight feature (per Step 2)

   The maintainer verifies preconditions (every `todo.aide` and `plan.aide` checkbox is checked; the named retro entry exists in the brain; if `session.aide` deletion is requested, no other in-flight modules remain), deletes `todo.aide` → `plan.aide` → `brief.aide` (and `session.aide` if authorized), and returns CLEANED / REFUSED / PARTIAL with the list of files touched. If REFUSED, route to the appropriate fix step (e.g. `/aide:fix` for unchecked `todo.aide` items) and re-delegate after.

4. **Report completion to the user** with a summary of what was built and which artifacts the maintainer cleaned up.

Do NOT delete any of these files yourself — always delegate to the maintainer. The maintainer is the only agent in the pipeline authorized to delete pipeline ephemerals.

### Refactor → `aide:refactor`

**This is NOT part of the feature pipeline.** Refactor is a separate flow with two modes selected by the `--specs` flag.

| Mode | When to use | Agents |
|---|---|---|
| Default (no flag) | Code drifts from coding playbook conventions on a module that already works and passed QA | `aide-auditor` → `aide-implementor` → `aide-qa` |
| `--specs` | `.aide` specs have grown bloated and violate the [Brevity Contract](../../.aide/docs/aide-spec.md#brevity-contract) | `aide-aligner` → `aide-spec-writer` and/or `aide-strategist` → `aide-aligner` |

**Detecting refactor intent:**

- "Refactor", "clean up code", "convention drift", "playbook conformance" → default mode
- "Slim the specs", "the .aide files are too long", "spec bloat", "trim", "compress the specs", or any reference to spec rot / oversized intent docs → `--specs` mode
- When `aide_discover` output shows `status: misaligned` on multiple nodes, ask the user whether the misalignment is cascade drift or bloat — if bloat, route to `--specs` mode

**Refactor requires a path argument.** If the user doesn't provide one, ask for it. Never run a full-app refactor unscoped.

#### Mode 1 — Code-drift refactor (default)

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.

#### Mode 2 — Spec-bloat sweep (`--specs`)

This mode is the canonical batched, cascade-aware fix flow when the aligner reports `spec-bloat` items. It exists to avoid the per-spec round-trip pain of running `/aide:spec` or `/aide:synthesize` against every bloated spec one at a time — instead, every rewrite happens in one coordinated sweep with batched diff review.

1. **Run the aligner.** Delegate to `aide-aligner` scoped to the provided path with explicit focus on the brevity and sibling-redundancy passes (the aligner runs all three passes by default — cascade, brevity, sibling-redundancy). The aligner writes `todo.aide` at every spec where bloat is found, tagged `Misalignment: spec-bloat`. This step is mandatory even if a recent alignment ran — bloat may have shifted since.

2. **Collect spec-bloat findings.** Read every `todo.aide` written or updated in step 1. For each, partition the items by which field is bloated:
   - **Frontmatter bloat** (`description`, `intent`, `outcomes.desired`, `outcomes.undesired` over caps or carrying forbidden content) → routes to `aide-spec-writer`
   - **Body bloat** (`## Context`, `## Strategy`, `## Good examples`, `## Bad examples` over caps) → routes to `aide-strategist`
   - **Sibling redundancy** flagged at children → routes the duplicated content up to the parent (rewrite the parent, slim the children)

3. **Sequence top-down.** Rewrite parent specs before children. A child that prunes content already covered by its parent must know what the parent will carry *after* the rewrite, not before. Specs at the same depth can run in parallel.

4. **Spawn rewriter agents.** For each bloated spec at the current depth:
   - Frontmatter: delegate to `aide-spec-writer` (Agent tool, `subagent_type: aide-spec-writer`). Include the bloated frontmatter, the ancestor chain from `aide_discover`, and the relevant `todo.aide` items.
   - Body: delegate to `aide-strategist` (Agent tool, `subagent_type: aide-strategist`). Include the bloated body, the ancestor chain, sibling specs, and the relevant `todo.aide` items.
   - Both needed: run frontmatter first, then body against the freshly-tightened frontmatter.

5. **Pause for batched diff review.** Present every rewrite as a before/after diff, grouped by spec. The user approves, rejects, or edits per spec. **Do not land any rewrite without explicit approval per spec** — bloat removal is a judgment call and the user is the authority.

6. **Land approved rewrites.** Apply approved diffs. Skip rejections; the user accepted the bloat as intentional. Mark rejected `todo.aide` items resolved-by-acceptance with a one-line note.

7. **Re-run the aligner.** A second alignment pass confirms which `spec-bloat` items cleared and surfaces any new drift the rewrites introduced.

8. **Report.** Total `.aide` files audited, total bloat items found, items resolved per spec, items rejected as intentional, items remaining (if any), and the final aligner verdict.

### 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 broken down by category (cascade / brevity / sibling-redundancy), and `todo.aide` paths for any misaligned nodes. Present this to the user. The recommended next step depends on the dominant category:
   - **Cascade or sibling-redundancy issues dominate** → suggest `/aide:spec` on the flagged specs to resolve them one at a time
   - **Brevity (`spec-bloat`) issues dominate** → suggest `/aide:refactor --specs <path>` for a batched cascade-aware sweep instead of per-spec rewrites

**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`, and entries persisted to the brain.
- **`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. (Synthesize, when it runs, also pauses to present the filled body — but synthesize is conditional, so it isn't always in the path.)
- **Stages 2 and 3 are conditional, not default.** The default path is Stage 1 → Stage 4 → 5 → 6 → 7. Research runs only when the spec-writer signals "Research needed: yes". Synthesize runs only when "Strategy needed: yes". Most modules are navigation stubs — frontmatter-only specs whose intent + outcomes + the user's implementation context are sufficient for planning. Adding synthesize when it isn't earned bloats the spec tree and burns context for downstream agents.
- **For Shape B plans, pass the user's implementation context to the architect verbatim.** When you skip synthesize, the user's words from the Stage 1 interview ARE the architectural input. Quote them in the architect's delegation prompt; do not paraphrase or summarize.
- **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.** Research entries go to `research/<domain>/` in the brain, 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.
- **`.aide/session.aide` is written by `aide-spec-writer`, deleted by `aide-maintainer`, never by you.** You hold the content (current stage, settled decisions, where the cycle stopped) because the conversation belongs to you. But the canonical-format write belongs to the spec-writer (same agent that owns `.aide` frontmatter). Delegate a CREATE at pipeline kick-off for multi-cycle features and an UPDATE at every meaningful state transition. If you find yourself about to call Write/Edit on `.aide/session.aide`, STOP — construct a delegation prompt instead.