@soleri/forge 5.4.0 → 5.6.0

package/dist/skills/retrospective.md

@@ -0,0 +1,189 @@
+---
+name: retrospective
+description: Use when the user asks "what did I learn this week", "sprint retro", "retrospective", "learning report", "what went well", "what could improve", "weekly summary", "monthly report", or wants to reflect on recent work and extract actionable insights from accumulated data.
+---
+
+# Retrospective — Learning Report From Real Data
+
+Generate a retrospective from actual session data, vault captures, plan outcomes, and brain intelligence. Not opinions — data-driven reflection on what happened, what worked, what didn't, and what to do differently.
+
+## When to Use
+
+- End of sprint / week / month
+- "What did I learn this week?"
+- "Sprint retrospective"
+- "What went well? What didn't?"
+- After completing a major feature or milestone
+
+## The Magic: Data-Driven Reflection
+
+### Step 1: Gather the Data
+
+**Brain stats — the big picture:**
+```
+YOUR_AGENT_core op:brain_stats
+```
+
+**Recent brain stats — compare velocity:**
+```
+YOUR_AGENT_core op:brain_stats
+  params: { since: "<start of period>" }
+```
+
+**Pattern strengths — what's proven:**
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+**Recent vault captures — what was learned:**
+```
+YOUR_AGENT_core op:vault_recent
+```
+
+**Memory topics — where knowledge clusters:**
+```
+YOUR_AGENT_core op:memory_topics
+```
+
+**Memory stats — volume and health:**
+```
+YOUR_AGENT_core op:memory_stats
+```
+
+**Plan stats — execution track record:**
+```
+YOUR_AGENT_core op:plan_stats
+```
+
+**Loop history — iterative workflow outcomes:**
+```
+YOUR_AGENT_core op:loop_history
+```
+
+**Search insights — what people looked for but didn't find:**
+```
+YOUR_AGENT_core op:admin_search_insights
+```
+
+**Vault analytics — knowledge quality:**
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+### Step 2: Analyze Patterns
+
+**Stale knowledge needing refresh:**
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+**Duplicates that crept in:**
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Contradictions in the knowledge base:**
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+**Curator health audit — overall quality:**
+```
+YOUR_AGENT_core op:curator_health_audit
+```
+
+### Step 3: Present the Retrospective
+
+```
+## Retrospective: [Period]
+
+### By the Numbers
+| Metric | This Period | Previous | Trend |
+|--------|-----------|----------|-------|
+| Patterns captured | X | Y | ↑/↓ |
+| Anti-patterns logged | X | Y | ↑/↓ |
+| Plans completed | X | Y | ↑/↓ |
+| Brain strength (avg) | X | Y | ↑/↓ |
+| Vault entries total | X | — | — |
+| Search misses | X | Y | ↑/↓ |
+
+### What Went Well
+[Patterns with high brain strength, completed plans, growing domains]
+
+### What Didn't Go Well
+[Recurring anti-patterns, failed plans, search misses = knowledge gaps]
+
+### Strongest Patterns
+[Top 5 patterns by brain strength — these are your superpowers]
+
+### Recurring Anti-Patterns
+[Top 3 anti-patterns that keep appearing — these need systemic fixes]
+
+### Knowledge Gaps
+[Domains with low coverage, frequent search misses, stale entries]
+
+### Vault Health
+- Quality score: X/100
+- Duplicates found: N
+- Contradictions found: N
+- Stale entries (>30 days): N
+
+### Recommendations
+1. [Action item based on data]
+2. [Action item based on data]
+3. [Action item based on data]
+```
+
+### Step 4: Capture the Retrospective
+
+Save the retrospective itself as knowledge:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "Retrospective — [period]",
+    description: "<key findings and action items>",
+    type: "workflow",
+    category: "meta",
+    tags: ["retrospective", "<period>"]
+  }
+```
+
+### Step 5: Clean Up (Optional)
+
+If the retrospective revealed quality issues, offer to fix them:
+
+**Consolidate vault (deduplicate, normalize, groom):**
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+**Rebuild brain intelligence with fresh data:**
+```
+YOUR_AGENT_core op:brain_build_intelligence
+```
+
+## The Magic
+
+This feels like magic because the user says "sprint retro" and gets a data-driven report they didn't have to compile. It's not AI making up observations — it's actual metrics from their vault, brain, plans, and memory. The recommendations come from real gaps, not generic advice.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `brain_stats` | Big picture metrics |
+| `brain_strengths` | Proven patterns |
+| `vault_recent` | What was captured recently |
+| `memory_topics` | Knowledge clusters |
+| `memory_stats` | Memory volume and health |
+| `plan_stats` | Plan completion rates |
+| `loop_history` | Iterative workflow outcomes |
+| `admin_search_insights` | Search miss analysis |
+| `admin_vault_analytics` | Knowledge quality metrics |
+| `vault_age_report` | Stale entries |
+| `curator_detect_duplicates` | Duplicate detection |
+| `curator_contradictions` | Knowledge conflicts |
+| `curator_health_audit` | Overall vault quality |
+| `capture_knowledge` | Persist the retrospective |
+| `curator_consolidate` | Post-retro cleanup |
+| `brain_build_intelligence` | Rebuild intelligence |

package/dist/skills/second-opinion.md

@@ -0,0 +1,142 @@
+---
+name: second-opinion
+description: Use when the user asks "should I", "what do you think about", "which approach", "compare options", "what would you recommend", "pros and cons", "trade-offs", or faces any technical decision and wants an informed recommendation backed by vault knowledge, brain patterns, and web research.
+---
+
+# Second Opinion — Decision Support From All Sources
+
+Before making any technical decision, get an informed recommendation that synthesizes vault knowledge, brain patterns, cross-project experience, and web research. Never decide in a vacuum.
+
+## When to Use
+
+- "Should I use Redis or Memcached?"
+- "What's the best way to handle auth?"
+- "Which testing framework?"
+- "Microservices or monolith?"
+- Any fork-in-the-road technical decision
+
+## The Magic: Multi-Source Decision Intelligence
+
+### Step 1: Understand the Decision
+
+Classify the intent to understand what kind of decision this is:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "<user's question>" }
+```
+
+### Step 2: Search All Knowledge Sources (in order)
+
+**Vault — has this been decided before?**
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<the decision or options being considered>" }
+```
+
+Look specifically for:
+- Previous decisions on this topic (type: "decision")
+- Patterns that favor one approach
+- Anti-patterns that warn against an approach
+
+**Brain — what's proven to work?**
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+```
+YOUR_AGENT_core op:brain_recommend
+  params: { projectName: "<current project>" }
+```
+
+**Cross-project — what did other projects choose?**
+```
+YOUR_AGENT_core op:memory_cross_project_search
+  params: { query: "<the decision topic>", crossProject: true }
+```
+
+**Memory — any relevant context from past sessions?**
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "<decision topic>" }
+```
+
+**Web — what does the broader community say?**
+Search the web for:
+- Comparison articles (X vs Y for [use case])
+- Benchmarks and performance data
+- Community consensus on best practices
+- Known limitations and gotchas
+
+### Step 3: Synthesize and Present
+
+Format the recommendation as a decision brief:
+
+```
+## Decision: [Question]
+
+### What the Vault Says
+[Existing decisions, patterns, and anti-patterns from vault]
+
+### What the Brain Recommends
+[Proven patterns, cross-project insights]
+
+### What the Web Says
+[Community consensus, benchmarks, comparison data]
+
+### Options Analysis
+
+| Criteria | Option A | Option B | Option C |
+|----------|----------|----------|----------|
+| [criteria 1] | ... | ... | ... |
+| [criteria 2] | ... | ... | ... |
+| Vault support | [existing patterns?] | [existing patterns?] | — |
+| Brain confidence | [strength score] | [strength score] | — |
+
+### Recommendation
+[Clear recommendation with reasoning]
+
+### Risks
+[What could go wrong with the recommended approach]
+```
+
+### Step 4: Capture the Decision
+
+Once the user decides, capture it to the vault for future reference:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<decision title>",
+    description: "<chosen option, rationale, rejected alternatives and why>",
+    type: "decision",
+    category: "<relevant domain>",
+    tags: ["<option-a>", "<option-b>", "decision", "<domain>"]
+  }
+```
+
+This is critical — the next person who faces the same decision will find it in the vault.
+
+## The Magic
+
+This feels like magic because the user asks "should I use X?" and instead of a generic AI opinion, they get:
+1. What their own project decided before (vault)
+2. What's proven to work across projects (brain)
+3. What other linked projects chose (cross-project)
+4. What the broader community recommends (web)
+5. A synthesized recommendation with trade-offs
+6. The decision captured for the next person who asks
+
+It's like having a senior architect who remembers every decision ever made.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify the decision type |
+| `search_intelligent` | Find previous decisions and patterns |
+| `brain_strengths` | Proven approaches |
+| `brain_recommend` | Project-specific recommendations |
+| `memory_cross_project_search` | What other projects decided |
+| `memory_search` | Session context for this decision |
+| `capture_knowledge` | Persist the final decision |

package/dist/skills/skills/brain-debrief.md

@@ -0,0 +1,214 @@
+---
+name: brain-debrief
+description: Use when the user asks "what have I learned", "brain stats", "pattern strengths", "cross-project insights", "intelligence report", "show me patterns", "what's working", "learning summary", or wants to explore accumulated knowledge and see what the brain has learned.
+---
+
+# Brain Debrief — Intelligence Report
+
+Surface what the brain has learned across sessions and projects. This turns raw vault data into actionable intelligence.
+
+## When to Use
+
+When the user wants to understand what patterns have proven valuable, what anti-patterns keep recurring, how knowledge is distributed across projects, or wants a "state of intelligence" report.
+
+## Orchestration by Query Type
+
+### "What have I learned?" (General debrief)
+
+1. Get the big picture:
+
+   ```
+   YOUR_AGENT_core op:brain_stats
+   ```
+
+   Total sessions, patterns captured, quality scores, coverage gaps.
+
+2. Get patterns ranked by proven strength:
+
+   ```
+   YOUR_AGENT_core op:brain_strengths
+   ```
+
+   Focus on strength >= 70 and successRate >= 0.7.
+
+3. Check memory landscape:
+
+   ```
+   YOUR_AGENT_core op:memory_topics
+   ```
+
+   Shows how knowledge clusters by topic.
+
+4. Check for stale knowledge:
+
+   ```
+   YOUR_AGENT_core op:vault_age_report
+   ```
+
+   Find entries that haven't been updated recently — candidates for review.
+
+5. Run a curator health audit:
+
+   ```
+   YOUR_AGENT_core op:curator_health_audit
+   ```
+
+   Vault quality score, tag normalization status, duplicate density.
+
+6. Present: top 5 strongest patterns, top 3 recurring anti-patterns, stale entries needing refresh, and coverage gaps.
+
+### "What's working across projects?" (Cross-project intelligence)
+
+1. Get patterns promoted to the global pool:
+
+   ```
+   YOUR_AGENT_core op:brain_global_patterns
+   ```
+
+2. Get recommendations based on project similarity:
+
+   ```
+   YOUR_AGENT_core op:brain_recommend
+     params: { projectName: "<current project>" }
+   ```
+
+3. Check linked projects:
+
+   ```
+   YOUR_AGENT_core op:project_linked_projects
+   ```
+
+4. Search across all projects for relevant patterns:
+
+   ```
+   YOUR_AGENT_core op:memory_cross_project_search
+     params: { query: "<topic>", crossProject: true }
+   ```
+
+5. Present: patterns from other projects that would apply here, ranked by relevance.
+
+### "Am I getting smarter?" (Learning velocity)
+
+1. Recent stats:
+
+   ```
+   YOUR_AGENT_core op:brain_stats
+     params: { since: "<7 days ago>" }
+   ```
+
+2. Longer period for comparison:
+
+   ```
+   YOUR_AGENT_core op:brain_stats
+     params: { since: "<30 days ago>" }
+   ```
+
+3. Memory stats:
+
+   ```
+   YOUR_AGENT_core op:memory_stats
+   ```
+
+4. Vault analytics:
+
+   ```
+   YOUR_AGENT_core op:admin_vault_analytics
+   ```
+
+5. Search insights — what queries are people running, what's missing:
+
+   ```
+   YOUR_AGENT_core op:admin_search_insights
+   ```
+
+6. Present: new patterns captured, strength changes, domains growing vs stagnant, search miss analysis.
+
+### "Build fresh intelligence" (Rebuild)
+
+1. Run the full pipeline:
+
+   ```
+   YOUR_AGENT_core op:brain_build_intelligence
+   ```
+
+   Compute strengths, update global registry, refresh project profiles.
+
+2. Consolidate vault (curator cleanup):
+
+   ```
+   YOUR_AGENT_core op:curator_consolidate
+   ```
+
+3. Show updated metrics:
+
+   ```
+   YOUR_AGENT_core op:brain_stats
+   ```
+
+4. Present: what changed after the rebuild.
+
+### "Export what I know" (Portability)
+
+Export brain intelligence:
+
+```
+YOUR_AGENT_core op:brain_export
+```
+
+Export memory:
+
+```
+YOUR_AGENT_core op:memory_export
+```
+
+Export vault as backup:
+
+```
+YOUR_AGENT_core op:vault_backup
+```
+
+These can be imported into another vault:
+
+```
+YOUR_AGENT_core op:brain_import
+YOUR_AGENT_core op:memory_import
+YOUR_AGENT_core op:vault_import
+```
+
+## Presenting Intelligence
+
+Format as a report:
+
+- **Strengths**: Top patterns with strength scores and domains
+- **Risks**: Recurring anti-patterns that keep appearing
+- **Gaps**: Domains with low coverage or stale knowledge
+- **Stale**: Entries needing refresh (from age report)
+- **Quality**: Curator health audit score
+- **Recommendations**: What to focus on learning next
+- **Search Misses**: What people are looking for but not finding
+
+## Exit Criteria
+
+Debrief is complete when the user's specific question has been answered with data from the brain. For general debriefs, present stats + strengths + gaps + stale entries at minimum.
+
+## Agent Tools Reference
+
+| Op                                | When to Use                                     |
+| --------------------------------- | ----------------------------------------------- |
+| `brain_stats`                     | Aggregate metrics — sessions, patterns, quality |
+| `brain_strengths`                 | Patterns ranked by proven strength              |
+| `brain_global_patterns`           | Cross-project promoted patterns                 |
+| `brain_recommend`                 | Project-similarity recommendations              |
+| `brain_build_intelligence`        | Rebuild full intelligence pipeline              |
+| `brain_export` / `brain_import`   | Portable intelligence transfer                  |
+| `memory_topics`                   | Knowledge clusters by topic                     |
+| `memory_stats`                    | Memory statistics                               |
+| `memory_export` / `memory_import` | Memory portability                              |
+| `memory_cross_project_search`     | Search across linked projects                   |
+| `vault_age_report`                | Find stale entries needing refresh              |
+| `vault_backup` / `vault_import`   | Vault backup and restore                        |
+| `curator_health_audit`            | Vault quality score and status                  |
+| `curator_consolidate`             | Full vault cleanup pipeline                     |
+| `admin_vault_analytics`           | Overall knowledge quality metrics               |
+| `admin_search_insights`           | Search miss analysis — what's not found         |
+| `project_linked_projects`         | See connected projects                          |