popeye-cli 1.10.0 → 2.1.0

package/tests/pipeline/role-execution-adapter.test.ts

@@ -0,0 +1,299 @@
+/**
+ * Role Execution Adapter tests — context building, prompt injection, role detection.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  buildRoleExecutionContext,
+  executeWithRoleContext,
+  buildAllRoleContexts,
+} from '../../src/pipeline/role-execution-adapter.js';
+import type { RoleExecutionContext, ClaudeExecuteOptions } from '../../src/pipeline/role-execution-adapter.js';
+import type { ArtifactEntry, PipelineRole } from '../../src/pipeline/types.js';
+import { createDefaultPipelineState } from '../../src/pipeline/types.js';
+
+const TEST_DIR = join(process.cwd(), 'tmp-role-adapter-test');
+
+function makeMockSkill(role: string) {
+  return {
+    role,
+    systemPrompt: `You are ${role}. Follow best practices.`,
+    constraints: ['Stay in scope', 'Do not modify tests'],
+    tools: [],
+  };
+}
+
+function makeRolePlanArtifact(role: string): ArtifactEntry {
+  return {
+    id: `plan-${role}`,
+    type: 'role_plan',
+    phase: 'ROLE_PLANNING',
+    version: 1,
+    path: `docs/role-plans/${role}.md`,
+    sha256: 'abc123',
+    timestamp: new Date().toISOString(),
+    immutable: true,
+    content_type: 'markdown',
+    group_id: `group-${role}`,
+  };
+}
+
+beforeEach(() => {
+  mkdirSync(join(TEST_DIR, 'docs', 'role-plans'), { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});
+
+describe('buildRoleExecutionContext', () => {
+  it('should build context with role, system prompt, and task scope', () => {
+    const planContent = [
+      '# FRONTEND_PROGRAMMER Role Plan',
+      '## Tasks',
+      '- Build login page in src/app/login/',
+      '- Implement dashboard components',
+      '## Dependencies',
+      'Requires API contracts from BACKEND_PROGRAMMER.',
+    ].join('\n');
+    const artifact = makeRolePlanArtifact('FRONTEND_PROGRAMMER');
+    writeFileSync(join(TEST_DIR, artifact.path), planContent);
+
+    const ctx = buildRoleExecutionContext(
+      'FRONTEND_PROGRAMMER',
+      makeMockSkill('FRONTEND_PROGRAMMER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.role).toBe('FRONTEND_PROGRAMMER');
+    expect(ctx.systemPrompt).toContain('FRONTEND_PROGRAMMER');
+    expect(ctx.systemPrompt).toContain('You are FRONTEND_PROGRAMMER');
+    expect(ctx.taskScope).toContain('Build login page');
+    expect(ctx.allowedPaths.length).toBeGreaterThan(0);
+  });
+
+  it('should include forbidden patterns for frontend role', () => {
+    const artifact = makeRolePlanArtifact('FRONTEND_PROGRAMMER');
+    writeFileSync(join(TEST_DIR, artifact.path), '# FRONTEND_PROGRAMMER Plan\n## Tasks\n- UI work');
+
+    const ctx = buildRoleExecutionContext(
+      'FRONTEND_PROGRAMMER',
+      makeMockSkill('FRONTEND_PROGRAMMER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.forbiddenPatterns).toContain('server/');
+    expect(ctx.forbiddenPatterns).toContain('prisma/');
+  });
+
+  it('should include forbidden patterns in system prompt', () => {
+    const artifact = makeRolePlanArtifact('FRONTEND_PROGRAMMER');
+    writeFileSync(join(TEST_DIR, artifact.path), '# FRONTEND_PROGRAMMER Plan\n## Tasks\n- UI');
+
+    const ctx = buildRoleExecutionContext(
+      'FRONTEND_PROGRAMMER',
+      makeMockSkill('FRONTEND_PROGRAMMER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.systemPrompt).toContain('Forbidden Paths');
+    expect(ctx.systemPrompt).toContain('server/');
+  });
+
+  it('should have no forbidden patterns for QA_TESTER', () => {
+    const artifact = makeRolePlanArtifact('QA_TESTER');
+    writeFileSync(join(TEST_DIR, artifact.path), '# QA_TESTER Plan\n## Tasks\n- Test all');
+
+    const ctx = buildRoleExecutionContext(
+      'QA_TESTER',
+      makeMockSkill('QA_TESTER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.forbiddenPatterns).toEqual([]);
+    expect(ctx.systemPrompt).not.toContain('Forbidden Paths');
+  });
+
+  it('should include skill constraints in system prompt', () => {
+    const artifact = makeRolePlanArtifact('BACKEND_PROGRAMMER');
+    writeFileSync(join(TEST_DIR, artifact.path), '# BACKEND_PROGRAMMER Plan\n## Tasks\n- API');
+
+    const ctx = buildRoleExecutionContext(
+      'BACKEND_PROGRAMMER',
+      makeMockSkill('BACKEND_PROGRAMMER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.systemPrompt).toContain('Stay in scope');
+    expect(ctx.systemPrompt).toContain('Do not modify tests');
+  });
+
+  it('should extract file paths from plan content as allowed paths', () => {
+    const planContent = [
+      '# BACKEND_PROGRAMMER Plan',
+      '## Tasks',
+      '- Implement API routes in src/api/routes.ts',
+      '- Update server/middleware.ts',
+    ].join('\n');
+    const artifact = makeRolePlanArtifact('BACKEND_PROGRAMMER');
+    writeFileSync(join(TEST_DIR, artifact.path), planContent);
+
+    const ctx = buildRoleExecutionContext(
+      'BACKEND_PROGRAMMER',
+      makeMockSkill('BACKEND_PROGRAMMER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.allowedPaths).toContain('src/api/routes.ts');
+    expect(ctx.allowedPaths).toContain('server/middleware.ts');
+  });
+
+  it('should handle missing plan file gracefully', () => {
+    const artifact = makeRolePlanArtifact('BACKEND_PROGRAMMER');
+    // Don't write the file
+
+    const ctx = buildRoleExecutionContext(
+      'BACKEND_PROGRAMMER',
+      makeMockSkill('BACKEND_PROGRAMMER'),
+      artifact,
+      TEST_DIR,
+    );
+
+    expect(ctx.role).toBe('BACKEND_PROGRAMMER');
+    expect(ctx.taskScope).toBe('');
+    expect(ctx.systemPrompt).toContain('BACKEND_PROGRAMMER');
+  });
+});
+
+describe('executeWithRoleContext', () => {
+  it('should inject systemPrompt into options', () => {
+    const ctx: RoleExecutionContext = {
+      role: 'FRONTEND_PROGRAMMER',
+      systemPrompt: 'You are FRONTEND_PROGRAMMER. Build the UI.',
+      allowedPaths: ['src/'],
+      forbiddenPatterns: ['server/'],
+      taskScope: 'Build login page',
+    };
+
+    const options: ClaudeExecuteOptions = {
+      projectDir: '/test/project',
+    };
+
+    const result = executeWithRoleContext(ctx, options);
+    expect(result.systemPrompt).toBe('You are FRONTEND_PROGRAMMER. Build the UI.');
+    expect(result.projectDir).toBe('/test/project');
+  });
+
+  it('should override existing systemPrompt', () => {
+    const ctx: RoleExecutionContext = {
+      role: 'BACKEND_PROGRAMMER',
+      systemPrompt: 'Role-specific prompt',
+      allowedPaths: [],
+      forbiddenPatterns: [],
+      taskScope: '',
+    };
+
+    const options: ClaudeExecuteOptions = {
+      projectDir: '/test',
+      systemPrompt: 'Old prompt',
+    };
+
+    const result = executeWithRoleContext(ctx, options);
+    expect(result.systemPrompt).toBe('Role-specific prompt');
+  });
+
+  it('should preserve other options', () => {
+    const ctx: RoleExecutionContext = {
+      role: 'QA_TESTER',
+      systemPrompt: 'Test prompt',
+      allowedPaths: [],
+      forbiddenPatterns: [],
+      taskScope: '',
+    };
+
+    const options: ClaudeExecuteOptions = {
+      projectDir: '/test',
+      customField: 'preserved',
+    };
+
+    const result = executeWithRoleContext(ctx, options);
+    expect(result.customField).toBe('preserved');
+  });
+});
+
+describe('buildAllRoleContexts', () => {
+  it('should build contexts for all detected roles', () => {
+    const pipeline = createDefaultPipelineState();
+    pipeline.activeRoles = ['FRONTEND_PROGRAMMER', 'BACKEND_PROGRAMMER'];
+
+    // Create plan files
+    const fePlan = makeRolePlanArtifact('FRONTEND_PROGRAMMER');
+    const bePlan = makeRolePlanArtifact('BACKEND_PROGRAMMER');
+    pipeline.artifacts.push(fePlan, bePlan);
+
+    writeFileSync(
+      join(TEST_DIR, fePlan.path),
+      '# FRONTEND_PROGRAMMER Role Plan\n## Tasks\n- Build UI',
+    );
+    writeFileSync(
+      join(TEST_DIR, bePlan.path),
+      '# BACKEND_PROGRAMMER Role Plan\n## Tasks\n- Build API',
+    );
+
+    const mockSkillLoader = {
+      loadSkill: (role: string) => makeMockSkill(role),
+      listSkills: () => [],
+    };
+
+    const contexts = buildAllRoleContexts(pipeline, mockSkillLoader as any, TEST_DIR);
+    expect(contexts.size).toBe(2);
+    expect(contexts.has('FRONTEND_PROGRAMMER')).toBe(true);
+    expect(contexts.has('BACKEND_PROGRAMMER')).toBe(true);
+  });
+
+  it('should skip roles with missing plan files', () => {
+    const pipeline = createDefaultPipelineState();
+    pipeline.activeRoles = ['FRONTEND_PROGRAMMER', 'BACKEND_PROGRAMMER'];
+
+    const fePlan = makeRolePlanArtifact('FRONTEND_PROGRAMMER');
+    pipeline.artifacts.push(fePlan);
+
+    // Only write FE plan, not BE
+    writeFileSync(
+      join(TEST_DIR, fePlan.path),
+      '# FRONTEND_PROGRAMMER Role Plan\n## Tasks\n- Build UI',
+    );
+
+    const mockSkillLoader = {
+      loadSkill: (role: string) => makeMockSkill(role),
+      listSkills: () => [],
+    };
+
+    const contexts = buildAllRoleContexts(pipeline, mockSkillLoader as any, TEST_DIR);
+    expect(contexts.size).toBe(1);
+    expect(contexts.has('FRONTEND_PROGRAMMER')).toBe(true);
+  });
+
+  it('should return empty map when no role plans exist', () => {
+    const pipeline = createDefaultPipelineState();
+    pipeline.activeRoles = ['FRONTEND_PROGRAMMER'];
+
+    const mockSkillLoader = {
+      loadSkill: (role: string) => makeMockSkill(role),
+      listSkills: () => [],
+    };
+
+    const contexts = buildAllRoleContexts(pipeline, mockSkillLoader as any, TEST_DIR);
+    expect(contexts.size).toBe(0);
+  });
+});

package/tests/pipeline/session-guidance.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Fix A tests — sessionGuidance threading through pipeline.
+ * Verifies additionalContext persists in PipelineState and reaches phases.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createDefaultPipelineState,
+  PipelineStateSchema,
+  ArtifactTypeSchema,
+} from '../../src/pipeline/types.js';
+
+describe('Fix A: sessionGuidance threading', () => {
+  describe('PipelineState.sessionGuidance', () => {
+    it('should accept sessionGuidance in pipeline state', () => {
+      const state = createDefaultPipelineState();
+      state.sessionGuidance = 'Upgrade from v1 to v2: preserve API backwards compat';
+
+      const result = PipelineStateSchema.safeParse(state);
+      expect(result.success).toBe(true);
+      expect(result.data?.sessionGuidance).toBe(
+        'Upgrade from v1 to v2: preserve API backwards compat',
+      );
+    });
+
+    it('should allow omitting sessionGuidance (backward compat)', () => {
+      const state = createDefaultPipelineState();
+      // No sessionGuidance set
+
+      const result = PipelineStateSchema.safeParse(state);
+      expect(result.success).toBe(true);
+      expect(result.data?.sessionGuidance).toBeUndefined();
+    });
+
+    it('should allow empty string for sessionGuidance', () => {
+      const state = createDefaultPipelineState();
+      state.sessionGuidance = '';
+
+      const result = PipelineStateSchema.safeParse(state);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('additional_context artifact type', () => {
+    it('should accept additional_context as valid artifact type', () => {
+      const result = ArtifactTypeSchema.safeParse('additional_context');
+      expect(result.success).toBe(true);
+    });
+
+    it('should still accept all existing artifact types', () => {
+      const existingTypes = [
+        'master_plan', 'architecture', 'role_plan', 'consensus',
+        'arbitration', 'audit_report', 'rca_report', 'production_readiness',
+        'change_request',
+      ];
+
+      for (const type of existingTypes) {
+        expect(ArtifactTypeSchema.safeParse(type).success).toBe(true);
+      }
+    });
+  });
+
+  describe('PipelineOptions additionalContext -> sessionGuidance', () => {
+    it('should store additionalContext in pipeline state when not already set', () => {
+      const pipeline = createDefaultPipelineState();
+      const additionalContext = 'Focus on mobile-first responsive design';
+
+      // Simulates orchestrator logic
+      if (additionalContext && !pipeline.sessionGuidance) {
+        pipeline.sessionGuidance = additionalContext;
+      }
+
+      expect(pipeline.sessionGuidance).toBe('Focus on mobile-first responsive design');
+    });
+
+    it('should not overwrite existing sessionGuidance on resume', () => {
+      const pipeline = createDefaultPipelineState();
+      pipeline.sessionGuidance = 'Original guidance from first run';
+      const additionalContext = 'New guidance on resume';
+
+      // Simulates orchestrator logic
+      if (additionalContext && !pipeline.sessionGuidance) {
+        pipeline.sessionGuidance = additionalContext;
+      }
+
+      expect(pipeline.sessionGuidance).toBe('Original guidance from first run');
+    });
+
+    it('should leave sessionGuidance undefined when no additionalContext', () => {
+      const pipeline = createDefaultPipelineState();
+      const additionalContext: string | undefined = undefined;
+
+      if (additionalContext && !pipeline.sessionGuidance) {
+        pipeline.sessionGuidance = additionalContext;
+      }
+
+      expect(pipeline.sessionGuidance).toBeUndefined();
+    });
+  });
+
+  describe('INTAKE phase guidance injection', () => {
+    it('should prepend guidance to plan input when provided', () => {
+      const guidance = 'Upgrade context: migrate from Express to Fastify';
+      const expandedIdea = 'Build a REST API with user authentication';
+
+      const planInput = guidance
+        ? `${guidance}\n\n---\n\n${expandedIdea}`
+        : expandedIdea;
+
+      expect(planInput).toContain(guidance);
+      expect(planInput).toContain('---');
+      expect(planInput).toContain(expandedIdea);
+      expect(planInput.indexOf(guidance)).toBeLessThan(planInput.indexOf(expandedIdea));
+    });
+
+    it('should pass through expandedIdea unchanged when no guidance', () => {
+      const guidance = '';
+      const expandedIdea = 'Build a REST API with user authentication';
+
+      const planInput = guidance
+        ? `${guidance}\n\n---\n\n${expandedIdea}`
+        : expandedIdea;
+
+      expect(planInput).toBe(expandedIdea);
+    });
+  });
+
+  describe('IMPLEMENTATION phase guidance injection', () => {
+    it('should merge role prompt with guidance', () => {
+      const combinedRolePrompt = '## BACKEND_PROGRAMMER\nScope: API endpoints';
+      const guidance = 'Preserve backwards compatibility with v1 API';
+
+      const systemPrompt = [combinedRolePrompt, guidance].filter(Boolean).join('\n\n') || undefined;
+
+      expect(systemPrompt).toContain(combinedRolePrompt);
+      expect(systemPrompt).toContain(guidance);
+    });
+
+    it('should use only role prompt when no guidance', () => {
+      const combinedRolePrompt = '## BACKEND_PROGRAMMER\nScope: API endpoints';
+      const guidance: string | undefined = undefined;
+
+      const systemPrompt = [combinedRolePrompt, guidance].filter(Boolean).join('\n\n') || undefined;
+
+      expect(systemPrompt).toBe(combinedRolePrompt);
+    });
+
+    it('should use only guidance when no role prompt', () => {
+      const combinedRolePrompt = '';
+      const guidance = 'Focus on performance';
+
+      const systemPrompt = [combinedRolePrompt, guidance].filter(Boolean).join('\n\n') || undefined;
+
+      expect(systemPrompt).toBe(guidance);
+    });
+
+    it('should return undefined when neither role prompt nor guidance', () => {
+      const combinedRolePrompt = '';
+      const guidance: string | undefined = undefined;
+
+      const systemPrompt = [combinedRolePrompt, guidance].filter(Boolean).join('\n\n') || undefined;
+
+      expect(systemPrompt).toBeUndefined();
+    });
+  });
+
+  describe('RECOVERY_LOOP guidance in RCA prompt', () => {
+    it('should include user guidance in RCA prompt when available', () => {
+      const debuggerPrompt = 'You are a debugger agent...';
+      const guidance = 'User wants API backwards compat preserved';
+      const failureEvidence = 'Failed phase: QA_VALIDATION';
+
+      const rcaPrompt = [
+        debuggerPrompt,
+        '',
+        ...(guidance ? ['## User Guidance', guidance, ''] : []),
+        '## Failure Evidence',
+        failureEvidence,
+      ].join('\n');
+
+      expect(rcaPrompt).toContain('## User Guidance');
+      expect(rcaPrompt).toContain(guidance);
+      expect(rcaPrompt.indexOf('User Guidance')).toBeLessThan(
+        rcaPrompt.indexOf('Failure Evidence'),
+      );
+    });
+
+    it('should omit User Guidance section when no guidance', () => {
+      const debuggerPrompt = 'You are a debugger agent...';
+      const guidance: string | undefined = undefined;
+      const failureEvidence = 'Failed phase: QA_VALIDATION';
+
+      const rcaPrompt = [
+        debuggerPrompt,
+        '',
+        ...(guidance ? ['## User Guidance', guidance, ''] : []),
+        '## Failure Evidence',
+        failureEvidence,
+      ].join('\n');
+
+      expect(rcaPrompt).not.toContain('## User Guidance');
+      expect(rcaPrompt).toContain('## Failure Evidence');
+    });
+  });
+});

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

@@ -0,0 +1,186 @@
+/**
+ * Skill Loader tests — frontmatter parsing, raw fallback, merge, caching.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  SkillLoader,
+  parseSkillMarkdown,
+  getDefaultSkill,
+  createSkillLoader,
+} from '../../src/pipeline/skill-loader.js';
+
+const TEST_DIR = join(process.cwd(), '.test-skill-loader');
+const SKILLS_DIR = join(TEST_DIR, 'skills');
+
+describe('SkillLoader', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+    mkdirSync(SKILLS_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+  });
+
+  describe('parseSkillMarkdown', () => {
+    it('should parse frontmatter with body', () => {
+      const md = `---
+role: ARCHITECT
+version: 2.0
+required_outputs:
+  - architecture_doc
+  - api_contracts
+constraints:
+  - no implementation details
+  - all contracts explicit
+---
+# System Prompt
+You are the Architect responsible for system design.`;
+
+      const result = parseSkillMarkdown(md);
+      expect(result.role).toBe('ARCHITECT');
+      expect(result.version).toBe('2.0');
+      expect(result.required_outputs).toEqual(['architecture_doc', 'api_contracts']);
+      expect(result.constraints).toEqual(['no implementation details', 'all contracts explicit']);
+      expect(result.systemPrompt).toContain('You are the Architect');
+    });
+
+    it('should treat entire content as systemPrompt when no frontmatter', () => {
+      const md = 'You are a specialized reviewer.\nReview all code carefully.';
+      const result = parseSkillMarkdown(md);
+
+      expect(result.systemPrompt).toBe(md);
+      expect(result.role).toBeUndefined();
+      expect(result.version).toBeUndefined();
+    });
+
+    it('should handle frontmatter with scalar values', () => {
+      const md = `---
+role: DEBUGGER
+version: 1.5
+---
+Debug the issue.`;
+
+      const result = parseSkillMarkdown(md);
+      expect(result.role).toBe('DEBUGGER');
+      expect(result.version).toBe('1.5');
+      expect(result.systemPrompt).toBe('Debug the issue.');
+    });
+
+    it('should handle empty body after frontmatter', () => {
+      const md = `---
+role: QA_TESTER
+version: 1.0
+---
+`;
+
+      const result = parseSkillMarkdown(md);
+      expect(result.role).toBe('QA_TESTER');
+      expect(result.systemPrompt).toBeUndefined();
+    });
+  });
+
+  describe('getDefaultSkill', () => {
+    it('should return a valid skill for known roles', () => {
+      const skill = getDefaultSkill('ARCHITECT');
+      expect(skill.role).toBe('ARCHITECT');
+      expect(skill.systemPrompt).toBeDefined();
+      expect(skill.systemPrompt.length).toBeGreaterThan(0);
+      expect(Array.isArray(skill.required_outputs)).toBe(true);
+      expect(Array.isArray(skill.constraints)).toBe(true);
+    });
+
+    it('should return fallback for unknown roles', () => {
+      const skill = getDefaultSkill('NONEXISTENT' as any);
+      expect(skill.role).toBe('NONEXISTENT');
+      expect(skill.systemPrompt).toContain('NONEXISTENT');
+    });
+  });
+
+  describe('SkillLoader class', () => {
+    it('should load default skills when no override exists', () => {
+      const loader = new SkillLoader(SKILLS_DIR);
+      const skill = loader.loadSkill('ARCHITECT');
+
+      expect(skill.role).toBe('ARCHITECT');
+      expect(skill.systemPrompt).toBeDefined();
+    });
+
+    it('should merge .md override with default', () => {
+      writeFileSync(join(SKILLS_DIR, 'ARCHITECT.md'), `---
+version: 3.0
+constraints:
+  - custom constraint
+---
+Custom architect prompt.`);
+
+      const loader = new SkillLoader(SKILLS_DIR);
+      const skill = loader.loadSkill('ARCHITECT');
+
+      expect(skill.role).toBe('ARCHITECT');
+      expect(skill.version).toBe('3.0');
+      expect(skill.systemPrompt).toBe('Custom architect prompt.');
+      expect(skill.constraints).toEqual(['custom constraint']);
+    });
+
+    it('should cache loaded skills', () => {
+      const loader = new SkillLoader(SKILLS_DIR);
+      const s1 = loader.loadSkill('DEBUGGER');
+      const s2 = loader.loadSkill('DEBUGGER');
+      expect(s1).toBe(s2); // Same reference = cached
+    });
+
+    it('should clear cache', () => {
+      const loader = new SkillLoader(SKILLS_DIR);
+      const s1 = loader.loadSkill('DEBUGGER');
+      loader.clearCache();
+      const s2 = loader.loadSkill('DEBUGGER');
+      expect(s1).not.toBe(s2); // Different reference after cache clear
+    });
+
+    it('should load all skills for given roles', () => {
+      const loader = new SkillLoader(SKILLS_DIR);
+      const skills = loader.loadAllSkills(['ARCHITECT', 'DEBUGGER', 'QA_TESTER']);
+
+      expect(skills.size).toBe(3);
+      expect(skills.has('ARCHITECT')).toBe(true);
+      expect(skills.has('DEBUGGER')).toBe(true);
+      expect(skills.has('QA_TESTER')).toBe(true);
+    });
+
+    it('should list available overrides', () => {
+      writeFileSync(join(SKILLS_DIR, 'ARCHITECT.md'), 'prompt');
+      writeFileSync(join(SKILLS_DIR, 'REVIEWER.md'), 'prompt');
+
+      const loader = new SkillLoader(SKILLS_DIR);
+      const overrides = loader.listAvailableOverrides();
+
+      expect(overrides).toContain('ARCHITECT');
+      expect(overrides).toContain('REVIEWER');
+    });
+
+    it('should handle no skills directory gracefully', () => {
+      const loader = new SkillLoader('/nonexistent/path');
+      const skill = loader.loadSkill('ARCHITECT');
+
+      // Falls back to default
+      expect(skill.role).toBe('ARCHITECT');
+      expect(skill.systemPrompt).toBeDefined();
+    });
+  });
+
+  describe('createSkillLoader', () => {
+    it('should create loader with skills dir', () => {
+      const loader = createSkillLoader(TEST_DIR);
+      expect(loader).toBeInstanceOf(SkillLoader);
+    });
+
+    it('should create loader without project dir', () => {
+      const loader = createSkillLoader();
+      expect(loader).toBeInstanceOf(SkillLoader);
+    });
+  });
+});