@soleri/forge 9.15.0 → 9.16.7

package/src/skills/soleri-agent-mode/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: soleri-agent-mode
+tier: default
+description: >
+  Use when the user addresses the agent directly ("AgentName, ...", "Hey AgentName"),
+  asks about available commands ("what commands do I have", "what can you do with MCP"),
+  uses vague agent-mode language ("save this", "remember this", "search for patterns",
+  "orchestrate this"), or when intent is ambiguous and needs routing to the right
+  facade + op. Also triggers on "how does this agent know", "command reference".
+---
+
+# Agent Mode — Intent Routing & Command Reference
+
+This skill governs how to interpret natural language directed at this agent and route it to the correct facade + op. Use it when a phrase is ambiguous, when the user addresses the agent directly, or when surfacing the command reference.
+
+## Routing Protocol (MANDATORY)
+
+Before executing any agent op, apply this 3-step protocol:
+
+**Step 1 — Semantic parse**
+Identify the verb + object in the user's message:
+
+- Verb: what action? (search, save, plan, execute, remember, check, show, run, fix)
+- Object: what is it about? (vault, brain, memory, plan, session, health, pattern)
+
+**Step 2 — Confirm via route_intent (when ambiguous)**
+
+```
+YOUR_AGENT_control op:route_intent
+  params: { input: "<user's phrase>", context: "<current task context>" }
+```
+
+Use this when the phrase matches 2+ intents. Skip it for obvious, unambiguous commands.
+
+**Step 3 — Execute the mapped op**
+Use the NL → Op table below to select facade + op. Pass `projectPath: "."` wherever required.
+
+---
+
+## Natural Language → Facade + Op Mapping
+
+### Search & Recall
+
+| What the user says                         | Facade              | Op                   | Notes                    |
+| ------------------------------------------ | ------------------- | -------------------- | ------------------------ |
+| "search for X" / "find patterns on X"      | `YOUR_AGENT_vault`  | `search_intelligent` | mode: "scan" first       |
+| "what do we know about X"                  | `YOUR_AGENT_vault`  | `search_intelligent` | mode: "full" if specific |
+| "recall X" / "remember X from before"      | `YOUR_AGENT_memory` | `memory_search`      | crossProject if broad    |
+| "what patterns are strong"                 | `YOUR_AGENT_brain`  | `brain_strengths`    | days: 30 default         |
+| "recommend something" / "what should I do" | `YOUR_AGENT_brain`  | `brain_recommend`    |                          |
+| "show me vault entries about X"            | `YOUR_AGENT_vault`  | `load_entries`       | after scan               |
+| "what's in the vault"                      | `YOUR_AGENT_vault`  | `vault_stats`        |                          |
+
+### Save & Capture
+
+| What the user says                              | Facade              | Op                  | Notes                 |
+| ----------------------------------------------- | ------------------- | ------------------- | --------------------- |
+| "save this" / "capture this" (detailed pattern) | `YOUR_AGENT_vault`  | `capture_knowledge` | full structured entry |
+| "quick save" / "jot this down"                  | `YOUR_AGENT_vault`  | `capture_quick`     | lightweight, fast     |
+| "remember this for the session"                 | `YOUR_AGENT_memory` | `memory_capture`    | session-scoped        |
+| "save the session" / "log what we did"          | `YOUR_AGENT_memory` | `session_capture`   | end-of-session        |
+| "ingest this URL" / "add this article"          | `YOUR_AGENT_vault`  | `ingest_url`        | external content      |
+| "ingest this text"                              | `YOUR_AGENT_vault`  | `ingest_text`       | raw text              |
+
+### Planning
+
+| What the user says                       | Facade            | Op                        | Notes                 |
+| ---------------------------------------- | ----------------- | ------------------------- | --------------------- |
+| "create a plan" / "plan this"            | `YOUR_AGENT_plan` | `create_plan`             | MANDATORY before code |
+| "approve the plan" / "looks good"        | `YOUR_AGENT_plan` | `approve_plan`            | Gate 1                |
+| "split the plan" / "break it into tasks" | `YOUR_AGENT_plan` | `plan_split`              | Gate 2                |
+| "check plan drift" / "what changed"      | `YOUR_AGENT_plan` | `plan_reconcile`          | post-execution        |
+| "complete the plan" / "close it out"     | `YOUR_AGENT_plan` | `plan_complete_lifecycle` | final step            |
+| "list active plans"                      | `YOUR_AGENT_plan` | `chain_list`              |                       |
+
+### Orchestration
+
+| What the user says                              | Facade                   | Op                     | Notes                        |
+| ----------------------------------------------- | ------------------------ | ---------------------- | ---------------------------- |
+| "orchestrate this" / "AgentName, orchestrate X" | `YOUR_AGENT_orchestrate` | `orchestrate_plan`     | vault+brain+plan in one call |
+| "execute the plan" / "start executing"          | `YOUR_AGENT_orchestrate` | `orchestrate_execute`  | tracks progress              |
+| "finish up" / "wrap the session"                | `YOUR_AGENT_orchestrate` | `orchestrate_complete` | epilogue: vault + session    |
+
+### Brain & Learning
+
+| What the user says                           | Facade             | Op                   | Notes                |
+| -------------------------------------------- | ------------------ | -------------------- | -------------------- |
+| "what has the brain learned" / "brain stats" | `YOUR_AGENT_brain` | `brain_stats`        |                      |
+| "give feedback on that"                      | `YOUR_AGENT_brain` | `brain_feedback`     | reinforcement signal |
+| "what patterns are failing"                  | `YOUR_AGENT_brain` | `brain_decay_report` |                      |
+| "radar analysis" / "spot patterns"           | `YOUR_AGENT_brain` | `radar_analyze`      |                      |
+| "show radar candidates"                      | `YOUR_AGENT_brain` | `radar_candidates`   |                      |
+
+### Health & Admin
+
+| What the user says                          | Facade               | Op                 | Notes |
+| ------------------------------------------- | -------------------- | ------------------ | ----- |
+| "health check" / "is everything working"    | `YOUR_AGENT_admin`   | `admin_health`     |       |
+| "list all tools" / "what tools do you have" | `YOUR_AGENT_admin`   | `admin_tool_list`  |       |
+| "session briefing" / "catch me up"          | `YOUR_AGENT_admin`   | `session_briefing` |       |
+| "diagnose X"                                | `YOUR_AGENT_admin`   | `admin_diagnostic` |       |
+| "run routing accuracy"                      | `YOUR_AGENT_control` | `routing_accuracy` |       |
+
+### Vault Maintenance
+
+| What the user says                 | Facade               | Op                          | Notes |
+| ---------------------------------- | -------------------- | --------------------------- | ----- |
+| "clean the vault" / "groom"        | `YOUR_AGENT_curator` | `curator_groom`             |       |
+| "find duplicates"                  | `YOUR_AGENT_curator` | `curator_detect_duplicates` |       |
+| "vault health audit"               | `YOUR_AGENT_curator` | `curator_health_audit`      |       |
+| "archive old entries"              | `YOUR_AGENT_vault`   | `vault_archive`             |       |
+| "push vault to git" / "sync vault" | `YOUR_AGENT_vault`   | `vault_git_push`            |       |
+
+### Identity & Control
+
+| What the user says                  | Facade               | Op                   | Notes                    |
+| ----------------------------------- | -------------------- | -------------------- | ------------------------ |
+| "Hello, AgentName!" / activate      | `YOUR_AGENT_core`    | `activate`           | params: projectPath      |
+| "Goodbye, AgentName!" / deactivate  | `YOUR_AGENT_core`    | `activate`           | params: deactivate: true |
+| "who are you" / "what mode is this" | `YOUR_AGENT_core`    | `identity`           |                          |
+| "register this project"             | `YOUR_AGENT_core`    | `register`           | params: projectPath      |
+| "route this intent"                 | `YOUR_AGENT_control` | `route_intent`       |                          |
+| "switch mode" / "morph to X"        | `YOUR_AGENT_control` | `morph`              |                          |
+| "what are the behavior rules"       | `YOUR_AGENT_control` | `get_behavior_rules` |                          |
+
+---
+
+## Disambiguation Matrix
+
+These phrases are ambiguous — resolve using context signals:
+
+| Phrase          | Context signal                           | Route to                                 |
+| --------------- | ---------------------------------------- | ---------------------------------------- |
+| "save this"     | Detailed explanation, pattern discussion | `vault.capture_knowledge`                |
+| "save this"     | Quick note, side comment                 | `vault.capture_quick`                    |
+| "save this"     | "For this session only"                  | `memory.memory_capture`                  |
+| "remember this" | Repeatable rule or pattern               | `vault.capture_knowledge`                |
+| "remember this" | Session-scoped fact                      | `memory.memory_capture`                  |
+| "search for X"  | Broad/exploratory                        | `vault.search_intelligent` mode:scan     |
+| "search for X"  | Specific known entry                     | `vault.search_intelligent` mode:full     |
+| "search for X"  | Across past sessions                     | `memory.memory_search` crossProject:true |
+| "check this"    | Code/PR in context                       | → `deep-review` skill                    |
+| "check this"    | System health                            | `admin.admin_health`                     |
+| "plan this"     | Work task                                | `orchestrate.orchestrate_plan`           |
+| "plan this"     | User wants to see plan first             | `plan.create_plan`                       |
+
+**Resolution rule:** When still ambiguous after checking context signals, ask one clarifying question before routing. Never guess and execute a write op.
+
+---
+
+## "AgentName, orchestrate X" — Full Flow
+
+When the user says "AgentName, orchestrate [task description]":
+
+1. **`YOUR_AGENT_orchestrate op:orchestrate_plan`** — vault lookup + brain recommendations + structured plan in one call
+2. Present the plan using the standard Plan Presentation format (Plan ID, Check ID, Grade, Status)
+3. Wait for Gate 1 approval: "approve" / "yes" / "looks good"
+4. **`YOUR_AGENT_plan op:plan_split`** — decompose into tasks
+5. Wait for Gate 2 approval
+6. **`YOUR_AGENT_orchestrate op:orchestrate_execute`** — track execution per task
+7. **`YOUR_AGENT_orchestrate op:orchestrate_complete`** — epilogue: vault capture + session record
+
+Never skip Gate 1 or Gate 2. Never proceed past a gate without explicit user approval.
+
+---
+
+## Anti-Patterns
+
+- **Guessing a write op** — if "save this" is ambiguous, ask before writing to vault
+- **Skipping route_intent for ambiguous phrases** — use it to confirm, not as a formality
+- **Executing orchestrate_plan without showing the plan** — always present before Gate 1
+- **Using memory_capture for reusable patterns** — session memory ≠ vault knowledge
+- **Ignoring the two-pass vault search** — scan first, load only top 2-4 results

