@soleri/forge 5.4.0 → 5.6.0

package/dist/skills/systematic-debugging.md

@@ -0,0 +1,230 @@
+---
+name: systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+<!-- Adapted from superpowers (MIT License) -->
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+## Phase 0: Search Before Investigating
+
+**BEFORE touching any code**, search for existing solutions. Follow this order:
+
+### Vault First
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<description of the bug or error message>" }
+```
+
+If the vault has a matching anti-pattern or previous fix, it likely contains the root cause and solution — apply it directly. This can save hours of investigation.
+
+Also check brain strengths for relevant debugging patterns:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+Check memory for similar bugs across sessions:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "<error or symptom>" }
+```
+
+### Web Search Second
+If the vault has nothing, search the web before investigating from scratch:
+- **Paste the exact error message** — someone likely hit this before
+- **Check GitHub issues** on relevant libraries
+- **Check Stack Overflow** for the error + framework/library combination
+- **Check official docs** — is this a known limitation or misconfiguration?
+
+A 30-second search that finds "this is a known issue in v3.2, upgrade to v3.3" saves hours of root cause investigation.
+
+### Then Investigate
+Only if vault and web search produce no answer, proceed to Phase 1.
+
+## Start a Debug Loop
+
+For complex bugs, start a validation loop to track investigation iterations:
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "Debug: <bug description>", mode: "custom" }
+```
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. Read Error Messages Carefully
+2. Reproduce Consistently
+3. Check Recent Changes
+4. Gather Evidence in Multi-Component Systems (add diagnostic instrumentation at each component boundary)
+5. Trace Data Flow backward through call stack
+
+Track each investigation step:
+```
+YOUR_AGENT_core op:loop_iterate
+```
+
+### Phase 2: Pattern Analysis
+
+1. Find Working Examples
+2. Compare Against References (read completely, don't skim)
+3. Identify Differences
+4. Understand Dependencies
+
+Search vault for working patterns to compare against:
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<working feature similar to broken one>" }
+```
+
+### Phase 3: Hypothesis and Testing
+
+1. Form Single Hypothesis ("I think X is the root cause because Y")
+2. Test Minimally (one variable at a time)
+3. Verify Before Continuing
+4. When You Don't Know — say so, ask for help
+
+### Phase 4: Implementation
+
+1. Create Failing Test Case (use test-driven-development skill)
+2. Implement Single Fix (root cause only, one change at a time)
+3. Verify Fix
+4. If Fix Doesn't Work: count attempts. If < 3, return to Phase 1. If >= 3, STOP and question architecture.
+5. If 3+ Fixes Failed: Question Architecture — discuss with human partner before attempting more fixes.
+
+## Phase 5: Capture the Learning
+
+Complete the debug loop:
+```
+YOUR_AGENT_core op:loop_complete
+```
+
+**MANDATORY after every resolved bug.** A fix without a capture is an incomplete fix.
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<short bug description>",
+    description: "<root cause, solution, and what made it hard to find>",
+    type: "anti-pattern",
+    category: "<relevant domain>",
+    tags: ["<relevant>", "<tags>"]
+  }
+```
+
+For quick captures when the fix is straightforward:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<bug description>",
+    description: "<root cause and fix>"
+  }
+```
+
+Capture a session summary:
+```
+YOUR_AGENT_core op:session_capture
+  params: { summary: "<bug, root cause, fix, files modified>" }
+```
+
+This is what makes the agent smarter over time. Next time someone hits a similar bug, Phase 0 vault search will surface your solution immediately.
+
+## Red Flags - STOP and Follow Process
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. |
+| "Emergency, no time for process" | Systematic is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+| "Skip the vault, I know this one" | The vault may know it better. 30 seconds to check saves hours. |
+
+## Quick Reference
+
+| Phase | Key Activities | Agent Tools |
+|-------|---------------|-------------|
+| **0. Search First** | Vault search, web search, 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** | Create test, fix, verify | `loop_iterate` |
+| **5. Capture** | Persist root cause, close loop | `capture_knowledge`, `loop_complete`, `session_capture` |
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Search vault for known bugs and patterns |
+| `brain_strengths` | Check proven debugging patterns |
+| `memory_search` | Search across session memories |
+| `loop_start` | Begin iterative debug cycle |
+| `loop_iterate` | Track each investigation/fix attempt |
+| `loop_complete` | Finish debug cycle |
+| `capture_knowledge` | Full anti-pattern capture |
+| `capture_quick` | Fast capture for simple fixes |
+| `session_capture` | Persist session context |
+
+**Related skills:**
+- test-driven-development
+- verification-before-completion
+- fix-and-learn (combines debugging + capture in one workflow)

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

