@soleri/forge 9.7.2 → 9.8.0

package/src/__tests__/scaffold-filetree.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { mkdirSync, rmSync, existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
@@ -197,6 +197,31 @@ describe('scaffoldFileTree', () => {
     expect(gitignore).toContain('_engine.md');
   });
 
+  it('generates conventions.md example instruction file', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'instructions', 'conventions.md'), 'utf-8');
+    expect(content).toContain('# Conventions');
+    expect(content).toContain('Naming Conventions');
+    expect(content).toContain('What to Avoid');
+    expect(content).toContain('kebab-case');
+  });
+
+  it('generates getting-started.md example instruction file', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(
+      join(result.agentDir, 'instructions', 'getting-started.md'),
+      'utf-8',
+    );
+    expect(content).toContain('Getting Started with Instructions');
+    expect(content).toContain('_engine.md');
+    expect(content).toContain('soleri dev');
+    expect(content).toContain('alphabetical order');
+  });
+
   it('fails if directory already exists', () => {
     scaffoldFileTree(MINIMAL_CONFIG, tempDir);
     const result2 = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
@@ -252,4 +277,260 @@ describe('scaffoldFileTree', () => {
     expect(result.success).toBe(true);
     expect(result.summary).toContain('No build step needed');
   });
+
+  it('generates user.md with placeholder content', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const userMdPath = join(result.agentDir, 'instructions', 'user.md');
+    expect(existsSync(userMdPath)).toBe(true);
+
+    const content = readFileSync(userMdPath, 'utf-8');
+    expect(content).toContain('# Your Custom Rules');
+    expect(content).toContain('priority placement in CLAUDE.md');
+    expect(content).toContain('Delete these instructions and replace with your own content.');
+  });
+
+  it('includes user.md in filesCreated', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+    expect(result.filesCreated).toContain('instructions/user.md');
+  });
+
+  it('places user.md content before engine rules ref in CLAUDE.md', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const claudeMd = readFileSync(join(result.agentDir, 'CLAUDE.md'), 'utf-8');
+    const userPos = claudeMd.indexOf('# Your Custom Rules');
+    const enginePos = claudeMd.indexOf('soleri:engine-rules-ref');
+
+    expect(userPos).toBeGreaterThan(-1);
+    expect(enginePos).toBeGreaterThan(-1);
+    expect(userPos).toBeLessThan(enginePos);
+  });
+
+  it('does not duplicate user.md in the alphabetical instructions section', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const claudeMd = readFileSync(join(result.agentDir, 'CLAUDE.md'), 'utf-8');
+    // user.md content should appear exactly once
+    const matches = claudeMd.match(/# Your Custom Rules/g);
+    expect(matches).toHaveLength(1);
+  });
+
+  // ─── Skills Filter Tests ─────────────────────────────────────
+
+  it('default scaffold creates only essential skills (~7)', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const skillDirs = readdirSync(join(result.agentDir, 'skills'), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    // Should have ~7 essential skills, not 30+
+    expect(skillDirs.length).toBeGreaterThanOrEqual(5);
+    expect(skillDirs.length).toBeLessThanOrEqual(10);
+
+    // Essential skills should be present
+    expect(skillDirs).toContain('agent-guide');
+    expect(skillDirs).toContain('vault-navigator');
+    expect(skillDirs).toContain('vault-capture');
+    expect(skillDirs).toContain('systematic-debugging');
+    expect(skillDirs).toContain('writing-plans');
+    expect(skillDirs).toContain('context-resume');
+    expect(skillDirs).toContain('agent-persona');
+
+    // Optional skills should NOT be present
+    expect(skillDirs).not.toContain('brainstorming');
+    expect(skillDirs).not.toContain('deep-review');
+    expect(skillDirs).not.toContain('code-patrol');
+    expect(skillDirs).not.toContain('yolo-mode');
+  });
+
+  it('skillsFilter: "all" creates all skills', () => {
+    const result = scaffoldFileTree(
+      { ...MINIMAL_CONFIG, id: 'all-skills', skillsFilter: 'all' },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const skillDirs = readdirSync(join(result.agentDir, 'skills'), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    // Should have all 30+ skills
+    expect(skillDirs.length).toBeGreaterThanOrEqual(25);
+    expect(skillDirs).toContain('brainstorming');
+    expect(skillDirs).toContain('deep-review');
+    expect(skillDirs).toContain('yolo-mode');
+  });
+
+  it('skillsFilter: explicit array creates exactly those skills', () => {
+    const result = scaffoldFileTree(
+      { ...MINIMAL_CONFIG, id: 'custom-skills', skillsFilter: ['vault-navigator', 'agent-guide'] },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const skillDirs = readdirSync(join(result.agentDir, 'skills'), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    expect(skillDirs).toEqual(['agent-guide', 'vault-navigator']);
+  });
+
+  it('CLAUDE.md only lists on-disk skills', () => {
+    // Default scaffold = essential only
+    const result = scaffoldFileTree({ ...MINIMAL_CONFIG, id: 'claude-md-skills' }, tempDir);
+    expect(result.success).toBe(true);
+
+    const claudeMd = readFileSync(join(result.agentDir, 'CLAUDE.md'), 'utf-8');
+
+    // Essential skills should appear
+    expect(claudeMd).toContain('vault-navigator');
+    expect(claudeMd).toContain('agent-guide');
+
+    // Optional skills should NOT appear (not on disk)
+    expect(claudeMd).not.toContain('brainstorming');
+    expect(claudeMd).not.toContain('yolo-mode');
+  });
+
+  it('skillsFilter default (essential) is not written to agent.yaml', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'agent.yaml'), 'utf-8');
+    expect(content).not.toContain('skillsFilter');
+  });
+
+  it('skillsFilter: "all" IS written to agent.yaml', () => {
+    const result = scaffoldFileTree(
+      { ...MINIMAL_CONFIG, id: 'written-filter', skillsFilter: 'all' },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'agent.yaml'), 'utf-8');
+    const parsed = parseYaml(content);
+    expect(parsed.skillsFilter).toBe('all');
+  });
+
+  // ─── Workspace & Routing Tests ─────────────────────────────
+
+  it('creates workspace directories with CONTEXT.md when workspaces defined', () => {
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        workspaces: [
+          { id: 'design', name: 'Design', description: 'Design workspace' },
+          { id: 'review', name: 'Review', description: 'Review workspace' },
+        ],
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    // Workspace directories and CONTEXT.md files exist
+    expect(existsSync(join(result.agentDir, 'workspaces', 'design', 'CONTEXT.md'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'workspaces', 'review', 'CONTEXT.md'))).toBe(true);
+
+    // CONTEXT.md contains workspace name and description
+    const content = readFileSync(
+      join(result.agentDir, 'workspaces', 'design', 'CONTEXT.md'),
+      'utf-8',
+    );
+    expect(content).toContain('# Design');
+    expect(content).toContain('Design workspace');
+  });
+
+  it('seeds default workspaces from domains when no explicit workspaces', () => {
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        domains: ['architecture'],
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    // Architecture domain seeds planning, src, docs workspaces
+    expect(existsSync(join(result.agentDir, 'workspaces', 'planning', 'CONTEXT.md'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'workspaces', 'src', 'CONTEXT.md'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'workspaces', 'docs', 'CONTEXT.md'))).toBe(true);
+  });
+
+  it('includes routing entries in agent.yaml', () => {
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        workspaces: [{ id: 'src', name: 'Source', description: 'Source code' }],
+        routing: [{ pattern: 'implement feature', workspace: 'src', skills: ['tdd'] }],
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'agent.yaml'), 'utf-8');
+    const parsed = parseYaml(content);
+
+    expect(parsed.workspaces).toHaveLength(1);
+    expect(parsed.workspaces[0].id).toBe('src');
+    expect(parsed.routing).toHaveLength(1);
+    expect(parsed.routing[0].pattern).toBe('implement feature');
+    expect(parsed.routing[0].workspace).toBe('src');
+    expect(parsed.routing[0].skills).toEqual(['tdd']);
+  });
+
+  it('creates no workspaces directory when no workspaces and no matching domains', () => {
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        domains: ['testing', 'quality'], // no workspace seeds for these
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    // No workspaces directory
+    expect(existsSync(join(result.agentDir, 'workspaces'))).toBe(false);
+  });
+
+  it('includes workspaces and routing sections in CLAUDE.md when defined', () => {
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        workspaces: [{ id: 'design', name: 'Design', description: 'Design patterns' }],
+        routing: [
+          { pattern: 'design component', workspace: 'design', skills: ['vault-navigator'] },
+        ],
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const claudeMd = readFileSync(join(result.agentDir, 'CLAUDE.md'), 'utf-8');
+    expect(claudeMd).toContain('## Workspaces');
+    expect(claudeMd).toContain('Design patterns');
+    expect(claudeMd).toContain('## Task Routing');
+    expect(claudeMd).toContain('design component');
+  });
+
+  it('omits workspaces and routing sections from CLAUDE.md when not defined', () => {
+    // Use domains with no workspace seeds
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        domains: ['testing', 'quality'],
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const claudeMd = readFileSync(join(result.agentDir, 'CLAUDE.md'), 'utf-8');
+    expect(claudeMd).not.toContain('## Workspaces');
+    expect(claudeMd).not.toContain('## Task Routing');
+  });
 });

