@aidemd-mcp/server 0.2.2 → 0.2.4

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

@@ -0,0 +1,64 @@
+---
+name: aide-spec-writer
+description: "Use this agent when you need to write the .aide intent spec frontmatter from a user interview. This agent captures intent — scope, outcomes, failure modes — and produces the frontmatter contract that every downstream phase works from. It does NOT fill body sections, write code, or delegate to other agents.\n\nExamples:\n\n- Orchestrator delegates: \"Interview the user about the new scoring module and write the .aide frontmatter\"\n  [Spec writer interviews, captures intent, writes frontmatter, presents for confirmation]\n\n- Orchestrator delegates: \"The user wants to add email templates. Capture the intent as a .aide spec\"\n  [Spec writer asks about purpose, consumers, success/failure criteria, writes frontmatter]"
+model: opus
+color: purple
+memory: user
+---
+
+You are the intent capture specialist for the AIDE pipeline — the agent that distills the orchestrator's delegation context into the precise contract every downstream agent works from. You take the intent context the orchestrator gathered from the user and produce `.aide` frontmatter that is specific enough to be falsifiable and broad enough to survive implementation changes. Your output is the north star the architect plans against, the implementor builds toward, and the QA agent validates against.
+
+## Your Role
+
+You receive a delegation from the orchestrator containing the intent context it gathered from its interview with the user. You distill that context into `.aide` frontmatter. You do NOT fill body sections (Context, Strategy, examples) — those come from the strategist after research.
+
+**You do NOT delegate to other agents.** You write the frontmatter and return results to the caller.
+
+## Input Expectations
+
+You will be given:
+- A target module or directory where the `.aide` file should live
+- Intent context gathered by the orchestrator from its conversation with the user: what the module is for, what success looks like, what failure looks like, and whether domain knowledge is available
+
+The orchestrator owns the user conversation. Your job is to take the context it provides and structure it into falsifiable frontmatter. If the delegation context is insufficient to write specific outcomes, return to the orchestrator listing what's missing — it will gather more context from the user and re-delegate.
+
+## Writing Protocol
+
+1. Read the AIDE template from the methodology docs before writing — copy the fenced template block into the new file
+2. Decide the filename:
+   - Use `.aide` if no `research.aide` exists in the target folder
+   - 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
+   - `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
+
+## Return Format
+
+When you finish, return:
+- **File created**: path to the `.aide` file
+- **Frontmatter summary**: the scope, intent, and outcome count
+- **Research needed**: yes/no — whether the domain requires research before synthesis
+- **Recommended next step**: `/aide:research` or `/aide:synthesize`
+
+Present the frontmatter to the user for confirmation before finalizing.
+
+## What You Do NOT Do
+
+- You do not fill body sections (Context, Strategy, examples). That is the strategist's job after research.
+- You do not write code, type signatures, or file paths in the spec.
+- You do not make architectural decisions. You capture intent; the architect decides how.
+- You do not expand scope. One spec, one scope.
+- You do not interview the user. The orchestrator owns the user conversation and passes context to you via the delegation prompt.
+- You do not delegate to other agents. You return results to the caller.
+
+## Update your agent memory
+
+As you write specs, record useful patterns about:
+- Intent phrasings that produced clear, falsifiable outcomes
+- Common gaps in delegation context that required returning to the orchestrator
+- Domain areas where research is typically needed vs already known

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

@@ -0,0 +1,67 @@
+---
+name: aide-strategist
+description: "Use this agent when the .aide frontmatter is complete and the brain has research — this agent synthesizes that research into the spec's body sections (Context, Strategy, Good/Bad examples, References). It reads from the brain, not the web. It does NOT delegate to other agents.\n\nExamples:\n\n- Orchestrator delegates: \"Synthesize the research into the outreach module's .aide body sections\"\n  [Strategist reads brain research, fills Context/Strategy/examples, presents for review]\n\n- Orchestrator delegates: \"The scoring spec frontmatter is done and brain has research — fill the body\"\n  [Strategist reads spec frontmatter + brain research, writes body sections]"
+model: opus
+color: purple
+memory: user
+mcpServers:
+  - obsidian
+---
+
+You are the strategist for the AIDE pipeline — the agent that bridges raw research and the intent spec's body sections. You read the brain's research notes, cross-reference them against the spec's frontmatter, and produce the Context, Strategy, examples, and References that give the architect everything needed to plan. You think in decisions, not descriptions — every paragraph you write names a choice and justifies it.
+
+## Your Role
+
+You receive a delegation to fill the body sections of a `.aide` spec whose frontmatter is already complete. You read the brain's research, synthesize it, and write the body. This is a fresh session — you did not run the research phase and carry no prior context.
+
+**You do NOT delegate to other agents.** You do your synthesis and return results to the caller.
+
+## Input Expectations
+
+- The target `.aide` file must have complete frontmatter (scope, intent, outcomes.desired, outcomes.undesired)
+- The brain must have research notes filed under the relevant domain
+- If either is missing, stop and escalate
+
+## Synthesis Process
+
+1. **Read the frontmatter.** The intent paragraph and outcomes are your compass — every body section must serve them.
+
+2. **Search the brain.** Use `mcp__obsidian__search_notes` to find research notes filed under the relevant domain (e.g., `research/cold-email/`). Read all relevant notes. If no brain is available, check for a co-located `research.aide`.
+
+3. **Fill `## Context`.** Why this module exists, the domain-level problem, constraints that shape it. Write for a generalist engineer who does not know this domain. No code. Do not restate context carried by a parent `.aide`.
+
+4. **Fill `## Strategy`.** Distill research into decisions. Each paragraph names a concrete choice — a tactic, threshold, structural decision, sequencing rule — and the reasoning or data that justifies it. Cite sources inline, compressed. Write in decision form, not description form. No code.
+
+5. **Fill `## Good examples`.** Concrete domain output that illustrates success. Real output, not code. Pattern material for the QA agent.
+
+6. **Fill `## Bad examples`.** The almost-right failures. Output that looks valid but violates intent. Recognizable failure modes the QA agent should watch for.
+
+7. **Fill `## References`.** Log every brain note you actually used during steps 2–4. For each note, write one bullet: the note's path, then ` -- `, then a one-line description of what specific finding or data point you drew from it for the Strategy. Do not list notes you opened but did not use — a padded list destroys the signal between each reference and the decision it supports. Descriptions are breadcrumbs: name the source and the finding, not a summary of the note.
+
+8. **Verify traceability.** Every strategy decision must trace back to an `outcomes.desired` entry or guard against an `outcomes.undesired` entry. Cut anything that doesn't serve the intent.
+
+## Return Format
+
+When you finish, return:
+- **File modified**: path to the `.aide` file
+- **Sections filled**: which body sections were written
+- **Research sources used**: which brain notes informed the synthesis — this is the same data as the spec's `## References` section, surfaced here for the caller and in the spec for the reviewer
+- **Traceability check**: confirm every strategy traces to an outcome
+- **Recommended next step**: `/aide:plan` for the architect
+
+Present the completed spec to the user for review before finalizing.
+
+## What You Do NOT Do
+
+- You do not do external research. You read the brain. If the brain is insufficient, escalate back to `/aide:research`.
+- You do not write code, file paths, type signatures, or function names in the spec.
+- You do not make architectural decisions. You provide the what and why; the architect provides the how.
+- You do not modify the frontmatter. That was locked in during the spec phase.
+- You do not delegate to other agents. You return results to the caller.
+
+## Update your agent memory
+
+As you synthesize research into specs, record useful context about:
+- Synthesis patterns that produced clear, actionable strategy sections
+- Domain areas where research was insufficient and needed more coverage
+- Spec structures that worked well for specific types of modules

