@soleri/forge 9.14.4 → 9.16.7

package/src/skills/soleri-orchestrate/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: soleri-orchestrate
+tier: default
+description: >
+  Use when the user gives a work task: "implement X", "build Y", "fix Z",
+  "add feature", or any request that requires planning and execution.
+  Runs the full orchestration loop: plan → execute → complete with vault
+  context and brain recommendations built in.
+---
+
+# Orchestrate — Full Work Loop
+
+Run the full work loop with vault intelligence: plan the task, execute it step by step, and close with knowledge capture. Use this for any non-trivial task where missing context or skipping steps would cost time.
+
+## When to Use
+
+- User gives a concrete work task ("implement auth", "refactor the parser", "fix the flaky test")
+- Task spans multiple files or has cross-cutting concerns
+- You want vault patterns and brain recommendations surfaced automatically
+
+## Orchestration
+
+### Step 1: Plan
+
+```
+YOUR_AGENT_orchestrate op:orchestrate_plan
+  params: {
+    prompt: "<user task description>",
+    context: { domain: "<inferred domain>" }
+  }
+```
+
+Present the plan to the user. If grade < A-, ask for approval before proceeding.
+
+### Step 2: Execute
+
+Once approved, begin execution. For each task in the plan:
+
+```
+YOUR_AGENT_orchestrate op:orchestrate_execute
+  params: {
+    planId: "<planId from step 1>",
+    taskId: "<current task id>",
+    output: "<what you did>"
+  }
+```
+
+Log progress after each task: show completed count / total and current task title.
+
+### Step 3: Complete
+
+After all tasks are done:
+
+```
+YOUR_AGENT_orchestrate op:orchestrate_complete
+  params: {
+    planId: "<planId>",
+    summary: "<one-line outcome>",
+    operatorSignals: {
+      qualityNotes: "<any quality observations>",
+      unexpectedComplexity: <true|false>
+    }
+  }
+```
+
+Report the completion summary and any knowledge captured.
+
+## Exit Criteria
+
+All plan tasks executed, `orchestrate_complete` called with outcome, knowledge persisted to vault.

package/src/skills/soleri-parallel-execute/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-parallel-execute
+tier: default
 description: >
   Use when the user says "run in parallel", "fan out", "concurrent execution",
   "batch execute", or "dispatch subagents". Executes independent plan tasks

package/src/skills/soleri-research-scout/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-research-scout
+tier: default
 description: >
   Use when the user says "scout", "research scout", "find new info",
   "what's new", or "scan the web". Discovers new information that challenges

package/src/skills/soleri-retrospective/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-retrospective
+tier: default
 description: >
   Use when the user says "sprint retro", "weekly summary", "what went well",
   "end of sprint", or "monthly report". Time-bound reflection on recent work

package/src/skills/soleri-second-opinion/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-second-opinion
+tier: default
 description: >
   Use when the user says "second opinion", "technical decision",
   "comparing approaches", or "which approach". Provides informed recommendations

package/src/skills/soleri-subagent-driven-development/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-subagent-driven-development
+tier: default
 description: >
   Use when the user says "use subagents", "parallel agents",
   "subagent driven", or "isolated execution". Decomposes work into isolated

package/src/skills/soleri-systematic-debugging/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-systematic-debugging
+tier: default
 description: >
   Use as the FIRST response when something is broken — "bug", "failing test",
   "not working", "debug this", "error", "crash", or "weird issue". Diagnoses

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

@@ -1,5 +1,6 @@
 ---
 name: soleri-test-driven-development
+tier: default
 description: >
   Use when the user says "TDD", "write tests first", "red green refactor",
   or "test driven". Write failing tests before implementation code for any

package/src/skills/soleri-using-git-worktrees/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-using-git-worktrees
+tier: default
 description: >
   Use when the user says "worktree", "parallel branch", "safe branch",
   or "isolated branch". Provides the protocol for creating, working in,

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

@@ -1,11 +1,12 @@
 ---
 name: soleri-vault-capture
+tier: default
 description: >
