@soleri/forge 9.0.0 → 9.2.0

package/src/skills/test-driven-development/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: test-driven-development
+description: Use when implementing any feature or bugfix — write failing tests before implementation code.
+---
+
+# Test-Driven Development (TDD)
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+## Before You Start — Search First
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<what you're about to test>" }
+YOUR_AGENT_core op:brain_strengths
+```
+
+If vault has testing guidance for this domain, follow it.
+
+## Start a TDD Loop
+
+```
+YOUR_AGENT_core op:loop_start
+  params: { prompt: "TDD: <feature>", mode: "custom" }
+```
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? Delete it. Start over. No exceptions.
+
+## Red-Green-Refactor
+
+### RED — Write Failing Test
+
+One behavior, clear name, real code (no mocks unless unavoidable). Run test, confirm it **fails** for the expected reason (feature missing, not typos). Track: `op:loop_iterate`.
+
+### GREEN — Minimal Code
+
+Simplest code to pass the test. Don't add features beyond the test. Run test, confirm it **passes** and other tests still pass. Track: `op:loop_iterate`.
+
+### REFACTOR — Clean Up
+
+After green only: remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior.
+
+### Repeat
+
+Next failing test for next behavior.
+
+## Verification Checklist
+
+- [ ] Every new function has a test
+- [ ] Watched each test fail before implementing
+- [ ] Failed for expected reason (not typo)
+- [ ] Wrote minimal code to pass
+- [ ] All tests pass, output pristine
+- [ ] Mocks only where unavoidable
+- [ ] Edge cases and errors covered
+
+## After TDD
+
+```
+YOUR_AGENT_core op:loop_complete
+YOUR_AGENT_core op:capture_quick
+  params: { title: "<testing pattern>", description: "<what you learned>" }
+```
+
+## Common Mistakes
+
+- Writing implementation before tests ("I'll test after")
+- Keeping pre-test code as "reference" (delete means delete)
+- Test passes immediately (testing existing behavior, not new)
+- Multiple behaviors in one test ("and" in name means split it)
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API first |
+| Must mock everything | Code too coupled — use DI |
+| Test setup huge | Extract helpers or simplify design |
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Find testing patterns |
+| `brain_strengths` | Proven testing approaches |
+| `loop_start` / `loop_iterate` / `loop_complete` | TDD cycle tracking |
+| `capture_quick` | Capture new testing patterns |

package/src/skills/vault-capture/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: vault-capture
+description: >
+  Use to capture a SINGLE known pattern, anti-pattern, workflow, decision, or principle to the
+  vault. Triggers on "save this", "capture this", "remember this pattern", "add to vault". The
+  user already knows what to capture. For bulk extraction from documents, code, or PRs, use
+  knowledge-harvest instead.
+---
+
+# Vault Capture — Persist Knowledge
+
+Capture patterns, anti-patterns, workflows, and principles to the vault. Captured knowledge compounds — it informs future searches, brain recommendations, and team reviews.
+
+## Steps
+
+### 1. Check for Duplicates
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<knowledge title or description>" }
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+If similar entry exists, update it instead of creating a duplicate.
+
+### 2. Classify the Knowledge
+
+| Type | Description |
+|------|-------------|
+| **pattern** | Works and should be repeated |
+| **anti-pattern** | Fails and should be avoided |
+| **workflow** | Steps for a specific task |
+| **principle** | Guiding rule or heuristic |
+| **decision** | Architectural choice with rationale |
+
+### 3. Capture
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<clear, searchable name>",
+    description: "<what it is and when it applies>",
+    type: "<pattern|anti-pattern|workflow|principle|decision>",
+    category: "<domain>",
+    tags: ["<tag1>", "<tag2>"],
+    example: "<code or before/after>",
+    why: "<reasoning>"
+  }
+```
+
+For quick captures: `YOUR_AGENT_core op:capture_quick params: { title: "<name>", description: "<details>" }`
+
+### 4. Post-Capture Quality
+
+- `op:curator_groom params: { entryId: "<id>" }` — normalize tags
+- `op:curator_enrich params: { entryId: "<id>" }` — LLM enrichment
+- `op:curator_contradictions` — check for conflicts
+
+### 5. Governance (if enabled)
+
+If capture returns a `proposalId`, entry is queued: `op:governance_proposals params: { action: "list" }`.
+
+### 6. Promote to Global (Optional)
+
+For cross-project knowledge: `op:memory_promote_to_global params: { entryId: "<id>" }`.
+
+### 7. Verify
+
+`op:admin_health` and `op:admin_vault_analytics` to confirm storage and quality.
+
+## Common Mistakes
+
+- Not checking for duplicates before capturing
+- Missing the `why` field (makes entries not actionable)
+- Skipping post-capture grooming (tags stay unnormalized)
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Check for duplicates |
+| `capture_knowledge` / `capture_quick` | Persist to vault |
+| `curator_groom` / `curator_enrich` | Post-capture quality |
+| `curator_contradictions` | Find conflicts |
+| `memory_promote_to_global` | Share cross-project |
+| `admin_health` | Verify health |