package/.claude/skills/brain/.aide

@@ -0,0 +1,229 @@
+---
+scope: .claude/skills/brain
+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
+  tells the agent to use the Obsidian MCP and read the vault's own CLAUDE.md
+  for navigation instructions, then execute whatever the user asked. All
+  vault-specific structure — directory layout, hub locations, routing tables,
+  crawling rules — lives in the vault's CLAUDE.md (already provisioned by
+  provisionBrain), never in the skill prompt. This separation means every
+  user gets the same shipped skill while their vault teaches the agent their
+  specific organization.
+outcomes:
+  desired:
+    - The skill prompt's only structural assumption is that the vault has a
+      CLAUDE.md at its root. It reads that file first, then follows whatever
+      navigation instructions the vault CLAUDE.md provides to fulfill the
+      user's request. No other vault paths, directory names, or hub locations
+      appear in the skill prompt.
+    - The skill works for any vault organization without modification. A user
+      who structures their vault differently from the AIDE defaults gets
+      correct agent behavior as long as their vault CLAUDE.md describes their
+      structure — the skill never contradicts or overrides vault-level
+      navigation instructions.
+    - The skill template ships through the existing initContent registry and
+      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:
+      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.
+  undesired:
+    - A skill prompt that hardcodes vault navigation rules, directory
+      paths, hub locations, or routing tables. This creates two sources
+      of truth — the skill and the vault CLAUDE.md — and they drift apart
+      the moment the user reorganizes their vault. The vault CLAUDE.md
+      is the single source of truth for vault structure; the skill is a
+      thin dispatcher that defers to it.
+    - A skill prompt that duplicates the wikilink crawling protocol,
+      decision protocol, or "where to find things" table that already
+      lives in the vault CLAUDE.md. Restating these rules in the skill
+      means updating two files on every protocol change, and the copy
+      in the skill will be the one that goes stale first.
+    - A skill that assumes the Obsidian MCP server is named a specific
+      key or that vault content follows AIDE's default scaffold structure.
+      Users who provisioned their vault before AIDE or who customized
+      the scaffold must not get broken behavior from a skill that
+      expected the defaults.
+    - A skill prompt that blurs the boundary with study-playbook by
+      including coding-playbook-specific navigation logic. The two
+      skills have distinct scopes; /brain should not subsume or
+      duplicate study-playbook's domain.
+---
+
+## Context
+
+The AIDE pipeline gives agents access to the user's Obsidian vault through
+two complementary skills. The first — study-playbook — is a specialist: it
+navigates the coding-playbook hub top-down to load conventions relevant to
+a coding task. But agents also need to reach vault content that has nothing
+to do with coding conventions — research notes, project context, environment
+details, identity, references, kanban boards, session logs. Without a
+general-purpose entry point, those agents either call the Obsidian MCP
+tools with no guidance on how the vault is organized (producing random
+searches that miss the structure) or the user manually teaches each agent
+the vault layout in every session.
+
+The vault CLAUDE.md — already provisioned by provisionBrain — solves this
+by encoding the vault's navigation intelligence in one place: the crawling
+protocol, the decision protocol, the where-to-find-things table. Any agent
+that reads the vault CLAUDE.md before doing anything else gets the full
+navigation playbook. The missing piece is a skill that tells agents to do
+exactly that: read the vault CLAUDE.md first, then execute the user's
+request using whatever navigation rules the vault provides.
+
+The design constraint is separation of concerns. The vault CLAUDE.md is
+the single source of truth for vault structure. The skill is a thin
+dispatcher that defers to it. If the skill restates any navigation rules,
+two sources of truth exist and the skill's copy will be the one that goes
+stale first — because users customize their vault CLAUDE.md but never
+modify shipped skills.
+
+## Strategy
+
+**The skill prompt is a three-step dispatcher, not a navigation guide.**
+The prompt tells the agent: (1) use the Obsidian MCP to read the vault's
+root CLAUDE.md, (2) follow whatever navigation instructions that file
+provides, (3) fulfill the user's request. No additional structure is
+needed. This mirrors the study-playbook pattern — study-playbook says
+"read the playbook hub, follow the structure top-down" without embedding
+the hub's content. The /brain skill says "read the vault CLAUDE.md, follow
+its rules" without embedding the vault's navigation tables. Both skills
+are generic dispatchers; all domain-specific intelligence lives in the
+vault itself. (Source: study-playbook SKILL.md pattern; provisionBrain
+vault CLAUDE.md template.)
+
+**No vault paths, directory names, or hub locations appear in the skill
+prompt.** The only structural assumption is that the vault has a CLAUDE.md
+at its root. provisionBrain already provisions this file with the crawling
+protocol, decision protocol, and where-to-find-things table. The skill
+trusts that content to be correct and complete — it never supplements,
+overrides, or paraphrases it. This means a user who reorganizes their vault
+updates their vault CLAUDE.md once and every agent session using /brain
+immediately reflects the change, with zero modifications to the shipped
+skill. (Source: provisionBrain spec, desired outcome on vault CLAUDE.md
+scoped to navigation only.)
+
+**The skill does not name the Obsidian MCP server key.** Different users
+may have different MCP server names depending on when they provisioned or
+whether they use a custom setup. The skill prompt refers to Obsidian MCP
+capabilities generically — "use the Obsidian MCP" — without assuming the
+server is registered under a specific key like "obsidian". The agent
+discovers the available MCP tools from its tool list at session start.
+(Source: undesired outcome on assuming specific MCP server key names.)
+
+**Scope boundary with study-playbook is enforced by omission.** The skill
+prompt contains no reference to the coding playbook, no mention of
+hub-first navigation specific to playbook sections, and no task routing
+logic. study-playbook owns the coding-playbook domain exclusively. /brain
+is the catch-all for everything else in the vault. If a user asks a
+/brain-invoked agent about coding conventions, the vault CLAUDE.md's
+decision protocol will route it to the study-playbook skill — the /brain
+skill does not need to handle that redirect itself because the vault
+CLAUDE.md already does. (Source: scaffoldCommands spec on skill scope
+separation; study-playbook SKILL.md scope restriction.)
+
+**The skill template ships through the existing initContent and
+installSkills pipeline.** It is registered in DOC_PATHS under a canonical
+name and in SKILL_DOCS with a host path, then installed to the host's
+skill directory by installSkills using the same idempotency contract as
+study-playbook: existing files are left untouched and reported as
+"exists", new files are created from the canonical template read through
+initContent. Adding the /brain skill is a two-line registration in
+initContent — one entry in DOC_PATHS, one entry in SKILL_DOCS — plus
+the template file itself. No new installation machinery is needed.
+(Source: initContent DOC_PATHS and SKILL_DOCS registries; installSkills
+planner-only contract.)
+
+**The skill template follows the SKILL.md format established by
+study-playbook.** It has a frontmatter block with name and description,
+a title heading, a brief purpose statement, and numbered steps. The
+steps are deliberately fewer and simpler than study-playbook's because
+the /brain skill delegates all navigation complexity to the vault
+CLAUDE.md rather than encoding its own multi-step crawling protocol.
+(Source: study-playbook SKILL.md structure.)
+
+## Good examples
+
+A developer types `/brain` and asks "what research do we have on cold
+email deliverability?" The agent reads the vault's root CLAUDE.md, finds
+the where-to-find-things table pointing research to the `research/`
+directory, uses `search_notes` scoped to `research/` with the query
+"cold email deliverability", reads the matching notes, and returns a
+synthesis. The skill prompt contributed exactly three instructions — read
+the vault CLAUDE.md, follow its rules, do what the user asked. Everything
+else came from the vault itself.
+
+A user has reorganized their vault so research lives under `domains/`
+instead of `research/`. They updated their vault CLAUDE.md's
+where-to-find-things table accordingly. The next time an agent uses
+/brain to look up research, it reads the updated table and searches
+`domains/` correctly. The shipped skill template was never modified.
+
+The skill prompt reads:
+
+> Read the vault's root CLAUDE.md using the Obsidian MCP. Follow the
+> navigation instructions it provides — crawling protocol, decision
+> protocol, lookup tables — to find and read the vault content relevant
+> to the user's request. Return what you found.
+
+No vault paths. No directory names. No crawling rules. No routing tables.
+Three sentences, full generality.
+
+A host project runs `aide_init` for the first time. The init summary
+shows `skills/brain/SKILL.md: created` alongside
+`skills/study-playbook/SKILL.md: exists`. The brain skill installed
+through the same pipeline as study-playbook with no special handling.
+
+## Bad examples
+
+A skill prompt that says "Read `research/` for research notes, read
+`projects/` for project context, read `kanban/board.md` for tasks."
+This duplicates the where-to-find-things table from the vault CLAUDE.md.
+The moment the user renames `kanban/` to `tasks/` and updates their
+vault CLAUDE.md, the skill prompt contradicts it — and the agent sees
+two conflicting sets of instructions in the same session.
+
+A skill prompt that includes the wikilink crawling protocol: "Hub notes
+are navigation, not content. Depth starts at content notes. Follow links
+1-2 levels deep." This is a verbatim copy of rules already in the vault
+CLAUDE.md. When provisionBrain updates the crawling protocol (for
+instance, changing the depth recommendation from 1-2 to 2-3), the skill
+still says 1-2. Two copies, one stale.
+
+A skill prompt that says "Use `mcp__obsidian__read_note` to read the
+vault CLAUDE.md." This hardcodes the MCP tool name, which assumes the
+Obsidian server is registered as "obsidian" in the host's MCP config.
+A user who registered it under a different key gets a broken tool
+reference. The skill should refer to the Obsidian MCP generically and
+let the agent discover the tool names from its available tool list.
+
+A skill prompt that includes "For coding conventions, use the
+study-playbook skill instead." This is coding-playbook-specific routing
+logic that belongs in the vault CLAUDE.md's decision protocol, not in
+the /brain skill. The skill should have no awareness of study-playbook's
+existence or domain — the vault CLAUDE.md handles the routing.
+
+A skill prompt that is 80 lines long with detailed step-by-step
+instructions for navigating different vault areas. This defeats the
+thin-dispatcher pattern. The study-playbook skill is longer because it
+encodes a generic crawling protocol the playbook hub does not carry.
+The /brain skill should be shorter because the vault CLAUDE.md already
+carries all the navigation intelligence — the skill just points to it.
+
+## References
+
+All domain knowledge for this spec was sourced from codebase files, not
+from external brain notes. The sources that informed strategy decisions:
+
+- `.claude/skills/study-playbook/SKILL.md` -- The thin-dispatcher pattern: a skill that says "read the hub, follow its structure" without embedding domain-specific content, establishing the template /brain follows.
+- `src/tools/init/provisionBrain/.aide` -- The vault CLAUDE.md template content and scoping rules (navigation only, no project instructions), confirming what the /brain skill can assume exists at the vault root.
+- `src/tools/init/provisionBrain/index.ts` -- The exact VAULT_CLAUDE_MD_TEMPLATE text provisioned into the vault, confirming it contains the crawling protocol, decision protocol, and where-to-find-things table the /brain skill defers to.
+- `src/tools/init/initContent/index.ts` -- The DOC_PATHS and SKILL_DOCS registries showing how study-playbook is registered, establishing the pattern for registering /brain as a second skill.
+- `src/tools/init/initContent/.aide` -- The single-reader invariant and enumeration rules confirming skill templates ship through initContent, not through direct filesystem reads.
+- `src/tools/init/scaffoldCommands/.aide` -- The study-playbook scope boundary: the skill is a generic crawling protocol with no environment-specific content, confirming /brain must maintain the same separation.
+- `.aide/intent.aide` -- The root spec's two-delivery-channel rule and progressive-disclosure-at-the-delivery-layer principle, confirming skills must be thin pointers to deep content, not content carriers themselves.
+

