@aidemd-mcp/server 0.2.0

package/.aide/docs/.aide

@@ -0,0 +1,128 @@
+---
+scope: .aide/docs
+status: aligned
+intent: >
+  Add a References section to the AIDE spec template and methodology so the
+  synthesis agent leaves a human-readable breadcrumb trail of which brain notes
+  it read when writing the Strategy. A reviewer looking at any .aide spec should
+  be able to trace every strategy decision back to the research that informed it,
+  without chasing the agent or re-running the pipeline. The mechanism is zero
+  infrastructure — path plus description, no UUIDs, no frontmatter changes, no
+  machine-readable pointers.
+outcomes:
+  desired:
+    - The AIDE template includes a `## References` section after `## Bad examples`
+      where the synthesis agent logs each brain note it read, as a path plus a
+      one-line description of what it drew from that note.
+    - The aide-spec doc describes the References section alongside the four
+      existing body sections, making clear it is populated by the synthesis agent
+      and serves human auditability, not tooling.
+    - The synthesis agent instructions explicitly require logging every brain note
+      read during strategy writing into the References section, so the breadcrumb
+      trail is a side effect of normal synthesis, not a separate step.
+    - A reviewer can read the References section and understand why each strategy
+      decision was made and what research backed it, even if the original brain
+      notes have moved — the description provides enough context to locate the
+      source again.
+  undesired:
+    - References that are machine-readable metadata (UUIDs, frontmatter fields,
+      structured pointers) rather than a simple human-readable list — this adds
+      infrastructure with no consumer.
+    - A References section that lists notes the agent opened but did not actually
+      use in the Strategy — padding the list destroys the signal that connects
+      each reference to a decision.
+    - References that duplicate the Strategy by restating the finding in full
+      instead of naming the source and what was drawn from it — the description
+      is a breadcrumb, not a summary.
+    - A requirement that references stay valid links — brain notes move, and the
+      description is the fallback by design, not an afterthought.
+---
+
+## Context
+
+The AIDE synthesis agent reads brain notes, distills them into Strategy decisions, and moves on. The finished spec carries the decisions but not the trail -- a reviewer seeing "do X because Y" in the Strategy has no way to verify what research note "Y" came from, whether the agent read it correctly, or whether other notes in the brain contradicted it. The only person who can answer those questions is the agent that wrote the spec, and that agent's context is gone the moment the session ends.
+
+This is an auditability gap. Every other link in the AIDE pipeline is traceable through files: the planner's intent is in the frontmatter, the architect's plan is in the plan.aide, the QA agent's findings are in the todo.aide. But the synthesis agent's reading list -- the bridge between raw research and the decisions in Strategy -- disappears. A reviewer who wants to challenge a strategy decision has to re-search the brain themselves, guess which notes the agent found, and hope nothing has moved since.
+
+The aide-spec doc already permits additional sections beyond the four required body sections (line 137: "Additional sections are allowed when the module needs them"). A References section formalizes the one the synthesis agent should have been leaving all along, without changing the frontmatter contract or adding infrastructure. The description on each entry is the load-bearing part: brain notes move, paths go stale, but a one-line description of what was drawn from a note gives a reviewer enough to relocate the source or judge the decision without it.
+
+## Strategy
+
+**References is a fifth body section, not a frontmatter field.** Adding it to frontmatter would mean every agent that reads the spec pays a token cost for metadata only the reviewer consumes. A body section after Bad examples keeps it out of the machine-readable contract and positions it as human-readable audit material -- the same relationship Bad examples has to outcomes.undesired. The aide-spec doc's existing allowance for additional sections already covers this; what changes is that the template includes it by default and the methodology doc names it alongside the four required sections.
+
+**Each entry is a path plus a one-line description of what was drawn from the note.** The path says where the note lived at synthesis time. The description says what finding or data point the agent pulled into the Strategy. Together they let a reviewer trace a strategy decision back to its source without re-reading the note -- and if the note has moved, the description provides enough context to find it again or judge the decision independently. No UUIDs, no structured metadata, no frontmatter pointers. The format is a flat list, one bullet per note, human-scannable in under thirty seconds. This directly serves the outcome that a reviewer can trace decisions even when original notes have moved.
+
+**Only notes that informed a strategy decision belong in References.** A note the agent opened, scanned, and discarded adds noise that breaks the signal between reference and decision. The test is simple: if removing a reference would leave no strategy decision ungrounded, the reference is padding and should be cut. This mirrors the writing standard already in the aide-spec doc -- "every section must drive a decision; cut anything that doesn't" -- applied to the audit trail itself. This guards against the undesired outcome of a padded list that destroys the connection between each reference and the decisions it supports.
+
+**The synthesis agent logs references as a side effect of normal synthesis, not as a separate step.** The agent already reads brain notes during step 3 of its process and distills them into Strategy during step 5. Logging each note it actually uses into a References section at write time costs one bullet per note and zero additional brain searches. Making it a separate post-hoc step would tempt the agent to reconstruct the list from memory rather than record it live, which defeats the purpose. The agent instructions should add reference-logging to the existing synthesis flow rather than appending a new phase.
+
+**Descriptions are breadcrumbs, not summaries.** A description that restates the full finding duplicates the Strategy and doubles the spec's length for no new information. The description names the source and identifies which data point or pattern was drawn from it -- enough to trace, not enough to replace reading the original. This guards against the undesired outcome where References becomes a shadow copy of Strategy.
+
+**References paths are not required to be valid links.** Brain notes move, vaults restructure, research gets archived. The spec's own intent says descriptions are the fallback by design, not an afterthought. No tooling should validate reference paths, and no agent should treat a stale path as an error. The path is a hint; the description is the contract.
+
+## Good examples
+
+A References section from a spec whose Strategy cites three brain notes:
+
+> ## References
+>
+> - research/cold-email/subject-line-data -- Open-rate benchmarks by subject line length and personalization type; sourced the "under 45 characters, company-name personalization" threshold used in Strategy.
+> - research/cold-email/spam-trigger-patterns -- List of phrases and formatting patterns that trigger spam filters in major providers; informed the "avoid all-caps, exclamation marks, and filler adjectives" constraint.
+> - research/cold-email/reply-rate-studies -- Comparison of CTA styles by reply rate across three SaaS outreach studies; grounded the "single question CTA" decision over multi-option closings.
+
+Each entry names a path, names the specific finding drawn from it, and maps to a visible decision in the Strategy. A reviewer can read the three bullets and know exactly which research backs which decision without opening a single note.
+
+A References section where one note contributed to multiple strategy decisions:
+
+> ## References
+>
+> - research/scoring/digital-presence-signals -- Coverage of which local-business signals (GMB completeness, review velocity, website mobile score) correlate with outreach receptivity; informed both the signal-weighting tiers and the "skip businesses with no web presence" filtering rule.
+> - research/scoring/false-positive-patterns -- Catalogue of signals that look positive but indicate businesses unlikely to convert (e.g., recent rebrand activity inflating web presence scores); grounded the "suppress scores during active rebrand" guard.
+
+The second entry supports a single guard-rail decision. The first supports two. Neither entry restates the full finding -- each names just enough to trace.
+
+## Bad examples
+
+A References section that lists every note the agent opened:
+
+> ## References
+>
+> - research/cold-email/subject-line-data -- Open-rate benchmarks.
+> - research/cold-email/industry-overview -- General overview of cold email as a channel.
+> - research/cold-email/competitor-tools -- List of competing products in the outreach space.
+> - research/cold-email/spam-trigger-patterns -- Spam filter trigger phrases.
+> - research/cold-email/reply-rate-studies -- Reply rate data.
+> - research/cold-email/legal-compliance -- CAN-SPAM and GDPR summary.
+
+The agent opened six notes but only three informed Strategy decisions. "industry-overview" and "competitor-tools" contributed nothing to any decision. "legal-compliance" was read but no compliance decision appears in the Strategy. The list is padded, and a reviewer cannot tell which references are load-bearing. The descriptions are also too terse -- "Open-rate benchmarks" does not say which benchmark or which decision it informed.
+
+A References section that duplicates Strategy:
+
+> ## References
+>
+> - research/cold-email/subject-line-data -- Subject lines under 45 characters with company-name personalization achieve 23% higher open rates than generic lines over 60 characters. Lines using first-name personalization show diminishing returns after the first touchpoint. The optimal range is 38-44 characters for B2B outreach to local service businesses, with the company name placed in the first five words.
+
+This is not a breadcrumb -- it is the full finding restated. The Strategy already contains the decision this data supports. The description should name the source and the data point ("open-rate benchmarks by subject line length; sourced the under-45-character threshold"), not reproduce the analysis.
+
+A References section with machine-readable metadata:
+
+> ## References
+>
+> ```yaml
+> - id: ref-001
+>   path: research/cold-email/subject-line-data
+>   hash: a3f2c1d
+>   accessed: 2025-01-15T14:32:00Z
+>   relevance: 0.92
+>   tags: [open-rate, subject-line, personalization]
+> ```
+
+No consumer exists for this structure. No tool parses it. The hash will be stale by the next vault sync. The relevance score is a number the agent invented. Every field beyond path and description is infrastructure without a consumer -- exactly the kind of overhead the intent says to avoid.
+
+A References section where paths are treated as contracts:
+
+> ## References
+>
+> - ~~research/cold-email/subject-line-data~~ -- **BROKEN LINK: note not found at expected path. Requires investigation before this spec can be trusted.**
+
+The path was never a contract. Brain notes move. The description ("open-rate benchmarks by subject line length; sourced the under-45-character threshold") gives a reviewer everything needed to relocate the source or evaluate the decision on its own merits. Flagging a stale path as a trust-breaking error misunderstands what the reference is for.

