@soleri/forge 5.2.0 → 5.5.0

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 |

package/dist/skills/vault-navigator.md

@@ -0,0 +1,129 @@
+---
+name: vault-navigator
+description: Use when the user asks "what does vault say", "search knowledge", "find pattern", "have we seen this before", "best practice for", "check vault", "vault search", "any patterns for", or wants to query the knowledge base for existing solutions or guidance.
+---
+
+# Vault Navigator — Knowledge Oracle
+
+Navigate the vault intelligently. The vault has multiple search strategies — this skill picks the right one based on what the user needs.
+
+## When to Use
+
+Any time the user wants to find existing knowledge before building something new. Also when asking about best practices, previous solutions, or patterns.
+
+## Search Strategy Decision Tree
+
+### For "Have we seen this before?" / "Best practice for X"
+Start with `YOUR_AGENT_core op:search_intelligent` — this is semantic search, the broadest and smartest query. Pass the user's question as the query.
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<user's question>" }
+```
+
+If results are weak (low scores or few matches), fall back to `YOUR_AGENT_core op:search` with explicit filters (type, category, tags, severity). This is structured search — narrower but more precise.
+
+### For "Show me everything about X" (Exploration)
+Use tag-based and domain-based browsing for broader exploration:
+
+```
+YOUR_AGENT_core op:vault_tags
+```
+Lists all tags in the vault — helps discover what topics are covered.
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+Lists all domains — shows the knowledge landscape at a glance.
+
+```
+YOUR_AGENT_core op:vault_recent
+```
+Shows recently added or modified entries — what's fresh in the vault.
+
+### For "What's stale?" / "What needs updating?"
+Run an age report to find outdated knowledge:
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+Present entries that haven't been updated recently — these are candidates for review, refresh, or removal.
+
+### For "What do other projects do?"
+Call `YOUR_AGENT_core op:memory_cross_project_search` with `crossProject: true`. This searches across all linked projects, not just the current one.
+
+```
+YOUR_AGENT_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+```
+
+Check what projects are linked:
+
+```
+YOUR_AGENT_core op:project_linked_projects
+```
+
+### For "Has brain learned anything about X?"
+Call `YOUR_AGENT_core op:brain_strengths` to see which patterns have proven strength. Then call `YOUR_AGENT_core op:brain_global_patterns` with a domain or tag filter to find cross-project patterns.
+
+```
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_global_patterns
+  params: { domain: "<domain>" }
+```
+
+### For "What do I know about X?" (broad exploration)
+Chain multiple strategies for comprehensive results:
+
+1. `search_intelligent` → semantic vault search
+2. `vault_tags` / `vault_domains` → browse knowledge landscape
+3. `memory_cross_project_search` → cross-project patterns
+4. `brain_strengths` → proven patterns
+
+Present all findings with source labels so the user knows where each insight came from.
+
+## Presenting Results
+
+Always include:
+- **Source**: Which search found it (vault, memory, brain, tags, domains)
+- **Confidence**: Score or strength rating
+- **Relevance**: Why this result matches the query
+- **Actionable next step**: How to apply this knowledge
+
+## Fallback: Web Search
+
+If all vault strategies return no results, search the web for the user's question before saying "nothing found." The web may have:
+- Documentation, articles, or guides on the topic
+- Community patterns and best practices
+- Library-specific solutions
+
+If web search finds something useful, offer to capture it to the vault:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<what was found>",
+    description: "<summary from web search, source URL>"
+  }
+```
+
+## Exit Criteria
+
+Search is complete when at least one search strategy has been tried and results presented. If no results found across all strategies (vault + web), say so explicitly — that's valuable information too (it means this is genuinely new territory worth exploring and capturing).
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Default semantic search — broadest and smartest |
+| `search` | Structured search with filters (type, tags, category) |
+| `vault_tags` | Browse all tags — discover knowledge landscape |
+| `vault_domains` | Browse all domains — see what areas are covered |
+| `vault_recent` | Recently modified entries — what's fresh |
+| `vault_age_report` | Find stale entries needing refresh |
+| `memory_cross_project_search` | Search across linked projects |
+| `project_linked_projects` | See what projects are connected |
+| `brain_strengths` | Proven patterns ranked by success |
+| `brain_global_patterns` | Cross-project patterns from global pool |
+| `capture_quick` | Capture web findings to vault for next time |