package/.claude/skills/brain/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: brain
+description: >
+  General-purpose interface to the user's Obsidian vault. Reads the vault's
+  root CLAUDE.md and follows its navigation instructions to find and return
+  vault content relevant to the user's request — research, project context,
+  environment, identity, references, or any other vault content. Use this
+  skill for any vault query that is not specifically about coding conventions.
+---
+
+# /brain — Access Vault Knowledge
+
+Read the user's Obsidian vault and return the content relevant to their request.
+
+---
+
+## Step 1: Read the Vault CLAUDE.md
+
+Use the Obsidian MCP to read the vault's root CLAUDE.md.
+
+This file contains all navigation intelligence for the vault — crawling
+protocol, decision protocol, and a table of where to find different types
+of content. Read it before doing anything else.
+
+---
+
+## Step 2: Follow the Navigation Instructions
+
+Execute the navigation steps the vault CLAUDE.md provides to find the content
+relevant to the user's request. Do not supplement, override, or paraphrase
+the vault's navigation rules — defer to them entirely.
+
+---
+
+## Step 3: Fulfill the User's Request
+
+Return what you found from the vault, synthesized in response to what the
+user asked.
+
+---
+
+## Navigation Rules
+
+- **Read the vault CLAUDE.md first.** Do not search, list directories, or
+  read any other file before reading the vault's root CLAUDE.md.
+- **Defer to the vault CLAUDE.md's navigation rules.** Do not supplement,
+  override, or paraphrase them. The vault CLAUDE.md is the single source
+  of truth for how this vault is organized.

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

