@soleri/forge 5.14.2 → 5.14.4

package/dist/skills/skills/vault-capture.md

@@ -0,0 +1,170 @@
+---
+name: vault-capture
+description: Use when the user says "capture this", "save to vault", "remember this pattern", "log this anti-pattern", "store this knowledge", "add to vault", "capture what we learned", or wants to persist a pattern, anti-pattern, workflow, or principle to the knowledge base.
+---
+
+# Vault Capture — Persist Knowledge
+
+Capture patterns, anti-patterns, workflows, and principles to the vault. Captured knowledge compounds — it informs future vault searches, brain recommendations, and team reviews.
+
+## When to Use
+
+After discovering something worth remembering: a solution that worked, a mistake to avoid, a workflow that proved effective, or a principle that should guide future work.
+
+## Orchestration Sequence
+
+### Step 1: Check for Duplicates
+
+Call `YOUR_AGENT_core op:search_intelligent` with the knowledge title or description. If a similar entry exists, consider updating it instead of creating a duplicate.
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<knowledge title or description>" }
+```
+
+Also run duplicate detection explicitly:
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+If duplicates are found, decide: update the existing entry or merge them.
+
+### Step 2: Classify the Knowledge
+
+Determine the entry type:
+
+- **pattern** — Something that works and should be repeated
+- **anti-pattern** — Something that fails and should be avoided
+- **workflow** — A sequence of steps for a specific task
+- **principle** — A guiding rule or heuristic
+- **decision** — An architectural or design choice with rationale
+
+Use intent routing to help classify:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "<description of the knowledge>" }
+```
+
+### Step 3: Capture
+
+For quick, single-entry captures:
+Call `YOUR_AGENT_core op:capture_knowledge` with:
+
+- **title**: Clear, searchable name
+- **description**: What it is and when it applies
+- **type**: From Step 2 classification
+- **category**: Domain area (e.g., "component-patterns", "api-design", "infrastructure")
+- **tags**: Searchable keywords
+- **example**: Code snippet or before/after if applicable
+- **why**: The reasoning — this is what makes the entry actionable
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<clear, searchable name>",
+    description: "<what it is and when it applies>",
+    type: "<pattern|anti-pattern|workflow|principle|decision>",
+    category: "<domain area>",
+    tags: ["<tag1>", "<tag2>"],
+    example: "<code or before/after>",
+    why: "<reasoning>"
+  }
+```
+
+For quick captures:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: { title: "<name>", description: "<details>" }
+```
+
+### Step 4: Post-Capture Quality
+
+After capturing, run the curator to ensure quality:
+
+**Groom the entry** — normalize tags, fix metadata:
+
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryId: "<captured entry id>" }
+```
+
+**Enrich the entry** — use LLM to add context, improve description:
+
+```
+YOUR_AGENT_core op:curator_enrich
+  params: { entryId: "<captured entry id>" }
+```
+
+**Check for contradictions** — does this conflict with existing knowledge?
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+If contradictions found, resolve them:
+
+```
+YOUR_AGENT_core op:curator_resolve_contradiction
+  params: { contradictionId: "<id>" }
+```
+
+### Step 5: Handle Governance (if enabled)
+
+If governance policy requires review, the capture returns a `proposalId`. The entry is queued for approval.
+
+```
+YOUR_AGENT_core op:governance_proposals
+  params: { action: "list" }
+```
+
+Present pending proposals to the user for approval.
+
+### Step 6: Promote to Global (Optional)
+
+If the knowledge applies across projects (not project-specific):
+
+```
+YOUR_AGENT_core op:memory_promote_to_global
+  params: { entryId: "<entry id>" }
+```
+
+This makes it available in cross-project searches and brain recommendations.
+
+### Step 7: Verify Health
+
+Confirm the capture was stored and vault health is maintained:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Check vault analytics for overall knowledge quality:
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+## Exit Criteria
+
+Capture is complete when: the entry is stored (or queued for review), categorized, tagged, groomed, and vault health confirmed. If promoted to global, cross-project availability is verified.
+
+## Agent Tools Reference
+
+| Op                              | When to Use                         |
+| ------------------------------- | ----------------------------------- |
+| `search_intelligent`            | Check for duplicates before capture |
+| `curator_detect_duplicates`     | Explicit duplicate detection        |
+| `route_intent`                  | Help classify knowledge type        |
+| `capture_knowledge`             | Full-metadata capture               |
+| `capture_quick`                 | Fast capture for simple entries     |
+| `curator_groom`                 | Normalize tags and metadata         |
+| `curator_enrich`                | LLM-powered metadata enrichment     |
+| `curator_contradictions`        | Find conflicting entries            |
+| `curator_resolve_contradiction` | Resolve conflicts                   |
+| `governance_proposals`          | Check/manage approval queue         |
+| `memory_promote_to_global`      | Share across projects               |
+| `admin_health`                  | Verify system health                |
+| `admin_vault_analytics`         | Overall knowledge quality metrics   |

package/dist/skills/skills/vault-curate.md

@@ -0,0 +1,107 @@
+---
+name: vault-curate
+description: >
+  Use when the user says "clean vault", "deduplicate", "groom knowledge",
+  "consolidate vault", "vault maintenance", "find duplicates", "merge patterns",
+  "check contradictions", "vault health", or wants to maintain, clean, reorganize,
+  or improve the quality of the agent's knowledge base.
+---
+
+# Vault Curate — Knowledge Maintenance
+
+Maintain vault quality through deduplication, grooming, contradiction detection, and consolidation. A well-curated vault produces better search results and brain recommendations.
+
+## When to Use
+
+Periodically (weekly or after heavy capture sessions), when search quality degrades, when vault health shows warnings, or when the user explicitly requests maintenance.
+
+## Orchestration Sequence
+
+### Step 1: Health Assessment
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+```
+YOUR_AGENT_core op:get_vault_analytics
+```
+
+Present the health summary to the user before proceeding: total entries, quality scores, staleness, coverage gaps.
+
+### Step 2: Detect Duplicates
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+This finds entries with overlapping titles, descriptions, or content. Review the duplicate pairs — some may be intentional (different contexts) while others are true duplicates.
+
+For true duplicates:
+
+```
+YOUR_AGENT_core op:merge_patterns
+  params: { patternIds: ["<id1>", "<id2>"] }
+```
+
+Preserve the best content from each.
+
+### Step 3: Find Contradictions
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+Contradictions erode trust in vault search results. For each contradiction: decide which entry is correct (check dates, context, evidence), then archive or update the incorrect one.
+
+### Step 4: Groom Entries
+
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+Runs tag enrichment and metadata cleanup across all entries. This improves searchability and categorization.
+
+For targeted grooming of specific entries:
+
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryIds: ["<id>"], tags: ["<tag>"] }
+```
+
+### Step 5: GPT Enrichment (Optional)
+
+```
+YOUR_AGENT_core op:curator_gpt_enrich
+```
+
+Adds AI-generated metadata to entries that lack descriptions, examples, or context. Fills in gaps without changing the core content.
+
+### Step 6: Full Consolidation
+
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+Runs the complete pipeline: dedup + archive stale entries + resolve contradictions. This is the heavy-duty cleanup.
+
+### Step 7: Knowledge Reorganization
+
+```
+YOUR_AGENT_core op:knowledge_reorganize
+  params: { mode: "preview" }
+```
+
+Preview first, then run again with `mode: "apply"` if the preview looks good.
+
+### Step 8: Verify Results
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+Compare with Step 1 metrics. Vault health should improve: fewer duplicates, no contradictions, better coverage.
+
+## Exit Criteria
+
+Curation is complete when: duplicates merged, contradictions resolved, entries groomed, and health metrics improved compared to Step 1 baseline.