package/src/__tests__/shared-rules.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { getEngineRulesContent, getEngineMarker } from '../templates/shared-rules.js';
+
+describe('shared-rules', () => {
+  const content = getEngineRulesContent();
+
+  it('includes the engine marker', () => {
+    expect(content).toContain(`<!-- ${getEngineMarker()} -->`);
+  });
+
+  describe('Reconciliation Triggers', () => {
+    it('includes the Reconciliation Triggers section', () => {
+      expect(content).toContain('### Reconciliation Triggers');
+    });
+
+    it('includes the explicit trigger (user says "done")', () => {
+      expect(content).toContain('**Explicit**');
+      expect(content).toMatch(/User says.*done.*ship it.*looks good/);
+    });
+
+    it('includes the plan-complete trigger', () => {
+      expect(content).toContain('**Plan-complete**');
+      expect(content).toContain(
+        'All tasks are complete. Want me to wrap up and capture what we learned, or is there more to fix?',
+      );
+    });
+
+    it('includes the idle trigger', () => {
+      expect(content).toContain('**Idle**');
+      expect(content).toContain(
+        "We've been idle on this plan. Ready to wrap up, or still working?",
+      );
+    });
+
+    it('includes the NEVER auto-complete rule', () => {
+      expect(content).toContain('**NEVER auto-complete without asking the user.**');
+    });
+
+    it('references orchestrate_status readiness field', () => {
+      expect(content).toContain('op:orchestrate_status');
+      expect(content).toContain('allTasksTerminal');
+    });
+  });
+
+  it('describes orchestrate_complete as user-gated in the Non-Negotiable Rule', () => {
+    expect(content).toContain('user-gated');
+  });
+});

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,