@soleri/forge 9.0.0 → 9.0.1

package/dist/skills/health-check/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: health-check
+description: Use when running maintenance on the knowledge base — deduplication, contradiction resolution, stale entry cleanup, or vault quality auditing.
+---
+
+# Health Check — Knowledge Base Maintenance
+
+Comprehensive maintenance cycle on the knowledge base. Finds stale entries, duplicates, contradictions, and quality issues.
+
+## Steps
+
+### 1. System Health
+
+```
+ernesto_core op:admin_health
+ernesto_core op:admin_diagnostic
+```
+
+### 2. Vault Metrics
+
+```
+ernesto_core op:admin_vault_size
+ernesto_core op:admin_vault_analytics
+ernesto_core op:vault_domains
+ernesto_core op:vault_tags
+```
+
+### 3. Quality Audit
+
+```
+ernesto_core op:curator_health_audit
+```
+
+### 4. Find Duplicates
+
+```
+ernesto_core op:curator_detect_duplicates
+```
+
+### 5. Find Contradictions
+
+```
+ernesto_core op:curator_contradictions
+ernesto_core op:curator_resolve_contradiction
+  params: { contradictionId: "<id>" }
+```
+
+### 6. Find Stale Entries
+
+```
+ernesto_core op:vault_age_report
+```
+
+Entries >30 days without updates: refresh, archive, or delete.
+
+### 7. Check Search Quality
+
+```
+ernesto_core op:admin_search_insights
+```
+
+### 8. Memory Health
+
+```
+ernesto_core op:memory_stats
+ernesto_core op:memory_deduplicate
+```
+
+### 9. Governance Queue
+
+```
+ernesto_core op:governance_proposals params: { action: "list" }
+ernesto_core op:governance_expire
+```
+
+### 10. Fix Everything (Optional, with user approval)
+
+- `op:curator_groom_all` — normalize tags, fix metadata
+- `op:curator_consolidate` — deduplicate, normalize, quality-score
+- `op:memory_prune` — remove stale memories
+- `op:brain_build_intelligence` — rebuild with clean data
+- `op:admin_reset_cache` — clear caches
+
+## Presenting the Report
+
+```
+## Knowledge Health Report
+
+### System
+| Check | Status |
+|-------|--------|
+| Infrastructure | OK / Issues |
+
+### Vault Quality
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total entries | X | — |
+| Quality score | X/100 | Good/Warning/Critical |
+
+### Issues Found
+| Issue | Count | Action |
+|-------|-------|--------|
+| Duplicates | X | Merge |
+| Contradictions | X | Resolve |
+| Stale entries (>30d) | X | Review |
+| Search misses | X | Fill gaps |
+
+### Recommended Actions
+1. [Most impactful fix]
+2. [Second most impactful]
+```
+
+## Common Mistakes
+
+- Running cleanup without presenting findings to user first
+- Skipping search insights (missing knowledge gaps)
+- Not rebuilding brain intelligence after major cleanup
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `admin_health` / `admin_diagnostic` | System health |
+| `admin_vault_analytics` / `admin_vault_size` | Vault metrics |
+| `curator_health_audit` | Quality score |
+| `curator_detect_duplicates` | Find duplicates |
+| `curator_contradictions` | Find conflicts |
+| `vault_age_report` | Stale entries |
+| `admin_search_insights` | Search miss analysis |
+| `curator_consolidate` | Full cleanup pipeline |
+| `brain_build_intelligence` | Rebuild after cleanup |

