@soleri/forge 9.3.1 → 9.4.0

package/dist/skills/executing-plans/SKILL.md

@@ -77,6 +77,18 @@ Capture mid-execution learnings with `op:capture_quick` as they happen — don't
 - Forgetting to reconcile the plan after execution (drift data improves future plans)
 - Starting implementation on main/master without explicit consent
 
+## Rationalization Prevention
+
+Do NOT rationalize away failures. If a verification step fails, the task is not complete.
+
+- **HARD-GATE: Each task's verification must pass before marking it `completed`.**
+- **HARD-GATE: Final verification (Step 6) must pass before `plan_reconcile`. Do not reconcile a failing plan.**
+- Do not say "this task is basically done" when its verification has not run.
+- Do not skip verification steps "to save time" -- they exist for a reason.
+- Do not mark a task `completed` while its tests fail, even if the code "looks right."
+- If a task is blocked or failing, leave it `in_progress` and report honestly.
+- Do not treat reconciliation drift as permission to ignore failures.
+
 ## Quick Reference
 
 | Op                                              | When to Use                 |

package/dist/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: finishing-a-development-branch
+description: >
+  Use when the user says "finish branch", "merge branch", "ready to merge", "PR ready",
+  "close branch", "submit PR", or wants to finalize a development branch for merge into
+  the base branch.
+---
+
+# Finishing a Development Branch
+
+Pre-merge checks, PR creation, merge strategy, and branch cleanup.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to prepare this branch for merge."
+
+## Step 1: Pre-Merge Checklist
+
+Run all checks before creating a PR. Stop on any failure.
+
+```bash
+npm test              # all tests pass
+npx tsc --noEmit      # typecheck clean
+npm run lint          # no lint errors (if configured)
+```
+
+Verify no uncommitted changes: `git status` should be clean. Commit or stash before proceeding.
+
+## Step 2: Create the Pull Request
+
+1. Push the branch: `git push -u origin <branch>`
+2. Create PR with `gh pr create`:
+   - **Title**: under 70 chars, conventional format (`feat:`, `fix:`, `refactor:`)
+   - **Body**: summary (what + why), test plan, breaking changes if any
+   - **Reviewers**: add if the user specifies or the repo has CODEOWNERS
+   - **Labels/milestone**: add if relevant
+
+Keep the description focused on *why* the change exists, not a file-by-file diff recap.
+
+## Step 3: Squash vs Merge Commit
+
+| Signal | Strategy | Rationale |
+|--------|----------|-----------|
+| Many WIP/fixup commits | **Squash** | Clean history, one logical change |
+| Each commit is a meaningful unit | **Merge commit** | Preserves granular history |
+| Single commit on branch | Either | No difference |
+| Team convention exists | **Follow it** | Consistency wins |
+
+Default to **squash** unless the user or repo convention says otherwise.
+
+## Step 4: Handle Merge Conflicts
+
+If the base branch has diverged:
+
+1. `git fetch origin && git rebase origin/<base>` — preferred, keeps history linear
+2. Resolve conflicts file by file, run the full checklist (Step 1) again after resolving
+3. `git rebase --continue` after each resolution
+4. If rebase is too complex, `git merge origin/<base>` is acceptable — ask the user
+
+Never force-push a rebased branch that others are working on.
+
+## Step 5: Branch Cleanup
+
+After merge is confirmed:
+
+1. `git checkout <base> && git pull`
+2. `git branch -d <branch>` — delete local branch
+3. If remote branch not auto-deleted: `git push origin --delete <branch>`
+
+## Anti-Patterns
+
+- **Force-pushing to shared branches** — destroys others' history; only force-push personal branches
+- **Merging without tests passing** — broken main is worse than a delayed merge
+- **Giant PRs** — split if touching 10+ files across unrelated concerns
+- **Empty PR descriptions** — reviewers need context; "fixes stuff" is not a description
+- **Leaving stale branches** — delete after merge; stale branches create confusion
+
+**Related skills:** executing-plans, verification-before-completion

package/dist/skills/fix-and-learn/SKILL.md

@@ -90,6 +90,18 @@ Bug resolved, tests pass, root cause captured in vault. A fix without a capture
 - Skipping the capture step after fixing
 - Not running the full test suite to check regressions
 
