@soleri/forge 9.3.1 → 9.4.0

package/dist/templates/clean-worktrees.js

@@ -0,0 +1,59 @@
+/**
+ * Generate a POSIX sh script that cleans up stale Claude Code worktrees.
+ * Registered as a SessionStart hook in scaffolded agents.
+ */
+export function generateCleanWorktreesScript() {
+    return `#!/bin/sh
+# Clean stale Claude Code worktrees on session start.
+# Registered as a SessionStart hook by Soleri scaffolding.
+# Safe: skips active worktrees, checks for unpushed commits.
+
+WORKTREE_DIR=".claude/worktrees"
+
+# Exit silently if no worktrees directory
+[ -d "$WORKTREE_DIR" ] || exit 0
+
+# Prune worktrees whose branches have been deleted
+git worktree prune 2>/dev/null
+
+# Get list of active worktrees (skip the main one)
+active_worktrees="$(git worktree list --porcelain 2>/dev/null | grep '^worktree ' | sed 's/^worktree //')"
+
+cleaned=0
+skipped=0
+
+for dir in "$WORKTREE_DIR"/*/; do
+  [ -d "$dir" ] || continue
+
+  # Resolve to absolute path for comparison
+  abs_dir="$(cd "$dir" 2>/dev/null && pwd)" || continue
+
+  # Skip if still in git worktree list (active)
+  if echo "$active_worktrees" | grep -qF "$abs_dir"; then
+    skipped=$((skipped + 1))
+    continue
+  fi
+
+  # Safety: check for unpushed commits before removing
+  branch="$(git -C "$dir" rev-parse --abbrev-ref HEAD 2>/dev/null)" || branch=""
+  if [ -n "$branch" ] && [ "$branch" != "HEAD" ]; then
+    upstream="$(git -C "$dir" rev-parse --abbrev-ref "@{upstream}" 2>/dev/null)" || upstream=""
+    if [ -n "$upstream" ]; then
+      unpushed="$(git -C "$dir" log "$upstream..$branch" --oneline 2>/dev/null)"
+      if [ -n "$unpushed" ]; then
+        skipped=$((skipped + 1))
+        continue
+      fi
+    fi
+  fi
+
+  rm -rf "$dir" 2>/dev/null && cleaned=$((cleaned + 1))
+done
+
+# Silent unless something was cleaned
+if [ "$cleaned" -gt 0 ]; then
+  echo "Cleaned $cleaned stale worktree(s), $skipped active/protected"
+fi
+`;
+}
+//# sourceMappingURL=clean-worktrees.js.map

package/dist/templates/clean-worktrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-worktrees.js","sourceRoot":"","sources":["../../src/templates/clean-worktrees.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,4BAA4B;IAC1C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDR,CAAC;AACF,CAAC"}

package/dist/templates/setup-script.js

@@ -50,11 +50,18 @@ if [ ! -f "$SETTINGS_FILE" ]; then
         "type": "prompt",
         "prompt": "Before context is compacted, capture a session summary by calling ${config.id}_core op:session_capture with a brief summary of what was accomplished, the topics covered, files modified, and tools used."
       }
+    ],
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "sh $AGENT_DIR/scripts/clean-worktrees.sh",
+        "timeout": 10
+      }
     ]
   }
 }
 SETTINGS
-  echo "[ok] Created $SETTINGS_FILE with PreCompact hook"
+  echo "[ok] Created $SETTINGS_FILE with PreCompact + SessionStart hooks"
 else
   if grep -q "PreCompact" "$SETTINGS_FILE" 2>/dev/null; then
     echo "[ok] PreCompact hook already configured — skipping"
@@ -72,6 +79,24 @@ else
     "
     echo "[ok] Added PreCompact hook to $SETTINGS_FILE"
   fi
+  # Add SessionStart worktree cleanup hook
+  if grep -q "clean-worktrees" "$SETTINGS_FILE" 2>/dev/null; then
+    echo "[ok] SessionStart worktree cleanup hook already configured"
+  else
+    node -e "
+      const fs = require('fs');
+      const settings = JSON.parse(fs.readFileSync('$SETTINGS_FILE', 'utf-8'));
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+      settings.hooks.SessionStart.push({
+        type: 'command',
+        command: 'sh $AGENT_DIR/scripts/clean-worktrees.sh',
+        timeout: 10
+      });
+      fs.writeFileSync('$SETTINGS_FILE', JSON.stringify(settings, null, 2) + '\\n');
+    "
+    echo "[ok] Added SessionStart worktree cleanup hook"
+  fi
 fi
 
 # Install skills to ~/.claude/commands/