package/dist/skills/knowledge-harvest/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: knowledge-harvest
+description: Use when pointing at code, docs, PRs, or any text to automatically extract and capture patterns, anti-patterns, and decisions into the vault.
+---
+
+# Knowledge Harvest — Extract Patterns From Anything
+
+Point at code, docs, PRs, architecture decisions, or postmortems — the agent extracts every pattern, anti-pattern, decision, and principle, then captures them to the vault.
+
+## Steps
+
+### 1. Understand the Source
+
+Read target content and classify: `ernesto_core op:route_intent params: { prompt: "Extract knowledge from: <source>" }`
+
+### 2. Check What's Already Known
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<topic of source material>" }
+ernesto_core op:vault_tags
+ernesto_core op:vault_domains
+```
+
+Focus extraction on gaps — skip what vault already covers.
+
+### 3. Extract and Classify
+
+| Type | What to Look For |
+|------|-----------------|
+| **pattern** | Repeatable approaches that work |
+| **anti-pattern** | Known mistakes to avoid |
+| **decision** | Architectural choices with rationale |
+| **principle** | Guiding rules or heuristics |
+| **workflow** | Step-by-step procedures |
+
+For each: determine category, severity, and tags.
+
+### 4. Batch Capture
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<clear, searchable name>",
+    description: "<what it is, when to apply, why it matters>",
+    type: "<pattern|anti-pattern|decision|principle|workflow>",
+    category: "<domain>",
+    tags: ["<tag1>", "<tag2>"],
+    example: "<code snippet or quote>",
+    why: "<reasoning>"
+  }
+```
+
+Present each capture as you go: `Captured: api-auth-jwt (pattern, critical)`
+
+### 5. Post-Harvest Quality
+
+- `op:curator_detect_duplicates` — find duplicates created during harvest
+- `op:curator_groom_all` — normalize tags, fix metadata
+- `op:curator_contradictions` — check for conflicts
+
+### 6. Verify and Report
+
+```
+## Harvest Complete
+
+Source: [name]
+Extracted: X entries (Y patterns, Z anti-patterns, W decisions)
+Duplicates: N (merged/skipped)
+Contradictions: N (flagged)
+Vault health: OK
+```
+
+Optionally promote universal patterns: `op:memory_promote_to_global`.
+
+## Common Mistakes
+
+- Not checking vault before extracting (creates duplicates)
+- Capturing too-granular entries instead of atomic, searchable ones
+- Skipping post-harvest quality checks (duplicates and contradictions accumulate)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Check existing knowledge |
+| `vault_tags` / `vault_domains` | See what's covered |
+| `capture_knowledge` | Capture each item |
+| `curator_detect_duplicates` | Post-harvest dedup |
+| `curator_groom_all` | Normalize entries |
+| `curator_contradictions` | Find conflicts |
+| `memory_promote_to_global` | Share cross-project |
+| `admin_vault_analytics` | Knowledge quality |