package/.aide/docs/agent-readable-code.md

@@ -0,0 +1,74 @@
+# Agent-Readable Code
+
+The outcome of [progressive disclosure](./progressive-disclosure.md). Progressive disclosure is the *contract* — what the writer does (folder-named-after-export, JSDoc on every function, inline narration on orchestrators). Agent-readable code is the *experience* an agent has when that contract is honored: the codebase answers questions at the shallowest tier possible, and agents spend their context window on the task, not on re-learning the repo.
+
+A codebase can follow the tiers mechanically and still be unreadable if the names lie, the files sprawl, or the operational surface is a pile of loose scripts. This note covers the complementary rules that make the contract actually pay off.
+
+## Naming for Agents
+
+Agents read English. Names that are clear to you are clear to the agent — but abbreviations, acronyms, and clever names are not.
+
+```typescript
+// ❌ Agent reads 4 files to figure out what these do
+processData()
+handleStuff()
+doWork()
+utils.ts
+
+// ✅ Agent knows immediately
+validateOrderPayload()
+persistAuditLog()
+formatReceiptEmail()
+createOrder/checkInventory/index.ts
+```
+
+**The folder name is the function name.** `createOrder/checkInventory/index.ts` exports `checkInventory`. No mental mapping required — Tier 1 of progressive disclosure only works if this rule is absolute.
+
+## Cascading Domain Structure
+
+Structure cascades downward through domain layers — never flat. Each level narrows scope, and the folder path reads as a sentence describing what you're looking at.
+
+```
+# ✅ Cascading — each layer narrows scope
+cli/
+├── deploy/
+│   ├── worker/
+│   │   └── index.ts      ← cli > deploy > worker
+│   └── app/
+│       └── index.ts      ← cli > deploy > app
+├── migrate/
+│   └── index.ts
+└── index.ts               ← CLI entry point
+
+# ❌ Flat — everything at one level, names carry all the context
+cli/
+├── deployWorker.ts
+├── deployWorkerNoCache.ts
+├── deployApp.ts
+├── migrateDb.ts
+└── index.ts
+```
+
+Flat structures force redundant prefixes (`deployWorker`, `deployWorkerNoCache`, `deployApp`) because there's no hierarchy to carry context. Cascading structures let each folder carry one word of meaning, and options become siblings or flags at the right depth — not name-encoded duplicates.
+
+This applies everywhere: service modules, CLI commands, API routes, component trees. Think in layers. If you're working on something and notice a flat structure that would read better as a cascade, flag it.
+
+## Eliminate Context Burn
+
+Context burn is any token the agent spends that doesn't help it complete the task. Common sources:
+
+**God files** — A 400-line file with mixed concerns forces the agent to read everything to find the 20 lines it needs. Split by responsibility.
+
+**Dead code** — Commented-out functions, unused imports, deprecated helpers. Delete them. They cost tokens and confuse the agent about what's current.
+
+**Magic strings** — `if (status === "QWFA")` requires the agent to search for what QWFA means. Use enums or named constants.
+
+**Scattered scripts** — 30 scripts in a flat folder with no entry point. The agent can't remember which one solved the same problem yesterday. Consolidate into a CLI.
+
+**Monolith handlers** — A single worker file handling 8 queue types. Split into per-queue subfolders with typed handlers.
+
+## The Test: Would a New Hire Understand?
+
+If a competent developer who has never seen your codebase could navigate to the right file, read the orchestrator, and understand the data flow in under 2 minutes — your code is agent-readable.
+
+If they'd need to grep across 5 files, decode abbreviations, and mentally reconstruct the call chain — your agent will too, except it'll do it every session.

