@soleri/forge 9.8.0 → 9.10.0

package/src/templates/shared-rules.ts

@@ -9,6 +9,8 @@
  * 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(): string {
@@ -20,6 +22,83 @@ export function getEngineRulesContent(): string {
   return ENGINE_RULES_LINES.join('\n');
 }
 
+// ─── Modular Engine Rules ────────────────────────────────────────────
+
+/** Feature modules that can be selectively included in engine rules. */
+export type EngineFeature = 'vault' | 'planning' | 'brain' | 'advanced';
+
+/** All available feature modules. */
+export const ENGINE_FEATURES: readonly EngineFeature[] = [
+  'vault',
+  'planning',
+  'brain',
+  'advanced',
+] as const;
+
+/**
+ * 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: Record<'core' | EngineFeature, readonly string[]> = {
+  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?: EngineFeature[]): string {
+  if (!features || features.length === 0) {
+    return getEngineRulesContent();
+  }
+
+  const allowedMarkers = new Set<string>(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: string[] = [
   `<!-- ${ENGINE_MARKER} -->`,
   '',
@@ -223,6 +302,42 @@ const ENGINE_RULES_LINES: string[] = [
   '```',
   '',
 
+  // ─── 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 -->',
@@ -606,6 +721,17 @@ const ENGINE_RULES_LINES: string[] = [
   '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 |',
@@ -636,28 +762,28 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### 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.',
+  '',
+  '### What Survives Regeneration',
   '',
-  '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.',
+  '| 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',
   '',
@@ -684,6 +810,14 @@ const ENGINE_RULES_LINES: string[] = [
   '| `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 |',
@@ -822,5 +956,63 @@ const ENGINE_RULES_LINES: string[] = [
   '- 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} -->`,
 ];