@studio-foundation/engine 0.3.0-beta.1

package/src/pipeline/invariants-loader.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadInvariantsFile } from './invariants-loader.js';
+
+const TMP = join('/tmp', '.studio-invariants-loader-test-' + Date.now());
+const INVARIANTS_PATH = join(TMP, 'invariants.md');
+
+describe('loadInvariantsFile', () => {
+  beforeAll(async () => {
+    await mkdir(TMP, { recursive: true });
+    await writeFile(INVARIANTS_PATH, '# Domain Invariants\n\nNever reproduce verbatim passages.');
+  });
+
+  afterAll(async () => {
+    await rm(TMP, { recursive: true, force: true });
+  });
+
+  it('returns file content when invariants.md exists', async () => {
+    const content = await loadInvariantsFile(TMP);
+    expect(content).toBe('# Domain Invariants\n\nNever reproduce verbatim passages.');
+  });
+
+  it('returns undefined when invariants.md does not exist', async () => {
+    const content = await loadInvariantsFile('/tmp/no-such-studio-dir-xyz');
+    expect(content).toBeUndefined();
+  });
+});
+
+describe('invariants content is suitable for system_prompt injection', () => {
+  it('non-empty content can be concatenated into a system_prompt string', async () => {
+    const dir = join('/tmp', '.studio-invariants-integration-' + Date.now());
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, 'invariants.md'),
+      '## Invariants\n\n- Never hallucinate entity names\n- Cite sources'
+    );
+
+    const content = await loadInvariantsFile(dir);
+
+    expect(content).toBeDefined();
+    expect(typeof content).toBe('string');
+    expect(content!.length).toBeGreaterThan(0);
+
+    const systemPrompt = `You are an agent.\n\n---\n\n## Project Invariants\n\n${content}`;
+    expect(systemPrompt).toContain('Never hallucinate entity names');
+    expect(systemPrompt).toContain('## Project Invariants');
+
+    await rm(dir, { recursive: true, force: true });
+  });
+});

package/src/pipeline/invariants-loader.ts

@@ -0,0 +1,14 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Load `.studio/invariants.md` from the project directory.
+ * Returns content if the file exists, undefined otherwise (non-fatal).
+ */
+export async function loadInvariantsFile(projectDir: string): Promise<string | undefined> {
+  try {
+    return await readFile(join(projectDir, 'invariants.md'), 'utf-8');
+  } catch {
+    return undefined;
+  }
+}

