@soleri/forge 9.7.2 → 9.9.0

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 {
@@ -75,7 +133,9 @@ When building a new feature, adding functionality, or creating components.
 - Link new entries to related knowledge: \`op:link_entries\`
 - Complete orchestration: \`op:orchestrate_complete\`
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: brainstorming
     requirement: Requirements are clear and user has approved the approach
     check: user-approval
@@ -92,7 +152,9 @@ When building a new feature, adding functionality, or creating components.
     requirement: Knowledge captured to vault with links
     check: knowledge-captured
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_links op:link_entries
@@ -133,7 +195,9 @@ When fixing bugs, resolving errors, or addressing regressions.
 - If the bug reveals a pattern or anti-pattern, capture it: \`op:capture_knowledge\`
 - Complete orchestration: \`op:orchestrate_complete\`
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: pre-execution
     requirement: Root cause identified and fix plan approved
     check: plan-approved
@@ -146,7 +210,9 @@ When fixing bugs, resolving errors, or addressing regressions.
     requirement: Anti-pattern captured if applicable
     check: knowledge-captured
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_plan op:create_plan
@@ -180,12 +246,16 @@ When reviewing code, auditing quality, or checking for issues.
 ### 4. Capture
 - If review reveals new patterns or anti-patterns, capture them: \`op:capture_knowledge\`
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: completion
     requirement: All blocking issues addressed
     check: issues-resolved
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_vault op:search_intelligent
   - soleri_vault op:capture_knowledge
   - soleri_brain op:recommend
@@ -217,7 +287,9 @@ Before crossing a context window boundary — \`/clear\`, context compaction, or
 - Use plan IDs to look up active plans: \`op:orchestrate_status\`
 - Continue from where the handoff left off
 `,
-    gates: `gates:
+    gates: `# Workflow gates — engine reads these and enforces them during plan execution.
+# Format: phase (brainstorming|pre-execution|post-task|completion), requirement, check
+gates:
   - phase: pre-transition
     requirement: Handoff document generated with current state
     check: handoff-generated
@@ -226,7 +298,9 @@ Before crossing a context window boundary — \`/clear\`, context compaction, or
     requirement: New context has loaded handoff and can reference active plans
     check: context-restored
 `,
-    tools: `tools:
+    tools: `# Workflow tools — engine merges these into plan steps.
+# Format: list of operation strings (agentId_facade op:operation_name)
+tools:
   - soleri_memory op:handoff_generate
   - soleri_memory op:session_capture
   - soleri_orchestrate op:orchestrate_status
@@ -235,6 +309,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 +556,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 +571,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 +604,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 +621,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 +651,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 +772,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 +808,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(