@soleri/forge 9.0.1 → 9.3.0

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

@@ -1,6 +1,10 @@
 ---
 name: executing-plans
-description: Use when there is a written implementation plan to execute with review checkpoints between task batches.
+description: >
+  Use when the user says "execute my plan", "run the plan", "start executing", "implement the
+  plan step by step", or has a written plan to execute sequentially with review checkpoints.
+  Tasks run one at a time in order. If tasks are independent and can run in parallel, use
+  parallel-execute instead.
 ---
 
 # Executing Plans
@@ -14,10 +18,10 @@ Load plan, review critically, execute tasks in batches, report for review betwee
 ### Step 1: Load and Review Plan
 
 ```
-ernesto_core op:get_plan
-ernesto_core op:plan_list_tasks
+YOUR_AGENT_core op:get_plan
+YOUR_AGENT_core op:plan_list_tasks
   params: { planId: "<id>" }
-ernesto_core op:plan_stats
+YOUR_AGENT_core op:plan_stats
 ```
 
 If no tracked plan exists, read from `docs/plans/`. Review critically — raise concerns before starting.
@@ -25,13 +29,14 @@ If no tracked plan exists, read from `docs/plans/`. Review critically — raise
 ### Step 2: Start Execution Loop
 
 ```
-ernesto_core op:loop_start
+YOUR_AGENT_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
@@ -49,10 +54,10 @@ 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
+2. `YOUR_AGENT_core op:loop_complete`
+3. `YOUR_AGENT_core op:plan_reconcile` — compare planned vs actual
+4. `YOUR_AGENT_core op:plan_complete_lifecycle` — extract knowledge, archive
+5. `YOUR_AGENT_core op:session_capture` — save session context
 
 Capture mid-execution learnings with `op:capture_quick` as they happen — don't wait until the end.
 
@@ -74,14 +79,14 @@ Capture mid-execution learnings with `op:capture_quick` as they happen — don't
 
 ## 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 |
+| 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/dist/skills/fix-and-learn/SKILL.md

@@ -1,6 +1,10 @@
 ---
 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.
+description: >
+  Use AFTER a root cause has been identified (typically via systematic-debugging) to execute
+  the fix and capture the learning in the vault. Triggers on "fix it", "apply the fix",
+  "patch this and remember". Do NOT use as the first response to a bug — use
+  systematic-debugging first to find root cause.
 ---
 
 # Fix & Learn — Debug, Repair, Capture
@@ -21,16 +25,16 @@ Fix bugs through a structured recovery workflow, then capture the root cause as
 ### Step 1: Classify and Route
 
 ```
-ernesto_core op:route_intent
+YOUR_AGENT_core op:route_intent
   params: { prompt: "<bug description>" }
 ```
 
 ### Step 2: Check Vault First
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<error message or bug description>" }
-ernesto_core op:memory_search
+YOUR_AGENT_core op:memory_search
   params: { query: "<bug description>" }
 ```
 
@@ -43,7 +47,7 @@ If vault has no answer, search for known issues, Stack Overflow answers, GitHub
 ### Step 4: Start Fix Loop
 
 ```
-ernesto_core op:loop_start
+YOUR_AGENT_core op:loop_start
   params: { prompt: "Fix: <bug description>", mode: "custom" }
 ```
 
@@ -59,12 +63,12 @@ If Steps 2-3 didn't produce a solution, use systematic-debugging skill:
 
 ### Step 6: Validate
 
-Run test suite. Use verification-before-completion skill. Complete loop: `ernesto_core op:loop_complete`.
+Run test suite. Use verification-before-completion skill. Complete loop: `YOUR_AGENT_core op:loop_complete`.
 
 ### Step 7: Capture the Learning
 
 ```
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<bug title>",
     description: "<root cause, solution, what made it hard to find>",
@@ -74,7 +78,7 @@ ernesto_core op:capture_knowledge
   }
 ```
 
-Run `ernesto_core op:curator_detect_duplicates` to avoid redundant entries.
+Run `YOUR_AGENT_core op:curator_detect_duplicates` to avoid redundant entries.
 
 ## Exit Criteria
 
@@ -88,11 +92,11 @@ Bug resolved, tests pass, root cause captured in vault. A fix without a capture
 
 ## 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 |
+| 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/dist/skills/health-check/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: health-check
-description: Use when running maintenance on the knowledge base — deduplication, contradiction resolution, stale entry cleanup, or vault quality auditing.
+description: >
+  Use when the user asks "check health", "system status", "how healthy is the vault",
+  "knowledge quality", "run diagnostics", "vault health report", or wants a read-only health
+  assessment of the knowledge base — scoring, reporting, finding issues. Does NOT modify vault
+  entries. To actively clean, merge, or deduplicate, use vault-curate instead.
 ---
 
 # Health Check — Knowledge Base Maintenance
