@soleri/forge 9.7.2 → 9.8.0

package/src/knowledge-installer.ts

@@ -154,16 +154,25 @@ interface InstallKnowledgeParams {
   agentPath: string;
   bundlePath: string;
   generateFacades?: boolean;
+  /** Agent format: 'filetree' skips package.json check and src/ patching */
+  format?: 'filetree' | 'typescript';
 }
 
 export async function installKnowledge(
   params: InstallKnowledgeParams,
 ): Promise<InstallKnowledgeResult> {
-  const { agentPath, bundlePath, generateFacades = true } = params;
+  const { agentPath, bundlePath, generateFacades = true, format } = params;
   const warnings: string[] = [];
   const facadesGenerated: string[] = [];
   const sourceFilesPatched: string[] = [];
 
+  // ── File-tree agent path ─────────────────────────────────────────
+  if (format === 'filetree') {
+    return installKnowledgeFiletree(agentPath, bundlePath);
+  }
+
+  // ── TypeScript agent path (existing behavior) ────────────────────
+
   // ── Step 1: Validate agent path ──────────────────────────────────
 
   const pkgPath = join(agentPath, 'package.json');
@@ -363,6 +372,120 @@ export async function installKnowledge(
   };
 }
 
+// ---------- File-tree agent installer ----------
+
+/**
+ * Install knowledge bundles into a file-tree agent.
+ * Writes to {agentPath}/knowledge/ — no package.json, no src/ patching, no build step.
+ * The engine picks up knowledge bundles from this directory at runtime.
+ */
+async function installKnowledgeFiletree(
+  agentPath: string,
+  bundlePath: string,
+): Promise<InstallKnowledgeResult> {
+  const warnings: string[] = [];
+
+  // Derive agentId from agent.yaml
+  let agentId = '';
+  const yamlPath = join(agentPath, 'agent.yaml');
+  if (existsSync(yamlPath)) {
+    try {
+      const raw = readFileSync(yamlPath, 'utf-8');
+      // Simple extraction — avoid importing yaml parser here
+      const idMatch = raw.match(/^id:\s*["']?([^\s"']+)/m);
+      if (idMatch) agentId = idMatch[1];
+    } catch {
+      // best-effort
+    }
+  }
+  if (!agentId) {
+    return fail(agentPath, '', 'No agent.yaml with valid id found — is this a file-tree agent?');
+  }
+
+  // Read and validate bundles
+  const bundleFiles = collectBundleFiles(bundlePath);
+  if (bundleFiles.length === 0) {
+    return fail(agentPath, agentId, `No .json bundle files found at ${bundlePath}`);
+  }
+
+  const bundles: Array<{ file: string; bundle: Bundle }> = [];
+  const issues: string[] = [];
+
+  for (const file of bundleFiles) {
+    try {
+      const raw = readFileSync(file, 'utf-8');
+      const parsed = JSON.parse(raw) as Bundle;
+      const fileIssues = validateBundle(parsed, file);
+      if (fileIssues.length > 0) {
+        issues.push(...fileIssues);
+      } else {
+        bundles.push({ file, bundle: parsed });
+      }
+    } catch (err) {
+      issues.push(
+        `${basename(file)}: invalid JSON — ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  if (bundles.length === 0) {
+    return fail(agentPath, agentId, `All bundles failed validation:\n${issues.join('\n')}`);
+  }
+
+  if (issues.length > 0) {
+    warnings.push(...issues);
+  }
+
+  // Determine new vs existing domains
+  const knowledgeDir = join(agentPath, 'knowledge');
+  mkdirSync(knowledgeDir, { recursive: true });
+
+  const existingFiles = readdirSync(knowledgeDir).filter((f) => f.endsWith('.json'));
+  const existingDomains = new Set(existingFiles.map((f) => f.replace(/\.json$/, '')));
+  const domainsAdded: string[] = [];
+  const domainsUpdated: string[] = [];
+
+  for (const { bundle } of bundles) {
+    if (existingDomains.has(bundle.domain)) {
+      domainsUpdated.push(bundle.domain);
+    } else {
+      domainsAdded.push(bundle.domain);
+    }
+  }
+
+  // Copy bundles to knowledge/
+  for (const { file, bundle } of bundles) {
+    const dest = join(knowledgeDir, `${bundle.domain}.json`);
+    copyFileSync(file, dest);
+  }
+
+  // No facade generation, no src/ patching, no build step for file-tree agents
+
+  const entriesTotal = bundles.reduce((sum, { bundle }) => sum + bundle.entries.length, 0);
+
+  const summaryParts = [
+    `Installed ${bundles.length} bundle(s) with ${entriesTotal} entries into ${agentId} (file-tree)`,
+  ];
+  if (domainsAdded.length > 0) summaryParts.push(`New domains: ${domainsAdded.join(', ')}`);
+  if (domainsUpdated.length > 0) summaryParts.push(`Updated domains: ${domainsUpdated.join(', ')}`);
+  if (warnings.length > 0) summaryParts.push(`${warnings.length} warning(s)`);
+
+  return {
+    success: true,
+    agentPath,
+    agentId,
+    bundlesInstalled: bundles.length,
+    entriesTotal,
+    domainsAdded,
+    domainsUpdated,
+    facadesGenerated: [],
+    sourceFilesPatched: [],
+    buildOutput: '',
+    warnings,
+    summary: summaryParts.join('. ') + '.',
+  };
+}
+
 // ---------- Helpers ----------
 
 function fail(agentPath: string, agentId: string, message: string): InstallKnowledgeResult {

package/src/lib.ts

@@ -21,7 +21,12 @@ export type {
 export { AgentConfigSchema, SETUP_TARGETS, MODEL_PRESETS } from './types.js';
 
 // ─── v7 File-Tree Agent ──────────────────────────────────────────────
-export { scaffoldFileTree } from './scaffold-filetree.js';
+export {
+  scaffoldFileTree,
+  SKILLS_REGISTRY,
+  ESSENTIAL_SKILLS,
+  resolveSkillsFilter,
+} from './scaffold-filetree.js';
 export type { FileTreeScaffoldResult } from './scaffold-filetree.js';
 export { AgentYamlSchema, TONES } from './agent-schema.js';
 export type { AgentYaml, AgentYamlInput } from './agent-schema.js';

package/src/scaffold-filetree.ts

@@ -18,6 +18,64 @@ import { composeClaudeMd } from './compose-claude-md.js';
 import { generateSkills } from './templates/skills.js';
 import type { AgentConfig } from './types.js';
 
+// ─── Skills Registry ─────────────────────────────────────────────────
+
+/**
+ * Skills classified as essential (always scaffolded by default) or optional
+ * (installed on demand via `soleri skills install`).
+ */
+export const SKILLS_REGISTRY: Record<string, 'essential' | 'optional'> = {
+  'agent-guide': 'essential',
+  'agent-persona': 'essential',
+  'vault-navigator': 'essential',
+  'vault-capture': 'essential',
+  'systematic-debugging': 'essential',
+  'writing-plans': 'essential',
+  'context-resume': 'essential',
+  // ─── Optional (installed on demand) ────────────
+  'agent-dev': 'optional',
+  'agent-issues': 'optional',
+  'brain-debrief': 'optional',
+  brainstorming: 'optional',
+  'code-patrol': 'optional',
+  'deep-review': 'optional',
+  'deliver-and-ship': 'optional',
+  'discovery-phase': 'optional',
+  'env-setup': 'optional',
+  'executing-plans': 'optional',
+  'finishing-a-development-branch': 'optional',
+  'fix-and-learn': 'optional',
+  'health-check': 'optional',
+  'knowledge-harvest': 'optional',
+  'mcp-doctor': 'optional',
+  'onboard-me': 'optional',
+  'parallel-execute': 'optional',
+  retrospective: 'optional',
+  'second-opinion': 'optional',
+  'subagent-driven-development': 'optional',
+  'test-driven-development': 'optional',
+  'using-git-worktrees': 'optional',
+  'vault-curate': 'optional',
+  'vault-smells': 'optional',
+  'verification-before-completion': 'optional',
+  'yolo-mode': 'optional',
+};
+
+/** Names of essential skills (always scaffolded when skillsFilter is 'essential'). */
+export const ESSENTIAL_SKILLS = Object.entries(SKILLS_REGISTRY)
+  .filter(([, tier]) => tier === 'essential')
+  .map(([name]) => name);
+
+/**
+ * Resolve the skill names to scaffold based on the skillsFilter config value.
+ * Returns null when all skills should be included (no filtering).
+ */
+export function resolveSkillsFilter(skillsFilter: 'all' | 'essential' | string[]): string[] | null {
+  if (skillsFilter === 'all') return null; // null = include all
+  if (skillsFilter === 'essential') return ESSENTIAL_SKILLS;
+  return skillsFilter; // explicit list
+}
+
 // ─── Types ────────────────────────────────────────────────────────────
 
 export interface FileTreeScaffoldResult {
@@ -235,6 +293,164 @@ Before crossing a context window boundary — \`/clear\`, context compaction, or
   },
 ];
 
+// ─── Example Instruction Files ───────────────────────────────────────
+
+const INSTRUCTIONS_CONVENTIONS = `# Conventions
+
+<!-- Customize this file with your project's naming conventions, coding standards, and rules. -->
+<!-- This file is composed into CLAUDE.md automatically — your agent will follow these rules. -->
+
+## Naming Conventions
+
+- Use \`kebab-case\` for file and directory names
+- Use \`camelCase\` for variables and functions
+- Use \`PascalCase\` for classes, types, and interfaces
+- Prefix private helpers with \`_\` (e.g., \`_validateInput\`)
+
+## File Organization
+
+- Source code goes in \`src/\`
+- Tests live next to the code they test (\`*.test.ts\`)
+- Shared utilities go in \`src/utils/\`
+- Types and interfaces go in \`src/types/\`
+
+## Code Standards
+
+- Every function must have a JSDoc comment explaining its purpose
+- Prefer \`const\` over \`let\`; never use \`var\`
+- Maximum file length: 300 lines — split if larger
+- No default exports — use named exports only
+
+## What to Avoid
+
+- Do not add new npm dependencies without approval
+- Do not use \`any\` type — use \`unknown\` and narrow
+- Do not commit commented-out code
+- Do not use hardcoded values — extract to constants or config
+`;
+
+const INSTRUCTIONS_GETTING_STARTED = `# Getting Started with Instructions
+
+This folder contains your agent's custom behavioral rules. Every \`.md\` file here
+is automatically composed into \`CLAUDE.md\` when you run \`soleri dev\`.
+
+## How It Works
+
+1. Create a new \`.md\` file in this folder (e.g., \`api-guidelines.md\`)
+2. Write your rules, conventions, or guidelines in Markdown
+3. Run \`soleri dev\` — it watches for changes and regenerates \`CLAUDE.md\`
+4. Your agent now follows these rules in every conversation
+
+## File Naming
+
+- Files are included in **alphabetical order** (prefix with numbers to control order)
+- \`_engine.md\` is auto-generated by Soleri — **do not edit it manually**
+- \`domain.md\` was generated from your agent's domain config
+
+## Tips
+
+- Keep each file focused on one topic (conventions, workflows, constraints)
+- Use clear headings — your agent reads these as instructions
+- Add "What to Avoid" sections — agents benefit from explicit anti-patterns
+- See the [Soleri docs](https://soleri.ai/docs) for more examples
+`;
+
+// ─── Workspace & Routing Seeds ───────────────────────────────────────
+
+/** Default workspaces seeded based on agent domains. */
+const DOMAIN_WORKSPACE_SEEDS: Record<string, { id: string; name: string; description: string }[]> =
+  {
+    // Design-related domains
+    design: [
+      {
+        id: 'design',
+        name: 'Design',
+        description: 'Design system patterns, tokens, and components',
+      },
+      { id: 'review', name: 'Review', description: 'Design review and accessibility audits' },
+    ],
+    'ui-design': [
+      { id: 'design', name: 'Design', description: 'UI design patterns, tokens, and components' },
+      { id: 'review', name: 'Review', description: 'Design review and accessibility audits' },
+    ],
+    accessibility: [
+      { id: 'design', name: 'Design', description: 'Accessible design patterns and tokens' },
+      { id: 'review', name: 'Review', description: 'Accessibility audits and compliance checks' },
+    ],
+    // Dev-related domains
+    architecture: [
+      {
+        id: 'planning',
+        name: 'Planning',
+        description: 'Architecture decisions and technical planning',
+      },
+      { id: 'src', name: 'Source', description: 'Implementation code and modules' },
+      { id: 'docs', name: 'Documentation', description: 'Technical documentation and ADRs' },
+    ],
+    backend: [
+      { id: 'planning', name: 'Planning', description: 'Backend architecture and API design' },
+      { id: 'src', name: 'Source', description: 'Implementation code and modules' },
+      { id: 'docs', name: 'Documentation', description: 'API documentation and guides' },
+    ],
+    frontend: [
+      {
+        id: 'planning',
+        name: 'Planning',
+        description: 'Frontend architecture and component design',
+      },
+      { id: 'src', name: 'Source', description: 'Implementation code and components' },
+      {
+        id: 'docs',
+        name: 'Documentation',
+        description: 'Component documentation and style guides',
+      },
+    ],
+    security: [
+      {
+        id: 'planning',
+        name: 'Planning',
+        description: 'Security architecture and threat modeling',
+      },
+      { id: 'src', name: 'Source', description: 'Security implementations and policies' },
+      { id: 'docs', name: 'Documentation', description: 'Security documentation and runbooks' },
+    ],
+  };
+
+/** Default routing entries seeded based on agent domains. */
+const DOMAIN_ROUTING_SEEDS: Record<
+  string,
+  { pattern: string; workspace: string; skills: string[] }[]
+> = {
+  design: [
+    { pattern: 'design component', workspace: 'design', skills: ['vault-navigator'] },
+    { pattern: 'review design', workspace: 'review', skills: ['deep-review'] },
+  ],
+  'ui-design': [
+    { pattern: 'design component', workspace: 'design', skills: ['vault-navigator'] },
+    { pattern: 'review design', workspace: 'review', skills: ['deep-review'] },
+  ],
+  architecture: [
+    { pattern: 'plan architecture', workspace: 'planning', skills: ['writing-plans'] },
+    { pattern: 'implement feature', workspace: 'src', skills: ['test-driven-development'] },
+    { pattern: 'write documentation', workspace: 'docs', skills: ['vault-capture'] },
+  ],
+  backend: [
+    { pattern: 'plan API', workspace: 'planning', skills: ['writing-plans'] },
+    { pattern: 'implement endpoint', workspace: 'src', skills: ['test-driven-development'] },
+    { pattern: 'write docs', workspace: 'docs', skills: ['vault-capture'] },
+  ],
+  frontend: [
+    { pattern: 'plan component', workspace: 'planning', skills: ['writing-plans'] },
+    { pattern: 'implement component', workspace: 'src', skills: ['test-driven-development'] },
+    { pattern: 'write docs', workspace: 'docs', skills: ['vault-capture'] },
+  ],
+  security: [
+    { pattern: 'threat model', workspace: 'planning', skills: ['writing-plans'] },
+    { pattern: 'implement policy', workspace: 'src', skills: ['test-driven-development'] },
+    { pattern: 'write runbook', workspace: 'docs', skills: ['vault-capture'] },
+  ],
+};
+
 // ─── Main Scaffolder ──────────────────────────────────────────────────
 
 /**
@@ -324,6 +540,13 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
       'AGENTS.md',
       'instructions/_engine.md',
       '',
+      '# OS',
+      '.DS_Store',
+      '',
+      '# Editor / IDE state',
+      '.obsidian/',
+      '.opencode/',
+      '',
     ].join('\n'),
     filesCreated,
   );
@@ -332,6 +555,24 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
   writeFile(agentDir, 'instructions/_engine.md', getEngineRulesContent(), filesCreated);
 
   // ─── 6. Write user instruction files ────────────────────────
+  // Generate user.md — user-editable file with priority placement in CLAUDE.md
+  const userMdContent = [
+    '# Your Custom Rules',
+    '',
+    'Add your agent-specific rules, constraints, and preferences here.',
+    'This file gets priority placement in CLAUDE.md — it appears before engine rules.',
+    '',
+    '## Examples of what to put here:',
+    '- Project-specific conventions',
+    '- Communication preferences',
+    '- Domain expertise to emphasize',
+    '- Things to always/never do',
+    '',
+    'Delete these instructions and replace with your own content.',
+    '',
+  ].join('\n');
+  writeFile(agentDir, 'instructions/user.md', userMdContent, filesCreated);
+
   // Generate domain-specific instruction file if agent has specialized domains
   if (config.domains.length > 0) {
     const domainLines = [
@@ -347,6 +588,15 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     writeFile(agentDir, 'instructions/domain.md', domainLines.join('\n'), filesCreated);
   }
 
+  // ─── 6b. Write example instruction files ─────────────────────
+  writeFile(agentDir, 'instructions/conventions.md', INSTRUCTIONS_CONVENTIONS, filesCreated);
+  writeFile(
+    agentDir,
+    'instructions/getting-started.md',
+    INSTRUCTIONS_GETTING_STARTED,
+    filesCreated,
+  );
+
   // ─── 7. Write workflows ─────────────────────────────────────
   for (const wf of BUILTIN_WORKFLOWS) {
     writeFile(agentDir, `workflows/${wf.name}/prompt.md`, wf.prompt, filesCreated);
@@ -355,7 +605,11 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
   }
 
   // ─── 8. Copy bundled skills (with placeholder substitution) ─
-  const skills = generateSkills({ id: config.id } as AgentConfig);
+  const resolvedSkills = resolveSkillsFilter(config.skillsFilter);
+  const skills = generateSkills({
+    id: config.id,
+    skills: resolvedSkills ?? undefined,
+  } as AgentConfig);
   for (const [relativePath, content] of skills) {
     mkdirSync(join(agentDir, dirname(relativePath)), { recursive: true });
     writeFile(agentDir, relativePath, content, filesCreated);
@@ -381,7 +635,33 @@ export function scaffoldFileTree(input: AgentYamlInput, outputDir: string): File
     totalSeeded += starterEntries.length;
   }
 
-  // ─── 9. Generate CLAUDE.md ──────────────────────────────────
+  // ─── 9b. Create workspace directories with CONTEXT.md ──────
+  // Resolve workspaces: use explicit config or seed from domains
+  const resolvedWorkspaces = resolveWorkspaces(config);
+  if (resolvedWorkspaces.length > 0) {
+    for (const ws of resolvedWorkspaces) {
+      const wsDir = join(agentDir, 'workspaces', ws.id);
+      mkdirSync(wsDir, { recursive: true });
+      const contextContent = [
+        `# ${ws.name}`,
+        '',
+        ws.description,
+        '',
+        '## Instructions',
+        '',
+        `<!-- Add workspace-specific instructions here for the "${ws.name}" context. -->`,
+        '',
+      ].join('\n');
+      writeFile(
+        agentDir,
+        `workspaces/${ws.id}/${ws.contextFile ?? 'CONTEXT.md'}`,
+        contextContent,
+        filesCreated,
+      );
+    }
+  }
+
+  // ─── 10. Generate CLAUDE.md ──────────────────────────────────
   const { content: claudeMd } = composeClaudeMd(agentDir);
   writeFile(agentDir, 'CLAUDE.md', claudeMd, filesCreated);
 
@@ -476,6 +756,34 @@ function buildAgentYaml(config: AgentYaml): Record<string, unknown> {
     setup.model = config.setup.model;
   if (Object.keys(setup).length > 0) yaml.setup = setup;
 
+  // Skills filter — only include if not the default ('essential')
+  if (config.skillsFilter && config.skillsFilter !== 'essential') {
+    yaml.skillsFilter = config.skillsFilter;
+  }
+
+  // Workspaces
+  const resolvedWs = resolveWorkspaces(config);
+  if (resolvedWs.length > 0) {
+    yaml.workspaces = resolvedWs.map((ws) =>
+      Object.assign(
+        { id: ws.id, name: ws.name, description: ws.description },
+        ws.contextFile !== `CONTEXT.md` ? { contextFile: ws.contextFile } : {},
+      ),
+    );
+  }
+
+  // Routing
+  const resolvedRouting = resolveRouting(config);
+  if (resolvedRouting.length > 0) {
+    yaml.routing = resolvedRouting.map((r) =>
+      Object.assign(
+        { pattern: r.pattern, workspace: r.workspace },
+        r.context.length > 0 ? { context: r.context } : {},
+        r.skills.length > 0 ? { skills: r.skills } : {},
+      ),
+    );
+  }
+
   // Packs
   if (config.packs && config.packs.length > 0) {
     yaml.packs = config.packs;
@@ -484,6 +792,76 @@ function buildAgentYaml(config: AgentYaml): Record<string, unknown> {
   return yaml;
 }
 
+// ─── Workspace & Routing Helpers ─────────────────────────────────────
+
+/**
+ * Resolve workspaces: use explicit config or seed from domains.
+ * Deduplicates by workspace id.
+ */
+function resolveWorkspaces(
+  config: AgentYaml,
+): { id: string; name: string; description: string; contextFile: string }[] {
+  // If explicitly defined, use those
+  if (config.workspaces && config.workspaces.length > 0) {
+    return config.workspaces.map((ws) => ({
+      id: ws.id,
+      name: ws.name,
+      description: ws.description,
+      contextFile: ws.contextFile ?? 'CONTEXT.md',
+    }));
+  }
+
+  // Otherwise, seed from domains
+  const seen = new Set<string>();
+  const workspaces: { id: string; name: string; description: string; contextFile: string }[] = [];
+
+  for (const domain of config.domains) {
+    const seeds = DOMAIN_WORKSPACE_SEEDS[domain];
+    if (!seeds) continue;
+    for (const seed of seeds) {
+      if (seen.has(seed.id)) continue;
+      seen.add(seed.id);
+      workspaces.push({ ...seed, contextFile: 'CONTEXT.md' });
+    }
+  }
+
+  return workspaces;
+}
+
+/**
+ * Resolve routing entries: use explicit config or seed from domains.
+ * Deduplicates by pattern string.
+ */
+function resolveRouting(
+  config: AgentYaml,
+): { pattern: string; workspace: string; context: string[]; skills: string[] }[] {
+  // If explicitly defined, use those
+  if (config.routing && config.routing.length > 0) {
+    return config.routing.map((r) => ({
+      pattern: r.pattern,
+      workspace: r.workspace,
+      context: r.context ?? [],
+      skills: r.skills ?? [],
+    }));
+  }
+
+  // Otherwise, seed from domains
+  const seen = new Set<string>();
+  const routes: { pattern: string; workspace: string; context: string[]; skills: string[] }[] = [];
+
+  for (const domain of config.domains) {
+    const seeds = DOMAIN_ROUTING_SEEDS[domain];
+    if (!seeds) continue;
+    for (const seed of seeds) {
+      if (seen.has(seed.pattern)) continue;
+      seen.add(seed.pattern);
+      routes.push({ ...seed, context: [] });
+    }
+  }
+
+  return routes;
+}
+
 // ─── Starter Pack Helpers ────────────────────────────────────────────
 
 /** Domain aliases — map agent domains to starter pack directories. */

package/src/scaffolder.ts

@@ -163,6 +163,13 @@ export function previewScaffold(config: AgentConfig): ScaffoldPreview {
     });
   }
 
+  if (opencodeSetup && config.hookPacks?.length) {
+    files.push({
+      path: '.opencode/plugins/',
+      description: `OpenCode enforcement plugin (${config.hookPacks.join(', ')})`,
+    });
+  }
+
   if (config.telegram) {
     files.push(
       {
@@ -334,6 +341,10 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     dirs.push('.claude');
   }
 
+  if (opencodeSetup && config.hookPacks?.length) {
+    dirs.push('.opencode/plugins');
+  }
+
   for (const dir of dirs) {
     mkdirSync(join(agentDir, dir), { recursive: true });
   }
@@ -570,6 +581,12 @@ export function scaffold(config: AgentConfig): ScaffoldResult {
     summaryLines.push(`${config.hookPacks.length} hook pack(s) bundled in .claude/`);
   }
 
+  if (opencodeSetup && config.hookPacks?.length) {
+    summaryLines.push(
+      `${config.hookPacks.length} hook pack(s) bundled as OpenCode plugin in .opencode/plugins/`,
+    );
+  }
+
   for (const registration of mcpRegistrations) {
     if (registration.result.registered) {
       summaryLines.push(