@soleri/forge 5.14.9 → 7.0.0

package/src/__tests__/detect-domain-packs.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { detectInstalledDomainPacks } from '../utils/detect-domain-packs.js';
+
+function createTempDir(): string {
+  const dir = join(
+    tmpdir(),
+    `soleri-forge-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+describe('detectInstalledDomainPacks', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup
+    }
+  });
+
+  it('returns empty array when no node_modules exists', () => {
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([]);
+  });
+
+  it('returns empty array when @soleri scope exists but has no domain-* packages', () => {
+    const scope = join(tempDir, 'node_modules', '@soleri', 'core');
+    mkdirSync(scope, { recursive: true });
+    writeFileSync(
+      join(scope, 'package.json'),
+      JSON.stringify({ name: '@soleri/core', version: '1.0.0' }),
+    );
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([]);
+  });
+
+  it('detects a domain pack with soleri-domain-pack keyword', () => {
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-design');
+    mkdirSync(packDir, { recursive: true });
+    writeFileSync(
+      join(packDir, 'package.json'),
+      JSON.stringify({
+        name: '@soleri/domain-design',
+        version: '2.1.0',
+        keywords: ['soleri-domain-pack'],
+      }),
+    );
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([
+      { name: 'design', package: '@soleri/domain-design', version: '2.1.0' },
+    ]);
+  });
+
+  it('detects a domain pack with a main entry point', () => {
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-security');
+    const distDir = join(packDir, 'dist');
+    mkdirSync(distDir, { recursive: true });
+    writeFileSync(
+      join(packDir, 'package.json'),
+      JSON.stringify({
+        name: '@soleri/domain-security',
+        version: '1.0.0',
+        main: 'dist/index.js',
+      }),
+    );
+    writeFileSync(join(distDir, 'index.js'), 'module.exports = {};');
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([
+      { name: 'security', package: '@soleri/domain-security', version: '1.0.0' },
+    ]);
+  });
+
+  it('detects multiple domain packs', () => {
+    for (const [suffix, ver] of [
+      ['design', '2.0.0'],
+      ['security', '1.0.0'],
+      ['analytics', '0.5.0'],
+    ]) {
+      const packDir = join(tempDir, 'node_modules', '@soleri', `domain-${suffix}`);
+      mkdirSync(packDir, { recursive: true });
+      writeFileSync(
+        join(packDir, 'package.json'),
+        JSON.stringify({
+          name: `@soleri/domain-${suffix}`,
+          version: ver,
+          keywords: ['soleri-domain-pack'],
+        }),
+      );
+    }
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toHaveLength(3);
+    expect(result.map((r) => r.name).sort()).toEqual(['analytics', 'design', 'security']);
+  });
+
+  it('skips packages without valid package.json', () => {
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-broken');
+    mkdirSync(packDir, { recursive: true });
+    writeFileSync(join(packDir, 'package.json'), '{ invalid json }');
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([]);
+  });
+
+  it('skips packages missing name or version', () => {
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-incomplete');
+    mkdirSync(packDir, { recursive: true });
+    writeFileSync(
+      join(packDir, 'package.json'),
+      JSON.stringify({ name: '@soleri/domain-incomplete' }), // no version
+    );
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([]);
+  });
+
+  it('skips packages that have no entry point and no keyword', () => {
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-empty');
+    mkdirSync(packDir, { recursive: true });
+    writeFileSync(
+      join(packDir, 'package.json'),
+      JSON.stringify({ name: '@soleri/domain-empty', version: '1.0.0' }),
+    );
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([]);
+  });
+
+  it('walks up to find node_modules in a parent directory', () => {
+    // Create node_modules in tempDir but search from a subdirectory
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-design');
+    mkdirSync(packDir, { recursive: true });
+    writeFileSync(
+      join(packDir, 'package.json'),
+      JSON.stringify({
+        name: '@soleri/domain-design',
+        version: '1.0.0',
+        keywords: ['soleri-domain-pack'],
+      }),
+    );
+
+    const subDir = join(tempDir, 'projects', 'my-agent');
+    mkdirSync(subDir, { recursive: true });
+
+    const result = detectInstalledDomainPacks(subDir);
+    expect(result).toEqual([
+      { name: 'design', package: '@soleri/domain-design', version: '1.0.0' },
+    ]);
+  });
+
+  it('detects domain pack with dist/index.js entry point (no main field)', () => {
+    const packDir = join(tempDir, 'node_modules', '@soleri', 'domain-testing');
+    mkdirSync(join(packDir, 'dist'), { recursive: true });
+    writeFileSync(
+      join(packDir, 'package.json'),
+      JSON.stringify({ name: '@soleri/domain-testing', version: '1.0.0' }),
+    );
+    writeFileSync(join(packDir, 'dist', 'index.js'), 'export default {};');
+
+    const result = detectInstalledDomainPacks(tempDir);
+    expect(result).toEqual([
+      { name: 'testing', package: '@soleri/domain-testing', version: '1.0.0' },
+    ]);
+  });
+});

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

@@ -0,0 +1,243 @@
+/**
+ * Tests for the file-tree scaffolder.
+ *
+ * Validates that scaffoldFileTree() produces a valid agent folder
+ * with all expected files and no TypeScript output.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { parse as parseYaml } from 'yaml';
+import { scaffoldFileTree } from '../scaffold-filetree.js';
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = join(tmpdir(), `soleri-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(tempDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+const MINIMAL_CONFIG = {
+  id: 'test-agent',
+  name: 'Test Agent',
+  role: 'Testing Advisor',
+  description: 'A test agent for validating the file-tree scaffolder output.',
+  domains: ['testing', 'quality'],
+  principles: ['Test everything', 'Fail fast'],
+};
+
+describe('scaffoldFileTree', () => {
+  it('creates agent directory with all expected files', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+
+    expect(result.success).toBe(true);
+    expect(result.agentDir).toBe(join(tempDir, 'test-agent'));
+    expect(result.filesCreated.length).toBeGreaterThan(10);
+
+    // Core files exist
+    expect(existsSync(join(result.agentDir, 'agent.yaml'))).toBe(true);
+    expect(existsSync(join(result.agentDir, '.mcp.json'))).toBe(true);
+    expect(existsSync(join(result.agentDir, '.gitignore'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'CLAUDE.md'))).toBe(true);
+
+    // Directories exist
+    expect(existsSync(join(result.agentDir, 'instructions'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'workflows'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'knowledge'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'skills'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'hooks'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'data'))).toBe(true);
+  });
+
+  it('generates NO TypeScript files', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    // No .ts files anywhere
+    const tsFiles = result.filesCreated.filter((f) => f.endsWith('.ts'));
+    expect(tsFiles).toEqual([]);
+
+    // No package.json
+    expect(existsSync(join(result.agentDir, 'package.json'))).toBe(false);
+
+    // No tsconfig.json
+    expect(existsSync(join(result.agentDir, 'tsconfig.json'))).toBe(false);
+
+    // No src/ directory
+    expect(existsSync(join(result.agentDir, 'src'))).toBe(false);
+
+    // No node_modules
+    expect(existsSync(join(result.agentDir, 'node_modules'))).toBe(false);
+  });
+
+  it('generates valid agent.yaml', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'agent.yaml'), 'utf-8');
+    const parsed = parseYaml(content);
+
+    expect(parsed.id).toBe('test-agent');
+    expect(parsed.name).toBe('Test Agent');
+    expect(parsed.role).toBe('Testing Advisor');
+    expect(parsed.domains).toEqual(['testing', 'quality']);
+    expect(parsed.principles).toEqual(['Test everything', 'Fail fast']);
+  });
+
+  it('generates valid .mcp.json pointing to soleri-engine', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, '.mcp.json'), 'utf-8');
+    const parsed = JSON.parse(content);
+
+    expect(parsed.mcpServers['soleri-engine']).toBeDefined();
+    expect(parsed.mcpServers['soleri-engine'].command).toBe('npx');
+    expect(parsed.mcpServers['soleri-engine'].args).toContain('@soleri/engine');
+    expect(parsed.mcpServers['soleri-engine'].args).toContain('./agent.yaml');
+  });
+
+  it('generates engine rules in instructions/_engine.md', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'instructions', '_engine.md'), 'utf-8');
+    expect(content).toContain('soleri:engine-rules');
+    expect(content).toContain('Vault as Source of Truth');
+    expect(content).toContain('Planning');
+    expect(content).toContain('Clean Commits');
+  });
+
+  it('generates domain instruction file', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'instructions', 'domain.md'), 'utf-8');
+    expect(content).toContain('testing, quality');
+    expect(content).toContain('Test everything');
+  });
+
+  it('generates workflow folders with prompt, gates, and tools', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    // Check feature-dev workflow
+    const featureDevDir = join(result.agentDir, 'workflows', 'feature-dev');
+    expect(existsSync(join(featureDevDir, 'prompt.md'))).toBe(true);
+    expect(existsSync(join(featureDevDir, 'gates.yaml'))).toBe(true);
+    expect(existsSync(join(featureDevDir, 'tools.yaml'))).toBe(true);
+
+    const prompt = readFileSync(join(featureDevDir, 'prompt.md'), 'utf-8');
+    expect(prompt).toContain('Feature Development');
+    expect(prompt).toContain('op:search_intelligent');
+
+    // Check bug-fix workflow
+    expect(existsSync(join(result.agentDir, 'workflows', 'bug-fix', 'prompt.md'))).toBe(true);
+
+    // Check code-review workflow
+    expect(existsSync(join(result.agentDir, 'workflows', 'code-review', 'prompt.md'))).toBe(true);
+  });
+
+  it('generates knowledge bundles per domain', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    // One bundle per domain
+    expect(existsSync(join(result.agentDir, 'knowledge', 'testing.json'))).toBe(true);
+    expect(existsSync(join(result.agentDir, 'knowledge', 'quality.json'))).toBe(true);
+
+    const bundle = JSON.parse(
+      readFileSync(join(result.agentDir, 'knowledge', 'testing.json'), 'utf-8'),
+    );
+    expect(bundle.domain).toBe('testing');
+    expect(bundle.version).toBe('1.0.0');
+    expect(bundle.entries).toEqual([]);
+  });
+
+  it('generates CLAUDE.md with correct agent identity', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const claudeMd = readFileSync(join(result.agentDir, 'CLAUDE.md'), 'utf-8');
+    expect(claudeMd).toContain('# Test Agent Mode');
+    expect(claudeMd).toContain('**Role:** Testing Advisor');
+    expect(claudeMd).toContain('test-agent_core op:activate');
+    expect(claudeMd).toContain('test-agent_vault');
+    expect(claudeMd).toContain('Available Workflows');
+    expect(claudeMd).toContain('feature-dev');
+  });
+
+  it('.gitignore excludes auto-generated files', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const gitignore = readFileSync(join(result.agentDir, '.gitignore'), 'utf-8');
+    expect(gitignore).toContain('CLAUDE.md');
+    expect(gitignore).toContain('AGENTS.md');
+    expect(gitignore).toContain('_engine.md');
+  });
+
+  it('fails if directory already exists', () => {
+    scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    const result2 = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+
+    expect(result2.success).toBe(false);
+    expect(result2.summary).toContain('already exists');
+  });
+
+  it('fails on invalid config', () => {
+    const result = scaffoldFileTree(
+      { id: 'INVALID_ID', name: '', role: '', description: '', domains: [], principles: [] } as any,
+      tempDir,
+    );
+    expect(result.success).toBe(false);
+    expect(result.summary).toContain('Invalid config');
+  });
+
+  it('omits default values from agent.yaml for clean output', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'agent.yaml'), 'utf-8');
+
+    // tone: pragmatic is the default — should NOT appear
+    expect(content).not.toContain('tone:');
+    // setup.target: opencode is the default — should NOT appear
+    expect(content).not.toContain('target:');
+    // engine.learning: true is the default — should NOT appear
+    expect(content).not.toContain('learning:');
+  });
+
+  it('includes non-default values in agent.yaml', () => {
+    const result = scaffoldFileTree(
+      {
+        ...MINIMAL_CONFIG,
+        tone: 'precise',
+        setup: { target: 'claude', model: 'claude-code-opus-4' },
+        engine: { cognee: true },
+      },
+      tempDir,
+    );
+    expect(result.success).toBe(true);
+
+    const content = readFileSync(join(result.agentDir, 'agent.yaml'), 'utf-8');
+    const parsed = parseYaml(content);
+
+    expect(parsed.tone).toBe('precise');
+    expect(parsed.setup.target).toBe('claude');
+    expect(parsed.setup.model).toBe('claude-code-opus-4');
+    expect(parsed.engine.cognee).toBe(true);
+  });
+
+  it('summary says no build step needed', () => {
+    const result = scaffoldFileTree(MINIMAL_CONFIG, tempDir);
+    expect(result.success).toBe(true);
+    expect(result.summary).toContain('No build step needed');
+  });
+});

