@soleri/forge 8.1.0 → 9.0.1

package/src/skills/retrospective/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: retrospective
+description: Use when reflecting on recent work — sprint retros, weekly summaries, learning reports, or extracting actionable insights from accumulated session data.
+---
+
+# Retrospective — Learning Report From Real Data
+
+Generate a data-driven retrospective from session data, vault captures, plan outcomes, and brain intelligence.
+
+## Steps
+
+### 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
+```
+
+### 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
+```
+
+### 3. Present the Retrospective
+
+```
+## Retrospective: [Period]
+
+### By the Numbers
+| Metric | This Period | Previous | Trend |
+|--------|-----------|----------|-------|
+| Patterns captured | X | Y | up/down |
+| Plans completed | X | Y | up/down |
+| Brain strength (avg) | X | Y | up/down |
+| Search misses | X | Y | up/down |
+
+### What Went Well
+[High brain strength patterns, completed plans, growing domains]
+
+### What Didn't Go Well
+[Recurring anti-patterns, failed plans, knowledge gaps]
+
+### Vault Health
+Quality: X/100 | Duplicates: N | Contradictions: N | Stale: N
+
+### Recommendations
+1. [Data-driven action item]
+2. [Data-driven action item]
+```
+
+### 4. Capture the Retrospective
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "Retrospective — [period]",
+    description: "<key findings and action items>",
+    type: "workflow",
+    category: "meta",
+    tags: ["retrospective"]
+  }
+```
+
+### 5. Clean Up (Optional)
+
+If quality issues found: `op:curator_consolidate` then `op:brain_build_intelligence`.
+
+## Common Mistakes
+
+- Presenting AI opinions instead of actual vault/brain metrics
+- Not comparing periods (missing trends)
+- Skipping the capture step (retrospective insights are lost)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `brain_stats` / `brain_strengths` | Metrics and patterns |
+| `vault_recent` | Recent captures |
+| `memory_topics` / `memory_stats` | Knowledge clusters |
+| `plan_stats` | Plan completion |
+| `admin_search_insights` | Search misses |
+| `curator_health_audit` | Vault quality |
+| `capture_knowledge` | Persist retrospective |

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

@@ -0,0 +1,97 @@
+---
+name: second-opinion
+description: Use when facing a technical decision, comparing approaches, or needing an informed recommendation backed by vault knowledge, brain patterns, and web research.
+---
+
+# Second Opinion — Decision Support From All Sources
+
+Get an informed recommendation that synthesizes vault knowledge, brain patterns, cross-project experience, and web research before making any technical decision.
+
+## Steps
+
+### 1. Understand the Decision
+
+```
+ernesto_core op:route_intent
+  params: { prompt: "<user's question>" }
+```
+
+### 2. Search All Knowledge Sources
+
+**Vault** — previous decisions, patterns, anti-patterns:
+```
+ernesto_core op:search_intelligent
+  params: { query: "<the decision or options>" }
+```
+
+**Brain** — proven approaches:
+```
+ernesto_core op:brain_strengths
+ernesto_core op:brain_recommend
+  params: { projectName: "<current project>" }
+```
+
+**Cross-project** — what other projects chose:
+```
+ernesto_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+```
+
+**Web** — community consensus, benchmarks, comparison articles.
+
+### 3. Synthesize and Present
+
+```
+## Decision: [Question]
+
+### What the Vault Says
+[Existing decisions, patterns, anti-patterns]
+
+### What the Brain Recommends
+[Proven patterns, cross-project insights]
+
+### What the Web Says
+[Community consensus, benchmarks]
+
+### Options Analysis
+| Criteria | Option A | Option B |
+|----------|----------|----------|
+| [criteria] | ... | ... |
+| Vault support | [patterns?] | [patterns?] |
+
+### Recommendation
+[Clear recommendation with reasoning]
+
+### Risks
+[What could go wrong]
+```
+
+### 4. Capture the Decision
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<decision title>",
+    description: "<chosen option, rationale, rejected alternatives>",
+    type: "decision",
+    category: "<domain>",
+    tags: ["decision"]
+  }
+```
+
+## Common Mistakes
+
+- Giving a generic AI opinion instead of searching vault/brain first
+- Not capturing the final decision (next person faces the same question blind)
+- Skipping cross-project search (another project may have solved this)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify decision type |
+| `search_intelligent` | Find previous decisions |
+| `brain_strengths` / `brain_recommend` | Proven approaches |
+| `memory_cross_project_search` | Other projects' choices |
+| `memory_search` | Session context |
+| `capture_knowledge` | Persist the decision |

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