@@ -0,0 +1,266 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix, before writing implementation code
+---
+
+<!-- Adapted from superpowers (MIT License) -->
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+**Violating the letter of the rules is violating the spirit of the rules.**
+
+## When to Use
+
+**Always:**
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask your human partner):**
+- Throwaway prototypes
+- Generated code
+- Configuration files
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+## Before You Start — Search First, Code Second
+
+**Never start writing tests blind.** Follow this lookup order:
+
+### 1. Vault First
+Check for existing testing patterns in the knowledge base:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<what you're about to test>" }
+```
+
+Look for:
+- **Testing patterns** for similar features (how were they tested before?)
+- **Anti-patterns** — common testing mistakes in this domain
+- **Proven approaches** from brain strengths:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+If the vault has testing guidance for this domain, follow it. Don't reinvent test strategies that have already been validated.
+
+### 2. Web Search
+If the vault has no relevant patterns, search the web for established testing approaches:
+- Library-specific testing patterns (e.g., how to test React hooks, Express middleware)
+- Best practices for the specific type of test (integration, e2e, unit)
+- Known gotchas in the testing framework being used
+
+### 3. Then Write the Test
+Only after consulting vault and web, proceed to write the failing test. You'll write better tests when informed by existing knowledge.
+
+## Start a TDD Loop
+
+For multi-test TDD cycles, start a validation loop to track iterations:
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "TDD: <feature being implemented>", mode: "custom" }
+```
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+Implement fresh from tests. Period.
+
+## Red-Green-Refactor
+
+### RED - Write Failing Test
+
+Write one minimal test showing what should happen.
+
+Good: clear name, tests real behavior, one thing
+Bad: vague name, tests mock not code
+
+**Requirements:**
+- One behavior
+- Clear name
+- Real code (no mocks unless unavoidable)
+
+### Verify RED - Watch It Fail
+
+**MANDATORY. Never skip.**
+
+Run: `npm test path/to/test.test.ts`
+
+Confirm:
+- Test fails (not errors)
+- Failure message is expected
+- Fails because feature missing (not typos)
+
+**Test passes?** You're testing existing behavior. Fix test.
+**Test errors?** Fix error, re-run until it fails correctly.
+
+Track the iteration:
+```
+YOUR_AGENT_core op:loop_iterate
+```
+
+### GREEN - Minimal Code
+
+Write simplest code to pass the test. Don't add features, refactor other code, or "improve" beyond the test.
+
+### Verify GREEN - Watch It Pass
+
+**MANDATORY.**
+
+Run: `npm test path/to/test.test.ts`
+
+Confirm:
+- Test passes
+- Other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix code, not test.
+**Other tests fail?** Fix now.
+
+Track the iteration:
+```
+YOUR_AGENT_core 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 feature.
+
+## Good Tests
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear** | Name describes behavior | `test('test1')` |
+| **Shows intent** | Demonstrates desired API | Obscures what code should do |
+
+## Why Order Matters
+
+Tests written after code pass immediately — proving nothing. Test-first forces you to watch the test fail, proving it actually tests something.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
+| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
+| "Existing code has no tests" | You're improving it. Add tests for existing code. |
+
+## Red Flags - STOP and Start Over
+
+- Code before test
+- Test after implementation
+- Test passes immediately
+- Can't explain why test failed
+- Tests added "later"
+- Rationalizing "just this once"
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "Keep as reference" or "adapt existing code"
+- "Already spent X hours, deleting is wasteful"
+- "TDD is dogmatic, I'm being pragmatic"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.
+
+## After TDD — Capture and Complete
+
+Complete the loop:
+```
+YOUR_AGENT_core op:loop_complete
+```
+
+If you discovered a new testing pattern, edge case, or anti-pattern during the TDD cycle, capture it:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<testing pattern or anti-pattern>",
+    description: "<what you learned, when it applies, why it matters>"
+  }
+```
+
+This compounds across sessions — next time someone works on similar code, the vault will surface your testing insight.
+
+## When Stuck
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
+| Test too complicated | Design too complicated. Simplify interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify design. |
+
+## Final Rule
+
+```
+Production code → test exists and failed first
+Otherwise → not TDD
+```
+
+No exceptions without your human partner's permission.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Find testing patterns before starting |
+| `brain_strengths` | Check proven testing approaches |
+| `loop_start` | Begin TDD validation loop |
+| `loop_iterate` | Track each red-green cycle |
+| `loop_complete` | Finish TDD loop |
+| `capture_quick` | Capture new testing patterns |

package/dist/skills/vault-capture.md