package/dist/skills/onboard-me/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: onboard-me
+description: Use when someone is new to the project and needs a structured introduction to its knowledge, patterns, decisions, and conventions.
+---
+
+# Onboard Me — Instant Project Intelligence
+
+Structured tour of everything the vault knows about this project. Decisions, patterns, anti-patterns, conventions — all in one walkthrough.
+
+## Steps
+
+### 1. Project Overview
+
+```
+ernesto_core op:identity
+ernesto_core op:project_get
+ernesto_core op:project_list_rules
+ernesto_core op:get_behavior_rules
+```
+
+### 2. Knowledge Landscape
+
+```
+ernesto_core op:vault_domains
+ernesto_core op:vault_tags
+ernesto_core op:admin_vault_size
+```
+
+### 3. Critical Knowledge
+
+```
+ernesto_core op:search
+  params: { severity: "critical" }
+```
+
+### 4. Key Decisions
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "architectural decision design choice" }
+```
+
+### 5. Strongest Patterns
+
+```
+ernesto_core op:brain_strengths
+```
+
+### 6. Anti-Patterns to Avoid
+
+```
+ernesto_core op:search
+  params: { type: "anti-pattern" }
+```
+
+### 7. Cross-Project Context
+
+```
+ernesto_core op:project_linked_projects
+ernesto_core op:brain_global_patterns
+```
+
+### 8. Knowledge Gaps
+
+```
+ernesto_core op:admin_search_insights
+ernesto_core op:vault_age_report
+```
+
+## Presenting the Onboarding
+
+```
+## Welcome to [Project Name]
+
+**Domains:** [list] | **Vault:** X entries across Y domains
+
+### Critical Rules (Must Follow)
+[Non-negotiable conventions]
+
+### Key Decisions
+[Top architectural decisions with rationale]
+
+### Proven Patterns (Do This)
+[Brain-strength patterns]
+
+### Anti-Patterns (Don't Do This)
+[Known mistakes]
+
+### Project Conventions
+[Rules, naming conventions]
+
+### Related Projects
+[Linked projects and shared patterns]
+
+### Knowledge Gaps
+[Areas not well-documented — ask the team]
+```
+
+**Tip:** Use vault-navigator to search topics as you work. Use second-opinion before architectural decisions.
+
+## Common Mistakes
+
+- Dumping all vault entries instead of curating the most important ones
+- Skipping anti-patterns (newcomers need to know what NOT to do)
+- Not surfacing knowledge gaps (newcomers should know where documentation is thin)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `identity` / `project_get` | Project overview |
+| `project_list_rules` / `get_behavior_rules` | Conventions |
+| `vault_domains` / `vault_tags` | Knowledge landscape |
+| `search` (severity/type filters) | Critical rules, anti-patterns |
+| `search_intelligent` | Key decisions |
+| `brain_strengths` | Proven patterns |
+| `brain_global_patterns` | Cross-project patterns |
+| `admin_search_insights` | Knowledge gaps |

package/dist/skills/retrospective/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: retrospective
+description: Use when reflecting on recent work — sprint retros, weekly summaries, learning reports, or extracting actionable insights from accumulated session data.
+---
+
+# Retrospective — Learning Report From Real Data
+
+Generate a data-driven retrospective from session data, vault captures, plan outcomes, and brain intelligence.
+
+## Steps
+
+### 1. Gather Data
+
+```
+ernesto_core op:brain_stats
+ernesto_core op:brain_stats params: { since: "<start of period>" }
+ernesto_core op:brain_strengths
+ernesto_core op:vault_recent
+ernesto_core op:memory_topics
+ernesto_core op:memory_stats
+ernesto_core op:plan_stats
+ernesto_core op:admin_search_insights
+ernesto_core op:admin_vault_analytics
+```
+
+### 2. Analyze Patterns
+
+```
+ernesto_core op:vault_age_report
+ernesto_core op:curator_detect_duplicates
+ernesto_core op:curator_contradictions
+ernesto_core op:curator_health_audit
+```
+
+### 3. Present the Retrospective
+
+```
+## Retrospective: [Period]
+
+### By the Numbers
+| Metric | This Period | Previous | Trend |
+|--------|-----------|----------|-------|
+| Patterns captured | X | Y | up/down |
+| Plans completed | X | Y | up/down |
+| Brain strength (avg) | X | Y | up/down |
+| Search misses | X | Y | up/down |
+
+### What Went Well
+[High brain strength patterns, completed plans, growing domains]
+
+### What Didn't Go Well
+[Recurring anti-patterns, failed plans, knowledge gaps]
+
+### Vault Health
+Quality: X/100 | Duplicates: N | Contradictions: N | Stale: N
+
+### Recommendations
+1. [Data-driven action item]
+2. [Data-driven action item]
+```
+
+### 4. Capture the Retrospective
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "Retrospective — [period]",
+    description: "<key findings and action items>",
+    type: "workflow",
+    category: "meta",
+    tags: ["retrospective"]
+  }
+```
+
+### 5. Clean Up (Optional)
+
+If quality issues found: `op:curator_consolidate` then `op:brain_build_intelligence`.
+
+## Common Mistakes
+
+- Presenting AI opinions instead of actual vault/brain metrics
+- Not comparing periods (missing trends)
+- Skipping the capture step (retrospective insights are lost)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `brain_stats` / `brain_strengths` | Metrics and patterns |
+| `vault_recent` | Recent captures |
+| `memory_topics` / `memory_stats` | Knowledge clusters |
+| `plan_stats` | Plan completion |
+| `admin_search_insights` | Search misses |
+| `curator_health_audit` | Vault quality |
+| `capture_knowledge` | Persist retrospective |

package/dist/skills/second-opinion/SKILL.md

