@soleri/forge 9.0.0 → 9.0.1

package/dist/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
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<what you're about to test>" }
+ernesto_core op:brain_strengths
+```
+
+If vault has testing guidance for this domain, follow it.
+
+## Start a TDD Loop
+
+```
+ernesto_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
+
+```
+ernesto_core op:loop_complete
+ernesto_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/dist/skills/vault-capture/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vault-capture
+description: Use when persisting a pattern, anti-pattern, workflow, decision, or principle to the knowledge base — after discovering something worth remembering.
+---
+
+# 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
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<knowledge title or description>" }
+ernesto_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
+
+```
+ernesto_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: `ernesto_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/dist/skills/vault-navigator/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: vault-navigator
+description: Use when querying the knowledge base for existing solutions, patterns, best practices, or prior art before building something new.
+---
+
+# 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"
+
+```
+ernesto_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)
+
+```
+ernesto_core op:vault_tags
+ernesto_core op:vault_domains
+ernesto_core op:vault_recent
+```
+
+### "What's stale?" / "What needs updating?"
+
+```
+ernesto_core op:vault_age_report
+```
+
+### "What do other projects do?"
+
+```
+ernesto_core op:memory_cross_project_search
+  params: { query: "<topic>", crossProject: true }
+ernesto_core op:project_linked_projects
+```
+
+### "Has brain learned about X?"
+
+```
+ernesto_core op:brain_strengths
+ernesto_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/dist/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing — before committing, creating PRs, or moving to the next task.
+---
+
+# 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:
+
+- `ernesto_core op:admin_health` — catches vault corruption, stale caches
+- `ernesto_core op:admin_diagnostic` — module status, database integrity, config validity
+- `ernesto_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: `ernesto_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/dist/skills/writing-plans/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: writing-plans
+description: Use when there is a spec or requirements for a multi-step task and an implementation plan needs to be written before touching code.
+---
+
+# 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
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<feature being planned>" }
+ernesto_core op:brain_strengths
+ernesto_core op:vault_domains
+ernesto_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
+
+```
+ernesto_core op:create_plan
+  params: {
+    objective: "<one-sentence goal>",
+    scope: { included: [...], excluded: [...] },
+    steps: [{ title: "Step 1", description: "details" }, ...]
+  }
+```
+
+## Grade and Improve
+
+```
+ernesto_core op:plan_grade params: { planId: "<id>" }
+ernesto_core op:plan_auto_improve params: { planId: "<id>" }
+ernesto_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: `ernesto_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
+
+```
+ernesto_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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soleri/forge",
-  "version": "9.0.0",
+  "version": "9.0.1",
   "description": "Scaffold AI agents that learn, remember, and grow with you.",
   "keywords": [
     "agent",

package/src/scaffold-filetree.ts

@@ -308,7 +308,22 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     writeFile(agentDir, `workflows/${wf.name}/tools.yaml`, wf.tools, filesCreated);
   }
 