package/dist/skills/skills/vault-navigator.md

@@ -0,0 +1,140 @@
+---
+name: vault-navigator
+description: Use when the user asks "what does vault say", "search knowledge", "find pattern", "have we seen this before", "best practice for", "check vault", "vault search", "any patterns for", or wants to query the knowledge base for existing solutions or guidance.
+---
+
+# Vault Navigator — Knowledge Oracle
+
+Navigate the vault intelligently. The vault has multiple search strategies — this skill picks the right one based on what the user needs.
+
+## When to Use
+
+Any time the user wants to find existing knowledge before building something new. Also when asking about best practices, previous solutions, or patterns.
+
+## Search Strategy Decision Tree
+
+### For "Have we seen this before?" / "Best practice for X"
+
+Start with `YOUR_AGENT_core op:search_intelligent` — this is semantic search, the broadest and smartest query. Pass the user's question as the query.
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<user's question>" }
+```
+
+If results are weak (low scores or few matches), fall back to `YOUR_AGENT_core op:search` with explicit filters (type, category, tags, severity). This is structured search — narrower but more precise.
+
+### For "Show me everything about X" (Exploration)
+
+Use tag-based and domain-based browsing for broader exploration:
+
+```
+YOUR_AGENT_core op:vault_tags
+```
+
+Lists all tags in the vault — helps discover what topics are covered.
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+
+Lists all domains — shows the knowledge landscape at a glance.
+
+```
+YOUR_AGENT_core op:vault_recent
+```
+
+Shows recently added or modified entries — what's fresh in the vault.
+
+### For "What's stale?" / "What needs updating?"
+
+Run an age report to find outdated knowledge:
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+Present entries that haven't been updated recently — these are candidates for review, refresh, or removal.
+
+### For "What do other projects do?"
+
+Call `YOUR_AGENT_core op:memory_cross_project_search` with `crossProject: true`. This searches across all linked projects, not just the current one.
+
+```
+YOUR_AGENT_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+```
+
+Check what projects are linked:
+
+```
+YOUR_AGENT_core op:project_linked_projects
+```
+
+### For "Has brain learned anything about X?"
+
+Call `YOUR_AGENT_core op:brain_strengths` to see which patterns have proven strength. Then call `YOUR_AGENT_core op:brain_global_patterns` with a domain or tag filter to find cross-project patterns.
+
+```
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_global_patterns
+  params: { domain: "<domain>" }
+```
+
+### For "What do I know about X?" (broad exploration)
+
+Chain multiple strategies for comprehensive results:
+
+1. `search_intelligent` → semantic vault search
+2. `vault_tags` / `vault_domains` → browse knowledge landscape
+3. `memory_cross_project_search` → cross-project patterns
+4. `brain_strengths` → proven patterns
+
+Present all findings with source labels so the user knows where each insight came from.
+
+## Presenting Results
+
+Always include:
+
+- **Source**: Which search found it (vault, memory, brain, tags, domains)
+- **Confidence**: Score or strength rating
+- **Relevance**: Why this result matches the query
+- **Actionable next step**: How to apply this knowledge
+
+## Fallback: Web Search
+
+If all vault strategies return no results, search the web for the user's question before saying "nothing found." The web may have:
+
+- Documentation, articles, or guides on the topic
+- Community patterns and best practices
+- Library-specific solutions
+
+If web search finds something useful, offer to capture it to the vault:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<what was found>",
+    description: "<summary from web search, source URL>"
+  }
+```
+
+## Exit Criteria
+
+Search is complete when at least one search strategy has been tried and results presented. If no results found across all strategies (vault + web), say so explicitly — that's valuable information too (it means this is genuinely new territory worth exploring and capturing).
+
+## Agent Tools Reference
+
+| Op                            | When to Use                                           |
+| ----------------------------- | ----------------------------------------------------- |
+| `search_intelligent`          | Default semantic search — broadest and smartest       |
+| `search`                      | Structured search with filters (type, tags, category) |
+| `vault_tags`                  | Browse all tags — discover knowledge landscape        |
+| `vault_domains`               | Browse all domains — see what areas are covered       |
+| `vault_recent`                | Recently modified entries — what's fresh              |
+| `vault_age_report`            | Find stale entries needing refresh                    |
+| `memory_cross_project_search` | Search across linked projects                         |
+| `project_linked_projects`     | See what projects are connected                       |
+| `brain_strengths`             | Proven patterns ranked by success                     |
+| `brain_global_patterns`       | Cross-project patterns from global pool               |
+| `capture_quick`               | Capture web findings to vault for next time           |