+## Rationalization Prevention
+
+Do NOT rationalize away failures. A fix is not done until it is proven done.
+
+- **HARD-GATE: The original symptom must be verified as resolved (test passes, error gone) before claiming the bug is fixed.**
+- **HARD-GATE: Full test suite must pass (no regressions) before completing the fix loop.**
+- Do not say "the fix should work" -- reproduce the original issue and confirm it is gone.
+- Do not say "this is unrelated" to dismiss a new test failure without investigation.
+- Do not skip the capture step -- a fix without a vault entry is incomplete.
+- If the fix introduces a new failure, the fix is not done. Do not rationalize it away.
+- If you cannot verify the fix, say so. Never claim success without evidence.
+
 ## Quick Reference
 
 | Op                                              | When to Use                |

package/dist/skills/mcp-doctor/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: mcp-doctor
+description: >
+  Use when MCP servers fail to connect, tools are missing, or the user says "check MCP",
+  "MCP not working", "server not connecting", "tools missing", "heal MCP", "fix MCP",
+  "mcp doctor", "mcp status". Diagnoses and repairs MCP server connectivity issues.
+---
+
+# MCP Doctor — Diagnose and Heal MCP Connections
+
+Systematically diagnose why MCP servers are not connecting and attempt to repair them.
+
+## Phase 1: Inventory
+
+Read the `.mcp.json` in the project root to get the list of configured servers.
+
+```bash
+cat .mcp.json
+```
+
+For each server entry, record:
+- Server name
+- Command (`command` field)
+- Arguments (`args` field)
+- Working directory (`cwd` field, defaults to `.`)
+- Environment variables (`env` field, if any)
+
+## Phase 2: Diagnose Each Server
+
+For each configured server, run these checks in order:
+
+### 2a. Binary exists?
+
+```bash
+which <command>
+# e.g. which node, which uvx, which npx
+```
+
+If the binary is missing, report it and suggest installation.
+
+### 2b. Entry point exists?
+
+For `node` commands, check the script file exists:
+```bash
+ls -la <args[0]>
+```
+
+For `npx`/`uvx` commands, check the package resolves:
+```bash
+npx --yes <package> --help 2>&1 | head -5
+# or
+uvx --from <source> <command> --help 2>&1 | head -5
+```
+
+### 2c. Server starts?
+
+Attempt to start the server with a timeout to verify it initializes:
+
+```bash
+timeout 10 <full command> 2>&1 &
+sleep 3
+kill %1 2>/dev/null
+```
+
+Look for:
+- Startup success messages (e.g. "Starting MCP server", "tools loaded")
+- Error messages (missing dependencies, port conflicts, config errors)
+- Crash/exit codes
+
+### 2d. Port conflicts?
+
+If the server binds to a port, check for conflicts:
+
+```bash
+lsof -i :<port>
+```
+
+If a stale process holds the port, report the PID and suggest killing it.
+
+### 2e. Dependencies met?
+
+For Node.js servers, check if `node_modules` exist:
+```bash
+ls <cwd>/node_modules/.package-lock.json 2>/dev/null
+```
+
+If missing, suggest `npm install`.
+
+For Python (uvx) servers, the virtual env is managed by uvx — check if the package installs cleanly.
+
+## Phase 3: Repair
+
+For each issue found, apply the appropriate fix:
+
+| Issue | Fix |
+|-------|-----|
+| Binary not found | Suggest install command |
+| Entry point missing | `npm run build` or check path |
+| Port conflict (stale process) | `kill <PID>` (ask user first) |
+| Missing node_modules | `npm install` in the right directory |
+| Config error in .mcp.json | Show the fix, apply with user approval |
+| Package resolution failure | Clear cache, retry install |
+| Server crashes on start | Show error log, diagnose root cause |
+
+**IMPORTANT:** Never kill processes without user confirmation. Always show the PID and process name first.
+
+## Phase 4: Verify
+
+After repairs, instruct the user:
+
+> Repairs complete. Please restart MCP connections:
+> 1. Type `/mcp` in the prompt
+> 2. Toggle the repaired server(s) off and back on
+> 3. Verify tools appear with a ToolSearch
+
+Note: Claude Code does not support programmatic MCP restarts. The user must use `/mcp` to reconnect.
+
+## Phase 5: Report
+
+Present findings as a table:
+
+```
+## MCP Doctor Report
+
+| Server | Binary | Entry Point | Starts | Port | Status |
+|--------|--------|-------------|--------|------|--------|
+| soleri | node OK | dist/index.js OK | OK | — | Healthy |
+| serena | uvx OK | git+... OK | OK | 24285 OK | Healthy |
+
+### Issues Found
+| Server | Issue | Fix Applied |
+|--------|-------|-------------|
+| serena | Stale process on :24285 | Killed PID 1234 |
+
+### Action Required
+- [ ] Run `/mcp` and reconnect repaired servers
+```
+
+## Common Issues
+
+- **uvx servers**: Often fail due to network issues when pulling from git. Check connectivity.
+- **Node servers**: Often fail because `dist/` hasn't been built. Run the build command.
+- **Port conflicts**: Previous server instances that didn't shut down cleanly. Kill and restart.
+- **cwd issues**: Relative `cwd: "."` resolves from where Claude Code launched, not the .mcp.json location.
+
+## Quick Reference
+
+| Check | Command | What it tells you |
+|-------|---------|-------------------|
+| Binary exists | `which <cmd>` | Is the runtime installed? |
+| Script exists | `ls <path>` | Is the entry point built? |
+| Port free | `lsof -i :<port>` | Is something blocking the port? |
+| Deps installed | `ls node_modules` | Are npm packages present? |
+| Server starts | `timeout 10 <cmd>` | Does initialization succeed? |

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

