@soleri/forge 5.4.0 → 5.5.0

package/dist/skills/health-check.md

@@ -0,0 +1,225 @@
+---
+name: health-check
+description: Use when the user asks "check health", "vault health", "knowledge quality", "clean up vault", "groom knowledge", "maintenance", "housekeeping", "deduplicate", "find contradictions", or wants to run a maintenance cycle on the knowledge base to keep it healthy and accurate.
+---
+
+# Health Check — Knowledge Base Maintenance
+
+Run a comprehensive maintenance cycle on the knowledge base. Finds stale entries, duplicates, contradictions, quality issues, and fixes them. Like a doctor's checkup for your knowledge.
+
+## When to Use
+
+- Weekly/monthly maintenance ritual
+- "Is my vault healthy?"
+- "Clean up my knowledge base"
+- Before a retrospective (clean data = better insights)
+- After a knowledge harvest (post-ingest quality check)
+
+## The Magic: Comprehensive Quality Audit
+
+### Step 1: System Health
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+```
+YOUR_AGENT_core op:admin_diagnostic
+```
+
+Catches infrastructure issues — database corruption, stale caches, configuration problems.
+
+### Step 2: Vault Metrics
+
+```
+YOUR_AGENT_core op:admin_vault_size
+```
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+
+```
+YOUR_AGENT_core op:vault_tags
+```
+
+Shows the big picture: how many entries, which domains, tag distribution.
+
+### Step 3: Quality Audit
+
+Run the curator's health audit — the most comprehensive quality check:
+
+```
+YOUR_AGENT_core op:curator_health_audit
+```
+
+This checks: tag normalization, description quality, severity distribution, domain coverage balance, and overall vault quality score.
+
+### Step 4: Find Duplicates
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+Present duplicates for review. Offer to merge or remove them.
+
+### Step 5: Find Contradictions
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+Contradictions are entries that give conflicting advice. Present each pair for the user to resolve:
+
+```
+YOUR_AGENT_core op:curator_resolve_contradiction
+  params: { contradictionId: "<id>" }
+```
+
+### Step 6: Find Stale Entries
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+Entries older than 30 days without updates are candidates for:
+- Refresh (still relevant, needs updating)
+- Archive (no longer relevant)
+- Delete (incorrect or superseded)
+
+### Step 7: Check Search Quality
+
+```
+YOUR_AGENT_core op:admin_search_insights
+```
+
+Shows what people search for but don't find — these are knowledge gaps that should be filled.
+
+### Step 8: Memory Health
+
+```
+YOUR_AGENT_core op:memory_stats
+```
+
+```
+YOUR_AGENT_core op:memory_deduplicate
+```
+
+Clean up duplicate memories.
+
+### Step 9: Governance Queue
+
+Check if any proposals are pending review:
+
+```
+YOUR_AGENT_core op:governance_proposals
+  params: { action: "list" }
+```
+
+```
+YOUR_AGENT_core op:governance_stats
+```
+
+Expire stale proposals:
+
+```
+YOUR_AGENT_core op:governance_expire
+```
+
+### Step 10: Fix Everything (Optional)
+
+If the user approves, run the full cleanup:
+
+**Groom all entries — normalize tags, fix metadata:**
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+**Full consolidation — deduplicate, normalize, quality-score:**
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+**Prune stale memory:**
+```
+YOUR_AGENT_core op:memory_prune
+```
+
+**Rebuild brain intelligence with clean data:**
+```
+YOUR_AGENT_core op:brain_build_intelligence
+```
+
+**Reset caches to pick up changes:**
+```
+YOUR_AGENT_core op:admin_reset_cache
+```
+
+## Presenting the Health Report
+
+```
+## Knowledge Health Report
+
+### System
+| Check | Status |
+|-------|--------|
+| Infrastructure | OK / Issues |
+| Database | OK / Issues |
+| Cache | OK / Issues |
+
+### Vault Quality
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total entries | X | — |
+| Quality score | X/100 | Good/Warning/Critical |
+| Domains | X | — |
+| Tags | X | — |
+
+### Issues Found
+| Issue | Count | Action |
+|-------|-------|--------|
+| Duplicates | X | Merge |
+| Contradictions | X | Resolve |
+| Stale entries (>30d) | X | Review |
+| Search misses | X | Fill gaps |
+| Pending proposals | X | Review |
+
+### Recommended Actions
+1. [Most impactful fix]
+2. [Second most impactful]
+3. [Third most impactful]
+```
+
+## The Magic
+
+This feels like magic because knowledge bases normally decay silently — duplicates accumulate, entries go stale, contradictions creep in, gaps grow. This skill makes decay visible and fixable in one command. It's like having a librarian who does a weekly audit of every book on every shelf.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `admin_health` | System health check |
+| `admin_diagnostic` | Comprehensive system diagnostic |
+| `admin_vault_size` | Vault storage metrics |
+| `admin_vault_analytics` | Knowledge quality metrics |
+| `admin_search_insights` | Search miss analysis |
+| `admin_reset_cache` | Clear caches after cleanup |
+| `vault_domains` / `vault_tags` | Knowledge landscape |
+| `vault_age_report` | Stale entry detection |
+| `curator_health_audit` | Quality score and audit |
+| `curator_detect_duplicates` | Find duplicates |
+| `curator_contradictions` | Find conflicting entries |
+| `curator_resolve_contradiction` | Resolve conflicts |
+| `curator_groom_all` | Batch tag normalization |
+| `curator_consolidate` | Full cleanup pipeline |
+| `memory_stats` | Memory health |
+| `memory_deduplicate` | Remove duplicate memories |
+| `memory_prune` | Remove stale memories |
+| `governance_proposals` | Pending review queue |
+| `governance_stats` | Governance metrics |
+| `governance_expire` | Expire stale proposals |
+| `brain_build_intelligence` | Rebuild after cleanup |

