@soleri/forge 9.11.0 → 9.12.1

package/src/scaffold-filetree.ts

@@ -26,40 +26,40 @@ import type { AgentConfig } from './types.js';
  * (installed on demand via `soleri skills install`).
  */
 export const SKILLS_REGISTRY: Record<string, 'essential' | 'optional'> = {
-  'agent-guide': 'essential',
-  'agent-persona': 'essential',
-  'vault-navigator': 'essential',
-  'vault-capture': 'essential',
-  'systematic-debugging': 'essential',
-  'writing-plans': 'essential',
-  'context-resume': 'essential',
+  'soleri-agent-guide': 'essential',
+  'soleri-agent-persona': 'essential',
+  'soleri-vault-navigator': 'essential',
+  'soleri-vault-capture': 'essential',
+  'soleri-systematic-debugging': 'essential',
+  'soleri-writing-plans': 'essential',
+  'soleri-context-resume': 'essential',
   // ─── Optional (installed on demand) ────────────
-  'agent-dev': 'optional',
-  'agent-issues': 'optional',
-  'brain-debrief': 'optional',
-  brainstorming: 'optional',
-  'code-patrol': 'optional',
-  'deep-review': 'optional',
-  'deliver-and-ship': 'optional',
-  'discovery-phase': 'optional',
-  'env-setup': 'optional',
-  'executing-plans': 'optional',
-  'finishing-a-development-branch': 'optional',
-  'fix-and-learn': 'optional',
-  'health-check': 'optional',
-  'knowledge-harvest': 'optional',
-  'mcp-doctor': 'optional',
-  'onboard-me': 'optional',
-  'parallel-execute': 'optional',
-  retrospective: 'optional',
-  'second-opinion': 'optional',
-  'subagent-driven-development': 'optional',
-  'test-driven-development': 'optional',
-  'using-git-worktrees': 'optional',
-  'vault-curate': 'optional',
-  'vault-smells': 'optional',
-  'verification-before-completion': 'optional',
-  'yolo-mode': 'optional',
+  'soleri-agent-dev': 'optional',
+  'soleri-agent-issues': 'optional',
+  'soleri-brain-debrief': 'optional',
+  'soleri-brainstorming': 'optional',
+  'soleri-code-patrol': 'optional',
+  'soleri-deep-review': 'optional',
+  'soleri-deliver-and-ship': 'optional',
+  'soleri-discovery-phase': 'optional',
+  'soleri-env-setup': 'optional',
+  'soleri-executing-plans': 'optional',
+  'soleri-finishing-a-development-branch': 'optional',
+  'soleri-fix-and-learn': 'optional',
+  'soleri-health-check': 'optional',
+  'soleri-knowledge-harvest': 'optional',
+  'soleri-mcp-doctor': 'optional',
+  'soleri-onboard-me': 'optional',
+  'soleri-parallel-execute': 'optional',
+  'soleri-retrospective': 'optional',
+  'soleri-second-opinion': 'optional',
+  'soleri-subagent-driven-development': 'optional',
+  'soleri-test-driven-development': 'optional',
+  'soleri-using-git-worktrees': 'optional',
+  'soleri-vault-curate': 'optional',
+  'soleri-vault-smells': 'optional',
+  'soleri-verification-before-completion': 'optional',
+  'soleri-yolo-mode': 'optional',
 };
 
 /** Names of essential skills (always scaffolded when skillsFilter is 'essential'). */
