workspace-maxxing 0.1.0

package/tests/cli.test.ts

@@ -0,0 +1,109 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execSync } from 'child_process';
+
+describe('CLI', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'workspace-maxxing-cli-'));
+    fs.writeFileSync(path.join(tempDir, 'package.json'), '{}');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('shows help when no args provided', () => {
+    const output = execSync('node dist/index.js', {
+      cwd: path.join(__dirname, '..'),
+      encoding: 'utf-8',
+    });
+
+    expect(output).toContain('workspace-maxxing');
+    expect(output).toContain('--opencode');
+    expect(output).toContain('--claude');
+    expect(output).toContain('--copilot');
+    expect(output).toContain('--gemini');
+  });
+
+  it('shows help when --help flag is provided', () => {
+    const output = execSync('node dist/index.js --help', {
+      cwd: path.join(__dirname, '..'),
+      encoding: 'utf-8',
+    });
+
+    expect(output).toContain('workspace-maxxing');
+    expect(output).toContain('--opencode');
+  });
+
+  it('installs skill when --opencode flag is provided', () => {
+    const cliPath = path.join(__dirname, '..', 'dist', 'index.js');
+    const output = execSync(`node "${cliPath}" --opencode`, {
+      cwd: tempDir,
+      encoding: 'utf-8',
+      env: { ...process.env, WORKSPACE_MAXXING_TEMPLATES: path.join(__dirname, '..', 'templates') },
+    });
+
+    expect(output).toContain('installed');
+    expect(
+      fs.existsSync(path.join(tempDir, '.agents', 'skills', 'workspace-maxxing', 'SKILL.md')),
+    ).toBe(true);
+  });
+
+  it('installs to claude path when --claude flag is provided', () => {
+    const cliPath = path.join(__dirname, '..', 'dist', 'index.js');
+    const output = execSync(`node "${cliPath}" --claude`, {
+      cwd: tempDir,
+      encoding: 'utf-8',
+      env: { ...process.env, WORKSPACE_MAXXING_TEMPLATES: path.join(__dirname, '..', 'templates') },
+    });
+
+    expect(output).toContain('claude');
+    expect(
+      fs.existsSync(path.join(tempDir, '.claude', 'skills', 'SKILL.md')),
+    ).toBe(true);
+  });
+
+  it('installs to copilot path when --copilot flag is provided', () => {
+    const cliPath = path.join(__dirname, '..', 'dist', 'index.js');
+    const output = execSync(`node "${cliPath}" --copilot`, {
+      cwd: tempDir,
+      encoding: 'utf-8',
+      env: { ...process.env, WORKSPACE_MAXXING_TEMPLATES: path.join(__dirname, '..', 'templates') },
+    });
+
+    expect(output).toContain('copilot');
+    expect(
+      fs.existsSync(path.join(tempDir, '.github', 'copilot-instructions', 'SKILL.md')),
+    ).toBe(true);
+  });
+
+  it('installs to gemini path when --gemini flag is provided', () => {
+    const cliPath = path.join(__dirname, '..', 'dist', 'index.js');
+    const output = execSync(`node "${cliPath}" --gemini`, {
+      cwd: tempDir,
+      encoding: 'utf-8',
+      env: { ...process.env, WORKSPACE_MAXXING_TEMPLATES: path.join(__dirname, '..', 'templates') },
+    });
+
+    expect(output).toContain('gemini');
+    expect(
+      fs.existsSync(path.join(tempDir, '.gemini', 'skills', 'SKILL.md')),
+    ).toBe(true);
+  });
+
+  it('errors on unsupported flag', () => {
+    try {
+      execSync('node dist/index.js --unknown-flag', {
+        cwd: path.join(__dirname, '..'),
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      fail('Should have thrown');
+    } catch (error) {
+      expect(true).toBe(true);
+    }
+  });
+});

package/tests/dispatch-parallel.test.ts

