@soleri/forge 8.0.0 → 9.0.0

package/src/scaffold-filetree.ts

@@ -7,8 +7,9 @@
  * Replaces the old scaffold() that generated TypeScript projects.
  */
 
-import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { stringify as yamlStringify } from 'yaml';
 import type { AgentYaml, AgentYamlInput } from './agent-schema.js';
 import { AgentYamlSchema } from './agent-schema.js';
@@ -93,8 +94,8 @@ When building a new feature, adding functionality, or creating components.
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_vault op:link_entries
-  - soleri_planner op:create_plan
-  - soleri_planner op:approve_plan
+  - soleri_plan op:create_plan
+  - soleri_plan op:approve_plan
   - soleri_brain op:recommend
 `,
   },
@@ -146,7 +147,7 @@ When fixing bugs, resolving errors, or addressing regressions.
     tools: `tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
-  - soleri_planner op:create_plan
+  - soleri_plan op:create_plan
   - soleri_brain op:recommend
 `,
   },
@@ -307,12 +308,16 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     writeFile(agentDir, `workflows/${wf.name}/tools.yaml`, wf.tools, filesCreated);
   }
 
-  // ─── 8. Write empty knowledge bundle ────────────────────────
+  // ─── 8. Write knowledge bundles (seed from starter packs if available) ──
+  const starterPacksDir = resolveStarterPacksDir();
+  let totalSeeded = 0;
+
   for (const domain of config.domains) {
+    const starterEntries = loadStarterEntries(starterPacksDir, domain);
     const bundle = {
       domain,
       version: '1.0.0',
-      entries: [],
+      entries: starterEntries,
     };
     writeFile(
       agentDir,
@@ -320,6 +325,7 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
       JSON.stringify(bundle, null, 2) + '\n',
       filesCreated,
     );
+    totalSeeded += starterEntries.length;
   }
 
   // ─── 9. Generate CLAUDE.md ──────────────────────────────────
@@ -332,6 +338,7 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     '',
     `  Files: ${filesCreated.length}`,
     `  Domains: ${config.domains.join(', ')}`,
+    `  Knowledge: ${totalSeeded} starter entries seeded`,
     `  Workflows: ${BUILTIN_WORKFLOWS.map((w) => w.name).join(', ')}`,
     '',
     'Next steps:',
@@ -393,11 +400,15 @@ function buildAgentYaml(config: AgentYaml): Record<string, unknown> {
     yaml.greeting = config.greeting;
   }
 
+  // Persona config — include if present
+  if (config.persona && Object.keys(config.persona).length > 0) {
+    yaml.persona = config.persona;
+  }
+
   // Engine config — only include non-defaults
   const engine: Record<string, unknown> = {};
   if (config.engine?.vault) engine.vault = config.engine.vault;
   if (config.engine?.learning === false) engine.learning = false;
-  if (config.engine?.cognee === true) engine.cognee = true;
   if (Object.keys(engine).length > 0) yaml.engine = engine;
 
   // Vaults
@@ -419,3 +430,67 @@ function buildAgentYaml(config: AgentYaml): Record<string, unknown> {
 
   return yaml;
 }
+
+// ─── Starter Pack Helpers ────────────────────────────────────────────
+
+/** Domain aliases — map agent domains to starter pack directories. */
+const DOMAIN_TO_STARTER: Record<string, string> = {
+  // design starter
+  frontend: 'design',
+  design: 'design',
+  'ui-design': 'design',
+  accessibility: 'design',
+  styling: 'design',
+  react: 'design',
+  'component-patterns': 'design',
+  'responsive-design': 'design',
+  // security starter
+  security: 'security',
+  auth: 'security',
+  authentication: 'security',
+  // architecture starter
+  architecture: 'architecture',
+  'api-design': 'architecture',
+  database: 'architecture',
+  backend: 'architecture',
+  infrastructure: 'architecture',
+};
+
+function resolveStarterPacksDir(): string | null {
+  // Try repo-relative path (monorepo development)
+  const forgeDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(forgeDir, '..', '..', '..', 'knowledge-packs', 'starter'),
+    join(forgeDir, '..', '..', 'knowledge-packs', 'starter'),
+  ];
+  for (const dir of candidates) {
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}
+
+function loadStarterEntries(starterDir: string | null, domain: string): unknown[] {
+  if (!starterDir) return [];
+
+  const packName = DOMAIN_TO_STARTER[domain];
+  if (!packName) return [];
+
+  const vaultDir = join(starterDir, packName, 'vault');
+  if (!existsSync(vaultDir)) return [];
+
+  const entries: unknown[] = [];
+  try {
+    const files = readdirSync(vaultDir).filter((f: string) => f.endsWith('.json'));
+    for (const file of files) {
+      const data = JSON.parse(readFileSync(join(vaultDir, file), 'utf-8'));
+      if (Array.isArray(data)) {
+        entries.push(...data);
+      } else if (data.entries && Array.isArray(data.entries)) {
+        entries.push(...data.entries);
+      }
+    }
+  } catch {
+    // Starter pack unavailable — return empty
+  }
+  return entries;
+}

package/src/scaffolder.ts

@@ -257,10 +257,6 @@ export function previewScaffold(config: AgentConfig): ScaffoldPreview {
       name: `${config.id}_control`,
       ops: ['get_identity', 'route_intent', 'governance_policy', '...control+governance ops'],
     },
-    {
-      name: `${config.id}_cognee`,
-      ops: ['cognee_status', 'cognee_search', '...cognee ops', '...cognee-sync'],
-    },
     // Agent-specific facade
     {
       name: `${config.id}_core`,

package/src/skills/agent-guide.md

@@ -38,7 +38,7 @@ This returns the agent's persona: name, role, description, tone, principles, and
 YOUR_AGENT_core op:admin_health
 ```
 