package/src/pipeline/loader.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from 'vitest';
+import { parsePipelineYaml } from './loader.js';
+import type { StageDefinition } from '@studio-foundation/contracts';
+
+const MINIMAL_STAGE = `
+  - name: analyze
+    kind: analysis
+    agent: analyst
+`;
+
+describe('parsePipelineYaml — on_pipeline_start', () => {
+  it('parses on_pipeline_start commands', () => {
+    const yaml = `
+name: test-pipeline
+description: test
+version: 1
+on_pipeline_start:
+  - command: "git status --short"
+    inject_as: git_status
+  - command: "git log --oneline -5"
+    inject_as: recent_commits
+stages:
+${MINIMAL_STAGE}
+`;
+    const result = parsePipelineYaml(yaml);
+    expect(result.on_pipeline_start).toEqual([
+      { command: 'git status --short', inject_as: 'git_status' },
+      { command: 'git log --oneline -5', inject_as: 'recent_commits' },
+    ]);
+  });
+
+  it('returns undefined on_pipeline_start when absent', () => {
+    const yaml = `
+name: test-pipeline
+description: test
+version: 1
+stages:
+${MINIMAL_STAGE}
+`;
+    const result = parsePipelineYaml(yaml);
+    expect(result.on_pipeline_start).toBeUndefined();
+  });
+
+  it('throws when on_pipeline_start entry is missing command', () => {
+    const yaml = `
+name: test-pipeline
+description: test
+version: 1
+on_pipeline_start:
+  - inject_as: git_status
+stages:
+${MINIMAL_STAGE}
+`;
+    expect(() => parsePipelineYaml(yaml)).toThrow("on_pipeline_start entry missing 'command'");
+  });
+
+  it('throws when on_pipeline_start entry is missing inject_as', () => {
+    const yaml = `
+name: test-pipeline
+description: test
+version: 1
+on_pipeline_start:
+  - command: "git status"
+stages:
+${MINIMAL_STAGE}
+`;
+    expect(() => parsePipelineYaml(yaml)).toThrow("on_pipeline_start entry missing 'inject_as'");
+  });
+});
+
+const PIPELINE_WITH_HOOKS = `
+name: test-pipeline
+description: test
+version: 1
+stages:
+  - name: code-gen
+    kind: code
+    agent: coder
+    hooks:
+      on_stage_start:
+        - command: "git stash"
+          on_failure: warn
+      on_stage_complete:
+        - command: "npx tsc --noEmit"
+          on_failure: reject
+      pre_tool_use:
+        - matcher: "repo_manager-write_file"
+          command: "echo pre {{tool.path}}"
+          on_failure: warn
+      post_tool_use:
+        - matcher: "repo_manager-write_file"
+          command: "npx prettier --write {{tool.path}}"
+          on_failure: warn
+`;
+
+describe('parsePipelineYaml — stage hooks', () => {
+  it('parses all four hook types from a stage', () => {
+    const result = parsePipelineYaml(PIPELINE_WITH_HOOKS);
+    const stage = result.stages[0] as StageDefinition;
+    expect(stage.hooks?.on_stage_start).toEqual([
+      { command: 'git stash', on_failure: 'warn' },
+    ]);
+    expect(stage.hooks?.on_stage_complete).toEqual([
+      { command: 'npx tsc --noEmit', on_failure: 'reject' },
+    ]);
+    expect(stage.hooks?.pre_tool_use).toEqual([
+      { matcher: 'repo_manager-write_file', command: 'echo pre {{tool.path}}', on_failure: 'warn' },
+    ]);
+    expect(stage.hooks?.post_tool_use).toEqual([
+      { matcher: 'repo_manager-write_file', command: 'npx prettier --write {{tool.path}}', on_failure: 'warn' },
+    ]);
+  });
+
+  it('returns undefined hooks when stage has no hooks', () => {
+    const yaml = `
+name: test-pipeline
+description: test
+version: 1
+stages:
+  - name: analyze
+    kind: analysis
+    agent: analyst
+`;
+    const result = parsePipelineYaml(yaml);
+    const stage = result.stages[0] as StageDefinition;
+    expect(stage.hooks).toBeUndefined();
+  });
+});

package/src/pipeline/loader.ts

