@soleri/forge 0.0.1 → 4.0.0

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 (128) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/README.md +199 -0
  3. package/dist/facades/forge.facade.d.ts +9 -0
  4. package/dist/facades/forge.facade.js +134 -0
  5. package/dist/facades/forge.facade.js.map +1 -0
  6. package/dist/index.d.ts +2 -0
  7. package/dist/index.js +81 -0
  8. package/dist/index.js.map +1 -0
  9. package/dist/knowledge-installer.d.ts +31 -0
  10. package/dist/knowledge-installer.js +437 -0
  11. package/dist/knowledge-installer.js.map +1 -0
  12. package/dist/scaffolder.d.ts +13 -0
  13. package/dist/scaffolder.js +330 -0
  14. package/dist/scaffolder.js.map +1 -0
  15. package/dist/templates/activate.d.ts +9 -0
  16. package/dist/templates/activate.js +139 -0
  17. package/dist/templates/activate.js.map +1 -0
  18. package/dist/templates/brain.d.ts +6 -0
  19. package/dist/templates/brain.js +478 -0
  20. package/dist/templates/brain.js.map +1 -0
  21. package/dist/templates/claude-md-template.d.ts +11 -0
  22. package/dist/templates/claude-md-template.js +73 -0
  23. package/dist/templates/claude-md-template.js.map +1 -0
  24. package/dist/templates/core-facade.d.ts +6 -0
  25. package/dist/templates/core-facade.js +456 -0
  26. package/dist/templates/core-facade.js.map +1 -0
  27. package/dist/templates/domain-facade.d.ts +7 -0
  28. package/dist/templates/domain-facade.js +119 -0
  29. package/dist/templates/domain-facade.js.map +1 -0
  30. package/dist/templates/entry-point.d.ts +5 -0
  31. package/dist/templates/entry-point.js +116 -0
  32. package/dist/templates/entry-point.js.map +1 -0
  33. package/dist/templates/facade-factory.d.ts +1 -0
  34. package/dist/templates/facade-factory.js +63 -0
  35. package/dist/templates/facade-factory.js.map +1 -0
  36. package/dist/templates/facade-types.d.ts +1 -0
  37. package/dist/templates/facade-types.js +46 -0
  38. package/dist/templates/facade-types.js.map +1 -0
  39. package/dist/templates/inject-claude-md.d.ts +11 -0
  40. package/dist/templates/inject-claude-md.js +92 -0
  41. package/dist/templates/inject-claude-md.js.map +1 -0
  42. package/dist/templates/intelligence-loader.d.ts +1 -0
  43. package/dist/templates/intelligence-loader.js +43 -0
  44. package/dist/templates/intelligence-loader.js.map +1 -0
  45. package/dist/templates/intelligence-types.d.ts +1 -0
  46. package/dist/templates/intelligence-types.js +24 -0
  47. package/dist/templates/intelligence-types.js.map +1 -0
  48. package/dist/templates/llm-client.d.ts +7 -0
  49. package/dist/templates/llm-client.js +300 -0
  50. package/dist/templates/llm-client.js.map +1 -0
  51. package/dist/templates/llm-key-pool.d.ts +7 -0
  52. package/dist/templates/llm-key-pool.js +211 -0
  53. package/dist/templates/llm-key-pool.js.map +1 -0
  54. package/dist/templates/llm-types.d.ts +5 -0
  55. package/dist/templates/llm-types.js +161 -0
  56. package/dist/templates/llm-types.js.map +1 -0
  57. package/dist/templates/llm-utils.d.ts +5 -0
  58. package/dist/templates/llm-utils.js +260 -0
  59. package/dist/templates/llm-utils.js.map +1 -0
  60. package/dist/templates/package-json.d.ts +2 -0
  61. package/dist/templates/package-json.js +37 -0
  62. package/dist/templates/package-json.js.map +1 -0
  63. package/dist/templates/persona.d.ts +2 -0
  64. package/dist/templates/persona.js +42 -0
  65. package/dist/templates/persona.js.map +1 -0
  66. package/dist/templates/planner.d.ts +5 -0
  67. package/dist/templates/planner.js +150 -0
  68. package/dist/templates/planner.js.map +1 -0
  69. package/dist/templates/readme.d.ts +5 -0
  70. package/dist/templates/readme.js +316 -0
  71. package/dist/templates/readme.js.map +1 -0
  72. package/dist/templates/setup-script.d.ts +6 -0
  73. package/dist/templates/setup-script.js +112 -0
  74. package/dist/templates/setup-script.js.map +1 -0
  75. package/dist/templates/test-brain.d.ts +6 -0
  76. package/dist/templates/test-brain.js +474 -0
  77. package/dist/templates/test-brain.js.map +1 -0
  78. package/dist/templates/test-facades.d.ts +6 -0
  79. package/dist/templates/test-facades.js +649 -0
  80. package/dist/templates/test-facades.js.map +1 -0
  81. package/dist/templates/test-llm.d.ts +7 -0
  82. package/dist/templates/test-llm.js +574 -0
  83. package/dist/templates/test-llm.js.map +1 -0
  84. package/dist/templates/test-loader.d.ts +5 -0
  85. package/dist/templates/test-loader.js +146 -0
  86. package/dist/templates/test-loader.js.map +1 -0
  87. package/dist/templates/test-planner.d.ts +5 -0
  88. package/dist/templates/test-planner.js +271 -0
  89. package/dist/templates/test-planner.js.map +1 -0
  90. package/dist/templates/test-vault.d.ts +5 -0
  91. package/dist/templates/test-vault.js +380 -0
  92. package/dist/templates/test-vault.js.map +1 -0
  93. package/dist/templates/tsconfig.d.ts +1 -0
  94. package/dist/templates/tsconfig.js +25 -0
  95. package/dist/templates/tsconfig.js.map +1 -0
  96. package/dist/templates/vault.d.ts +5 -0
  97. package/dist/templates/vault.js +263 -0
  98. package/dist/templates/vault.js.map +1 -0
  99. package/dist/templates/vitest-config.d.ts +1 -0
  100. package/dist/templates/vitest-config.js +27 -0
  101. package/dist/templates/vitest-config.js.map +1 -0
  102. package/dist/types.d.ts +89 -0
  103. package/dist/types.js +21 -0
  104. package/dist/types.js.map +1 -0
  105. package/package.json +42 -4
  106. package/src/__tests__/knowledge-installer.test.ts +805 -0
  107. package/src/__tests__/scaffolder.test.ts +323 -0
  108. package/src/facades/forge.facade.ts +150 -0
  109. package/src/index.ts +101 -0
  110. package/src/knowledge-installer.ts +532 -0
  111. package/src/scaffolder.ts +386 -0
  112. package/src/templates/activate.ts +145 -0
  113. package/src/templates/claude-md-template.ts +137 -0
  114. package/src/templates/core-facade.ts +457 -0
  115. package/src/templates/domain-facade.ts +121 -0
  116. package/src/templates/entry-point.ts +120 -0
  117. package/src/templates/inject-claude-md.ts +94 -0
  118. package/src/templates/llm-client.ts +301 -0
  119. package/src/templates/package-json.ts +39 -0
  120. package/src/templates/persona.ts +45 -0
  121. package/src/templates/readme.ts +319 -0
  122. package/src/templates/setup-script.ts +113 -0
  123. package/src/templates/test-facades.ts +656 -0
  124. package/src/templates/tsconfig.ts +25 -0
  125. package/src/templates/vitest-config.ts +26 -0
  126. package/src/types.ts +68 -0
  127. package/tsconfig.json +21 -0
  128. package/vitest.config.ts +15 -0