-  // ─── 8. Write knowledge bundles (seed from starter packs if available) ──
+  // ─── 8. Copy bundled skills ─────────────────────────────────
+  const skillsSrcDir = join(dirname(fileURLToPath(import.meta.url)), 'skills');
+  if (existsSync(skillsSrcDir)) {
+    const skillDirs = readdirSync(skillsSrcDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+    for (const skillName of skillDirs) {
+      const skillFile = join(skillsSrcDir, skillName, 'SKILL.md');
+      if (existsSync(skillFile)) {
+        mkdirSync(join(agentDir, 'skills', skillName), { recursive: true });
+        writeFile(agentDir, `skills/${skillName}/SKILL.md`, readFileSync(skillFile, 'utf-8'), filesCreated);
+      }
+    }
+  }
+
+  // ─── 9. Write knowledge bundles (seed from starter packs if available) ──
   const starterPacksDir = resolveStarterPacksDir();
   let totalSeeded = 0;
 

package/src/skills/brain-debrief/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: brain-debrief
+description: Use when the user wants to see accumulated knowledge, pattern strengths, cross-project insights, learning velocity, or an intelligence report from the brain.
+---
+
+# Brain Debrief — Intelligence Report
+
+Surface what the brain has learned across sessions and projects. Turns raw vault data into actionable intelligence.
+
+## Orchestration by Query Type
+
+### "What have I learned?" (General debrief)
+
+1. `ernesto_core op:brain_stats` — total sessions, patterns, quality scores
+2. `ernesto_core op:brain_strengths` — patterns ranked by strength (focus >= 70)
+3. `ernesto_core op:memory_topics` — knowledge clusters
+4. `ernesto_core op:vault_age_report` — stale entries needing refresh
+5. `ernesto_core op:curator_health_audit` — vault quality score
+
+Present: top 5 patterns, top 3 anti-patterns, stale entries, coverage gaps.
+
+### "What's working across projects?" (Cross-project)
+
+1. `ernesto_core op:brain_global_patterns` — promoted patterns
+2. `ernesto_core op:brain_recommend params: { projectName: "<project>" }` — similarity-based recommendations
+3. `ernesto_core op:project_linked_projects` — connected projects
+4. `ernesto_core op:memory_cross_project_search params: { query: "<topic>", crossProject: true }`
+
+### "Am I getting smarter?" (Learning velocity)
+
+Compare `brain_stats` for 7-day vs 30-day periods. Check `memory_stats`, `admin_vault_analytics`, `admin_search_insights`. Present: new patterns, strength changes, growing vs stagnant domains.
+
+### "Build fresh intelligence" (Rebuild)
+
+1. `ernesto_core op:brain_build_intelligence` — full pipeline rebuild
+2. `ernesto_core op:curator_consolidate` — vault cleanup
+3. Show updated `brain_stats`
+
+### "Export what I know" (Portability)
+
+Use `brain_export`, `memory_export`, `vault_backup`. Import with corresponding `_import` ops.
+
+## Presenting Intelligence
+
+Format as a report with: Strengths, Risks (recurring anti-patterns), Gaps, Stale entries, Quality score, Recommendations, Search Misses.
+
+## Common Mistakes
+
+- Presenting raw tool output instead of synthesized insights
+- Skipping the stale entry check (vault_age_report)
+- Not comparing periods when reporting learning velocity
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `brain_stats` | Aggregate metrics |
+| `brain_strengths` | Proven patterns ranked |
+| `brain_global_patterns` | Cross-project patterns |
+| `brain_recommend` | Project-similarity recommendations |
+| `brain_build_intelligence` | Rebuild intelligence pipeline |
+| `memory_topics` / `memory_stats` | Knowledge clusters and health |
+| `vault_age_report` | Stale entries |
+| `curator_health_audit` | Vault quality score |
+| `admin_vault_analytics` | Knowledge quality metrics |
+| `admin_search_insights` | Search miss analysis |

package/src/skills/brainstorming/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: brainstorming
+description: Use when creating features, building components, adding functionality, or modifying behavior — explores intent and design before implementation.
+---
+
+# Brainstorming Ideas Into Designs
+
+Turn ideas into fully formed designs through collaborative dialogue. Understand project context, ask questions one at a time, present a design, get approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Checklist
+
+Complete in order:
+
+1. **Classify intent** — `ernesto_core op:route_intent`
+2. **Search vault for prior art** — `ernesto_core op:search_intelligent`
+3. **Search web for existing solutions** — don't build what already exists
+4. **Explore project context** — check files, docs, recent commits
+5. **Ask clarifying questions** — one at a time, purpose/constraints/success criteria
+6. **Propose 2-3 approaches** — with trade-offs and your recommendation
+7. **Present design** — in sections scaled to complexity, get approval after each
+8. **Capture design decision** — persist to vault
+9. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
+10. **Transition** — invoke writing-plans skill (the ONLY next skill)
+
+## Search Before Designing
+
+### Vault First
+
+```
+ernesto_core op:search_intelligent
+  params: { query: "<the feature or idea>" }
+```
+
+Also check: `op:vault_tags`, `op:vault_domains`, `op:brain_strengths`, `op:memory_cross_project_search` with `crossProject: true`.
+
+### Web Search Second
+
+If vault has no prior art, search web for existing libraries, reference implementations, best practices, known pitfalls.
+
+Present findings: "Before we design this, here's what I found..."
+
+## The Process
+
+- **Understanding**: Check project state, ask one question per message, prefer multiple choice
+- **Exploring**: Propose 2-3 approaches, lead with recommendation, reference vault patterns and web findings
+- **Presenting**: Scale each section to complexity, ask after each section, cover architecture/components/data flow/error handling/testing
+
+## After the Design
+
+**Capture the decision:**
+
+```
+ernesto_core op:capture_knowledge
+  params: {
+    title: "<feature> — design decision",
+    description: "<chosen approach, rationale, rejected alternatives>",
+    type: "decision",
+    category: "<domain>",
+    tags: ["design-decision"]
+  }
+```
+
+Write validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit. Then invoke writing-plans.
+
+## Common Mistakes
+
+- Skipping vault search and reinventing solved problems
+- Jumping to implementation without design approval
+- Asking multiple questions per message (overwhelming)
+- Treating "simple" projects as too simple to need a design
+
+## Quick Reference
+
+| Op | When to Use |
+|----|-------------|
+| `route_intent` | Classify work type |
+| `search_intelligent` | Search vault for prior art |
+| `vault_tags` / `vault_domains` | Browse knowledge landscape |
+| `brain_strengths` | Check proven patterns |
+| `memory_cross_project_search` | Check other projects |
+| `capture_knowledge` | Persist design decision |