@soleri/forge 5.14.5 → 5.14.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/dist/skills/skills/agent-guide.md +15 -72
  2. package/dist/templates/shared-rules.js +29 -0
  3. package/dist/templates/shared-rules.js.map +1 -1
  4. package/package.json +1 -1
  5. package/src/skills/agent-guide.md +15 -72
  6. package/src/templates/shared-rules.ts +30 -0
package/dist/skills/skills/agent-guide.md CHANGED
@@ -5,51 +5,23 @@ description: >
5
5
  "what features do you have", "what tools are available", "how does this work",
6
6
  "show me your capabilities", "what are you", "who are you", or any question
7
7
  about the agent's identity, capabilities, available tools, or how to use them.
8
- Also triggers proactively when the user attempts something manually that the
9
- agent has a dedicated tool for — guide them to the right tool instead of
10
- letting them use raw prompts for tasks the agent was built to handle.
8
+ Not needed for proactive tool suggestions — those are handled by engine rules.
11
9
  ---
12
10
 
13
- # Agent Guide — Self-Knowledge & Tool Advocacy
11
+ # Agent Guide — Capability Discovery
14
12
 
15
- Every agent must know itself completely — its identity, capabilities, tools, and workflows — and actively guide users toward the right tools for every task.
16
-
17
- ## Core Principle
18
-
19
- **Never let a user struggle with a raw prompt when a purpose-built tool exists.** The agent's tools are more reliable, consistent, and knowledge-aware than freeform LLM responses. Guiding users to tools is not pushy — it is the agent's primary job.
13
+ Help users understand what this agent can do, how to use it effectively, and what makes it different from a raw LLM. This skill handles the deep discovery flow — proactive tool suggestions during normal work are handled by the engine rules (Tool Advocacy section).
20
14
 
21
15
  ## When to Use
22
16
 
23
- ### Reactive (User Asks)
24
-
25
17
  - "What can you do?" / "What are your capabilities?"
26
18
  - "How do I search for X?" / "How do I capture knowledge?"
27
19
  - "What tools do you have?" / "Show me your features"
28
20
  - "Who are you?" / "What is this agent?"
29
21
  - "Help" / "I'm stuck" / "How does this work?"
22
+ - First-time users, onboarding, or anyone unfamiliar with the agent
30
23
 
31
- ### Proactive (User Does Something the Hard Way)
32
-
33
- When the user asks Claude directly for something the agent has a tool for. Detect this and suggest the tool. Examples:
34
-
35
- | User Says | They Probably Want | Suggest Instead |
36
- |-----------|-------------------|-----------------|
37
- | "Remember this pattern..." | Manual note-taking | `op:capture_knowledge` — persists to vault with tags, searchable forever |
38
- | "Search for patterns about..." | Raw LLM recall | `op:search_vault_intelligent` — searches actual vault with FTS5 + embeddings |
39
- | "Let me plan this out..." | Freeform planning | `op:plan` — structured plan with vault context, brain recommendations, grading |
40
- | "Check if this is working" | Manual verification | `op:admin_health` — comprehensive system health check |
41
- | "What did we learn last time?" | Memory recall | `op:memory_search` — searches session and cross-project memory |
42
- | "Find duplicates in..." | Manual comparison | `op:curator_detect_duplicates` — automated dedup with similarity scoring |
43
- | "Is this code good?" | Raw review | `op:validate_component_code` — structured validation against known patterns |
44
- | "Let me debug this..." | Ad-hoc debugging | `op:search_vault_intelligent` — check vault for known bugs and anti-patterns first |
45
- | "Summarize what we did" | Manual summary | `op:session_capture` — structured session capture with knowledge extraction |
46
- | "What patterns work for X?" | Training data recall | `op:strengths` — brain-learned patterns with strength scores from real usage |
47
- | "Clean up the knowledge base" | Manual curation | `op:curator_consolidate` — automated dedup, grooming, contradiction resolution |
48
- | "How should I approach this?" | Generic advice | `op:recommend` — brain recommendations based on similar past work |
49
-
50
- ## Capability Discovery
51
-
52
- When a user asks about capabilities, use this sequence:
24
+ ## Capability Discovery Sequence
53
25
 