@@ -0,0 +1,97 @@
+---
+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.
+---
+
+# Second Opinion — Decision Support From All Sources
+
+Get an informed recommendation that synthesizes vault knowledge, brain patterns, cross-project experience, and web research before making any technical decision.
+
+## Steps
+
+### 1. Understand the Decision
+
+```
+ernesto_core op:route_intent
+  params: { prompt: "<user's question>" }
+```
+
+### 2. Search All Knowledge Sources
+
+**Vault** — previous decisions, patterns, anti-patterns:
+```
+ernesto_core op:search_intelligent
+  params: { query: "<the decision or options>" }
+```
+
+**Brain** — proven approaches:
+```
+ernesto_core op:brain_strengths
+ernesto_core op:brain_recommend
+  params: { projectName: "<current project>" }
+```
+
+**Cross-project** — what other projects chose:
+```
+ernesto_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+```
+
+**Web** — community consensus, benchmarks, comparison articles.
+
+### 3. Synthesize and Present
+
+```
+## Decision: [Question]
+
+### What the Vault Says
+[Existing decisions, patterns, anti-patterns]
+
+### What the Brain Recommends
+[Proven patterns, cross-project insights]
+
+### What the Web Says
+[Community consensus, benchmarks]
+
+### Options Analysis
+| Criteria | Option A | Option B |
+|----------|----------|----------|
+| [criteria] | ... | ... |
+| Vault support | [patterns?] | [patterns?] |
+
+### Recommendation
+[Clear recommendation with reasoning]
+
+### Risks
+[What could go wrong]
+```
+
+### 4. Capture the Decision
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<decision title>",
+    description: "<chosen option, rationale, rejected alternatives>",
+    type: "decision",
+    category: "<domain>",
+    tags: ["decision"]
+  }
+```
+
+## Common Mistakes
+
+- Giving a generic AI opinion instead of searching vault/brain first
+- Not capturing the final decision (next person faces the same question blind)
+- Skipping cross-project search (another project may have solved this)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify decision type |
+| `search_intelligent` | Find previous decisions |
+| `brain_strengths` / `brain_recommend` | Proven approaches |
+| `memory_cross_project_search` | Other projects' choices |
+| `memory_search` | Session context |
+| `capture_knowledge` | Persist the decision |

package/dist/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior — before proposing fixes.
+---
+
+# Systematic Debugging
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+## Phase 0: Search Before Investigating
+
+**BEFORE touching any code:**
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<bug or error message>" }
+ernesto_core op:brain_strengths
+ernesto_core op:memory_search
+  params: { query: "<error or symptom>" }
+```
+
+If vault has a match — apply it directly. Then search web: exact error message, GitHub issues, Stack Overflow, official docs.
+
+Only if vault and web produce no answer, proceed to Phase 1.
+
+## Start a Debug Loop
+
+```
+ernesto_core op:loop_start
+  params: { prompt: "Debug: <bug>", mode: "custom" }
+```
+
+## The Four Phases
+
+### Phase 1: Root Cause Investigation
+
+1. Read error messages carefully
+2. Reproduce consistently
+3. Check recent changes
+4. Gather evidence at component boundaries
+5. Trace data flow backward through call stack
+
+Track each step with `op:loop_iterate`.
+
+### Phase 2: Pattern Analysis
+
+Find working examples, compare against references (read completely), identify differences, understand dependencies. Use `op:search_intelligent` for comparison.
+
+### Phase 3: Hypothesis and Testing
+
+Form single hypothesis, test minimally (one variable at a time), verify before continuing. If unsure — ask for help.
+
+### Phase 4: Implementation
+
+1. Create failing test (use test-driven-development skill)
+2. Implement single fix (root cause only)
+3. Verify fix
+4. If < 3 attempts failed, return to Phase 1. If >= 3, STOP — question architecture with human partner.
+
+## Phase 5: Capture the Learning
+
+```
+ernesto_core op:loop_complete
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<bug>",
+    description: "<root cause, solution, what made it hard to find>",
+    type: "anti-pattern",
+    category: "<domain>",
+    tags: ["<relevant>"]
+  }
+ernesto_core op:session_capture
+```
+
+## Red Flags — STOP and Return to Phase 1
+
+- "Quick fix for now" / "Just try changing X"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" after 2+ failures
+- Each fix reveals a new problem elsewhere
+
+## Common Mistakes
+
+- Skipping vault search ("I know this one") — 30 seconds saves hours
+- Making multiple changes at once (can't isolate what worked)
+- Skipping the capture step (same bug will recur)
+
+## Quick Reference
+
+| Phase | Key Activities | Tools |
+|-------|---------------|-------|
+| 0. Search | Vault, web, memory | `search_intelligent`, `brain_strengths`, `memory_search` |
+| 1. Root Cause | Read errors, reproduce, trace | `loop_iterate` |
+| 2. Pattern | Find working examples, compare | `search_intelligent` |
+| 3. Hypothesis | Form theory, test minimally | `loop_iterate` |
+| 4. Implementation | Test, fix, verify | `loop_iterate` |
+| 5. Capture | Persist root cause | `capture_knowledge`, `loop_complete` |
+
+**Related skills:** test-driven-development, verification-before-completion, fix-and-learn