@@ -0,0 +1,316 @@
1
+ /**
2
+ * Generate a README.md for the scaffolded agent.
3
+ */
4
+ export function generateReadme(config) {
5
+ const domainRows = config.domains
6
+ .map((d) => `| ${d} | *Ready for knowledge capture* |`)
7
+ .join('\n');
8
+ const principleLines = config.principles.map((p) => `- ${p}`).join('\n');
9
+ return `# ${config.name} — ${config.role}
10
+
11
+ ${config.description}
12
+
13
+ ## Why ${config.name}
14
+
15
+ Every team accumulates knowledge — patterns that work, mistakes to avoid, architectural decisions and their reasoning. Without a system, this knowledge lives in people's heads, scattered docs, or buried in Slack threads. When someone leaves or context shifts, it's gone.
16
+
17
+ ${config.name} is your team's persistent knowledge layer. It:
18
+ - **Remembers** patterns, decisions, and lessons across sessions and projects
19
+ - **Retrieves** the right knowledge at the right time using intelligent search
20
+ - **Learns** from your feedback — accepted suggestions boost similar patterns, dismissed ones fade
21
+ - **Plans** multi-step tasks and tracks execution
22
+ - **Grows** with every interaction — the more you use it, the smarter it gets
23
+
24
+ The agent starts empty. That's intentional. Your expertise is the content; ${config.name} is the infrastructure that makes it searchable, persistent, and always available.
25
+
26
+ ## Quick Start
27
+
28
+ \`\`\`bash
29
+ # 1. Install and build
30
+ cd ${config.id}
31
+ npm install
32
+ npm run build
33
+
34
+ # 2. Add to Claude Code
35
+ ./scripts/setup.sh
36
+
37
+ # 3. Start a new Claude Code session, then say:
38
+ # "Hello, ${config.name}!"
39
+ \`\`\`
40
+
41
+ That's it. ${config.name} will activate, check your setup, and offer to configure itself.
42
+
43
+ ## Prerequisites
44
+
45
+ - **Node.js 18+** — \`node --version\` to check
46
+ - **Claude Code** — Anthropic's CLI for Claude (\`claude\` command)
47
+
48
+ ## What Happens When You Say "Hello, ${config.name}!"
49
+
50
+ 1. ${config.name} returns its persona, principles, and tool recommendations
51
+ 2. Claude adopts the ${config.name} persona for the rest of the session
52
+ 3. ${config.name} checks if your project has CLAUDE.md integration
53
+ 4. If not, it offers to inject its configuration (facades table, intent detection, knowledge protocol)
54
+
55
+ ## Manual Setup (if setup.sh doesn't work)
56
+
57
+ Add this to \`~/.claude/settings.json\` under \`mcpServers\`:
58
+
59
+ \`\`\`json
60
+ {
61
+ "mcpServers": {
62
+ "${config.id}": {
63
+ "command": "node",
64
+ "args": ["dist/index.js"],
65
+ "cwd": "/absolute/path/to/${config.id}"
66
+ }
67
+ }
68
+ }
69
+ \`\`\`
70
+
71
+ Then restart Claude Code.
72
+
73
+ ## Domains
74
+
75
+ | Domain | What it covers |
76
+ |--------|---------------|
77
+ ${domainRows}
78
+
79
+ ## Core Principles
80
+
81
+ ${principleLines}
82
+
83
+ ## Features
84
+
85
+ ### Knowledge Vault
86
+ SQLite-backed knowledge storage with FTS5 full-text search. Domains start empty and grow as you capture patterns.
87
+
88
+ ### Intelligence Layer (Brain)
89
+ A local, zero-dependency intelligence layer that sits between facades and vault:
90
+ - **TF-IDF + Hybrid Scoring** — Re-ranks search results across 5 dimensions: semantic similarity (40%), severity (15%), recency (15%), tag overlap (15%), domain match (15%)
91
+ - **Auto-Tagging** — Extracts tags from title + description using TF-IDF scoring on capture
92
+ - **Duplicate Detection** — Checks similarity before capture: blocks at >= 0.8, warns at >= 0.6
93
+ - **Adaptive Weights** — Tracks accepted/dismissed results; after 30+ feedback entries, scoring weights auto-tune
94
+ - **Graceful Degradation** — Works immediately on empty vaults; falls back to severity + recency when vocabulary is empty
95
+
96
+ ### Memory System
97
+ Captures session summaries, lessons learned, and user preferences. Memories persist across sessions and are searchable.
98
+
99
+ ### Session Capture
100
+ A PreCompact hook automatically captures session summaries before context compaction, preserving context across sessions.
101
+
102
+ ### Planning
103
+ Multi-step task planning with state machine: draft → approved → executing → completed. Plans are surfaced on activation.
104
+
105
+ ### Export
106
+ Export vault knowledge as JSON bundles for version control and sharing.
107
+
108
+ ### LLM Client (Optional)
109
+ Unified OpenAI/Anthropic client with multi-key rotation, circuit breakers, and model routing. Works without configuration — capabilities unlock when API keys are provided.
110
+
111
+ **Setup:**
112
+ Create \`~/.${config.id}/keys.json\`:
113
+ \`\`\`json
114
+ {
115
+ "openai": ["sk-..."],
116
+ "anthropic": ["sk-ant-..."]
117
+ }
118
+ \`\`\`
119
+
120
+ Or set environment variables: \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\`.
121
+
122
+ **Model routing** (optional) — \`~/.${config.id}/model-routing.json\`:
123
+ \`\`\`json
124
+ {
125
+ "routes": [],
126
+ "defaultOpenAIModel": "gpt-4o-mini",
127
+ "defaultAnthropicModel": "claude-sonnet-4-20250514"
128
+ }
129
+ \`\`\`
130
+
131
+ Use \`llm_status\` to check provider availability and key pool health.
132
+
133
+ ## How to Use
134
+
135
+ ### Activating and Deactivating
136
+
137
+ - **"Hello, ${config.name}!"** — Activate the persona. Claude adopts ${config.name}'s identity, principles, and tool access for the session.
138
+ - **"Goodbye, ${config.name}!"** — Deactivate. Claude returns to its default behavior.
139
+
140
+ ### Daily Workflow
141
+
142
+ Once active, ${config.name} works as your domain advisor. Here's how a typical session looks:
143
+
144
+ **Ask for guidance** — ${config.name} searches its vault and responds with relevant patterns:
145
+ \\\`\\\`\\\`
146
+ You: How should we handle rate limiting?
147
+ ${config.name}: [searches vault] Based on my patterns, here's what I recommend...
148
+ \\\`\\\`\\\`
149
+
150
+ **Capture knowledge** — When you discover something worth remembering, tell ${config.name} to capture it:
151
+ \\\`\\\`\\\`
152
+ You: We decided to use token bucket for rate limiting. Capture this as a pattern.
153
+ ${config.name}: [captures to vault with auto-tags: rate-limiting, token-bucket, api-design]
154
+ \\\`\\\`\\\`
155
+
156
+ **Plan multi-step work** — For larger tasks, ${config.name} creates trackable plans:
157
+ \\\`\\\`\\\`
158
+ You: Plan out the caching implementation.
159
+ ${config.name}: Created plan "Add Caching Layer" with 4 tasks:
160
+ 1. Define cache invalidation strategy
161
+ 2. Add Redis client configuration
162
+ 3. Implement cache middleware
163
+ 4. Add cache-related tests
164
+ Approve to start execution?
165
+ \\\`\\\`\\\`
166
+
167
+ **Give feedback** — When ${config.name} suggests something, your response teaches it:
168
+ \\\`\\\`\\\`
169
+ You: That pattern doesn't apply here — we're using GraphQL, not REST.
170
+ ${config.name}: [records feedback] Got it. I'll adjust future recommendations.
171
+ \\\`\\\`\\\`
172
+
173
+ **Search across sessions** — Knowledge persists. Next week, next month, different project:
174
+ \\\`\\\`\\\`
175
+ You: What did we decide about rate limiting last month?
176
+ ${config.name}: [searches vault + memory] You chose token bucket with...
177
+ \\\`\\\`\\\`
178
+
179
+ ### Key Operations
180
+
181
+ | What you want | What to say |
182
+ |---------------|-------------|
183
+ | Search knowledge | Ask any domain question |
184
+ | Capture a pattern | "Capture this as a pattern" / "Remember this" |
185
+ | Create a plan | "Plan out [task]" |
186
+ | Check vault health | "What's in your vault?" / "Vault stats" |
187
+ | Export knowledge | "Export your knowledge as JSON" |
188
+ | Check LLM status | "LLM status" (if API keys configured) |
189
+
190
+ ## Populating Your Agent
191
+
192
+ ${config.name} starts with an empty vault. Here's how to fill it with knowledge.
193
+
194
+ ### One at a Time (conversational capture)
195
+
196
+ The simplest way — tell ${config.name} what you've learned and ask it to capture:
197
+
198
+ \\\`\\\`\\\`
199
+ You: We decided to use token bucket for rate limiting with a 100 req/min limit.
200
+ Capture this as a pattern in api-design.
201
+
202
+ ${config.name}: [captures to vault]
203
+ Captured: api-rate-limiting (pattern, warning)
204
+ Auto-tags: rate-limiting, token-bucket, api-design
205
+ \\\`\\\`\\\`
206
+
207
+ ### Bulk Ingestion (document feed)
208
+
209
+ To populate the vault from existing documents (architecture docs, coding standards, RFCs, post-mortems), paste or reference the document and ask ${config.name} to extract patterns:
210
+
211
+ \\\`\\\`\\\`
212
+ You: Here's our API design guide: [paste content or file path]
213
+ Read through it and capture every pattern, anti-pattern, and rule
214
+ into the api-design domain.
215
+
216
+ ${config.name}: [reads document, extracts and captures each pattern]
217
+ Captured 12 entries:
218
+ - api-auth-jwt (pattern, critical) — Always use short-lived JWTs
219
+ - api-no-sql-in-controllers (anti-pattern, warning) — Keep SQL in data layer
220
+ - api-pagination-required (rule, warning) — All list endpoints must paginate
221
+ ...
222
+ \\\`\\\`\\\`
223
+
224
+ This works with any text: wiki pages, Slack threads, PR review comments, meeting notes. Claude acts as the intake pipeline — it reads, classifies, and calls \\\`capture\\\` for each extracted entry.
225
+
226
+ ### JSON Bundles (manual or scripted)
227
+
228
+ For programmatic loading, edit the JSON files directly:
229
+
230
+ \\\`\\\`\\\`json
231
+ // src/intelligence/data/api-design.json
232
+ {
233
+ "domain": "api-design",
234
+ "version": "1.0.0",
235
+ "entries": [
236
+ {
237
+ "id": "api-auth-jwt",
238
+ "type": "pattern",
239
+ "domain": "api-design",
240
+ "title": "Use short-lived JWTs for authentication",
241
+ "severity": "critical",
242
+ "description": "Issue JWTs with 15-minute expiry...",
243
+ "tags": ["auth", "jwt", "security"]
244
+ }
245
+ ]
246
+ }
247
+ \\\`\\\`\\\`
248
+
249
+ Then rebuild (\\\`npm run build\\\`) to pick up the changes. Entries from JSON bundles load on startup.
250
+
251
+ ### Tips for Building a Useful Vault
252
+
253
+ - **Start with your team's top 10 decisions** — the ones people keep asking about
254
+ - **Capture anti-patterns from real incidents** — what went wrong and why
255
+ - **Use severity wisely** — \\\`critical\\\` for must-follow rules, \\\`warning\\\` for strong recommendations, \\\`suggestion\\\` for nice-to-haves
256
+ - **Let auto-tagging work** — the Brain extracts tags from titles and descriptions automatically. You can add manual tags too, but you don't have to
257
+ - **Export regularly** — \\\`export\\\` dumps your vault to JSON for version control and sharing with teammates
258
+
259
+ ## Growing Your Agent
260
+
261
+ ${config.name} gets smarter through use — no code changes needed:
262
+
263
+ 1. **Capture patterns** — Every time you capture a decision, pattern, or lesson, the vault grows. The Brain auto-tags entries and detects duplicates.
264
+ 2. **Give feedback** — Accept or dismiss suggestions. After 30+ feedback entries, the Brain auto-tunes its scoring weights to match your preferences.
265
+ 3. **Use memory** — Session summaries are captured automatically before context compaction. Lessons and preferences persist across sessions.
266
+ 4. **Register projects** — Register ${config.name} with multiple projects. It builds context about each one and surfaces relevant knowledge on activation.
267
+ 5. **Export and share** — Export vault knowledge as JSON. Share bundles with teammates or back them up in version control.
268
+
269
+ The more you interact, the more valuable ${config.name} becomes. A fresh agent with 50+ captured patterns and a month of feedback is significantly more useful than one on day one.
270
+
271
+ ## Roadmap
272
+
273
+ ${config.name} ships with a solid foundation. Below are optional improvements you can add yourself, ordered by impact.
274
+
275
+ ### 1. Curator Pipeline
276
+ **What:** Background vault maintenance — tag normalization, duplicate merging, quality scoring, stale entry detection.
277
+ **Why:** Without grooming, vault quality degrades over time. Tags drift, duplicates accumulate, outdated entries linger.
278
+ **How:** Add a \`src/curator/\` module with: a job queue (SQLite-backed), a groom pipeline that scans entries on a schedule, a tag normalizer that consolidates synonyms, and a duplicate detector that merges near-identical entries. Wire it as a \`curator\` facade with ops like \`groom\`, \`scan\`, \`normalize_tags\`, \`merge_duplicates\`. Can optionally use the LLM client for GPT-powered classification.
279
+
280
+ ### 2. Document Intake
281
+ **What:** Ingest documents (PDF, markdown, text) into the vault automatically — extract content, classify it, deduplicate, and write entries.
282
+ **Why:** Manual knowledge entry is the biggest friction point. An intake pipeline lets you point at reference material and populate the vault.
283
+ **How:** Add a \`src/intake/\` module with: a content extractor (start with markdown/text, add PDF via \`pdf-parse\`), a chunker that splits long documents into entry-sized pieces, a classifier that assigns domain/type/severity (can use LLM or heuristics), and a dedup gate that checks against existing entries before writing. Expose as an \`intake\` facade op.
284
+
285
+ ### 3. Learning Loop
286
+ **What:** Turn accumulated feedback into measurable improvement — track which suggestions get accepted vs dismissed, extract user preferences, adjust scoring.
287
+ **Why:** The Brain already records feedback and tunes weights after 30+ entries. A full learning loop goes further: it builds a preference profile, identifies which patterns resonate, and deprioritizes ones that get consistently dismissed.
288
+ **How:** Add a \`src/learning/\` module with: a feedback analyzer that aggregates accept/dismiss rates per tag and per domain, a preference extractor that builds a user profile from feedback patterns, and a scoring adjuster that feeds insights back into the Brain's weight tuner. Run periodically or trigger after N new feedback entries.
289
+
290
+ ### 4. Embeddings & Vector Search
291
+ **What:** Supplement TF-IDF with embedding-based semantic search using OpenAI's embedding API.
292
+ **Why:** TF-IDF is keyword-based — it misses semantic similarity (e.g., "auth" vs "authentication"). Embeddings capture meaning, not just words.
293
+ **How:** Add an embedding service that calls OpenAI's \`text-embedding-3-small\` via the LLM client, stores vectors in a \`vault_embeddings\` table, and adds a vector similarity search path to the Brain. Use cosine similarity to rank. Falls back to TF-IDF when no API key is configured.
294
+
295
+ ### 5. Cross-Project Memory
296
+ **What:** Share knowledge and memories across projects — a global pattern pool, project linking, and unified search.
297
+ **Why:** Lessons learned in one project often apply to others. Without cross-project memory, each project starts from zero.
298
+ **How:** Extend the memory system with: a global pool table that stores entries visible to all projects, project link records that connect related projects, and a cross-project search op that queries across all registered projects. Add \`scope\` (project/global) to memory entries.
299
+
300
+ ### 6. Context Engine
301
+ **What:** Semantic analysis of user messages — intent classification, entity extraction, and context-aware knowledge retrieval.
302
+ **Why:** Currently the agent responds to explicit ops. A context engine lets it understand *what the user means* and proactively retrieve relevant knowledge.
303
+ **How:** Add a \`src/context/\` module with: an intent classifier (rule-based patterns like "how do I" → PLAN, "this is broken" → FIX), an entity extractor that pulls domain-specific terms from messages, and a knowledge retriever that combines intent + entities to query the vault. Can start rule-based and upgrade to LLM-powered later.
304
+
305
+ ### 7. Proactive Agency
306
+ **What:** The agent doesn't just answer — it anticipates, warns, and suggests without being asked.
307
+ **Why:** Moves the agent from reactive (Q&A) to proactive (advisor). Catches issues before they become problems.
308
+ **How:** Add a \`src/agency/\` module with: a suggestion generator that surfaces relevant patterns based on context, a warning detector that flags potential issues (e.g., anti-patterns in captured code), and a notification system that delivers insights at the right moment. Wire into Claude Code hooks for file-change triggers.
309
+
310
+ ### 8. Plugin System
311
+ **What:** Runtime-extensible architecture — load, validate, and hot-reload plugins that add new facades, ops, or intelligence.
312
+ **Why:** Lets users extend the agent without modifying core code. Third parties can publish domain-specific plugins.
313
+ **How:** Add a \`src/plugins/\` module with: a plugin loader that scans a directory for plugin packages, a validator that checks plugin manifests against a schema, a registry that tracks active plugins and their facades, and a hot-reload watcher. Each plugin exports a \`register()\` function that receives the vault and brain instances.
314
+ `;
315
+ }
316
+ //# sourceMappingURL=readme.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"readme.js","sourceRoot":"","sources":["../../src/templates/readme.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,oCAAoC,CAAC;SACtD,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEzE,OAAO,KAAK,MAAM,CAAC,IAAI,MAAM,MAAM,CAAC,IAAI;;EAExC,MAAM,CAAC,WAAW;;SAEX,MAAM,CAAC,IAAI;;;;EAIlB,MAAM,CAAC,IAAI;;;;;;;6EAOgE,MAAM,CAAC,IAAI;;;;;;KAMnF,MAAM,CAAC,EAAE;;;;;;;;eAQC,MAAM,CAAC,IAAI;;;aAGb,MAAM,CAAC,IAAI;;;;;;;uCAOe,MAAM,CAAC,IAAI;;KAE7C,MAAM,CAAC,IAAI;uBACO,MAAM,CAAC,IAAI;KAC7B,MAAM,CAAC,IAAI;;;;;;;;;;OAUT,MAAM,CAAC,EAAE;;;kCAGkB,MAAM,CAAC,EAAE;;;;;;;;;;;;EAYzC,UAAU;;;;EAIV,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BF,MAAM,CAAC,EAAE;;;;;;;;;;sCAUe,MAAM,CAAC,EAAE;;;;;;;;;;;;;;;cAejC,MAAM,CAAC,IAAI,8CAA8C,MAAM,CAAC,IAAI;gBAClE,MAAM,CAAC,IAAI;;;;eAIZ,MAAM,CAAC,IAAI;;yBAED,MAAM,CAAC,IAAI;;;EAGlC,MAAM,CAAC,IAAI;;;8EAGiE,MAAM,CAAC,IAAI;;;EAGvF,MAAM,CAAC,IAAI;;;+CAGkC,MAAM,CAAC,IAAI;;;EAGxD,MAAM,CAAC,IAAI;;;;;;;;2BAQc,MAAM,CAAC,IAAI;;;EAGpC,MAAM,CAAC,IAAI;;;;;;EAMX,MAAM,CAAC,IAAI;;;;;;;;;;;;;;;;EAgBX,MAAM,CAAC,IAAI;;;;0BAIa,MAAM,CAAC,IAAI;;;;;;EAMnC,MAAM,CAAC,IAAI;;;;;;;mJAOsI,MAAM,CAAC,IAAI;;;;;;;EAO5J,MAAM,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6CX,MAAM,CAAC,IAAI;;;;;sCAKyB,MAAM,CAAC,IAAI;;;2CAGN,MAAM,CAAC,IAAI;;;;EAIpD,MAAM,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCZ,CAAC;AACF,CAAC"}
@@ -0,0 +1,6 @@
1
+ import type { AgentConfig } from '../types.js';
2
+ /**
3
+ * Generate a scripts/setup.sh for the scaffolded agent.
4
+ * Handles: Node.js check, build, Claude Code MCP server registration.
5
+ */
6
+ export declare function generateSetupScript(config: AgentConfig): string;
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Generate a scripts/setup.sh for the scaffolded agent.
3
+ * Handles: Node.js check, build, Claude Code MCP server registration.
4
+ */
5
+ export function generateSetupScript(config) {
6
+ return `#!/usr/bin/env bash
7
+ set -euo pipefail
8
+
9
+ AGENT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
10
+ AGENT_NAME="${config.id}"
11
+
12
+ echo "=== ${config.name} Setup ==="
13
+ echo ""
14
+
15
+ # Check Node.js
16
+ if ! command -v node &>/dev/null; then
17
+ echo "Error: Node.js is not installed. Install Node.js 18+ first."
18
+ exit 1
19
+ fi
20
+
21
+ NODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1)
22
+ if [ "$NODE_VERSION" -lt 18 ]; then
23
+ echo "Error: Node.js 18+ required (found v$(node -v))."
24
+ exit 1
25
+ fi
26
+ echo "[ok] Node.js $(node -v)"
27
+
28
+ # Check if built
29
+ if [ ! -f "$AGENT_DIR/dist/index.js" ]; then
30
+ echo ""
31
+ echo "Building ${config.name}..."
32
+ cd "$AGENT_DIR"
33
+ npm install
34
+ npm run build
35
+ echo "[ok] Built successfully"
36
+ else
37
+ echo "[ok] Already built"
38
+ fi
39
+
40
+ # Check Claude Code
41
+ if ! command -v claude &>/dev/null; then
42
+ echo ""
43
+ echo "Warning: 'claude' command not found."
44
+ echo "Install Claude Code first: https://docs.anthropic.com/en/docs/claude-code"
45
+ echo ""
46
+ echo "After installing, add ${config.name} manually to ~/.claude/settings.json"
47
+ echo "(see README.md for the JSON config)"
48
+ exit 1
49
+ fi
50
+ echo "[ok] Claude Code found"
51
+
52
+ # Register MCP server with Claude Code
53
+ echo ""
54
+ echo "Registering ${config.name} with Claude Code..."
55
+
56
+ claude mcp add --scope user "$AGENT_NAME" -- node "$AGENT_DIR/dist/index.js"
57
+ echo "[ok] Registered ${config.name} as MCP server"
58
+
59
+ # Configure PreCompact hook for session capture
60
+ SETTINGS_FILE="$HOME/.claude/settings.json"
61
+ echo ""
62
+ echo "Configuring session capture hook..."
63
+
64
+ if [ ! -d "$HOME/.claude" ]; then
65
+ mkdir -p "$HOME/.claude"
66
+ fi
67
+
68
+ if [ ! -f "$SETTINGS_FILE" ]; then
69
+ cat > "$SETTINGS_FILE" << SETTINGS
70
+ {
71
+ "hooks": {
72
+ "PreCompact": [
73
+ {
74
+ "type": "prompt",
75
+ "prompt": "Before context is compacted, capture a session summary by calling ${config.id.replace(/-/g, '_')}_core op:session_capture with a brief summary of what was accomplished, the topics covered, files modified, and tools used."
76
+ }
77
+ ]
78
+ }
79
+ }
80
+ SETTINGS
81
+ echo "[ok] Created $SETTINGS_FILE with PreCompact hook"
82
+ else
83
+ if grep -q "PreCompact" "$SETTINGS_FILE" 2>/dev/null; then
84
+ echo "[ok] PreCompact hook already configured — skipping"
85
+ else
86
+ # Use node to safely merge hook into existing settings
87
+ node -e "
88
+ const fs = require('fs');
89
+ const settings = JSON.parse(fs.readFileSync('$SETTINGS_FILE', 'utf-8'));
90
+ if (!settings.hooks) settings.hooks = {};
91
+ if (!settings.hooks.PreCompact) settings.hooks.PreCompact = [];
92
+ settings.hooks.PreCompact.push({
93
+ type: 'prompt',
94
+ prompt: 'Before context is compacted, capture a session summary by calling ${config.id.replace(/-/g, '_')}_core op:session_capture with a brief summary of what was accomplished, the topics covered, files modified, and tools used.'
95
+ });
96
+ fs.writeFileSync('$SETTINGS_FILE', JSON.stringify(settings, null, 2) + '\\n');
97
+ "
98
+ echo "[ok] Added PreCompact hook to $SETTINGS_FILE"
99
+ fi
100
+ fi
101
+
102
+ echo ""
103
+ echo "=== Setup Complete ==="
104
+ echo ""
105
+ echo "Next:"
106
+ echo " 1. Start a new Claude Code session (or restart if one is open)"
107
+ echo " 2. Say: \\"Hello, ${config.name}!\\""
108
+ echo ""
109
+ echo "${config.name} will activate and guide you from there."
110
+ `;
111
+ }
112
+ //# sourceMappingURL=setup-script.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"setup-script.js","sourceRoot":"","sources":["../../src/templates/setup-script.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,OAAO;;;;cAIK,MAAM,CAAC,EAAE;;YAEX,MAAM,CAAC,IAAI;;;;;;;;;;;;;;;;;;;mBAmBJ,MAAM,CAAC,IAAI;;;;;;;;;;;;;;;gCAeE,MAAM,CAAC,IAAI;;;;;;;;oBAQvB,MAAM,CAAC,IAAI;;;wBAGP,MAAM,CAAC,IAAI;;;;;;;;;;;;;;;;;;uFAkBoD,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;;;;;;;;;;;;;;;;;;;qFAmB9B,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;;;;;;;;;;;;;4BAarF,MAAM,CAAC,IAAI;;QAE/B,MAAM,CAAC,IAAI;CAClB,CAAC;AACF,CAAC"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Generates brain test file for a new agent.
3
+ * Tests cover: TF-IDF scoring, intelligent search, auto-tagging,
4
+ * duplicate detection, feedback, adaptive weights, vocabulary.
5
+ */
6
+ export declare function generateBrainTest(): string;