package/dist/skills/knowledge-harvest.md

@@ -0,0 +1,178 @@
+---
+name: knowledge-harvest
+description: Use when the user says "learn from this", "extract patterns", "harvest knowledge", "ingest this document", "read this and capture", "populate vault from", or points at code, docs, PRs, or any text and wants the agent 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, postmortems, or any text — the agent reads it, extracts every pattern, anti-pattern, decision, and principle, then captures them all to the vault. Zero-friction knowledge population.
+
+## When to Use
+
+- "Learn from this file" / "Extract patterns from this codebase"
+- "Read our architecture doc and capture everything"
+- "Harvest knowledge from this PR"
+- "Ingest this post-mortem"
+- Populating a fresh vault with existing team knowledge
+
+## The Magic: Automated Knowledge Extraction
+
+### Step 1: Understand the Source
+
+Read the target content (code, docs, etc.) and classify what type of knowledge it contains:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "Extract knowledge from: <source description>" }
+```
+
+### Step 2: Check What's Already Known
+
+Before extracting, search the vault to avoid duplicates:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<topic of the source material>" }
+```
+
+```
+YOUR_AGENT_core op:vault_tags
+```
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+
+This tells you what the vault already covers — focus extraction on gaps.
+
+### Step 3: Extract and Classify
+
+Read through the source material and identify:
+
+| Type | What to Look For |
+|------|-----------------|
+| **pattern** | "We always do X because Y" — repeatable approaches |
+| **anti-pattern** | "Don't do X because Y" — known mistakes |
+| **decision** | "We chose X over Y because Z" — architectural choices |
+| **principle** | "We believe X" — guiding rules |
+| **workflow** | "The process for X is: step 1, step 2..." — procedures |
+
+For each extracted item, determine:
+- **Category**: Which domain it belongs to
+- **Severity**: critical / warning / suggestion
+- **Tags**: Searchable keywords
+
+### Step 4: Batch Capture
+
+For each extracted item, capture to the vault:
+
+```
+YOUR_AGENT_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>"],
+    severity: "<critical|warning|suggestion>",
+    example: "<code snippet or quote from source>",
+    why: "<reasoning>"
+  }
+```
+
+Present each capture to the user as you go:
+```
+Captured: api-auth-jwt (pattern, critical)
+  → "Use short-lived JWTs for authentication"
+  Auto-tags: auth, jwt, security
+```
+
+### Step 5: Post-Harvest Quality
+
+After all items captured, run quality checks:
+
+**Detect any duplicates created during harvest:**
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Groom all new entries — normalize tags, fix metadata:**
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+**Enrich entries with additional context:**
+```
+YOUR_AGENT_core op:curator_enrich
+  params: { entryId: "<id>" }
+```
+
+**Check for contradictions with existing knowledge:**
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+### Step 6: Verify Harvest Results
+
+Check vault health after the harvest:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+Present a summary:
+```
+## Harvest Complete
+
+Source: [file/doc name]
+Extracted: X entries
+  - Y patterns
+  - Z anti-patterns
+  - W decisions
+  - V principles
+
+Duplicates found: N (merged/skipped)
+Contradictions found: N (flagged for review)
+Vault health: OK
+```
+
+### Step 7: Promote Universal Patterns (Optional)
+
+If any extracted patterns apply across projects:
+
+```
+YOUR_AGENT_core op:memory_promote_to_global
+  params: { entryId: "<id>" }
+```
+
+## The Magic
+
+This feels like magic because the user points at a 50-page architecture doc and says "learn from this" — and 2 minutes later, the vault has 30 classified, tagged, searchable patterns that inform every future conversation. The agent didn't just read the doc — it understood it, classified it, deduplicated it, and made it permanent.
+
+## Tips for Best Results
+
+- **Start with your team's top 10 decisions** — the ones people keep asking about
+- **Feed postmortems** — they're goldmines of anti-patterns
+- **Feed architecture decision records (ADRs)** — pure decision captures
+- **Feed code review comments** — patterns that reviewers enforce repeatedly
+- **Feed onboarding docs** — principles that new team members need to learn
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify the source material |
+| `search_intelligent` | Check for existing knowledge |
+| `vault_tags` / `vault_domains` | See what's already covered |
+| `capture_knowledge` | Capture each extracted item |
+| `curator_detect_duplicates` | Find duplicates post-harvest |
+| `curator_groom_all` | Normalize all new entries |
+| `curator_enrich` | LLM-enrich entries |
+| `curator_contradictions` | Find conflicts with existing knowledge |
+| `memory_promote_to_global` | Share universal patterns cross-project |
+| `admin_health` | Post-harvest health check |
+| `admin_vault_analytics` | Knowledge quality metrics |

