@soleri/forge 9.7.2 → 9.9.0

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/setup-script.ts

@@ -322,6 +322,77 @@ else
     echo "Note: Add $AGENT_DIR/scripts to PATH, or symlink $AGENT_DIR/scripts/$AGENT_NAME to /usr/local/bin/$AGENT_NAME"
   fi
 fi
+
+# Configure OpenCode enforcement plugin (hooks)
+OPENCODE_PLUGINS_DIR="$AGENT_DIR/.opencode/plugins"
+ENFORCEMENT_PLUGIN="$OPENCODE_PLUGINS_DIR/soleri-enforcement.ts"
+
+echo ""
+echo "Configuring OpenCode enforcement plugin..."
+mkdir -p "$OPENCODE_PLUGINS_DIR"
+
+if [ -f "$ENFORCEMENT_PLUGIN" ]; then
+  echo "[ok] Enforcement plugin already exists — skipping"
+else
+  cat > "$ENFORCEMENT_PLUGIN" << PLUGIN
+/**
+ * Soleri enforcement plugin for OpenCode.
+ * Auto-generated by setup script — do not edit manually.
+ *
+ * Hooks:
+ * - tool.execute.before: block destructive commands (anti-deletion)
+ * - session.compacted: capture session summary before context compaction
+ * - session.created: clean stale git worktrees on session start
+ */
+
+const DESTRUCTIVE_PATTERNS = [
+  /\\brm\\s+(-[rRf]+\\s+|--force\\s+|--recursive\\s+)/,
+  /\\brmdir\\b/,
+  /\\bgit\\s+push\\s+--force\\b/,
+  /\\bgit\\s+push\\s+-f\\b/,
+  /\\bgit\\s+reset\\s+--hard\\b/,
+  /\\bgit\\s+clean\\s+-[a-zA-Z]*f/,
+];
+
+export default {
+  hooks: {
+    'tool.execute.before': (ctx) => {
+      // Anti-deletion: intercept destructive commands
+      const input = JSON.stringify(ctx.input ?? '');
+      for (const pattern of DESTRUCTIVE_PATTERNS) {
+        if (pattern.test(input)) {
+          throw new Error(
+            '[soleri-anti-deletion] BLOCKED: Destructive command detected. ' +
+            'Use explicit confirmation or a safer alternative.'
+          );
+        }
+      }
+    },
+    'session.compacted': (ctx) => {
+      // Session capture: call op:session_capture before context compaction
+      console.info(
+        '[soleri-session-capture] 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.'
+      );
+    },
+    'session.created': (ctx) => {
+      // Worktree cleanup: clean stale git worktrees on session start
+      try {
+        const { execSync } = require('child_process');
+        execSync('sh $AGENT_DIR/scripts/clean-worktrees.sh', {
+          timeout: 10000,
+          stdio: 'pipe',
+        });
+      } catch (err) {
+        console.warn('[soleri-worktree-cleanup] Failed to clean worktrees:', err.message);
+      }
+    },
+  },
+};
+PLUGIN
+  echo "[ok] Created enforcement plugin at $ENFORCEMENT_PLUGIN"
+fi
 `
     : '';
 

package/src/templates/shared-rules.ts

@@ -223,6 +223,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 -->',
@@ -341,13 +377,29 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### The Non-Negotiable Rule',
   '',
-  '`op:orchestrate_complete` runs for EVERY task — simple or complex. This captures:',
+  '`op:orchestrate_complete` runs for EVERY task — simple or complex. But it is **user-gated**: never auto-complete without confirmation.',
+  '',
+  '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.',
   '',
+  '### Reconciliation Triggers',
+  '',
+  '`op:orchestrate_complete` is triggered by one of three conditions — all require user confirmation before running.',
+  '',
+  '| Trigger | Condition | Agent Action |',
+  '|---------|-----------|--------------|',
+  '| **Explicit** | User says "done", "ship it", "looks good", "wrap up" | Call `op:orchestrate_complete` immediately |',
+  '| **Plan-complete** | All plan tasks reach terminal state (completed/skipped/failed) | Ask: "All tasks are complete. Want me to wrap up and capture what we learned, or is there more to fix?" |',
+  '| **Idle** | Plan in `executing` state with no recent task work | Ask: "We\'ve been idle on this plan. Ready to wrap up, or still working?" |',
+  '',
+  '**NEVER auto-complete without asking the user.** The agent detects readiness but the user decides when to finalize.',
+  '',
+  'Use `op:orchestrate_status` to check plan readiness — it includes a `readiness` field with `allTasksTerminal`, `terminalCount`, `totalCount`, and `idleSince` for the active plan.',
+  '',
   '### Exceptions (skip assessment, execute directly)',
   '',
   '- Read-only operations (search, status, health check)',
@@ -588,6 +640,18 @@ 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',
   '',
@@ -631,11 +695,14 @@ const ENGINE_RULES_LINES: string[] = [
   'The composition pipeline assembles CLAUDE.md from:',
   '',
   '1. **Agent identity** — from `agent.yaml`',
-  '2. **Engine rules** — from `@soleri/forge` shared rules (this section)',
-  '3. **User instructions** — from `instructions/*.md` (alphabetically sorted)',
-  '4. **Tools table** — from engine registration',
-  '5. **Workflow index** — from `workflows/`',
-  '6. **Skills index** — from `skills/`',
+  '2. **Custom instructions** — from `instructions/user.md` (priority placement, before engine rules)',
+  '3. **Engine rules** — from `@soleri/forge` shared rules (this section)',
+  '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.',
   '',
   '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.',
   '',
@@ -664,6 +731,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 |',
@@ -687,6 +762,10 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '### Hooks & Skills',
   '',
+  'Your agent ships with **essential skills** by default (agent-guide, agent-persona, vault-navigator, vault-capture, systematic-debugging, writing-plans, context-resume). Install more with `soleri skills install <name>`. List available skills with `soleri skills list`.',
+  '',
+  'To scaffold all skills instead, set `skillsFilter: all` in `agent.yaml`.',
+  '',
   '| Command | What it does |',
   '|---------|-------------|',
   '| `soleri hooks list-packs` | Show available hook packs and their status |',
@@ -701,6 +780,7 @@ const ENGINE_RULES_LINES: string[] = [
   '|---------|-------------|',
   '| `soleri install` | Register agent as MCP server (`--target opencode\\|claude\\|codex\\|all`) |',
   '| `soleri uninstall` | Remove agent MCP server entry |',
+  '| `soleri create --no-git` | Scaffold agent without git initialization |',
   '| `soleri governance --show` | Show vault governance policy |',
   '| `soleri governance --preset <name>` | Set policy preset (strict\\|moderate\\|permissive) |',
   '| `soleri upgrade` | Upgrade @soleri/cli (`--check` to preview) |',
@@ -749,6 +829,28 @@ const ENGINE_RULES_LINES: string[] = [
   '- Any file inside `@soleri/core` or `@soleri/forge`',
   '',
 
+  // ─── Workspace Routing ─────────────────────────────────────
+  '## Workspace Routing',
+  '<!-- soleri:workspace-routing -->',
+  '',
+  'Agents can define **workspaces** — scoped context areas with their own CONTEXT.md files — and a **routing table** that maps task patterns to workspaces.',
+  '',
+  '### How It Works',
+  '',
+  '1. When a task matches a routing pattern, navigate to that workspace.',
+  "2. Load the workspace's CONTEXT.md for task-specific instructions and context.",
+  '3. Activate only the skills listed in the routing entry.',
+  '4. If no pattern matches, use the default root context (agent-level CLAUDE.md).',
+  '',
+  '### Routing Rules',
+  '',
+  '- Patterns are matched by semantic similarity, not exact string match.',
+  '- The routing table is defined in `agent.yaml` under the `routing:` key.',
+  '- Workspaces are directories under `workspaces/{id}/` with a CONTEXT.md file.',
+  '- When entering a workspace, its CONTEXT.md supplements (not replaces) the root context.',
+  '- Skills listed in the routing entry are prioritized but do not prevent other skills from activating.',
+  '',
+
   // ─── Verification Protocol ─────────────────────────────────
   '## Verification Protocol',
   '<!-- soleri:verification-protocol -->',
@@ -775,5 +877,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} -->`,
 ];