@@ -0,0 +1,124 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { dispatchSkill, dispatchParallel, ParallelDispatchResult, ParallelInvocation } from '../src/scripts/dispatch';
+
+describe('parallel dispatch', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-parallel-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('dispatches multiple skills in parallel and aggregates results', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'validation'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'validation', 'SKILL.md'), '---\nname: validation\n---\n\nTest');
+
+    const invocations: ParallelInvocation[] = [
+      { skill: 'validation', batchId: 1, testCaseId: 'tc-001' },
+      { skill: 'validation', batchId: 1, testCaseId: 'tc-002' },
+    ];
+
+    const results = dispatchParallel(invocations, skillsDir);
+
+    expect(results).toHaveLength(2);
+    expect(results[0].status).toBe('passed');
+    expect(results[1].status).toBe('passed');
+  });
+
+  it('fails worker invocations when external runner is not configured', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'worker'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'worker', 'SKILL.md'), '---\nname: worker\n---\n\nTest');
+
+    const invocations: ParallelInvocation[] = [
+      { skill: 'worker', batchId: 1, testCaseId: 'tc-001' },
+      { skill: 'worker', batchId: 1, testCaseId: 'tc-002' },
+    ];
+
+    const results = dispatchParallel(invocations, skillsDir);
+
+    expect(results).toHaveLength(2);
+    expect(results[0].status).toBe('failed');
+    expect(results[1].status).toBe('failed');
+  });
+
+  it('includes batchId and testCaseId in results', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'validation'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'validation', 'SKILL.md'), '---\nname: validation\n---\n\nTest');
+
+    const invocations: ParallelInvocation[] = [
+      { skill: 'validation', batchId: 2, testCaseId: 'tc-003' },
+    ];
+
+    const results = dispatchParallel(invocations, skillsDir);
+
+    expect(results[0].batchId).toBe(2);
+    expect(results[0].testCaseId).toBe('tc-003');
+  });
+
+  it('handles missing skill gracefully in parallel mode', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(skillsDir, { recursive: true });
+
+    const invocations: ParallelInvocation[] = [
+      { skill: 'nonexistent', batchId: 1, testCaseId: 'tc-001' },
+    ];
+
+    const results = dispatchParallel(invocations, skillsDir);
+
+    expect(results[0].status).toBe('failed');
+  });
+
+  it('supports external runner mode for worker invocations', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'worker'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'worker', 'SKILL.md'), '---\nname: worker\n---\n\nTest');
+
+    const runnerPath = path.join(tempDir, 'parallel-runner.js');
+    fs.writeFileSync(
+      runnerPath,
+      [
+        'const args = process.argv.slice(2);',
+        'const skill = args[0];',
+        'const batchId = Number(args[1]);',
+        'const testCaseId = args[2];',
+        'console.log(JSON.stringify({',
+        '  skill,',
+        '  status: "passed",',
+        '  timestamp: "2026-04-08T00:00:00.000Z",',
+        '  findings: ["parallel runner executed"],',
+        '  recommendations: ["continue"],',
+        '  metrics: { executionTimeMs: 8 },',
+        '  nextSkill: "validation",',
+        '  batchId,',
+        '  testCaseId,',
+        '}));',
+      ].join('\n'),
+    );
+
+    const invocations: ParallelInvocation[] = [
+      { skill: 'worker', batchId: 3, testCaseId: 'tc-010' },
+      { skill: 'worker', batchId: 3, testCaseId: 'tc-011' },
+    ];
+
+    const runnerCommand = `"${process.execPath}" "${runnerPath}" {skill} {batchId} {testCaseId}`;
+    const results = dispatchParallel(invocations, skillsDir, {
+      workspacePath: tempDir,
+      runnerCommand,
+      runnerTimeoutSeconds: 10,
+    });
+
+    expect(results).toHaveLength(2);
+    expect(results[0].status).toBe('passed');
+    expect(results[1].status).toBe('passed');
+    expect(results[0].findings).toContain('parallel runner executed');
+    expect(results[1].testCaseId).toBe('tc-011');
+  });
+});

package/tests/dispatch.test.ts