package/src/skills/vault-navigator/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: vault-navigator
+description: >
+  Use when the user asks "search the vault", "find patterns for", "have we seen this before",
+  "what does the vault say about", "best practice for", "check vault", "vault search", or wants
+  to query the knowledge base for existing solutions and prior art. For saving a new entry, use
+  vault-capture instead.
+---
+
+# Vault Navigator — Knowledge Oracle
+
+Navigate the vault intelligently. Picks the right search strategy based on what the user needs.
+
+## Search Strategy Decision Tree
+
+### "Have we seen this?" / "Best practice for X"
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<question>" }
+```
+
+If results are weak, fall back to `op:search` with explicit filters (type, category, tags, severity).
+
+### "Show me everything about X" (Exploration)
+
+```
+YOUR_AGENT_core op:vault_tags
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_recent
+```
+
+### "What's stale?" / "What needs updating?"
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+### "What do other projects do?"
+
+```
+YOUR_AGENT_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+YOUR_AGENT_core op:project_linked_projects
+```
+
+### "Has brain learned about X?"
+
+```
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:brain_global_patterns
+  params: { domain: "<domain>" }
+```
+
+### Broad exploration ("What do I know about X?")
+
+Chain: `search_intelligent` -> `vault_tags` / `vault_domains` -> `memory_cross_project_search` -> `brain_strengths`. Label each finding with its source.
+
+## Presenting Results
+
+Always include: **Source** (vault/memory/brain), **Confidence** (score), **Relevance** (why it matches), **Next step** (how to apply).
+
+## Fallback: Web Search
+
+If all vault strategies return nothing, search the web. If web finds something useful, offer to capture: `op:capture_quick`.
+
+## Common Mistakes
+
+- Using only one search strategy instead of trying multiple
+- Not labeling result sources (user can't judge confidence)
+- Saying "nothing found" without trying web search fallback
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Default semantic search |
+| `search` | Structured search with filters |
+| `vault_tags` / `vault_domains` | Browse knowledge landscape |
+| `vault_recent` | Recently modified entries |
+| `vault_age_report` | Stale entries |
+| `memory_cross_project_search` | Cross-project search |
+| `brain_strengths` / `brain_global_patterns` | Proven patterns |
+| `capture_quick` | Capture web findings |

package/src/skills/vault-smells/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: vault-smells
+description: >
+  Use for deep knowledge quality analysis — finding contradictions, stale patterns, orphaned entries,
+  weak links, knowledge decay, and structural issues in the vault. Triggers on "vault smells",
+  "knowledge quality", "vault analysis", "find contradictions", "stale patterns", "knowledge debt",
+  "vault deep check", "is my vault healthy". Goes deeper than health-check (which is operational).
+  For code review, use deep-review instead.
+---
+
+# Vault Smells — Knowledge Quality Deep Analysis
+
+Detects structural problems in the knowledge base that degrade decision quality over time. Goes beyond operational health (is the DB up?) into knowledge integrity (is the knowledge trustworthy?).
+
+## Smell Categories
+
+### 1. Contradiction Smells
+
+Entries that give conflicting guidance. The most dangerous smell — leads to inconsistent decisions.
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+**What to look for:**
+- Two patterns that recommend opposite approaches for the same situation
+- An anti-pattern that contradicts an active pattern
+- Entries from different time periods with conflicting advice (the older one may be stale)
+
+**Resolution:** Present contradictions to user. One must win — archive the loser or scope them to different contexts.
+
+### 2. Staleness Smells
+
+Knowledge that was true once but may not be anymore.
+
+```
+YOUR_AGENT_core op:vault_age_report
+```
+
+**Indicators:**
+- Entries >60 days without access or update
+- Patterns referencing APIs, libraries, or versions that have changed
+- Entries tagged with technologies the project no longer uses
+- Confidence scores that haven't been reinforced by brain feedback
+
+**Action:** Flag for review. Don't auto-delete — stale doesn't mean wrong.
+
+### 3. Orphan Smells
+
+Entries with no connections to the rest of the knowledge graph.
+
+```
+YOUR_AGENT_core op:admin_vault_analytics
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Indicators:**
+- Entries with zero inbound or outbound links
+- Entries never returned in search results (check search insights)
+- Entries with no tags or only generic tags
+- Entries that were captured but never groomed
+
+**Why it matters:** Orphans don't surface when needed. They're knowledge that exists but can't be found. In a Zettelkasten, an unlinked note is a dead note.
+
+**Action:** Link, merge, or archive. Every entry should connect to at least one other.
+
+### 4. Duplication Smells
+
+Multiple entries covering the same ground with slight variations.
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+**Indicators:**
+- High similarity scores between entries
+- Same tags and category but different titles
+- Entries captured in different sessions about the same topic
+- Parallel entries — one as pattern, one as anti-pattern for the same concept
+
+**Action:** Merge the best parts into one authoritative entry. Archive the rest.
+
+### 5. Shallow Entry Smells
+
+Entries that exist but lack substance — captured in a hurry, never enriched.
+
+```
+YOUR_AGENT_core op:curator_health_audit
+```
+
+**Indicators:**
+- Description under 50 characters
+- No examples or context
+- Missing "why" — only states "what" without rationale
+- No tags beyond the auto-generated ones
+- Quality score below 40
+
+**Action:** Enrich with context, examples, and rationale — or archive if no longer relevant.
+
+### 6. Category Drift Smells
+
+The taxonomy has grown inconsistent over time.
+
+```
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+```
+
+**Indicators:**
+- Near-duplicate categories (e.g., "error-handling" and "errors" and "exception-handling")
+- Categories with only 1-2 entries (too granular)
+- Tags used inconsistently (same concept, different tag names)
+- Entries miscategorized (architecture pattern filed under "testing")
+
+**Action:** Normalize with `op:curator_groom_all`. Merge overlapping categories.
+
+### 7. Confidence Decay Smells
+
+Brain patterns losing strength without reinforcement.
+
+```
+YOUR_AGENT_core op:brain_strengths
+```
+
+**Indicators:**
+- Patterns with high initial strength that have decayed below 0.3
+- Patterns that were strong but haven't received positive feedback in >30 days
+- Patterns with mixed feedback (both positive and negative) — unresolved
+
+**Action:** Review with user. Reinforce valid patterns, retire invalid ones.
+
+### 8. Knowledge Gap Smells
+
+Areas where the vault *should* have knowledge but doesn't.
+
+```
+YOUR_AGENT_core op:admin_search_insights
+```
+
+**Indicators:**
+- Repeated search queries that return no results
+- Domains the project uses but vault has no entries for
+- Anti-patterns captured without corresponding patterns (what to do instead?)
+- Patterns without linked anti-patterns (what to avoid?)
+
+**Action:** Create targeted entries to fill gaps. Use knowledge-harvest skill on relevant docs/code.
+
+## Running the Analysis
+
+### Step 1: Gather Data
+
+```
+YOUR_AGENT_core op:admin_health
+YOUR_AGENT_core op:admin_vault_analytics
+YOUR_AGENT_core op:curator_health_audit
+YOUR_AGENT_core op:curator_contradictions
+YOUR_AGENT_core op:curator_detect_duplicates
+YOUR_AGENT_core op:vault_age_report
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:admin_search_insights
+```
+
+### Step 2: Classify Smells
+
+For each smell category, assess severity:
+
+| Severity | Meaning |
+|----------|---------|
+| 🟢 Clean | No issues in this category |
+| 🟡 Minor | 1-3 instances, low impact |
+| 🟠 Moderate | Multiple instances, degrading quality |
+| 🔴 Critical | Widespread, actively causing bad decisions |
+
+### Step 3: Present the Report
+
+```
+## Vault Smell Report
+
+### Overview
+| Metric | Value |
+|--------|-------|
+| Total entries | X |
+| Overall health score | X/100 |
+| Smells found | X across Y categories |
+
+### Smell Summary
+| Category | Severity | Count | Impact |
+|----------|----------|-------|--------|
+| Contradictions | 🔴/🟠/🟡/🟢 | X | Inconsistent decisions |
+| Staleness | 🔴/🟠/🟡/🟢 | X | Outdated guidance |
+| Orphans | 🔴/🟠/🟡/🟢 | X | Unfindable knowledge |
+| Duplicates | 🔴/🟠/🟡/🟢 | X | Noise, conflicting versions |
+| Shallow entries | 🔴/🟠/🟡/🟢 | X | Low-value knowledge |
+| Category drift | 🔴/🟠/🟡/🟢 | X | Poor discoverability |
+| Confidence decay | 🔴/🟠/🟡/🟢 | X | Unreliable recommendations |
+| Knowledge gaps | 🔴/🟠/🟡/🟢 | X | Blind spots |
+
+### Critical Findings
+[Top 3 most impactful issues with specific entries/examples]
+
+### Recommended Actions
+| Priority | Action | Effort | Impact |
+|----------|--------|--------|--------|
+| 1 | [most impactful fix] | Low/Med/High | High |
+| 2 | [second] | Low/Med/High | Med |
+| 3 | [third] | Low/Med/High | Med |
+
+### Trend (if prior reports exist)
+| Metric | Last Check | Now | Direction |
+|--------|-----------|-----|-----------|
+| Health score | X | Y | ↑/↓/→ |
+| Smell count | X | Y | ↑/↓/→ |
+```
+
+### Step 4: Fix (with user approval)
+
+Do NOT auto-fix. Present findings, get approval, then:
+
+- Contradictions → `op:curator_resolve_contradiction`
+- Duplicates → `op:curator_groom` (merge)
+- Orphans → link or archive
+- Shallow entries → enrich or archive
+- Category drift → `op:curator_groom_all` (normalize)
+- Gaps → `op:capture_knowledge` (fill)
+
+After fixes: `op:brain_build_intelligence` to rebuild with clean data.
+
+## Common Mistakes
+
+- Auto-fixing without presenting findings first (user may disagree)
+- Treating all smells as equally urgent (contradictions >> orphans)
+- Deleting stale entries without checking if they're still valid
+- Running this too frequently (monthly is usually enough)
+- Not rebuilding brain intelligence after major cleanup
+
+## Quick Reference
+
+| Smell | Detection Op | Fix Op |
+|-------|-------------|--------|
+| Contradictions | `curator_contradictions` | `curator_resolve_contradiction` |
+| Staleness | `vault_age_report` | Review + archive/update |
+| Orphans | `admin_vault_analytics` | Link or archive |
+| Duplicates | `curator_detect_duplicates` | `curator_groom` (merge) |
+| Shallow entries | `curator_health_audit` | Enrich or archive |
+| Category drift | `vault_domains` + `vault_tags` | `curator_groom_all` |
+| Confidence decay | `brain_strengths` | Reinforce or retire |
+| Knowledge gaps | `admin_search_insights` | `capture_knowledge` |
+
+**Related skills:** health-check (operational status), vault-curate (active cleanup), knowledge-harvest (fill gaps)