@@ -0,0 +1,115 @@
+---
+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
+  its navigation instructions — through the existing initContent/installSkills
+  pipeline, with the doc hub updated to reflect the new skill count.
+---
+
+## Plan
+
+### 1. Create the canonical SKILL.md template
+
+- [x] Create `.claude/skills/brain/SKILL.md` following the same structural
+  pattern as `.claude/skills/study-playbook/SKILL.md`: YAML frontmatter with
+  `name` and `description`, a title heading, a brief purpose statement, and
+  numbered steps.
+- [x] The frontmatter `name` field is `brain`. The `description` field is a
+  one-line summary scoped to general-purpose vault access — contrast with
+  study-playbook's coding-playbook-only scope.
+- [x] The prompt body is a three-step dispatcher (per the spec's Strategy
+  section): (1) use the Obsidian MCP to read the vault's root CLAUDE.md,
+  (2) follow whatever navigation instructions that file provides, (3) fulfill
+  the user's request. No additional structure beyond these three steps.
+- [x] The prompt must NOT contain: vault directory paths, hub locations,
+  routing tables, the wikilink crawling protocol, MCP tool names (like
+  `mcp__obsidian__read_note`), references to study-playbook, or
+  coding-playbook-specific navigation logic. Refer to the Obsidian MCP
+  generically — "use the Obsidian MCP" — so the agent discovers tool names
+  from its available tool list.
+- [x] The only structural assumption is that the vault has a CLAUDE.md at its
+  root. The spec's good-example prompt is the reference:
+  "Read the vault's root CLAUDE.md using the Obsidian MCP. Follow the
+  navigation instructions it provides — crawling protocol, decision protocol,
+  lookup tables — to find and read the vault content relevant to the user's
+  request. Return what you found."
+- [x] Add a Navigation Rules section (like study-playbook has) with just two
+  rules: (a) read the vault CLAUDE.md first, before doing anything else, and
+  (b) defer to whatever navigation rules the CLAUDE.md provides — do not
+  supplement, override, or paraphrase them.
+- [x] The total prompt should be significantly shorter than study-playbook's
+  (~80 lines). Target under 40 lines. The vault CLAUDE.md carries all
+  navigation intelligence; the skill is a thin pointer.
+
+### 2. Register the skill in initContent and verify the pipeline
+
+- [x] 2a. In `src/tools/init/initContent/index.ts`, add `"skills/brain"` to
+  the `DOC_PATHS` registry, mapping to `".claude/skills/brain/SKILL.md"`.
+  Place it after the existing `"skills/study-playbook"` entry.
+- [x] 2b. In the same file, add a second entry to the `SKILL_DOCS` array:
+  `{ canonical: "skills/brain", hostPath: "brain/SKILL.md" }`. Place it after
+  the study-playbook entry.
+- [x] 2c. Run `rtk vitest run src/tools/init/initContent/index.test.ts` to
+  confirm the existing tests still pass — the new registry entry should not
+  break anything since it just adds a new key that resolves to a real file.
+- [x] 2d. Run `rtk vitest run src/tools/upgrade/index.test.ts` to confirm the
+  upgrade pipeline's skill iteration still works. The `listSkills` mock in
+  those tests returns an empty array, so the new entry should not affect them.
+
+### 3. Update the doc hub skill count
+
+- [x] In `.aide/docs/index.md`, update the Skills section to reflect two
+  shipped skills instead of one. Add a row for `brain` to the skill table
+  with purpose: "General-purpose vault access — read the vault CLAUDE.md,
+  follow its navigation rules, fulfill the user's request".
+- [x] Update the prose line above the table from "one canonical skill" to
+  "two canonical skills".
+
+### 4. Add a regression test for the new skill's canonical content
+
+- [x] In `src/tools/init/initContent/index.test.ts`, add a test that calls
+  `readCanonicalDoc("skills/brain")` and asserts the result equals the bytes
+  read directly from `.claude/skills/brain/SKILL.md` via `readFileSync`. This
+  follows the exact pattern of the existing `"returns disk bytes verbatim for
+  aide-spec"` test.
+- [x] Run `rtk vitest run src/tools/init/initContent/index.test.ts` to confirm
+  the new test passes.
+
+### 5. Verify end-to-end installation and build
+
+- [x] Run `rtk tsc` to confirm the TypeScript build passes with the new
+  registry entries.
+- [x] Run `rtk vitest run` to confirm all tests pass project-wide.
+
+## Decisions
+
+**Thin dispatcher over navigation guide.** The spec is explicit: the skill
+prompt is three sentences, not eighty lines. The vault CLAUDE.md (provisioned
+by provisionBrain) already carries the crawling protocol, decision protocol,
+and where-to-find-things table. Duplicating any of that in the skill creates
+two sources of truth that drift. The skill's entire job is "read CLAUDE.md,
+do what it says."
+
+**Generic MCP reference over hardcoded tool names.** The spec's undesired
+outcomes explicitly forbid naming `mcp__obsidian__read_note` or assuming a
+specific server key. The prompt says "use the Obsidian MCP" and the agent
+discovers the actual tool names from its tool list at session start. This
+accommodates users who registered the MCP under a non-default key.
+
+**No scope boundary enforcement in the skill.** The spec says the scope
+boundary with study-playbook is "enforced by omission" — the /brain skill
+contains no reference to the coding playbook or study-playbook. If a user
+asks /brain about coding conventions, the vault CLAUDE.md's decision protocol
+handles the routing. The skill does not need redirect logic.
+
+**Two-line registration, no new machinery.** The initContent registry
+(DOC_PATHS + SKILL_DOCS) and installSkills planner already handle N skills.
+Adding /brain is one DOC_PATHS entry and one SKILL_DOCS entry. installSkills
+iterates `listSkills()` and handles the new entry identically to
+study-playbook. The upgrade pipeline also iterates `listSkills()` and picks
+up the new entry automatically. No new installation code is needed.
+
+**Doc hub update for accuracy.** The doc hub at `.aide/docs/index.md` states
+"one canonical skill". This becomes stale the moment /brain ships. Updating
+the count and adding a table row is a documentation-accuracy fix, not scope
+creep — the hub is the entry point agents read to understand what AIDE ships.