@@ -0,0 +1,218 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { dispatchSkill, DispatchReport } from '../src/scripts/dispatch';
+
+describe('dispatchSkill', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('loads and returns report for a valid sub-skill', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'validation'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'validation', 'SKILL.md'), '---\nname: validation\ndescription: test\n---\n\n## Overview\nTest');
+
+    const result = dispatchSkill('validation', skillsDir);
+
+    expect(result.skill).toBe('validation');
+    expect(result.status).toBeDefined();
+    expect(result.timestamp).toBeDefined();
+  });
+
+  it('returns failed status for non-existent skill', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(skillsDir, { recursive: true });
+
+    const result = dispatchSkill('nonexistent', skillsDir);
+
+    expect(result.skill).toBe('nonexistent');
+    expect(result.status).toBe('failed');
+    expect(result.findings.length).toBeGreaterThan(0);
+  });
+
+  it('includes nextSkill recommendation in report', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'validation'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'validation', 'SKILL.md'), '---\nname: validation\ndescription: test\n---\n\n## Overview\nTest');
+
+    const result = dispatchSkill('validation', skillsDir);
+
+    expect(result.nextSkill).toBeDefined();
+  });
+
+  it('maps validation to prompt-engineering as next skill', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'validation'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'validation', 'SKILL.md'), '---\nname: validation\ndescription: test\n---\n\n## Overview\nTest');
+
+    const result = dispatchSkill('validation', skillsDir);
+
+    expect(result.nextSkill).toBe('prompt-engineering');
+  });
+
+  it('maps research to architecture as next skill', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'research'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'research', 'SKILL.md'), '---\nname: research\ndescription: test\n---\n\n## Overview\nTest');
+
+    const result = dispatchSkill('research', skillsDir);
+
+    expect(result.nextSkill).toBe('architecture');
+  });
+
+  it('fails worker dispatch when external runner is not configured', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'worker'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'worker', 'SKILL.md'), '---\nname: worker\ndescription: test\n---\n\n## Overview\nTest');
+
+    const result = dispatchSkill('worker', skillsDir);
+
+    expect(result.status).toBe('failed');
+    expect(result.findings.join(' ')).toContain('External sub-agent runner is required');
+  });
+
+  it('fails fixer dispatch when external runner is not configured', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'fixer'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'fixer', 'SKILL.md'), '---\nname: fixer\ndescription: test\n---\n\n## Overview\nTest');
+
+    const result = dispatchSkill('fixer', skillsDir);
+
+    expect(result.status).toBe('failed');
+    expect(result.findings.join(' ')).toContain('External sub-agent runner is required');
+  });
+
+  it('uses external runner command for worker skill when configured', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'worker'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'worker', 'SKILL.md'), '---\nname: worker\ndescription: test\n---\n\n## Overview\nTest');
+
+    const runnerPath = path.join(tempDir, 'runner.js');
+    fs.writeFileSync(
+      runnerPath,
+      [
+        'const skill = process.argv[2];',
+        'const batchId = Number(process.argv[3]);',
+        'const testCaseId = process.argv[4];',
+        'console.log(JSON.stringify({',
+        '  skill,',
+        '  status: "passed",',
+        '  timestamp: "2026-04-08T00:00:00.000Z",',
+        '  findings: ["external runner executed"],',
+        '  recommendations: ["continue"],',
+        '  metrics: { executionTimeMs: 12 },',
+        '  nextSkill: "validation",',
+        '  batchId,',
+        '  testCaseId,',
+        '}));',
+      ].join('\n'),
+    );
+
+    const runnerCommand = `"${process.execPath}" "${runnerPath}" {skill} {batchId} {testCaseId}`;
+
+    const result = dispatchSkill('worker', skillsDir, {
+      workspacePath: tempDir,
+      runnerCommand,
+      invocation: {
+        skill: 'worker',
+        batchId: 1,
+        testCaseId: 'tc-001',
+      },
+    });
+
+    expect(result.status).toBe('passed');
+    expect(result.findings).toContain('external runner executed');
+    expect(result.nextSkill).toBe('validation');
+  });
+
+  it('writes runner telemetry artifact for external worker dispatch', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'worker'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'worker', 'SKILL.md'), '---\nname: worker\ndescription: test\n---\n\n## Overview\nTest');
+
+    const runnerPath = path.join(tempDir, 'runner-telemetry.js');
+    fs.writeFileSync(
+      runnerPath,
+      [
+        'const skill = process.argv[2];',
+        'const batchId = Number(process.argv[3]);',
+        'const testCaseId = process.argv[4];',
+        'console.log(JSON.stringify({',
+        '  skill,',
+        '  status: "passed",',
+        '  timestamp: "2026-04-08T00:00:00.000Z",',
+        '  findings: ["runner telemetry"],',
+        '  recommendations: ["continue"],',
+        '  metrics: { executionTimeMs: 7 },',
+        '  nextSkill: "validation",',
+        '  batchId,',
+        '  testCaseId,',
+        '}));',
+      ].join('\n'),
+    );
+
+    const runnerCommand = `"${process.execPath}" "${runnerPath}" {skill} {batchId} {testCaseId}`;
+
+    const result = dispatchSkill('worker', skillsDir, {
+      workspacePath: tempDir,
+      runnerCommand,
+      invocation: {
+        skill: 'worker',
+        batchId: 1,
+        testCaseId: 'tc-telemetry',
+      },
+    });
+
+    expect(result.status).toBe('passed');
+
+    const runsDir = path.join(tempDir, '.agents', 'iteration', 'runs');
+    expect(fs.existsSync(runsDir)).toBe(true);
+    const telemetryFiles = fs.readdirSync(runsDir).filter((f) => f.endsWith('.json'));
+    expect(telemetryFiles.length).toBeGreaterThan(0);
+
+    const telemetry = JSON.parse(fs.readFileSync(path.join(runsDir, telemetryFiles[0]), 'utf-8'));
+    expect(telemetry.skill).toBe('worker');
+    expect(telemetry.status).toBe('passed');
+    expect(telemetry.batchId).toBe(1);
+    expect(telemetry.testCaseId).toBe('tc-telemetry');
+    expect(telemetry.commandTemplate).toContain('{skill}');
+    expect(typeof telemetry.durationMs).toBe('number');
+  });
+
+  it('returns failed status when external runner command fails', () => {
+    const skillsDir = path.join(tempDir, 'skills');
+    fs.mkdirSync(path.join(skillsDir, 'worker'), { recursive: true });
+    fs.writeFileSync(path.join(skillsDir, 'worker', 'SKILL.md'), '---\nname: worker\ndescription: test\n---\n\n## Overview\nTest');
+
+    const runnerPath = path.join(tempDir, 'failing-runner.js');
+    fs.writeFileSync(
+      runnerPath,
+      [
+        'console.error("runner failed");',
+        'process.exit(2);',
+      ].join('\n'),
+    );
+
+    const runnerCommand = `"${process.execPath}" "${runnerPath}"`;
+
+    const result = dispatchSkill('worker', skillsDir, {
+      workspacePath: tempDir,
+      runnerCommand,
+      invocation: {
+        skill: 'worker',
+        batchId: 2,
+        testCaseId: 'tc-002',
+      },
+    });
+
+    expect(result.status).toBe('failed');
+    expect(result.findings.join(' ')).toContain('runner failed');
+  });
+});

