@soleri/forge 9.3.0 → 9.4.0

package/src/templates/setup-script.ts

@@ -53,11 +53,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"
@@ -75,6 +82,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/src/templates/shared-rules.ts

@@ -114,13 +114,25 @@ const ENGINE_RULES_LINES: string[] = [
   '- 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 -->',
   '',
-  '- **MANDATORY**: Create a formal plan (`op:create_plan`) for every work task. Memory and vault knowledge alone are not sufficient — plans must be persisted and graded.',
-  '- Use `op:create_plan` before writing ANY code. Show the plan, wait for approval.',
+  '- For complex tasks, use `op:create_plan` before writing code. Simple tasks can execute directly — but always run `op:orchestrate_complete`.',
   '- Two-gate approval: Gate 1 (`op:approve_plan`), Gate 2 (`op:plan_split`). Never skip either.',
   '- Wait for explicit "yes" / "approve" before proceeding past each gate.',
   '- After execution: `op:plan_reconcile` (drift report) then `op:plan_complete_lifecycle` (knowledge capture, archive).',
@@ -128,6 +140,26 @@ const ENGINE_RULES_LINES: string[] = [
   '- On session start: check for plans in `executing`/`reconciling` state and remind.',
   '- Exceptions: read-only operations, user says "just do it", single-line fixes.',
   '',
+  '### Task Auto-Assessment',
+  '',
+  'When picking up a work task (including GH issues decomposed from a parent plan), autonomously assess complexity — do NOT ask the user whether to create a plan.',
+  '',
+  '| Signal | Classification | Action |',
+  '|--------|---------------|--------|',
+  '| Single file, clear acceptance criteria | **Simple** | Execute directly |',
+  '| Approach already described in parent plan | **Simple** | Execute directly |',
+  '| Touches 3+ files or has cross-cutting concerns | **Complex** | Create scoped plan |',
+  '| Unresolved design decisions not in parent plan | **Complex** | Create scoped plan |',
+  '| New dependencies or architectural choices needed | **Complex** | Create scoped plan |',
+  '',
+  '**Simple task flow:** Vault search (quick) → execute → `op:orchestrate_complete` (captures knowledge).',
+  '',
+  '**Complex task flow:** Vault search → create lightweight scoped plan → two-gate approval → execute → reconcile → complete.',
+  '',
+  '**Key rule:** Knowledge gets captured either way via `op:orchestrate_complete`. Planning ceremony is for *decision-making*, not record-keeping.',
+  '',
+  '**Anti-pattern:** Creating a full graded plan for trivial tasks (add a CSS class, rename a variable, single-line fix).',
+  '',
   '### Grade Gate',
   '',
   '**MANDATORY**: Plans must grade **A or higher** before approval. The engine enforces this programmatically.',
@@ -191,6 +223,38 @@ const ENGINE_RULES_LINES: string[] = [
   '```',
   '',
 
+  // ─── 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 -->',
@@ -256,12 +320,40 @@ const ENGINE_RULES_LINES: string[] = [
   '## Work Task Routing',
   '<!-- soleri:task-routing -->',
   '',
-  'Use the orchestration layer for ALL work tasks:',
-  '- `op:orchestrate_plan` → vault + brain + structured plan.',
-  '- `op:orchestrate_execute` → execution tracking.',
-  '- `op:orchestrate_complete` → epilogue (vault, session).',
+  'On every work task, assess complexity then route:',
+  '',
+  '### Auto-Assessment',
+  '',
+  'Evaluate these signals before deciding the execution path:',
+  '',
+  '| Signal | Simple (< 40) | Complex (≥ 40) |',
+  '|--------|---------------|----------------|',
+  '| Files touched | 1-2 | 3+ |',
+  '| Cross-cutting concerns | No | Yes |',
+  '| New dependencies | None | Yes |',
+  '| Design decisions | Already decided | Unresolved |',
+  '| Approach described | In parent plan/issue | Not yet |',
+  '',
+  '### Routing',
+  '',
+  '- **Simple tasks** → execute directly → `op:orchestrate_complete` (always)',
+  '- **Complex tasks** → `op:orchestrate_plan` → approve → execute → `op:orchestrate_complete` (always)',
+  '',
+  '### The Non-Negotiable Rule',
+  '',
+  '`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)",
+  '',
+  'Without completion, the knowledge trail is lost. The code is in git, but the WHY disappears.',
+  '',
+  '### Exceptions (skip assessment, execute directly)',
   '',
-  'The orchestrator handles vault lookup, brain recommendations, and knowledge capture automatically.',
+  '- Read-only operations (search, status, health check)',
+  '- User explicitly says "just do it"',
+  '- Single-line fixes (typo, rename, one-liner)',
+  '- Questions and explanations',
   '',
 
   // ─── Intent Detection ────────────────────────────────────
@@ -303,6 +395,36 @@ const ENGINE_RULES_LINES: string[] = [
   '- 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',
@@ -342,15 +464,72 @@ const ENGINE_RULES_LINES: string[] = [
   '**Do NOT suggest tools when:** the user is having a conversation (not a task), already declined, or explicitly says "just tell me".',
   '',
 
+  // ─── Overlay Mode ─────────────────────────────────────────
+  '## Overlay Mode — Active Agent Protocol',
+  '<!-- soleri:overlay-mode -->',
+  '',
+  'When you are activated as an agent (via greeting or activation command), you ARE this agent — not Claude with tools on the side. You drive the full cycle through your toolset.',
+  '',
+  '### Tool-First Routing (MANDATORY when active)',
+  '',
+  'On every user request:',
+  '1. **Discover capabilities** — call `op:admin_tool_list` on first request of the session (or after context compaction resets your state)',
+  '2. **Parse intent** — what does the user want? Use semantic-first analysis.',
+  '3. **Route through agent tools** — always prefer your MCP tools over raw Claude reasoning:',
+  '   - **Knowledge questions** → vault search before answering from training data',
+  '   - **Recommendations** → brain recommend before proposing approaches',
+  '   - **Work tasks** → orchestrate plan before writing code',
+  '   - **Quality checks** → curator or admin health before manual inspection',
+  '   - **Learning moments** → capture to vault, don\'t just say "I\'ll remember"',
+  '4. **Fall back only when no tool fits** — file read/write/edit, git operations, shell commands, casual conversation',
+  '',
+  '### Self-Healing Discovery',
+  '',
+  '- After activation or context compaction, call `op:admin_tool_list` to refresh your capability inventory',
+  '- Do NOT rely on memorized tool lists from earlier in the conversation',
+  '- The tool list adapts when packs are installed — always discover dynamically',
+  '',
+  '### Character Persistence',
+  '',
+  '- **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)',
+  '- Git operations (commit, push, branch, status)',
+  '- Shell commands the user explicitly requests',
+  '- Casual conversation, greetings, explanations',
+  '- One-line fixes where planning overhead exceeds the work',
+  '',
+
   // ─── Session Lifecycle ───────────────────────────────────
   '## Session Lifecycle',
   '<!-- soleri:session -->',
   '',
   '### Session Start Protocol',
   '',
-  'Do NOT call tools automatically on session start — just greet the user in character.',
-  'Call `op:session_start` only when you need project context for a task (not on every message).',
-  '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',
   '',
@@ -428,6 +607,39 @@ const ENGINE_RULES_LINES: string[] = [
   '| 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 -->',
@@ -440,11 +652,12 @@ const ENGINE_RULES_LINES: string[] = [
   '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/src/templates/skills.ts

@@ -6,34 +6,8 @@ import type { AgentConfig } from '../types.js';
 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.
@@ -85,7 +59,7 @@ export function generateSkills(config: AgentConfig): Array<[string, string]> {
 
     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`);
     }
 

package/src/templates/vitest-config.ts

@@ -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/vitest.config.ts

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