@soleri/forge 9.0.1 → 9.2.0

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)

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,15 +15,15 @@ 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.
@@ -39,7 +43,7 @@ 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>",

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

package/dist/skills/parallel-execute/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: parallel-execute
+description: >
+  Use when executing a plan where independent tasks can run concurrently. Triggers on "run in
+  parallel", "parallelize", "fan out", "concurrent execution", "run simultaneously", "at the
+  same time", "dispatch subagents", "batch execute", or when a plan has 3+ tasks with no
+  dependency overlap. For sequential task-by-task execution, use executing-plans instead.
+---
+
+# Parallel Execute — Subagent-Driven Plan Execution
+
+Execute plan tasks in parallel by dispatching independent tasks to separate subagents. The controller agent (you) never implements — you dispatch, review, and integrate.
+
+**Announce at start:** "I'm using the parallel-execute skill to run independent tasks concurrently."
+
+<HARD-GATE>
+You MUST have an approved, split plan before using this skill. If no plan exists or it has no tasks, stop and use the writing-plans skill first.
+</HARD-GATE>
+
+## When to Use
+
+- Plan has 3+ tasks
+- At least 2 tasks have no dependency overlap (can run simultaneously)
+- Tasks touch different files/modules (low merge conflict risk)
+
+**Do NOT use when:**
+- All tasks are sequential (each depends on the previous)
+- Tasks modify the same files (high conflict risk)
+- Plan has fewer than 3 tasks (use executing-plans instead)
+
+## The Process
+
+### Step 1: Load Plan and Build Dependency Graph
+
+```
+YOUR_AGENT_core op:get_plan
+YOUR_AGENT_core op:plan_list_tasks params:{ planId: "<id>" }
+```
+
+Map out which tasks are independent by checking `dependsOn` for each task. Group tasks into **waves** — sets of tasks that can run in parallel:
+
+- **Wave 1**: All tasks with no dependencies (or whose dependencies are already complete)
+- **Wave 2**: Tasks whose dependencies are all in Wave 1
+- **Wave N**: Tasks whose dependencies are all in prior waves
+
+Present the wave plan to the user before starting:
+
+```
+## Execution Waves
+
+| Wave | Tasks | Parallel? |
+|------|-------|-----------|
+| 1 | task-1, task-3, task-5 | Yes (3 subagents) |
+| 2 | task-2 (depends on task-1) | Solo |
+| 3 | task-4 (depends on task-2, task-3) | Solo |
+```
+
+### Step 2: Dispatch a Wave
+
+For each task in the current wave:
+
+1. Check readiness:
+   ```
+   YOUR_AGENT_core op:plan_dispatch params:{ planId: "<id>", taskId: "<taskId>" }
+   ```
+   Only dispatch tasks where `ready: true`.
+
+2. Mark as in_progress:
+   ```
+   YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "in_progress" }
+   ```
+
+3. Gather vault context for the task:
+   ```
+   YOUR_AGENT_core op:search params:{ query: "<task topic>", mode: "scan" }
+   ```
+
+4. **Launch all ready tasks as parallel Agent calls in a single message.** Each subagent gets:
+
+```
+You are implementing a single task from a plan. Work autonomously.
+
+## Task
+- **ID**: {taskId}
+- **Title**: {title}
+- **Description**: {description}
+- **Acceptance Criteria**: {criteria}
+
+## Context
+- **Plan Objective**: {planObjective}
+- **Vault Patterns to Follow**: {relevantPatterns}
+- **Files Likely Involved**: {fileHints}
+
+## Rules
+- Implement ONLY this task — do not touch files outside your scope
+- Run tests after implementation
+- If blocked, report the blocker and stop — do not guess
+- Do not commit — the controller handles commits
+- When done, report: files changed, tests passing, any concerns
+
+## Self-Review Checklist
+Before reporting completion, verify:
+- [ ] All acceptance criteria met
+- [ ] Tests pass
+- [ ] No files modified outside task scope
+- [ ] No console.log or debug code left behind
+- [ ] No raw colors or hardcoded values (use semantic tokens)
+```
+
+Use the Agent tool with `isolation: "worktree"` when tasks touch nearby files to prevent conflicts.
+
+### Step 3: Collect Results
+
+As subagents complete, collect their results. For each completed task:
+
+1. **Run spec review** — spawn a reviewer subagent:
+   ```
+   YOUR_AGENT_core op:plan_review_spec params:{ planId: "<id>", taskId: "<taskId>" }
+   ```
+   Use the returned prompt to launch a spec-review Agent that reads the ACTUAL code changes (not the implementer's self-report).
+
+2. **Record spec review outcome:**
+   ```
+   YOUR_AGENT_core op:plan_review_outcome params:{
+     planId: "<id>", taskId: "<taskId>",
+     reviewType: "spec", reviewer: "spec-reviewer",
+     outcome: "approved|rejected|needs_changes",
+     comments: "<specific file:line references>"
+   }
+   ```
+
+3. **If spec passes, run quality review:**
+   ```
+   YOUR_AGENT_core op:plan_review_quality params:{ planId: "<id>", taskId: "<taskId>" }
+   ```
+   Launch a quality-review Agent with the returned prompt.
+
+4. **Record quality review outcome:**
+   ```
+   YOUR_AGENT_core op:plan_review_outcome params:{
+     planId: "<id>", taskId: "<taskId>",
+     reviewType: "quality", reviewer: "quality-reviewer",
+     outcome: "approved|rejected|needs_changes",
+     comments: "<severity-tagged feedback>"
+   }
+   ```
+
+5. **Handle outcomes:**
+
+| Spec | Quality | Action |
+|------|---------|--------|
+| Pass | Pass | Mark task completed |
+| Fail | — | Dispatch fix subagent with failure feedback (max 2 retries) |
+| Pass | Critical issues | Dispatch targeted fix subagent (max 2 retries) |
+| Pass | Minor issues only | Mark completed, note issues for later |
+
+6. **Mark completed:**
+   ```
+   YOUR_AGENT_core op:update_task params:{ planId: "<id>", taskIndex: <n>, status: "completed" }
+   ```
+
+### Step 4: Advance to Next Wave
+
+After all tasks in a wave are complete (or failed after retries):
+
+1. Report wave results to the user:
+   ```
+   ## Wave N Complete
+
+   | Task | Status | Review | Notes |
+   |------|--------|--------|-------|
+   | task-1 | Completed | Spec: Pass, Quality: Pass | — |
+   | task-3 | Completed | Spec: Pass, Quality: Minor issues | Noted for cleanup |
+   | task-5 | Failed | Spec: Fail (2 retries exhausted) | Escalated |
+   ```
+
+2. **Wait for user acknowledgment** before proceeding to the next wave.
+
+3. Check which tasks in the next wave are now ready (dependencies met).
+
+4. Repeat from Step 2.
+
+### Step 5: Final Integration Review
+
+After all waves complete:
+
+1. Spawn a final review subagent that checks cross-cutting concerns:
+   - Consistency across all task implementations
+   - Integration points between tasks
+   - No conflicting patterns or duplicate code
+   - Tests pass together (not just individually)
+
+2. Report to user with full execution summary.
+
+### Step 6: Complete Plan Lifecycle
+
+Same as executing-plans — reconcile, capture knowledge, archive:
+
+```
+YOUR_AGENT_core op:plan_reconcile params:{
+  planId: "<id>",
+  actualOutcome: "<what happened>",
+  driftItems: [{ type: "...", description: "...", impact: "...", rationale: "..." }]
+}
+
+YOUR_AGENT_core op:plan_complete_lifecycle params:{
+  planId: "<id>",
+  patterns: ["<patterns discovered>"],
+  antiPatterns: ["<anti-patterns discovered>"]
+}
+
+YOUR_AGENT_core op:session_capture params:{
+  summary: "<execution summary with parallel metrics>"
+}
+```
+
+## Subagent Isolation Rules
+
+| Situation | Isolation |
+|-----------|-----------|
+| Tasks touch completely different directories | No isolation needed |
+| Tasks touch files in the same package | Use `isolation: "worktree"` |
+| Tasks modify the same file | **Do NOT parallelize** — run sequentially |
+
+When using worktree isolation, the controller must merge worktree changes back after review passes.
+
+## Failure Handling
+
+| Failure | Response |
+|---------|----------|
+| Subagent reports blocker | Pause that task, continue others in the wave |
+| Spec review fails | Dispatch fix subagent with feedback (retry 1/2) |
+| Second retry fails | Mark task as `failed`, escalate to user |
+| Merge conflict from worktree | Resolve manually, then re-run quality review |
+| All tasks in wave fail | Stop execution, report to user |
+
+## Capture Learnings
+
+During execution, capture insights about parallelization:
+
+```
+YOUR_AGENT_core op:capture_quick params:{
+  title: "<what you learned about parallel execution>",
+  description: "<context: which tasks parallelized well, which conflicted>"
+}
+```
+
+## When to Fall Back to Sequential
+
+**Switch to executing-plans skill mid-execution when:**
+- Subagents keep conflicting on shared files
+- Merge resolution is taking longer than the parallelization saves
+- User requests sequential execution
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `get_plan` | Load tracked plan |
+| `plan_list_tasks` | List all tasks with dependencies |
+| `plan_dispatch` | Check task readiness (dependencies met?) |
+| `update_task` | Mark tasks in_progress / completed / failed |
+| `plan_review_spec` | Generate spec compliance review prompt |
+| `plan_review_quality` | Generate code quality review prompt |
+| `plan_review_outcome` | Record review pass/fail result |
+| `plan_reconcile` | Post-execution drift analysis |
+| `plan_complete_lifecycle` | Extract knowledge, archive |
+| `session_capture` | Save session context |
+| `capture_quick` | Capture mid-execution learnings |
+| `search` | Vault lookup for task context |
+
+## Integration
+
+**Required skills:**
+- writing-plans — Creates the plan this skill executes
+- verification-before-completion — Verify work before claiming completion
+- executing-plans — Fallback for sequential execution

package/dist/skills/retrospective/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: retrospective
-description: Use when reflecting on recent work — sprint retros, weekly summaries, learning reports, or extracting actionable insights from accumulated session data.
+description: >
+  Use for time-bound reflection on recent WORK — "sprint retro", "weekly summary", "what went
+  well this week", "end of sprint", "monthly report". Reviews sessions and extracts actionable
+  improvements. For brain pattern intelligence and strength scores, use brain-debrief instead.
 ---
 
 # Retrospective — Learning Report From Real Data
@@ -12,24 +15,24 @@ Generate a data-driven retrospective from session data, vault captures, plan out
 ### 1. Gather Data
 
 ```
-ernesto_core op:brain_stats
-ernesto_core op:brain_stats params: { since: "<start of period>" }
-ernesto_core op:brain_strengths
-ernesto_core op:vault_recent
-ernesto_core op:memory_topics
-ernesto_core op:memory_stats
-ernesto_core op:plan_stats
-ernesto_core op:admin_search_insights
-ernesto_core op:admin_vault_analytics
+YOUR_AGENT_core op:brain_stats
+YOUR_AGENT_core op:brain_stats params: { since: "<start of period>" }
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:vault_recent
+YOUR_AGENT_core op:memory_topics
+YOUR_AGENT_core op:memory_stats
+YOUR_AGENT_core op:plan_stats
+YOUR_AGENT_core op:admin_search_insights
+YOUR_AGENT_core op:admin_vault_analytics
 ```
 
 ### 2. Analyze Patterns
 
 ```
-ernesto_core op:vault_age_report
-ernesto_core op:curator_detect_duplicates
-ernesto_core op:curator_contradictions
-ernesto_core op:curator_health_audit
+YOUR_AGENT_core op:vault_age_report
+YOUR_AGENT_core op:curator_detect_duplicates
+YOUR_AGENT_core op:curator_contradictions
+YOUR_AGENT_core op:curator_health_audit
 ```
 
 ### 3. Present the Retrospective
@@ -62,7 +65,7 @@ Quality: X/100 | Duplicates: N | Contradictions: N | Stale: N
 ### 4. Capture the Retrospective
 
 ```
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "Retrospective — [period]",
     description: "<key findings and action items>",

package/dist/skills/second-opinion/SKILL.md

@@ -12,7 +12,7 @@ Get an informed recommendation that synthesizes vault knowledge, brain patterns,
 ### 1. Understand the Decision
 
 ```
-ernesto_core op:route_intent
+YOUR_AGENT_core op:route_intent
   params: { prompt: "<user's question>" }
 ```
 
@@ -20,20 +20,20 @@ ernesto_core op:route_intent
 
 **Vault** — previous decisions, patterns, anti-patterns:
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<the decision or options>" }
 ```
 
 **Brain** — proven approaches:
 ```
-ernesto_core op:brain_strengths
-ernesto_core op:brain_recommend
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_recommend
   params: { projectName: "<current project>" }
 ```
 
 **Cross-project** — what other projects chose:
 ```
-ernesto_core op:memory_cross_project_search
+YOUR_AGENT_core op:memory_cross_project_search
   params: { query: "<topic>", crossProject: true }
 ```
 
@@ -69,7 +69,7 @@ ernesto_core op:memory_cross_project_search
 ### 4. Capture the Decision
 
 ```
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<decision title>",
     description: "<chosen option, rationale, rejected alternatives>",

package/dist/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior — before proposing fixes.
+description: >
+  Use as the FIRST response when something is broken — "bug", "failing test", "not working",
+  "debug this", "error", "crash", "unexpected behavior", "weird issue". Diagnoses root cause
+  before proposing fixes. After root cause is found, hand off to fix-and-learn for repair and
+  knowledge capture.
 ---
 
 # Systematic Debugging
@@ -12,10 +16,10 @@ description: Use when encountering any bug, test failure, or unexpected behavior
 **BEFORE touching any code:**
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<bug or error message>" }
-ernesto_core op:brain_strengths
-ernesto_core op:memory_search
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:memory_search
   params: { query: "<error or symptom>" }
 ```
 
@@ -26,7 +30,7 @@ Only if vault and web produce no answer, proceed to Phase 1.
 ## Start a Debug Loop
 
 ```
-ernesto_core op:loop_start
+YOUR_AGENT_core op:loop_start
   params: { prompt: "Debug: <bug>", mode: "custom" }
 ```
 
@@ -60,8 +64,8 @@ Form single hypothesis, test minimally (one variable at a time), verify before c
 ## Phase 5: Capture the Learning
 
 ```
-ernesto_core op:loop_complete
-ernesto_core op:capture_knowledge
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_knowledge
   params: {
     title: "<bug>",
     description: "<root cause, solution, what made it hard to find>",
@@ -69,7 +73,7 @@ ernesto_core op:capture_knowledge
     category: "<domain>",
     tags: ["<relevant>"]
   }
-ernesto_core op:session_capture
+YOUR_AGENT_core op:session_capture
 ```
 
 ## Red Flags — STOP and Return to Phase 1

package/dist/skills/test-driven-development/SKILL.md

@@ -10,9 +10,9 @@ description: Use when implementing any feature or bugfix — write failing tests
 ## Before You Start — Search First
 
 ```
-ernesto_core op:search_intelligent
+YOUR_AGENT_core op:search_intelligent
   params: { query: "<what you're about to test>" }
-ernesto_core op:brain_strengths
+YOUR_AGENT_core op:brain_strengths
 ```
 
 If vault has testing guidance for this domain, follow it.
@@ -20,7 +20,7 @@ If vault has testing guidance for this domain, follow it.
 ## Start a TDD Loop
 
 ```
-ernesto_core op:loop_start
+YOUR_AGENT_core op:loop_start
   params: { prompt: "TDD: <feature>", mode: "custom" }
 ```
 
@@ -63,8 +63,8 @@ Next failing test for next behavior.
 ## After TDD
 
 ```
-ernesto_core op:loop_complete
-ernesto_core op:capture_quick
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_quick
   params: { title: "<testing pattern>", description: "<what you learned>" }
 ```