@soleri/forge 9.11.0 → 9.12.1

package/{src/skills/onboard-me → dist/skills/soleri-onboard-me}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: onboard-me
+name: soleri-onboard-me
 description: >
-  Use when someone is new to the PROJECT and needs orientation — "onboard me", "I'm new here",
-  "project overview", "what should I know about this codebase". Questions about the project's
-  patterns and conventions, not about the agent's capabilities (use agent-guide for that).
+  Use when the user says "onboard me", "I'm new here", "project overview",
+  or "what should I know about this codebase". Provides a structured tour
+  of everything the vault knows about this project.
 ---
 
 # Onboard Me — Instant Project Intelligence
@@ -101,6 +101,15 @@ YOUR_AGENT_core op:vault_age_report
 
 **Tip:** Use vault-navigator to search topics as you work. Use second-opinion before architectural decisions.
 
+### Record Onboarding
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: { title: "Onboarding completed for <project>", description: "<key takeaways and knowledge gaps identified>", type: "workflow", tags: ["onboarding", "<project>"] }
+```
+
+Record what was covered and what gaps remain for future onboarding.
+
 ## Common Mistakes
 
 - Dumping all vault entries instead of curating the most important ones
@@ -119,3 +128,4 @@ YOUR_AGENT_core op:vault_age_report
 | `brain_strengths`                           | Proven patterns               |
 | `brain_global_patterns`                     | Cross-project patterns        |
 | `admin_search_insights`                     | Knowledge gaps                |
+| `capture_knowledge`                         | Record onboarding completion  |

package/{src/skills/parallel-execute → dist/skills/soleri-parallel-execute}/SKILL.md

@@ -1,10 +1,9 @@
 ---
-name: parallel-execute
+name: soleri-parallel-execute
 description: >
-  Use when executing a plan where independent tasks can run concurrently. Triggers on "run in
-  parallel", "parallelize", "fan out", "concurrent execution", "run simultaneously", "at the
-  same time", "dispatch subagents", "batch execute", or when a plan has 3+ tasks with no
-  dependency overlap. For sequential task-by-task execution, use executing-plans instead.
+  Use when the user says "run in parallel", "fan out", "concurrent execution",
+  "batch execute", or "dispatch subagents". Executes independent plan tasks
+  concurrently via subagents. For sequential execution, use executing-plans.
 ---
 
 # Parallel Execute — Subagent-Driven Plan Execution
@@ -165,7 +164,7 @@ As subagents complete, collect their results. For each completed task:
 | Pass | Critical issues   | Dispatch targeted fix subagent (max 2 retries)              |
 | Pass | Minor issues only | Mark completed, note issues for later                       |
 
-6. **Mark completed:**
+1. **Mark completed:**
    ```
    YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "completed" }
    ```
@@ -234,7 +233,13 @@ YOUR_AGENT_core op:session_capture params:{
 | Tasks touch files in the same package        | Use `isolation: "worktree"`               |
 | Tasks modify the same file                   | **Do NOT parallelize** — run sequentially |
 
-When using worktree isolation, the controller must merge worktree changes back after review passes.
+When using worktree isolation, the controller must merge worktree changes back after review passes, then **immediately delete the local branch**:
+
+```bash
+git branch -D <subagent/taskId>
+```
+
+Worktree branches are local-only — never push them to remote. Branch cleanup is mandatory after every merge.
 
 ## Failure Handling
 

package/dist/skills/soleri-research-scout/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: soleri-research-scout
+description: >
+  Use when the user says "scout", "research scout", "find new info",
+  "what's new", or "scan the web". Discovers new information that challenges
+  or updates existing vault knowledge via web search.
+---
+
+# /research-scout — Knowledge Discovery via Vault Branching
+
+Finds new information that challenges or updates existing vault knowledge.
+Searches web, Reddit, HN, and Quora for strategies, tools, announcements,
+and workflow changes relevant to vault domains.
+
+Findings go to a **scout branch** — never the main vault. Weekly review
+promotes the good ones, discards the rest.
+
+**Announce at start:** "Scouting for new intelligence — findings go to the scout branch, not the main vault."
+
+## Two Modes
+
+| Command                  | What it does                                     |
+| ------------------------ | ------------------------------------------------ |
+| `/research-scout`        | Run a scout pass — search web, capture to branch |
+| `/research-scout review` | Review branch findings, promote or discard       |
+
+---
+
+## Mode 1: Scout Pass
+
+### Step 1: Ensure Scout Branch Exists
+
+```
+YOUR_AGENT_branching op:vault_branch_list
+```
+
+If no branch named `scout-findings` exists, create it:
+
+```
+YOUR_AGENT_branching op:vault_branch
+  params: { name: "scout-findings" }
+```
+
+### Step 2: Identify What to Scout
+
+Pull active domains and recent topics from the vault:
+
+```
+YOUR_AGENT_vault op:vault_domains
+YOUR_AGENT_vault op:vault_recent params:{ limit: 15 }
+YOUR_AGENT_brain op:brain_strengths params:{ limit: 10 }
+```
+
+From these, build 3-5 focused search queries based on:
+
+- Active vault domains (e.g., "typescript", "react", "testing")
+- Strong brain patterns (what the user works on most)
+- Recent capture topics (what's top of mind)
+
+### Step 3: Web Search
+
+For each query, search with year context:
+
+```
+WebSearch: "{topic} new tools breaking changes 2026"
+WebSearch: "{topic} best practices updated site:reddit.com OR site:news.ycombinator.com"
+```
+
+Focus on:
+
+- New tool releases or deprecations
+- Breaking changes in dependencies
+- Updated best practices that contradict vault patterns
+- Workflow patterns gaining traction
+
+### Step 4: Cross-Reference Against Main Vault
+
+For each finding, check if the main vault already knows:
+
+```
+YOUR_AGENT_vault op:search_intelligent
+  params: { query: "{finding summary}" }
+```
+
+Classify:
+
+- **NEW** — vault has nothing on this topic. Worth capturing.
+- **UPDATE** — vault has related entry but info is outdated. Capture with link.
+- **CONTRADICTS** — finding conflicts with existing vault pattern. High value. Capture with contradiction link.
+- **REDUNDANT** — vault already has this. Skip entirely.
+
+**Only keep NEW, UPDATE, and CONTRADICTS.** Discard REDUNDANT.
+
+### Step 5: Validate Before Capture
+
+For each non-redundant finding:
+
+- Verify from at least 2 independent sources
+- Check the date — reject anything older than 3 months
+- Assess relevance — does this matter for active projects?
+
+**If a finding can't be verified from 2 sources, skip it.**
+
+### Step 6: Capture to Scout Branch
+
+Switch to scout branch, capture, switch back:
+
+```
+YOUR_AGENT_branching op:vault_branch_add
+  params: {
+    branch: "scout-findings",
+    entry: {
+      title: "{concise finding title}",
+      type: "pattern",
+      domain: "{relevant domain}",
+      description: "{what changed and why it matters}",
+      why: "Scout [{date}]: {source URL}. {what it changes or adds}",
+      severity: "suggestion",
+      tags: ["research-scout", "{domain}", "{source-type}"]
+    }
+  }
+```
+
+If the finding CONTRADICTS an existing main vault entry, note the
+contradicted entry ID in the description so the reviewer can link them
+during promotion.
+
+### Step 7: Scout Report
+
+Present results:
+
+| #   | Finding | Type        | Domain   | Source | Status                            |
+| --- | ------- | ----------- | -------- | ------ | --------------------------------- |
+| 1   | {title} | NEW         | {domain} | {url}  | Captured to branch                |
+| 2   | {title} | CONTRADICTS | {domain} | {url}  | Captured — contradicts {entry_id} |
+| 3   | {title} | REDUNDANT   | {domain} | —      | Skipped                           |
+
+**Summary:** {N} sources searched, {found} findings, {captured} captured to scout branch, {skipped} skipped as redundant.
+
+### Step 8: Session Capture
+
+```
+YOUR_AGENT_memory op:session_capture
+  params: {
+    summary: "Research scout: searched {N} topics, {captured} findings staged to scout-findings branch, {contradictions} contradictions flagged",
+    topics: ["{domains searched}"],
+    intent: "research"
+  }
+```
+
+---
+
+## Mode 2: Scout Review (Weekly)
+
+### Step 1: Load Branch Findings
+
+```
+YOUR_AGENT_branching op:vault_branch_list
+```
+
+List all entries on the `scout-findings` branch.
+
+### Step 2: Triage Each Finding
+
+For each entry on the branch, present to the user:
+
+| Field           | Value                          |
+| --------------- | ------------------------------ |
+| **Title**       | {title}                        |
+| **Domain**      | {domain}                       |
+| **Source**      | {from why field}               |
+| **Age**         | {days since capture}           |
+| **Contradicts** | {entry ID if noted, or "none"} |
+
+Ask: **Promote, Archive, or Skip?**
+
+- **Promote** — merge into main vault via `vault_merge_branch` or manual `capture_knowledge`. If it contradicts an entry, create a `link_entries` with type `contradicts`.
+- **Archive** — remove from branch, don't add to main vault.
+- **Skip** — leave on branch for next review.
+
+### Step 3: Clean Up Branch
+
+After review, delete the branch and recreate fresh:
+
+```
+YOUR_AGENT_branching op:vault_delete_branch
+  params: { name: "scout-findings" }
+YOUR_AGENT_branching op:vault_branch
+  params: { name: "scout-findings" }
+```
+
+### Step 4: Report
+
+| Metric       | Value      |
+| ------------ | ---------- |
+| **Reviewed** | {total}    |
+| **Promoted** | {promoted} |
+| **Archived** | {archived} |
+| **Skipped**  | {skipped}  |
+
+---
+
+## Scheduling
+
+### Nightly scout (3x)
+
+```
+/schedule create --name "research-scout-nightly" --cron "0 2,4,6 * * *" --prompt "/research-scout"
+```
+
+### Weekly review (Monday 9am)
+
+```
+/schedule create --name "research-scout-review" --cron "0 9 * * 1" --prompt "/research-scout review"
+```
+
+---
+
+## Quality Gates
+
+- **Max 5 captures per scout run** — if you find more, pick the 5 most impactful
+- **2-source minimum** — never capture from a single unverified source
+- **3-month freshness** — reject findings older than 90 days
+- **Domain relevance** — only scout domains the user actively works in
+- **No opinions** — capture facts, tools, and changes, not hot takes

package/dist/skills/{retrospective → soleri-retrospective}/SKILL.md

@@ -1,9 +1,10 @@
 ---
-name: retrospective
+name: soleri-retrospective
 description: >
-  Use for time-bound reflection on recent WORK — "sprint retro", "weekly summary", "what went
-  well this week", "end of sprint", "monthly report". Reviews sessions and extracts actionable
-  improvements. For brain pattern intelligence and strength scores, use brain-debrief instead.
+  Use when the user says "sprint retro", "weekly summary", "what went well",
+  "end of sprint", or "monthly report". Time-bound reflection on recent work
+  that reviews sessions and extracts actionable improvements. For brain
+  pattern intelligence and strength scores, use brain-debrief instead.
 ---
 
 # Retrospective — Learning Report From Real Data

package/{src/skills/second-opinion → dist/skills/soleri-second-opinion}/SKILL.md

@@ -1,6 +1,9 @@
 ---
-name: second-opinion
-description: Use when facing a technical decision, comparing approaches, or needing an informed recommendation backed by vault knowledge, brain patterns, and web research.
+name: soleri-second-opinion
+description: >
+  Use when the user says "second opinion", "technical decision",
+  "comparing approaches", or "which approach". Provides informed recommendations
+  backed by vault knowledge, brain patterns, and web research.
 ---
 
 # Second Opinion — Decision Support From All Sources

package/dist/skills/{subagent-driven-development → soleri-subagent-driven-development}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: subagent-driven-development
+name: soleri-subagent-driven-development
 description: >
-  Use when the user says "use subagents", "parallel agents", "fan out", "dispatch agents",
-  "subagent driven", or when a task decomposes into 2+ independent units that benefit from
-  isolated execution. Covers when to dispatch, worktree isolation, and merge strategy.
+  Use when the user says "use subagents", "parallel agents",
+  "subagent driven", or "isolated execution". Decomposes work into isolated
+  units and dispatches subagents for independent execution.
 ---
 
 # Subagent-Driven Development
@@ -56,6 +56,14 @@ Not all subagents are equal. Route by complexity:
 
 Read all relevant files. Consult the vault for patterns. Make every design decision. Define the exact spec for each subagent task: files to touch, approach to use, acceptance criteria.
 
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "subagent decomposition" }
+
+YOUR_AGENT_core op:brain_recommend
+  params: { query: "<task domain>" }
+```
+
 ### Step 2: Decompose & Route
 
 Break work into discrete units. For each, determine: files involved, dependencies on other units, conflict risk, complexity. Assign agent type per the routing table.