package/dist/skills/skills/verification-before-completion.md

@@ -0,0 +1,182 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+<!-- Adapted from superpowers (MIT License) -->
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. AGENT CHECK: Run system diagnostics
+6. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Agent System Checks
+
+After passing all verification commands, run system diagnostics:
+
+### Health Check
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Catches issues tests might miss — vault corruption, stale caches, configuration drift.
+
+### Full Diagnostic
+
+```
+YOUR_AGENT_core op:admin_diagnostic
+```
+
+Comprehensive system check — module status, database integrity, cache health, configuration validity.
+
+### Vault Analytics
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+Verify knowledge quality metrics — are capture rates healthy? Any degradation?
+
+If any check reports problems, address them before claiming completion.
+
+## Common Failures
+
+| Claim                 | Requires                        | Not Sufficient                 |
+| --------------------- | ------------------------------- | ------------------------------ |
+| Tests pass            | Test command output: 0 failures | Previous run, "should pass"    |
+| Linter clean          | Linter output: 0 errors         | Partial check, extrapolation   |
+| Build succeeds        | Build command: exit 0           | Linter passing, logs look good |
+| Bug fixed             | Test original symptom: passes   | Code changed, assumed fixed    |
+| Regression test works | Red-green cycle verified        | Test passes once               |
+| Agent completed       | VCS diff shows changes          | Agent reports "success"        |
+| Requirements met      | Line-by-line checklist          | Tests passing                  |
+| Agent healthy         | `admin_diagnostic` clean        | "No errors in logs"            |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- ANY wording implying success without having run verification
+
+## Rationalization Prevention
+
+| Excuse                                  | Reality                |
+| --------------------------------------- | ---------------------- |
+| "Should work now"                       | RUN the verification   |
+| "I'm confident"                         | Confidence ≠ evidence  |
+| "Just this once"                        | No exceptions          |
+| "Linter passed"                         | Linter ≠ compiler      |
+| "Agent said success"                    | Verify independently   |
+| "I'm tired"                             | Exhaustion ≠ excuse    |
+| "Partial check is enough"               | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter     |
+
+## Key Patterns
+
+**Tests:**
+
+```
+[Run test command] [See: 34/34 pass] "All tests pass"
+NOT: "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+
+```
+Write -> Run (pass) -> Revert fix -> Run (MUST FAIL) -> Restore -> Run (pass)
+NOT: "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+
+```
+[Run build] [See: exit 0] "Build passes"
+NOT: "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+
+```
+Re-read plan -> Create checklist -> Verify each -> Report gaps or completion
+NOT: "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+
+```
+Agent reports success -> Check VCS diff -> Verify changes -> Report actual state
+NOT: Trust agent report
+```
+
+## After Verification — Capture Session
+
+Once work is verified complete, capture a session summary so context persists:
+
+```
+YOUR_AGENT_core op:session_capture
+  params: {
+    summary: "<what was accomplished, files modified, key decisions>"
+  }
+```
+
+This ensures the next session has context about what was verified and completed.
+
+## When To Apply
+
+**ALWAYS before:**
+
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+## The Bottom Line
+
+Run the command. Read the output. THEN claim the result. This is non-negotiable.
+
+## Agent Tools Reference
+
+| Op                      | When to Use                         |
+| ----------------------- | ----------------------------------- |
+| `admin_health`          | Quick system health check           |
+| `admin_diagnostic`      | Comprehensive system diagnostic     |
+| `admin_vault_analytics` | Knowledge quality metrics           |
+| `session_capture`       | Persist verified completion context |