@soleri/forge 5.5.0 → 5.6.0

package/src/skills/executing-plans.md

@@ -41,6 +41,7 @@ YOUR_AGENT_core op:plan_stats
 If no tracked plan exists, read the plan file from `docs/plans/`.
 
 Review critically — identify any questions or concerns about the plan.
+
 - If concerns: Raise them with your human partner before starting
 - If no concerns: Create TodoWrite and proceed
 
@@ -56,9 +57,11 @@ YOUR_AGENT_core op:loop_start
 The loop tracks iterations and validates progress automatically.
 
 ### Step 3: Execute Batch
+
 **Default: First 3 tasks**
 
 For each task:
+
 1. Mark as in_progress:
    ```
    YOUR_AGENT_core op:update_task
@@ -79,7 +82,9 @@ YOUR_AGENT_core op:loop_iterate
 ```
 
 ### Step 4: Report
+
 When batch complete:
+
 - Show what was implemented
 - Show verification output
 - Check loop status:
@@ -89,7 +94,9 @@ When batch complete:
 - Say: "Ready for feedback."
 
 ### Step 5: Continue
+
 Based on feedback:
+
 - Apply changes if needed
 - Execute next batch
 - Repeat until complete
@@ -101,11 +108,13 @@ After all tasks complete and verified:
 1. Run final verification (use verification-before-completion skill)
 
 2. Complete the validation loop:
+
    ```
    YOUR_AGENT_core op:loop_complete
    ```
 
 3. Reconcile plan — compare what was planned vs what actually happened:
+
    ```
    YOUR_AGENT_core op:plan_reconcile
      params: {
@@ -116,12 +125,14 @@ After all tasks complete and verified:
    ```
 
 4. Complete plan lifecycle — extract knowledge and archive:
+
    ```
    YOUR_AGENT_core op:plan_complete_lifecycle
      params: { planId: "<id>" }
    ```
 
 5. Archive the plan for historical reference:
+
    ```
    YOUR_AGENT_core op:plan_archive
      params: { planId: "<id>" }
@@ -150,6 +161,7 @@ Don't wait until the end — capture insights as they happen.
 ## When to Stop and Ask for Help
 
 **STOP executing immediately when:**
+
 - Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
 - Plan has critical gaps preventing starting
 - You don't understand an instruction
@@ -160,12 +172,14 @@ Don't wait until the end — capture insights as they happen.
 ## When to Revisit Earlier Steps
 
 **Return to Review (Step 1) when:**
+
 - Partner updates the plan based on your feedback
 - Fundamental approach needs rethinking
 
 **Don't force through blockers** - stop and ask.
 
 ## Remember
+
 - Review plan critically first
 - Follow plan steps exactly
 - Don't skip verifications
@@ -177,25 +191,26 @@ Don't wait until the end — capture insights as they happen.
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `get_plan` | Load tracked plan |
-| `plan_list_tasks` | List all tasks in the plan |
-| `plan_stats` | Plan overview and metrics |
-| `update_task` | Mark tasks in_progress / completed |
-| `loop_start` | Begin validation loop for iterative execution |
-| `loop_iterate` | Track each iteration |
-| `loop_status` | Check loop progress |
-| `loop_complete` | Finish validation loop |
-| `plan_reconcile` | Compare planned vs actual (post-execution) |
-| `plan_complete_lifecycle` | Extract knowledge from execution |
-| `plan_archive` | Archive plan for history |
-| `session_capture` | Save session context |
-| `capture_quick` | Capture mid-execution learnings |
+| Op                        | When to Use                                   |
+| ------------------------- | --------------------------------------------- |
+| `get_plan`                | Load tracked plan                             |
+| `plan_list_tasks`         | List all tasks in the plan                    |
+| `plan_stats`              | Plan overview and metrics                     |
+| `update_task`             | Mark tasks in_progress / completed            |
+| `loop_start`              | Begin validation loop for iterative execution |
+| `loop_iterate`            | Track each iteration                          |
+| `loop_status`             | Check loop progress                           |
+| `loop_complete`           | Finish validation loop                        |
+| `plan_reconcile`          | Compare planned vs actual (post-execution)    |
+| `plan_complete_lifecycle` | Extract knowledge from execution              |
+| `plan_archive`            | Archive plan for history                      |
+| `session_capture`         | Save session context                          |
+| `capture_quick`           | Capture mid-execution learnings               |
 
 ## Integration
 
 **Required workflow skills:**
+
 - writing-plans — Creates the plan this skill executes
 - verification-before-completion — Verify work before claiming completion
 - test-driven-development — Follow TDD for each implementation step

package/src/skills/fix-and-learn.md

@@ -66,6 +66,7 @@ If vault returns a match with high confidence — **use it**. Don't re-investiga
 ### Step 3: Search the Web
 
 If the vault has no answer, search for existing solutions before investigating from scratch:
+
 - Known issues in the library/framework
 - Stack Overflow answers for the exact error
 - GitHub issues on relevant repos
@@ -85,6 +86,7 @@ YOUR_AGENT_core op:loop_start
 ### Step 5: Diagnose and Fix
 
 Only if Steps 2-3 didn't produce a solution, apply the systematic debugging approach (use systematic-debugging skill):
+
 1. Reproduce the issue
 2. Isolate the root cause
 3. **Plan the fix before writing code** — even a one-line mental plan
@@ -123,6 +125,7 @@ YOUR_AGENT_core op:capture_knowledge
 ```
 
 For quick captures:
+
 ```
 YOUR_AGENT_core op:capture_quick
   params: { title: "<bug>", description: "<root cause and fix>" }
@@ -148,17 +151,17 @@ Fix is complete when: the bug is resolved, tests pass (Step 6), and the root cau
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `route_intent` | Classify as FIX intent |
-| `search_intelligent` | Check vault for known bugs |
-| `memory_search` | Search across session memories |
-| `memory_topics` | See if bugs cluster in an area |
-| `memory_stats` | Understand debugging landscape |
-| `loop_start` | Begin iterative fix cycle |
-| `loop_iterate` | Track each fix attempt |
-| `loop_complete` | Finish fix cycle |
-| `capture_knowledge` | Full anti-pattern capture |
-| `capture_quick` | Fast capture |
-| `curator_detect_duplicates` | Prevent redundant entries |
-| `admin_health` | Verify system health |
+| Op                          | When to Use                    |
+| --------------------------- | ------------------------------ |
+| `route_intent`              | Classify as FIX intent         |
+| `search_intelligent`        | Check vault for known bugs     |
+| `memory_search`             | Search across session memories |
+| `memory_topics`             | See if bugs cluster in an area |
+| `memory_stats`              | Understand debugging landscape |
+| `loop_start`                | Begin iterative fix cycle      |
+| `loop_iterate`              | Track each fix attempt         |
+| `loop_complete`             | Finish fix cycle               |
+| `capture_knowledge`         | Full anti-pattern capture      |
+| `capture_quick`             | Fast capture                   |
+| `curator_detect_duplicates` | Prevent redundant entries      |
+| `admin_health`              | Verify system health           |

package/src/skills/health-check.md

@@ -87,6 +87,7 @@ YOUR_AGENT_core op:vault_age_report
 ```
 
 Entries older than 30 days without updates are candidates for:
+
 - Refresh (still relevant, needs updating)
 - Archive (no longer relevant)
 - Delete (incorrect or superseded)
@@ -135,26 +136,31 @@ YOUR_AGENT_core op:governance_expire
 If the user approves, run the full cleanup:
 
 **Groom all entries — normalize tags, fix metadata:**
+
 ```
 YOUR_AGENT_core op:curator_groom_all
 ```
 
 **Full consolidation — deduplicate, normalize, quality-score:**
+
 ```
 YOUR_AGENT_core op:curator_consolidate
 ```
 
 **Prune stale memory:**
+
 ```
 YOUR_AGENT_core op:memory_prune
 ```
 
 **Rebuild brain intelligence with clean data:**
+
 ```
 YOUR_AGENT_core op:brain_build_intelligence
 ```
 
 **Reset caches to pick up changes:**
+
 ```
 YOUR_AGENT_core op:admin_reset_cache
 ```