package/tests/fixer-skill.test.ts

@@ -0,0 +1,203 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('fixer sub-skill', () => {
+  const skillPath = path.join(__dirname, '..', 'templates', '.workspace-templates', 'skills', 'fixer', 'SKILL.md');
+  const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const parseInlineYamlArray = (value: string): string[] =>
+    value
+      .replace(/^\[/, '')
+      .replace(/\]$/, '')
+      .split(',')
+      .map((item) => item.trim().replace(/^['"]|['"]$/g, ''))
+      .filter((item) => item.length > 0);
+  const getSectionBody = (content: string, heading: string): string | null => {
+    const headingPattern = escapeRegExp(heading);
+    const sectionMatch = content.match(
+      new RegExp(`##\\s+${headingPattern}\\s*\\r?\\n([\\s\\S]*?)(?=\\r?\\n##\\s+|$)`, 'i'),
+    );
+
+    return sectionMatch ? sectionMatch[1] : null;
+  };
+
+  it('exists', () => {
+    expect(fs.existsSync(skillPath)).toBe(true);
+  });
+
+  it('has YAML frontmatter at the top with required keys', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+
+    expect(frontmatterMatch).not.toBeNull();
+
+    if (!frontmatterMatch) {
+      return;
+    }
+
+    const frontmatter = frontmatterMatch[1];
+
+    expect(frontmatter).toMatch(/^name:\s*fixer\s*$/m);
+
+    const descriptionMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    expect(descriptionMatch).not.toBeNull();
+    expect(descriptionMatch?.[1].trim()).not.toBe('');
+
+    const triggersLineMatch = frontmatter.match(/^triggers:\s*(.*)$/m);
+    expect(triggersLineMatch).not.toBeNull();
+
+    const triggersInlineValue = triggersLineMatch?.[1].trim() ?? '';
+    if (/^\[.*\]$/.test(triggersInlineValue)) {
+      const triggerItems = parseInlineYamlArray(triggersInlineValue);
+      expect(triggerItems.length).toBeGreaterThan(0);
+    } else {
+      expect(triggersInlineValue).toBe('');
+
+      const triggersBlockMatch = frontmatter.match(/^triggers:\s*\r?\n((?:\s*-\s+.+\r?\n?)*)/m);
+      expect(triggersBlockMatch).not.toBeNull();
+
+      const triggerItems = (triggersBlockMatch?.[1] ?? '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('- '))
+        .map((line) => line.replace(/^-\s+/, '').trim())
+        .filter((line) => line.length > 0);
+
+      expect(triggerItems.length).toBeGreaterThan(0);
+    }
+
+    const firstHeadingIndex = content.indexOf('\n## ');
+    expect(firstHeadingIndex).toBeGreaterThan(frontmatterMatch[0].length - 1);
+
+    const betweenFrontmatterAndFirstHeading = content
+      .slice(frontmatterMatch[0].length, firstHeadingIndex)
+      .trim();
+    expect(betweenFrontmatterAndFirstHeading).toBe('');
+  });
+
+  it('has required sections', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+
+    expect(content).toContain('## Overview');
+    expect(content).toContain('## When to Use');
+    expect(content).toContain('## When Not to Use');
+    expect(content).toContain('## The Iron Law');
+    expect(content).toContain('## The Process');
+    expect(content).toContain('## Anti-Rationalization Table');
+    expect(content).toContain('## Sub-Skill Dispatch');
+    expect(content).toContain('## Report Format');
+  });
+
+  it('has Iron Law section', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const ironLawSection = getSectionBody(content, 'The Iron Law');
+
+    expect(ironLawSection).not.toBeNull();
+
+    if (!ironLawSection) {
+      return;
+    }
+
+    expect(ironLawSection).toMatch(/NO BLIND RETRIES/i);
+    expect(ironLawSection).toMatch(/NO COSMETIC FIXES/i);
+    expect(ironLawSection).toMatch(/NO FIXING WHAT IS NOT BROKEN/i);
+    expect(ironLawSection).toMatch(/NO CLAIMING FIX WITHOUT RE-?VALIDATION/i);
+  });
+
+  it('captures core fixer process semantics without brittle paragraph matching', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const processSection = getSectionBody(content, 'The Process');
+
+    expect(processSection).not.toBeNull();
+
+    if (!processSection) {
+      return;
+    }
+
+    expect(processSection).toMatch(/root\s+cause[\s\S]{0,160}map[\s\S]{0,120}finding[\s\S]{0,120}defect/i);
+    expect(processSection).toMatch(/minimal\s+fix[\s\S]{0,160}change\s+only[\s\S]{0,120}needed/i);
+    expect(processSection).toMatch(/dispatch\s+validation[\s\S]{0,200}(after\s+fix|re-?validation)/i);
+  });
+
+  it('has Anti-Rationalization Table', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const antiRationalizationSection = getSectionBody(content, 'Anti-Rationalization Table');
+
+    expect(antiRationalizationSection).not.toBeNull();
+
+    if (!antiRationalizationSection) {
+      return;
+    }
+
+    expect(antiRationalizationSection).toContain('| Thought | Reality |');
+    expect(antiRationalizationSection).toMatch(/re-?run the worker logic/i);
+    expect(antiRationalizationSection).toMatch(/blind retries/i);
+    expect(antiRationalizationSection).toMatch(/fix other things while i am here/i);
+    expect(antiRationalizationSection).toMatch(/scope creep/i);
+  });
+
+  it('has Report Format section with required fixer report fields', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    expect(content.toLowerCase()).toContain('report format');
+
+    const reportJsonBlockMatch = content.match(/## Report Format[\s\S]*?```json\r?\n([\s\S]*?)\r?\n```/i);
+    expect(reportJsonBlockMatch).not.toBeNull();
+
+    if (!reportJsonBlockMatch) {
+      return;
+    }
+
+    const reportSample = JSON.parse(reportJsonBlockMatch[1]);
+
+    expect(reportSample).toEqual(
+      expect.objectContaining({
+        skill: 'fixer',
+        status: expect.any(String),
+        timestamp: expect.any(String),
+        testCaseId: expect.any(String),
+        batchId: expect.any(Number),
+        findings: expect.any(Array),
+        fixesApplied: expect.any(Array),
+        recommendations: expect.any(Array),
+        metrics: expect.any(Object),
+        nextSkill: 'validation',
+      }),
+    );
+
+    expect(reportSample.metrics).toEqual(
+      expect.objectContaining({
+        findingsAddressed: expect.any(Number),
+        fixesApplied: expect.any(Number),
+      }),
+    );
+  });
+
+  it('keeps Process report shape aligned with Report Format fields', () => {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    const processSection = getSectionBody(content, 'The Process');
+
+    expect(processSection).not.toBeNull();
+
+    if (!processSection) {
+      return;
+    }
+
+    expect(processSection).toMatch(/Write\s+report\.json/i);
+
+    const requiredFields = [
+      'skill',
+      'status',
+      'timestamp',
+      'testCaseId',
+      'batchId',
+      'findings',
+      'fixesApplied',
+      'recommendations',
+      'metrics',
+      'nextSkill',
+    ];
+
+    for (const field of requiredFields) {
+      expect(processSection).toMatch(new RegExp(`\\b${escapeRegExp(field)}\\b`, 'i'));
+    }
+  });
+});