@@ -0,0 +1,154 @@
+---
+name: vault-capture
+description: Use when the user says "capture this", "save to vault", "remember this pattern", "log this anti-pattern", "store this knowledge", "add to vault", "capture what we learned", or wants to persist a pattern, anti-pattern, workflow, or principle to the knowledge base.
+---
+
+# Vault Capture — Persist Knowledge
+
+Capture patterns, anti-patterns, workflows, and principles to the vault. Captured knowledge compounds — it informs future vault searches, brain recommendations, and team reviews.
+
+## When to Use
+
+After discovering something worth remembering: a solution that worked, a mistake to avoid, a workflow that proved effective, or a principle that should guide future work.
+
+## Orchestration Sequence
+
+### Step 1: Check for Duplicates
+Call `YOUR_AGENT_core op:search_intelligent` with the knowledge title or description. If a similar entry exists, consider updating it instead of creating a duplicate.
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<knowledge title or description>" }
+```
+
+Also run duplicate detection explicitly:
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+If duplicates are found, decide: update the existing entry or merge them.
+
+### Step 2: Classify the Knowledge
+Determine the entry type:
+- **pattern** — Something that works and should be repeated
+- **anti-pattern** — Something that fails and should be avoided
+- **workflow** — A sequence of steps for a specific task
+- **principle** — A guiding rule or heuristic
+- **decision** — An architectural or design choice with rationale
+
+Use intent routing to help classify:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "<description of the knowledge>" }
+```
+
+### Step 3: Capture
+For quick, single-entry captures:
+Call `YOUR_AGENT_core op:capture_knowledge` with:
+- **title**: Clear, searchable name
+- **description**: What it is and when it applies
+- **type**: From Step 2 classification
+- **category**: Domain area (e.g., "component-patterns", "api-design", "infrastructure")
+- **tags**: Searchable keywords
+- **example**: Code snippet or before/after if applicable
+- **why**: The reasoning — this is what makes the entry actionable
+
+```
+YOUR_AGENT_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 area>",
+    tags: ["<tag1>", "<tag2>"],
+    example: "<code or before/after>",
+    why: "<reasoning>"
+  }
+```
+
+For quick captures:
+```
+YOUR_AGENT_core op:capture_quick
+  params: { title: "<name>", description: "<details>" }
+```
+
+### Step 4: Post-Capture Quality
+
+After capturing, run the curator to ensure quality:
+
+**Groom the entry** — normalize tags, fix metadata:
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryId: "<captured entry id>" }
+```
+
+**Enrich the entry** — use LLM to add context, improve description:
+```
+YOUR_AGENT_core op:curator_enrich
+  params: { entryId: "<captured entry id>" }
+```
+
+**Check for contradictions** — does this conflict with existing knowledge?
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+If contradictions found, resolve them:
+```
+YOUR_AGENT_core op:curator_resolve_contradiction
+  params: { contradictionId: "<id>" }
+```
+
+### Step 5: Handle Governance (if enabled)
+If governance policy requires review, the capture returns a `proposalId`. The entry is queued for approval.
+
+```
+YOUR_AGENT_core op:governance_proposals
+  params: { action: "list" }
+```
+
+Present pending proposals to the user for approval.
+
+### Step 6: Promote to Global (Optional)
+If the knowledge applies across projects (not project-specific):
+```
+YOUR_AGENT_core op:memory_promote_to_global
+  params: { entryId: "<entry id>" }
+```
+
+This makes it available in cross-project searches and brain recommendations.
+
+### Step 7: Verify Health
+Confirm the capture was stored and vault health is maintained:
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Check vault analytics for overall knowledge quality:
+```
+YOUR_AGENT_core op:admin_vault_analytics
+```
+
+## Exit Criteria
+
+Capture is complete when: the entry is stored (or queued for review), categorized, tagged, groomed, and vault health confirmed. If promoted to global, cross-project availability is verified.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Check for duplicates before capture |
+| `curator_detect_duplicates` | Explicit duplicate detection |
+| `route_intent` | Help classify knowledge type |
+| `capture_knowledge` | Full-metadata capture |
+| `capture_quick` | Fast capture for simple entries |
+| `curator_groom` | Normalize tags and metadata |
+| `curator_enrich` | LLM-powered metadata enrichment |
+| `curator_contradictions` | Find conflicting entries |
+| `curator_resolve_contradiction` | Resolve conflicts |
+| `governance_proposals` | Check/manage approval queue |
+| `memory_promote_to_global` | Share across projects |
+| `admin_health` | Verify system health |
+| `admin_vault_analytics` | Overall knowledge quality metrics |