@@ -0,0 +1,77 @@
+---
+name: subagent-driven-development
+description: >
+  Use when the user says "use subagents", "parallel agents", "fan out", "dispatch agents",
+  "subagent driven", or when a task decomposes into 2+ independent units that benefit from
+  isolated execution. Covers when to dispatch, worktree isolation, and merge strategy.
+---
+
+# 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.
+
+**Announce at start:** "I'm using the subagent-driven-development skill to dispatch isolated agents."
+
+## When to Dispatch
+
+| Signal | Dispatch? |
+|--------|-----------|
+| 2+ independent tasks touching different files | Yes — no conflict risk, parallel speedup |
+| Risky/experimental work (spike, prototype) | Yes — isolate blast radius in a worktree |
+| Large refactor across unrelated modules | Yes — each module is a clean unit |
+| Single-file change or trivial fix | **No** — overhead exceeds benefit |
+| Tasks with sequential dependencies | **No** — cannot parallelize |
+| Tasks modifying the same file | **No** — guaranteed merge conflicts |
+
+## The Process
+
+### Step 1: Decompose
+
+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: Dispatch with Worktree Isolation
+
+```
+Agent(prompt: "<task prompt>", isolation: "worktree")
+```
+
+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.
+
+Launch all independent subagents in a **single message** so they run in parallel.
+
+### Step 3: 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
+
+After all merges, capture learnings:
+```
+YOUR_AGENT_core op:capture_quick params:{
+  title: "subagent dispatch outcome",
+  description: "<which tasks parallelized well, which conflicted>"
+}
+```
+
+## 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 |
+
+## Merge Strategy
+
+| Situation | Strategy |
+|-----------|----------|
+| Completely separate directories | Fast-forward merge, no conflicts expected |
+| Different files in the same package | Merge one by one, test after each |
+| Unexpected conflict | Resolve manually, re-run tests, capture as anti-pattern |
+| Subagent result fails review | Dispatch fix subagent into same worktree (max 2 retries) |
+
+**Related skills:** parallel-execute, executing-plans, verification-before-completion