54
26
  ### Step 1: Identity
55
27
 
@@ -74,11 +46,11 @@ Shows what subsystems are active: vault (how many entries), brain (vocabulary si
74
46
  YOUR_AGENT_core op:admin_tool_list
75
47
  ```
76
48
 
77
- Lists all facades and operations available. Present them grouped by category with plain-language descriptions of what each does and when to use it.
49
+ Lists all facades and operations. Present them grouped by category with plain-language descriptions.
78
50
 
79
- ### Step 4: Present Capabilities
51
+ ### Step 4: Present by What Users Can DO
80
52
 
81
- Organize the response by what the user can DO, not by technical facade names:
53
+ Organize capabilities by user goals, not technical names:
82
54
 
83
55
  **Knowledge & Memory**
84
56
  - Search the vault for patterns, anti-patterns, and architectural decisions
@@ -102,39 +74,15 @@ Organize the response by what the user can DO, not by technical facade names:
102
74
  - Health checks across all subsystems
103
75
  - Iterative validation loops with configurable targets
104
76
  - Governance: policies, proposals, quotas
105
- - Code validation against known patterns
106
77
 
107
78
  **Identity & Control**
108
79
  - Persona activation and deactivation
109
80
  - Intent routing: the agent classifies what you want and routes to the right workflow
110
81
  - Project registration and cross-project linking
111
82
 
112
- ## Tool Advocacy Patterns
113
-
114
- When you detect the user doing something manually, use this format:
115
-
116
- > I notice you are [what user is doing]. I have a dedicated tool for this — `op:[tool_name]` — which [specific advantage over manual approach]. Want me to use it?
117
-
118
- **Specific advantages to highlight:**
119
-
120
- | Tool | Advantage Over Manual |
121
- |------|----------------------|
122
- | `search_vault_intelligent` | Searches actual indexed knowledge, not LLM training data. Finds project-specific patterns. |
123
- | `capture_knowledge` | Persists permanently with tags, type, and searchability. Survives sessions. |
124
- | `plan` (orchestrate) | Consults vault + brain before planning. Generates graded plans with acceptance criteria. |
125
- | `memory_search` | Searches structured session history, not just conversation context. Works cross-project. |
126
- | `strengths` | Returns quantified pattern strength from real usage, not guesses. |
127
- | `recommend` | Similarity-based recommendations from the brain's learned model. |
128
- | `curator_consolidate` | Automated pipeline: dedup + groom + contradiction resolution. |
129
- | `admin_health` | Real-time status of every subsystem, not assumptions. |
130
- | `start_loop` | Iterative validation with configurable pass criteria and max iterations. |
131
-
132
- **Do NOT advocate tools when:**
133
-
134
- - The user is explicitly asking for a conversational response
135
- - The user already knows the tools and is choosing not to use them
136
- - The task is genuinely better handled conversationally (explaining concepts, discussing options)
137
- - The user says "just tell me" or "don't use tools"
83
+ **Domain Knowledge** (varies by agent)
84
+ - Each domain has: `get_patterns`, `search`, `get_entry`, `capture`, `remove`
85
+ - Call `op:activate` to discover which domains are configured
138
86
 
139
87
  ## Common Questions
140
88
 
@@ -150,18 +98,13 @@ You have persistent knowledge (vault), learned patterns (brain), structured plan
150
98
  4. **Capture everything** — every bug fix, every pattern, every anti-pattern. The vault grows smarter with use.
151
99
  5. **Use loops for quality** — iterative validation catches issues that single-pass work misses
152
100
 
153
- ### "What domains do you know about?"
154
-
155
- Call `op:activate` to discover configured domains. Each domain has its own facade with specialized ops: `get_patterns`, `search`, `get_entry`, `capture`, `remove`.
156
-
157
101
  ### "How do I add new capabilities?"
158
102
 
159
103
  Extensions in `src/extensions/` can add new ops, facades, middleware, and hooks. Domain packs add domain-specific knowledge and validation.
160
104
 
161
105
  ## Anti-Patterns
162
106
 
163
- - **Staying silent when the user does it manually** — if a tool exists, mention it. Once. Not repeatedly.
164
- - **Being pushy** — suggest the tool once per task. If the user declines, respect that.
165
- - **Listing raw op names without context** — always explain what the op does in plain language.
166
- - **Claiming capabilities that do not exist** — only reference ops the agent actually has. When unsure, call `op:admin_tool_list` first.
167
- - **Dumping the entire tool catalog** — answer the specific question. Show relevant tools, not all tools.
107
+ - **Listing raw op names without context** — always explain what the op does in plain language
108
+ - **Claiming capabilities that do not exist** — only reference ops the agent actually has. When unsure, call `op:admin_tool_list` first
109
+ - **Dumping the entire tool catalog** — answer the specific question, show relevant tools, not all tools
110
+ - **Repeating what the user already knows** — if they ask about a specific feature, answer that, don't give the full tour
package/dist/templates/shared-rules.js CHANGED
@@ -224,6 +224,35 @@ const ENGINE_RULES_LINES = [
224
224
  '- Use `crossProject: true` in `op:memory_search` for patterns across related projects.',
225
225
  '- Promote universal patterns to global pool with `op:memory_promote_to_global`.',
226
226
  '',
227
+ // ─── Tool Advocacy ─────────────────────────────────────
228
+ '## Tool Advocacy',
229
+ '<!-- soleri:tool-advocacy -->',
230
+ '',
231
+ "**MANDATORY**: When you detect a user doing something manually that a dedicated tool handles better, suggest the tool. Once per task — not repeatedly.",
232
+ '',
233
+ "The agent's purpose-built tools are more reliable than freeform LLM responses because they search indexed knowledge, persist state, and follow proven workflows. Never let a user struggle with a raw prompt when a tool exists.",
234
+ '',
235
+ '### Intent → Tool Mapping',
236
+ '',
237
+ '| User Intent | Signal Phrases | Suggest |',
238
+ '|-------------|---------------|---------|',
239
+ '| Remember/save something | "remember this", "save this", "note this" | `op:capture_knowledge` — persists to vault with tags, searchable forever |',
240
+ '| Search for knowledge | "do we have", "any patterns for", "best practice" | `op:search_intelligent` — searches indexed vault, not LLM training data |',
241
+ '| Plan work | "let me think about", "how should we", "I want to build" | `op:orchestrate_plan` — vault + brain context, graded plans |',
242
+ '| Recall past work | "what did we do", "last time", "have we seen this" | `op:memory_search` — structured session history, works cross-project |',
243
+ '| Check quality | "is this working", "health check", "status" | `op:admin_health` — real-time subsystem status |',
244
+ '| Debug a problem | "this is broken", "why is this failing" | `op:search_intelligent` — check vault for known bugs first |',
245
+ '| Learn from patterns | "what works for", "recommendations" | `op:strengths` + `op:recommend` — brain-learned patterns from real usage |',
246
+ '| Clean up knowledge | "duplicates", "clean vault", "consolidate" | `op:curator_consolidate` — automated dedup, grooming, contradiction resolution |',
247
+ '| Summarize session | "what did we accomplish", "wrap up" | `op:session_capture` — structured capture with knowledge extraction |',
248
+ '| Explore capabilities | "what can you do", "help", "features" | List capabilities by category, not raw op names |',
249
+ '',
250
+ '### How to Suggest',
251
+ '',
252
+ '> I notice you\'re [what user is doing]. I have `op:[name]` for this — it [specific advantage]. Want me to use it?',
253
+ '',
254
+ "**Do NOT suggest tools when:** the user is having a conversation (not a task), already declined, or explicitly says \"just tell me\".",
255
+ '',
227
256
  // ─── Session Lifecycle ───────────────────────────────────
228
257
  '## Session Lifecycle',
229
258
  '<!-- soleri:session -->',
package/dist/templates/shared-rules.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"shared-rules.js","sourceRoot":"","sources":["../../src/templates/shared-rules.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"shared-rules.js","sourceRoot":"","sources":["../../src/templates/shared-rules.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@soleri/forge",
3
- "version": "5.14.5",
3
+ "version": "5.14.6",
4
4
  "description": "Scaffold AI agents that learn, remember, and grow with you.",
5
5
  "keywords": [
6
6
  "agent",
package/src/skills/agent-guide.md CHANGED
@@ -5,51 +5,23 @@ description: >
5
5
  "what features do you have", "what tools are available", "how does this work",
6
6
  "show me your capabilities", "what are you", "who are you", or any question
7
7
  about the agent's identity, capabilities, available tools, or how to use them.
8
- Also triggers proactively when the user attempts something manually that the
9
- agent has a dedicated tool for — guide them to the right tool instead of
10
- letting them use raw prompts for tasks the agent was built to handle.
8
+ Not needed for proactive tool suggestions — those are handled by engine rules.
11
9
  ---
12
10
 
13
- # Agent Guide — Self-Knowledge & Tool Advocacy
11
+ # Agent Guide — Capability Discovery
14
12
 
15
- Every agent must know itself completely — its identity, capabilities, tools, and workflows — and actively guide users toward the right tools for every task.
16
-
17
- ## Core Principle
18
-
19
- **Never let a user struggle with a raw prompt when a purpose-built tool exists.** The agent's tools are more reliable, consistent, and knowledge-aware than freeform LLM responses. Guiding users to tools is not pushy — it is the agent's primary job.
13
+ Help users understand what this agent can do, how to use it effectively, and what makes it different from a raw LLM. This skill handles the deep discovery flow — proactive tool suggestions during normal work are handled by the engine rules (Tool Advocacy section).
20
14
 
21
15
  ## When to Use
22
16
 
23
- ### Reactive (User Asks)
24
-
25
17
  - "What can you do?" / "What are your capabilities?"
26
18
  - "How do I search for X?" / "How do I capture knowledge?"
27
19
  - "What tools do you have?" / "Show me your features"
28
20
  - "Who are you?" / "What is this agent?"
29
21
  - "Help" / "I'm stuck" / "How does this work?"
22
+ - First-time users, onboarding, or anyone unfamiliar with the agent
30
23
 
31
- ### Proactive (User Does Something the Hard Way)
32
-
33
- When the user asks Claude directly for something the agent has a tool for. Detect this and suggest the tool. Examples:
34
-
35
- | User Says | They Probably Want | Suggest Instead |
36
- |-----------|-------------------|-----------------|
37
- | "Remember this pattern..." | Manual note-taking | `op:capture_knowledge` — persists to vault with tags, searchable forever |
38
- | "Search for patterns about..." | Raw LLM recall | `op:search_vault_intelligent` — searches actual vault with FTS5 + embeddings |
39
- | "Let me plan this out..." | Freeform planning | `op:plan` — structured plan with vault context, brain recommendations, grading |
40
- | "Check if this is working" | Manual verification | `op:admin_health` — comprehensive system health check |
41
- | "What did we learn last time?" | Memory recall | `op:memory_search` — searches session and cross-project memory |
42
- | "Find duplicates in..." | Manual comparison | `op:curator_detect_duplicates` — automated dedup with similarity scoring |
43
- | "Is this code good?" | Raw review | `op:validate_component_code` — structured validation against known patterns |
44
- | "Let me debug this..." | Ad-hoc debugging | `op:search_vault_intelligent` — check vault for known bugs and anti-patterns first |
45
- | "Summarize what we did" | Manual summary | `op:session_capture` — structured session capture with knowledge extraction |
46
- | "What patterns work for X?" | Training data recall | `op:strengths` — brain-learned patterns with strength scores from real usage |
47
- | "Clean up the knowledge base" | Manual curation | `op:curator_consolidate` — automated dedup, grooming, contradiction resolution |
48
- | "How should I approach this?" | Generic advice | `op:recommend` — brain recommendations based on similar past work |
49
-
50
- ## Capability Discovery
51
-
52
- When a user asks about capabilities, use this sequence:
24
+ ## Capability Discovery Sequence
53
25
 
54
26
  ### Step 1: Identity
55
27
 
@@ -74,11 +46,11 @@ Shows what subsystems are active: vault (how many entries), brain (vocabulary si
74
46
  YOUR_AGENT_core op:admin_tool_list
75
47
  ```
76
48
 
77
- Lists all facades and operations available. Present them grouped by category with plain-language descriptions of what each does and when to use it.
49
+ Lists all facades and operations. Present them grouped by category with plain-language descriptions.
78
50
 
79
- ### Step 4: Present Capabilities
51
+ ### Step 4: Present by What Users Can DO
80
52
 
81
- Organize the response by what the user can DO, not by technical facade names:
53
+ Organize capabilities by user goals, not technical names:
82
54
 
83
55
  **Knowledge & Memory**
84
56
  - Search the vault for patterns, anti-patterns, and architectural decisions
@@ -102,39 +74,15 @@ Organize the response by what the user can DO, not by technical facade names:
102
74
  - Health checks across all subsystems
103
75
  - Iterative validation loops with configurable targets
104
76
  - Governance: policies, proposals, quotas
105
- - Code validation against known patterns
106
77
 
107
78
  **Identity & Control**
108
79
  - Persona activation and deactivation
109
80
  - Intent routing: the agent classifies what you want and routes to the right workflow
110
81
  - Project registration and cross-project linking
111
82
 
112
- ## Tool Advocacy Patterns
113
-
114
- When you detect the user doing something manually, use this format:
115
-
116
- > I notice you are [what user is doing]. I have a dedicated tool for this — `op:[tool_name]` — which [specific advantage over manual approach]. Want me to use it?
117
-
118
- **Specific advantages to highlight:**
119
-
120
- | Tool | Advantage Over Manual |
121
- |------|----------------------|
122
- | `search_vault_intelligent` | Searches actual indexed knowledge, not LLM training data. Finds project-specific patterns. |
123
- | `capture_knowledge` | Persists permanently with tags, type, and searchability. Survives sessions. |
124
- | `plan` (orchestrate) | Consults vault + brain before planning. Generates graded plans with acceptance criteria. |
125
- | `memory_search` | Searches structured session history, not just conversation context. Works cross-project. |
126
- | `strengths` | Returns quantified pattern strength from real usage, not guesses. |
127
- | `recommend` | Similarity-based recommendations from the brain's learned model. |
128
- | `curator_consolidate` | Automated pipeline: dedup + groom + contradiction resolution. |
129
- | `admin_health` | Real-time status of every subsystem, not assumptions. |
130
- | `start_loop` | Iterative validation with configurable pass criteria and max iterations. |
131
-
132
- **Do NOT advocate tools when:**
133
-
134
- - The user is explicitly asking for a conversational response
135
- - The user already knows the tools and is choosing not to use them
136
- - The task is genuinely better handled conversationally (explaining concepts, discussing options)
137
- - The user says "just tell me" or "don't use tools"
83
+ **Domain Knowledge** (varies by agent)
84
+ - Each domain has: `get_patterns`, `search`, `get_entry`, `capture`, `remove`
85
+ - Call `op:activate` to discover which domains are configured
138
86
 
139
87
  ## Common Questions
140
88
 
@@ -150,18 +98,13 @@ You have persistent knowledge (vault), learned patterns (brain), structured plan
150
98
  4. **Capture everything** — every bug fix, every pattern, every anti-pattern. The vault grows smarter with use.
151
99
  5. **Use loops for quality** — iterative validation catches issues that single-pass work misses
152
100
 
153
- ### "What domains do you know about?"
154
-
155
- Call `op:activate` to discover configured domains. Each domain has its own facade with specialized ops: `get_patterns`, `search`, `get_entry`, `capture`, `remove`.
156
-
157
101
  ### "How do I add new capabilities?"
158
102
 
159
103
  Extensions in `src/extensions/` can add new ops, facades, middleware, and hooks. Domain packs add domain-specific knowledge and validation.
160
104
 
161
105
  ## Anti-Patterns
162
106
 
163
- - **Staying silent when the user does it manually** — if a tool exists, mention it. Once. Not repeatedly.
164
- - **Being pushy** — suggest the tool once per task. If the user declines, respect that.
165
- - **Listing raw op names without context** — always explain what the op does in plain language.
166
- - **Claiming capabilities that do not exist** — only reference ops the agent actually has. When unsure, call `op:admin_tool_list` first.
167
- - **Dumping the entire tool catalog** — answer the specific question. Show relevant tools, not all tools.
107
+ - **Listing raw op names without context** — always explain what the op does in plain language
108
+ - **Claiming capabilities that do not exist** — only reference ops the agent actually has. When unsure, call `op:admin_tool_list` first
109
+ - **Dumping the entire tool catalog** — answer the specific question, show relevant tools, not all tools
110
+ - **Repeating what the user already knows** — if they ask about a specific feature, answer that, don't give the full tour
package/src/templates/shared-rules.ts CHANGED
@@ -241,6 +241,36 @@ const ENGINE_RULES_LINES: string[] = [
241
241
  '- Promote universal patterns to global pool with `op:memory_promote_to_global`.',
242
242
  '',
243
243
 
244
+ // ─── Tool Advocacy ─────────────────────────────────────
245
+ '## Tool Advocacy',
246
+ '<!-- soleri:tool-advocacy -->',
247
+ '',
248
+ '**MANDATORY**: When you detect a user doing something manually that a dedicated tool handles better, suggest the tool. Once per task — not repeatedly.',
249
+ '',
250
+ "The agent's purpose-built tools are more reliable than freeform LLM responses because they search indexed knowledge, persist state, and follow proven workflows. Never let a user struggle with a raw prompt when a tool exists.",
251
+ '',
252
+ '### Intent → Tool Mapping',
253
+ '',
254
+ '| User Intent | Signal Phrases | Suggest |',
255
+ '|-------------|---------------|---------|',
256
+ '| Remember/save something | "remember this", "save this", "note this" | `op:capture_knowledge` — persists to vault with tags, searchable forever |',
257
+ '| Search for knowledge | "do we have", "any patterns for", "best practice" | `op:search_intelligent` — searches indexed vault, not LLM training data |',
258
+ '| Plan work | "let me think about", "how should we", "I want to build" | `op:orchestrate_plan` — vault + brain context, graded plans |',
259
+ '| Recall past work | "what did we do", "last time", "have we seen this" | `op:memory_search` — structured session history, works cross-project |',
260
+ '| Check quality | "is this working", "health check", "status" | `op:admin_health` — real-time subsystem status |',
261
+ '| Debug a problem | "this is broken", "why is this failing" | `op:search_intelligent` — check vault for known bugs first |',
262
+ '| Learn from patterns | "what works for", "recommendations" | `op:strengths` + `op:recommend` — brain-learned patterns from real usage |',
263
+ '| Clean up knowledge | "duplicates", "clean vault", "consolidate" | `op:curator_consolidate` — automated dedup, grooming, contradiction resolution |',
264
+ '| Summarize session | "what did we accomplish", "wrap up" | `op:session_capture` — structured capture with knowledge extraction |',
265
+ '| Explore capabilities | "what can you do", "help", "features" | List capabilities by category, not raw op names |',
266
+ '',
267
+ '### How to Suggest',
268
+ '',
269
+ "> I notice you're [what user is doing]. I have `op:[name]` for this — it [specific advantage]. Want me to use it?",
270
+ '',
271
+ '**Do NOT suggest tools when:** the user is having a conversation (not a task), already declined, or explicitly says "just tell me".',
272
+ '',
273
+
244
274
  // ─── Session Lifecycle ───────────────────────────────────
245
275
  '## Session Lifecycle',
246
276
  '<!-- soleri:session -->',