@@ -0,0 +1,99 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior — before proposing fixes.
+---
+
+# Systematic Debugging
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+## Phase 0: Search Before Investigating
+
+**BEFORE touching any code:**
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<bug or error message>" }
+ernesto_core op:brain_strengths
+ernesto_core op:memory_search
+  params: { query: "<error or symptom>" }
+```
+
+If vault has a match — apply it directly. Then search web: exact error message, GitHub issues, Stack Overflow, official docs.
+
+Only if vault and web produce no answer, proceed to Phase 1.
+
+## Start a Debug Loop
+
+```
+ernesto_core op:loop_start
+  params: { prompt: "Debug: <bug>", mode: "custom" }
+```
+
+## The Four Phases
+
+### Phase 1: Root Cause Investigation
+
+1. Read error messages carefully
+2. Reproduce consistently
+3. Check recent changes
+4. Gather evidence at component boundaries
+5. Trace data flow backward through call stack
+
+Track each step with `op:loop_iterate`.
+
+### Phase 2: Pattern Analysis
+
+Find working examples, compare against references (read completely), identify differences, understand dependencies. Use `op:search_intelligent` for comparison.
+
+### Phase 3: Hypothesis and Testing
+
+Form single hypothesis, test minimally (one variable at a time), verify before continuing. If unsure — ask for help.
+
+### Phase 4: Implementation
+
+1. Create failing test (use test-driven-development skill)
+2. Implement single fix (root cause only)
+3. Verify fix
+4. If < 3 attempts failed, return to Phase 1. If >= 3, STOP — question architecture with human partner.
+
+## Phase 5: Capture the Learning
+
+```
+ernesto_core op:loop_complete
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<bug>",
+    description: "<root cause, solution, what made it hard to find>",
+    type: "anti-pattern",
+    category: "<domain>",
+    tags: ["<relevant>"]
+  }
+ernesto_core op:session_capture
+```
+
+## Red Flags — STOP and Return to Phase 1
+
+- "Quick fix for now" / "Just try changing X"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" after 2+ failures
+- Each fix reveals a new problem elsewhere
+
+## Common Mistakes
+
+- Skipping vault search ("I know this one") — 30 seconds saves hours
+- Making multiple changes at once (can't isolate what worked)
+- Skipping the capture step (same bug will recur)
+
+## Quick Reference
+
+| Phase | Key Activities | Tools |
+|-------|---------------|-------|
+| 0. Search | Vault, web, memory | `search_intelligent`, `brain_strengths`, `memory_search` |
+| 1. Root Cause | Read errors, reproduce, trace | `loop_iterate` |
+| 2. Pattern | Find working examples, compare | `search_intelligent` |
+| 3. Hypothesis | Form theory, test minimally | `loop_iterate` |
+| 4. Implementation | Test, fix, verify | `loop_iterate` |
+| 5. Capture | Persist root cause | `capture_knowledge`, `loop_complete` |
+
+**Related skills:** test-driven-development, verification-before-completion, fix-and-learn

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

@@ -0,0 +1,91 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix — write failing tests before implementation code.
+---
+
+# Test-Driven Development (TDD)
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+## Before You Start — Search First
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<what you're about to test>" }
+ernesto_core op:brain_strengths
+```
+
+If vault has testing guidance for this domain, follow it.
+
+## Start a TDD Loop
+
+```
+ernesto_core op:loop_start
+  params: { prompt: "TDD: <feature>", mode: "custom" }
+```
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over. No exceptions.
+
+## Red-Green-Refactor
+
+### RED — Write Failing Test
+
+One behavior, clear name, real code (no mocks unless unavoidable). Run test, confirm it **fails** for the expected reason (feature missing, not typos). Track: `op:loop_iterate`.
+
+### GREEN — Minimal Code
+
+Simplest code to pass the test. Don't add features beyond the test. Run test, confirm it **passes** and other tests still pass. Track: `op:loop_iterate`.
+
+### REFACTOR — Clean Up
+
+After green only: remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior.
+
+### Repeat
+
+Next failing test for next behavior.
+
+## Verification Checklist
+
+- [ ] Every new function has a test
+- [ ] Watched each test fail before implementing
+- [ ] Failed for expected reason (not typo)
+- [ ] Wrote minimal code to pass
+- [ ] All tests pass, output pristine
+- [ ] Mocks only where unavoidable
+- [ ] Edge cases and errors covered
+
+## After TDD
+
+```
+ernesto_core op:loop_complete
+ernesto_core op:capture_quick
+  params: { title: "<testing pattern>", description: "<what you learned>" }
+```
+
+## Common Mistakes
+
+- Writing implementation before tests ("I'll test after")
+- Keeping pre-test code as "reference" (delete means delete)
+- Test passes immediately (testing existing behavior, not new)
+- Multiple behaviors in one test ("and" in name means split it)
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API first |
+| Must mock everything | Code too coupled — use DI |
+| Test setup huge | Extract helpers or simplify design |
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Find testing patterns |
+| `brain_strengths` | Proven testing approaches |
+| `loop_start` / `loop_iterate` / `loop_complete` | TDD cycle tracking |
+| `capture_quick` | Capture new testing patterns |