package/dist/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: using-git-worktrees
+description: >
+  Use when the user says "worktree", "isolate", "parallel branch", "safe branch", or when a plan
+  has independent tasks that benefit from parallel execution in isolated branches. Provides the
+  protocol for creating, working in, and cleaning up git worktrees safely.
+---
+
+# Using Git Worktrees
+
+Isolate work into parallel branches without stashing or switching. Use for multi-task plans, risky changes, or parallel execution. Claude Code natively supports `isolation: "worktree"` on sub-agents.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to isolate this work."
+
+## When to Use
+
+- Plan has 2+ independent tasks that can run in parallel
+- Risky or experimental change that should not touch the main working tree
+- Long-running task where you need the main branch clean for hotfixes
+
+## Creation Protocol
+
+```bash
+# 1. Pre-flight — working tree must be clean
+git status
+git log origin/main..main              # check for unpushed commits
+
+# 2. Create worktree
+git worktree add ../<repo>-<task> -b <branch-name>
+cd ../<repo>-<task>
+
+# 3. Bootstrap and baseline
+npm install                            # shared .git does NOT share node_modules
+npm test                               # must pass before any changes
+```
+
+If the working tree is dirty, commit or stash first. If baseline tests fail, stop and investigate.
+
+## Working in a Worktree
+
+- Full working copy — edit, test, commit normally
+- Commits are visible across worktrees (shared `.git`)
+- `git worktree list` to see all active worktrees
+
+## Cleanup Protocol
+
+```bash
+# 1. Safety check — never delete with unpushed/uncommitted work
+git log origin/<branch>..<branch>      # unpushed commits?
+git diff --stat                        # uncommitted changes?
+
+# 2. Merge or discard
+git merge <branch-name>                # from main worktree
+# OR: git branch -D <branch-name>     # only if work is abandoned
+
+# 3. Remove and verify
+git worktree remove ../<repo>-<task>
+git worktree prune
+git worktree list                      # confirm removal
+```
+
+## Anti-Patterns
+- Creating worktrees for single-file changes or one-liner fixes
+- Leaving orphan worktrees after tasks complete — always clean up
+- Deleting the worktree directory manually instead of `git worktree remove`
+- Forgetting `npm install` in new worktree
+- Skipping baseline tests before starting work
+
+## Quick Reference
+
+| Action           | Command                                          |
+| ---------------- | ------------------------------------------------ |
+| Create           | `git worktree add ../<name> -b <branch>`         |
+| List             | `git worktree list`                              |
+| Remove           | `git worktree remove ../<name>`                  |
+| Prune            | `git worktree prune`                             |
+| Check unpushed   | `git log origin/<branch>..<branch>`              |
+| Claude Code      | Sub-agent with `isolation: "worktree"` parameter |
+
+**Related skills:** executing-plans, parallel-execute

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

@@ -0,0 +1,99 @@
+---
+name: vault-curate
+description: >
+  Use when the user says "clean vault", "deduplicate", "groom knowledge",
+  "consolidate vault", "vault maintenance", "find duplicates", "merge patterns",
+  "check contradictions", "vault health", or wants to maintain, clean, reorganize,
+  or improve the quality of the agent's knowledge base.
+---
+
+# Vault Curate — Knowledge Maintenance
+
+Maintain vault quality through deduplication, grooming, contradiction detection, and consolidation. A well-curated vault produces better search results and brain recommendations.
+
+## When to Use
+
+Periodically (weekly or after heavy capture sessions), when search quality degrades, when vault health shows warnings, or when the user explicitly requests maintenance.
+
+## Orchestration Sequence
+
+### Step 1: Health Assessment
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+```
+YOUR_AGENT_core op:get_vault_analytics
+```
+
+Present the health summary to the user before proceeding: total entries, quality scores, staleness, coverage gaps.
+
+### Step 2: Detect Duplicates
+
+```
+YOUR_AGENT_core op:curator_detect_duplicates
+```
+
+This finds entries with overlapping titles, descriptions, or content. Review the duplicate pairs — some may be intentional (different contexts) while others are true duplicates.
+
+For true duplicates:
+
+```
+YOUR_AGENT_core op:merge_patterns
+  params: { patternIds: ["<id1>", "<id2>"] }
+```
+
+Preserve the best content from each.
+
+### Step 3: Find Contradictions
+
+```
+YOUR_AGENT_core op:curator_contradictions
+```
+
+Contradictions erode trust in vault search results. For each contradiction: decide which entry is correct (check dates, context, evidence), then archive or update the incorrect one.
+
+### Step 4: Groom Entries
+
+```
+YOUR_AGENT_core op:curator_groom_all
+```
+
+Runs tag enrichment and metadata cleanup across all entries. This improves searchability and categorization.
+
+For targeted grooming of specific entries:
+
+```
+YOUR_AGENT_core op:curator_groom
+  params: { entryIds: ["<id>"], tags: ["<tag>"] }
+```
+
+### Step 5: Full Consolidation
+
+```
+YOUR_AGENT_core op:curator_consolidate
+```
+
+Runs the complete pipeline: dedup + archive stale entries + resolve contradictions. This is the heavy-duty cleanup.
+
+### Step 6: Knowledge Reorganization
+
+```
+YOUR_AGENT_core op:knowledge_reorganize
+  params: { mode: "preview" }
+```
+
+Preview first, then run again with `mode: "apply"` if the preview looks good.
+
+### Step 7: Verify Results
+
+```
+YOUR_AGENT_core op:knowledge_health
+```
+
+Compare with Step 1 metrics. Vault health should improve: fewer duplicates, no contradictions, better coverage.
+
+## Exit Criteria
+
+Curation is complete when: duplicates merged, contradictions resolved, entries groomed, and health metrics improved compared to Step 1 baseline.

