@soleri/forge 8.1.0 → 9.0.1

package/src/skills/code-patrol/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: code-patrol
+description: Use when reviewing code against the project's own captured patterns, anti-patterns, and conventions — not generic lint rules but institutional knowledge.
+---
+
+# Code Patrol — Review Code Against Your Own Knowledge
+
+Review code against vault patterns, anti-patterns, and project conventions. Catches violations that no linter knows about.
+
+## Steps
+
+### 1. Understand the Code's Domain
+
+```
+ernesto_core op:route_intent
+  params: { prompt: "Code review: <brief description>" }
+ernesto_core op:vault_domains
+```
+
+### 2. Load Relevant Patterns
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<what this code does>" }
+ernesto_core op:search
+  params: { type: "anti-pattern" }
+ernesto_core op:search
+  params: { severity: "critical" }
+ernesto_core op:project_list_rules
+ernesto_core op:brain_strengths
+```
+
+### 3. Review the Code
+
+| Check | Source | Severity |
+|-------|--------|----------|
+| Violates critical rule | `search (severity: critical)` | Must fix |
+| Matches known anti-pattern | `search (type: anti-pattern)` | Must fix |
+| Doesn't follow proven pattern | `brain_strengths` | Should fix |
+| Breaks project conventions | `project_list_rules` | Should fix |
+| Misses pattern opportunity | `search_intelligent` | Could improve |
+
+### 4. Present the Review
+
+```
+## Code Patrol Report
+
+### Must Fix (Critical)
+- **[Rule name]**: [What's wrong]
+  Vault ref: [entry title] | Fix: [How]
+
+### Should Fix (Warning)
+- **[Anti-pattern]**: [What's wrong]
+  Better approach: [The pattern to follow]
+
+### Could Improve (Suggestion)
+- **[Pattern opportunity]**: [Could benefit from...]
+
+### Summary
+X critical, Y warnings, Z suggestions
+```
+
+### 5. Learn From the Review
+
+If review reveals new patterns or gaps not in vault, capture with `capture_quick` or `capture_knowledge`.
+
+### 6. Verify After Fixes
+
+Re-run patrol after user applies fixes. Check `admin_health`.
+
+## Common Mistakes
+
+- Reviewing only against generic lint rules instead of vault knowledge
+- Not loading anti-patterns before reviewing
+- Skipping the capture step when a new pattern is discovered
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify code domain |
+| `search_intelligent` | Find relevant patterns |
+| `search` | Find anti-patterns and critical rules |
+| `project_list_rules` / `get_behavior_rules` | Project conventions |
+| `brain_strengths` | Proven patterns |
+| `capture_quick` / `capture_knowledge` | Capture new discoveries |

package/src/skills/context-resume/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: context-resume
+description: Use when starting a new session, returning to work after a break, or needing to reconstruct working context from memory, plans, and sessions.
+---
+
+# Context Resume — Pick Up Where You Left Off
+
+Reconstruct full working context in seconds. Chains memory, plans, sessions, and brain to rebuild exactly where you left off — even across session boundaries and context compactions.
+
+## Steps
+
+### 1. Load Active Plans
+
+```
+ernesto_core op:plan_stats
+ernesto_core op:get_plan
+ernesto_core op:plan_list_tasks
+  params: { planId: "<id>" }
+```
+
+Present: plan objective, task status (completed/in-progress/pending), what's next.
+
+### 2. Search Recent Memory
+
+```
+ernesto_core op:memory_search
+  params: { query: "session summary" }
+ernesto_core op:memory_list
+ernesto_core op:vault_recent
+```
+
+### 3. Check Active Loops
+
+```
+ernesto_core op:loop_is_active
+ernesto_core op:loop_status
+```
+
+### 4. Brain Snapshot
+
+```
+ernesto_core op:brain_strengths
+```
+
+### 5. System Health
+
+```
+ernesto_core op:admin_health
+```
+
+## Presenting the Resume
+
+```
+## Where You Left Off
+
+**Active Plans:**
+- [Plan name] — X/Y tasks complete, next: [task]
+
+**Last Session:**
+- [Summary — what was done, key decisions]
+
+**Recent Captures:**
+- [New patterns/anti-patterns added]
+
+**Active Loops:**
+- [Any in-progress validation loops]
+
+**Brain Says:**
+- [Top relevant patterns]
+
+**Health:** [OK / Issues]
+
+## Recommended Next Step
+[Based on active plans and last session context]
+```
+
+## Common Mistakes
+
+- Not checking for active loops (missing mid-flight TDD or debug cycles)
+- Skipping the health check (stale caches can cause confusing behavior)
+- Not loading recent vault captures (missing context from last session)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `plan_stats` / `get_plan` / `plan_list_tasks` | Active plans |
+| `memory_search` / `memory_list` | Session summaries |
+| `vault_recent` | Recently captured knowledge |
+| `loop_is_active` / `loop_status` | In-flight loops |
+| `brain_strengths` | Relevant proven patterns |
+| `admin_health` | System health check |

package/src/skills/executing-plans/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: executing-plans
+description: Use when there is a written implementation plan to execute with review checkpoints between task batches.
+---
+
+# Executing Plans
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+```
+ernesto_core op:get_plan
+ernesto_core op:plan_list_tasks
+  params: { planId: "<id>" }
+ernesto_core op:plan_stats
+```
+
+If no tracked plan exists, read from `docs/plans/`. Review critically — raise concerns before starting.
+
+### Step 2: Start Execution Loop
+
+```
+ernesto_core op:loop_start
+  params: { prompt: "<plan objective>", mode: "custom" }
+```
+
+### Step 3: Execute Batch (default: first 3 tasks)
+
+For each task:
+1. `op:update_task` — mark `in_progress`
+2. Follow each step exactly
+3. Run verifications as specified
+4. `op:update_task` — mark `completed`
+5. `op:loop_iterate` — track progress
+
+### Step 4: Report
+
+Show what was implemented, verification output, loop status. Say: "Ready for feedback."
+
+### Step 5: Continue
+
+Apply feedback, execute next batch, repeat until complete.
+
+### Step 6: Complete Development
+
+1. Run final verification (use verification-before-completion skill)
+2. `ernesto_core op:loop_complete`
+3. `ernesto_core op:plan_reconcile` — compare planned vs actual
+4. `ernesto_core op:plan_complete_lifecycle` — extract knowledge, archive
+5. `ernesto_core op:session_capture` — save session context
+
+Capture mid-execution learnings with `op:capture_quick` as they happen — don't wait until the end.
+
+## When to Stop
+
+- Hit a blocker (missing dependency, unclear instruction, repeated test failures)
+- Plan has critical gaps
+- Don't understand an instruction
+
+**Ask for clarification rather than guessing.**
+
+## Common Mistakes
+
+- Not reviewing the plan critically before starting
+- Skipping verifications to save time
+- Guessing through blockers instead of stopping to ask
+- Forgetting to reconcile the plan after execution (drift data improves future plans)
+- Starting implementation on main/master without explicit consent
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `get_plan` / `plan_list_tasks` / `plan_stats` | Load plan |
+| `update_task` | Mark task status |
+| `loop_start` / `loop_iterate` / `loop_complete` | Validation loop |
+| `plan_reconcile` | Post-execution drift report |
+| `plan_complete_lifecycle` | Extract knowledge, archive |
+| `session_capture` | Save session context |
+| `capture_quick` | Mid-execution learnings |
+
+**Related skills:** writing-plans, verification-before-completion, test-driven-development

package/src/skills/fix-and-learn/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: fix-and-learn
+description: Use when fixing bugs, broken behavior, errors, regressions, or unexpected results and wanting to capture the learning for future sessions.
+---
+
+# Fix & Learn — Debug, Repair, Capture
+
+Fix bugs through a structured recovery workflow, then capture the root cause as a reusable anti-pattern. The learning step makes fixes compound across sessions.
+
+## The Search Order — MANDATORY
+
+**Never jump to writing code.** Always follow this lookup order:
+
+1. **Vault first** — has this been solved before?
+2. **Web search** — is there a known solution?
+3. **Plan the fix** — design approach before touching code
+4. **Implement** — only after steps 1-3
+
+## Orchestration Sequence
+
+### Step 1: Classify and Route
+
+```
+ernesto_core op:route_intent
+  params: { prompt: "<bug description>" }
+```
+
+### Step 2: Check Vault First
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<error message or bug description>" }
+ernesto_core op:memory_search
+  params: { query: "<bug description>" }
+```
+
+If vault returns a high-confidence match — use it. Don't re-investigate solved problems.
+
+### Step 3: Search the Web
+
+If vault has no answer, search for known issues, Stack Overflow answers, GitHub issues, official docs.
+
+### Step 4: Start Fix Loop
+
+```
+ernesto_core op:loop_start
+  params: { prompt: "Fix: <bug description>", mode: "custom" }
+```
+
+### Step 5: Diagnose and Fix
+
+If Steps 2-3 didn't produce a solution, use systematic-debugging skill:
+
+1. Reproduce the issue
+2. Isolate root cause
+3. Plan the fix before writing code
+4. Implement the fix
+5. Verify — no regressions
+
+### Step 6: Validate
+
+Run test suite. Use verification-before-completion skill. Complete loop: `ernesto_core op:loop_complete`.
+
+### Step 7: Capture the Learning
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<bug title>",
+    description: "<root cause, solution, what made it hard to find>",
+    type: "anti-pattern",
+    category: "<domain>",
+    tags: ["<error-type>", "<component>"]
+  }
+```
+
+Run `ernesto_core op:curator_detect_duplicates` to avoid redundant entries.
+
+## Exit Criteria
+
+Bug resolved, tests pass, root cause captured in vault. A fix without a capture is incomplete.
+
+## Common Mistakes
+
+- Jumping to code before searching vault/web
+- Skipping the capture step after fixing
+- Not running the full test suite to check regressions
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify as FIX intent |
+| `search_intelligent` | Check vault for known bugs |
+| `memory_search` | Search session memories |
+| `loop_start` / `loop_iterate` / `loop_complete` | Iterative fix cycle |
+| `capture_knowledge` / `capture_quick` | Persist anti-pattern |
+| `curator_detect_duplicates` | Prevent redundant entries |

package/src/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/src/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/src/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 |