@soleri/forge 5.14.2 → 5.14.4

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

@@ -0,0 +1,185 @@
+---
+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/skills/onboard-me.md

@@ -0,0 +1,198 @@
+---
+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                   |

package/dist/skills/skills/retrospective.md

@@ -0,0 +1,205 @@
+---
+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        |