@soleri/forge 9.7.2 → 9.9.0

package/src/agent-schema.ts

@@ -145,6 +145,32 @@ export const WorkflowDefinitionSchema = z.object({
   verificationCriteria: z.array(z.string()).optional().default([]),
 });
 
+// ─── Workspace & Routing Schemas ─────────────────────────────────────
+
+/** Workspace definition — scoped context area within an agent */
+export const WorkspaceSchema = z.object({
+  /** Unique workspace identifier (kebab-case) */
+  id: z.string().min(1),
+  /** Human-readable workspace name */
+  name: z.string().min(1),
+  /** What this workspace is for */
+  description: z.string().min(1),
+  /** Context file name within the workspace directory. Default: CONTEXT.md */
+  contextFile: z.string().optional().default('CONTEXT.md'),
+});
+
+/** Routing entry — maps task patterns to workspaces */
+export const RoutingEntrySchema = z.object({
+  /** Task pattern that triggers this route (e.g., "write script", "review code") */
+  pattern: z.string().min(1),
+  /** Target workspace id */
+  workspace: z.string().min(1),
+  /** Extra context files to load for this route */
+  context: z.array(z.string()).optional().default([]),
+  /** Skills to activate for this route */
+  skills: z.array(z.string()).optional().default([]),
+});
+
 // ─── Main Agent Schema ────────────────────────────────────────────────
 
 /**
@@ -187,13 +213,53 @@ export const AgentYamlSchema = z.object({
   /** LLM client integration settings */
   setup: SetupConfigSchema.optional().default({}),
 
+  // ─── Skills ─────────────────────────────────────
+  /**
+   * Controls which skills are scaffolded.
+   * - 'essential' (default): ~7 core skills for a lightweight start
+   * - 'all': scaffold all available skills (backward compat)
+   * - string[]: scaffold only the named skills
+   */
+  skillsFilter: z
+    .union([z.literal('all'), z.literal('essential'), z.array(z.string())])
+    .optional()
+    .default('essential'),
+
+  // ─── Workspaces & Routing ───────────────────────
+  /** Scoped context areas within the agent */
+  workspaces: z.array(WorkspaceSchema).optional(),
+  /** Task pattern → workspace routing table */
+  routing: z.array(RoutingEntrySchema).optional(),
+
   // ─── Domain Packs ──────────────────────────────
   /** npm domain packs with custom ops and knowledge */
   packs: z.array(DomainPackSchema).optional(),
+
+  // ─── Git Initialization ────────────────────────
+  /** Git initialization configuration. If omitted, git is not initialized. */
+  git: z
+    .object({
+      /** Whether to run git init in the scaffolded agent directory */
+      init: z.boolean(),
+      /** Optional remote repository configuration */
+      remote: z
+        .object({
+          /** How to set up the remote: 'gh' creates via GitHub CLI, 'manual' uses a provided URL */
+          type: z.enum(['gh', 'manual']),
+          /** Remote URL (required for 'manual', auto-generated for 'gh') */
+          url: z.string().optional(),
+          /** Repository visibility for 'gh' type. Default: 'private' */
+          visibility: z.enum(['public', 'private']).optional().default('private'),
+        })
+        .optional(),
+    })
+    .optional(),
 });
 
 export type AgentYaml = z.infer<typeof AgentYamlSchema>;
 export type AgentYamlInput = z.input<typeof AgentYamlSchema>;
+export type Workspace = z.infer<typeof WorkspaceSchema>;
+export type RoutingEntry = z.infer<typeof RoutingEntrySchema>;
 export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
 export type WorkflowGate = z.infer<typeof WorkflowGateSchema>;
 export type WorkflowTaskTemplate = z.infer<typeof WorkflowTaskTemplateSchema>;

package/src/compose-claude-md.ts