@@ -439,32 +439,36 @@ const DOMAIN_ROUTING_SEEDS: Record<
   { pattern: string; workspace: string; skills: string[] }[]
 > = {
   design: [
-    { pattern: 'design component', workspace: 'design', skills: ['vault-navigator'] },
-    { pattern: 'review design', workspace: 'review', skills: ['deep-review'] },
+    { pattern: 'design component', workspace: 'design', skills: ['soleri-vault-navigator'] },
+    { pattern: 'review design', workspace: 'review', skills: ['soleri-deep-review'] },
   ],
   'ui-design': [
-    { pattern: 'design component', workspace: 'design', skills: ['vault-navigator'] },
-    { pattern: 'review design', workspace: 'review', skills: ['deep-review'] },
+    { pattern: 'design component', workspace: 'design', skills: ['soleri-vault-navigator'] },
+    { pattern: 'review design', workspace: 'review', skills: ['soleri-deep-review'] },
   ],
   architecture: [
-    { pattern: 'plan architecture', workspace: 'planning', skills: ['writing-plans'] },
-    { pattern: 'implement feature', workspace: 'src', skills: ['test-driven-development'] },
-    { pattern: 'write documentation', workspace: 'docs', skills: ['vault-capture'] },
+    { pattern: 'plan architecture', workspace: 'planning', skills: ['soleri-writing-plans'] },
+    { pattern: 'implement feature', workspace: 'src', skills: ['soleri-test-driven-development'] },
+    { pattern: 'write documentation', workspace: 'docs', skills: ['soleri-vault-capture'] },
   ],
   backend: [
-    { pattern: 'plan API', workspace: 'planning', skills: ['writing-plans'] },
-    { pattern: 'implement endpoint', workspace: 'src', skills: ['test-driven-development'] },
-    { pattern: 'write docs', workspace: 'docs', skills: ['vault-capture'] },
+    { pattern: 'plan API', workspace: 'planning', skills: ['soleri-writing-plans'] },
+    { pattern: 'implement endpoint', workspace: 'src', skills: ['soleri-test-driven-development'] },
+    { pattern: 'write docs', workspace: 'docs', skills: ['soleri-vault-capture'] },
   ],
   frontend: [
-    { pattern: 'plan component', workspace: 'planning', skills: ['writing-plans'] },
-    { pattern: 'implement component', workspace: 'src', skills: ['test-driven-development'] },
-    { pattern: 'write docs', workspace: 'docs', skills: ['vault-capture'] },
+    { pattern: 'plan component', workspace: 'planning', skills: ['soleri-writing-plans'] },
+    {
+      pattern: 'implement component',
+      workspace: 'src',
+      skills: ['soleri-test-driven-development'],
+    },
+    { pattern: 'write docs', workspace: 'docs', skills: ['soleri-vault-capture'] },
   ],
   security: [
-    { pattern: 'threat model', workspace: 'planning', skills: ['writing-plans'] },
-    { pattern: 'implement policy', workspace: 'src', skills: ['test-driven-development'] },
-    { pattern: 'write runbook', workspace: 'docs', skills: ['vault-capture'] },
+    { pattern: 'threat model', workspace: 'planning', skills: ['soleri-writing-plans'] },
+    { pattern: 'implement policy', workspace: 'src', skills: ['soleri-test-driven-development'] },
+    { pattern: 'write runbook', workspace: 'docs', skills: ['soleri-vault-capture'] },
   ],
 };
 

package/src/skills/{agent-dev → soleri-agent-dev}/SKILL.md

@@ -1,12 +1,9 @@
 ---
-name: agent-dev
+name: soleri-agent-dev
 description: >
-  Use when extending the agent itself — adding facades, tools, vault operations,
-  brain features, new skills, or modifying agent internals. Triggers on "add a facade",
-  "new tool", "extend vault", "add brain feature", "new skill", "add operation",
-  "extend agent", or when the work target is the agent's own codebase rather than
-  a project the agent assists with. Enforces vault-first knowledge gathering before
-  any code reading or planning.
+  Use when the user says "add a facade", "new tool", "extend vault",
+  "add brain feature", "new skill", or "extend agent". For extending
+  the agent's own internals with vault-first knowledge gathering.
 ---
 
 # Agent Dev — Vault-First Internal Development

package/src/skills/{agent-guide → soleri-agent-guide}/SKILL.md

@@ -1,11 +1,9 @@
 ---