-  Use when the user says "save this", "capture this", "remember this pattern",
-  "add to vault", "vault capture", or when persisting learnings from a work
-  session. Validated capture with tier scoping, duplicate detection, and
-  abstraction review. For bulk extraction from documents, code, or PRs, use
-  knowledge-harvest instead.
+  Use when the user says "save this to vault", "capture this", "remember this pattern",
+  "add to vault", "vault capture", or when persisting learnings from a work session.
+  Priority over memory_capture for durable knowledge (patterns, decisions, anti-patterns).
+  For quick session notes say "save this as a memory" to use memory_capture instead.
+  For bulk extraction from documents, code, or PRs, use knowledge-harvest.
 ---
 
 # Vault Capture — Validated Knowledge Persistence

package/src/skills/soleri-vault-curate/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-vault-curate
+tier: default
 description: >
   Use when the user says "clean vault", "deduplicate vault", "groom knowledge",
   "merge patterns", or "vault maintenance". Maintains vault quality through

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

@@ -1,5 +1,6 @@
 ---
 name: soleri-vault-navigator
+tier: default
 description: >
   Use when the user says "search the vault", "find patterns for",
   "have we seen this before", "vault search", or "best practice for".

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

@@ -1,5 +1,6 @@
 ---
 name: soleri-vault-smells
+tier: default
 description: >
   Use when the user says "vault quality", "vault analysis", "knowledge quality",
   "knowledge debt", "stale patterns", or "find contradictions". Deep knowledge

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

@@ -1,5 +1,6 @@
 ---
 name: soleri-verification-before-completion
+tier: default
 description: >
   Use when the user says "verify this works", "check output", "quality gate",
   or "run tests before done". Internal quality gate before claiming any task

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

@@ -1,9 +1,12 @@
 ---
 name: soleri-writing-plans
+tier: default
 description: >
-  Use when the user says "create a plan", "break this down", or
-  "plan the implementation". Creates structured implementation plans when
-  requirements are already known. For exploration, use brainstorming.
+  Use when the user says "create a plan", "write up a plan", "break this down",
+  or "plan the implementation". Produces a human-readable markdown plan file.
+  Takes priority over orchestrate_plan MCP op for explicit plan-writing requests.
+  For exploration or ideation, use brainstorming. For automated task orchestration,
+  the engine uses orchestrate_plan directly without this skill.
 ---
 
 # Writing Plans

package/src/skills/soleri-yolo-mode/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-yolo-mode
+tier: default
 description: >
   Use when the user says "yolo", "autonomous", "skip approvals",
   "full auto", or "hands off". Activates autonomous execution mode

package/src/templates/claude-md-template.ts

@@ -70,60 +70,12 @@ export function generateClaudeMdTemplate(config: AgentConfig): string {
     '',
   ];
 
-  // ─── Compact Facade Table ───────────────────────────────
+  // ─── Skill pointer (replaces inline facade table) ───────
   mdLines.push(
-    '## Essential Tools',
-    `<!-- ${toolPrefix}:tools -->`,
+    `> Command reference: use the ${bt}${toolPrefix}-agent-mode${bt} skill or run ${bt}${toolPrefix}_admin op:admin_tool_list${bt}`,
     '',
-    '| Facade | Key Ops |',
-    '|--------|---------|',
-    `| ${bt}${toolPrefix}_core${bt} | ${bt}health${bt}, ${bt}search${bt}, ${bt}identity${bt}, ${bt}session_start${bt}, ${bt}activate${bt} |`,
   );
 
