@soleri/forge 5.5.0 → 5.6.0

package/src/skills/systematic-debugging.md

@@ -26,6 +26,7 @@ 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
@@ -34,6 +35,7 @@ Use for ANY technical issue:
 - 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
@@ -45,6 +47,7 @@ Use for ANY technical issue:
 **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>" }
@@ -66,7 +69,9 @@ YOUR_AGENT_core op:memory_search
 ```
 
 ### 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
@@ -75,6 +80,7 @@ If the vault has nothing, search the web before investigating from scratch:
 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
@@ -101,6 +107,7 @@ You MUST complete each phase before proceeding to the next.
 5. Trace Data Flow backward through call stack
 
 Track each investigation step:
+
 ```
 YOUR_AGENT_core op:loop_iterate
 ```
@@ -113,6 +120,7 @@ YOUR_AGENT_core op:loop_iterate
 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>" }
@@ -136,6 +144,7 @@ YOUR_AGENT_core op:search_intelligent
 ## Phase 5: Capture the Learning
 
 Complete the debug loop:
+
 ```
 YOUR_AGENT_core op:loop_complete
 ```
@@ -164,6 +173,7 @@ YOUR_AGENT_core op:capture_quick
 ```
 
 Capture a session summary:
+
 ```
 YOUR_AGENT_core op:session_capture
   params: { summary: "<bug, root cause, fix, files modified>" }
@@ -187,44 +197,45 @@ This is what makes the agent smarter over time. Next time someone hits a similar
 
 ## 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. |
+| 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` |
+| 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 |
-|----|-------------|
+| 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 |
+| `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/src/skills/test-driven-development.md

@@ -18,12 +18,14 @@ Write the test first. Watch it fail. Write minimal code to pass.
 ## When to Use
 
 **Always:**
+
 - New features
 - Bug fixes
 - Refactoring
 - Behavior changes
 
 **Exceptions (ask your human partner):**
+
 - Throwaway prototypes
 - Generated code
 - Configuration files
@@ -35,6 +37,7 @@ Thinking "skip TDD just this once"? Stop. That's rationalization.
 **Never start writing tests blind.** Follow this lookup order:
 
 ### 1. Vault First
+
 Check for existing testing patterns in the knowledge base:
 
 ```
@@ -43,6 +46,7 @@ YOUR_AGENT_core op:search_intelligent
 ```
 
 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:
@@ -54,12 +58,15 @@ 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
@@ -80,6 +87,7 @@ 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
@@ -97,6 +105,7 @@ 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)
@@ -108,6 +117,7 @@ Bad: vague name, tests mock not code
 Run: `npm test path/to/test.test.ts`
 
 Confirm:
+
 - Test fails (not errors)
 - Failure message is expected
 - Fails because feature missing (not typos)
@@ -116,6 +126,7 @@ Confirm:
 **Test errors?** Fix error, re-run until it fails correctly.
 
 Track the iteration:
+
 ```
 YOUR_AGENT_core op:loop_iterate
 ```
@@ -131,6 +142,7 @@ Write simplest code to pass the test. Don't add features, refactor other code, o
 Run: `npm test path/to/test.test.ts`
 
 Confirm:
+
 - Test passes
 - Other tests still pass
 - Output pristine (no errors, warnings)
@@ -139,6 +151,7 @@ Confirm:
 **Other tests fail?** Fix now.
 
 Track the iteration:
+
 ```
 YOUR_AGENT_core op:loop_iterate
 ```
@@ -146,6 +159,7 @@ YOUR_AGENT_core op:loop_iterate
 ### REFACTOR - Clean Up
 
 After green only:
+
 - Remove duplication
 - Improve names
 - Extract helpers
@@ -158,11 +172,11 @@ 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 |
+| 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
 
@@ -170,19 +184,19 @@ Tests written after code pass immediately — proving nothing. Test-first forces
 
 ## 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. |
+| 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
 
@@ -220,6 +234,7 @@ Can't check all boxes? You skipped TDD. Start over.
 ## After TDD — Capture and Complete
 
 Complete the loop:
+
 ```
 YOUR_AGENT_core op:loop_complete
 ```
@@ -238,12 +253,12 @@ This compounds across sessions — next time someone works on similar code, the
 
 ## When Stuck
 
-| Problem | Solution |
-|---------|----------|
+| 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. |
+| 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
 
@@ -256,11 +271,11 @@ No exceptions without your human partner's permission.
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
+| 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 |
+| `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/src/skills/vault-capture.md

@@ -14,6 +14,7 @@ After discovering something worth remembering: a solution that worked, a mistake
 ## 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.
 
 ```
@@ -30,7 +31,9 @@ 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
@@ -45,8 +48,10 @@ YOUR_AGENT_core op:route_intent
 ```
 
 ### 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
@@ -69,6 +74,7 @@ YOUR_AGENT_core op:capture_knowledge
 ```
 
 For quick captures:
+
 ```
 YOUR_AGENT_core op:capture_quick
   params: { title: "<name>", description: "<details>" }
@@ -79,29 +85,34 @@ YOUR_AGENT_core op:capture_quick
 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.
 
 ```
@@ -112,7 +123,9 @@ YOUR_AGENT_core op:governance_proposals
 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>" }
@@ -121,12 +134,15 @@ YOUR_AGENT_core op:memory_promote_to_global
 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
 ```
@@ -137,18 +153,18 @@ Capture is complete when: the entry is stored (or queued for review), categorize
 
 ## 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 |
+| 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/src/skills/vault-navigator.md

@@ -14,6 +14,7 @@ Any time the user wants to find existing knowledge before building something new
 ## 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.
 
 ```
@@ -24,24 +25,29 @@ YOUR_AGENT_core op:search_intelligent
 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:
 
 ```
@@ -51,6 +57,7 @@ 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.
 
 ```
@@ -65,6 +72,7 @@ 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.
 
 ```
@@ -74,6 +82,7 @@ YOUR_AGENT_core op:brain_global_patterns
 ```
 
 ### For "What do I know about X?" (broad exploration)
+
 Chain multiple strategies for comprehensive results:
 
 1. `search_intelligent` → semantic vault search
@@ -86,6 +95,7 @@ Present all findings with source labels so the user knows where each insight cam
 ## 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
@@ -94,6 +104,7 @@ Always include:
 ## 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
@@ -114,16 +125,16 @@ Search is complete when at least one search strategy has been tried and results
 
 ## 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 |
+| 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           |