-name: agent-guide
+name: soleri-agent-guide
 description: >
-  Use when the user asks "what can you do", "help me", "how do I use this",
-  "what features do you have", "what tools are available", "how does this work",
-  "show me your capabilities", "what are you", "who are you", or any question
-  about the agent's identity, capabilities, available tools, or how to use them.
-  Not needed for proactive tool suggestions — those are handled by engine rules.
+  Use when the user says "what can you do", "how do I use this",
+  "what features", "what tools available", "who are you", or "show capabilities".
+  Helps users discover agent capabilities and available tools.
 ---
 
 # Agent Guide — Capability Discovery
@@ -36,6 +34,9 @@ This returns the agent's persona: name, role, description, tone, principles, and
 
 ```
 YOUR_AGENT_core op:admin_health
+YOUR_AGENT_core op:vault_stats
+YOUR_AGENT_core op:brain_stats
+YOUR_AGENT_core op:memory_stats
 ```
 
 Shows what subsystems are active: vault (how many entries), brain (vocabulary size), LLM availability, cognee status. This tells the user what the agent currently has to work with.

package/{dist/skills/agent-issues → src/skills/soleri-agent-issues}/SKILL.md

@@ -1,11 +1,9 @@
 ---
-name: agent-issues
+name: soleri-agent-issues
 description: >
-  Use when creating GitHub issues, bugs, tasks, or milestones that will be
-  worked on by AI coding agents. Triggers on: "create issue", "file bug",
-  "gh issue", "add milestone", "create task", "report bug", "gh tasks",
-  "create tasks", "create tickets", "file tickets", or when generating
-  structured work items from conversation context.
+  Use when the user says "create issue", "file bug", "gh issue",
+  "create task", "report bug", or "create tickets". Creates structured
+  GitHub issues optimized for AI agent execution.
 ---
 
 # Agent-Optimized Issue Creation
@@ -26,6 +24,18 @@ An agent cannot act on "improve avatar handling." It can act on: "Add PNG upload
 - Creating milestones with sub-issues
 - Converting vault patterns or anti-patterns into actionable fixes
 
+## Vault Context Check
+
+Before creating the issue, search for related patterns:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<bug description or feature summary>" }
+
+YOUR_AGENT_core op:memory_search
+  params: { query: "<similar issues>" }
+```
+
 ## Issue Template by Type
 
 ### Bug
@@ -177,6 +187,15 @@ An agent cannot act on "improve avatar handling." It can act on: "Add PNG upload
 - [ ] <milestone-level verification>
 ````
 
+## Record Issue
+
+After creating the issue, capture it for future reference:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: { title: "GH Issue #<number>: <title>", tags: ["github", "issue"] }
+```
+
 ## Field Guide
 
 ### Writing Good Objectives