-  // Domain facades — one row per domain
-  for (const d of config.domains) {
-    const toolName = `${toolPrefix}_${d.replace(/-/g, '_')}`;
-    mdLines.push(
-      `| ${bt}${toolName}${bt} | ${bt}get_patterns${bt}, ${bt}search${bt}, ${bt}capture${bt} |`,
-    );
-  }
-
-  // Domain pack facades (if any)
-  if (config.domainPacks?.length) {
-    mdLines.push('', '**Domain Pack Facades:**', '');
-    for (const ref of config.domainPacks) {
-      mdLines.push(
-        `| ${bt}${ref.name}${bt} (pack: ${bt}${ref.package}${bt}) | *custom ops — see ${bt}admin_tool_list${bt}* |`,
-      );
-    }
-  }
-
-  // Engine facades — use actual tool names (standalone facades, NOT _core sub-groups)
-  mdLines.push(
-    // Vault — knowledge lifecycle, capture, search, management
-    `| ${bt}${toolPrefix}_vault${bt} | ${bt}search_intelligent${bt}, ${bt}capture_knowledge${bt}, ${bt}capture_quick${bt}, ${bt}search_feedback${bt} |`,
-    `| ${bt}${toolPrefix}_vault${bt} (keeper) | ${bt}knowledge_audit${bt}, ${bt}knowledge_health${bt}, ${bt}knowledge_merge${bt}, ${bt}knowledge_reorganize${bt} |`,
-    `| ${bt}${toolPrefix}_vault${bt} (mgmt) | ${bt}vault_get${bt}, ${bt}vault_update${bt}, ${bt}vault_remove${bt}, ${bt}vault_tags${bt}, ${bt}vault_domains${bt}, ${bt}vault_recent${bt} |`,
-    // Curator — quality, dedup, contradictions, grooming
-    `| ${bt}${toolPrefix}_curator${bt} | ${bt}curator_status${bt}, ${bt}curator_detect_duplicates${bt}, ${bt}curator_contradictions${bt}, ${bt}curator_groom_all${bt}, ${bt}curator_consolidate${bt}, ${bt}curator_health_audit${bt} |`,
-    `| ${bt}${toolPrefix}_curator${bt} (advanced) | ${bt}curator_enrich${bt}, ${bt}curator_hybrid_contradictions${bt}, ${bt}curator_entry_history${bt}, ${bt}curator_queue_stats${bt} |`,
-    // Planning, orchestration, brain
-    `| ${bt}${toolPrefix}_plan${bt} | ${bt}create_plan${bt}, ${bt}approve_plan${bt}, ${bt}plan_split${bt}, ${bt}plan_reconcile${bt}, ${bt}plan_complete_lifecycle${bt} |`,
-    `| ${bt}${toolPrefix}_orchestrate${bt} | ${bt}orchestrate_plan${bt}, ${bt}orchestrate_execute${bt}, ${bt}orchestrate_complete${bt} |`,
-    `| ${bt}${toolPrefix}_brain${bt} | ${bt}brain_stats${bt}, ${bt}brain_feedback${bt}, ${bt}rebuild_vocabulary${bt}, ${bt}brain_strengths${bt}, ${bt}brain_recommend${bt} |`,
-    // Memory, control, loop
-    `| ${bt}${toolPrefix}_memory${bt} | ${bt}memory_search${bt}, ${bt}memory_capture${bt}, ${bt}session_capture${bt} |`,
-    `| ${bt}${toolPrefix}_control${bt} | ${bt}route_intent${bt}, ${bt}morph${bt}, ${bt}get_behavior_rules${bt}, ${bt}governance_dashboard${bt}, ${bt}governance_policy${bt} |`,
-    `| ${bt}${toolPrefix}_loop${bt} | ${bt}loop_start${bt}, ${bt}loop_iterate${bt}, ${bt}loop_status${bt}, ${bt}loop_cancel${bt} |`,
-    // Intelligence — context, agency
-    `| ${bt}${toolPrefix}_context${bt} | ${bt}context_extract_entities${bt}, ${bt}context_retrieve_knowledge${bt}, ${bt}context_analyze${bt} |`,
-    `| ${bt}${toolPrefix}_agency${bt} | ${bt}agency_enable${bt}, ${bt}agency_status${bt}, ${bt}agency_surface_patterns${bt}, ${bt}agency_warnings${bt}, ${bt}agency_clarify${bt} |`,
-    // Admin
-    `| ${bt}${toolPrefix}_admin${bt} | ${bt}admin_health${bt}, ${bt}admin_tool_list${bt}, ${bt}admin_diagnostic${bt} |`,
-  );
-
-  mdLines.push('', `> Full list: ${bt}${toolPrefix}_admin op:admin_tool_list${bt}`, '');
-
   // ─── Hook Packs (conditional) ──────────────────────────
   appendHookPacks(mdLines, config);
 

