@soleri/forge 9.2.0 → 9.3.1

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

@@ -23,6 +23,7 @@ YOUR_AGENT_core op:curator_contradictions
 ```
 
 **What to look for:**
+
 - Two patterns that recommend opposite approaches for the same situation
 - An anti-pattern that contradicts an active pattern
 - Entries from different time periods with conflicting advice (the older one may be stale)
@@ -38,6 +39,7 @@ YOUR_AGENT_core op:vault_age_report
 ```
 
 **Indicators:**
+
 - Entries >60 days without access or update
 - Patterns referencing APIs, libraries, or versions that have changed
 - Entries tagged with technologies the project no longer uses
@@ -55,6 +57,7 @@ YOUR_AGENT_core op:curator_detect_duplicates
 ```
 
 **Indicators:**
+
 - Entries with zero inbound or outbound links
 - Entries never returned in search results (check search insights)
 - Entries with no tags or only generic tags
@@ -73,6 +76,7 @@ YOUR_AGENT_core op:curator_detect_duplicates
 ```
 
 **Indicators:**
+
 - High similarity scores between entries
 - Same tags and category but different titles
 - Entries captured in different sessions about the same topic
@@ -89,6 +93,7 @@ YOUR_AGENT_core op:curator_health_audit
 ```
 
 **Indicators:**
+
 - Description under 50 characters
 - No examples or context
 - Missing "why" — only states "what" without rationale
@@ -107,6 +112,7 @@ YOUR_AGENT_core op:vault_tags
 ```
 
 **Indicators:**
+
 - Near-duplicate categories (e.g., "error-handling" and "errors" and "exception-handling")
 - Categories with only 1-2 entries (too granular)
 - Tags used inconsistently (same concept, different tag names)