@@ -0,0 +1,149 @@
+// Load pipeline definitions from YAML files
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as yaml from 'js-yaml';
+import type { PipelineDefinition, PipelineEntry, StageGroup, StageDefinition, StartupCommand, StageHooks } from '@studio-foundation/contracts';
+
+export async function loadPipeline(path: string): Promise<PipelineDefinition> {
+  let content: string;
+  try {
+    content = await readFile(path, 'utf-8');
+  } catch (err) {
+    throw new Error(`Failed to load pipeline at ${path}: ${(err as Error).message}`);
+  }
+
+  return parsePipelineYaml(content, path);
+}
+
+export async function loadPipelineByName(
+  name: string,
+  pipelinesDir: string
+): Promise<PipelineDefinition> {
+  const path = join(pipelinesDir, `${name}.pipeline.yaml`);
+  return loadPipeline(path);
+}
+
+export function parsePipelineYaml(yamlContent: string, sourcePath?: string): PipelineDefinition {
+  const parsed = yaml.load(yamlContent) as Record<string, unknown>;
+  const context = sourcePath ? ` (from ${sourcePath})` : '';
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`Invalid pipeline YAML: expected an object${context}`);
+  }
+
+  if (!parsed.name || typeof parsed.name !== 'string') {
+    throw new Error(`Pipeline missing required field 'name'${context}`);
+  }
+
+  if (!Array.isArray(parsed.stages)) {
+    throw new Error(`Pipeline missing required field 'stages'${context}`);
+  }
+
+  if (parsed.stages.length === 0) {
+    throw new Error(`Pipeline must have at least one stage${context}`);
+  }
+
+  const stages: PipelineEntry[] = [];
+  for (const entry of parsed.stages as any[]) {
+    if (entry.group) {
+      // Group entry
+      if (!Array.isArray(entry.stages) || entry.stages.length < 2) {
+        throw new Error(`Group '${entry.group}' must have at least 2 stages${context}`);
+      }
+      for (const s of entry.stages) {
+        validateStageFields(s, context);
+      }
+
+      const mode = entry.mode === 'parallel' ? 'parallel' : undefined;
+      let maxIterations: number = entry.max_iterations ?? 3;
+
+      if (mode === 'parallel' && maxIterations > 1) {
+        console.warn(
+          `[studio] parallel group '${entry.group}' has max_iterations > 1 — iterations are ignored in parallel mode, using 1`
+        );
+        maxIterations = 1;
+      }
+
+      stages.push({
+        group: entry.group,
+        max_iterations: maxIterations,
+        ...(mode ? { mode } : {}),
+        ...(entry.on_failure ? { on_failure: entry.on_failure } : {}),
+        stages: entry.stages.map((s: any) => ({ ...s, hooks: parseStageHooks(s) })),
+      } as StageGroup);
+    } else {
+      // Simple stage
+      validateStageFields(entry, context);
+      stages.push({ ...entry, hooks: parseStageHooks(entry) } as StageDefinition);
+    }
+  }
+
+  // Parse on_pipeline_start commands
+  let on_pipeline_start: StartupCommand[] | undefined;
+  if (Array.isArray(parsed.on_pipeline_start)) {
+    on_pipeline_start = [];
+    for (const cmd of parsed.on_pipeline_start as any[]) {
+      if (!cmd.command || typeof cmd.command !== 'string') {
+        throw new Error(`on_pipeline_start entry missing 'command'${context}`);
+      }
+      if (!cmd.inject_as || typeof cmd.inject_as !== 'string') {
+        throw new Error(`on_pipeline_start entry missing 'inject_as'${context}`);
+      }
+      on_pipeline_start.push({ command: cmd.command, inject_as: cmd.inject_as });
+    }
+    if (on_pipeline_start.length === 0) {
+      on_pipeline_start = undefined;
+    }
+  }
+
+  return {
+    ...parsed,
+    stages,
+    on_pipeline_start,
+  } as unknown as PipelineDefinition;
+}
+
+function parseStageHooks(entry: any): StageHooks | undefined {
+  if (!entry.hooks || typeof entry.hooks !== 'object') return undefined;
+  const h = entry.hooks;
+  const result: StageHooks = {};
+
+  if (Array.isArray(h.on_stage_start)) {
+    result.on_stage_start = h.on_stage_start.map((hk: any) => ({
+      command: String(hk.command ?? ''),
+      on_failure: hk.on_failure ?? 'warn',
+    }));
+  }
+  if (Array.isArray(h.on_stage_complete)) {
+    result.on_stage_complete = h.on_stage_complete.map((hk: any) => ({
+      command: String(hk.command ?? ''),
+      on_failure: hk.on_failure ?? 'warn',
+    }));
+  }
+  if (Array.isArray(h.pre_tool_use)) {
+    result.pre_tool_use = h.pre_tool_use.map((hk: any) => ({
+      matcher: String(hk.matcher ?? ''),
+      command: String(hk.command ?? ''),
+      on_failure: hk.on_failure ?? 'warn',
+    }));
+  }
+  if (Array.isArray(h.post_tool_use)) {
+    result.post_tool_use = h.post_tool_use.map((hk: any) => ({
+      matcher: String(hk.matcher ?? ''),
+      command: String(hk.command ?? ''),
+      on_failure: hk.on_failure ?? 'warn',
+    }));
+  }
+
+  const hasAny = result.on_stage_start || result.on_stage_complete
+    || result.pre_tool_use || result.post_tool_use;
+  return hasAny ? result : undefined;
+}
+
+function validateStageFields(stage: any, context: string): void {
+  if (!stage.name) throw new Error(`Stage missing 'name'${context}`);
+  if (!stage.kind && !stage.executor) throw new Error(`Stage '${stage.name}' missing 'kind'${context}`);
+  if (!stage.agent && stage.executor !== 'script') throw new Error(`Stage '${stage.name}' missing 'agent'${context}`);
+  if (stage.executor === 'script' && !stage.script) throw new Error(`Stage '${stage.name}' missing 'script' (required when executor: 'script')${context}`);
+}