package/src/templates/package-json.ts

@@ -9,6 +9,7 @@ export function generatePackageJson(config: AgentConfig): string {
     main: 'dist/index.js',
     bin: { [`${config.id}-mcp`]: 'dist/index.js' },
     scripts: {
+      postinstall: 'soleri hooks sync || true',
       dev: 'tsx src/index.ts',
       build: 'tsc && node scripts/copy-assets.js',
       start: 'node dist/index.js',
@@ -39,6 +40,7 @@ export function generatePackageJson(config: AgentConfig): string {
       '@anthropic-ai/sdk': '^0.39.0',
     },
     devDependencies: {
+      '@soleri/cli': '^9.0.0',
       '@types/node': '^22.13.4',
       '@vitest/coverage-v8': '^3.0.5',
       tsx: '^4.19.2',

package/src/templates/setup-script.ts

@@ -35,72 +35,15 @@ echo "Registering ${config.name} with Claude Code..."
 claude mcp add --scope user "$AGENT_NAME" -- node "$AGENT_DIR/dist/index.js"
 echo "[ok] Registered ${config.name} as MCP server (Claude Code)"
 
-# Configure PreCompact hook for session capture
-SETTINGS_FILE="$HOME/.claude/settings.json"
+# Sync lifecycle hooks into ~/.claude/settings.json
 echo ""
-echo "Configuring Claude session capture hook..."
-
-if [ ! -d "$HOME/.claude" ]; then
-  mkdir -p "$HOME/.claude"
-fi
-
-if [ ! -f "$SETTINGS_FILE" ]; then
-  cat > "$SETTINGS_FILE" << SETTINGS
-{
-  "hooks": {
-    "PreCompact": [
-      {
-        "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 + SessionStart hooks"
+echo "Syncing lifecycle hooks..."
+if command -v soleri &>/dev/null; then
+  soleri hooks sync
 else
-  if grep -q "PreCompact" "$SETTINGS_FILE" 2>/dev/null; then
-    echo "[ok] PreCompact hook already configured — skipping"
-  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.PreCompact) settings.hooks.PreCompact = [];
-      settings.hooks.PreCompact.push({
-        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.'
-      });
-      fs.writeFileSync('$SETTINGS_FILE', JSON.stringify(settings, null, 2) + '\\n');
-    "
-    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
+  npx --yes soleri hooks sync
 fi
+echo "[ok] Lifecycle hooks synced"
 
 # Install skills to ~/.claude/skills/
 SKILLS_DIR="$AGENT_DIR/skills"

package/src/templates/shared-rules.ts

@@ -186,12 +186,20 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   'The vault is a **Zettelkasten** — a connected knowledge graph. Every knowledge operation follows Zettelkasten principles: atomic entries, typed links, dense connections.',
   '',
-  '- **SHOULD**: Consult the vault BEFORE every decision — search + traverse the link graph.',
-  '- Lookup order: 1) VAULT search → 2) VAULT traverse (follow links 2 hops) → 3) MEMORY → 4) CODEBASE → 5) WEB/TRAINING.',
+  '**SHOULD follow this lookup order for every question, problem, or task — regardless of whether agent MCP is active:**',
+  '',
+  '1. **Vault** — `op:search_intelligent` + traverse links 2 hops (when agent MCP is active)',
+  '2. **Web** — `WebSearch` tool (always — never skip if vault returns no answer)',
+  '3. **Memory** — `op:memory_search` (when agent MCP is active)',
+  '4. **Codebase** — read relevant files',
+  '5. **Training data** — last resort; flag as potentially outdated',
+  '',
+  '- Web search is **not optional**. If vault is unavailable or returns no relevant results, search the web before answering from training data alone.',
+  '- If the vault has a pattern, follow it. If it has an anti-pattern, avoid it.',
   "- **Search + Traverse**: Don't just search — traverse from the best result to discover connected knowledge and anti-patterns.",
   '- Check `contradicts` links to know what to avoid. Check `sequences` links for ordering dependencies.',
   '- Persist lessons: capture + link. An unlinked entry is incomplete.',
-  '- Exceptions: runtime errors with stack traces → codebase first; user explicitly asks to search web.',
+  '- Exception: runtime errors with stack traces → codebase first.',
   '',
   '### Vault Search Strategy',
   '',
@@ -651,7 +659,6 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### Character Persistence',
   '',
-  '- **SHOULD**: 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',

package/src/templates/skills.ts

@@ -6,8 +6,8 @@ import type { AgentConfig } from '../types.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_DIR = join(__dirname, '..', 'skills');
 
-/** Placeholder token in skill templates that gets replaced with agent-specific tool name. */
-const AGENT_PLACEHOLDER = 'YOUR_AGENT_core';
+/** Placeholder token in skill templates that gets replaced with agent-specific tool prefix. */
+const AGENT_PLACEHOLDER = 'YOUR_AGENT_';
 
 // ---------------------------------------------------------------------------
 // Frontmatter step extraction
@@ -77,6 +77,63 @@ export function extractStepsFromFrontmatter(content: string): SkillStepDef[] | n
   return steps.length > 0 ? steps : null;
 }
 
+// ---------------------------------------------------------------------------
+// Announce / Complete injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the `name:` field from YAML frontmatter.
+ * Returns the raw string value, or null if not found.
+ */
+export function extractNameFromFrontmatter(content: string): string | null {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+  const nameMatch = fmMatch[1].match(/^name:\s*(.+)/m);
+  return nameMatch ? nameMatch[1].trim().replace(/^["']|["']$/g, '') : null;
+}
+
+/**
+ * Inject announce and completion feedback instructions into a skill's content.
+ *
+ * Announce goes immediately after the frontmatter block.
+ * Complete goes at the very end of the file.
+ * Both are inside HTML comments so they don't clutter the rendered output.
+ */
+export function injectSkillFeedback(content: string, skillName: string): string {
+  // Count ### headings as "steps"
+  const stepMatches = content.match(/^### .+/gm) ?? [];
+  const stepCount = stepMatches.length;
+  const firstStep = stepMatches[0]?.replace(/^### \d+\.\s*/, '').trim() ?? 'Step 1';
+
+  const displayName = skillName
+    .replace(/^soleri-/, '')
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+  const announceBlock = [
+    '',
+    '## Announce',
+    '',
+    `When this skill is invoked, immediately say:`,
+    `> "Using **${displayName}** skill${stepCount > 0 ? ` (${stepCount} steps)` : ''}. Starting with: ${firstStep}"`,
+    '',
+  ].join('\n');
+
+  const completeBlock = [
+    '',
+    '## Completion',
+    '',
+    'After all steps are done, close with a one-line summary:',
+    `> "${displayName} complete: {brief outcome — e.g. '3 captured, 1 skipped'}"`,
+    '',
+  ].join('\n');
+
+  // Insert announce block right after the closing ---  of frontmatter
+  const afterFm = content.replace(/^(---\n[\s\S]*?\n---\n)/, `$1${announceBlock}`);
+
+  return afterFm + completeBlock;
+}
+
 // ---------------------------------------------------------------------------
 // Skill generation
 // ---------------------------------------------------------------------------
@@ -136,9 +193,12 @@ export function generateSkills(config: AgentConfig): Array<[string, string]> {
     let content = readFileSync(contentPath, 'utf-8');
 
     if (content.includes(AGENT_PLACEHOLDER)) {
-      content = content.replace(/YOUR_AGENT_core/g, `${config.id}_core`);
+      content = content.replace(/YOUR_AGENT_/g, `${config.id}_`);
     }
 
+    // Inject announce / complete feedback blocks
+    content = injectSkillFeedback(content, skillName);
+
     // Extract structured steps from frontmatter and append as metadata block
     const steps = extractStepsFromFrontmatter(content);
     if (steps) {

package/vitest.config.ts

@@ -3,7 +3,8 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
   test: {
     environment: 'node',
-    pool: 'threads',
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
     testTimeout: 30_000,
     exclude: ['**/node_modules/**', '**/.claude/worktrees/**'],
     coverage: {