@@ -200,26 +206,26 @@ This feels like magic because knowledge bases normally decay silently — duplic
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `admin_health` | System health check |
-| `admin_diagnostic` | Comprehensive system diagnostic |
-| `admin_vault_size` | Vault storage metrics |
-| `admin_vault_analytics` | Knowledge quality metrics |
-| `admin_search_insights` | Search miss analysis |
-| `admin_reset_cache` | Clear caches after cleanup |
-| `vault_domains` / `vault_tags` | Knowledge landscape |
-| `vault_age_report` | Stale entry detection |
-| `curator_health_audit` | Quality score and audit |
-| `curator_detect_duplicates` | Find duplicates |
-| `curator_contradictions` | Find conflicting entries |
-| `curator_resolve_contradiction` | Resolve conflicts |
-| `curator_groom_all` | Batch tag normalization |
-| `curator_consolidate` | Full cleanup pipeline |
-| `memory_stats` | Memory health |
-| `memory_deduplicate` | Remove duplicate memories |
-| `memory_prune` | Remove stale memories |
-| `governance_proposals` | Pending review queue |
-| `governance_stats` | Governance metrics |
-| `governance_expire` | Expire stale proposals |
-| `brain_build_intelligence` | Rebuild after cleanup |
+| Op                              | When to Use                     |
+| ------------------------------- | ------------------------------- |
+| `admin_health`                  | System health check             |
+| `admin_diagnostic`              | Comprehensive system diagnostic |
+| `admin_vault_size`              | Vault storage metrics           |
+| `admin_vault_analytics`         | Knowledge quality metrics       |
+| `admin_search_insights`         | Search miss analysis            |
+| `admin_reset_cache`             | Clear caches after cleanup      |
+| `vault_domains` / `vault_tags`  | Knowledge landscape             |
+| `vault_age_report`              | Stale entry detection           |
+| `curator_health_audit`          | Quality score and audit         |
+| `curator_detect_duplicates`     | Find duplicates                 |
+| `curator_contradictions`        | Find conflicting entries        |
+| `curator_resolve_contradiction` | Resolve conflicts               |
+| `curator_groom_all`             | Batch tag normalization         |
+| `curator_consolidate`           | Full cleanup pipeline           |
+| `memory_stats`                  | Memory health                   |
+| `memory_deduplicate`            | Remove duplicate memories       |
+| `memory_prune`                  | Remove stale memories           |
+| `governance_proposals`          | Pending review queue            |
+| `governance_stats`              | Governance metrics              |
+| `governance_expire`             | Expire stale proposals          |
+| `brain_build_intelligence`      | Rebuild after cleanup           |

package/src/skills/knowledge-harvest.md

@@ -49,15 +49,16 @@ This tells you what the vault already covers — focus extraction on gaps.
 
 Read through the source material and identify:
 
-| Type | What to Look For |
-|------|-----------------|
-| **pattern** | "We always do X because Y" — repeatable approaches |
-| **anti-pattern** | "Don't do X because Y" — known mistakes |
-| **decision** | "We chose X over Y because Z" — architectural choices |
-| **principle** | "We believe X" — guiding rules |
-| **workflow** | "The process for X is: step 1, step 2..." — procedures |
+| Type             | What to Look For                                       |
+| ---------------- | ------------------------------------------------------ |
+| **pattern**      | "We always do X because Y" — repeatable approaches     |
+| **anti-pattern** | "Don't do X because Y" — known mistakes                |
+| **decision**     | "We chose X over Y because Z" — architectural choices  |
+| **principle**    | "We believe X" — guiding rules                         |
+| **workflow**     | "The process for X is: step 1, step 2..." — procedures |
 
 For each extracted item, determine:
+
 - **Category**: Which domain it belongs to
 - **Severity**: critical / warning / suggestion
 - **Tags**: Searchable keywords
@@ -81,6 +82,7 @@ YOUR_AGENT_core op:capture_knowledge
 ```
 
 Present each capture to the user as you go:
+
 ```
 Captured: api-auth-jwt (pattern, critical)
   → "Use short-lived JWTs for authentication"
@@ -92,22 +94,26 @@ Captured: api-auth-jwt (pattern, critical)
 After all items captured, run quality checks:
 
 **Detect any duplicates created during harvest:**
+
 ```
 YOUR_AGENT_core op:curator_detect_duplicates
 ```
 
 **Groom all new entries — normalize tags, fix metadata:**