package/src/skills/soleri-agent-persona/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-agent-persona
+tier: default
 description: >
   Use when the user says "activate persona", "be yourself",
   "stay in character", or "hello [agent name]". Reinforces character

package/src/skills/soleri-brain-debrief/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-brain-debrief
+tier: default
 description: >
   Use when the user says "brain stats", "pattern strengths",
   "intelligence report", "show brain data", or "what patterns are strongest".

package/src/skills/soleri-brainstorming/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-brainstorming
+tier: default
 description: >
   Use when the user says "I want to build something", "let's think about",
   "what if we", "creative exploration", or "ideate". For open-ended creative

package/src/skills/soleri-build-skill/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-build-skill
+tier: default
 description: >
   Use when creating a new skill, updating an existing skill, or scaffolding a skill
   template for a Soleri agent. Triggers on "create a skill", "new skill", "build skill",
@@ -24,6 +25,7 @@ Skills live in two places:
 ```yaml
 ---
 name: soleri-{skill-name}
+tier: default
 description: >
   Use when the user says "trigger1", "trigger2", "trigger3",
   or wants to [brief purpose]. [One sentence about what the skill does].

package/src/skills/soleri-code-patrol/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-code-patrol
+tier: default
 description: >
   Use when the user says "check against patterns", "pattern compliance",
   "convention check", "review against vault", or "institutional review".

package/src/skills/soleri-context-resume/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-context-resume
+tier: default
 description: >
   Use when the user says "where did I leave off", "what was I working on",
   "catch me up", "resume session", or "continue where we stopped".

package/src/skills/soleri-curator/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: soleri-curator
+tier: default
+description: >
+  Use when the user says "curator status", "vault health", "how is the vault",
+  "curator health", "check vault quality", or "what needs grooming".
+  Quick vault health check with targeted grooming recommendations.
+  For full maintenance (dedup, archive, consolidate), use vault-curate.
+---
+
+# Curator — Vault Health and Quick Grooming
+
+Get a rapid health snapshot of the vault and run targeted grooming on specific entries. Use this for regular check-ins and spot fixes. For deep maintenance (dedup, archive stale, full consolidation) use the `vault-curate` skill.
+
+## When to Use
+
+- Quick "how is the vault doing?" check
+- After a few capture sessions to verify entry quality
+- Spot-grooming specific entries or domains
+- Before starting a big research session
+
+## Orchestration
+
+### Step 1: Health Snapshot
+
+```
+YOUR_AGENT_curator op:curator_health
+```
+
+Present results as a status table:
+
+| Metric                  | Value              | Status        |
+| ----------------------- | ------------------ | ------------- |
+| **Total entries**       | {totalEntries}     | —             |
+| **Quality score**       | {qualityScore}/100 | {ok/warn/bad} |
+| **Stale entries**       | {staleCount}       | —             |
+| **Duplicates detected** | {duplicateCount}   | —             |
+| **Grooming needed**     | {needsGrooming}    | —             |
+
+If health score < 70 or duplicates > 10, recommend running `vault-curate`.
+
+### Step 2: Curator Status
+
+```
+YOUR_AGENT_curator op:curator_status
+```
+
+Show last grooming date, entries processed, and any pending actions.
+
+### Step 3: Targeted Grooming (optional)
+
+If specific entries need attention:
+
+```
+YOUR_AGENT_curator op:curator_groom
+  params: {
+    entryIds: ["<id1>", "<id2>"],
+    tags: ["<suggested-tag>"]
+  }
+```
+
+Report how many entries were updated.
+
+## Exit Criteria
+
+Health snapshot presented. If issues found, user is informed with a clear recommendation to run `vault-curate` for full maintenance or `curator_groom` for spot fixes.

package/src/skills/soleri-deep-review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-deep-review
+tier: default
 description: >
   Use when the user says "deep review", "code smells", "architecture review",
   "is this well architected", or "optimization review". Multi-pass code review

package/src/skills/soleri-deliver-and-ship/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-deliver-and-ship
+tier: default
 description: >
   Use when the user says "ship it", "pre-PR check", "delivery checklist", "is this ready",
   "final review", or "ready to deploy". Runs pre-delivery quality gates

package/src/skills/soleri-discovery-phase/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-discovery-phase
+tier: default
 description: >
   Use when the user says "I don't know where to start", "investigate",
   "research this", "explore the problem", or "discovery". Structured exploration

package/src/skills/soleri-dream/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-dream
+tier: default
 description: >
   Use when the user says "dream", "consolidate memory", "clean up memory",
   "memory cleanup", or "dream status". Runs automatic memory consolidation
@@ -78,7 +79,18 @@ YOUR_AGENT_core op:brain_build_intelligence
 
 Rebuild brain intelligence with the freshly consolidated vault data.
 
-### Step 5: Capture to Memory
+### Step 5: Normalize Relative Dates
+
+If the dream report includes entries with relative date references ("today", "yesterday", "last week"), normalize them. Search for entries containing relative dates and update to absolute ISO dates:
+
+```
+YOUR_AGENT_vault op:search_intelligent
+  params: { query: "today OR yesterday OR last week OR last month", limit: 20 }
+```
+
+For each entry with relative dates, update `content` to replace relative references with absolute dates based on the entry's `capturedAt` timestamp.
+
+### Step 6: Capture to Memory
 
 ```
 YOUR_AGENT_memory op:session_capture