package/.aide/docs/aide-spec.md

@@ -0,0 +1,201 @@
+# AIDE Spec
+
+**Autonomous Intent-Driven Engineering (AIDE)** puts intent at the center of everything. Not code, not tests, not prompts — intent. A short `.aide` doc lives next to the code it governs, and that doc is the contract. Architects plan from it. Implementors build from it. QA validates against it. When the intent changes, the code changes. When the code drifts from the intent, the code is wrong — full stop. Across a project, these docs form a **cascading intent tree**: a hierarchy of `.aide` specs rooted at the project level, each child narrowing the intent of its parent. Agents navigate the tree from root to leaf to understand the full context behind any module.
+
+The name is a double entendre. AIDE is also an **AI Domain Expert** — the pipeline includes a domain expert agent that fills the brain with domain knowledge and a strategist agent that distills that knowledge into the spec's body sections. A human domain expert can fill the brain the same way the agent would — the strategist reads the brain regardless of who wrote to it. But domain expertise is a perk, not the point. Intent is the first-class citizen; research is just one way to inform it.
+
+The brain can be filled by the domain expert agent, by a human domain expert, or by both. The pipeline downstream — strategist, architect, implementor, QA — treats the brain's content as authoritative regardless of the source. The developer decides what source is appropriate for the domain. The methodology applies to any domain; only the source of the brain's knowledge changes.
+
+The research layer is optional. It runs only when the module needs domain knowledge that isn't already available — either from the user's interview context or from a prior session that already filled the brain. If the brain already has coverage, or the user holds the knowledge directly, the research phase is skipped and the strategist fills the body sections from what's available. Once the intent doc exists, the rest of the methodology treats it as authoritative regardless of how it got there.
+
+AIDE is a three-layer model:
+
+- **The brain holds durable knowledge.** External to the project — a vault, an MCP memory store, a team wiki. Two kinds of content live here: domain research (what the module is supposed to do in the real world) and engineering conventions (how this team writes code — the coding playbook). Different agents pull different slices: the strategist draws on domain research when filling the spec body; the architect draws on the coding playbook when translating intent into a plan. Neither bloats the repo with reference material every session has to re-read.
+- **The `.aide` file holds the intent.** A short, structured brief living next to the orchestrator it governs. Strategy, outcomes, anti-patterns, domain examples. No code. This is the contract.
+- **The code holds itself.** The implementation is ephemeral — if the intent changes, the code changes. The spec persists; the code is its current expression.
+
+## File Types
+
+| File            | Purpose                                                                                                                                                                                                                                                                 |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.aide`         | The intent spec. Default and sufficient for most modules.                                                                                                                                                                                                               |
+| `intent.aide`   | Same as `.aide`, renamed for disambiguation when a `research.aide` exists in the same folder.                                                                                                                                                                           |
+| `research.aide` | Optional. Co-located research fallback when no external brain is available. Prefer external memory (brain, MCP) over this — every file in the repo fills context whether the agent reads it or not, and agents don't always honor "skip this" instructions.              |
+| `plan.aide`     | The architect's implementation plan. Checkboxed steps the implementor executes top-to-bottom. Lives next to the `.aide` it implements. See [plan.aide spec](./plan-aide.md).                                                                                             |
+| `todo.aide`     | QA re-alignment document. Captures where implementation drifted from intent, with per-issue misalignment tags and a retro section. One `todo.aide` per QA loop. See [todo.aide spec](./todo-aide.md).                                                                    |
+
+**Default to `.aide` alone.** Push research out to the brain or an MCP memory store. Only split into `research.aide` + `intent.aide` when the research genuinely can't live elsewhere. Never have both `.aide` and `intent.aide` in the same folder.
+
+## Where `.aide` Files Live
+
+`.aide` files live next to orchestrator `index.ts` files — **never next to helpers**. An orchestrator coordinates a pipeline; its spec provides the domain context for that pipeline. Helpers are small, focused functions — their folder name and code are self-explanatory.
+
+**Placement rule:** if a folder contains an orchestrator that coordinates helpers, it can have a `.aide`. If it contains a single-purpose helper, it doesn't. The one exception is the project root intent spec at `.aide/intent.aide` — the top of the cascading intent tree. It lives inside the `.aide/` folder because the project root has no orchestrator, and naming it `intent.aide` avoids ambiguity with the `.aide/` directory itself. All other specs inherit from it, directly or transitively.
+
+### Inheritance
+
+`.aide` files at deeper levels inherit the context of their parent. A deeply nested spec doesn't re-explain the parent's strategy — that's in the parent spec. It only describes what makes *this* submodule succeed or fail. Each nested spec stays lean because the parent already carries the shared intent context.
+
+A submodule is any meaningful subdivision of the parent module — a pipeline stage, a strategy variant, a resource type, a rendering target, a channel, a subdomain of the problem. The tree reflects the composition of the module.
+
+### Bootstrapping a project
+
+Every intent tree needs a root. The project root intent spec lives at `.aide/intent.aide` — inside the `.aide/` folder alongside the methodology docs, not as a bare file at the repo root. Its `scope` is `.` (the project root) or the project name. Its `intent` describes the project's purpose at the highest level. Its `outcomes` define the project-wide success criteria and failure modes that every deeper spec inherits.
+
+`aide_init` creates this file during project bootstrap. On the first `/aide` run against a new project, the spec writer creates it as Stage 1 before any module-level specs exist.
+
+Without a root intent spec, child specs have nothing to inherit from. They are forced to restate project-level context that belongs at the root — or worse, they omit it entirely, leaving gaps the architect and QA agents can't fill. The root spec establishes the project-wide contract; everything below narrows it.
+
+### Example: full project intent tree
+
+```
+project-root/
+├── .aide/
+│   ├── intent.aide                    ← project root intent (top of the intent tree)
+│   └── docs/                          ← methodology docs (not specs)
+│       └── ...
+├── src/
+│   ├── .aide                          ← src-level intent (narrows project root)
+│   └── service/<feature>/
+│       ├── .aide                      ← feature strategy (narrows src-level)
+│       ├── index.ts
+│       ├── <submodule-a>/
+│       │   ├── .aide                  ← submodule-a strategy (inherits feature)
+│       │   ├── index.ts
+│       │   ├── <submodule-a1>/
+│       │   │   ├── .aide              ← submodule-a1 intent (inherits submodule-a)
+│       │   │   ├── index.ts
+│       │   │   └── <helper>/
+│       │   │       └── index.ts       ← helper (no .aide)
+│       │   ├── <submodule-a2>/
+│       │   │   ├── .aide
+│       │   │   └── index.ts
+│       │   └── <submodule-a3>/
+│       │       ├── .aide
+│       │       └── index.ts
+│       └── shared/
+│           └── <helper>/
+│               └── index.ts           ← helper (no .aide)
+```
+
+The intent tree runs from `.aide/intent.aide` at the top down to the deepest feature submodule. Orchestrators have specs. Helpers don't. Deeper specs inherit from shallower ones. The shape of the tree matches the shape of the module — whatever best expresses its composition.
+
+## Code Alongside the Spec
+
+A `.aide` spec is one layer of context. The code sitting next to it is another. The spec carries the *intent and strategy*; the code carries the *shape and flow*, self-documented through progressively deeper tiers so an agent can stop at the shallowest one that answers its question.
+
+See [Progressive Disclosure](./progressive-disclosure.md) for the full pattern: folder structure at Tier 1, JSDoc on every function at Tier 2, inline step-by-step comments on orchestrators at Tier 3. Together, the spec and the progressively-disclosed code give an agent everything it needs without reading helper bodies.
+
+## Spec Structure
+
+Every `.aide` file follows the same structure. **Frontmatter is required, and the five body sections below are required.** Without structure, agents generate freeform specs that don't scale — repeatability comes from the template.
+
+The canonical template lives at [AIDE Template](./aide-template.md). Agents should read the template before writing a new spec.
+
+### Frontmatter (required)
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `scope` | Yes | The module path this spec governs. One spec, one scope. |
+| `description` | Yes | One-line purpose statement. Makes ancestor chains in `aide_discover` self-contained — agents reading the chain understand what each spec governs without opening it. |
+| `intent` | Yes | One paragraph, plain language: what this module is *for*. The north star every other field serves. Written so a human reading it cold understands the purpose in ten seconds. Everything in `outcomes` must be traceable back to this sentence. |
+| `outcomes.desired` | Yes | The success criteria. One or more statements describing what the module should produce. The QA agent measures actual output against this list. Keep it short — every extra entry dilutes the intent. |
+| `outcomes.undesired` | Yes | The failure modes. Outputs that look correct but violate intent — the green-tests-bad-output failures. The QA agent checks these explicitly even when tests pass. |
+| `status` | No | Alignment state set by tooling, not by the spec writer. Omit for pending (default — no review has happened). Set to `aligned` by the aligner agent after verification; set to `misaligned` by the QA agent when drift is detected. Surfaced inline in `aide_discover` output so agents reading the ancestor chain see alignment state without opening each spec. |
+
+**Scope, description, intent, outcomes. That's the whole contract.** `status` is the one lifecycle field that exists, added alongside the tooling that reads it — the `aide_discover` ancestor chain surfaces it inline, and `aide_validate` warns when it is absent. Its three states are implicit pending (field absent — no review has happened), `aligned` (set by the aligner agent after verification), and `misaligned` (set by the QA agent when drift is detected). The field is never set by the spec writer directly; it is a tool-verified signal. No other lifecycle fields exist — `revision` and similar state encodings are deliberately omitted. Git history tracks change; the rule "if the intent changes, it's a new spec" is the forcing function.
+
+`intent` states the purpose; `outcomes` is the intent-engineering contract that operationalizes it — desired is the target, undesired is the tripwire. Both outcome lists are two sides of the same declaration, and both must serve the intent above them.
+
+### Cascading intent tree
+
+The **cascading intent tree** (or **intent tree**) is the hierarchy of `.aide` specs from `.aide/intent.aide` at the project root down to the deepest module-level spec. Intent flows downward: each child spec inherits everything above it and narrows it to the slice of the problem it owns. An agent navigating the intent tree reads from root to leaf — the full chain gives the complete context for any module.
+
+`intent` inherits down the tree just like the rest of the spec. A nested `.aide` doesn't restate the parent's purpose — it narrows it to the slice of the problem *this* module owns. The agent reads the parent spec first, then the child, and the child's intent is understood as a specialization of the parent.
+
+A child spec should:
+
+- **Narrow the purpose** to the specific submodule it owns, not restate the parent-level mission.
+- **Add outcomes** that only make sense at this level (submodule-specific formats, thresholds, shapes).
+- **Add tripwires** tied to the unique failure modes of this submodule — not duplicate parent-level tripwires that apply to the whole tree.
+
+A child spec should **not**:
+
+- Restate the parent's purpose, invariants, or universally-applicable tripwires.
+- Re-cite research that supports parent-level decisions.
+- Describe behavior that any sibling submodule shares.
+
+**Rule of thumb:** if a child `.aide` could be copy-pasted into a sibling folder and still make sense, it's too generic — push that content up to the parent. A child spec should only contain what's *specific to this submodule*.
+
+**Outcomes cascade strictly.** A child's outcomes don't replace the parent's — they narrow them. Every ancestor's `outcomes.desired` and `outcomes.undesired` still apply to the child's output. A submodule whose local output satisfies its own outcomes but violates a parent's intent is wrong in the context of the whole application. Agents must walk the full intent tree from root to leaf (via `aide_discover`) before judging whether a module's output is valid — local validity is necessary but not sufficient.
+
+### Body sections (required)
+
+Every spec has the same five body sections. See [AIDE Template](./aide-template.md) for the full template with inline guidance.
+
+- **`## Context`** — Why this module exists and the domain-level background an agent needs to make good decisions. No code.
+- **`## Strategy`** — The synthesized approach. How this module honors its `intent` and achieves its `outcomes.desired`. Research pulled from the brain gets distilled here into decisions — specific tactics, thresholds, structural choices, and the reasoning behind each one. Write in decision form ("do X because Y"), not description form. Cite data inline. No code.
+- **`## Good examples`** — Concrete domain output that illustrates success. Real output, not code. Pattern material for QA agents verifying the system's output.
+- **`## Bad examples`** — Concrete domain output that illustrates failure, especially the almost-right-but-wrong cases. Expands on `outcomes.undesired` with recognizable failure material.
+- **`## References`** — A flat list of brain notes the synthesis agent read during strategy writing, each as a path plus a one-line description of what was drawn from it. Its purpose is human auditability: a reviewer can trace every strategy decision back to the research that informed it without re-running the pipeline. Populated by the synthesis agent as a side effect of normal synthesis — not filled manually after the fact. Paths are not required to be valid links; the description is the fallback by design.
+
+Additional sections (constraints, state machine, etc.) are allowed when the module needs them. These five are the floor.
+
+### Frontmatter vs Strategy — what each layer owns
+
+- **Frontmatter (`intent` + `outcomes`)** declares *what* the module is for and *what* counts as success or failure. It is a contract — short, falsifiable, machine-readable.
+- **`## Strategy` body** answers *how* — the intent combined with research from the brain, compressed into actionable decisions the architect can turn into a plan and the implementor can execute without re-reading the sources.
+
+If the strategy contradicts the intent, the intent wins and the strategy is wrong. If a new research finding changes the strategy but not the intent, rewrite the strategy in place. If the intent itself changes, the scope and identity of the spec have changed — consider whether it should be a new spec entirely.
+
+## Writing Standards
+
+- **Specs are contracts, not essays.** Every section must drive a decision. Cut anything that doesn't.
+- **Include data.** "Short subject lines work better" is useless. Concrete numbers with source attribution are actionable.
+- **No code.** No filenames, no type signatures, no function bodies, no worked code examples. The code documents itself when it's written. The spec describes intent; the implementer figures out the code. Including code in a spec wastes tokens documenting something ephemeral.
+- **Domain examples only.** When you show an example, show what the *output* should look like in the domain (a real email, a real report section, a real API response), not what the code that produces it looks like.
+- **Each spec stands alone** except for inheritance from parent `.aide` files. Don't cross-reference sibling specs.
+- **Decisions, not descriptions.** Each paragraph in `## Strategy` should state a concrete choice and the reasoning that justifies it. An architect reading the strategy should know what to do *and* why that approach beats the alternatives, so the plan it produces can handle unanticipated edge cases without re-opening the spec.
+- **Citations ride alongside decisions.** When a decision is grounded in external data or research, name the source and the finding in-line. Don't footnote; don't link out to sources a downstream agent would have to chase.
+
+## When to Write a `.aide`
+
+| Scenario | `.aide` needed? |
+|----------|-----------------|
+| New feature with unknown domain | Yes — at the feature root, and in submodules that implement domain logic |
+| New feature with clear requirements | Yes — at the feature root; submodule specs only if domain context is needed |
+| Adding a submodule to an existing feature | Only if the submodule implements domain logic beyond what the code expresses |
+| Simple helper or utility | No — the folder name and code are the spec |
+| Bug fix or simple change | No |
+
+The test: if the module implements domain logic that requires context beyond the code itself, it gets a `.aide`. If the folder name + code are self-explanatory, it doesn't.
+
+## Intent Engineering
+
+A `.aide` file captures more than what to build — it captures **intent**. Without intent, an agent runs the tests, sees green, and calls it done. But green tests don't mean the feature works. Hidden failures only surface when someone understands what the code is *supposed* to accomplish.
+
+The `outcomes` block gives the QA agent that understanding. `desired` tells it what to aim for; `undesired` tells it what to watch for even when everything looks fine. An output that is technically valid but violates the spec's intent — that's a hidden failure. The `undesired` list catches it. Without the spec, the agent would never flag it.
+
+## The Agent Pipeline
+
+AIDE isn't one agent doing everything. It's a pipeline of specialized agents, each with one job and a narrow set of inputs. Every stage runs in a fresh context — no agent carries conversation from a prior stage. Handoff is via files only: `.aide`, `plan.aide`, `todo.aide`, brain notes. Splitting the roles is how each agent keeps its context small enough to stay accurate.
+
+The pipeline is driven by an **orchestrator** (`/aide`) that interviews the user, detects pipeline state from existing files, and spins up each agent in sequence. The orchestrator can resume mid-pipeline — if a user starts a new session and runs `/aide`, it picks up where the last session left off by checking which files exist.
+
+1. **Spec Writer** (`/aide:spec`). Takes the orchestrator's delegation context — gathered from its interview with the user — and distills it into `.aide` frontmatter: `scope`, `intent`, `outcomes.desired`, `outcomes.undesired`. No body sections, no research, no code. The spec writer structures intent into a falsifiable contract; the orchestrator owns the user conversation. The frontmatter is presented to the user for confirmation before proceeding.
+
+2. **Domain Expert** (`/aide:research`). *Optional.* Fills the brain with domain knowledge — the same role a human domain expert would play, automated. Runs only when the module requires domain knowledge that isn't already available. Ingests sources (vault notes, web search, MCP memory), synthesizes patterns, resolves conflicts, and persists the result to the brain filed by **domain** (e.g., `research/email-marketing/`), not by project — domain knowledge is reusable. If no external brain is available, falls back to a co-located `research.aide`. The domain expert never writes `.aide` files; its sole output is reusable knowledge.
+
+3. **Strategist** (`/aide:synthesize`). Reads the brain's domain knowledge and distills it into the `.aide` body sections: `## Context`, `## Strategy`, `## Good examples`, `## Bad examples`, `## References`. Uses `aide_discover` to walk the intent tree. Every strategy decision must trace to an outcome; anything that doesn't serve the intent gets cut.
+
+4. **Architect agent** (`/aide:plan`). Translates the complete `.aide` spec into a `plan.aide` — a checkboxed implementation plan the implementor executes top-to-bottom. Reads the `.aide` for what the module must produce, pulls the coding playbook from the brain for how this team writes code, and reads the current codebase for what already exists. Output: file placement, naming, sequencing, contracts, reuse decisions, test steps. No code. The plan is presented to the user for approval before build begins. See [plan.aide spec](./plan-aide.md).
+
+5. **Implementor agent** (`/aide:build`). Executes `plan.aide`. Reads the plan and the `.aide` spec, writes the code, writes the tests, checks each plan step off as it completes, runs tests until green. The same agent type also runs the fix loop (`/aide:fix`) — one session per `todo.aide` item, clean context each time. If the plan is ambiguous, escalates back to the architect rather than inventing an answer.
+
+6. **QA agent** (`/aide:qa`). Uses `aide_discover` to walk the full intent tree, compares actual output against `outcomes.desired`, checks for anything in `outcomes.undesired`, and writes a `todo.aide` re-alignment document next to the spec. Each issue traces to a specific outcome and is tagged with the pipeline stage where intent was lost (`misalignment`). Includes a `## Retro` section capturing what would have caught the issues earlier. Does not propose solutions. See [todo.aide spec](./todo-aide.md).
+
+The fix loop cycles between QA and Implementor: QA produces `todo.aide`, the implementor fixes one item per session in clean context, QA re-validates. When all items are resolved, the orchestrator promotes the retro findings to the brain at `process/retro/` as durable process learning.
+
+Every agent reads the same `.aide` spec. No agent needs a human to explain what to build or how to build it — the context is already in the files.
+
+See [Automated QA](./automated-qa.md) for the full QA verification loop.