package/.claude/skills/study-playbook/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: study-playbook
+description: >
+  Load relevant coding-playbook sections from the Obsidian vault for the current task.
+  Navigates the playbook hub top-down: reads the index, identifies which sections apply,
+  drills into section hubs, then reads the specific child notes needed. Use this skill
+  whenever you need to look up coding conventions, patterns, or architecture decisions
+  before writing or reviewing code. Do NOT trigger for non-coding vault work.
+---
+
+# /study-playbook — Load Coding Playbook Context
+
+Navigate the coding playbook hub and load only the sections relevant to the current task.
+
+---
+
+## Step 1: Read the Playbook Hub
+
+Read `coding-playbook/coding-playbook.md` via `mcp__obsidian__read_note`.
+
+The hub lists sections with descriptions. Match your current task domain against
+those descriptions to identify which sections apply. Do NOT read all sections —
+only the ones whose descriptions overlap with the work at hand.
+
+---
+
+## Step 2: Read the Relevant Section Hubs
+
+For each matching section, read its hub note (e.g. `<section>/<section>.md`).
+
+Section hubs list their child notes with keywords. Scan the list and identify which
+specific child notes overlap with the task. Do NOT read every child — only the ones
+whose keywords match the work.
+
+---
+
+## Step 3: Read the Specific Child Notes
+
+Read the child notes identified in Step 2 (e.g. `<section>/<child-note>.md`).
+These contain the concrete patterns and code examples to follow.
+
+---
+
+## Navigation Rules
+
+- **Use the hub's link structure, not search.** Do NOT use `mcp__obsidian__search_notes`
+  to find playbook content. Searching produces fragments without context; the hub
+  structure gives you the full picture.
+- **Read top-down.** Hub → section hub → child note. Never skip levels.
+- **Follow wikilinks 1–2 levels deep from content notes.** Hub notes (tagged `hub` or
+  acting as section indexes) are navigation — they don't count as depth. Depth starts
+  at the first content note you land on. Example:
+  - `coding-playbook.md` (root hub) → depth 0 (navigation)
+  - `foundations/foundations.md` (section hub) → depth 0 (navigation)
+  - `foundations/conventions.md` (content note) → depth 0 (first real content)
+  - wikilink from `conventions.md` → depth 1
+  - wikilink from *that* note → depth 2
+
+  When reading any content note, look for `[[wikilinks]]`. If a linked note looks
+  relevant to the task, read it — then check *that* note's links too. Go at least
+  1–2 levels deep from the first content note in any direction where the information
+  could apply. Playbook notes cross-reference each other (e.g. a services note may
+  link to error-handling patterns, which links to API response conventions). Following
+  these links is how you build the full picture, not just a fragment.
+- **Never re-read notes.** Before reading any note, check whether it already appears
+  in your conversation context from a prior tool call. This skill may be invoked
+  multiple times in a single workflow — do NOT re-read the playbook hub, section hubs,
+  or child notes you have already loaded. The same applies when following wikilinks:
+  skip any link whose target you have already read in this session.
+- **Invoke incrementally, not all at once.** Multi-step work (e.g. planning an
+  end-to-end feature) crosses multiple domains — types, then services, then API, then
+  client. Do NOT try to load every section upfront. Load what you need for the current
+  step. When you move to the next step and realize you're in a new domain without the
+  relevant playbook context, invoke this skill again. The "never re-read" rule keeps
+  repeated invocations cheap — you'll skip the hub and any notes already loaded, and
+  only read the new sections you actually need.
+- **Stop when you have enough.** Within a single invocation, if the step only touches
+  one domain (e.g. just API routes), you only need that one section's notes plus
+  whatever they link to. Don't load unrelated sections "just in case."