@@ -96,6 +108,24 @@ Auto-dream triggers automatically on session start when BOTH conditions are met:
 
 Manual `/dream` always runs immediately (force=true).
 
+## Auto-Dream Scheduling
+
+To enable periodic auto-dream (runs every 24h after 5+ sessions):
+
+```
+YOUR_AGENT_core op:curator_schedule_start
+  params: {
+    intervalHours: 24,
+    minSessions: 5
+  }
+```
+
+To disable:
+
+```
+YOUR_AGENT_core op:curator_schedule_stop
+```
+
 ## Background
 
 Inspired by Claude Code's AutoDream feature and the neuroscience of REM sleep.

package/src/skills/soleri-env-setup/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-env-setup
+tier: default
 description: >
   Use when the user says "setup environment", "post-clone setup", "broken build",
   "missing dependencies", or "MODULE_NOT_FOUND". Detects what a project needs,

package/src/skills/soleri-executing-plans/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-executing-plans
+tier: default
 description: >
   Use when the user says "execute my plan", "run the plan", "start executing",
   or "implement the plan". Executes tasks sequentially with review checkpoints.

package/src/skills/soleri-finishing-a-development-branch/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-finishing-a-development-branch
+tier: default
 description: >
   Use when the user says "finish branch", "ready to merge", "PR ready",
   "submit PR", or "close branch". Handles pre-merge checks, PR creation,