@@ -123,6 +129,7 @@ YOUR_AGENT_core op:brain_strengths
 ```
 
 **Indicators:**
+
 - Patterns with high initial strength that have decayed below 0.3
 - Patterns that were strong but haven't received positive feedback in >30 days
 - Patterns with mixed feedback (both positive and negative) — unresolved
@@ -131,13 +138,14 @@ YOUR_AGENT_core op:brain_strengths
 
 ### 8. Knowledge Gap Smells
 
-Areas where the vault *should* have knowledge but doesn't.
+Areas where the vault _should_ have knowledge but doesn't.
 
 ```
 YOUR_AGENT_core op:admin_search_insights
 ```
 
 **Indicators:**
+
 - Repeated search queries that return no results
 - Domains the project uses but vault has no entries for
 - Anti-patterns captured without corresponding patterns (what to do instead?)
@@ -166,11 +174,11 @@ YOUR_AGENT_core op:admin_search_insights
 
 For each smell category, assess severity:
 
-| Severity | Meaning |
-|----------|---------|
-| 🟢 Clean | No issues in this category |
-| 🟡 Minor | 1-3 instances, low impact |
-| 🟠 Moderate | Multiple instances, degrading quality |
+| Severity    | Meaning                                    |
+| ----------- | ------------------------------------------ |
+| 🟢 Clean    | No issues in this category                 |
+| 🟡 Minor    | 1-3 instances, low impact                  |
+| 🟠 Moderate | Multiple instances, degrading quality      |
 | 🔴 Critical | Widespread, actively causing bad decisions |
 
 ### Step 3: Present the Report
@@ -237,15 +245,15 @@ After fixes: `op:brain_build_intelligence` to rebuild with clean data.
 
 ## Quick Reference
 
-| Smell | Detection Op | Fix Op |
-|-------|-------------|--------|
-| Contradictions | `curator_contradictions` | `curator_resolve_contradiction` |
-| Staleness | `vault_age_report` | Review + archive/update |
-| Orphans | `admin_vault_analytics` | Link or archive |
-| Duplicates | `curator_detect_duplicates` | `curator_groom` (merge) |
-| Shallow entries | `curator_health_audit` | Enrich or archive |
-| Category drift | `vault_domains` + `vault_tags` | `curator_groom_all` |
-| Confidence decay | `brain_strengths` | Reinforce or retire |
-| Knowledge gaps | `admin_search_insights` | `capture_knowledge` |
+| Smell            | Detection Op                   | Fix Op                          |
+| ---------------- | ------------------------------ | ------------------------------- |
+| Contradictions   | `curator_contradictions`       | `curator_resolve_contradiction` |
+| Staleness        | `vault_age_report`             | Review + archive/update         |
+| Orphans          | `admin_vault_analytics`        | Link or archive                 |
+| Duplicates       | `curator_detect_duplicates`    | `curator_groom` (merge)         |
+| Shallow entries  | `curator_health_audit`         | Enrich or archive               |
+| Category drift   | `vault_domains` + `vault_tags` | `curator_groom_all`             |
+| Confidence decay | `brain_strengths`              | Reinforce or retire             |
+| Knowledge gaps   | `admin_search_insights`        | `capture_knowledge`             |
 
 **Related skills:** health-check (operational status), vault-curate (active cleanup), knowledge-harvest (fill gaps)

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

@@ -43,12 +43,12 @@ If any check reports problems, address before claiming completion.
 
 ## Common Failures
 
-| Claim | Requires | Not Sufficient |
-|-------|----------|----------------|
-| Tests pass | Test output: 0 failures | Previous run, "should pass" |
-| Build succeeds | Build command: exit 0 | Linter passing |
-| Bug fixed | Original symptom passes | "Code changed, assumed fixed" |
-| Requirements met | Line-by-line checklist | Tests passing alone |
+| Claim            | Requires                | Not Sufficient                |
+| ---------------- | ----------------------- | ----------------------------- |
+| Tests pass       | Test output: 0 failures | Previous run, "should pass"   |
+| Build succeeds   | Build command: exit 0   | Linter passing                |
+| Bug fixed        | Original symptom passes | "Code changed, assumed fixed" |
+| Requirements met | Line-by-line checklist  | Tests passing alone           |
 
 ## Red Flags — STOP
 
@@ -57,12 +57,12 @@ If any check reports problems, address before claiming completion.
 - About to commit/push/PR without verification
 - Relying on partial verification
 
-| Excuse | Reality |
-|--------|---------|
-| "Should work now" | RUN the verification |
-| "I'm confident" | Confidence is not evidence |
-| "Just this once" | No exceptions |
-| "Partial check is enough" | Partial proves nothing |
+| Excuse                    | Reality                    |
+| ------------------------- | -------------------------- |
+| "Should work now"         | RUN the verification       |
+| "I'm confident"           | Confidence is not evidence |
+| "Just this once"          | No exceptions              |
+| "Partial check is enough" | Partial proves nothing     |
 
 ## After Verification
 
@@ -77,9 +77,9 @@ Capture session summary: `YOUR_AGENT_core op:session_capture params: { summary:
 
 ## Quick Reference
 
-| Op | When to Use |
-|----|-------------|
-| `admin_health` | Quick system health check |
-| `admin_diagnostic` | Comprehensive diagnostic |
-| `admin_vault_analytics` | Knowledge quality metrics |
-| `session_capture` | Persist verified completion context |
+| Op                      | When to Use                         |
+| ----------------------- | ----------------------------------- |
+| `admin_health`          | Quick system health check           |
+| `admin_diagnostic`      | Comprehensive diagnostic            |
+| `admin_vault_analytics` | Knowledge quality metrics           |
+| `session_capture`       | Persist verified completion context |

package/src/skills/writing-plans/SKILL.md

@@ -97,12 +97,12 @@ Offer execution choice: subagent-driven (this session) or parallel session with
 
 ## Quick Reference
 
-| Op | When to Use |
-|----|-------------|
-| `search_intelligent` | Find patterns before planning |
-| `brain_strengths` | Proven approaches |
-| `create_plan` | Create tracked plan |
-| `plan_grade` / `plan_auto_improve` | Grade and improve |
-| `plan_iterate` | Iterate with feedback |
-| `plan_split` | Split into tasks |
-| `approve_plan` | Lock in approved plan |
+| Op                                 | When to Use                   |
+| ---------------------------------- | ----------------------------- |
+| `search_intelligent`               | Find patterns before planning |
+| `brain_strengths`                  | Proven approaches             |
+| `create_plan`                      | Create tracked plan           |
+| `plan_grade` / `plan_auto_improve` | Grade and improve             |
+| `plan_iterate`                     | Iterate with feedback         |
+| `plan_split`                       | Split into tasks              |
+| `approve_plan`                     | Lock in approved plan         |

package/src/templates/shared-rules.ts

@@ -119,8 +119,7 @@ const ENGINE_RULES_LINES: string[] = [
   '## Planning',
   '<!-- soleri:planning -->',
   '',
-  '- **MANDATORY**: Create a formal plan (`op:create_plan`) for every work task. Memory and vault knowledge alone are not sufficient — plans must be persisted and graded.',
-  '- Use `op:create_plan` before writing ANY code. Show the plan, wait for approval.',
+  '- For complex tasks, use `op:create_plan` before writing code. Simple tasks can execute directly — but always run `op:orchestrate_complete`.',
   '- Two-gate approval: Gate 1 (`op:approve_plan`), Gate 2 (`op:plan_split`). Never skip either.',
   '- Wait for explicit "yes" / "approve" before proceeding past each gate.',
   '- After execution: `op:plan_reconcile` (drift report) then `op:plan_complete_lifecycle` (knowledge capture, archive).',
@@ -128,6 +127,26 @@ const ENGINE_RULES_LINES: string[] = [
   '- On session start: check for plans in `executing`/`reconciling` state and remind.',
   '- Exceptions: read-only operations, user says "just do it", single-line fixes.',
   '',
+  '### Task Auto-Assessment',
+  '',
+  'When picking up a work task (including GH issues decomposed from a parent plan), autonomously assess complexity — do NOT ask the user whether to create a plan.',
+  '',
+  '| Signal | Classification | Action |',
+  '|--------|---------------|--------|',
+  '| Single file, clear acceptance criteria | **Simple** | Execute directly |',
+  '| Approach already described in parent plan | **Simple** | Execute directly |',
+  '| Touches 3+ files or has cross-cutting concerns | **Complex** | Create scoped plan |',
+  '| Unresolved design decisions not in parent plan | **Complex** | Create scoped plan |',
+  '| New dependencies or architectural choices needed | **Complex** | Create scoped plan |',
+  '',
+  '**Simple task flow:** Vault search (quick) → execute → `op:orchestrate_complete` (captures knowledge).',
+  '',
+  '**Complex task flow:** Vault search → create lightweight scoped plan → two-gate approval → execute → reconcile → complete.',
+  '',
+  '**Key rule:** Knowledge gets captured either way via `op:orchestrate_complete`. Planning ceremony is for *decision-making*, not record-keeping.',
+  '',
+  '**Anti-pattern:** Creating a full graded plan for trivial tasks (add a CSS class, rename a variable, single-line fix).',
+  '',
   '### Grade Gate',
   '',
   '**MANDATORY**: Plans must grade **A or higher** before approval. The engine enforces this programmatically.',
@@ -256,12 +275,40 @@ const ENGINE_RULES_LINES: string[] = [
   '## Work Task Routing',
   '<!-- soleri:task-routing -->',
   '',
-  'Use the orchestration layer for ALL work tasks:',
-  '- `op:orchestrate_plan` → vault + brain + structured plan.',
-  '- `op:orchestrate_execute` → execution tracking.',
-  '- `op:orchestrate_complete` → epilogue (vault, session).',
+  'On every work task, assess complexity then route:',
+  '',
+  '### Auto-Assessment',
+  '',
+  'Evaluate these signals before deciding the execution path:',
+  '',
+  '| Signal | Simple (< 40) | Complex (≥ 40) |',
+  '|--------|---------------|----------------|',
+  '| Files touched | 1-2 | 3+ |',
+  '| Cross-cutting concerns | No | Yes |',
+  '| New dependencies | None | Yes |',
+  '| Design decisions | Already decided | Unresolved |',
+  '| Approach described | In parent plan/issue | Not yet |',
+  '',
+  '### Routing',
+  '',
+  '- **Simple tasks** → execute directly → `op:orchestrate_complete` (always)',
+  '- **Complex tasks** → `op:orchestrate_plan` → approve → execute → `op:orchestrate_complete` (always)',
+  '',
+  '### The Non-Negotiable Rule',
+  '',
+  '`op:orchestrate_complete` runs for EVERY task — simple or complex. This captures:',
+  '- Knowledge to vault (patterns learned, decisions made)',
+  '- Session summary (what was done, files changed)',
+  '- Brain feedback (what worked, what didn\'t)',
   '',
-  'The orchestrator handles vault lookup, brain recommendations, and knowledge capture automatically.',
+  'Without completion, the knowledge trail is lost. The code is in git, but the WHY disappears.',
+  '',
+  '### Exceptions (skip assessment, execute directly)',
+  '',
+  '- Read-only operations (search, status, health check)',
+  '- User explicitly says "just do it"',
+  '- Single-line fixes (typo, rename, one-liner)',
+  '- Questions and explanations',
   '',
 
   // ─── Intent Detection ────────────────────────────────────
@@ -342,15 +389,56 @@ const ENGINE_RULES_LINES: string[] = [
   '**Do NOT suggest tools when:** the user is having a conversation (not a task), already declined, or explicitly says "just tell me".',
   '',
 
+  // ─── Overlay Mode ─────────────────────────────────────────
+  '## Overlay Mode — Active Agent Protocol',
+  '<!-- soleri:overlay-mode -->',
+  '',
+  'When you are activated as an agent (via greeting or activation command), you ARE this agent — not Claude with tools on the side. You drive the full cycle through your toolset.',
+  '',
+  '### Tool-First Routing (MANDATORY when active)',
+  '',
+  'On every user request:',
+  '1. **Discover capabilities** — call `op:admin_tool_list` on first request of the session (or after context compaction resets your state)',
+  '2. **Parse intent** — what does the user want? Use semantic-first analysis.',
+  '3. **Route through agent tools** — always prefer your MCP tools over raw Claude reasoning:',
+  '   - **Knowledge questions** → vault search before answering from training data',
+  '   - **Recommendations** → brain recommend before proposing approaches',
+  '   - **Work tasks** → orchestrate plan before writing code',
+  '   - **Quality checks** → curator or admin health before manual inspection',
+  '   - **Learning moments** → capture to vault, don\'t just say "I\'ll remember"',
+  '4. **Fall back only when no tool fits** — file read/write/edit, git operations, shell commands, casual conversation',
+  '',
+  '### Self-Healing Discovery',
+  '',
+  '- After activation or context compaction, call `op:admin_tool_list` to refresh your capability inventory',
+  '- Do NOT rely on memorized tool lists from earlier in the conversation',
+  '- The tool list adapts when packs are installed — always discover dynamically',
+  '',
+  '### Character Persistence',
+  '',
+  '- All communication flows through your persona\'s voice — tone, vocabulary, opinions',
+  '- Stay in character until explicitly deactivated',
+  '- Context compaction does not change who you are — these rules persist in CLAUDE.md',
+  '- If you notice yourself dropping character, re-read your activation context',
+  '',
+  '### What NOT to Route Through Tools',
+  '',
+  '- Pure file read/write/edit operations (use Read, Edit, Write tools directly)',
+  '- Git operations (commit, push, branch, status)',
+  '- Shell commands the user explicitly requests',
+  '- Casual conversation, greetings, explanations',
+  '- One-line fixes where planning overhead exceeds the work',
+  '',
+
   // ─── Session Lifecycle ───────────────────────────────────
   '## Session Lifecycle',
   '<!-- soleri:session -->',
   '',
   '### Session Start Protocol',
   '',
-  'Do NOT call tools automatically on session start — just greet the user in character.',
-  'Call `op:session_start` only when you need project context for a task (not on every message).',
+  'On activation, discover capabilities via `op:admin_tool_list`. 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.',
   '',
   '### Context Compaction',
   '',