package/src/pipeline/output-validator.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { validateOutput } from './output-validator.js';
+import type { OutputContract } from '@studio-foundation/contracts';
+
+const schemaOnlyContract: OutputContract = {
+  name: 'test-schema',
+  version: 1,
+  schema: { required_fields: ['summary', 'files_changed'] },
+};
+
+const toolCallContract: OutputContract = {
+  name: 'test-tool-calls',
+  version: 1,
+  schema: { required_fields: ['summary'] },
+  tool_calls: { minimum: 1, required_tools: ['repo_manager-write_file'] },
+};
+
+const postValidationContract: OutputContract = {
+  name: 'test-post-validation',
+  version: 1,
+  schema: { required_fields: ['status'] },
+  post_validation: {
+    rejection_detection: {
+      field: 'status',
+      approved_values: ['approved'],
+      rejected_values: ['rejected'],
+    },
+  },
+};
+
+describe('validateOutput', () => {
+  describe('schema validation', () => {
+    it('returns valid: true when all required fields are present', () => {
+      const result = validateOutput(schemaOnlyContract, { summary: 'ok', files_changed: ['a.ts'] });
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
+    it('returns valid: false with error when required field is missing', () => {
+      const result = validateOutput(schemaOnlyContract, { summary: 'ok' });
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain('Missing required field: files_changed');
+    });
+
+    it('returns valid: false when output is not an object', () => {
+      const result = validateOutput(schemaOnlyContract, 'not an object');
+      expect(result.valid).toBe(false);
+    });
+  });
+
+  describe('tool_calls validation', () => {
+    it('returns valid: false when minimum not met (empty tool_calls)', () => {
+      const result = validateOutput(toolCallContract, { summary: 'ok' }, []);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes('at least 1 successful tool call'))).toBe(true);
+    });
+
+    it('returns valid: false when required tool was not called', () => {
+      const result = validateOutput(
+        toolCallContract,
+        { summary: 'ok' },
+        [{ id: 'call-1', name: 'shell-run_command', arguments: {}, result: 'ok' }]
+      );
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes('repo_manager-write_file'))).toBe(true);
+    });
+
+    it('returns valid: true when required tool was called successfully', () => {
+      const result = validateOutput(
+        toolCallContract,
+        { summary: 'ok' },
+        [{ id: 'call-2', name: 'repo_manager-write_file', arguments: { path: 'a.ts' }, result: 'ok' }]
+      );
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+  });
+
+  describe('post_validation', () => {
+    it('accepted: true when approved value present', () => {
+      const result = validateOutput(postValidationContract, { status: 'approved' });
+      expect(result.valid).toBe(true);
+    });
+
+    it('accepted: false with rejection_reason when rejected value present', () => {
+      const result = validateOutput(postValidationContract, { status: 'rejected' });
+      expect(result.post_validation.accepted).toBe(false);
+      expect(result.post_validation.rejection_reason).toBeTruthy();
+    });
+
+    it('post_validation runs independently of schema validity', () => {
+      const result = validateOutput(
+        { ...postValidationContract, schema: { required_fields: ['summary', 'status'] } },
+        { status: 'rejected' }
+      );
+      expect(result.valid).toBe(false);
+      expect(result.post_validation.accepted).toBe(false);
+    });
+  });
+});

package/src/pipeline/output-validator.ts

