@soleri/forge 5.5.0 → 5.7.0

package/src/skills/retrospective.md

@@ -20,52 +20,62 @@ Generate a retrospective from actual session data, vault captures, plan outcomes
 ### Step 1: Gather the Data
 
 **Brain stats — the big picture:**
+
 ```
 YOUR_AGENT_core op:brain_stats
 ```
 
 **Recent brain stats — compare velocity:**
+
 ```
 YOUR_AGENT_core op:brain_stats
   params: { since: "<start of period>" }
 ```
 
 **Pattern strengths — what's proven:**
+
 ```
 YOUR_AGENT_core op:brain_strengths
 ```
 
 **Recent vault captures — what was learned:**
+
 ```
 YOUR_AGENT_core op:vault_recent
 ```
 
 **Memory topics — where knowledge clusters:**
+
 ```
 YOUR_AGENT_core op:memory_topics
 ```
 
 **Memory stats — volume and health:**
+
 ```
 YOUR_AGENT_core op:memory_stats
 ```
 
 **Plan stats — execution track record:**
+
 ```
 YOUR_AGENT_core op:plan_stats
 ```
 
 **Loop history — iterative workflow outcomes:**
+
 ```
 YOUR_AGENT_core op:loop_history
 ```
 
 **Search insights — what people looked for but didn't find:**
+
 ```
 YOUR_AGENT_core op:admin_search_insights
 ```
 
 **Vault analytics — knowledge quality:**
+
 ```
 YOUR_AGENT_core op:admin_vault_analytics
 ```
@@ -73,21 +83,25 @@ YOUR_AGENT_core op:admin_vault_analytics
 ### Step 2: Analyze Patterns
 
 **Stale knowledge needing refresh:**
+
 ```
 YOUR_AGENT_core op:vault_age_report
 ```
 
 **Duplicates that crept in:**
+
 ```
 YOUR_AGENT_core op:curator_detect_duplicates
 ```
 
 **Contradictions in the knowledge base:**
+
 ```
 YOUR_AGENT_core op:curator_contradictions
 ```
 
 **Curator health audit — overall quality:**
+
 ```
 YOUR_AGENT_core op:curator_health_audit
 ```
@@ -154,11 +168,13 @@ YOUR_AGENT_core op:capture_knowledge
 If the retrospective revealed quality issues, offer to fix them:
 
 **Consolidate vault (deduplicate, normalize, groom):**
+
 ```
 YOUR_AGENT_core op:curator_consolidate
 ```
 
 **Rebuild brain intelligence with fresh data:**
+
 ```
 YOUR_AGENT_core op:brain_build_intelligence
 ```
@@ -169,21 +185,21 @@ This feels like magic because the user says "sprint retro" and gets a data-drive
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `brain_stats` | Big picture metrics |
-| `brain_strengths` | Proven patterns |
-| `vault_recent` | What was captured recently |
-| `memory_topics` | Knowledge clusters |
-| `memory_stats` | Memory volume and health |
-| `plan_stats` | Plan completion rates |
-| `loop_history` | Iterative workflow outcomes |
-| `admin_search_insights` | Search miss analysis |
-| `admin_vault_analytics` | Knowledge quality metrics |
-| `vault_age_report` | Stale entries |
-| `curator_detect_duplicates` | Duplicate detection |
-| `curator_contradictions` | Knowledge conflicts |
-| `curator_health_audit` | Overall vault quality |
-| `capture_knowledge` | Persist the retrospective |
-| `curator_consolidate` | Post-retro cleanup |
-| `brain_build_intelligence` | Rebuild intelligence |
+| Op                          | When to Use                 |
+| --------------------------- | --------------------------- |
+| `brain_stats`               | Big picture metrics         |
+| `brain_strengths`           | Proven patterns             |
+| `vault_recent`              | What was captured recently  |
+| `memory_topics`             | Knowledge clusters          |
+| `memory_stats`              | Memory volume and health    |
+| `plan_stats`                | Plan completion rates       |
+| `loop_history`              | Iterative workflow outcomes |
+| `admin_search_insights`     | Search miss analysis        |
+| `admin_vault_analytics`     | Knowledge quality metrics   |
+| `vault_age_report`          | Stale entries               |
+| `curator_detect_duplicates` | Duplicate detection         |
+| `curator_contradictions`    | Knowledge conflicts         |
+| `curator_health_audit`      | Overall vault quality       |
+| `capture_knowledge`         | Persist the retrospective   |
+| `curator_consolidate`       | Post-retro cleanup          |
+| `brain_build_intelligence`  | Rebuild intelligence        |

package/src/skills/second-opinion.md

@@ -29,17 +29,20 @@ YOUR_AGENT_core op:route_intent
 ### Step 2: Search All Knowledge Sources (in order)
 
 **Vault — has this been decided before?**
+
 ```
 YOUR_AGENT_core op:search_intelligent
   params: { query: "<the decision or options being considered>" }
 ```
 
 Look specifically for:
+
 - Previous decisions on this topic (type: "decision")
 - Patterns that favor one approach
 - Anti-patterns that warn against an approach
 
 **Brain — what's proven to work?**
+
 ```
 YOUR_AGENT_core op:brain_strengths
 ```
@@ -50,12 +53,14 @@ YOUR_AGENT_core op:brain_recommend
 ```
 
 **Cross-project — what did other projects choose?**
+
 ```
 YOUR_AGENT_core op:memory_cross_project_search
   params: { query: "<the decision topic>", crossProject: true }
 ```
 
 **Memory — any relevant context from past sessions?**
+
 ```
 YOUR_AGENT_core op:memory_search
   params: { query: "<decision topic>" }
@@ -63,6 +68,7 @@ YOUR_AGENT_core op:memory_search
 
 **Web — what does the broader community say?**
 Search the web for:
+
 - Comparison articles (X vs Y for [use case])
 - Benchmarks and performance data
 - Community consensus on best practices
@@ -120,6 +126,7 @@ This is critical — the next person who faces the same decision will find it in
 ## The Magic
 
 This feels like magic because the user asks "should I use X?" and instead of a generic AI opinion, they get:
+
 1. What their own project decided before (vault)
 2. What's proven to work across projects (brain)
 3. What other linked projects chose (cross-project)
@@ -131,12 +138,12 @@ It's like having a senior architect who remembers every decision ever made.
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `route_intent` | Classify the decision type |
-| `search_intelligent` | Find previous decisions and patterns |
-| `brain_strengths` | Proven approaches |
-| `brain_recommend` | Project-specific recommendations |
-| `memory_cross_project_search` | What other projects decided |
-| `memory_search` | Session context for this decision |
-| `capture_knowledge` | Persist the final decision |
+| Op                            | When to Use                          |
+| ----------------------------- | ------------------------------------ |
+| `route_intent`                | Classify the decision type           |
+| `search_intelligent`          | Find previous decisions and patterns |
+| `brain_strengths`             | Proven approaches                    |
+| `brain_recommend`             | Project-specific recommendations     |
+| `memory_cross_project_search` | What other projects decided          |
+| `memory_search`               | Session context for this decision    |
+| `capture_knowledge`           | Persist the final decision           |

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          |