@soleri/forge 5.14.4 → 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 (10) hide show
  1. package/dist/skills/skills/agent-guide.md +110 -0
  2. package/dist/templates/shared-rules.js +29 -0
  3. package/dist/templates/shared-rules.js.map +1 -1
  4. package/dist/templates/skills.js +1 -0
  5. package/dist/templates/skills.js.map +1 -1
  6. package/package.json +1 -1
  7. package/src/__tests__/scaffolder.test.ts +2 -1
  8. package/src/skills/agent-guide.md +110 -0
  9. package/src/templates/shared-rules.ts +30 -0
  10. package/src/templates/skills.ts +1 -0
package/dist/skills/skills/agent-guide.md ADDED
@@ -0,0 +1,110 @@
1
+ ---
2
+ name: agent-guide
3
+ description: >
4
+ Use when the user asks "what can you do", "help me", "how do I use this",
5
+ "what features do you have", "what tools are available", "how does this work",
6
+ "show me your capabilities", "what are you", "who are you", or any question
7
+ about the agent's identity, capabilities, available tools, or how to use them.
8
+ Not needed for proactive tool suggestions — those are handled by engine rules.
9
+ ---
10
+
11
+ # Agent Guide — Capability Discovery
12
+
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).
14
+
15
+ ## When to Use
16
+
17
+ - "What can you do?" / "What are your capabilities?"
18
+ - "How do I search for X?" / "How do I capture knowledge?"
19
+ - "What tools do you have?" / "Show me your features"
20
+ - "Who are you?" / "What is this agent?"
21
+ - "Help" / "I'm stuck" / "How does this work?"
22
+ - First-time users, onboarding, or anyone unfamiliar with the agent
23
+
24
+ ## Capability Discovery Sequence
25
+
26
+ ### Step 1: Identity
27
+
28
+ ```
29
+ YOUR_AGENT_core op:activate
30
+ params: { projectPath: "." }
31
+ ```
32
+
33
+ This returns the agent's persona: name, role, description, tone, principles, and domains. Present the identity first — who the agent is and what it specializes in.
34
+
35
+ ### Step 2: Health & Status
36
+
37
+ ```
38
+ YOUR_AGENT_core op:admin_health
39
+ ```
40
+
41
+ Shows what subsystems are active: vault (how many entries), brain (vocabulary size), LLM availability, cognee status. This tells the user what the agent currently has to work with.
42
+
43
+ ### Step 3: Available Tools
44
+
45
+ ```
46
+ YOUR_AGENT_core op:admin_tool_list
47
+ ```
48
+
49
+ Lists all facades and operations. Present them grouped by category with plain-language descriptions.
50
+
51
+ ### Step 4: Present by What Users Can DO
52
+
53
+ Organize capabilities by user goals, not technical names:
54
+
55
+ **Knowledge & Memory**
56
+ - Search the vault for patterns, anti-patterns, and architectural decisions
57
+ - Capture new knowledge from the current session
58
+ - Search across sessions and projects for relevant context
59
+ - Curate: deduplicate, groom, resolve contradictions
60
+
61
+ **Planning & Execution**
62
+ - Create structured plans with vault context and brain recommendations
63
+ - Split plans into tasks with complexity estimates
64
+ - Track execution with drift detection
65
+ - Complete with knowledge capture and session recording
66
+
67
+ **Intelligence & Learning**
68
+ - Brain learns from every session — patterns get stronger with use
69
+ - Recommendations based on similar past work
70
+ - Strength tracking: which patterns are proven vs experimental
71
+ - Feedback loop: brain improves based on what works
72
+
73
+ **Quality & Validation**
74
+ - Health checks across all subsystems
75
+ - Iterative validation loops with configurable targets
76
+ - Governance: policies, proposals, quotas
77
+
78
+ **Identity & Control**
79
+ - Persona activation and deactivation
80
+ - Intent routing: the agent classifies what you want and routes to the right workflow
81
+ - Project registration and cross-project linking
82
+
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
86
+
87
+ ## Common Questions
88
+
89
+ ### "What makes you different from regular Claude?"
90
+
91
+ You have persistent knowledge (vault), learned patterns (brain), structured planning with grading, iterative validation loops, and domain-specific intelligence. Regular Claude starts fresh every conversation — this agent accumulates knowledge and gets smarter over time.
92
+
93
+ ### "How do I get the most out of you?"
94
+
95
+ 1. **Use the vault** — search before deciding, capture after learning
96
+ 2. **Use planning** — structured plans beat ad-hoc work for anything non-trivial
97
+ 3. **Trust the brain** — pattern recommendations come from real usage data
98
+ 4. **Capture everything** — every bug fix, every pattern, every anti-pattern. The vault grows smarter with use.
99
+ 5. **Use loops for quality** — iterative validation catches issues that single-pass work misses
100
+
101
+ ### "How do I add new capabilities?"
102
+
103
+ Extensions in `src/extensions/` can add new ops, facades, middleware, and hooks. Domain packs add domain-specific knowledge and validation.
104
+
105
+ ## Anti-Patterns
106
+
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":"AAAA;;;;;;;;;GASG;AAEH,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAE5C,MAAM,UAAU,eAAe;IAC7B,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,qBAAqB;IACnC,OAAO,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,kBAAkB,GAAa;IACnC,QAAQ,aAAa,MAAM;IAC3B,EAAE;IACF,uBAAuB;IACvB,EAAE;IACF,qGAAqG;IACrG,EAAE;IAEF,2DAA2D;IAC3D,uBAAuB;IACvB,oCAAoC;IACpC,EAAE;IACF,8FAA8F;IAC9F,uFAAuF;IACvF,EAAE;IAEF,0DAA0D;IAC1D,wBAAwB;IACxB,gCAAgC;IAChC,EAAE;IACF,2FAA2F;IAC3F,EAAE;IACF,2GAA2G;IAC3G,+KAA+K;IAC/K,EAAE;IACF,qFAAqF;IACrF,EAAE;IAEF,4DAA4D;IAC5D,6BAA6B;IAC7B,gCAAgC;IAChC,EAAE;IACF,uHAAuH;IACvH,sHAAsH;IACtH,+EAA+E;IAC/E,8FAA8F;IAC9F,sGAAsG;IACtG,EAAE;IAEF,4DAA4D;IAC5D,aAAa;IACb,0BAA0B;IAC1B,EAAE;IACF,mFAAmF;IACnF,+FAA+F;IAC/F,yEAAyE;IACzE,uHAAuH;IACvH,2FAA2F;IAC3F,oFAAoF;IACpF,gFAAgF;IAChF,EAAE;IACF,sBAAsB;IACtB,EAAE;IACF,mCAAmC;IACnC,mCAAmC;IACnC,mDAAmD;IACnD,2CAA2C;IAC3C,+CAA+C;IAC/C,0DAA0D;IAC1D,4BAA4B;IAC5B,EAAE;IACF,uBAAuB;IACvB,EAAE;IACF,8CAA8C;IAC9C,EAAE;IACF,KAAK;IACL,wBAAwB;IACxB,EAAE;IACF,mBAAmB;IACnB,mBAAmB;IACnB,4BAA4B;IAC5B,8BAA8B;IAC9B,uCAAuC;IACvC,2BAA2B;IAC3B,uCAAuC;IACvC,EAAE;IACF,+BAA+B;IAC/B,EAAE;IACF,YAAY;IACZ,yBAAyB;IACzB,yBAAyB;IACzB,yBAAyB;IACzB,EAAE;IACF,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,qBAAqB;IACrB,KAAK;IACL,EAAE;IACF,wEAAwE;IACxE,EAAE;IACF,kBAAkB;IAClB,EAAE;IACF,KAAK;IACL,mBAAmB;IACnB,mBAAmB;IACnB,wCAAwC;IACxC,+BAA+B;IAC/B,EAAE;IACF,6CAA6C;IAC7C,6CAA6C;IAC7C,kCAAkC;IAClC,KAAK;IACL,EAAE;IAEF,4DAA4D;IAC5D,sBAAsB;IACtB,mCAAmC;IACnC,EAAE;IACF,6EAA6E;IAC7E,EAAE;IACF,qCAAqC;IACrC,KAAK;IACL,kCAAkC;IAClC,kCAAkC;IAClC,2BAA2B;IAC3B,KAAK;IACL,EAAE;IACF,wEAAwE;IACxE,EAAE;IACF,4FAA4F;IAC5F,EAAE;IAEF,4DAA4D;IAC5D,kBAAkB;IAClB,+BAA+B;IAC/B,EAAE;IACF,sDAAsD;IACtD,EAAE;IACF,mBAAmB;IACnB,0CAA0C;IAC1C,2BAA2B;IAC3B,2CAA2C;IAC3C,8EAA8E;IAC9E,EAAE;IACF,2BAA2B;IAC3B,KAAK;IACL,+BAA+B;IAC/B,kCAAkC;IAClC,wCAAwC;IACxC,KAAK;IACL,EAAE;IAEF,4DAA4D;IAC5D,sBAAsB;IACtB,mCAAmC;IACnC,EAAE;IACF,0DAA0D;IAC1D,EAAE;IACF,+CAA+C;IAC/C,+CAA+C;IAC/C,2DAA2D;IAC3D,6DAA6D;IAC7D,EAAE;IACF,6BAA6B;IAC7B,8BAA8B;IAC9B,6DAA6D;IAC7D,gDAAgD;IAChD,uDAAuD;IACvD,EAAE;IAEF,4DAA4D;IAC5D,sBAAsB;IACtB,8BAA8B;IAC9B,EAAE;IACF,iDAAiD;IACjD,4DAA4D;IAC5D,kDAAkD;IAClD,0DAA0D;IAC1D,EAAE;IACF,oGAAoG;IACpG,EAAE;IAEF,4DAA4D;IAC5D,qBAAqB;IACrB,kCAAkC;IAClC,EAAE;IACF,4EAA4E;IAC5E,EAAE;IACF,qBAAqB;IACrB,qBAAqB;IACrB,0DAA0D;IAC1D,yDAAyD;IACzD,oDAAoD;IACpD,uDAAuD;IACvD,wDAAwD;IACxD,mDAAmD;IACnD,EAAE;IACF,iFAAiF;IACjF,EAAE;IAEF,4DAA4D;IAC5D,8BAA8B;IAC9B,iCAAiC;IACjC,EAAE;IACF,gHAAgH;IAChH,uHAAuH;IACvH,EAAE;IACF,mCAAmC;IACnC,oCAAoC;IACpC,2DAA2D;IAC3D,kDAAkD;IAClD,EAAE;IAEF,4DAA4D;IAC5D,wBAAwB;IACxB,uBAAuB;IACvB,EAAE;IACF,2GAA2G;IAC3G,6HAA6H;IAC7H,2FAA2F;IAC3F,EAAE;IAEF,4DAA4D;IAC5D,yBAAyB;IACzB,+BAA+B;IAC/B,EAAE;IACF,wFAAwF;IACxF,iFAAiF;IACjF,EAAE;IAEF,0DAA0D;IAC1D,kBAAkB;IAClB,+BAA+B;IAC/B,EAAE;IACF,wJAAwJ;IACxJ,EAAE;IACF,kOAAkO;IAClO,EAAE;IACF,2BAA2B;IAC3B,EAAE;IACF,4CAA4C;IAC5C,2CAA2C;IAC3C,oJAAoJ;IACpJ,wJAAwJ;IACxJ,wIAAwI;IACxI,kJAAkJ;IAClJ,kHAAkH;IAClH,4HAA4H;IAC5H,0IAA0I;IAC1I,sJAAsJ;IACtJ,mIAAmI;IACnI,oHAAoH;IACpH,EAAE;IACF,oBAAoB;IACpB,EAAE;IACF,oHAAoH;IACpH,EAAE;IACF,uIAAuI;IACvI,EAAE;IAEF,4DAA4D;IAC5D,sBAAsB;IACtB,yBAAyB;IACzB,EAAE;IACF,4BAA4B;IAC5B,EAAE;IACF,uBAAuB;IACvB,gEAAgE;IAChE,iGAAiG;IACjG,wEAAwE;IACxE,6DAA6D;IAC7D,wEAAwE;IACxE,EAAE;IACF,wBAAwB;IACxB,EAAE;IACF,yEAAyE;IACzE,gEAAgE;IAChE,EAAE;IAEF,SAAS,aAAa,MAAM;CAC7B,CAAC"}
package/dist/templates/skills.js CHANGED
@@ -6,6 +6,7 @@ const SKILLS_DIR = join(__dirname, '..', 'skills');
6
6
  /** Skills that use YOUR_AGENT_core placeholder and need agent-specific substitution. */