package/dist/skills/verification-before-completion/SKILL.md

@@ -75,6 +75,18 @@ Capture session summary: `YOUR_AGENT_core op:session_capture params: { summary:
 - Running linter but not build (linter does not check compilation)
 - Skipping the red-green cycle for regression tests
 
+## Rationalization Prevention
+
+Do NOT rationalize away failures. If a check fails, it fails. Period.
+
+- **HARD-GATE: All verification commands must pass (exit 0, 0 failures) before claiming task complete.**
+- **HARD-GATE: Agent system checks (`admin_health`, `admin_diagnostic`) must report no problems before completion.**
+- Do not say "tests probably pass" -- run them and read the output.
+- Do not say "this is a minor issue" to skip a failing check.
+- Do not say "it worked last time" -- stale results are not evidence.
+- Do not downgrade a failure to a warning to avoid blocking completion.
+- If a check fails and you cannot fix it, report the failure honestly. Never hide it.
+
 ## Quick Reference
 
 | Op                      | When to Use                         |

package/dist/skills/yolo-mode/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: yolo-mode
+description: >
+  Use when the user says "yolo", "autonomous", "skip approvals", "full auto", "hands off",
+  or asks to execute without approval gates. Activates autonomous execution mode where the
+  agent skips plan approval gates but preserves all safety invariants.
+---
+
+# YOLO Mode
+
+Autonomous execution without approval gates. Plans execute immediately — no Gate 1, no Gate 2, no confirmation prompts.
+
+**Announce at start:** "I'm activating YOLO mode — autonomous execution with safety invariants intact."
+
+## Activation Flow
+
+### Step 1: Verify Safety Hook Pack
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Check that the YOLO Safety Hook Pack is installed. This pack intercepts destructive commands (force push, reset --hard, drop table, rm -rf).
+
+**HARD-GATE: Refuse to activate YOLO mode if the safety hook pack is not installed.** Tell the user: "YOLO mode requires the safety hook pack. Run `soleri hooks add-pack yolo-safety` first."
+
+### Step 2: Morph to YOLO Mode
+
+```
+YOUR_AGENT_core op:morph
+  params: { mode: "YOLO-MODE" }
+```
+
+### Step 3: Confirm to User
+
+State clearly: "YOLO mode active. Approval gates are off. Safety invariants remain enforced. Say 'exit YOLO' to return to normal mode."
+
+## What Gets Skipped
+
+- Plan approval Gate 1 (`op:approve_plan`)
+- Plan approval Gate 2 (`op:plan_split` confirmation)
+- User confirmation prompts between steps
+- "Ready for feedback?" checkpoints
+
+## What Is NEVER Skipped
+
+- **`op:orchestrate_complete`** — knowledge capture runs on every task, always
+- **Vault search before decisions** — check vault for patterns/anti-patterns before acting
+- **YOLO Safety Hook Pack** — intercepts destructive commands (force push, drop table, rm -rf, reset --hard)
+- **Test execution** — tests still run; failures still block completion
+- **`op:plan_reconcile`** — drift reports still generated after execution
+
+## Exit Conditions
+
+YOLO mode deactivates when any of these occur:
+
+- User says "exit YOLO", "stop YOLO", or "normal mode"
+- Session ends
+- Explicit deactivation: `op:morph params: { mode: "DEFAULT" }`
+- Safety hook intercepts a destructive command (auto-exits, requires re-activation)
+
+## Anti-Patterns
+
+- Activating YOLO on an unfamiliar codebase — you need vault context first
+- Skipping tests in YOLO — tests are safety, not ceremony
+- Using YOLO for architectural decisions that need human judgment
+- Staying in YOLO after a safety hook triggers — re-evaluate before re-activating
+- Running YOLO without reviewing what the safety hook pack actually covers
+
+## Quick Reference
+
+| Op                    | When to Use                          |
+| --------------------- | ------------------------------------ |
+| `admin_health`        | Verify safety hook pack is installed |
+| `morph`               | Activate/deactivate YOLO mode        |
+| `orchestrate_complete`| After every task (never skip)        |
+| `search_intelligent`  | Before every decision (never skip)   |
+| `plan_reconcile`      | After execution (never skip)         |
+
+**Related skills:** executing-plans, writing-plans

package/dist/templates/clean-worktrees.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generate a POSIX sh script that cleans up stale Claude Code worktrees.
+ * Registered as a SessionStart hook in scaffolded agents.
+ */
+export declare function generateCleanWorktreesScript(): string;