@soleri/forge 9.8.0 → 9.10.0

package/dist/skills/subagent-driven-development/SKILL.md

@@ -8,10 +8,37 @@ description: >
 
 # Subagent-Driven Development
 
-Decompose work into isolated units, dispatch subagents via the Agent tool, merge results back. You are the controller — you never implement, you orchestrate.
+Decompose work into isolated units, dispatch subagents via the Agent tool, merge results back. You are the orchestrator — you make all decisions, subagents execute.
 
 **Announce at start:** "I'm using the subagent-driven-development skill to dispatch isolated agents."
 
+## The Orchestrator Contract
+
+**You are the boss. Subagents are the crew.**
+
+1. **All decisions stay with the orchestrator.** Research the task, consult the vault, decide the approach. Subagents receive exact specs — scope, file boundaries, acceptance criteria. They execute, they don't decide.
+2. **Subagents MUST NOT create plans.** Only the orchestrator creates plans. Subagent prompts must explicitly state: "Do NOT create plans, do NOT call planning tools."
+3. **If a subagent hits ambiguity, it returns — it doesn't guess.** The orchestrator resolves, then re-dispatches.
+4. **The orchestrator reconciles all work.** After subagents return, the orchestrator reviews changes, merges, captures knowledge.
+
+## Hybrid Agent Routing
+
+Not all subagents are equal. Route by complexity:
+
+| Signal                                | Agent Type                | Why                           |
+| ------------------------------------- | ------------------------- | ----------------------------- |
+| Single file, clear spec, no decisions | **Claude Code worker**    | Fast, low overhead            |
+| Approach already in parent plan       | **Claude Code worker**    | Spec is decided               |
+| 3+ files, cross-cutting concerns      | **Soleri agent instance** | Needs vault, brain, lifecycle |
+| Unresolved design decisions           | **Soleri agent instance** | Needs judgment                |
+| New dependencies or architecture      | **Soleri agent instance** | Needs full context            |
+
+**User overrides:**
+
+- "Use full agent for everything" → all Soleri agent instances
+- "Just use workers" → all Claude Code workers
+- Default: hybrid routing
+
 ## When to Dispatch
 
 | Signal                                        | Dispatch?                                |
@@ -25,47 +52,87 @@ Decompose work into isolated units, dispatch subagents via the Agent tool, merge
 
 ## The Process
 
-### Step 1: Decompose
+### Step 1: Research & Decide (Orchestrator only)
+
+Read all relevant files. Consult the vault for patterns. Make every design decision. Define the exact spec for each subagent task: files to touch, approach to use, acceptance criteria.
 
-Break work into discrete units. For each, determine: files involved, dependencies on other units, conflict risk. Only units with no file overlap and no inter-dependency qualify for dispatch.
+### Step 2: Decompose & Route
 
-### Step 2: Dispatch with Worktree Isolation
+Break work into discrete units. For each, determine: files involved, dependencies on other units, conflict risk, complexity. Assign agent type per the routing table.
+
+### Step 3: Dispatch
+
+Present the dispatch table to the user:
 
 ```
-Agent(prompt: "<task prompt>", isolation: "worktree")
+## Dispatching N tasks in parallel
+
+| # | Task | Agent | Why |
+|---|------|-------|-----|
+| 1 | Description | Worker / Instance | Routing reason |
 ```
 
-Each subagent prompt must include: (1) task scope, (2) file boundaries, (3) acceptance criteria, (4) rules — no commits, no out-of-scope changes, run tests before reporting.
+Each subagent prompt must include:
+
+- Task scope and file boundaries
+- Acceptance criteria
+- "Do NOT create plans. Do NOT make design decisions. Execute this spec exactly."
+- For Soleri instances: "Activate, execute, run orchestrate_complete when done."
 
 Launch all independent subagents in a **single message** so they run in parallel.
+Use `isolation: "worktree"` for file-modifying tasks.
 
-### Step 3: Review and Merge
+### Step 4: Review and Merge
 
 For each returning subagent:
 
 1. **Review** — read actual file changes (do not trust self-reports alone), verify tests pass, check scope compliance
 2. **Merge** — `git merge` or `git cherry-pick` from the worktree branch, one at a time
 3. **Test** — run the full suite after each merge; only proceed if green
-4. **Conflicts** — resolve manually, re-run tests, capture as anti-pattern for future planning
+4. **Conflicts** — resolve manually, re-run tests, capture as anti-pattern
+
+### Step 5: Reconcile & Report
+
+After all merges, report to the user:
 