7
7
  const AGENT_SPECIFIC_SKILLS = new Set([
8
8
  'agent-dev',
9
+ 'agent-guide',
9
10
  'agent-persona',
10
11
  'brain-debrief',
11
12
  'brainstorming',
package/dist/templates/skills.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/templates/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnD,wFAAwF;AACxF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,WAAW;IACX,eAAe;IACf,eAAe;IACf,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,YAAY;IACZ,eAAe;IACf,gBAAgB;IAChB,sBAAsB;IACtB,yBAAyB;IACzB,eAAe;IACf,cAAc;IACd,iBAAiB;IACjB,gCAAgC;IAChC,eAAe;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,UAAoB,CAAC;IAEzB,IAAI,CAAC;QACH,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,gEAAgE;IAChE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAE5G,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAE1C,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAE5D,IAAI,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,SAAS,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
1
+ {"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/templates/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAEnD,wFAAwF;AACxF,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,WAAW;IACX,aAAa;IACb,eAAe;IACf,eAAe;IACf,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,YAAY;IACZ,eAAe;IACf,gBAAgB;IAChB,sBAAsB;IACtB,yBAAyB;IACzB,eAAe;IACf,cAAc;IACd,iBAAiB;IACjB,gCAAgC;IAChC,eAAe;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,IAAI,UAAoB,CAAC;IAEzB,IAAI,CAAC;QACH,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2DAA2D;IAC3D,gEAAgE;IAChE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAE5G,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAE1C,IAAI,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACnD,SAAS;QACX,CAAC;QAED,IAAI,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAE5D,IAAI,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,SAAS,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@soleri/forge",
3
- "version": "5.14.4",
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/__tests__/scaffolder.test.ts CHANGED
@@ -262,7 +262,7 @@ describe('Scaffolder', () => {
262
262
  .filter((e) => e.isDirectory())
263
263
  .map((e) => e.name);
264
264
 
265
- expect(skillDirs).toHaveLength(22);
265
+ expect(skillDirs).toHaveLength(23);
266
266
 
267
267
  // Verify each skill dir has a SKILL.md
268
268
  for (const dir of skillDirs) {
@@ -277,6 +277,7 @@ describe('Scaffolder', () => {
277
277
 
278
278
  expect(skillDirs).toEqual([
279
279
  'agent-dev',
280
+ 'agent-guide',
280
281
  'agent-persona',
281
282
  'brain-debrief',
282
283
  'brainstorming',
package/src/skills/agent-guide.md ADDED
@@ -0,0 +1,110 @@
1
+ ---
2
+ name: agent-guide
3
+ description: >
4
+ Use when the user asks "what can you do", "help me", "how do I use this",
5
+ "what features do you have", "what tools are available", "how does this work",
6
+ "show me your capabilities", "what are you", "who are you", or any question
7
+ about the agent's identity, capabilities, available tools, or how to use them.
8
+ Not needed for proactive tool suggestions — those are handled by engine rules.
9
+ ---
10
+
11
+ # Agent Guide — Capability Discovery
12
+
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).
14
+
15
+ ## When to Use
16
+
17
+ - "What can you do?" / "What are your capabilities?"
18
+ - "How do I search for X?" / "How do I capture knowledge?"
19
+ - "What tools do you have?" / "Show me your features"
20
+ - "Who are you?" / "What is this agent?"
21
+ - "Help" / "I'm stuck" / "How does this work?"
22
+ - First-time users, onboarding, or anyone unfamiliar with the agent
23
+
24
+ ## Capability Discovery Sequence
25
+
26
+ ### Step 1: Identity
27
+
28
+ ```
29
+ YOUR_AGENT_core op:activate
30
+ params: { projectPath: "." }
31
+ ```
32
+
33
+ This returns the agent's persona: name, role, description, tone, principles, and domains. Present the identity first — who the agent is and what it specializes in.
34
+
35
+ ### Step 2: Health & Status
36
+
37
+ ```
38
+ YOUR_AGENT_core op:admin_health
39
+ ```
40
+
41
+ Shows what subsystems are active: vault (how many entries), brain (vocabulary size), LLM availability, cognee status. This tells the user what the agent currently has to work with.
42
+
43
+ ### Step 3: Available Tools
44
+
45
+ ```
46
+ YOUR_AGENT_core op:admin_tool_list
47
+ ```
48
+
49
+ Lists all facades and operations. Present them grouped by category with plain-language descriptions.
50
+
51
+ ### Step 4: Present by What Users Can DO
52
+
53
+ Organize capabilities by user goals, not technical names:
54
+
55
+ **Knowledge & Memory**
56
+ - Search the vault for patterns, anti-patterns, and architectural decisions
57
+ - Capture new knowledge from the current session
58
+ - Search across sessions and projects for relevant context
59
+ - Curate: deduplicate, groom, resolve contradictions
60
+
61
+ **Planning & Execution**
62
+ - Create structured plans with vault context and brain recommendations
63
+ - Split plans into tasks with complexity estimates
64
+ - Track execution with drift detection
65
+ - Complete with knowledge capture and session recording
66
+
67
+ **Intelligence & Learning**
68
+ - Brain learns from every session — patterns get stronger with use
69
+ - Recommendations based on similar past work
70
+ - Strength tracking: which patterns are proven vs experimental
71
+ - Feedback loop: brain improves based on what works
72
+
73
+ **Quality & Validation**
74
+ - Health checks across all subsystems
75
+ - Iterative validation loops with configurable targets
76
+ - Governance: policies, proposals, quotas
77
+
78
+ **Identity & Control**
79
+ - Persona activation and deactivation
80
+ - Intent routing: the agent classifies what you want and routes to the right workflow
81
+ - Project registration and cross-project linking
82
+
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
86
+
87
+ ## Common Questions
88
+
89
+ ### "What makes you different from regular Claude?"
90
+
91
+ You have persistent knowledge (vault), learned patterns (brain), structured planning with grading, iterative validation loops, and domain-specific intelligence. Regular Claude starts fresh every conversation — this agent accumulates knowledge and gets smarter over time.
92
+
93
+ ### "How do I get the most out of you?"
94
+
95
+ 1. **Use the vault** — search before deciding, capture after learning
96
+ 2. **Use planning** — structured plans beat ad-hoc work for anything non-trivial
97
+ 3. **Trust the brain** — pattern recommendations come from real usage data
98
+ 4. **Capture everything** — every bug fix, every pattern, every anti-pattern. The vault grows smarter with use.
99
+ 5. **Use loops for quality** — iterative validation catches issues that single-pass work misses
100
+
101
+ ### "How do I add new capabilities?"
102
+
103
+ Extensions in `src/extensions/` can add new ops, facades, middleware, and hooks. Domain packs add domain-specific knowledge and validation.
104
+
105
+ ## Anti-Patterns
106
+
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 -->',
package/src/templates/skills.ts CHANGED
@@ -9,6 +9,7 @@ const SKILLS_DIR = join(__dirname, '..', 'skills');
9
9
  /** Skills that use YOUR_AGENT_core placeholder and need agent-specific substitution. */
10
10
  const AGENT_SPECIFIC_SKILLS = new Set([
11
11
  'agent-dev',
12
+ 'agent-guide',
12
13
  'agent-persona',
13
14
  'brain-debrief',
14
15
  'brainstorming',