package/src/skills/vault-capture/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vault-capture
+description: Use when persisting a pattern, anti-pattern, workflow, decision, or principle to the knowledge base — after discovering something worth remembering.
+---
+
+# Vault Capture — Persist Knowledge
+
+Capture patterns, anti-patterns, workflows, and principles to the vault. Captured knowledge compounds — it informs future searches, brain recommendations, and team reviews.
+
+## Steps
+
+### 1. Check for Duplicates
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<knowledge title or description>" }
+ernesto_core op:curator_detect_duplicates
+```
+
+If similar entry exists, update it instead of creating a duplicate.
+
+### 2. Classify the Knowledge
+
+| Type | Description |
+|------|-------------|
+| **pattern** | Works and should be repeated |
+| **anti-pattern** | Fails and should be avoided |
+| **workflow** | Steps for a specific task |
+| **principle** | Guiding rule or heuristic |
+| **decision** | Architectural choice with rationale |
+
+### 3. Capture
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<clear, searchable name>",
+    description: "<what it is and when it applies>",
+    type: "<pattern|anti-pattern|workflow|principle|decision>",
+    category: "<domain>",
+    tags: ["<tag1>", "<tag2>"],
+    example: "<code or before/after>",
+    why: "<reasoning>"
+  }
+```
+
+For quick captures: `ernesto_core op:capture_quick params: { title: "<name>", description: "<details>" }`
+
+### 4. Post-Capture Quality
+
+- `op:curator_groom params: { entryId: "<id>" }` — normalize tags
+- `op:curator_enrich params: { entryId: "<id>" }` — LLM enrichment
+- `op:curator_contradictions` — check for conflicts
+
+### 5. Governance (if enabled)
+
+If capture returns a `proposalId`, entry is queued: `op:governance_proposals params: { action: "list" }`.
+
+### 6. Promote to Global (Optional)
+
+For cross-project knowledge: `op:memory_promote_to_global params: { entryId: "<id>" }`.
+
+### 7. Verify
+
+`op:admin_health` and `op:admin_vault_analytics` to confirm storage and quality.
+
+## Common Mistakes
+
+- Not checking for duplicates before capturing
+- Missing the `why` field (makes entries not actionable)
+- Skipping post-capture grooming (tags stay unnormalized)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Check for duplicates |
+| `capture_knowledge` / `capture_quick` | Persist to vault |
+| `curator_groom` / `curator_enrich` | Post-capture quality |
+| `curator_contradictions` | Find conflicts |
+| `memory_promote_to_global` | Share cross-project |
+| `admin_health` | Verify health |