@@ -82,14 +90,21 @@ Each subagent prompt must include:
 Launch all independent subagents in a **single message** so they run in parallel.
 Use `isolation: "worktree"` for file-modifying tasks.
 
-### Step 4: Review and Merge
+### Step 4: Review, Merge, and Clean Up
 
 For each returning subagent:
 
 1. **Review** — read actual file changes (do not trust self-reports alone), verify tests pass, check scope compliance
 2. **Merge** — `git merge` or `git cherry-pick` from the worktree branch, one at a time
 3. **Test** — run the full suite after each merge; only proceed if green
-4. **Conflicts** — resolve manually, re-run tests, capture as anti-pattern
+4. **Clean up the branch** — after merge is confirmed and tests pass:
+   ```bash
+   git branch -D <subagent/taskId>              # delete local branch
+   ```
+   Worktree branches are local-only — never push them to remote.
+5. **Conflicts** — resolve manually, re-run tests, capture as anti-pattern
+
+**Branch cleanup is mandatory.** Every merged branch must be deleted immediately. Do not leave branches for later cleanup — they accumulate fast during parallel execution.
 
 ### Step 5: Reconcile & Report
 
@@ -98,8 +113,8 @@ After all merges, report to the user:
 **Minimal (default):**
 
 ```
-✓ N/N complete. M patterns captured to vault.
-  → Decisions: [any design decisions the orchestrator made]
+N/N complete. M patterns captured to vault.
+  -> Decisions: [any design decisions the orchestrator made]
 ```
 
 **Detailed (on request):**