package/src/__tests__/scaffolder.test.ts

@@ -99,7 +99,7 @@ describe('Scaffolder', () => {
       scaffold(testConfig);
       const pkg = JSON.parse(readFileSync(join(tempDir, 'atlas', 'package.json'), 'utf-8'));
 
-      expect(pkg.name).toBe('atlas-mcp');
+      expect(pkg.name).toBe('atlas');
       expect(pkg.type).toBe('module');
       expect(pkg.dependencies['@modelcontextprotocol/sdk']).toBeDefined();
       expect(pkg.dependencies['@soleri/core']).toBe('^2.0.0');
@@ -121,7 +121,7 @@ describe('Scaffolder', () => {
       expect(persona).toContain('Data quality is non-negotiable');
     });
 
-    it('should create empty intelligence data files', () => {
+    it('should create seeded intelligence data files', () => {
       scaffold(testConfig);
       const dataDir = join(tempDir, 'atlas', 'src', 'intelligence', 'data');
       const files = readdirSync(dataDir);
@@ -132,7 +132,9 @@ describe('Scaffolder', () => {
 
       const bundle = JSON.parse(readFileSync(join(dataDir, 'data-pipelines.json'), 'utf-8'));
       expect(bundle.domain).toBe('data-pipelines');
-      expect(bundle.entries).toEqual([]);
+      expect(bundle.entries.length).toBe(1);
+      expect(bundle.entries[0].id).toBe('data-pipelines-seed');
+      expect(bundle.entries[0].tags).toContain('seed');
     });
 
     it('should create entry point using runtime factories from @soleri/core', () => {

package/src/agent-schema.ts

@@ -0,0 +1,184 @@
+/**
+ * Soleri v7 — File-Tree Agent Schema
+ *
+ * Defines the agent.yaml format for file-tree agents.
+ * This replaces the old AgentConfigSchema that generated TypeScript projects.
+ *
+ * An agent is a folder. This schema defines agent.yaml — the single source
+ * of truth for identity and engine configuration.
+ */
+
+import { z } from 'zod';
+
+// ─── Constants ────────────────────────────────────────────────────────
+
+/** Communication tones */
+export const TONES = ['precise', 'mentor', 'pragmatic'] as const;
+export type Tone = (typeof TONES)[number];
+
+/** Where to set up client integration */
+export const SETUP_TARGETS = ['claude', 'codex', 'opencode', 'both', 'all'] as const;
+export type SetupTarget = (typeof SETUP_TARGETS)[number];
+
+// ─── Sub-Schemas ──────────────────────────────────────────────────────
+
+/** External vault connection */
+const VaultConnectionSchema = z.object({
+  /** Display name for this vault */
+  name: z.string().min(1),
+  /** Absolute path to vault SQLite database */
+  path: z.string().min(1),
+  /** Search priority (0–1). Higher = results ranked higher. Default: 0.5 */
+  priority: z.number().min(0).max(1).optional().default(0.5),
+});
+
+/** Domain pack reference */
+const DomainPackSchema = z.object({
+  /** Domain name (e.g., "design", "code-review") */
+  name: z.string().min(1),
+  /** npm package name (e.g., "@soleri/domain-design") */
+  package: z.string().min(1),
+  /** Semver version constraint (optional) */
+  version: z.string().optional(),
+});
+
+/** Engine configuration */
+const EngineConfigSchema = z.object({
+  /** Path to agent's vault SQLite database. Default: ~/.{id}/vault.db */
+  vault: z.string().optional(),
+  /** Enable brain/learning loop. Default: true */
+  learning: z.boolean().optional().default(true),
+  /** Enable Cognee vector search. Default: false */
+  cognee: z.boolean().optional().default(false),
+});
+
+/** Client setup configuration */
+const SetupConfigSchema = z.object({
+  /** Target client for MCP registration */
+  target: z.enum(SETUP_TARGETS).optional().default('opencode'),
+  /** Primary model for the client */
+  model: z.string().optional().default('claude-code-sonnet-4'),
+});
+
+// ─── Workflow Sub-Schemas ─────────────────────────────────────────────
+
+/** Gate phases in a workflow */
+export const GATE_PHASES = ['brainstorming', 'pre-execution', 'post-task', 'completion'] as const;
+export type GatePhase = (typeof GATE_PHASES)[number];
+
+/** Workflow gate definition (maps to gates.yaml) */
+export const WorkflowGateSchema = z.object({
+  phase: z.enum(GATE_PHASES),
+  requirement: z.string().min(1),
+  check: z.string().min(1),
+});
+
+/** Task template ordering */
+export const TASK_ORDERS = ['before-implementation', 'after-implementation', 'parallel'] as const;
+
+/** Task template types */
+export const TASK_TYPES = [
+  'implementation',
+  'test',
+  'story',
+  'documentation',
+  'verification',
+] as const;
+
+/** Workflow task template (injected during plan generation) */
+export const WorkflowTaskTemplateSchema = z.object({
+  taskType: z.enum(TASK_TYPES),
+  titleTemplate: z.string().min(1),
+  acceptanceCriteria: z.array(z.string()).optional().default([]),
+  tools: z.array(z.string()).optional().default([]),
+  order: z.enum(TASK_ORDERS),
+});
+
+/** Workflow intent types */
+export const INTENTS = ['BUILD', 'FIX', 'REVIEW', 'PLAN', 'IMPROVE', 'DELIVER'] as const;
+export type Intent = (typeof INTENTS)[number];
+
+/** Workflow definition (maps to workflow folder contents) */
+export const WorkflowDefinitionSchema = z.object({
+  /** Unique workflow ID (derived from folder name if not specified) */
+  id: z.string().optional(),
+  /** generic or domain tier */
+  tier: z.enum(['generic', 'domain']).optional().default('generic'),
+  /** Human-readable title */
+  title: z.string().min(1),
+  /** When to activate this workflow */
+  trigger: z.string().optional(),
+  /** What this workflow does */
+  description: z.string().optional(),
+  /** Numbered step-by-step process (from prompt.md, parsed at runtime) */
+  steps: z.string().optional(),
+  /** Success criteria */
+  expectedOutcome: z.string().optional(),
+  /** ID of generic workflow this domain workflow extends */
+  extends: z.string().optional(),
+  /** Domain filtering: skip UI playbooks for backend tasks */
+  domain: z.enum(['ui', 'backend', 'any']).optional().default('any'),
+  /** Intents that trigger this workflow */
+  matchIntents: z.array(z.enum(INTENTS)).optional().default([]),
+  /** Keywords in plan text that trigger this workflow */
+  matchKeywords: z.array(z.string()).optional().default([]),
+  /** Lifecycle checkpoints */
+  gates: z.array(WorkflowGateSchema).optional().default([]),
+  /** Task templates injected during plan generation */
+  taskTemplates: z.array(WorkflowTaskTemplateSchema).optional().default([]),
+  /** Tools auto-added to plan's tool chain */
+  toolInjections: z.array(z.string()).optional().default([]),
+  /** Completion gate validation rules */
+  verificationCriteria: z.array(z.string()).optional().default([]),
+});
+
+// ─── Main Agent Schema ────────────────────────────────────────────────
+
+/**
+ * agent.yaml schema — the single source of truth for a file-tree agent.
+ *
+ * This is what `soleri create` generates and what the engine reads on startup.
+ */
+export const AgentYamlSchema = z.object({
+  // ─── Identity (required) ────────────────────────
+  /** Agent identifier — kebab-case, used for directories and tool prefixes */
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/, 'Must be kebab-case (e.g., "gaudi", "my-agent")'),
+  /** Human-readable display name */
+  name: z.string().min(1).max(50),
+  /** One-line role description */
+  role: z.string().min(1).max(100),
+  /** Longer description of capabilities */
+  description: z.string().min(10).max(500),
+  /** Knowledge domains (1–20) */
+  domains: z.array(z.string().min(1)).min(1).max(20),
+  /** Core principles (1–10) */
+  principles: z.array(z.string().min(1)).min(1).max(10),
+
+  // ─── Personality (optional) ─────────────────────
+  /** Communication tone */
+  tone: z.enum(TONES).optional().default('pragmatic'),
+  /** Greeting message (auto-generated if omitted) */
+  greeting: z.string().min(10).max(300).optional(),
+
+  // ─── Engine ─────────────────────────────────────
+  /** Knowledge engine configuration */
+  engine: EngineConfigSchema.optional().default({}),
+
+  // ─── Vault Connections ──────────────────────────
+  /** Link to external vaults for shared knowledge */
+  vaults: z.array(VaultConnectionSchema).optional(),
+
+  // ─── Client Setup ──────────────────────────────
+  /** LLM client integration settings */
+  setup: SetupConfigSchema.optional().default({}),
+
+  // ─── Domain Packs ──────────────────────────────
+  /** npm domain packs with custom ops and knowledge */
+  packs: z.array(DomainPackSchema).optional(),
+});
+
+export type AgentYaml = z.infer<typeof AgentYamlSchema>;
+export type AgentYamlInput = z.input<typeof AgentYamlSchema>;
+export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
+export type WorkflowGate = z.infer<typeof WorkflowGateSchema>;
+export type WorkflowTaskTemplate = z.infer<typeof WorkflowTaskTemplateSchema>;