package/src/skills/vault-navigator/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: vault-navigator
+description: Use when querying the knowledge base for existing solutions, patterns, best practices, or prior art before building something new.
+---
+
+# Vault Navigator — Knowledge Oracle
+
+Navigate the vault intelligently. Picks the right search strategy based on what the user needs.
+
+## Search Strategy Decision Tree
+
+### "Have we seen this?" / "Best practice for X"
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<question>" }
+```
+
+If results are weak, fall back to `op:search` with explicit filters (type, category, tags, severity).
+
+### "Show me everything about X" (Exploration)
+
+```
+ernesto_core op:vault_tags
+ernesto_core op:vault_domains
+ernesto_core op:vault_recent
+```
+
+### "What's stale?" / "What needs updating?"
+
+```
+ernesto_core op:vault_age_report
+```
+
+### "What do other projects do?"
+
+```
+ernesto_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+ernesto_core op:project_linked_projects
+```
+
+### "Has brain learned about X?"
+
+```
+ernesto_core op:brain_strengths
+ernesto_core op:brain_global_patterns
+  params: { domain: "<domain>" }
+```
+
+### Broad exploration ("What do I know about X?")
+
+Chain: `search_intelligent` -> `vault_tags` / `vault_domains` -> `memory_cross_project_search` -> `brain_strengths`. Label each finding with its source.
+
+## Presenting Results
+
+Always include: **Source** (vault/memory/brain), **Confidence** (score), **Relevance** (why it matches), **Next step** (how to apply).
+
+## Fallback: Web Search
+
+If all vault strategies return nothing, search the web. If web finds something useful, offer to capture: `op:capture_quick`.
+
+## Common Mistakes
+
+- Using only one search strategy instead of trying multiple
+- Not labeling result sources (user can't judge confidence)
+- Saying "nothing found" without trying web search fallback
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Default semantic search |
+| `search` | Structured search with filters |
+| `vault_tags` / `vault_domains` | Browse knowledge landscape |
+| `vault_recent` | Recently modified entries |
+| `vault_age_report` | Stale entries |
+| `memory_cross_project_search` | Cross-project search |
+| `brain_strengths` / `brain_global_patterns` | Proven patterns |
+| `capture_quick` | Capture web findings |

package/src/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing — before committing, creating PRs, or moving to the next task.
+---
+
+# Verification Before Completion
+
+**Core principle:** Evidence before claims, always.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - NO → State actual status with evidence
+   - YES → State claim WITH evidence
+5. AGENT CHECK: Run system diagnostics
+6. ONLY THEN: Make the claim
+```
+
+## Agent System Checks
+
+After passing verification commands:
+
+- `ernesto_core op:admin_health` — catches vault corruption, stale caches
+- `ernesto_core op:admin_diagnostic` — module status, database integrity, config validity
+- `ernesto_core op:admin_vault_analytics` — knowledge quality metrics
+
+If any check reports problems, address before claiming completion.
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test output: 0 failures | Previous run, "should pass" |
+| Build succeeds | Build command: exit 0 | Linter passing |
+| Bug fixed | Original symptom passes | "Code changed, assumed fixed" |
+| Requirements met | Line-by-line checklist | Tests passing alone |
+
+## Red Flags — STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification
+- About to commit/push/PR without verification
+- Relying on partial verification
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence is not evidence |
+| "Just this once" | No exceptions |
+| "Partial check is enough" | Partial proves nothing |
+
+## After Verification
+
+Capture session summary: `ernesto_core op:session_capture params: { summary: "<what was accomplished>" }`
+
+## Common Mistakes
+
+- Claiming "tests pass" based on a previous run
+- Trusting agent success reports without independent verification
+- Running linter but not build (linter does not check compilation)
+- Skipping the red-green cycle for regression tests
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `admin_health` | Quick system health check |
+| `admin_diagnostic` | Comprehensive diagnostic |
+| `admin_vault_analytics` | Knowledge quality metrics |
+| `session_capture` | Persist verified completion context |