+
 ```
 YOUR_AGENT_core op:curator_groom_all
 ```
 
 **Enrich entries with additional context:**
+
 ```
 YOUR_AGENT_core op:curator_enrich
   params: { entryId: "<id>" }
 ```
 
 **Check for contradictions with existing knowledge:**
+
 ```
 YOUR_AGENT_core op:curator_contradictions
 ```
@@ -125,6 +131,7 @@ YOUR_AGENT_core op:admin_vault_analytics
 ```
 
 Present a summary:
+
 ```
 ## Harvest Complete
 
@@ -163,16 +170,16 @@ This feels like magic because the user points at a 50-page architecture doc and
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `route_intent` | Classify the source material |
-| `search_intelligent` | Check for existing knowledge |
-| `vault_tags` / `vault_domains` | See what's already covered |
-| `capture_knowledge` | Capture each extracted item |
-| `curator_detect_duplicates` | Find duplicates post-harvest |
-| `curator_groom_all` | Normalize all new entries |
-| `curator_enrich` | LLM-enrich entries |
-| `curator_contradictions` | Find conflicts with existing knowledge |
-| `memory_promote_to_global` | Share universal patterns cross-project |
-| `admin_health` | Post-harvest health check |
-| `admin_vault_analytics` | Knowledge quality metrics |
+| Op                             | When to Use                            |
+| ------------------------------ | -------------------------------------- |
+| `route_intent`                 | Classify the source material           |
+| `search_intelligent`           | Check for existing knowledge           |
+| `vault_tags` / `vault_domains` | See what's already covered             |
+| `capture_knowledge`            | Capture each extracted item            |
+| `curator_detect_duplicates`    | Find duplicates post-harvest           |
+| `curator_groom_all`            | Normalize all new entries              |
+| `curator_enrich`               | LLM-enrich entries                     |
+| `curator_contradictions`       | Find conflicts with existing knowledge |
+| `memory_promote_to_global`     | Share universal patterns cross-project |
+| `admin_health`                 | Post-harvest health check              |
+| `admin_vault_analytics`        | Knowledge quality metrics              |

package/src/skills/onboard-me.md

@@ -169,6 +169,7 @@ Use `/second-opinion` before making any architectural decision.
 ## The Magic
 
 This feels like magic because a new team member says "onboard me" and instantly gets:
+
 1. Every critical rule they must follow
 2. Every architectural decision and why it was made
 3. Proven patterns to follow
@@ -180,18 +181,18 @@ No other onboarding tool does this — it's not a static wiki, it's a living kno
 
 ## Agent Tools Reference
 
-| Op | When to Use |
-|----|-------------|
-| `identity` | Project persona and description |
-| `project_get` | Project registration details |
-| `project_list_rules` | Project-specific rules |
-| `get_behavior_rules` | Behavioral conventions |
-| `vault_domains` / `vault_tags` | Knowledge landscape |
-| `admin_vault_size` | How much knowledge exists |
-| `search` | Find critical entries and anti-patterns |
-| `search_intelligent` | Find decisions and patterns |
-| `brain_strengths` | Proven approaches |
-| `brain_global_patterns` | Cross-project patterns |
-| `project_linked_projects` | Related projects |
-| `admin_search_insights` | What's not in the vault |
-| `vault_age_report` | Stale knowledge areas |
+| Op                             | When to Use                             |
+| ------------------------------ | --------------------------------------- |
+| `identity`                     | Project persona and description         |
+| `project_get`                  | Project registration details            |
+| `project_list_rules`           | Project-specific rules                  |
+| `get_behavior_rules`           | Behavioral conventions                  |
+| `vault_domains` / `vault_tags` | Knowledge landscape                     |
+| `admin_vault_size`             | How much knowledge exists               |
+| `search`                       | Find critical entries and anti-patterns |
+| `search_intelligent`           | Find decisions and patterns             |
+| `brain_strengths`              | Proven approaches                       |
+| `brain_global_patterns`        | Cross-project patterns                  |
+| `project_linked_projects`      | Related projects                        |
+| `admin_search_insights`        | What's not in the vault                 |
+| `vault_age_report`             | Stale knowledge areas                   |

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           |