@soleri/forge 9.0.1 → 9.2.0

package/src/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,7 +29,7 @@ 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" }
 ```
 
@@ -49,10 +53,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.
 

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

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