-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.
+Shows what subsystems are active: vault (how many entries), brain (vocabulary size), LLM availability. This tells the user what the agent currently has to work with.
 
 ### Step 3: Available Tools
 

package/src/templates/agents-md.ts

@@ -80,7 +80,6 @@ ${domainRows}
 | ${bt}${tp}_memory${bt} | ${bt}memory_search${bt}, ${bt}memory_capture${bt}, ${bt}session_capture${bt} |
 | ${bt}${tp}_control${bt} | ${bt}route_intent${bt}, ${bt}morph${bt}, ${bt}get_behavior_rules${bt}, ${bt}governance_dashboard${bt}, ${bt}governance_policy${bt} |
 | ${bt}${tp}_loop${bt} | ${bt}loop_start${bt}, ${bt}loop_iterate${bt}, ${bt}loop_status${bt}, ${bt}loop_cancel${bt} |
-| ${bt}${tp}_cognee${bt} | ${bt}cognee_search${bt}, ${bt}cognee_graph_stats${bt}, ${bt}cognee_export_status${bt} |
 | ${bt}${tp}_context${bt} | ${bt}context_extract_entities${bt}, ${bt}context_retrieve_knowledge${bt}, ${bt}context_analyze${bt} |
 | ${bt}${tp}_agency${bt} | ${bt}agency_enable${bt}, ${bt}agency_status${bt}, ${bt}agency_surface_patterns${bt}, ${bt}agency_warnings${bt}, ${bt}agency_clarify${bt} |
 | ${bt}${tp}_admin${bt} | ${bt}admin_health${bt}, ${bt}admin_tool_list${bt}, ${bt}admin_diagnostic${bt} |

package/src/templates/claude-md-template.ts

