@soleri/forge 5.4.0 → 5.5.0

package/src/skills/code-patrol.md

@@ -0,0 +1,176 @@
+---
+name: code-patrol
+description: Use when the user asks "review this code", "check this against patterns", "code patrol", "does this follow our rules", "validate against vault", "check for anti-patterns", or wants code reviewed not against generic lint rules but against the project's own captured patterns, anti-patterns, and conventions.
+---
+
+# Code Patrol — Review Code Against Your Own Knowledge
+
+Review code against the vault's patterns, anti-patterns, and project conventions — not generic lint rules, but YOUR team's captured knowledge applied to new code. Catches violations that no linter knows about.
+
+## When to Use
+
+- Before committing or creating a PR
+- "Does this follow our patterns?"
+- "Check this code against our rules"
+- Code review with institutional knowledge
+- After writing implementation code
+
+## The Magic: Project-Specific Code Intelligence
+
+### Step 1: Understand the Code's Domain
+
+Classify what domain this code belongs to:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "Code review: <brief description of the code>" }
+```
+
+Determine which vault domains are relevant:
+
+```
+YOUR_AGENT_core op:vault_domains
+```
+
+### Step 2: Load Relevant Patterns
+
+Search for patterns in the code's domain:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<what this code does>" }
+```
+
+Search specifically for anti-patterns to check against:
+
+```
+YOUR_AGENT_core op:search
+  params: { type: "anti-pattern" }
+```
+
+Search for critical rules that must not be violated:
+
+```
+YOUR_AGENT_core op:search
+  params: { severity: "critical" }
+```
+
+Load project-specific rules:
+
+```
+YOUR_AGENT_core op:project_list_rules
+```
+
+```
+YOUR_AGENT_core op:get_behavior_rules
+```
+
+Get proven approaches from the brain:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+### Step 3: Review the Code
+
+With vault patterns loaded, review the code checking for:
+
+| Check | Source | Severity |
+|-------|--------|----------|
+| Violates a critical rule | `search (severity: critical)` | Must fix |
+| Matches a known anti-pattern | `search (type: anti-pattern)` | Must fix |
+| Doesn't follow a proven pattern | `brain_strengths` | Should fix |
+| Breaks project conventions | `project_list_rules` | Should fix |
+| Misses an opportunity to use a pattern | `search_intelligent` | Could improve |
+
+### Step 4: Present the Review
+
+```
+## Code Patrol Report
+
+### Must Fix (Critical)
+- **[Rule name]**: [What's wrong and why]
+  Vault ref: [entry title] (severity: critical)
+  Fix: [How to fix it]
+
+### Should Fix (Warning)
+- **[Anti-pattern name]**: [What's wrong]
+  Vault ref: [entry title] (type: anti-pattern)
+  Better approach: [The pattern to follow]
+
+### Could Improve (Suggestion)
+- **[Pattern opportunity]**: [The code works but could benefit from...]
+  Vault ref: [entry title] (type: pattern)
+
+### Looks Good
+- [What the code does well — patterns it follows correctly]
+
+### Summary
+X critical issues, Y warnings, Z suggestions
+Patterns followed: [list]
+Patterns missed: [list]
+```
+
+### Step 5: Learn From the Review
+
+If the review reveals a new pattern or anti-pattern not in the vault, capture it:
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<new pattern or anti-pattern discovered>",
+    description: "<what it is, when it applies>"
+  }
+```
+
+If the review reveals a knowledge gap, note it:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<missing convention>",
+    description: "<this should be documented as a project rule>",
+    type: "principle",
+    category: "<domain>",
+    tags: ["convention", "code-review"]
+  }
+```
+
+### Step 6: Verify After Fixes
+
+After the user applies fixes, re-run the patrol to confirm clean:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<re-check the specific violations>" }
+```
+
+Check system health:
+```
+YOUR_AGENT_core op:admin_health
+```
+
+## The Magic
+
+This feels like magic because:
+1. It's not ESLint — it catches things like "we decided not to use inheritance here" or "this API pattern caused production issues last month"
+2. The rules come from YOUR team's experience, not a generic config file
+3. It gets smarter over time — every captured pattern becomes a new check
+4. It catches institutional knowledge violations that no static analyzer can
+
+A linter checks syntax. Code patrol checks wisdom.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify the code's domain |
+| `vault_domains` | See which domains are relevant |
+| `search_intelligent` | Find relevant patterns for this code |
+| `search` | Find anti-patterns and critical rules |
+| `project_list_rules` | Project-specific conventions |
+| `get_behavior_rules` | Behavioral rules |
+| `brain_strengths` | Proven patterns to check against |
+| `capture_quick` | Capture new patterns discovered during review |
+| `capture_knowledge` | Capture new conventions |
+| `admin_health` | Post-review health check |

package/src/skills/context-resume.md

@@ -0,0 +1,143 @@
+---
+name: context-resume
+description: Use when starting a new session, returning to work, or when the user asks "what was I working on", "where did I leave off", "catch me up", "morning standup", "resume", "what's the status". Reconstructs full working context from memory, plans, and sessions.
+---
+
+# Context Resume — Pick Up Where You Left Off
+
+Reconstruct your full working context in seconds. Chains memory, plans, sessions, and brain to rebuild exactly where you left off — even across session boundaries and context compactions.
+
+## When to Use
+
+- Starting a new Claude Code session
+- Returning after a break
+- "What was I working on?"
+- "Morning standup"
+- After context compaction (session_capture fires automatically, this reads it back)
+
+## The Magic: Full Context Reconstruction
+
+### Step 1: Load Active Plans
+
+Check for plans in progress — these are your active work streams:
+
+```
+YOUR_AGENT_core op:plan_stats
+```
+
+For each active plan, load its details and task status:
+
+```
+YOUR_AGENT_core op:get_plan
+YOUR_AGENT_core op:plan_list_tasks
+  params: { planId: "<id>" }
+```
+
+Present:
+- Plan objective and current status
+- Which tasks are completed, in progress, or pending
+- What's next to do
+
+### Step 2: Search Recent Memory
+
+Load the latest session summaries — these capture what happened before:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "session summary" }
+```
+
+```
+YOUR_AGENT_core op:memory_list
+```
+
+Also check recent vault captures — what knowledge was added recently?
+
+```
+YOUR_AGENT_core op:vault_recent
+```
+
+### Step 3: Check Active Loops
+
+See if there's a validation loop in progress:
+
+```
+YOUR_AGENT_core op:loop_is_active
+```
+
+If active:
+```
+YOUR_AGENT_core op:loop_status
+```
+
+This tells you if an iterative workflow (TDD, debugging, migration) was mid-flight.
+
+### Step 4: Brain Snapshot
+
+Get the latest brain insights relevant to current work:
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+### Step 5: System Health
+
+Quick health check to make sure everything is working:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+## Presenting the Resume
+
+Format as a concise standup:
+
+```
+## Where You Left Off
+
+**Active Plans:**
+- [Plan name] — X/Y tasks complete, next: [task description]
+
+**Last Session:**
+- [Summary from memory — what was done, key decisions]
+
+**Recent Captures:**
+- [New patterns/anti-patterns added to vault]
+
+**Active Loops:**
+- [Any in-progress validation loops]
+
+**Brain Says:**
+- [Top relevant patterns for current work]
+
+**Health:** [OK / Issues found]
+
+## Recommended Next Step
+[Based on active plans and last session context]
+```
+
+## The Magic
+
+This feels like magic because the user just says "catch me up" and the agent:
+1. Knows what plans are active and where they stand
+2. Remembers what happened last session (even across context compactions)
+3. Shows what knowledge was recently captured
+4. Detects in-flight loops
+5. Recommends what to work on next
+
+No other tool does this — the agent has genuine persistent memory.
+
+## Agent Tools Reference
+
+| Op | When to Use |
+|----|-------------|
+| `plan_stats` | Find active plans |
+| `get_plan` | Load plan details |
+| `plan_list_tasks` | See task status within plan |
+| `memory_search` | Find session summaries |
+| `memory_list` | Browse recent memories |
+| `vault_recent` | Recently captured knowledge |
+| `loop_is_active` | Check for in-flight loops |
+| `loop_status` | Get loop details |
+| `brain_strengths` | Relevant proven patterns |
+| `admin_health` | System health check |

