@soleri/forge 9.11.0 → 9.12.1

package/src/templates/readme.ts

@@ -86,9 +86,9 @@ export function generateReadme(config: AgentConfig): string {
 
   const skillsInstallNote =
     claudeSetup && codexSetup
-      ? 'Skills are installed to `~/.claude/commands/` and `~/.codex/skills/` during setup. Run `./scripts/setup.sh` to install or reinstall.'
+      ? 'Skills are installed to `~/.claude/skills/` and `~/.codex/skills/` during setup. Run `./scripts/setup.sh` to install or reinstall.'
       : claudeSetup
-        ? 'Skills are installed to `~/.claude/commands/` during setup. Run `./scripts/setup.sh` to install or reinstall.'
+        ? 'Skills are installed to `~/.claude/skills/` during setup. Run `./scripts/setup.sh` to install or reinstall.'
         : 'Skills are installed to `~/.codex/skills/` during setup. Run `./scripts/setup.sh` to install or reinstall.';
 
   return `# ${config.name} — ${config.role}
@@ -155,33 +155,33 @@ ${skillsLead}
 
 | Skill | Description |
 |-------|-------------|
-| \`/test-driven-development\` | Red-green-refactor TDD workflow with vault-informed test patterns |
-| \`/systematic-debugging\` | Root cause investigation — vault search, web search, then diagnose |
-| \`/verification-before-completion\` | Evidence-based completion claims with system diagnostics |
-| \`/brainstorming\` | Collaborative design exploration with vault + web research first |
-| \`/writing-plans\` | Implementation plans with quality grading and auto-improvement |
-| \`/executing-plans\` | Batch execution with loop tracking and plan reconciliation |
-| \`/fix-and-learn\` | Fix bugs and capture root cause — vault search before any fix |
-| \`/code-patrol\` | Review code against YOUR vault patterns, not generic lint rules |
+| \`/soleri-test-driven-development\` | Red-green-refactor TDD workflow with vault-informed test patterns |
+| \`/soleri-systematic-debugging\` | Root cause investigation — vault search, web search, then diagnose |
+| \`/soleri-verification-before-completion\` | Evidence-based completion claims with system diagnostics |
+| \`/soleri-brainstorming\` | Collaborative design exploration with vault + web research first |
+| \`/soleri-writing-plans\` | Implementation plans with quality grading and auto-improvement |
+| \`/soleri-executing-plans\` | Batch execution with loop tracking and plan reconciliation |
+| \`/soleri-fix-and-learn\` | Fix bugs and capture root cause — vault search before any fix |
+| \`/soleri-code-patrol\` | Review code against YOUR vault patterns, not generic lint rules |
 
 **Knowledge Management:**
 
 | Skill | Description |
 |-------|-------------|
-| \`/vault-navigator\` | Intelligent vault search — tags, domains, age reports, cross-project |
-| \`/vault-capture\` | Persist knowledge with curator grooming and governance |
-| \`/knowledge-harvest\` | Point at any doc/code — auto-extract patterns into vault |
-| \`/brain-debrief\` | Intelligence report — strengths, gaps, cross-project insights |
+| \`/soleri-vault-navigator\` | Intelligent vault search — tags, domains, age reports, cross-project |
+| \`/soleri-vault-capture\` | Persist knowledge with curator grooming and governance |
+| \`/soleri-knowledge-harvest\` | Point at any doc/code — auto-extract patterns into vault |
+| \`/soleri-brain-debrief\` | Intelligence report — strengths, gaps, cross-project insights |
 
 **Magic UX:**
 
 | Skill | Description |
 |-------|-------------|
-| \`/context-resume\` | "What was I working on?" — full context reconstruction |
-| \`/second-opinion\` | Decision support from vault + brain + web combined |
-| \`/retrospective\` | Data-driven sprint/week retro from actual metrics |
-| \`/onboard-me\` | Instant project knowledge tour for newcomers |
-| \`/health-check\` | Vault maintenance — duplicates, contradictions, stale entries |
+| \`/soleri-context-resume\` | "What was I working on?" — full context reconstruction |
+| \`/soleri-second-opinion\` | Decision support from vault + brain + web combined |
+| \`/soleri-retrospective\` | Data-driven sprint/week retro from actual metrics |
+| \`/soleri-onboard-me\` | Instant project knowledge tour for newcomers |
+| \`/soleri-health-check\` | Vault maintenance — duplicates, contradictions, stale entries |
 
 ${skillsInstallNote}
 

package/src/templates/setup-script.ts

@@ -102,14 +102,13 @@ else
   fi
 fi
 
-# Install skills to ~/.claude/commands/
+# Install skills to ~/.claude/skills/
 SKILLS_DIR="$AGENT_DIR/skills"
-COMMANDS_DIR="$HOME/.claude/commands"
+CLAUDE_SKILLS_DIR="$HOME/.claude/skills"
 
 if [ -d "$SKILLS_DIR" ]; then
   echo ""
   echo "Installing skills for Claude Code..."
-  mkdir -p "$COMMANDS_DIR"
   skill_installed=0
   skill_skipped=0
   for skill_dir in "$SKILLS_DIR"/*/; do
@@ -117,15 +116,36 @@ if [ -d "$SKILLS_DIR" ]; then
     skill_file="$skill_dir/SKILL.md"
     [ -f "$skill_file" ] || continue
     skill_name="$(basename "$skill_dir")"
-    dest="$COMMANDS_DIR/$skill_name.md"
+    dest_dir="$CLAUDE_SKILLS_DIR/$skill_name"
+    dest="$dest_dir/SKILL.md"
     if [ -f "$dest" ]; then
       skill_skipped=$((skill_skipped + 1))
     else
+      mkdir -p "$dest_dir"
       cp "$skill_file" "$dest"
       skill_installed=$((skill_installed + 1))
     fi
   done
   echo "[ok] Claude skills: $skill_installed installed, $skill_skipped already present"
+
+  # Migrate legacy commands to skills (one-time cleanup)
+  LEGACY_DIR="$HOME/.claude/commands"
+  if [ -d "$LEGACY_DIR" ]; then
+    legacy_migrated=0
+    for legacy_file in "$LEGACY_DIR"/*.md; do
+      [ -f "$legacy_file" ] || continue
+      legacy_name="$(basename "$legacy_file" .md)"
+      dest_dir="$CLAUDE_SKILLS_DIR/$legacy_name"
+      if [ ! -d "$dest_dir" ]; then
+        mkdir -p "$dest_dir"
+        mv "$legacy_file" "$dest_dir/SKILL.md"
+        legacy_migrated=$((legacy_migrated + 1))
+      fi
+    done
+    if [ "$legacy_migrated" -gt 0 ]; then
+      echo "[ok] Migrated $legacy_migrated legacy commands from ~/.claude/commands/ to ~/.claude/skills/"
+    fi
+  fi
 fi
 `
     : '';

package/src/templates/shared-rules.ts

@@ -301,6 +301,22 @@ const ENGINE_RULES_LINES: string[] = [
   '| skipped | ... | medium | ... |',
   '```',
   '',
+  '### Incremental Correction',
+  '',
+  'When a single step fails or produces wrong output, use `op:orchestrate_rerun_step` to re-execute it without restarting the entire plan.',
+  '',
+  '- **Target step** is marked as `rerun` and re-executed.',
+  '- **Downstream steps** are marked as `stale` (their cached output may be invalid).',
+  '- Use `cascadeTo` to also mark a range of downstream steps as `rerun` (not just stale).',
+  '- `op:plan_reconcile` includes a rerun report showing which steps were re-executed and why.',
+  '',
+  '**When to use:**',
+  '- A step produced incorrect output but the rest of the plan is fine.',
+  '- External conditions changed (e.g., a dependency was updated) and one step needs re-evaluation.',
+  '- A gate failed on a step that can be retried after a fix.',
+  '',
+  '**Anti-pattern:** Re-running steps speculatively. Only re-run when you have a clear reason.',
+  '',
 
   // ─── Workflow Overrides ──────────────────────────────────
   '## Workflow Overrides',
@@ -605,6 +621,7 @@ const ENGINE_RULES_LINES: string[] = [
   '| Debug a problem | "this is broken", "why is this failing" | `op:search_intelligent` — check vault for known bugs first |',
   '| Learn from patterns | "what works for", "recommendations" | `op:strengths` + `op:recommend` — brain-learned patterns from real usage |',
   '| Clean up knowledge | "duplicates", "clean vault", "consolidate" | `op:curator_consolidate` — automated dedup, grooming, contradiction resolution |',
+  '| Consolidate memory | "dream", "consolidate memory", "vault maintenance" | `op:dream_run` — automatic memory consolidation (runs on session start after 5+ sessions/24h, or force with `/dream`) |',
   '| Summarize session | "what did we accomplish", "wrap up" | `op:session_capture` — structured capture with knowledge extraction |',
   '| Explore capabilities | "what can you do", "help", "features" | List capabilities by category, not raw op names |',
   '',
@@ -682,6 +699,16 @@ const ENGINE_RULES_LINES: string[] = [
   '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.',
   '',
+  '### Pre-flight Manifest',
+  '',
+  'Every `session_start` response includes a `preflight` object. Use it for self-awareness:',
+  '- **tools** — full list of available facade ops (facade name, op name, description).',
+  '- **skills** — installed skill names.',
+  '- **activePlans** — plans currently in `executing` state (planId, title, status).',
+  '- **vaultSummary** — entry count, connection status, and domain list.',
+  '',
+  'Read `preflight` before calling `op:admin_tool_list` — it covers the same ground with zero extra round-trips.',
+  '',
   '### Context Compaction',
   '',
   'A PreCompact hook calls `op:session_capture` before context compaction.',
@@ -703,6 +730,18 @@ const ENGINE_RULES_LINES: string[] = [
   '| Switching to a different task mid-plan | `op:handoff_generate` to bookmark state |',
   '',
 
+  // ─── Skill Step Checkpoints ────────────────────────────
+  '### Skill Step Checkpoints',
+  '',
+  'Skills with structured steps return a checkpoint summary at each step boundary.',
+  'When executing a multi-step skill:',
+  '1. Start with `op:skill_step_start` to create a tracker',
+  '2. After each step, call `op:skill_step_advance` with evidence',
+  '3. On completion, call `op:skill_step_complete` to validate',
+  '',
+  'Save intermediate outputs to files, not context. This survives context compaction.',
+  '',
+
   // ─── Getting Started & Updates ─────────────────────────
   '## Getting Started & Updates',
   '<!-- soleri:getting-started -->',
@@ -844,7 +883,7 @@ 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`.',
+  'Your agent ships with **essential skills** by default (soleri-agent-guide, soleri-agent-persona, soleri-vault-navigator, soleri-vault-capture, soleri-systematic-debugging, soleri-writing-plans, soleri-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`.',
   '',
@@ -856,6 +895,15 @@ const ENGINE_RULES_LINES: string[] = [
   '| `soleri skills list` | List installed skill packs |',
   '| `soleri skills install <pack>` | Install a skill pack |',
   '',
+  '### Dream (Memory Consolidation)',
+  '',
+  '| Command | What it does |',
+  '|---------|-------------|',
+  '| `soleri dream` | Run vault memory consolidation (dream pass) immediately |',
+  '| `soleri dream schedule [--time HH:MM]` | Schedule daily dream at specified time (default: 22:00) |',
+  '| `soleri dream unschedule` | Remove scheduled dream cron job |',
+  '| `soleri dream status` | Show dream status: last run, sessions since, cron schedule |',
+  '',
   '### Installation & Setup',
   '',
   '| Command | What it does |',
@@ -986,10 +1034,11 @@ const ENGINE_RULES_LINES: string[] = [
   '',
   '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:',
+  '3. **Worktree branches are local-only — never push them to remote.** They exist for isolated subagent execution and get merged back locally. After merge, delete the local branch immediately with `git branch -D <branch>`.',
+  '4. **Worktree cleanup is guaranteed.** Four-layer defense: (a) `finally` block in dispatcher cleans per-task worktree and local branch, (b) orchestrator deletes local branch after confirmed merge, (c) `cleanupAll()` runs after batch completion, (d) `SessionStart` hook prunes orphaned worktrees and deletes merged `subagent/*` and `worktree-agent-*` local branches.',
+  '5. **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.',
+  '6. **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.',
+  '7. **UX output contract.** The orchestrator communicates subagent work to the user at three verbosity levels:',
   '',
   '### UX Output Format',
   '',

package/src/templates/skills.ts

@@ -9,6 +9,78 @@ const SKILLS_DIR = join(__dirname, '..', 'skills');
 /** Placeholder token in skill templates that gets replaced with agent-specific tool name. */
 const AGENT_PLACEHOLDER = 'YOUR_AGENT_core';
 
+// ---------------------------------------------------------------------------
+// Frontmatter step extraction
+// ---------------------------------------------------------------------------
+
+export type SkillStepEvidence = 'tool_called' | 'file_exists';
+
+export interface SkillStepDef {
+  id: string;
+  description: string;
+  evidence: SkillStepEvidence;
+}
+
+/**
+ * Extract optional `steps` array from YAML frontmatter.
+ * Uses simple regex parsing — no YAML dependency needed.
+ */
+export function extractStepsFromFrontmatter(content: string): SkillStepDef[] | null {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+
+  const fm = fmMatch[1];
+  const stepsIdx = fm.indexOf('\nsteps:');
+  if (stepsIdx === -1) return null;
+
+  // Collect lines after "steps:" that are indented (part of the array)
+  const afterSteps = fm.slice(stepsIdx + '\nsteps:'.length);
+  const lines = afterSteps.split('\n');
+  const steps: SkillStepDef[] = [];
+  let current: Partial<SkillStepDef> | null = null;
+
+  for (const line of lines) {
+    // Stop at next top-level YAML key or end of indented block
+    if (line.match(/^\S/) && line.trim() !== '') break;
+
+    const itemMatch = line.match(/^\s+-\s+id:\s*(.+)/);
+    if (itemMatch) {
+      if (current?.id && current.description && current.evidence) {
+        steps.push(current as SkillStepDef);
+      }
+      current = { id: itemMatch[1].trim().replace(/^["']|["']$/g, '') };
+      continue;
+    }
+
+    if (current) {
+      const descMatch = line.match(/^\s+description:\s*(.+)/);
+      if (descMatch) {
+        current.description = descMatch[1].trim().replace(/^["']|["']$/g, '');
+        continue;
+      }
+      const evMatch = line.match(/^\s+evidence:\s*(.+)/);
+      if (evMatch) {
+        const raw = evMatch[1].trim().replace(/^["']|["']$/g, '');
+        if (raw === 'tool_called' || raw === 'file_exists') {
+          current.evidence = raw;
+        }
+        continue;
+      }
+    }
+  }
+
+  // Push last item
+  if (current?.id && current.description && current.evidence) {
+    steps.push(current as SkillStepDef);
+  }
+
+  return steps.length > 0 ? steps : null;
+}
+
+// ---------------------------------------------------------------------------
+// Skill generation
+// ---------------------------------------------------------------------------
+
 /**
  * Generate skill files for the scaffolded agent.
  * Returns [relativePath, content] tuples for each skill.
@@ -17,6 +89,10 @@ const AGENT_PLACEHOLDER = 'YOUR_AGENT_core';
  * - If config.skills is undefined/empty, all skills are included (backward compat).
  * - Superpowers-adapted skills (MIT): copied as-is
  * - Engine-adapted skills: YOUR_AGENT_core → {config.id}_core
+ *
+ * When a skill's frontmatter contains a `steps` array, the steps are appended
+ * as a hidden metadata block (`<!-- soleri:steps ... -->`) so the runtime can
+ * extract them for step-tracking.
  */
 export function generateSkills(config: AgentConfig): Array<[string, string]> {
   const files: Array<[string, string]> = [];
@@ -63,6 +139,12 @@ export function generateSkills(config: AgentConfig): Array<[string, string]> {
       content = content.replace(/YOUR_AGENT_core/g, `${config.id}_core`);
     }
 
+    // Extract structured steps from frontmatter and append as metadata block
+    const steps = extractStepsFromFrontmatter(content);
+    if (steps) {
+      content += `\n<!-- soleri:steps ${JSON.stringify(steps)} -->\n`;
+    }
+
     files.push([`skills/${skillName}/SKILL.md`, content]);
   }
 

package/dist/skills/vault-capture/SKILL.md

@@ -1,86 +0,0 @@
----
-name: vault-capture
-description: >
-  Use to capture a SINGLE known pattern, anti-pattern, workflow, decision, or principle to the
-  vault. Triggers on "save this", "capture this", "remember this pattern", "add to vault". The
-  user already knows what to capture. For bulk extraction from documents, code, or PRs, use
-  knowledge-harvest instead.
----
-
-# Vault Capture — Persist Knowledge
-
-Capture patterns, anti-patterns, workflows, and principles to the vault. Captured knowledge compounds — it informs future searches, brain recommendations, and team reviews.
-
-## Steps
-
-### 1. Check for Duplicates
-
-```
-YOUR_AGENT_core op:search_intelligent
-  params: { query: "<knowledge title or description>" }
-YOUR_AGENT_core op:curator_detect_duplicates
-```
-
-If similar entry exists, update it instead of creating a duplicate.
-
-### 2. Classify the Knowledge
-
-| Type             | Description                         |
-| ---------------- | ----------------------------------- |
-| **pattern**      | Works and should be repeated        |
-| **anti-pattern** | Fails and should be avoided         |
-| **workflow**     | Steps for a specific task           |
-| **principle**    | Guiding rule or heuristic           |
-| **decision**     | Architectural choice with rationale |
-
-### 3. Capture
-
-```
-YOUR_AGENT_core op:capture_knowledge
-  params: {
-    title: "<clear, searchable name>",
-    description: "<what it is and when it applies>",
-    type: "<pattern|anti-pattern|workflow|principle|decision>",
-    category: "<domain>",
-    tags: ["<tag1>", "<tag2>"],
-    example: "<code or before/after>",
-    why: "<reasoning>"
-  }
-```
-
-For quick captures: `YOUR_AGENT_core op:capture_quick params: { title: "<name>", description: "<details>" }`
-
-### 4. Post-Capture Quality
-
-- `op:curator_groom params: { entryId: "<id>" }` — normalize tags
-- `op:curator_enrich params: { entryId: "<id>" }` — LLM enrichment
-- `op:curator_contradictions` — check for conflicts
-
-### 5. Governance (if enabled)
-
-If capture returns a `proposalId`, entry is queued: `op:governance_proposals params: { action: "list" }`.
-
-### 6. Promote to Global (Optional)
-
-For cross-project knowledge: `op:memory_promote_to_global params: { entryId: "<id>" }`.
-
-### 7. Verify
-
-`op:admin_health` and `op:admin_vault_analytics` to confirm storage and quality.
-
-## Common Mistakes
-
-- Not checking for duplicates before capturing
-- Missing the `why` field (makes entries not actionable)
-- Skipping post-capture grooming (tags stay unnormalized)
-
-## Quick Reference
-
-| Op                                    | When to Use          |
-| ------------------------------------- | -------------------- |
-| `search_intelligent`                  | Check for duplicates |
-| `capture_knowledge` / `capture_quick` | Persist to vault     |
-| `curator_groom` / `curator_enrich`    | Post-capture quality |
-| `curator_contradictions`              | Find conflicts       |
-| `memory_promote_to_global`            | Share cross-project  |
-| `admin_health`                        | Verify health        |

package/src/skills/vault-capture/SKILL.md

@@ -1,86 +0,0 @@
----
-name: vault-capture
-description: >
-  Use to capture a SINGLE known pattern, anti-pattern, workflow, decision, or principle to the
-  vault. Triggers on "save this", "capture this", "remember this pattern", "add to vault". The
-  user already knows what to capture. For bulk extraction from documents, code, or PRs, use
-  knowledge-harvest instead.
----
-
-# Vault Capture — Persist Knowledge
-
-Capture patterns, anti-patterns, workflows, and principles to the vault. Captured knowledge compounds — it informs future searches, brain recommendations, and team reviews.
-
-## Steps
-
-### 1. Check for Duplicates
-
-```
-YOUR_AGENT_core op:search_intelligent
-  params: { query: "<knowledge title or description>" }
-YOUR_AGENT_core op:curator_detect_duplicates
-```
-
-If similar entry exists, update it instead of creating a duplicate.
-
-### 2. Classify the Knowledge
-
-| Type             | Description                         |
-| ---------------- | ----------------------------------- |
-| **pattern**      | Works and should be repeated        |
-| **anti-pattern** | Fails and should be avoided         |
-| **workflow**     | Steps for a specific task           |
-| **principle**    | Guiding rule or heuristic           |
-| **decision**     | Architectural choice with rationale |
-
-### 3. Capture
-
-```
-YOUR_AGENT_core op:capture_knowledge
-  params: {
-    title: "<clear, searchable name>",
-    description: "<what it is and when it applies>",
-    type: "<pattern|anti-pattern|workflow|principle|decision>",
-    category: "<domain>",
-    tags: ["<tag1>", "<tag2>"],
-    example: "<code or before/after>",
-    why: "<reasoning>"
-  }
-```
-
-For quick captures: `YOUR_AGENT_core op:capture_quick params: { title: "<name>", description: "<details>" }`
-
-### 4. Post-Capture Quality
-
-- `op:curator_groom params: { entryId: "<id>" }` — normalize tags
-- `op:curator_enrich params: { entryId: "<id>" }` — LLM enrichment
-- `op:curator_contradictions` — check for conflicts
-
-### 5. Governance (if enabled)
-
-If capture returns a `proposalId`, entry is queued: `op:governance_proposals params: { action: "list" }`.
-
-### 6. Promote to Global (Optional)
-
-For cross-project knowledge: `op:memory_promote_to_global params: { entryId: "<id>" }`.
-
-### 7. Verify
-
-`op:admin_health` and `op:admin_vault_analytics` to confirm storage and quality.
-
-## Common Mistakes
-
-- Not checking for duplicates before capturing
-- Missing the `why` field (makes entries not actionable)
-- Skipping post-capture grooming (tags stay unnormalized)
-
-## Quick Reference
-
-| Op                                    | When to Use          |
-| ------------------------------------- | -------------------- |
-| `search_intelligent`                  | Check for duplicates |
-| `capture_knowledge` / `capture_quick` | Persist to vault     |
-| `curator_groom` / `curator_enrich`    | Post-capture quality |
-| `curator_contradictions`              | Find conflicts       |
-| `memory_promote_to_global`            | Share cross-project  |
-| `admin_health`                        | Verify health        |