package/src/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: verification-before-completion
+description: >
+  Use as an internal quality gate before claiming any task is done — run tests, check output,
+  verify behavior. This is a mid-workflow checkpoint, not a shipping gate. For actual deployment
+  and release workflows, use deliver-and-ship instead.
+---
+
+# Verification Before Completion
+
+**Core principle:** Evidence before claims, always.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - NO → State actual status with evidence
+   - YES → State claim WITH evidence
+5. AGENT CHECK: Run system diagnostics
+6. ONLY THEN: Make the claim
+```
+
+## Agent System Checks
+
+After passing verification commands:
+
+- `YOUR_AGENT_core op:admin_health` — catches vault corruption, stale caches
+- `YOUR_AGENT_core op:admin_diagnostic` — module status, database integrity, config validity
+- `YOUR_AGENT_core op:admin_vault_analytics` — knowledge quality metrics
+
+If any check reports problems, address before claiming completion.
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test output: 0 failures | Previous run, "should pass" |
+| Build succeeds | Build command: exit 0 | Linter passing |
+| Bug fixed | Original symptom passes | "Code changed, assumed fixed" |
+| Requirements met | Line-by-line checklist | Tests passing alone |
+
+## Red Flags — STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification
+- About to commit/push/PR without verification
+- Relying on partial verification
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence is not evidence |
+| "Just this once" | No exceptions |
+| "Partial check is enough" | Partial proves nothing |
+
+## After Verification
+
+Capture session summary: `YOUR_AGENT_core op:session_capture params: { summary: "<what was accomplished>" }`
+
+## Common Mistakes
+
+- Claiming "tests pass" based on a previous run
+- Trusting agent success reports without independent verification
+- Running linter but not build (linter does not check compilation)
+- Skipping the red-green cycle for regression tests
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `admin_health` | Quick system health check |
+| `admin_diagnostic` | Comprehensive diagnostic |
+| `admin_vault_analytics` | Knowledge quality metrics |
+| `session_capture` | Persist verified completion context |

package/src/skills/writing-plans/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: writing-plans
+description: >
+  Use when the user has clear requirements or a spec and needs a structured implementation plan —
+  "create a plan", "break this down", "plan the implementation". Requirements are already known.
+  For open-ended exploration when requirements are unclear, use brainstorming instead.
+---
+
+# Writing Plans
+
+Write implementation plans assuming the engineer has zero codebase context. Document everything: which files to touch, code, testing, expected output. Bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Before Writing — Search First
+
+### 1. Vault First
+
+```
+YOUR_AGENT_core op:search_intelligent
+  params: { query: "<feature being planned>" }
+YOUR_AGENT_core op:brain_strengths
+YOUR_AGENT_core op:vault_domains
+YOUR_AGENT_core op:vault_tags
+```
+
+### 2. Web Search Second
+
+If vault lacks guidance: libraries, reference implementations, API docs, known pitfalls.
+
+### 3. Then Write the Plan
+
+Incorporate vault insights and web findings. Reference specific entries.
+
+## Create a Tracked Plan
+
+```
+YOUR_AGENT_core op:create_plan
+  params: {
+    objective: "<one-sentence goal>",
+    scope: { included: [...], excluded: [...] },
+    steps: [{ title: "Step 1", description: "details" }, ...]
+  }
+```
+
+## Grade and Improve
+
+```
+YOUR_AGENT_core op:plan_grade params: { planId: "<id>" }
+YOUR_AGENT_core op:plan_auto_improve params: { planId: "<id>" }
+YOUR_AGENT_core op:plan_meets_grade params: { planId: "<id>", targetGrade: "A" }
+```
+
+Iterate with: `op:plan_iterate params: { planId: "<id>", feedback: "<improvement>" }`
+
+## Split into Tasks
+
+After approval: `YOUR_AGENT_core op:plan_split params: { planId: "<id>" }`
+
+## Task Granularity
+
+Each step is one action (2-5 minutes): write failing test, run it, implement, run tests, commit.
+
+## Plan Document Header
+
+```markdown
+# [Feature] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task.
+
+**Goal:** [One sentence]
+**Architecture:** [2-3 sentences]
+**Tech Stack:** [Key technologies]
+```
+
+## Task Structure
+
+- Files: Create / Modify / Test paths
+- Steps: Write failing test (code) -> verify fail (expected output) -> implement (code) -> verify pass (expected output) -> commit (exact commands)
+
+## After Approval
+
+```
+YOUR_AGENT_core op:approve_plan params: { planId: "<id>" }
+```
+
+Offer execution choice: subagent-driven (this session) or parallel session with executing-plans.
+
+## Common Mistakes
+
+- Writing plans from scratch without searching vault first
+- Vague steps like "add validation" instead of exact code
+- Missing test steps in the plan
+- Not grading the plan before presenting to user
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `search_intelligent` | Find patterns before planning |
+| `brain_strengths` | Proven approaches |
+| `create_plan` | Create tracked plan |
+| `plan_grade` / `plan_auto_improve` | Grade and improve |
+| `plan_iterate` | Iterate with feedback |
+| `plan_split` | Split into tasks |
+| `approve_plan` | Lock in approved plan |