package/src/skills/soleri-fix-and-learn/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-fix-and-learn
+tier: default
 description: >
   Use when the user says "fix it", "apply the fix", "patch this and remember",
   or "fix and capture". Executes a fix AFTER root cause is identified and

package/src/skills/soleri-health-check/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-health-check
+tier: default
 description: >
   Use when the user says "system health", "agent health", "run diagnostics",
   "system status", or "check health". Read-only health assessment of the

package/src/skills/soleri-intake/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: soleri-intake
+tier: default
+description: >
+  Use when the user says "ingest this", "add this URL", "import this book",
+  "read and capture", "ingest batch", or when processing external content
+  into the vault. Handles URLs, text, books, and batch imports with
+  automatic knowledge extraction.
+---
+
+# Intake — Ingest External Content
+
+Import external content (URLs, books, text, batch files) into the vault with automatic knowledge extraction. The intake skill handles chunking, entity extraction, and vault persistence so you don't have to do it manually.
+
+## When to Use
+
+- User pastes a URL ("save this article to vault")
+- User shares a book or long document ("ingest this book into your knowledge base")
+- User wants to capture raw text from an external source
+- Batch importing multiple sources at once
+
+## Orchestration
+
+### Step 1: Identify Content Type
+
+Determine what the user is providing:
+
+| Type             | Use Op         | When                             |
+| ---------------- | -------------- | -------------------------------- |
+| URL              | `ingest_url`   | User pastes a web link           |
+| Book / long doc  | `ingest_book`  | PDF, long markdown, or file path |
+| Raw text         | `ingest_text`  | User pastes text directly        |
+| Multiple sources | `ingest_batch` | List of URLs or file paths       |
+
+### Step 2: Ingest
+
+**URL:**
+
+```
+YOUR_AGENT_intake op:ingest_url
+  params: {
+    url: "<url>",
+    domain: "<inferred domain>",
+    tags: ["<tag1>", "<tag2>"]
+  }
+```
+
+**Book / Long Document:**
+
+```
+YOUR_AGENT_intake op:ingest_book
+  params: {
+    path: "<file path or url>",
+    title: "<document title>",
+    domain: "<domain>",
+    chunkStrategy: "chapter"
+  }
+```
+
+**Raw Text:**
+
+```
+YOUR_AGENT_intake op:ingest_text
+  params: {
+    text: "<content>",
+    title: "<descriptive title>",
+    domain: "<domain>",
+    tags: ["<tag>"]
+  }
+```
+
+**Batch:**
+
+```
+YOUR_AGENT_intake op:ingest_batch
+  params: {
+    sources: [
+      { type: "url", value: "<url1>" },
+      { type: "url", value: "<url2>" }
+    ],
+    domain: "<domain>"
+  }
+```
+
+### Step 3: Report Results
+
+Present a summary table:
+
+| Field               | Value             |
+| ------------------- | ----------------- |
+| **Entries created** | {count}           |
+| **Domain**          | {domain}          |
+| **Tags**            | {tags.join(', ')} |
+| **Status**          | {status}          |
+
+If any sources failed, list them with reasons so the user can retry.
+
+## Exit Criteria
+
+All content ingested, entry IDs confirmed, results reported to user.