@@ -56,7 +56,26 @@ export function composeClaudeMd(agentDir: string, tools?: ToolEntry[]): Composed
   // 5. Essential tools table
   sections.push(composeToolsTable(agentYaml, tools));
 
-  // 6. Engine rules — NOT inlined (they are injected once into ~/.claude/CLAUDE.md
+  // 6. User custom instructions (instructions/user.md) — priority placement
+  //    This file is user-editable and appears BEFORE engine rules and other instructions.
+  const userMdPath = join(agentDir, 'instructions', 'user.md');
+  if (existsSync(userMdPath)) {
+    const userContent = readFileSync(userMdPath, 'utf-8').trim();
+    if (userContent) {
+      sections.push(userContent);
+      sources.push(userMdPath);
+    }
+  }
+
+  // 6b. Workspaces section (if defined)
+  const workspacesSection = composeWorkspacesSection(agentYaml);
+  if (workspacesSection) sections.push(workspacesSection);
+
+  // 6c. Routing table (if defined)
+  const routingSection = composeRoutingTable(agentYaml);
+  if (routingSection) sections.push(routingSection);
+
+  // 7. Engine rules — NOT inlined (they are injected once into ~/.claude/CLAUDE.md
   //    or project CLAUDE.md via `soleri install`). Including them here would
   //    triple-load the rules (~8k tokens duplicated per layer).
   //    We emit a short reference so the agent knows rules exist.
@@ -72,11 +91,11 @@ export function composeClaudeMd(agentDir: string, tools?: ToolEntry[]): Composed
     sources.push(enginePath);
   }
 