package/dist/skills/onboard-me.md

@@ -0,0 +1,197 @@
+---
+name: onboard-me
+description: Use when the user says "onboard me", "I'm new here", "what should I know", "project overview", "show me the ropes", "knowledge tour", "what are the rules", "how does this project work", or is new to the project and needs a structured introduction to its knowledge, patterns, decisions, and conventions.
+---
+
+# Onboard Me — Instant Project Intelligence
+
+Give any newcomer a structured tour of everything the vault knows about this project. Decisions, patterns, anti-patterns, principles, conventions — all in one guided walkthrough. Turns months of tribal knowledge into a 5-minute briefing.
+
+## When to Use
+
+- New team member joining the project
+- Switching context to a project you haven't touched in a while
+- "What should I know before I start?"
+- "What are the rules here?"
+
+## The Magic: Structured Knowledge Tour
+
+### Step 1: Project Overview
+
+Get the project identity and registration:
+
+```
+YOUR_AGENT_core op:identity
+```
+
+```
+YOUR_AGENT_core op:project_get
+```
+
+Get project-specific rules and conventions:
+
+```
+YOUR_AGENT_core op:project_list_rules
+```
+
+Get behavior rules:
+
+```
+YOUR_AGENT_core op:get_behavior_rules
+```
+
+### Step 2: Knowledge Landscape
+
+Show what the vault knows, organized by domain:
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+
+```
+YOUR_AGENT_core op:vault_tags
+```
+
+```
+YOUR_AGENT_core op:admin_vault_size
+```
+
+Present: "This project has X entries across Y domains, covering Z tags."
+
+### Step 3: Critical Knowledge
+
+Search for the most important entries — critical severity first:
+
+```
+YOUR_AGENT_core op:search
+  params: { severity: "critical" }
+```
+
+These are the "must know" items — rules that cannot be violated.
+
+### Step 4: Key Decisions
+
+Search for architectural and design decisions:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "architectural decision design choice" }
+```
+
+Present the top decisions with their rationale — this is the "why" behind the codebase.
+
+### Step 5: Strongest Patterns
+
+Show what the brain has validated as proven approaches:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+These are the "how" — patterns that have been used successfully and should be followed.
+
+### Step 6: Anti-Patterns to Avoid
+
+Search for anti-patterns — things that went wrong and shouldn't be repeated:
+
+```
+YOUR_AGENT_core op:search
+  params: { type: "anti-pattern" }
+```
+
+Present as a "don't do this" list with the reasoning.
+
+### Step 7: Cross-Project Context
+
+Check if this project is linked to others:
+
+```
+YOUR_AGENT_core op:project_linked_projects
+```
+
+If linked, show what patterns are shared:
+
+```
+YOUR_AGENT_core op:brain_global_patterns
+```
+
+### Step 8: Knowledge Gaps
+
+Show what's NOT in the vault — areas where the newcomer should ask questions:
+
+```
+YOUR_AGENT_core op:admin_search_insights
+```
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+## Presenting the Onboarding
+
+```
+## Welcome to [Project Name]
+
+**Role:** [project description]
+**Domains:** [list of knowledge domains]
+**Vault:** X entries across Y domains
+
+---
+
+### Critical Rules (Must Follow)
+[Critical severity entries — non-negotiable conventions]
+
+### Key Decisions
+[Top architectural decisions with rationale]
+"We chose X over Y because Z"
+
+### Proven Patterns (Do This)
+[Top brain-strength patterns — the project's best practices]
+
+### Anti-Patterns (Don't Do This)
+[Known mistakes — save yourself the debugging]
+
+### Project Conventions
+[Project rules, behavior rules, naming conventions]
+
+### Related Projects
+[Linked projects and shared patterns]
+
+### Knowledge Gaps
+[Areas not well-documented — ask the team about these]
+
+---
+
+**Tip:** Use `/vault-navigator` to search for specific topics as you work.
+Use `/second-opinion` before making any architectural decision.
+```
+
+## The Magic
+
+This feels like magic because a new team member says "onboard me" and instantly gets:
+1. Every critical rule they must follow
+2. Every architectural decision and why it was made
+3. Proven patterns to follow
+4. Anti-patterns to avoid
+5. What's shared with other projects
+6. Where the knowledge gaps are
+
+No other onboarding tool does this — it's not a static wiki, it's a living knowledge base that grows with the project.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `identity` | Project persona and description |
+| `project_get` | Project registration details |
+| `project_list_rules` | Project-specific rules |
+| `get_behavior_rules` | Behavioral conventions |
+| `vault_domains` / `vault_tags` | Knowledge landscape |
+| `admin_vault_size` | How much knowledge exists |
+| `search` | Find critical entries and anti-patterns |
+| `search_intelligent` | Find decisions and patterns |
+| `brain_strengths` | Proven approaches |
+| `brain_global_patterns` | Cross-project patterns |
+| `project_linked_projects` | Related projects |
+| `admin_search_insights` | What's not in the vault |
+| `vault_age_report` | Stale knowledge areas |