package/src/skills/soleri-knowledge-harvest/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-knowledge-harvest
+tier: default
 description: >
   Use when the user says "learn from this", "harvest knowledge", "ingest this",
   or "extract patterns from". Extracts multiple patterns from a source like

package/src/skills/soleri-loop/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: soleri-loop
+tier: default
+description: >
+  Use when the user says "start a loop", "run until done", "iterate until X",
+  "loop status", or "cancel loop". Manages iterative execution loops that
+  repeat a task until a condition is met or a grade threshold is reached.
+---
+
+# Loop — Iterative Execution
+
+Run a task in a loop until a condition is met — grade threshold, promise fulfilled, or explicit cancellation. Useful for plan refinement, quality iteration, and autonomous improvement cycles.
+
+## When to Use
+
+- Improving a plan until it reaches grade A
+- Running validation until all tests pass
+- Any task that needs to repeat with self-correction until done
+
+## Orchestration
+
+### Step 1: Start Loop
+
+```
+YOUR_AGENT_loop op:loop_start
+  params: {
+    prompt: "<task description>",
+    mode: "<plan-iteration | custom>",
+    maxIterations: <number, default 10>
+  }
+```
+
+**Modes:**
+
+- `plan-iteration` — repeats `create_plan` until grade >= A (target-based)
+- `custom` — user-defined stop condition; loop continues until promise satisfied
+
+Note the `loopId` from the response — needed for status and cancel.
+
+### Step 2: Monitor
+
+At each iteration, check status:
+
+```
+YOUR_AGENT_loop op:loop_status
+  params: { loopId: "<loopId>" }
+```
+
+Report progress to user:
+
+| Field              | Value                                |
+| ------------------ | ------------------------------------ |
+| **Iteration**      | {currentIteration} / {maxIterations} |
+| **Status**         | {status}                             |
+| **Last result**    | {lastResult}                         |
+| **Stop condition** | {stopCondition}                      |
+
+### Step 3: Cancel (if needed)
+
+If the user wants to stop early:
+
+```
+YOUR_AGENT_loop op:loop_cancel
+  params: { loopId: "<loopId>", reason: "<why stopping>" }
+```
+
+## Exit Criteria
+
+Loop completes when: stop condition is met, max iterations reached, or user explicitly cancels. Report final outcome and iteration count.

package/src/skills/soleri-mcp-doctor/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-mcp-doctor
+tier: default
 description: >
   Use when the user says "MCP not working", "tools missing", "fix MCP",
   "mcp doctor", or "server not connecting". Diagnoses and repairs MCP server

package/src/skills/soleri-onboard-me/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: soleri-onboard-me
+tier: default
 description: >
   Use when the user says "onboard me", "I'm new here", "project overview",
   or "what should I know about this codebase". Provides a structured tour