@@ -289,3 +308,11 @@ Always apply at least:
 - Priority: `P0`, `P1`, `P2`, `P3` (if using priority labels)
 - Component: package or module name (if using component labels)
 ```
+
+## Agent Tools Reference
+
+| Op                   | When to Use                               |
+| -------------------- | ----------------------------------------- |
+| `search_intelligent` | Check vault before creating issues        |
+| `memory_search`      | Find similar past issues                  |
+| `capture_quick`      | Record created issue for future reference |

package/{dist/skills/agent-persona → src/skills/soleri-agent-persona}/SKILL.md

@@ -1,10 +1,9 @@
 ---
-name: agent-persona
+name: soleri-agent-persona
 description: >
-  Use when the user activates the agent's persona via its greeting phrase, or says
-  "activate persona", "be yourself", "stay in character", or any activation phrase
-  defined in the agent's persona configuration. Reinforces character persistence
-  through the session and survives context compaction.
+  Use when the user says "activate persona", "be yourself",
+  "stay in character", or "hello [agent name]". Reinforces character
+  persistence through the session and survives context compaction.
 ---
 
 # Agent Persona — Stay in Character

package/{dist/skills/brain-debrief → src/skills/soleri-brain-debrief}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: brain-debrief
+name: soleri-brain-debrief
 description: >
-  Use when the user wants to explore the brain's learned PATTERNS — "brain stats", "pattern
-  strengths", "what patterns are strongest", "intelligence report", "show brain data". Focused
-  on the brain module's accumulated pattern intelligence. For time-bound sprint or weekly
-  reflection, use retrospective instead.
+  Use when the user says "brain stats", "pattern strengths",
+  "intelligence report", "show brain data", or "what patterns are strongest".
+  Surfaces accumulated pattern intelligence from the brain module. For
+  time-bound work reflection (sprint retro, weekly summary), use retrospective instead.
 ---
 
 # Brain Debrief — Intelligence Report

package/src/skills/{brainstorming → soleri-brainstorming}/SKILL.md

@@ -1,10 +1,9 @@
 ---
-name: brainstorming
+name: soleri-brainstorming
 description: >
-  Use for open-ended creative exploration when requirements are NOT yet clear — "I want to build
-  something", "let's think about", "explore options for", "what if we". Explores intent and
-  design before implementation. If the user already has a spec or clear requirements, use
-  writing-plans instead.
+  Use when the user says "I want to build something", "let's think about",
+  "what if we", "creative exploration", or "ideate". For open-ended creative
+  exploration when requirements are NOT yet clear.
 ---
 
 # Brainstorming Ideas Into Designs

package/src/skills/soleri-build-skill/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: soleri-build-skill
+description: >
+  Use when creating a new skill, updating an existing skill, or scaffolding a skill
+  template for a Soleri agent. Triggers on "create a skill", "new skill", "build skill",
+  "add a skill", "write a skill", "skill template", "scaffold skill".
+---
+
+# Build Skill — Create Skills for Soleri Agents
+
+Create well-structured skills that follow Soleri conventions. Skills are SKILL.md files in the forge that get synced to agents as slash commands.
+
+## Skill Anatomy
+
+Skills live in two places:
+
+| Location                                           | Purpose                    |
+| -------------------------------------------------- | -------------------------- |
+| `packages/forge/src/skills/soleri-{name}/SKILL.md` | Source — ships with Soleri |
+| `~/.claude/skills/{agent}-soleri-{name}/SKILL.md`  | Runtime — synced per agent |
+
+### File Structure
+
+```yaml
+---
+name: soleri-{skill-name}
+description: >
+  Use when the user says "trigger1", "trigger2", "trigger3",
+  or wants to [brief purpose]. [One sentence about what the skill does].
+---
+
+# Skill Title — Short Purpose
+
+[Core workflow instructions with numbered steps]
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Check vault before starting |
+| `capture_knowledge` | Persist patterns worth remembering |
+```
+
+## Creation Process
+
+### Step 1: Search Vault for Prior Art
+
+Before creating anything, check if a similar skill or pattern exists:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<skill topic>" }
+```
+
+List existing skills to avoid duplication:
+
+```bash
+ls packages/forge/src/skills/
+```
+
+### Step 2: Check Trigger Keywords
+
+Every skill needs 4-8 unique trigger phrases in the `description:` field. Before choosing triggers, check ALL existing skills to avoid overlap:
+
+```bash
+grep -h "description:" packages/forge/src/skills/soleri-*/SKILL.md
+```
+
+Rules:
+
+- No trigger phrase may appear in more than one skill
+- Use quoted phrases: `"exact trigger words"`
+- Cover the full intent range — think about how users naturally ask for this
+- Avoid generic words that overlap with other skills (e.g., "review" is used by deep-review)
+
+### Step 3: Design the Workflow
+
+Identify 3-5 concrete scenarios. Ask the user if unclear:
+
+- "What exact phrases should trigger this skill?"
+- "Walk me through one example end-to-end"
+- "What should this skill NOT do?"
+
+### Step 4: Wire In Engine Ops
+
+Every Soleri skill should use the engine where applicable. Use the `YOUR_AGENT_core` placeholder — it gets replaced with the agent's actual facade name at sync time.
+
+Common integration points:
+
+| When                 | Op                            | Why                               |
+| -------------------- | ----------------------------- | --------------------------------- |
+| Before starting work | `search_intelligent`          | Check vault for prior art         |
+| Before starting work | `memory_search`               | Check session history             |
+| During execution     | `brain_recommend`             | Get brain recommendations         |
+| After completion     | `capture_knowledge`           | Persist patterns learned          |
+| After completion     | `capture_quick`               | Fast capture for simple learnings |
+| Quality checks       | `admin_health`                | Verify system health              |
+| Iteration tracking   | `loop_start` / `loop_iterate` | Track multi-step work             |
+
+### Available Facades
+
+All ops use the `YOUR_AGENT_core` placeholder:
+
+| Domain                 | Key Ops                                                                                             |
+| ---------------------- | --------------------------------------------------------------------------------------------------- |
+| Vault search & capture | `search_intelligent`, `search`, `capture_knowledge`, `capture_quick`, `vault_tags`, `vault_domains` |
+| Admin & health         | `admin_health`, `admin_diagnostic`, `admin_tool_list`, `admin_vault_analytics`                      |
+| Curator & quality      | `curator_health_audit`, `curator_detect_duplicates`, `curator_contradictions`, `curator_groom_all`  |
+| Brain & learning       | `brain_stats`, `brain_strengths`, `brain_recommend`, `brain_build_intelligence`                     |
+| Memory & sessions      | `memory_search`, `memory_stats`, `session_capture`, `memory_cross_project_search`                   |
+| Planning               | `create_plan`, `approve_plan`, `plan_split`, `plan_reconcile`, `plan_complete_lifecycle`            |
+| Loops & validation     | `loop_start`, `loop_iterate`, `loop_complete`, `loop_status`                                        |
+
+### Step 5: Write the Skill
+
+Follow these rules:
+
+**Naming:**
+
+- Folder: `packages/forge/src/skills/soleri-{name}/SKILL.md`
+- `name:` field must be `soleri-{name}` — matching the folder
+- All Soleri skills use the `soleri-` prefix
+
+**Frontmatter:**
+
+- `description:` must include specific trigger phrases in quotes
+- Use `>` for multi-line YAML folded scalar descriptions
+
+**Body (target 1,500-2,000 words):**
+
+- Imperative form ("Search the vault", not "You should search")
+- Numbered steps with concrete op examples including params
+- Agent Tools Reference table at the end
+- Common Mistakes section if applicable
+
+**Op References:**
+
+- Always use `YOUR_AGENT_core op:xxx` — never hardcode agent names
+- Include example params where helpful
+- Only reference ops that actually exist (verify with `admin_tool_list`)
+
+### Step 6: Validate
+
+Checklist before committing:
+
+- [ ] Folder is `soleri-{name}/SKILL.md` in `packages/forge/src/skills/`
+- [ ] `name:` matches folder name
+- [ ] `description:` has 4-8 specific trigger phrases in quotes
+- [ ] No trigger overlap with existing skills
+- [ ] All ops use `YOUR_AGENT_core` placeholder
+- [ ] No hardcoded agent names (`ernesto_core`, `salvador_core`, etc.)
+- [ ] Imperative writing style throughout
+- [ ] Agent Tools Reference table at the end
+- [ ] Under 3,000 words (ideally 1,500-2,000)
+- [ ] TypeScript compiles: `npx tsc --noEmit` in packages/forge
+
+### Step 7: Copy to Reference Agent
+
+If the skill should appear in the reference agent:
+
+```bash
+cp -r packages/forge/src/skills/soleri-{name} examples/reference-agent/skills/
+```
+
+### Step 8: Register in Scaffold Pipeline
+
+Add the skill to `SKILLS_REGISTRY` in `packages/forge/src/scaffold-filetree.ts` and `SKILL_CATEGORIES` in `packages/forge/src/compose-claude-md.ts` so it gets included in new scaffolds.
+
+### Step 9: Capture the Decision
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "New skill: soleri-{name} — {purpose}",
+    description: "Created skill for {what it does}. Triggers: {triggers}.",
+    type: "workflow",
+    domain: "tooling",
+    tags: ["skill", "workflow", "{domain}"]
+  }
+```
+
+## Updating Existing Skills
+
+1. Read the current file first
+2. Search vault for related patterns or feedback
+3. Make targeted changes — don't rewrite the whole skill
+4. Verify all ops still use `YOUR_AGENT_core` placeholder
+5. Update `description:` if triggers changed
+6. Check for trigger overlap after changes
+7. Update reference agent copy if it exists
+
+## Common Mistakes
+
+- **Vague descriptions** — "Use for project management" vs "Use when creating GitHub issues or tracking milestones"
+- **Trigger overlap** — Using "review" when `soleri-deep-review` already owns it
+- **Hardcoded agent names** — `ernesto_core` instead of `YOUR_AGENT_core`
+- **Missing engine wiring** — A skill that never checks the vault is a missed opportunity
+- **Second person** — "You should search" instead of "Search the vault"
+- **Too long** — Over 3,000 words bloats context. Extract details into separate files if needed
+- **No prefix** — Forgetting the `soleri-` prefix on the folder and name
+
+## Agent Tools Reference
+
+| Op                   | When to Use                            |
+| -------------------- | -------------------------------------- |
+| `search_intelligent` | Check for existing skills and patterns |
+| `capture_knowledge`  | Capture skill creation decision        |
+| `admin_tool_list`    | Verify available ops                   |
+| `vault_domains`      | Check domain categories                |
+| `memory_search`      | Find related past work                 |

package/src/skills/{code-patrol → soleri-code-patrol}/SKILL.md

@@ -1,6 +1,10 @@
 ---
-name: code-patrol
-description: Use when reviewing code against the project's own captured patterns, anti-patterns, and conventions — not generic lint rules but institutional knowledge.
+name: soleri-code-patrol
+description: >
+  Use when the user says "check against patterns", "pattern compliance",
+  "convention check", "review against vault", or "institutional review".
+  Reviews code against the project's own captured patterns and conventions.
+  For general code quality review (smells, architecture), use deep-review instead.
 ---
 
 # Code Patrol — Review Code Against Your Own Knowledge

package/{dist/skills/context-resume → src/skills/soleri-context-resume}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: context-resume
+name: soleri-context-resume
 description: >
-  Use when the user says "where did I leave off", "what was I working on", "catch me up",
-  "resume", "continue where we stopped", or is starting a new session and needs to reconstruct
-  working context from memory, plans, and sessions.
+  Use when the user says "where did I leave off", "what was I working on",
+  "catch me up", "resume session", or "continue where we stopped".
+  Reconstructs working context from memory, plans, and sessions.
 ---
 
 # Context Resume — Pick Up Where You Left Off

package/{dist/skills/deep-review → src/skills/soleri-deep-review}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: deep-review
+name: soleri-deep-review
 description: >
-  Use for in-depth code review beyond linting — architecture fitness, code smells, solution quality,
-  optimization opportunities. Triggers on "deep review", "review this code", "is this well architected",
-  "code smells", "review this module", "architecture review", "is this the right approach",
-  "optimization review". Works on any codebase. For vault-specific knowledge quality, use vault-smells instead.
+  Use when the user says "deep review", "code smells", "architecture review",
+  "is this well architected", or "optimization review". Multi-pass code review
+  analyzing structural health, smells, and solution quality. For reviewing
+  against the project's own vault patterns and conventions, use code-patrol instead.
 ---
 
 # Deep Review — Architecture, Smells & Solution Quality

package/src/skills/{deliver-and-ship → soleri-deliver-and-ship}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: deliver-and-ship
+name: soleri-deliver-and-ship
 description: >
-  Use when the user says "ship it", "ready to deploy", "package", "release",
-  "pre-PR check", "delivery checklist", "is this ready", "final review", or mentions
-  shipping, deploying, packaging, or releasing work. Runs pre-delivery quality gates
-  to ensure nothing ships without passing stability, knowledge capture, and code quality checks.
+  Use when the user says "ship it", "pre-PR check", "delivery checklist", "is this ready",
+  "final review", or "ready to deploy". Runs pre-delivery quality gates
+  to ensure nothing ships without passing stability and code quality checks.
+  For mid-workflow verification (not shipping), use verification-before-completion instead.
 ---
 
 # Deliver & Ship — Quality Gate Runner

package/{dist/skills/discovery-phase → src/skills/soleri-discovery-phase}/SKILL.md

@@ -1,10 +1,9 @@
 ---
-name: discovery-phase
+name: soleri-discovery-phase
 description: >
-  Use for structured exploration before committing to a plan — "I don't know where to start",
-  "what are our options", "investigate", "research this", "explore options", "discovery". Ideal
-  when requirements are unclear, entering a new domain, or facing architectural decisions. Produces
-  a discovery document with options, tradeoffs, and a recommendation.
+  Use when the user says "I don't know where to start", "investigate",
+  "research this", "explore the problem", or "discovery". Structured exploration
+  before committing to a plan, producing options with tradeoffs.
 ---
 
 # Discovery Phase
@@ -19,12 +18,13 @@ Do NOT create a plan, write code, or take any implementation action until the di
 
 1. **Define the question** — restate what we're exploring as one specific, answerable sentence
 2. **Search vault for prior art** — `YOUR_AGENT_core op:search_intelligent params: { query: "<question>", mode: "scan" }`. Also `op:memory_search` with `crossProject: true`.
-3. **Explore codebase** — read relevant files, configs, architecture, recent commits
-4. **Identify constraints** — hard (must-haves) vs soft (nice-to-haves), unknowns that block a decision
-5. **Draft 2-4 options** — each with pros, cons, risk, and effort (S/M/L)
-6. **Recommend** — pick one, state the primary reason, note what would change the answer
-7. **Capture to vault** — persist the discovery finding
-8. **Transition** — hand off to brainstorming or writing-plans skill
+3. **Get brain recommendations** — `YOUR_AGENT_core op:brain_recommend params: { query: "<discovery topic>" }`. Get brain recommendations for similar past explorations.
+4. **Explore codebase** — read relevant files, configs, architecture, recent commits
+5. **Identify constraints** — hard (must-haves) vs soft (nice-to-haves), unknowns that block a decision
+6. **Draft 2-4 options** — each with pros, cons, risk, and effort (S/M/L)
+7. **Recommend** — pick one, state the primary reason, note what would change the answer
+8. **Capture to vault** — persist the discovery finding
+9. **Transition** — hand off to brainstorming or writing-plans skill
 
 ## Option Format
 
@@ -61,9 +61,10 @@ Save to `docs/discoveries/YYYY-MM-DD-<topic>.md` and commit. Then transition to
 
 ## Quick Reference
 
-| Op                   | When to Use                        |
-| -------------------- | ---------------------------------- |
-| `search_intelligent` | Search vault for prior art         |
-| `memory_search`      | Check session history and projects |
-| `capture_knowledge`  | Persist discovery finding          |
-| `route_intent`       | Classify what comes after          |
+| Op                   | When to Use                                         |
+| -------------------- | --------------------------------------------------- |
+| `search_intelligent` | Search vault for prior art                          |
+| `memory_search`      | Check session history and projects                  |
+| `brain_recommend`    | Brain recommendations for similar past explorations |
+| `capture_knowledge`  | Persist discovery finding                           |
+| `route_intent`       | Classify what comes after                           |