package/src/skills/executing-plans.md

@@ -0,0 +1,201 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+<!-- Adapted from superpowers (MIT License) -->
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+First, load the tracked plan from the agent:
+
+```
+YOUR_AGENT_core op:get_plan
+```
+
+List all tasks to understand scope:
+
+```
+YOUR_AGENT_core op:plan_list_tasks
+  params: { planId: "<id>" }
+```
+
+Check plan stats for an overview:
+
+```
+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
+
+### Step 2: Start Execution Loop
+
+For iterative tasks, start a validation loop:
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "<plan objective>", mode: "custom" }
+```
+
+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
+     params: { planId: "<id>", taskIndex: <n>, status: "in_progress" }
+   ```
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed:
+   ```
+   YOUR_AGENT_core op:update_task
+     params: { planId: "<id>", taskIndex: <n>, status: "completed" }
+   ```
+
+After each task, iterate the loop:
+
+```
+YOUR_AGENT_core op:loop_iterate
+```
+
+### Step 4: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Check loop status:
+  ```
+  YOUR_AGENT_core op:loop_status
+  ```
+- Say: "Ready for feedback."
+
+### Step 5: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 6: Complete Development
+
+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: {
+       planId: "<id>",
+       actualSteps: "<description of what was actually done>",
+       driftNotes: "<what differed from the plan>"
+     }
+   ```
+
+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>" }
+   ```
+
+6. Capture a session summary:
+   ```
+   YOUR_AGENT_core op:session_capture
+     params: { summary: "<what was built, key decisions, files modified>" }
+   ```
+
+## Capture Learnings During Execution
+
+If you discover something worth remembering during execution (a gotcha, a better approach, an anti-pattern):
+
+```
+YOUR_AGENT_core op:capture_quick
+  params: {
+    title: "<what you learned>",
+    description: "<context, why it matters, when it applies>"
+  }
+```
+
+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
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## 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
+- Between batches: just report and wait
+- Stop when blocked, don't guess
+- Capture learnings as you go, not just at the end
+- Always reconcile the plan after execution — drift data makes future plans better
+- Never start implementation on main/master branch without explicit user consent
+
+## 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 |
+
+## 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

@@ -0,0 +1,164 @@
+---
+name: fix-and-learn
+description: Use AFTER systematic-debugging completes to execute the fix and capture the learning in the vault. Invoke this skill when moving from diagnosis to repair for bugs, broken behavior, errors, regressions, or unexpected results. Chains with systematic-debugging — debugging finds root cause, this skill fixes and captures the anti-pattern.
+---
+
+# Fix & Learn — Debug, Repair, Capture
+
+Fix bugs through a structured recovery workflow, then capture the root cause as a reusable anti-pattern. The learning step is what makes fixes compound across sessions.
+
+## When to Use
+
+Any time something is broken, behaving unexpectedly, or producing errors. This includes runtime bugs, visual regressions, type errors, and "it used to work" situations.
+
+## The Search Order — MANDATORY
+
+**Never jump to writing code.** Always follow this lookup order:
+
+1. **Vault first** — has this been solved before?
+2. **Web search** — is there a known solution or pattern?
+3. **Plan the fix** — design the approach before touching code
+4. **Implement** — only after steps 1-3
+
+Skipping to implementation is the #1 cause of wasted time and recurring bugs.
+
+## Orchestration Sequence
+
+### Step 1: Classify and Route
+
+Classify the intent to confirm this is a FIX and get routing context:
+
+```
+YOUR_AGENT_core op:route_intent
+  params: { prompt: "<user's bug description>" }
+```
+
+### Step 2: Check Vault First
+
+Search for this bug or similar issues:
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<error message or bug description>" }
+```
+
+Check memory for patterns across sessions:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "<bug description>" }
+```
+
+Check memory topics — are bugs clustering in a specific area?
+
+```
+YOUR_AGENT_core op:memory_topics
+```
+
+Check memory stats to understand the debugging landscape:
+
+```
+YOUR_AGENT_core op:memory_stats
+```
+
+If vault returns a match with high confidence — **use it**. Don't re-investigate what's already been solved.
+
+### 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
+- Official documentation for the API or feature involved
+
+A 30-second web search can save hours of investigation.
+
+### Step 4: Start Fix Loop
+
+For complex bugs requiring multiple iterations, start a validation loop:
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "Fix: <bug description>", mode: "custom" }
+```
+
+### 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
+4. Implement the fix
+5. Verify the fix resolves the issue without regressions
+
+Track each iteration:
+
+```
+YOUR_AGENT_core op:loop_iterate
+```
+
+### Step 6: Validate the Fix
+
+Run the project's test suite to ensure the fix didn't introduce regressions. Use the verification-before-completion skill to confirm all checks pass.
+
+Complete the loop when validated:
+
+```
+YOUR_AGENT_core op:loop_complete
+```
+
+### Step 7: Capture the Learning
+
+This step is critical — it's what makes the agent smarter over time.
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<bug title>",
+    description: "<root cause, solution, what made it hard to find>",
+    type: "anti-pattern",
+    category: "<domain>",
+    tags: ["<error-type>", "<component>"]
+  }
+```
+
+For quick captures:
+```
+YOUR_AGENT_core op:capture_quick
+  params: { title: "<bug>", description: "<root cause and fix>" }
+```
+
+### Step 8: Post-Capture Quality
+
+Run duplicate detection to ensure we didn't create redundant entries:
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+### Step 9: Verify Health
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+## Exit Criteria
+
+Fix is complete when: the bug is resolved, tests pass (Step 6), and the root cause is captured in vault (Step 7). A fix without a capture is an incomplete fix.
+
+## 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 |