-  // 7. User instructions (instructions/*.md, excluding _engine.md)
+  // 8. User instructions (instructions/*.md, excluding _engine.md and user.md)
   const instructionsDir = join(agentDir, 'instructions');
   if (existsSync(instructionsDir)) {
     const files = readdirSync(instructionsDir)
-      .filter((f) => f.endsWith('.md') && f !== '_engine.md')
+      .filter((f) => f.endsWith('.md') && f !== '_engine.md' && f !== 'user.md')
       .sort();
     for (const file of files) {
       const filePath = join(instructionsDir, file);
@@ -198,6 +217,47 @@ function composeToolsTable(agent: AgentYaml, tools?: ToolEntry[]): string {
   return lines.join('\n');
 }
 
+function composeWorkspacesSection(agent: AgentYaml): string | null {
+  if (!agent.workspaces || agent.workspaces.length === 0) return null;
+
+  const lines: string[] = [
+    '## Workspaces',
+    '',
+    'Scoped context areas — each workspace has its own CONTEXT.md with task-specific instructions.',
+    '',
+    '| Workspace | Description |',
+    '|-----------|-------------|',
+  ];
+
+  for (const ws of agent.workspaces) {
+    lines.push(`| \`${ws.id}\` | ${ws.description} |`);
+  }
+
+  return lines.join('\n');
+}
+
+function composeRoutingTable(agent: AgentYaml): string | null {
+  if (!agent.routing || agent.routing.length === 0) return null;
+
+  const lines: string[] = [
+    '## Task Routing',
+    '',
+    'When a task matches a pattern below, navigate to the target workspace, load its CONTEXT.md, and activate the listed skills.',
+    'If no pattern matches, use the default root context.',
+    '',
+    '| Task Pattern | Route To | Context | Skills |',
+    '|--------------|----------|---------|--------|',
+  ];
+
+  for (const route of agent.routing) {
+    const ctx = route.context.length > 0 ? route.context.join(', ') : '—';
+    const skills = route.skills.length > 0 ? route.skills.map((s) => `\`${s}\``).join(', ') : '—';
+    lines.push(`| ${route.pattern} | \`${route.workspace}\` | ${ctx} | ${skills} |`);
+  }
+
+  return lines.join('\n');
+}
+
 function composeWorkflowIndex(workflowsDir: string): string | null {
   const dirs = readdirSync(workflowsDir, { withFileTypes: true })
     .filter((d) => d.isDirectory())

package/src/domain-manager.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { generateDomainFacade } from './templates/domain-facade.js';
 import { generateVaultOnlyDomainFacade } from './knowledge-installer.js';
 import { patchIndexTs, patchClaudeMdContent } from './patching.js';
@@ -17,6 +18,7 @@ interface AddDomainParams {
   agentPath: string;
   domain: string;
   noBuild?: boolean;
+  format?: 'filetree' | 'typescript';
 }
 
 /**
@@ -41,9 +43,17 @@ function isV5Agent(agentPath: string): boolean {
  * 6. Rebuild (unless noBuild)
  */
 export async function addDomain(params: AddDomainParams): Promise<AddDomainResult> {
-  const { agentPath, domain, noBuild = false } = params;
+  const { agentPath, domain, noBuild = false, format } = params;
   const warnings: string[] = [];
 
+  // ── File-tree agent path ──
+
+  if (format === 'filetree') {
+    return addDomainFileTree(agentPath, domain);
+  }
+
+  // ── TypeScript agent path (default / backward compat) ──
+
   // ── Validate agent ──
 
   const pkgPath = join(agentPath, 'package.json');
@@ -174,6 +184,69 @@ export async function addDomain(params: AddDomainParams): Promise<AddDomainResul
   };
 }
 
+/**
+ * Add a domain to a file-tree agent (agent.yaml + knowledge/).
+ * No facade generation, no src/ patching, no build step.
+ */
+function addDomainFileTree(agentPath: string, domain: string): AddDomainResult {
+  // ── Validate domain name ──
+
+  if (!/^[a-z][a-z0-9-]*$/.test(domain)) {
+    return fail(agentPath, domain, `Invalid domain name "${domain}" — must be kebab-case`);
+  }
+
+  // ── Read and validate agent.yaml ──
+
+  const yamlPath = join(agentPath, 'agent.yaml');
+  if (!existsSync(yamlPath)) {
+    return fail(agentPath, domain, 'No agent.yaml found — is this a file-tree agent?');
+  }
+
+  let agentYaml: Record<string, unknown>;
+  try {
+    agentYaml = parseYaml(readFileSync(yamlPath, 'utf-8')) as Record<string, unknown>;
+  } catch {
+    return fail(agentPath, domain, 'Failed to parse agent.yaml — is it valid YAML?');
+  }
+
+  const agentId = (agentYaml.id as string) ?? '';
+  if (!agentId) {
+    return fail(agentPath, domain, 'agent.yaml is missing an "id" field');
+  }
+
+  // ── Check if domain already exists ──
+
+  const domains: string[] = Array.isArray(agentYaml.domains) ? (agentYaml.domains as string[]) : [];
+  if (domains.includes(domain)) {
+    return fail(agentPath, domain, `Domain "${domain}" already exists in agent.yaml`);
+  }
+
+  // ── Update agent.yaml domains array ──
+
+  agentYaml.domains = [...domains, domain];
+  writeFileSync(yamlPath, stringifyYaml(agentYaml), 'utf-8');
+
+  // ── Create knowledge/{domain}.json ──
+
+  const knowledgeDir = join(agentPath, 'knowledge');
+  mkdirSync(knowledgeDir, { recursive: true });
+
+  const bundlePath = join(knowledgeDir, `${domain}.json`);
+  const emptyBundle = JSON.stringify({ domain, entries: [] }, null, 2);
+  writeFileSync(bundlePath, emptyBundle, 'utf-8');
+
+  return {
+    success: true,
+    agentPath,
+    domain,
+    agentId,
+    facadeGenerated: false,
+    buildOutput: '',
+    warnings: [],
+    summary: `Added domain "${domain}" to ${agentId} (file-tree agent)`,
+  };
+}
+
 function fail(agentPath: string, domain: string, message: string): AddDomainResult {
   return {
     success: false,

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';