@@ -0,0 +1,40 @@
+import type { OutputContract, ToolCall } from '@studio-foundation/contracts';
+import {
+  validateSchema,
+  validateToolCalls,
+  validateRequiredTools,
+  validateCountedTools,
+  validateToolGroups,
+} from '@studio-foundation/ralph';
+import { postValidate, type PostValidationResult } from './post-validator.js';
+
+export interface OutputValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  post_validation: PostValidationResult;
+}
+
+export function validateOutput(
+  contract: OutputContract,
+  output: unknown,
+  toolCalls: ToolCall[] = []
+): OutputValidationResult {
+  const results = [
+    validateSchema(output, contract),
+    validateToolCalls(toolCalls, contract.tool_calls),
+    validateRequiredTools(toolCalls, contract.tool_calls),
+    validateCountedTools(toolCalls, contract.tool_calls),
+    validateToolGroups(toolCalls, contract.tool_calls),
+  ];
+
+  const errors = results.flatMap(r => r.errors);
+  const warnings = results.flatMap(r => r.warnings);
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    post_validation: postValidate(output, contract),
+  };
+}

package/src/pipeline/post-validator.ts

@@ -0,0 +1,124 @@
+// Post-validation sémantique
+//
+// Vérifie le CONTENU de l'output après que ralph a validé le FORMAT.
+// Utilisé pour les stages avec une gate d'approbation — l'agent peut
+// retourner un JSON valide qui dit quand même "non".
+//
+// Configuré dans le contract YAML via la section "post_validation".
+
+import type { OutputContract } from '@studio-foundation/contracts';
+
+export interface PostValidationResult {
+  accepted: boolean;
+  rejection_reason?: string;
+  rejection_details?: string[];
+}
+
+export function postValidate(
+  output: unknown,
+  contract: OutputContract
+): PostValidationResult {
+  // No post_validation config → everything is accepted
+  if (!contract.post_validation?.rejection_detection) {
+    return { accepted: true };
+  }
+
+  const { field, approved_values, rejected_values, details_field, summary_field, reject_if_non_empty } =
+    contract.post_validation.rejection_detection;
+
+  if (!field) {
+    return { accepted: true };
+  }
+
+  // Extract field value from output
+  if (!output || typeof output !== 'object') {
+    return { accepted: true };
+  }
+
+  const o = output as Record<string, unknown>;
+  const actualValue = o[field];
+
+  if (typeof actualValue !== 'string') {
+    return { accepted: true };
+  }
+
+  // Check reject_if_non_empty before approved_values — a non-empty field always rejects
+  if (reject_if_non_empty) {
+    const fieldValue = o[reject_if_non_empty];
+    if (Array.isArray(fieldValue) && fieldValue.length > 0) {
+      const details = fieldValue
+        .map(item => {
+          if (typeof item === 'string') return item;
+          if (typeof item !== 'object' || item === null) return undefined;
+          const obj = item as Record<string, unknown>;
+          const text = obj.description ?? obj.issue ?? obj.message ?? obj.text ?? obj.error;
+          if (typeof text === 'string' && text.length > 0) return text;
+          return Object.values(obj).find((v): v is string => typeof v === 'string' && v.length > 0);
+        })
+        .filter((d): d is string => typeof d === 'string');
+
+      const summary = summary_field && typeof o[summary_field] === 'string'
+        ? (o[summary_field] as string)
+        : undefined;
+
+      return {
+        accepted: false,
+        rejection_reason: `Rejected: ${reject_if_non_empty} is non-empty (${fieldValue.length} items)${summary ? `. ${summary}` : ''}`,
+        rejection_details: details.length > 0 ? details : undefined,
+      };
+    }
+  }
+
+  // Check approved values (if specified)
+  if (approved_values?.length && approved_values.includes(actualValue)) {
+    return { accepted: true };
+  }
+
+  // Check rejected values (if specified)
+  if (rejected_values?.length && !rejected_values.includes(actualValue)) {
+    // Value is not in rejected list and no approved list matched → accept
+    if (!approved_values?.length) {
+      return { accepted: true };
+    }
+  }
+
+  // If we have approved_values and the value isn't in them → rejected
+  // If we have rejected_values and the value is in them → rejected
+
+  // Extract details from configured field
+  const details: string[] = [];
+  if (details_field) {
+    const detailsValue = o[details_field];
+    if (typeof detailsValue === 'string' && detailsValue.length > 0) {
+      details.push(detailsValue);
+    } else if (Array.isArray(detailsValue)) {
+      for (const item of detailsValue) {
+        if (typeof item === 'string') {
+          details.push(item);
+        } else if (typeof item === 'object' && item !== null) {
+          const obj = item as Record<string, unknown>;
+          const text = obj.description ?? obj.issue ?? obj.message ?? obj.text ?? obj.error;
+          if (typeof text === 'string' && text.length > 0) {
+            details.push(text);
+          } else {
+            const firstStr = Object.values(obj).find(
+              (v): v is string => typeof v === 'string' && v.length > 0
+            );
+            if (firstStr !== undefined) details.push(firstStr);
+          }
+        }
+      }
+    }
+  }
+
+  // Extract summary from configured field
+  const summary = summary_field && typeof o[summary_field] === 'string'
+    ? (o[summary_field] as string)
+    : undefined;
+
+  return {
+    accepted: false,
+    rejection_reason: `Rejected: ${field} = "${actualValue}" (expected: ${(approved_values ?? []).join(' or ')})${summary ? `. ${summary}` : ''}`,
+    rejection_details: details.length > 0 ? details : undefined,
+  };
+}