package/dist/templates/setup-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup-script.js","sourceRoot":"","sources":["../../src/templates/setup-script.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup-script.js","sourceRoot":"","sources":["../../src/templates/setup-script.ts"],"names":[],"mappings":"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"}

package/dist/templates/shared-rules.js

@@ -105,6 +105,19 @@ const ENGINE_RULES_LINES = [
     '- Persist lessons: capture + link. An unlinked entry is incomplete.',
     '- Exceptions: runtime errors with stack traces → codebase first; user explicitly asks to search web.',
     '',
+    '### Vault Search Strategy',
+    '',
+    "Default to **two-pass search** — scan first, load only what's relevant. This saves tokens and keeps context lean.",
+    '',
+    '| Situation | Strategy |',
+    '|-----------|----------|',
+    '| Broad/exploratory query | `mode: "scan"` → triage by score → `op:load_entries` for top matches |',
+    '| Specific known entry | `mode: "full"` directly |',
+    '| Work task (need vault context before coding) | Scan → pick relevant → load |',
+    '| Existence check ("do we have X?") | `mode: "scan"` only, no load needed |',
+    '',
+    '**Never load all scan results.** Pick the top 2-4 by relevance score and skip entries below 0.30 unless the query is very specific.',
+    '',
     // ─── Planning ────────────────────────────────────────────
     '## Planning',
     '<!-- soleri:planning -->',
@@ -199,6 +212,37 @@ const ENGINE_RULES_LINES = [
     '| skipped | ... | medium | ... |',
     '```',
     '',
+    // ─── YOLO Mode ──────────────────────────────────────────
+    '## YOLO Mode',
+    '<!-- soleri:yolo-mode -->',
+    '',
+    'YOLO mode skips plan approval gates for faster execution. The agent executes tasks directly without waiting for Gate 1 (`op:approve_plan`) or Gate 2 (`op:plan_split`) confirmation.',
+    '',
+    '### What Changes',
+    '',
+    '- Plan approval gates are **auto-approved** — no user confirmation needed.',
+    '- Task routing skips the two-gate ceremony — plans are created, approved, and split in one pass.',
+    '',
+    '### What Does NOT Change',
+    '',
+    '- `op:orchestrate_complete` **always runs** — knowledge capture is never skipped.',
+    '- Vault search **always runs** — decisions must be informed by existing patterns.',
+    '- Brain feedback loop remains active.',
+    '- Grade gate still applies — plans must grade A or higher.',
+    '',
+    '### Prerequisites',
+    '',
+    '- **YOLO Safety Hook Pack** must be installed: `soleri hooks add-pack yolo-safety`',
+    '- The hook pack intercepts destructive commands (force push, reset --hard, drop table) and requires explicit confirmation.',
+    '- Staging backups are created before destructive operations.',
+    '',
+    '### Activation & Deactivation',
+    '',
+    '| Action | Method |',
+    '|--------|--------|',
+    '| Activate | `soleri yolo` or `op:morph params:{ mode: "YOLO-MODE" }` |',
+    '| Deactivate | "exit YOLO", session end, or `op:activate params:{ deactivate: true }` |',
+    '',
     // ─── Output Formatting ───────────────────────────────────
     '## Output Formatting',
     '<!-- soleri:output-formatting -->',
@@ -285,7 +329,7 @@ const ENGINE_RULES_LINES = [
     '`op:orchestrate_complete` runs for EVERY task — simple or complex. This captures:',
     '- Knowledge to vault (patterns learned, decisions made)',
     '- Session summary (what was done, files changed)',
-    '- Brain feedback (what worked, what didn\'t)',
+    "- Brain feedback (what worked, what didn't)",
     '',
     'Without completion, the knowledge trail is lost. The code is in git, but the WHY disappears.',
     '',
@@ -333,6 +377,36 @@ const ENGINE_RULES_LINES = [
     '- Brain tells you **which** patterns matter (names + strength scores). Vault tells you **what** they are (rules, examples).',
     "- Pull only what's relevant to the current task — don't load everything at session start.",
     '',
+    '### Second Brain Features',
+    '',
+    '| Feature | How to use |',
+    '|---------|-----------|',
+    '| **Two-pass search** | `op:search_intelligent` with `mode: "scan"` for lightweight results, then `op:load_entries` for full content. See **Vault Search Strategy**. |',
+    '| **Session briefing** | `op:session_briefing` on session start — surfaces last session, active plans, recent captures, brain recommendations |',
+    '| **Evidence reconciliation** | `op:plan_reconcile_with_evidence` — cross-references plan tasks against git diff |',
+    '| **Learning radar** | `op:radar_analyze` to detect patterns from corrections, search misses, workarounds. `op:radar_candidates` to review, `op:radar_approve`/`op:radar_dismiss` |',
+    '| **External ingestion** | `op:ingest_url` for articles, `op:ingest_text` for transcripts/notes, `op:ingest_batch` for multiple items |',
+    '| **Content synthesis** | `op:synthesize` — turn vault knowledge into briefs, outlines, talking points, or post drafts |',
+    '| **Skill chains** | `op:chain_execute` — multi-step workflows with data flow between steps and approval gates |',
+    '',
+    '### Brain Feedback Loop',
+    '',
+    'After using a vault search result to inform a decision, action, or response, call `op:record_feedback` with:',
+    '- `query`: the original search query',
+    '- `entryId`: the vault entry ID that was used',
+    '- `action`: "accepted" (result was useful) or "rejected" (result was irrelevant/wrong)',
+    '- `confidence`: 0.0–1.0 how relevant the result was to the task',
+    '',
+    'Do this for:',
+    '- `search_intelligent` results that influence your next action',
+    '- `orchestrate_plan` vault recommendations you follow',
+    '- Vault entries you cite or reference in responses',
+    '',
+    'Do NOT record feedback for:',
+    '- Existence checks ("do we have X?" — just scanning, not using)',
+    "- Results you browse but don't act on",
+    '- Duplicate feedback for the same entry in the same task',
+    '',
     // ─── Cross-Project Memory ────────────────────────────────
     '## Cross-Project Memory',
     '<!-- soleri:cross-project -->',
@@ -396,11 +470,27 @@ const ENGINE_RULES_LINES = [
     '',
     '### Character Persistence',
     '',
-    '- All communication flows through your persona\'s voice — tone, vocabulary, opinions',
+    '- **MANDATORY**: Prefix every response with `{AgentName} >` when activated (e.g., `Ernesto >`, `Salvador >`). This signals to the user that the agent persona is active.',
+    "- All communication flows through your persona's voice — tone, vocabulary, opinions",
     '- Stay in character until explicitly deactivated',
     '- Context compaction does not change who you are — these rules persist in CLAUDE.md',
     '- If you notice yourself dropping character, re-read your activation context',
     '',
+    '### Operator Learning (automatic, silent)',
+    'When calling `op:orchestrate_complete`, fill the `operatorSignals` field with your observations from this session:',
+    '',
+    '- **Expertise**: which topics did the operator demonstrate knowledge in? Where did they need explanation? Report topic + level (learning/intermediate/expert).',
+    "- **Corrections**: did they tell you to change behavior? Quote their exact words. Note if it's global or project-specific.",
+    '- **Interests**: did they share anything personal? Hobbies, background, music, culture? Report the tag and context.',
+    '- **Patterns**: did you notice work habits? Batching, scoping, pacing, communication style? Report what you observed.',
+    '',
+    'Rules:',
+    "- Fill what you observed. Empty arrays for what you didn't notice.",
+    '- Store facts, not assumptions. "User asked about React hooks" not "User doesn\'t know React."',
+    '- Never announce you are learning. Never ask for confirmation.',
+    '- Decline to store: health, medical, political, religious, sexual, financial, legal content.',
+    '- The engine handles compounding and persistence — just report honestly.',
+    '',
     '### What NOT to Route Through Tools',
     '',
     '- Pure file read/write/edit operations (use Read, Edit, Write tools directly)',
@@ -415,8 +505,8 @@ const ENGINE_RULES_LINES = [
     '',
     '### Session Start Protocol',
     '',
-    'On activation, discover capabilities via `op:admin_tool_list`. Call `op:register` when project context is needed for a task.',
-    'Call `op:activate` only when checking evolved capabilities or recovering session state.',
+    'On activation, discover capabilities via `op:admin_tool_list`. Call `op:session_briefing` to surface last session context, active plans, and brain recommendations.',
+    'Call `op:register` when project context is needed for a task. Call `op:activate` only when checking evolved capabilities or recovering session state.',
     'After context compaction, re-discover capabilities — do not assume your tool inventory is still cached.',
     '',
     '### Context Compaction',
@@ -493,6 +583,38 @@ const ENGINE_RULES_LINES = [
     '| "Check my setup" | `soleri doctor` |',
     '| Template drift suspected | `soleri agent diff` to see what changed |',
     '',
+    // ─── Persona Self-Update ────────────────────────────────────
+    '## Persona Self-Update',
+    '<!-- soleri:persona-self-update -->',
+    '',
+    'When the user asks to change your personality, voice, quirks, or character:',
+    '',
+    '1. **Edit your own `agent.yaml`** — the `persona:` block is the source of truth for your character.',
+    '2. **NEVER modify Soleri engine code** — `@soleri/core`, `packages/core/src/persona/defaults.ts`, or any engine package. Those define the default template for ALL agents.',
+    '3. After editing `agent.yaml`, tell the user to run `soleri agent refresh` to regenerate CLAUDE.md, then reactivate.',
+    '',
+    '### What You Can Change',
+    '',
+    '| Field | Purpose |',
+    '|-------|---------|',
+    '| `persona.template` | Template ID (informational, can be custom) |',
+    '| `persona.inspiration` | Who/what inspires the character |',
+    '| `persona.culture` | Cultural background |',
+    '| `persona.voice` | How you sound (tone, cadence, vocabulary) |',
+    '| `persona.traits` | Personality traits |',
+    '| `persona.quirks` | Memorable behaviors and expressions |',
+    '| `persona.opinions` | Beliefs about craft and quality |',
+    '| `persona.metaphors` | Domains you draw metaphors from |',
+    '| `persona.languageRule` | How you mix languages |',
+    '| `persona.greetings` | Session start messages |',
+    '| `persona.signoffs` | Session end messages |',
+    '',
+    '### What You Must NOT Change',
+    '',
+    '- Engine defaults in `packages/core/src/persona/defaults.ts`',
+    '- The `PERSONA_TEMPLATES` registry',
+    '- Any file inside `@soleri/core` or `@soleri/forge`',
+    '',
     // ─── Verification Protocol ─────────────────────────────────
     '## Verification Protocol',
     '<!-- soleri:verification-protocol -->',
@@ -505,11 +627,12 @@ const ENGINE_RULES_LINES = [
     '2. **Prove** — reproduce the issue (test case, error log, stack trace)',
     '3. **Fix** — only after the issue is proven reproducible',
     '',
-    '### Anti-pattern',
+    '### Anti-patterns',
     '',
     '- Fixing code "just in case" or for aesthetics without a proven issue',
     '- Claiming a bug exists without reproduction evidence',
     '- Refactoring working code under the guise of a bug fix',
+    '- **Dismissing test failures as "flaky" or "pre-existing" without reading the test code and the handler it exercises.** A test that fails consistently is broken, not flaky. Investigate the root cause before classifying.',
     '',
     '### Scope',
     '',

package/dist/templates/shared-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared-rules.js","sourceRoot":"","sources":["../../src/templates/shared-rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shared-rules.js","sourceRoot":"","sources":["../../src/templates/shared-rules.ts"],"names":[],"mappings":"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"}

package/dist/templates/skills.js

@@ -3,34 +3,8 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_DIR = join(__dirname, '..', 'skills');
-/** Skills that use YOUR_AGENT_core placeholder and need agent-specific substitution. */
-const AGENT_SPECIFIC_SKILLS = new Set([
-    'agent-dev',
-    'agent-guide',
-    'agent-persona',
-    'brain-debrief',
-    'brainstorming',
-    'code-patrol',
-    'context-resume',
-    'deep-review',
-    'deliver-and-ship',
-    'executing-plans',
-    'fix-and-learn',
-    'health-check',
-    'knowledge-harvest',
-    'onboard-me',
-    'parallel-execute',
-    'retrospective',
-    'second-opinion',
-    'systematic-debugging',
-    'test-driven-development',
-    'vault-capture',
-    'vault-curate',
-    'vault-navigator',
-    'vault-smells',
-    'verification-before-completion',
-    'writing-plans',
-]);
+/** Placeholder token in skill templates that gets replaced with agent-specific tool name. */
+const AGENT_PLACEHOLDER = 'YOUR_AGENT_core';
 /**
  * Generate skill files for the scaffolded agent.
  * Returns [relativePath, content] tuples for each skill.
@@ -77,7 +51,7 @@ export function generateSkills(config) {
             continue;
         }
         let content = readFileSync(contentPath, 'utf-8');
-        if (AGENT_SPECIFIC_SKILLS.has(skillName)) {
+        if (content.includes(AGENT_PLACEHOLDER)) {
             content = content.replace(/YOUR_AGENT_core/g, `${config.id}_core`);
         }
         files.push([`skills/${skillName}/SKILL.md`, content]);

package/dist/templates/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/templates/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnD,wFAAwF;AACxF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,WAAW;IACX,aAAa;IACb,eAAe;IACf,eAAe;IACf,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,aAAa;IACb,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,YAAY;IACZ,kBAAkB;IAClB,eAAe;IACf,gBAAgB;IAChB,sBAAsB;IACtB,yBAAyB;IACzB,eAAe;IACf,cAAc;IACd,iBAAiB;IACjB,cAAc;IACd,gCAAgC;IAChC,eAAe;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,OAAiB,CAAC;IAEtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,gEAAgE;IAChE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAE5G,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAE1C,wBAAwB;QACxB,gDAAgD;QAChD,yCAAyC;QACzC,IAAI,SAAiB,CAAC;QACtB,IAAI,WAAmB,CAAC;QAExB,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YAC5C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,SAAS;YACnC,SAAS,GAAG,KAAK,CAAC;YAClB,WAAW,GAAG,OAAO,CAAC;QACxB,CAAC;aAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrC,WAAW,GAAG,SAAS,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,SAAS;QACX,CAAC;QAED,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAEjD,IAAI,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,SAAS,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/templates/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnD,6FAA6F;AAC7F,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,OAAiB,CAAC;IAEtB,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,gEAAgE;IAChE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAE5G,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAE1C,wBAAwB;QACxB,gDAAgD;QAChD,yCAAyC;QACzC,IAAI,SAAiB,CAAC;QACtB,IAAI,WAAmB,CAAC;QAExB,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YAC5C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,SAAS;YACnC,SAAS,GAAG,KAAK,CAAC;YAClB,WAAW,GAAG,OAAO,CAAC;QACxB,CAAC;aAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACjC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrC,WAAW,GAAG,SAAS,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,SAAS;QACX,CAAC;QAED,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAEjD,IAAI,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACxC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,SAAS,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/templates/vitest-config.js

@@ -15,6 +15,7 @@ export default defineConfig({
     testTimeout: 30_000,
     hookTimeout: 10_000,
     teardownTimeout: 5_000,
+    exclude: ['**/node_modules/**', '**/.claude/worktrees/**'],
     coverage: {
       provider: 'v8',
       include: ['src/**/*.ts'],

package/dist/templates/vitest-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"vitest-config.js","sourceRoot":"","sources":["../../src/templates/vitest-config.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB;IAClC,OAAO;;;;;;;;;;;;;;;;;;;;;;;CAuBR,CAAC;AACF,CAAC"}
+{"version":3,"file":"vitest-config.js","sourceRoot":"","sources":["../../src/templates/vitest-config.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB;IAClC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;CAwBR,CAAC;AACF,CAAC"}

package/package.json

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

package/src/compose-claude-md.ts

@@ -8,7 +8,7 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
-import type { AgentYaml } from './agent-schema.js';
+import { AgentYamlSchema, type AgentYaml } from './agent-schema.js';
 import { ENGINE_MODULE_MANIFEST, CORE_KEY_OPS } from '@soleri/core/module-manifest';
 
 // ─── Types ────────────────────────────────────────────────────────────
@@ -39,7 +39,7 @@ export function composeClaudeMd(agentDir: string, tools?: ToolEntry[]): Composed
 
   // 1. Read agent.yaml
   const agentYamlPath = join(agentDir, 'agent.yaml');
-  const agentYaml = parseYaml(readFileSync(agentYamlPath, 'utf-8')) as AgentYaml;
+  const agentYaml = AgentYamlSchema.parse(parseYaml(readFileSync(agentYamlPath, 'utf-8')));
   sources.push(agentYamlPath);
 
   const sections: string[] = [];
@@ -220,6 +220,90 @@ function composeWorkflowIndex(workflowsDir: string): string | null {
   return lines.join('\n');
 }
 
+/** Skill categories for grouping in the CLAUDE.md index. */
+const SKILL_CATEGORIES: Record<string, { label: string; skills: string[] }> = {
+  getting_started: {
+    label: 'Getting Started',
+    skills: ['agent-guide', 'agent-persona', 'onboard-me', 'env-setup', 'context-resume'],
+  },
+  planning: {
+    label: 'Planning & Execution',
+    skills: ['brainstorming', 'writing-plans', 'executing-plans', 'parallel-execute'],
+  },
+  building: {
+    label: 'Building & Fixing',
+    skills: [
+      'test-driven-development',
+      'systematic-debugging',
+      'fix-and-learn',
+      'agent-dev',
+      'code-patrol',
+    ],
+  },
+  knowledge: {
+    label: 'Knowledge & Learning',
+    skills: [
+      'vault-capture',
+      'vault-navigator',
+      'vault-curate',
+      'vault-smells',
+      'knowledge-harvest',
+      'brain-debrief',
+    ],
+  },
+  quality: {
+    label: 'Quality & Delivery',
+    skills: [
+      'verification-before-completion',
+      'deep-review',
+      'deliver-and-ship',
+      'health-check',
+      'mcp-doctor',
+    ],
+  },
+  reflection: {
+    label: 'Reflection & Research',
+    skills: ['retrospective', 'second-opinion'],
+  },
+};
+
+/**
+ * Extract the description from SKILL.md frontmatter.
+ * Handles both single-line and multi-line YAML folded scalars (>).
+ */
+function extractSkillDescription(content: string): string | null {
+  // Match the frontmatter block
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+
+  const fm = fmMatch[1];
+
+  // Try parsing the description field — handles both inline and folded (>) forms
+  const descIdx = fm.indexOf('description:');
+  if (descIdx === -1) return null;
+
+  const afterDesc = fm.slice(descIdx + 'description:'.length);
+  const restLines = afterDesc.split('\n');
+
+  // Single-line: "description: some text"
+  const firstLine = restLines[0].trim();
+  if (firstLine && firstLine !== '>' && firstLine !== '|') {
+    return firstLine;
+  }
+
+  // Multi-line folded scalar (> or |): collect indented continuation lines
+  const parts: string[] = [];
+  for (let i = 1; i < restLines.length; i++) {
+    const line = restLines[i];
+    // Stop at next YAML key or end of frontmatter
+    if (line.match(/^\S/) || line.trim() === '---') break;
+    const trimmed = line.trim();
+    if (trimmed) parts.push(trimmed);
+  }
+
+  return parts.length > 0 ? parts.join(' ') : null;
+}
+
 function composeSkillsIndex(skillsDir: string): string | null {
   const dirs = readdirSync(skillsDir, { withFileTypes: true })
     .filter((d) => d.isDirectory())
@@ -227,18 +311,51 @@ function composeSkillsIndex(skillsDir: string): string | null {
 
   if (dirs.length === 0) return null;
 
-  const lines: string[] = ['## Available Skills', ''];
-
+  // Collect all available skills with descriptions
+  const skillMap = new Map<string, string>();
   for (const dir of dirs) {
     const skillPath = join(skillsDir, dir.name, 'SKILL.md');
     if (existsSync(skillPath)) {
       const content = readFileSync(skillPath, 'utf-8');
-      // Extract description from frontmatter if present
-      const descMatch = content.match(/^description:\s*(.+)$/m);
-      const desc = descMatch ? descMatch[1].trim() : dir.name;
-      lines.push(`- **${dir.name}**: ${desc}`);
+      const desc = extractSkillDescription(content) ?? dir.name;
+      skillMap.set(dir.name, desc);
     }
   }
 
-  return lines.join('\n');
+  if (skillMap.size === 0) return null;
+
+  const lines: string[] = [
+    '## Available Skills',
+    '',
+    'Skills are specialized workflows that activate automatically when you describe a matching task.',
+    'Each skill provides a structured, step-by-step approach backed by vault knowledge and brain patterns.',
+    '',
+  ];
+
+  // Group skills into categories
+  const categorized = new Set<string>();
+
+  for (const [_key, category] of Object.entries(SKILL_CATEGORIES)) {
+    const categorySkills = category.skills.filter((s) => skillMap.has(s));
+    if (categorySkills.length === 0) continue;
+
+    lines.push(`### ${category.label}`, '');
+    for (const skill of categorySkills) {
+      lines.push(`- **${skill}**: ${skillMap.get(skill)!}`);
+      categorized.add(skill);
+    }
+    lines.push('');
+  }
+
+  // Any uncategorized skills go into an "Other" section
+  const uncategorized = [...skillMap.keys()].filter((s) => !categorized.has(s)).sort();
+  if (uncategorized.length > 0) {
+    lines.push('### Other', '');
+    for (const skill of uncategorized) {
+      lines.push(`- **${skill}**: ${skillMap.get(skill)!}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
 }