@soleri/forge 9.8.0 → 9.10.0

package/src/scaffold-filetree.ts

@@ -13,7 +13,8 @@ import { fileURLToPath } from 'node:url';
 import { stringify as yamlStringify } from 'yaml';
 import type { AgentYaml, AgentYamlInput } from './agent-schema.js';
 import { AgentYamlSchema } from './agent-schema.js';
-import { getEngineRulesContent } from './templates/shared-rules.js';
+import { getModularEngineRules } from './templates/shared-rules.js';
+import type { EngineFeature } from './templates/shared-rules.js';
 import { composeClaudeMd } from './compose-claude-md.js';
 import { generateSkills } from './templates/skills.js';
 import type { AgentConfig } from './types.js';
@@ -133,7 +134,9 @@ When building a new feature, adding functionality, or creating components.
 - Link new entries to related knowledge: \`op:link_entries\`
 - Complete orchestration: \`op:orchestrate_complete\`
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: brainstorming
     requirement: Requirements are clear and user has approved the approach
     check: user-approval
@@ -150,7 +153,9 @@ When building a new feature, adding functionality, or creating components.
     requirement: Knowledge captured to vault with links
     check: knowledge-captured
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_links op:link_entries
@@ -191,7 +196,9 @@ When fixing bugs, resolving errors, or addressing regressions.
 - If the bug reveals a pattern or anti-pattern, capture it: \`op:capture_knowledge\`
 - Complete orchestration: \`op:orchestrate_complete\`
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: pre-execution
     requirement: Root cause identified and fix plan approved
     check: plan-approved
@@ -204,7 +211,9 @@ When fixing bugs, resolving errors, or addressing regressions.
     requirement: Anti-pattern captured if applicable
     check: knowledge-captured
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_plan op:create_plan
@@ -238,12 +247,16 @@ When reviewing code, auditing quality, or checking for issues.
 ### 4. Capture
 - If review reveals new patterns or anti-patterns, capture them: \`op:capture_knowledge\`
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: completion
     requirement: All blocking issues addressed
     check: issues-resolved
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_brain op:recommend
@@ -275,7 +288,9 @@ Before crossing a context window boundary — \`/clear\`, context compaction, or
 - Use plan IDs to look up active plans: \`op:orchestrate_status\`
 - Continue from where the handoff left off
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: pre-transition
     requirement: Handoff document generated with current state
     check: handoff-generated
@@ -284,7 +299,9 @@ Before crossing a context window boundary — \`/clear\`, context compaction, or
     requirement: New context has loaded handoff and can reference active plans
     check: context-restored
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_memory op:handoff_generate
   - soleri_memory op:session_capture
   - soleri_orchestrate op:orchestrate_status
@@ -551,8 +568,14 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     filesCreated,
   );
 
-  // ─── 5. Write engine rules ──────────────────────────────────
-  writeFile(agentDir, 'instructions/_engine.md', getEngineRulesContent(), filesCreated);
+  // ─── 5. Write engine rules (modular — respects engine.features) ─────
+  const engineFeatures = config.engine?.features as EngineFeature[] | undefined;
+  writeFile(
+    agentDir,
+    'instructions/_engine.md',
+    getModularEngineRules(engineFeatures),
+    filesCreated,
+  );
 
   // ─── 6. Write user instruction files ────────────────────────
   // Generate user.md — user-editable file with priority placement in CLAUDE.md

package/src/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/src/templates/inject-claude-md.ts

@@ -70,10 +70,15 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     ' * `<!-- 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());',
@@ -99,13 +104,24 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     ' * 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);',
     '}',
     '',
     '/**',
@@ -154,6 +170,24 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     '}',
     '',
     '/**',
+    ' * 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 {',
@@ -186,13 +220,24 @@ export function generateInjectClaudeMd(config: AgentConfig): string {
     ' * 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/src/templates/section-parser.ts

@@ -0,0 +1,97 @@
+/**
+ * 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;
+}
+
+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: string): ParsedContent {
+  // Split at each `## ` heading — lookahead preserves the heading in the chunk
+  const chunks = content.split(/(?=^## )/m);
+
+  let preamble = '';
+  const sections: ParsedSection[] = [];
+  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: ParsedContent, allowedMarkers: Set<string>): string {
+  const parts: string[] = [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');
+}