-After all merges, capture learnings:
+**Minimal (default):**
 
 ```
-YOUR_AGENT_core op:capture_quick params:{
-  title: "subagent dispatch outcome",
-  description: "<which tasks parallelized well, which conflicted>"
-}
+✓ N/N complete. M patterns captured to vault.
+  → Decisions: [any design decisions the orchestrator made]
+```
+
+**Detailed (on request):**
+
 ```
+| # | Task | Agent | Status | Knowledge |
+|---|------|-------|--------|-----------|
+| 1 | Desc | Worker | Done ✓ | — |
+| 2 | Desc | Instance | Done ✓ | 2 patterns |
+```
+
+Capture learnings to vault. Run `orchestrate_complete` for the parent plan.
+
+## Worktree Cleanup Guarantee
+
+Three layers — nothing accumulates:
+
+1. **Per-task:** `finally` block in dispatcher removes worktree after each task
+2. **Per-batch:** `cleanupAll()` runs after all subagents complete
+3. **Per-session:** `SessionStart` hook prunes orphaned worktrees
 
 ## Anti-Patterns
 
-| Anti-Pattern                                 | Why It Fails                                  |
-| -------------------------------------------- | --------------------------------------------- |
-| Dispatching for a 5-line fix                 | Startup overhead exceeds the work             |
-| Parallel dispatch of dependent tasks         | Second agent works on stale assumptions       |
-| Skipping worktree isolation for nearby files | Silent overwrites between agents              |
-| Trusting self-reports without reading code   | Agents miss edge cases or misunderstand scope |
-| Dispatching 10+ agents at once               | Review bottleneck shifts to the controller    |
+| Anti-Pattern                                 | Why It Fails                                        |
+| -------------------------------------------- | --------------------------------------------------- |
+| Subagent creating its own plan               | Stale plans accumulate, lifecycle never completes   |
+| Subagent making design decisions             | Inconsistent approaches, orchestrator loses control |
+| Dispatching for a 5-line fix                 | Startup overhead exceeds the work                   |
+| Parallel dispatch of dependent tasks         | Second agent works on stale assumptions             |
+| Skipping worktree isolation for nearby files | Silent overwrites between agents                    |
+| Trusting self-reports without reading code   | Agents miss edge cases or misunderstand scope       |
+| Dispatching 10+ agents at once               | Review bottleneck shifts to the controller          |
+| Not cleaning up worktrees after merge        | Disk bloat, stale branch accumulation               |
 
 ## Merge Strategy
 

package/dist/templates/inject-claude-md.js