package/src/pipeline/skill-loader.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadSkillFiles } from './skill-loader.js';
+
+const TMP = join('/tmp', '.studio-skill-loader-test-' + Date.now());
+
+describe('loadSkillFiles', () => {
+  beforeAll(async () => {
+    await mkdir(TMP, { recursive: true });
+    await writeFile(join(TMP, 'git-workflow.skill.md'), '# Git Workflow\n\nAlways branch from main.');
+    await writeFile(join(TMP, 'code-conventions.skill.md'), '# Code Conventions\n\nUse camelCase.');
+  });
+
+  afterAll(async () => {
+    await rm(TMP, { recursive: true, force: true });
+  });
+
+  it('loads existing skill files by name', async () => {
+    const skills = await loadSkillFiles(['git-workflow', 'code-conventions'], TMP);
+    expect(skills).toHaveLength(2);
+    expect(skills[0]).toEqual({ name: 'git-workflow', content: '# Git Workflow\n\nAlways branch from main.' });
+    expect(skills[1]).toEqual({ name: 'code-conventions', content: '# Code Conventions\n\nUse camelCase.' });
+  });
+
+  it('skips missing skill files without throwing', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const skills = await loadSkillFiles(['git-workflow', 'nonexistent'], TMP);
+    expect(skills).toHaveLength(1);
+    expect(skills[0].name).toBe('git-workflow');
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('nonexistent'));
+    warnSpy.mockRestore();
+  });
+
+  it('returns empty array when names list is empty', async () => {
+    const skills = await loadSkillFiles([], TMP);
+    expect(skills).toHaveLength(0);
+  });
+
+  it('returns empty array when skills directory does not exist', async () => {
+    const skills = await loadSkillFiles(['git-workflow'], '/tmp/nonexistent-skills-dir-xyz-abc');
+    expect(skills).toHaveLength(0);
+  });
+});

package/src/pipeline/skill-loader.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface SkillContent {
+  name: string;
+  content: string;
+}
+
+/**
+ * Load `.skill.md` files by name from a skills directory.
+ * Missing files are skipped with a warning (non-fatal).
+ */
+export async function loadSkillFiles(
+  names: string[],
+  skillsDir: string
+): Promise<SkillContent[]> {
+  if (names.length === 0) return [];
+  if (!existsSync(skillsDir)) return [];
+
+  const results: SkillContent[] = [];
+  for (const name of names) {
+    const filePath = join(skillsDir, `${name}.skill.md`);
+    try {
+      const content = await readFile(filePath, 'utf-8');
+      results.push({ name, content });
+    } catch {
+      console.warn(`[studio] Skill '${name}' not found at ${filePath} — skipping.`);
+    }
+  }
+  return results;
+}