@@ -12,43 +16,43 @@ Comprehensive maintenance cycle on the knowledge base. Finds stale entries, dupl
 ### 1. System Health
 
 ```
-ernesto_core op:admin_health
-ernesto_core op:admin_diagnostic
+YOUR_AGENT_core op:admin_health
+YOUR_AGENT_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
+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
 ```
 
 ### 3. Quality Audit
 
 ```
-ernesto_core op:curator_health_audit
+YOUR_AGENT_core op:curator_health_audit
 ```
 
 ### 4. Find Duplicates
 
 ```
-ernesto_core op:curator_detect_duplicates
+YOUR_AGENT_core op:curator_detect_duplicates
 ```
 
 ### 5. Find Contradictions
 
 ```
-ernesto_core op:curator_contradictions
-ernesto_core op:curator_resolve_contradiction
+YOUR_AGENT_core op:curator_contradictions
+YOUR_AGENT_core op:curator_resolve_contradiction
   params: { contradictionId: "<id>" }
 ```
 
 ### 6. Find Stale Entries
 
 ```
-ernesto_core op:vault_age_report
+YOUR_AGENT_core op:vault_age_report
 ```
 
 Entries >30 days without updates: refresh, archive, or delete.
@@ -56,21 +60,21 @@ Entries >30 days without updates: refresh, archive, or delete.
 ### 7. Check Search Quality
 
 ```
-ernesto_core op:admin_search_insights
+YOUR_AGENT_core op:admin_search_insights
 ```
 
 ### 8. Memory Health
 
 ```
-ernesto_core op:memory_stats
-ernesto_core op:memory_deduplicate
+YOUR_AGENT_core op:memory_stats
+YOUR_AGENT_core op:memory_deduplicate
 ```
 
 ### 9. Governance Queue
 
 ```
-ernesto_core op:governance_proposals params: { action: "list" }
-ernesto_core op:governance_expire
+YOUR_AGENT_core op:governance_proposals params: { action: "list" }
+YOUR_AGENT_core op:governance_expire
 ```
 
 ### 10. Fix Everything (Optional, with user approval)
@@ -118,14 +122,14 @@ ernesto_core op:governance_expire
 
 ## 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 |
+| 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

@@ -1,6 +1,10 @@
 ---
 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.
+description: >
+  Use to EXTRACT multiple patterns from a source — code, docs, PRs, articles. Triggers on
+  "learn from this", "harvest knowledge", "ingest this document", "extract patterns from".
+  The agent reads the source and identifies what to capture. For saving a single known item,
+  use vault-capture instead.
 ---
 
 # Knowledge Harvest — Extract Patterns From Anything
@@ -11,35 +15,35 @@ Point at code, docs, PRs, architecture decisions, or postmortems — the agent e
 
 ### 1. Understand the Source
 
-Read target content and classify: `ernesto_core op:route_intent params: { prompt: "Extract knowledge from: <source>" }`
+Read target content and classify: `YOUR_AGENT_core op:route_intent params: { prompt: "Extract knowledge from: <source>" }`
 
 ### 2. Check What's Already Known
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<topic of source material>" }
-ernesto_core op:vault_tags
-ernesto_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+YOUR_AGENT_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 |
+| 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
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<clear, searchable name>",
     description: "<what it is, when to apply, why it matters>",
@@ -81,13 +85,13 @@ Optionally promote universal patterns: `op:memory_promote_to_global`.
 
 ## 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 |
+| 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

@@ -1,6 +1,9 @@
 ---
 name: onboard-me
-description: Use when someone is new to the project and needs a structured introduction to its knowledge, patterns, decisions, and conventions.
+description: >
+  Use when someone is new to the PROJECT and needs orientation — "onboard me", "I'm new here",
+  "project overview", "what should I know about this codebase". Questions about the project's
+  patterns and conventions, not about the agent's capabilities (use agent-guide for that).
 ---
 
 # Onboard Me — Instant Project Intelligence
@@ -12,59 +15,59 @@ Structured tour of everything the vault knows about this project. Decisions, pat
 ### 1. Project Overview
 
 ```
-ernesto_core op:identity
-ernesto_core op:project_get
-ernesto_core op:project_list_rules
-ernesto_core op:get_behavior_rules
+YOUR_AGENT_core op:identity
+YOUR_AGENT_core op:project_get
+YOUR_AGENT_core op:project_list_rules
+YOUR_AGENT_core op:get_behavior_rules
 ```
 
 ### 2. Knowledge Landscape
 
 ```
-ernesto_core op:vault_domains
-ernesto_core op:vault_tags
-ernesto_core op:admin_vault_size
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+YOUR_AGENT_core op:admin_vault_size
 ```
 
 ### 3. Critical Knowledge
 
 ```
-ernesto_core op:search
+YOUR_AGENT_core op:search
   params: { severity: "critical" }
 ```
 
 ### 4. Key Decisions
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "architectural decision design choice" }
 ```
 
 ### 5. Strongest Patterns
 
 ```
-ernesto_core op:brain_strengths
+YOUR_AGENT_core op:brain_strengths
 ```
 
 ### 6. Anti-Patterns to Avoid
 
 ```
-ernesto_core op:search
+YOUR_AGENT_core op:search
   params: { type: "anti-pattern" }
 ```
 
 ### 7. Cross-Project Context
 
 ```
-ernesto_core op:project_linked_projects
-ernesto_core op:brain_global_patterns
+YOUR_AGENT_core op:project_linked_projects
+YOUR_AGENT_core op:brain_global_patterns
 ```
 
 ### 8. Knowledge Gaps
 
 ```
-ernesto_core op:admin_search_insights
-ernesto_core op:vault_age_report
+YOUR_AGENT_core op:admin_search_insights
+YOUR_AGENT_core op:vault_age_report
 ```
 
 ## Presenting the Onboarding
@@ -106,13 +109,13 @@ ernesto_core op:vault_age_report
 
 ## 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 |
+| 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                |