@@ -107,19 +122,25 @@ After all merges, report to the user:
 ```
 | # | Task | Agent | Status | Knowledge |
 |---|------|-------|--------|-----------|
-| 1 | Desc | Worker | Done ✓ | — |
-| 2 | Desc | Instance | Done ✓ | 2 patterns |
+| 1 | Desc | Worker | Done | -- |
+| 2 | Desc | Instance | Done | 2 patterns |
 ```
 
 Capture learnings to vault. Run `orchestrate_complete` for the parent plan.
 
-## Worktree Cleanup Guarantee
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: { title: "<learned pattern>", description: "<merge strategy or decomposition insight>", type: "pattern", tags: ["subagent", "parallel-execution"] }
+```
+
+## Worktree & Branch Cleanup Guarantee
 
-Three layers — nothing accumulates:
+Worktree branches are **local-only** — never push them to remote. Four layers ensure nothing accumulates:
 
-1. **Per-task:** `finally` block in dispatcher removes worktree after each task
-2. **Per-batch:** `cleanupAll()` runs after all subagents complete
-3. **Per-session:** `SessionStart` hook prunes orphaned worktrees
+1. **Per-task:** `finally` block in dispatcher removes worktree and local branch after each task
+2. **Per-merge:** Orchestrator deletes local branch immediately after confirmed merge (Step 4)
+3. **Per-batch:** `cleanupAll()` runs after all subagents complete
+4. **Per-session:** `SessionStart` hook prunes orphaned worktrees and deletes merged `subagent/*` and `worktree-agent-*` local branches
 
 ## Anti-Patterns
 

package/{src/skills/systematic-debugging → dist/skills/soleri-systematic-debugging}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: systematic-debugging
+name: soleri-systematic-debugging
 description: >
-  Use as the FIRST response when something is broken — "bug", "failing test", "not working",
-  "debug this", "error", "crash", "unexpected behavior", "weird issue". Diagnoses root cause
-  before proposing fixes. After root cause is found, hand off to fix-and-learn for repair and
-  knowledge capture.
+  Use as the FIRST response when something is broken — "bug", "failing test",
+  "not working", "debug this", "error", "crash", or "weird issue". Diagnoses
+  root cause before proposing fixes. After root cause is found, hand off to
+  fix-and-learn for repair and knowledge capture.
 ---
 
 # Systematic Debugging

package/{src/skills/test-driven-development → dist/skills/soleri-test-driven-development}/SKILL.md

@@ -1,6 +1,9 @@
 ---
-name: test-driven-development
-description: Use when implementing any feature or bugfix — write failing tests before implementation code.
+name: soleri-test-driven-development
+description: >
+  Use when the user says "TDD", "write tests first", "red green refactor",
+  or "test driven". Write failing tests before implementation code for any
+  feature or bugfix.
 ---
 
 # Test-Driven Development (TDD)
@@ -9,6 +12,13 @@ description: Use when implementing any feature or bugfix — write failing tests
 
 ## Before You Start — Search First
 
+### Check Vault for Testing Patterns
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<domain> testing patterns" }
+```
+
 ```
 YOUR_AGENT_core op:search_intelligent
   params: { query: "<what you're about to test>" }

package/dist/skills/{using-git-worktrees → soleri-using-git-worktrees}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: using-git-worktrees
+name: soleri-using-git-worktrees
 description: >
-  Use when the user says "worktree", "isolate", "parallel branch", "safe branch", or when a plan
-  has independent tasks that benefit from parallel execution in isolated branches. Provides the
-  protocol for creating, working in, and cleaning up git worktrees safely.
+  Use when the user says "worktree", "parallel branch", "safe branch",
+  or "isolated branch". Provides the protocol for creating, working in,
+  and cleaning up git worktrees safely.
 ---
 
 # Using Git Worktrees
@@ -12,6 +12,13 @@ Isolate work into parallel branches without stashing or switching. Use for multi
 
 **Announce at start:** "I'm using the using-git-worktrees skill to isolate this work."
 
+## Check Vault for Worktree Patterns
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "worktree parallel execution patterns" }
+```
+
 ## When to Use
 
 - Plan has 2+ independent tasks that can run in parallel
@@ -79,3 +86,17 @@ git worktree list                      # confirm removal
 | Claude Code    | Sub-agent with `isolation: "worktree"` parameter |
 
 **Related skills:** executing-plans, parallel-execute
+
+## Capture Worktree Learnings
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: { title: "<what was learned>", tags: ["worktree", "parallel-execution"] }
+```
+
+## Agent Tools Reference
+
+| Op                   | When to Use                       |
+| -------------------- | --------------------------------- |
+| `search_intelligent` | Check vault before starting       |
+| `capture_quick`      | Fast capture for simple learnings |