@@ -115,8 +115,7 @@ export function generateClaudeMdTemplate(config: AgentConfig): string {
     `| ${bt}${toolPrefix}_memory${bt} | ${bt}memory_search${bt}, ${bt}memory_capture${bt}, ${bt}session_capture${bt} |`,
     `| ${bt}${toolPrefix}_control${bt} | ${bt}route_intent${bt}, ${bt}morph${bt}, ${bt}get_behavior_rules${bt}, ${bt}governance_dashboard${bt}, ${bt}governance_policy${bt} |`,
     `| ${bt}${toolPrefix}_loop${bt} | ${bt}loop_start${bt}, ${bt}loop_iterate${bt}, ${bt}loop_status${bt}, ${bt}loop_cancel${bt} |`,
-    // Intelligence — cognee, context, agency
-    `| ${bt}${toolPrefix}_cognee${bt} | ${bt}cognee_search${bt}, ${bt}cognee_graph_stats${bt}, ${bt}cognee_export_status${bt} |`,
+    // Intelligence — context, agency
     `| ${bt}${toolPrefix}_context${bt} | ${bt}context_extract_entities${bt}, ${bt}context_retrieve_knowledge${bt}, ${bt}context_analyze${bt} |`,
     `| ${bt}${toolPrefix}_agency${bt} | ${bt}agency_enable${bt}, ${bt}agency_status${bt}, ${bt}agency_surface_patterns${bt}, ${bt}agency_warnings${bt}, ${bt}agency_clarify${bt} |`,
     // Admin

package/src/templates/entry-point.ts

@@ -56,7 +56,7 @@ async function main(): Promise<void> {
   // ─── Runtime — vault, brain, planner, curator, LLM, key pools ───
   const runtime = createAgentRuntime({
     agentId: '${config.id}',
-    dataDir: join(__dirname, 'intelligence', 'data'),${config.sharedVaultPath ? `\n    sharedVaultPath: '${config.sharedVaultPath}',` : ''}${config.cognee ? `\n    cognee: true,` : ''}
+    dataDir: join(__dirname, 'intelligence', 'data'),${config.sharedVaultPath ? `\n    sharedVaultPath: '${config.sharedVaultPath}',` : ''}
   });
 
   const tag = PERSONA.name.toLowerCase();
@@ -263,12 +263,12 @@ ${
   const domainPacks = await loadDomainPacksFromConfig(${JSON.stringify(config.domainPacks)});
   console.error(\`[\${tag}] Loaded \${domainPacks.length} domain packs\`);
   for (const pack of domainPacks) {
-    if (pack.onActivate) await pack.onActivate(runtime);
+    const packRuntime = createPackRuntime(runtime);
+    if (pack.onActivate) await pack.onActivate(packRuntime, runtime);
   }
 
   // ─── Capability Registry ─────────────────────────────────────
   const capabilityRegistry = new CapabilityRegistry();
-  const packRuntime = createPackRuntime(runtime);
 
   // Register domain pack capabilities
   for (const pack of domainPacks) {

package/src/templates/shared-rules.ts

@@ -69,6 +69,26 @@ const ENGINE_RULES_LINES: string[] = [
   '- After every response, rate your confidence from 1 to 10. Anything below 7, flag it.',
   '',
 
+  // ─── MCP Tool Schema Validation ─────────────────────────
+  '## MCP Tool Schema Validation',
+  '<!-- soleri:tool-schema-validation -->',
+  '',
+  '**MANDATORY**: Before calling any MCP tool for the first time in a session, fetch its full JSON schema first.',
+  '',
+  '- Use `ToolSearch` (or platform equivalent) to retrieve the tool definition before invoking it.',
+  '- Read required fields, types, enum constraints, and nesting structure.',
+  '- Do NOT guess parameter shapes from memory or training data — schemas evolve between versions.',
+  '- Once fetched, the schema is valid for the remainder of the session.',
+  '',
+  '**Why:** MCP tools have strict parameter validation. Guessing formats causes repeated failures (wrong nesting, invalid enums, missing required fields), wasting tokens and eroding user trust. The schema is always available — use it.',
+  '',
+  '| Wrong | Right |',
+  '|-------|-------|',
+  '| Call tool, fail, retry with different shape | ToolSearch first, call once correctly |',
+  '| Assume `severity: "suggestion"` is valid | Read schema: `"critical" \\| "warning" \\| "info"` |',
+  '| Pass flat params when tool expects `entries[]` | Read schema: `entries` is required array |',
+  '',
+
   // ─── Memory Quality Gate ───────────────────────────────
   '## Memory Quality Gate',
   '<!-- soleri:memory-quality -->',

package/src/templates/test-facades.ts

@@ -86,7 +86,6 @@ ${domainPackDescribes ? `\n${domainPackDescribes}\n` : ''}
       expect(names).toContain('${config.id}_loop');
       expect(names).toContain('${config.id}_orchestrate');
       expect(names).toContain('${config.id}_control');
-      expect(names).toContain('${config.id}_cognee');
     });
 
     it('total ops across all facades should meet minimum threshold', () => {
@@ -273,16 +272,6 @@ ${domainPackDescribes ? `\n${domainPackDescribes}\n` : ''}
     });
   });
 
-  describe('${config.id}_cognee', () => {
-    it('should contain cognee ops', () => {
-      const facade = createSemanticFacades(runtime, '${config.id}').find(f => f.name === '${config.id}_cognee')!;
-      const opNames = facade.ops.map(o => o.name);
-      expect(opNames).toContain('cognee_status');
-      expect(opNames).toContain('cognee_search');
-      expect(opNames).toContain('cognee_sync_status');
-    });
-  });
-
   describe('${config.id}_core (agent-specific)', () => {
     function buildAgentFacade(): FacadeConfig {
       const agentOps: OpDefinition[] = [

package/src/types.ts

@@ -31,10 +31,10 @@ export const AgentConfigSchema = z.object({
   role: z.string().min(1).max(100),
   /** Longer description of what this agent does */
   description: z.string().min(10).max(500),
-  /** Knowledge domains this agent covers */
-  domains: z.array(z.string().min(1)).min(1).max(20),
-  /** Core principles the agent follows (3-7 recommended) */
-  principles: z.array(z.string()).min(1).max(10),
+  /** Knowledge domains this agent covers (discovered from usage if empty) */
+  domains: z.array(z.string().min(1)).max(20).optional().default([]),
+  /** Core principles the agent follows (discovered from usage if empty) */
+  principles: z.array(z.string()).max(10).optional().default([]),
   /** Communication tone: precise, mentor, or pragmatic */
   tone: z.enum(TONES).optional().default('pragmatic'),
   /** Greeting message when agent introduces itself (auto-generated if omitted) */
@@ -51,8 +51,6 @@ export const AgentConfigSchema = z.object({
   setupTarget: z.enum(SETUP_TARGETS).optional().default('claude'),
   /** Enable Telegram transport scaffolding. Default: false. */
   telegram: z.boolean().optional().default(false),
-  /** Enable Cognee vector search integration. Default: false. */
-  cognee: z.boolean().optional().default(false),
   /** Domain packs — npm packages with custom ops, knowledge, rules, and skills. */
   domainPacks: z
     .array(
@@ -78,6 +76,8 @@ export const AgentConfigSchema = z.object({
     .optional(),
   /** @deprecated Use vaults[] instead. Shorthand for a single shared vault at priority 0.6. */
   sharedVaultPath: z.string().optional(),
+  /** Composable persona configuration. If omitted, Italian Craftsperson default is used. */
+  persona: z.record(z.unknown()).optional(),
 });
 
 export type AgentConfig = z.infer<typeof AgentConfigSchema>;