@@ -67,10 +67,15 @@ export function generateInjectClaudeMd(config) {
         ' * `<!-- soleri:engine-rules -->`. If already present, they are updated.',
         ' * Agent block (identity + facade table) is injected under',
         ` * \`<!-- ${marker} -->\`.`,
+        ' *',
+        ' * @param skipEngineRules - If true, skip engine rules injection (used for global files)',
         ' */',
-        'function injectIntoFile(filePath: string): InjectResult {',
-        '  // Step 1: Engine rules — shared across all agents',
-        '  const engineAction = injectBlock(filePath, getEngineRulesContent(), getEngineRulesMarker());',
+        'function injectIntoFile(filePath: string, skipEngineRules = false): InjectResult {',
+        '  // Step 1: Engine rules — shared across all agents (skip for global files)',
+        '  let engineAction: string = "skipped";',
+        '  if (!skipEngineRules) {',
+        '    engineAction = injectBlock(filePath, getEngineRulesContent(), getEngineRulesMarker());',
+        '  }',
         '',
         '  // Step 2: Agent-specific block',
         '  const agentAction = injectBlock(filePath, getClaudeMdContent(), getClaudeMdMarker());',
@@ -96,13 +101,24 @@ export function generateInjectClaudeMd(config) {
         ' * Inject into the global ~/.claude/CLAUDE.md.',
         " * Creates ~/.claude/ directory if it doesn't exist.",
         ' * This makes the activation phrase work in any project.',
+        ' * Engine rules are NOT injected globally — they live in project-level CLAUDE.md only.',
         ' */',
         'export function injectClaudeMdGlobal(): InjectResult {',
         "  const claudeDir = join(homedir(), '.claude');",
         '  if (!existsSync(claudeDir)) {',
         '    mkdirSync(claudeDir, { recursive: true });',
         '  }',
-        "  return injectIntoFile(join(claudeDir, 'CLAUDE.md'));",
+        "  const filePath = join(claudeDir, 'CLAUDE.md');",
+        '',
+        '  // Add header comment for new files',
+        '  if (!existsSync(filePath)) {',
+        "    writeFileSync(filePath, '<!-- Global agent activation file. Engine rules live in project-level CLAUDE.md only. -->\\n', 'utf-8');",
+        '  }',
+        '',
+        '  // Self-heal: strip engine rules if they leaked into the global file',
+        '  removeBlock(filePath, getEngineRulesMarker());',
+        '',
+        '  return injectIntoFile(filePath, true);',
         '}',
         '',
         '/**',
@@ -151,6 +167,24 @@ export function generateInjectClaudeMd(config) {
         '}',
         '',
         '/**',
+        ' * Remove engine rules from the global ~/.claude/CLAUDE.md.',
+        ' * Self-healing: strips engine rules that should not be in the global file.',
+        ' */',
+        'export function removeEngineRulesFromGlobal(): { removed: boolean; path: string } {',
+        "  const filePath = join(homedir(), '.claude', 'CLAUDE.md');",
+        '  return { removed: removeBlock(filePath, getEngineRulesMarker()), path: filePath };',
+        '}',
+        '',
+        '/**',
+        ' * Remove engine rules from the global ~/.config/opencode/AGENTS.md.',
+        ' * Self-healing: strips engine rules that should not be in the global file.',
+        ' */',
+        'export function removeEngineRulesFromGlobalAgentsMd(): { removed: boolean; path: string } {',
+        "  const filePath = join(homedir(), '.config', 'opencode', 'AGENTS.md');",
+        '  return { removed: removeBlock(filePath, getEngineRulesMarker()), path: filePath };',
+        '}',
+        '',
+        '/**',
         ' * Check if the agent marker exists in a CLAUDE.md file.',
         ' */',
         'export function hasAgentMarker(filePath: string): boolean {',
@@ -183,13 +217,24 @@ export function generateInjectClaudeMd(config) {
         ' * Inject into the global ~/.config/opencode/AGENTS.md.',
         " * Creates ~/.config/opencode/ directory if it doesn't exist.",
         ' * This makes the activation phrase work in any OpenCode project.',
+        ' * Engine rules are NOT injected globally — they live in project-level AGENTS.md only.',
         ' */',
         'export function injectAgentsMdGlobal(): InjectResult {',
         "  const opencodeDir = join(homedir(), '.config', 'opencode');",
         '  if (!existsSync(opencodeDir)) {',
         '    mkdirSync(opencodeDir, { recursive: true });',
         '  }',
-        "  return injectIntoFile(join(opencodeDir, 'AGENTS.md'));",
+        "  const filePath = join(opencodeDir, 'AGENTS.md');",
+        '',
+        '  // Add header comment for new files',
+        '  if (!existsSync(filePath)) {',
+        "    writeFileSync(filePath, '<!-- Global agent activation file. Engine rules live in project-level AGENTS.md only. -->\\n', 'utf-8');",
+        '  }',
+        '',
+        '  // Self-heal: strip engine rules if they leaked into the global file',
+        '  removeBlock(filePath, getEngineRulesMarker());',
+        '',
+        '  return injectIntoFile(filePath, true);',
         '}',
         '',
         '/**',

package/dist/templates/inject-claude-md.js.map

@@ -1 +1 @@
-{"version":3,"file":"inject-claude-md.js","sourceRoot":"","sources":["../../src/templates/inject-claude-md.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAmB;IACxD,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC;IAEnC,OAAO;QACL,+EAA+E;QAC/E,oCAAoC;QACpC,mCAAmC;QACnC,8HAA8H;QAC9H,EAAE;QACF,iCAAiC;QACjC,sBAAsB;QACtB,iBAAiB;QACjB,+CAA+C;QAC/C,0BAA0B;QAC1B,GAAG;QACH,EAAE;QACF,KAAK;QACL,iDAAiD;QACjD,wEAAwE;QACxE,6CAA6C;QAC7C,KAAK;QACL,2HAA2H;QAC3H,kDAAkD;QAClD,iDAAiD;QACjD,EAAE;QACF,gCAAgC;QAChC,wDAAwD;QACxD,uBAAuB;QACvB,KAAK;QACL,EAAE;QACF,qDAAqD;QACrD,EAAE;QACF,yCAAyC;QACzC,qDAAqD;QACrD,iDAAiD;QACjD,0BAA0B;QAC1B,iFAAiF;QACjF,8DAA8D;QAC9D,OAAO;QACP,0BAA0B;QAC1B,sHAAsH;QACtH,kDAAkD;QAClD,yBAAyB;QACzB,OAAO;QACP,wGAAwG;QACxG,gDAAgD;QAChD,uBAAuB;QACvB,KAAK;QACL,EAAE;QACF,kEAAkE;QAClE,6EAA6E;QAC7E,sBAAsB;QACtB,GAAG;QACH,EAAE;QACF,KAAK;QACL,6DAA6D;QAC7D,IAAI;QACJ,+DAA+D;QAC/D,0EAA0E;QAC1E,4DAA4D;QAC5D,aAAa,MAAM,SAAS;QAC5B,KAAK;QACL,2DAA2D;QAC3D,sDAAsD;QACtD,gGAAgG;QAChG,EAAE;QACF,mCAAmC;QACnC,yFAAyF;QACzF,EAAE;QACF,YAAY;QACZ,qBAAqB;QACrB,qBAAqB;QACrB,mEAAmE;QACnE,8CAA8C;QAC9C,MAAM;QACN,GAAG;QACH,EAAE;QACF,KAAK;QACL,mDAAmD;QACnD,8DAA8D;QAC9D,iDAAiD;QACjD,KAAK;QACL,qEAAqE;QACrE,0DAA0D;QAC1D,GAAG;QACH,EAAE;QACF,KAAK;QACL,gDAAgD;QAChD,sDAAsD;QACtD,0DAA0D;QAC1D,KAAK;QACL,wDAAwD;QACxD,iDAAiD;QACjD,iCAAiC;QACjC,gDAAgD;QAChD,KAAK;QACL,wDAAwD;QACxD,GAAG;QACH,EAAE;QACF,KAAK;QACL,iDAAiD;QACjD,KAAK;QACL,mEAAmE;QACnE,4CAA4C;QAC5C,qDAAqD;QACrD,kDAAkD;QAClD,iDAAiD;QACjD,mDAAmD;QACnD,sCAAsC;QACtC,+CAA+C;QAC/C,oCAAoC;QACpC,oEAAoE;QACpE,iFAAiF;QACjF,uEAAuE;QACvE,oDAAoD;QACpD,gBAAgB;QAChB,GAAG;QACH,EAAE;QACF,KAAK;QACL,8DAA8D;QAC9D,8DAA8D;QAC9D,uCAAuC;QACvC,KAAK;QACL,8EAA8E;QAC9E,6DAA6D;QAC7D,mFAAmF;QACnF,GAAG;QACH,EAAE;QACF,KAAK;QACL,mDAAmD;QACnD,KAAK;QACL,2FAA2F;QAC3F,oDAAoD;QACpD,mFAAmF;QACnF,GAAG;QACH,EAAE;QACF,KAAK;QACL,4CAA4C;QAC5C,gDAAgD;QAChD,KAAK;QACL,gEAAgE;QAChE,yDAAyD;QACzD,GAAG;QACH,EAAE;QACF,KAAK;QACL,0DAA0D;QAC1D,KAAK;QACL,6DAA6D;QAC7D,4CAA4C;QAC5C,oDAAoD;QACpD,mCAAmC,MAAM,SAAS;QAClD,GAAG;QACH,EAAE;QACF,KAAK;QACL,mEAAmE;QACnE,KAAK;QACL,6DAA6D;QAC7D,4CAA4C;QAC5C,oDAAoD;QACpD,uEAAuE;QACvE,GAAG;QACH,EAAE;QACF,mEAAmE;QACnE,EAAE;QACF,KAAK;QACL,oDAAoD;QACpD,+EAA+E;QAC/E,8DAA8D;QAC9D,KAAK;QACL,qEAAqE;QACrE,0DAA0D;QAC1D,GAAG;QACH,EAAE;QACF,KAAK;QACL,yDAAyD;QACzD,+DAA+D;QAC/D,mEAAmE;QACnE,KAAK;QACL,wDAAwD;QACxD,+DAA+D;QAC/D,mCAAmC;QACnC,kDAAkD;QAClD,KAAK;QACL,0DAA0D;QAC1D,GAAG;QACH,EAAE;QACF,KAAK;QACL,mDAAmD;QACnD,KAAK;QACL,2FAA2F;QAC3F,oDAAoD;QACpD,mFAAmF;QACnF,GAAG;QACH,EAAE;QACF,KAAK;QACL,uEAAuE;QACvE,KAAK;QACL,8EAA8E;QAC9E,yEAAyE;QACzE,mFAAmF;QACnF,GAAG;QACH,EAAE;QACF,KAAK;QACL,2DAA2D;QAC3D,KAAK;QACL,uEAAuE;QACvE,4CAA4C;QAC5C,oDAAoD;QACpD,mCAAmC,MAAM,SAAS;QAClD,GAAG;KACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"inject-claude-md.js","sourceRoot":"","sources":["../../src/templates/inject-claude-md.ts"],"names":[],"mappings":"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"}

package/dist/templates/section-parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Section parser for marker-delimited engine rules content.
+ *
+ * Extracts `<!-- soleri:xxx -->` sections from the engine rules markdown,
+ * enabling selective inclusion of feature modules.
+ *
+ * Single-pass: splits on `## ` headings, maps chunks to markers, filters.
+ */
+export interface ParsedSection {
+    /** e.g. 'soleri:response-integrity' */
+    marker: string;
+    /** Full text including heading and marker comment */
+    content: string;
+}
+export interface ParsedContent {
+    /** Everything before the first section */
+    preamble: string;
+    /** Ordered list of parsed sections */
+    sections: ParsedSection[];
+    /** Closing marker line and anything after */
+    closing: string;
+}
+/**
+ * Parse marker-delimited sections from engine rules content.
+ *
+ * Strategy: split on `## ` heading boundaries, then classify each chunk
+ * as preamble, section (has a marker), or closing (has closing marker).
+ */
+export declare function parseSections(content: string): ParsedContent;
+/**
+ * Rebuild content from parsed sections, including only allowed markers.
+ */
+export declare function filterSections(parsed: ParsedContent, allowedMarkers: Set<string>): string;

package/dist/templates/section-parser.js

@@ -0,0 +1,75 @@
+/**
+ * Section parser for marker-delimited engine rules content.
+ *
+ * Extracts `<!-- soleri:xxx -->` sections from the engine rules markdown,
+ * enabling selective inclusion of feature modules.
+ *
+ * Single-pass: splits on `## ` headings, maps chunks to markers, filters.
+ */
+const SECTION_MARKER_RE = /<!-- (soleri:[a-z-]+) -->/;
+const CLOSING_MARKER = '<!-- /soleri:engine-rules -->';
+/**
+ * Parse marker-delimited sections from engine rules content.
+ *
+ * Strategy: split on `## ` heading boundaries, then classify each chunk
+ * as preamble, section (has a marker), or closing (has closing marker).
+ */
+export function parseSections(content) {
+    // Split at each `## ` heading — lookahead preserves the heading in the chunk
+    const chunks = content.split(/(?=^## )/m);
+    let preamble = '';
+    const sections = [];
+    let closing = '';
+    let foundFirstSection = false;
+    for (const chunk of chunks) {
+        // Check if this chunk contains the closing marker
+        const closingIdx = chunk.indexOf(CLOSING_MARKER);
+        if (closingIdx !== -1) {
+            // Content before closing marker belongs to last section or preamble
+            const beforeClosing = chunk.slice(0, closingIdx);
+            const afterClosing = chunk.slice(closingIdx);
+            if (beforeClosing.trim()) {
+                const markerMatch = beforeClosing.match(SECTION_MARKER_RE);
+                if (markerMatch && markerMatch[1] !== 'soleri:engine-rules') {
+                    sections.push({ marker: markerMatch[1], content: beforeClosing });
+                    foundFirstSection = true;
+                }
+                else if (!foundFirstSection) {
+                    preamble += beforeClosing;
+                }
+            }
+            closing = afterClosing;
+            continue;
+        }
+        // Check if chunk has a section marker
+        const markerMatch = chunk.match(SECTION_MARKER_RE);
+        if (markerMatch && markerMatch[1] !== 'soleri:engine-rules') {
+            sections.push({ marker: markerMatch[1], content: chunk });
+            foundFirstSection = true;
+        }
+        else {
+            // No marker — this is preamble (before first section)
+            if (!foundFirstSection) {
+                preamble += chunk;
+            }
+        }
+    }
+    return { preamble, sections, closing };
+}
+/**
+ * Rebuild content from parsed sections, including only allowed markers.
+ */
+export function filterSections(parsed, allowedMarkers) {
+    const parts = [parsed.preamble];
+    for (const section of parsed.sections) {
+        if (allowedMarkers.has(section.marker)) {
+            let text = section.content;
+            if (!text.endsWith('\n'))
+                text += '\n';
+            parts.push(text);
+        }
+    }
+    parts.push(parsed.closing);
+    return parts.join('\n');
+}
+//# sourceMappingURL=section-parser.js.map

package/dist/templates/section-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-parser.js","sourceRoot":"","sources":["../../src/templates/section-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,MAAM,iBAAiB,GAAG,2BAA2B,CAAC;AACtD,MAAM,cAAc,GAAG,+BAA+B,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,6EAA6E;IAC7E,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAE1C,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,kDAAkD;QAClD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACjD,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;YACtB,oEAAoE;YACpE,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;YACjD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAE7C,IAAI,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;gBACzB,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;gBAC3D,IAAI,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,qBAAqB,EAAE,CAAC;oBAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;oBAClE,iBAAiB,GAAG,IAAI,CAAC;gBAC3B,CAAC;qBAAM,IAAI,CAAC,iBAAiB,EAAE,CAAC;oBAC9B,QAAQ,IAAI,aAAa,CAAC;gBAC5B,CAAC;YACH,CAAC;YACD,OAAO,GAAG,YAAY,CAAC;YACvB,SAAS;QACX,CAAC;QAED,sCAAsC;QACtC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACnD,IAAI,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,qBAAqB,EAAE,CAAC;YAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1D,iBAAiB,GAAG,IAAI,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,sDAAsD;YACtD,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACvB,QAAQ,IAAI,KAAK,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB,EAAE,cAA2B;IAC/E,MAAM,KAAK,GAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE1C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,IAAI,IAAI,IAAI,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/templates/shared-rules.d.ts

@@ -11,3 +11,17 @@
 export declare function getEngineMarker(): string;
 /** Returns the full engine rules markdown content (with markers). */
 export declare function getEngineRulesContent(): string;
+/** Feature modules that can be selectively included in engine rules. */
+export type EngineFeature = 'vault' | 'planning' | 'brain' | 'advanced';
+/** All available feature modules. */
+export declare const ENGINE_FEATURES: readonly EngineFeature[];
+/**
+ * Returns engine rules with only selected feature modules included.
+ *
+ * Core rules are ALWAYS included. Feature modules are included when:
+ * - `features` is undefined/empty → ALL modules included (backward compatible)
+ * - `features` is specified → only listed modules + core
+ *
+ * @param features - Feature modules to include. Omit for all.
+ */
+export declare function getModularEngineRules(features?: EngineFeature[]): string;

package/dist/templates/shared-rules.js

@@ -8,6 +8,7 @@
  *
  * Uses op:name syntax — the active agent provides the tool prefix.
  */
+import { parseSections, filterSections } from './section-parser.js';
 const ENGINE_MARKER = 'soleri:engine-rules';
 export function getEngineMarker() {
     return ENGINE_MARKER;
@@ -16,6 +17,75 @@ export function getEngineMarker() {
 export function getEngineRulesContent() {
     return ENGINE_RULES_LINES.join('\n');
 }
+/** All available feature modules. */
+export const ENGINE_FEATURES = [
+    'vault',
+    'planning',
+    'brain',
+    'advanced',
+];
+/**
+ * Section markers grouped by module.
+ *
+ * 'core' sections are always included.
+ * Feature modules are included only when requested (or when no filter is specified).
+ */
+const MODULE_SECTIONS = {
+    core: [
+        'soleri:what-is-soleri',
+        'soleri:response-integrity',
+        'soleri:tool-schema-validation',
+        'soleri:memory-quality',
+        'soleri:output-formatting',
+        'soleri:clean-commits',
+        'soleri:intent-detection',
+        'soleri:overlay-mode',
+        'soleri:session',
+        'soleri:getting-started',
+        'soleri:cli',
+        'soleri:persona-self-update',
+        'soleri:workspace-routing',
+    ],
+    vault: [
+        'soleri:vault-protocol',
+        'soleri:knowledge-capture',
+        'soleri:tool-advocacy',
+        'soleri:cross-project',
+    ],
+    planning: [
+        'soleri:planning',
+        'soleri:workflow-overrides',
+        'soleri:yolo-mode',
+        'soleri:task-routing',
+        'soleri:validation-loop',
+        'soleri:verification-protocol',
+    ],
+    brain: ['soleri:brain', 'soleri:model-routing'],
+    advanced: ['soleri:subagent-identity'],
+};
+/**
+ * Returns engine rules with only selected feature modules included.
+ *
+ * Core rules are ALWAYS included. Feature modules are included when:
+ * - `features` is undefined/empty → ALL modules included (backward compatible)
+ * - `features` is specified → only listed modules + core
+ *
+ * @param features - Feature modules to include. Omit for all.
+ */
+export function getModularEngineRules(features) {
+    if (!features || features.length === 0) {
+        return getEngineRulesContent();
+    }
+    const allowedMarkers = new Set(MODULE_SECTIONS.core);
+    for (const feature of features) {
+        const sections = MODULE_SECTIONS[feature];
+        if (sections)
+            for (const m of sections)
+                allowedMarkers.add(m);
+    }
+    const parsed = parseSections(getEngineRulesContent());
+    return filterSections(parsed, allowedMarkers);
+}
 const ENGINE_RULES_LINES = [
     `<!-- ${ENGINE_MARKER} -->`,
     '',
@@ -212,6 +282,41 @@ const ENGINE_RULES_LINES = [
     '| skipped | ... | medium | ... |',
     '```',
     '',
+    // ─── Workflow Overrides ──────────────────────────────────
+    '## Workflow Overrides',
+    '<!-- soleri:workflow-overrides -->',
+    '',
+    "The engine reads `gates.yaml` and `tools.yaml` from your agent's `workflows/` directory and merges them into plans.",
+    '',
+    '**Three files, three purposes:**',
+    '- `prompt.md` — Claude reads this as narrative guidance (what to do)',
+    '- `gates.yaml` — Engine enforces these as plan checkpoints (when to validate)',
+    '- `tools.yaml` — Engine merges these into plan steps (what tools to use)',
+    '',
+    '**Default mapping** (workflow name → orchestration intent):',
+    '| Workflow | Intent |',
+    '|----------|--------|',
+    '| `feature-dev` | BUILD |',
+    '| `bug-fix` | FIX |',
+    '| `code-review` | REVIEW |',
+    '| `context-handoff` | HANDOFF |',
+    '',
+    'Override in `agent.yaml`:',
+    '```yaml',
+    'workflowIntents:',
+    '  my-custom-workflow: BUILD',
+    '  security-review: REVIEW',
+    '```',
+    '',
+    '**How it works:**',
+    '1. You call `orchestrate_plan` with a task',
+    '2. Engine detects intent (e.g., REVIEW)',
+    '3. Engine checks if your agent has a matching workflow (e.g., `workflows/code-review/`)',
+    '4. If found: workflow gates are appended to plan gates, workflow tools are merged into plan steps',
+    '5. If not found: current behavior unchanged',
+    '',
+    '**Editing workflows changes engine behavior.** If you modify `gates.yaml` in `workflows/code-review/`, the next REVIEW plan will include your custom gates.',
+    '',
     // ─── YOLO Mode ──────────────────────────────────────────
     '## YOLO Mode',
     '<!-- soleri:yolo-mode -->',
@@ -582,6 +687,17 @@ const ENGINE_RULES_LINES = [
     'The scaffolded agent is ready immediately — no build step, no npm install for the agent itself.',
     'Git is initialized by default (`git init` + initial commit). Use `--no-git` to skip. After scaffolding, the CLI offers to set up a remote via `gh repo create` (if gh CLI is available) or a manual remote URL. The `--yes` flag enables git init but skips the remote prompt.',
     '',
+    '### Browsable Knowledge',
+    '',
+    "Your agent's vault is automatically synced to `knowledge/vault/` as markdown files. Browse them in VS Code, Obsidian, or any editor.",
+    '',
+    '```bash',
+    '# Export vault to a custom location (e.g., Obsidian)',
+    'soleri vault export --path ~/obsidian-vault/soleri',
+    '```',
+    '',
+    'The engine indexes entries in SQLite for fast search, but you always own the files.',
+    '',
     '### Updating Soleri',
     '',
     '| What to update | Command |',
@@ -612,28 +728,28 @@ const ENGINE_RULES_LINES = [
     '',
     '### How Your CLAUDE.md is Built',
     '',
-    'Your CLAUDE.md is **auto-generated** — never edit it manually. It gets regenerated by `composeClaudeMd()` in these scenarios:',
-    '',
-    '| Trigger | How |',
-    '|---------|-----|',
-    '| `soleri dev` | Hot-reloads and regenerates on file changes |',
-    '| `soleri agent refresh` | Explicitly regenerates from latest templates |',
-    '| `soleri agent update` | After engine update, regenerates to pick up new rules |',
-    '| Scaffold (`create-soleri`) | Generates initial CLAUDE.md for new agents |',
+    'Your CLAUDE.md is **auto-generated** — never edit it manually (except inside `<!-- user:custom -->` markers). Regenerated by `soleri dev`, `soleri agent refresh`, `soleri agent update`, and on scaffold.',
     '',
     'The composition pipeline assembles CLAUDE.md from:',
     '',
     '1. **Agent identity** — from `agent.yaml`',
     '2. **Custom instructions** — from `instructions/user.md` (priority placement, before engine rules)',
-    '3. **Engine rules** — from `@soleri/forge` shared rules (this section)',
+    '3. **Engine rules** — modular, controlled by `engine.features` in `agent.yaml`',
     '4. **User instructions** — from `instructions/*.md` (alphabetically sorted, excluding `user.md` and `_engine.md`)',
     '5. **Tools table** — from engine registration',
     '6. **Workflow index** — from `workflows/`',
     '7. **Skills index** — from `skills/`',
     '',
-    '`instructions/user.md` is the recommended place for your most important agent-specific rules — it appears early in CLAUDE.md for maximum influence on model behavior. Other `instructions/*.md` files are included after engine rules.',
+    '**Modular engine rules:** The `engine.features` array in `agent.yaml` controls which rule modules are included. Available: `vault`, `planning`, `brain`, `advanced`. Core rules are always included. Default (no features specified) = all modules.',
     '',
-    'When the engine updates (`@soleri/core` or `@soleri/forge`), running `soleri agent refresh` regenerates CLAUDE.md with the latest shared rules. Your own `instructions/*.md` files are where agent-specific behavior lives — those survive regeneration.',
+    '### What Survives Regeneration',
+    '',
+    '| Source | Survives? |',
+    '|--------|-----------|',
+    '| `instructions/*.md` | Yes — re-read on every regen |',
+    '| `<!-- user:custom -->` zone in CLAUDE.md | Yes — extracted and re-injected |',
+    '| `agent.yaml` | Drives regen (source of truth) |',
+    '| Manual CLAUDE.md edits outside markers | No — overwritten, warning logged |',
     '',
     '### System Requirements',
     '',
@@ -659,6 +775,14 @@ const ENGINE_RULES_LINES = [
     '| `soleri dev` | Run agent in development mode (stdio MCP) |',
     '| `soleri test` | Run agent tests (`--watch`, `--coverage`) |',
     '',
+    '### Vault',
+    '',
+    '| Command | What it does |',
+    '|---------|-------------|',
+    '| `soleri vault export` | Export vault entries as browsable markdown files |',
+    '| `soleri vault export --path <dir>` | Export to custom directory (e.g., Obsidian vault) |',
+    '| `soleri vault export --domain <name>` | Export entries from a specific domain |',
+    '',
     '### Knowledge & Packs',
     '',
     '| Command | What it does |',
@@ -793,6 +917,63 @@ const ENGINE_RULES_LINES = [
     '- Does NOT apply to new code, new files, or greenfield features',
     '- Advisory only — flags warnings, never blocks execution',
     '',
+    // ─── Subagent Identity & Behavioral Contract ──────────────
+    '## Subagent Identity & Behavioral Contract',
+    '<!-- soleri:subagent-identity -->',
+    '',
+    'When the orchestrator fans out work to subagents, two agent types are available. The orchestrator routes based on task complexity.',
+    '',
+    '### Agent Types',
+    '',
+    '| Type | When to use | Capabilities | Overhead |',
+    '|------|------------|--------------|----------|',
+    '| **Claude Code worker** | Mechanical tasks: single-file edits, test fixes, config changes, clear specs | File read/write/edit, git, shell, tests | Low — fast, stateless |',
+    '| **Soleri agent instance** | Complex tasks: design decisions, multi-file with cross-cutting concerns, new dependencies | Full agent lifecycle: vault, brain, planning, knowledge capture | High — full activation cycle |',
+    '',
+    '### Routing Table',
+    '',
+    '| Signal | Route to |',
+    '|--------|---------|',
+    '| Single file, clear acceptance criteria, spec fully decided | Claude Code worker |',
+    '| Approach already described in parent plan | Claude Code worker |',
+    '| Touches 3+ files with cross-cutting concerns | Soleri agent instance |',
+    '| Unresolved design decisions not in parent plan | Soleri agent instance |',
+    '| New dependencies or architectural choices needed | Soleri agent instance |',
+    '',
+    '### The Rules',
+    '',
+    '1. **Orchestrator owns all decisions.** Subagents execute specs — they do NOT make design decisions. If a subagent encounters ambiguity, it returns to the orchestrator with a question, not a guess.',
+    '2. **Subagents MUST NOT create plans.** Only the parent orchestrator creates plans. Subagents receive task prompts with exact scope, file boundaries, and acceptance criteria. They execute and return results.',
+    '3. **Worktree cleanup is guaranteed.** Three-layer defense: (a) `finally` block in dispatcher cleans per-task worktree, (b) `cleanupAll()` runs after batch completion, (c) `SessionStart` hook prunes orphaned worktrees on every session.',
+    '4. **Escalation protocol.** When a subagent hits ambiguity or a blocking issue, it MUST return to the orchestrator with a clear description of the blocker. The orchestrator decides — ask the user or resolve — then re-dispatches.',
+    '5. **No freelancing.** Subagents stay within their assigned file boundaries and acceptance criteria. No "while I\'m here" improvements, no scope creep, no out-of-scope commits.',
+    '6. **UX output contract.** The orchestrator communicates subagent work to the user at three verbosity levels:',
+    '',
+    '### UX Output Format',
+    '',
+    '**Minimal (default):**',
+    '```',
+    'Dispatching N tasks in parallel...',
+    '',
+    '✓ N/N complete. M patterns captured to vault.',
+    '  → Decisions: [list any design decisions made]',
+    '```',
+    '',
+    '**Detailed (on request or for complex work):**',
+    '```',
+    '| # | Task | Agent | Status | Knowledge |',
+    '|---|------|-------|--------|-----------|',
+    '| 1 | Description | Worker/Instance | Done ✓ | — |',
+    '```',
+    '',
+    '**Verbose (debugging):** Full lifecycle state, vault entries, plan IDs.',
+    '',
+    '### User Overrides',
+    '',
+    '- "Use full agent for everything" → all subagents are Soleri agent instances',
+    '- "Just use workers" → all subagents are Claude Code workers (no lifecycle overhead)',
+    '- Default: hybrid routing based on complexity',
+    '',
     `<!-- /${ENGINE_MARKER} -->`,
 ];
 //# sourceMappingURL=shared-rules.js.map