package/.aide/docs/aide-template.md

@@ -0,0 +1,110 @@
+# AIDE Template
+
+> **For agents: this file is a scaffold, not a reference.** If you are creating a new `.aide` file, copy the fenced block in [The Template](#the-template) below verbatim into the new file, then replace every `<…>` placeholder with content specific to the module being specced. The prose under each body heading is *instructional guidance written for you* — overwrite it with real content as soon as you have it. Do not paraphrase this page into the new spec, and do not copy any text that lives *outside* the fenced block.
+
+## How to use this template
+
+1. Create the new `.aide` file at the correct location (next to the orchestrator `index.ts` it governs, or at `.aide/intent.aide` for the project root — see [placement rules](./aide-spec.md#where-aide-files-live)).
+2. Copy the entire fenced block under [The Template](#the-template) into the new file, without the surrounding backticks.
+3. Fill in the frontmatter: replace each `<…>` placeholder with a concrete value.
+4. For each of the first four body sections (`## Context`, `## Strategy`, `## Good examples`, `## Bad examples`), read the guidance paragraph, then **replace it** with real content for this module. The guidance is a prompt for you — it does not belong in the finished spec. For `## References`, do not replace the guidance paragraph manually — the synthesis agent populates this section from its reading log during synthesis. If you are the synthesis agent, log every brain note you actually used (path + one-line description of what you drew from it for the Strategy); discard notes you opened but did not use.
+5. A finished `.aide` file contains zero `<…>` placeholders and zero guidance paragraphs from this template.
+
+## The Template
+
+````markdown
+---
+scope: <module path this spec governs, e.g. service/<module-name>. One spec, one scope.>
+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, written so a human reading it cold understands
+  the purpose of this module in under ten seconds. State the problem being solved
+  and the conditions of success in terms of the consumer/user/recipient of the
+  module's output — not in terms of the code that will implement it. This is the
+  north star every other field must serve: every entry in "outcomes" below must
+  be traceable back to this sentence. If the intent changes, the revision bumps
+  and prior builds are invalidated.
+outcomes:
+  desired:
+    - <One concrete, observable success criterion. Describe what the module's output must achieve for the intent to be satisfied. Keep it specific — every extra entry dilutes the intent, so aim for the minimum set that fully expresses success. 2-5 bullets is usually right.>
+    - <Success criteria are what the QA agent compares actual output against. Write them so they are falsifiable: a reviewer should be able to look at a real output and say yes or no without hedging.>
+    - <If a criterion has a measurable threshold (a rate, a count, a length), state it. If it's qualitative, state the quality in terms concrete enough to judge.>
+  undesired:
+    - <A failure mode that violates the intent. Especially important: the kind of output that looks correct on the surface and passes tests but misses the point. This is the tripwire list the QA agent checks even when everything else looks fine.>
+    - <Call out the almost-right answers a lazy or pattern-matching agent would produce. If there's a phrase, shape, or shortcut that consistently signals failure in this domain, name it here.>
+    - <Undesired outcomes are how intent survives green tests. Without this list, an agent will ship output that is technically valid and actually wrong.>
+---
+
+## Context
+
+<!-- REPLACE THIS COMMENT with the Context body. Rules for what goes here:
+  - Explain why this module exists and the domain-level problem it solves.
+  - Write for a strong generalist engineer who does not know this specific domain.
+  - Cover the constraints that shape the problem, the stakes of getting it wrong,
+    and why a naive implementation would fail.
+  - Do not restate context already carried by a parent `.aide`; child specs inherit.
+  - Only include context specific to this module's scope.
+  - No code, no filenames, no type signatures.
+  Delete this entire HTML comment once the real Context is written. -->
+
+## Strategy
+
+<!-- REPLACE THIS COMMENT with the Strategy body. Rules for what goes here:
+  - Describe how this module honors its `intent` and hits `outcomes.desired`
+    without tripping `outcomes.undesired`.
+  - Distill research (from the brain or an adjacent `research.aide`) into
+    actionable decisions.
+  - Write in decision form, not description form: each paragraph states a
+    concrete choice (tactic, threshold, structural decision, sequencing rule)
+    and the reasoning or data that justifies it.
+  - An architect agent must be able to read this and know what to do AND why
+    that approach beats the alternatives, so it can produce a plan the
+    implementor can execute without further architectural decisions.
+  - Cite sources inline, compressed: name the source, name the number or finding
+    that matters, move on. No footnotes.
+  - No code, no filenames, no type signatures, no function names, no worked
+    code examples. If the implementation were rewritten from scratch this
+    section should survive untouched.
+  Delete this entire HTML comment once the real Strategy is written. -->
+
+## Good examples
+
+<!-- REPLACE THIS COMMENT with concrete domain examples of success for this
+  module's output. Rules for what goes here:
+  - Real domain output, not code. If the module produces text, show a passage
+    that works. If it produces a structured record, show a record that is
+    correct in spirit, not just in schema. If it produces a decision, show a
+    correct one with enough context to see why it is correct.
+  - Examples are pattern material for QA agents verifying output — pick ones
+    that illustrate the intent, not the edge cases.
+  Delete this entire HTML comment once the real examples are written. -->
+
+## Bad examples
+
+<!-- REPLACE THIS COMMENT with concrete domain examples of failure. Rules:
+  - Show the almost-right answer: output that looks valid, passes tests, and
+    still violates the intent.
+  - Show the specific phrases, structures, or shortcuts that signal failure
+    in this domain.
+  - Each bad example must make it obvious WHY it is bad — either inline or
+    by pairing it with the matching good example above.
+  - The goal is recognizable failure modes, not an enumeration.
+  Delete this entire HTML comment once the real examples are written. -->
+
+## References
+
+<!-- The synthesis agent populates this section during synthesis — do not fill
+  it manually after the fact. Rules for what goes here:
+  - Each entry is a bullet: the brain note path, then ` -- `, then a one-line
+    description of what was drawn from that note for the Strategy.
+  - Only notes that actually informed a strategy decision belong here. Notes
+    the agent opened but did not use are excluded — padding the list destroys
+    the signal between each reference and the decision it supports.
+  - Descriptions are breadcrumbs: name the source and the specific finding or
+    data point drawn from it. Do not restate the full finding; do not duplicate
+    the Strategy.
+  - Paths are hints, not contracts. Brain notes move; the description is the
+    fallback. No tooling should validate reference paths, and no agent should
+    treat a stale path as an error.
+  Delete this entire HTML comment once the real references are written. -->
+````