@vitronai/themis 0.1.15 → 1.2.1

package/src/cli.js

@@ -24,13 +24,54 @@ async function main(argv) {
     const initFlags = parseInitFlags(argv.slice(1));
     const initResult = runInit(cwd, initFlags);
     console.log('Themis initialized. Next: npx themis generate <source-root> && npx themis test');
-    if (initFlags.agents) {
-      if (initResult && initResult.path && initResult.created) {
-        console.log(`Agents: created ${formatCliPath(cwd, initResult.path)} from the Themis downstream template.`);
+    if (initResult.autoDetected) {
+      const detected = [];
+      if (initResult.agents) detected.push('AGENTS.md');
+      if (initResult.claudeCode) detected.push('Claude Code');
+      if (initResult.cursor) detected.push('Cursor');
+      if (detected.length > 0) {
+        console.log(`Auto-detected: ${detected.join(', ')}`);
+      }
+    }
+    if (initFlags.agents || initResult.agents) {
+      const agents = initResult.agents;
+      if (agents && agents.created) {
+        console.log(`Agents: created ${formatCliPath(cwd, agents.path)} from the Themis downstream template.`);
       } else {
         console.log('Agents: skipped AGENTS.md scaffold because one already exists.');
       }
     }
+    if (initResult.cursor) {
+      const cur = initResult.cursor;
+      if (cur.created) {
+        console.log(`Cursor: created ${formatCliPath(cwd, cur.path)} from the Themis Cursor template.`);
+      } else if (cur.appended) {
+        console.log(`Cursor: appended Themis section to ${formatCliPath(cwd, cur.path)}.`);
+      } else {
+        console.log(`Cursor: skipped .cursorrules update (already mentions @vitronai/themis).`);
+      }
+    }
+    if (initResult.claudeCode) {
+      const cc = initResult.claudeCode;
+      if (cc.claudeMd.created) {
+        console.log(`Claude Code: created ${formatCliPath(cwd, cc.claudeMd.path)} from the Themis Claude template.`);
+      } else if (cc.claudeMd.appended) {
+        console.log(`Claude Code: appended Themis section to ${formatCliPath(cwd, cc.claudeMd.path)}.`);
+      } else {
+        console.log(`Claude Code: skipped CLAUDE.md update (already mentions @vitronai/themis).`);
+      }
+      if (cc.skill.created) {
+        console.log(`Claude Code: installed skill at ${formatCliPath(cwd, cc.skill.path)}.`);
+      } else {
+        console.log(`Claude Code: skipped skill (${formatCliPath(cwd, cc.skill.path)} already exists).`);
+      }
+      if (cc.commands.written.length > 0) {
+        console.log(`Claude Code: installed ${cc.commands.written.length} slash command(s) under ${formatCliPath(cwd, cc.commands.dir)}.`);
+      }
+      if (cc.commands.skipped.length > 0) {
+        console.log(`Claude Code: skipped ${cc.commands.skipped.length} existing slash command file(s).`);
+      }
+    }
     return;
   }
 
@@ -95,6 +136,17 @@ async function main(argv) {
     if (result.convertedFiles && result.convertedFiles.length > 0) {
       console.log(`Codemods: converted ${result.convertedFiles.length} file(s) to Themis-native patterns.`);
     }
+    if (result.assist) {
+      console.log(`Assistant: analyzed ${result.assistSummary.analyzedFiles} migrated file(s).`);
+      if (result.assistSummary.findings.length > 0) {
+        console.log(
+          `Assistant: flagged ${result.assistSummary.findings.length} manual follow-up item(s) across ${result.assistSummary.unresolvedFiles.length} file(s).`
+        );
+      } else {
+        console.log('Assistant: no unsupported Jest/Vitest-only patterns detected in migrated files.');
+      }
+      console.log(`Report: ${formatCliPath(cwd, result.reportPath)}`);
+    }
     console.log('Runtime compatibility is enabled for @jest/globals, vitest, and @testing-library/react imports.');
     console.log('Next: run npx themis test or npm run test:themis');
     return;
@@ -500,7 +552,8 @@ function parseMigrateFlags(args) {
   const flags = {
     source: args[0],
     rewriteImports: false,
-    convert: false
+    convert: false,
+    assist: false
   };
 
   for (let i = 1; i < args.length; i += 1) {
@@ -511,6 +564,16 @@ function parseMigrateFlags(args) {
     }
     if (token === '--convert') {
       flags.convert = true;
+      continue;
+    }
+    if (token === '--assist') {
+      flags.assist = true;
+      flags.rewriteImports = true;
+      flags.convert = true;
+      continue;
+    }
+    if (token.startsWith('-')) {
+      throw new Error(`Unsupported migrate option: ${token}`);
     }
   }
 
@@ -519,7 +582,9 @@ function parseMigrateFlags(args) {
 
 function parseInitFlags(args) {
   const flags = {
-    agents: false
+    agents: false,
+    claudeCode: false,
+    cursor: false
   };
 
   for (let i = 0; i < args.length; i += 1) {
@@ -528,6 +593,14 @@ function parseInitFlags(args) {
       flags.agents = true;
       continue;
     }
+    if (token === '--claude-code' || token === '--claude') {
+      flags.claudeCode = true;
+      continue;
+    }
+    if (token === '--cursor') {
+      flags.cursor = true;
+      continue;
+    }
     if (token.startsWith('-')) {
       throw new Error(`Unsupported init option: ${token}`);
     }
@@ -741,7 +814,7 @@ function printUsage() {
   console.log('  generate [path]         Scan source files and generate Themis contract tests');
   console.log('                         Options: [--json] [--plan] [--output path] [--files a,b] [--match-source regex] [--match-export regex] [--scenario name] [--min-confidence level] [--require-confidence level] [--include regex] [--exclude regex] [--review] [--update] [--clean] [--changed] [--force] [--strict] [--write-hints] [--fail-on-skips] [--fail-on-conflicts]');
   console.log('  scan [path]             Alias for generate');
-  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert]   Scaffold an incremental migration bridge for existing suites');
+  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert] [--assist]   Scaffold an incremental migration bridge for existing suites');
   console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
 }
 

package/src/init.js

@@ -3,17 +3,36 @@ const path = require('path');
 const { initConfig } = require('./config');
 const { ensureGitignoreEntries } = require('./gitignore');
 
-const AGENTS_TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'AGENTS.themis.md');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const AGENTS_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'AGENTS.themis.md');
+const CLAUDE_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'CLAUDE.themis.md');
+const CLAUDE_SKILL_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'claude-skill', 'SKILL.md');
+const CLAUDE_COMMANDS_TEMPLATE_DIR = path.join(TEMPLATES_DIR, 'claude-commands');
+const CURSOR_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'cursorrules.themis.md');
 
 function runInit(cwd, options = {}) {
   initConfig(cwd);
   ensureGitignoreEntries(cwd, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
 
-  if (options.agents) {
-    return ensureAgentsTemplate(cwd);
+  const hasExplicitFlags = options.agents || options.claudeCode || options.cursor;
+  const detected = hasExplicitFlags ? options : detectAgents(cwd, options);
+
+  const result = {};
+
+  if (detected.agents) {
+    result.agents = ensureAgentsTemplate(cwd);
+  }
+
+  if (detected.claudeCode) {
+    result.claudeCode = ensureClaudeCodeAssets(cwd);
+  }
+
+  if (detected.cursor) {
+    result.cursor = writeCursorRules(cwd);
   }
 
-  return null;
+  result.autoDetected = !hasExplicitFlags;
+  return result;
 }
 
 function ensureAgentsTemplate(cwd) {
@@ -33,6 +52,105 @@ function ensureAgentsTemplate(cwd) {
   };
 }
 
+function ensureClaudeCodeAssets(cwd) {
+  const result = {
+    claudeMd: writeClaudeMd(cwd),
+    skill: writeClaudeSkill(cwd),
+    commands: writeClaudeCommands(cwd)
+  };
+  return result;
+}
+
+function writeClaudeMd(cwd) {
+  const targetPath = path.join(cwd, 'CLAUDE.md');
+  const source = fs.readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8');
+
+  if (!fs.existsSync(targetPath)) {
+    fs.writeFileSync(targetPath, source, 'utf8');
+    return { path: targetPath, created: true, appended: false };
+  }
+
+  const existing = fs.readFileSync(targetPath, 'utf8');
+  if (existing.includes('@vitronai/themis')) {
+    return { path: targetPath, created: false, appended: false };
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(targetPath, existing + separator + source, 'utf8');
+  return { path: targetPath, created: false, appended: true };
+}
+
+function writeClaudeSkill(cwd) {
+  const targetDir = path.join(cwd, '.claude', 'skills', 'themis');
+  const targetPath = path.join(targetDir, 'SKILL.md');
+  if (fs.existsSync(targetPath)) {
+    return { path: targetPath, created: false };
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  const source = fs.readFileSync(CLAUDE_SKILL_TEMPLATE_PATH, 'utf8');
+  fs.writeFileSync(targetPath, source, 'utf8');
+  return { path: targetPath, created: true };
+}
+
+function writeClaudeCommands(cwd) {
+  const targetDir = path.join(cwd, '.claude', 'commands');
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const entries = fs.readdirSync(CLAUDE_COMMANDS_TEMPLATE_DIR);
+  const written = [];
+  const skipped = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    const sourcePath = path.join(CLAUDE_COMMANDS_TEMPLATE_DIR, entry);
+    const targetPath = path.join(targetDir, entry);
+    if (fs.existsSync(targetPath)) {
+      skipped.push(targetPath);
+      continue;
+    }
+    const source = fs.readFileSync(sourcePath, 'utf8');
+    fs.writeFileSync(targetPath, source, 'utf8');
+    written.push(targetPath);
+  }
+
+  return { dir: targetDir, written, skipped };
+}
+
+function detectAgents(cwd) {
+  const flags = { agents: true, claudeCode: false, cursor: false };
+
+  // Claude Code: .claude/ dir or CLAUDE.md exists
+  if (fs.existsSync(path.join(cwd, '.claude')) || fs.existsSync(path.join(cwd, 'CLAUDE.md'))) {
+    flags.claudeCode = true;
+  }
+
+  // Cursor: .cursorrules or .cursor/ dir exists
+  if (fs.existsSync(path.join(cwd, '.cursorrules')) || fs.existsSync(path.join(cwd, '.cursor'))) {
+    flags.cursor = true;
+  }
+
+  return flags;
+}
+
+function writeCursorRules(cwd) {
+  const targetPath = path.join(cwd, '.cursorrules');
+  const source = fs.readFileSync(CURSOR_TEMPLATE_PATH, 'utf8');
+
+  if (!fs.existsSync(targetPath)) {
+    fs.writeFileSync(targetPath, source, 'utf8');
+    return { path: targetPath, created: true, appended: false };
+  }
+
+  const existing = fs.readFileSync(targetPath, 'utf8');
+  if (existing.includes('@vitronai/themis')) {
+    return { path: targetPath, created: false, appended: false };
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(targetPath, existing + separator + source, 'utf8');
+  return { path: targetPath, created: false, appended: true };
+}
+
 module.exports = {
   runInit
 };

package/src/migrate.js

@@ -10,6 +10,40 @@ const THEMIS_COMPAT_FILE = 'themis.compat.js';
 const MIGRATION_REPORT_FILE = ARTIFACT_RELATIVE_PATHS.migrationReport;
 const SCANNABLE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
 const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', '.themis']);
+const MIGRATION_ASSIST_PATTERNS = Object.freeze([
+  {
+    id: 'remaining-framework-import',
+    category: 'remaining-framework-import',
+    severity: 'warning',
+    pattern: /(?:import\s+[^;]*?from\s+['"](?:@jest\/globals|vitest|@testing-library\/react)['"]|import\s*\(\s*['"](?:@jest\/globals|vitest|@testing-library\/react)['"]\s*\)|require\(\s*['"](?:@jest\/globals|vitest|@testing-library\/react)['"]\s*\))/,
+    message: 'Framework-specific imports are still present after migration scaffolding.',
+    suggestion: 'Rewrite or remove remaining framework imports so the suite only depends on Themis-compatible entry points.'
+  },
+  {
+    id: 'unsupported-helper',
+    category: 'unsupported-helper',
+    severity: 'warning',
+    pattern: /\b(?:jest|vi)\.(?:mocked|doMock|dontMock|setMock|requireActual|requireMock|createMockFromModule|isolateModules|isolateModulesAsync|unstable_mockModule|importActual|importMock)\s*\(/,
+    message: 'Unsupported Jest/Vitest helper detected.',
+    suggestion: 'Replace the helper with an explicit Themis mock, fixture, or project-local test utility before relying on the migrated suite.'
+  },
+  {
+    id: 'async-matcher-chain',
+    category: 'async-matcher-chain',
+    severity: 'warning',
+    pattern: /\.\s*(?:resolves|rejects)\b/,
+    message: 'Promise matcher chains remain in the migrated file.',
+    suggestion: 'Rewrite promise assertions to explicit await-based checks so they run under Themis without framework-specific matcher chaining.'
+  },
+  {
+    id: 'focused-alias',
+    category: 'focused-alias',
+    severity: 'warning',
+    pattern: /\b(?:fit|xit|fdescribe|xdescribe)\s*\(/,
+    message: 'Focused or excluded Jest/Vitest aliases remain in the migrated file.',
+    suggestion: 'Replace focused aliases with Themis-supported describe/test forms before running the migrated suite broadly.'
+  }
+]);
 
 function runMigrate(cwd, framework, options = {}) {
   const source = String(framework || '').trim().toLowerCase();
@@ -66,7 +100,14 @@ function runMigrate(cwd, framework, options = {}) {
   const conversionSummary = options.convert
     ? convertMigrationFiles(projectRoot, scan.matches)
     : { convertedFiles: [], convertedAssertions: 0, removedImports: 0 };
-  const report = buildMigrationReport(projectRoot, source, scan.matches, rewriteSummary, conversionSummary);
+  const assistSummary = analyzeMigrationAssist(projectRoot, scan.matches, {
+    enabled: Boolean(options.assist)
+  });
+  const report = buildMigrationReport(projectRoot, source, scan.matches, rewriteSummary, conversionSummary, assistSummary, {
+    rewriteImports: Boolean(options.rewriteImports),
+    convert: Boolean(options.convert),
+    assist: Boolean(options.assist)
+  });
   fs.mkdirSync(path.dirname(reportPath), { recursive: true });
   fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
 
@@ -84,7 +125,9 @@ function runMigrate(cwd, framework, options = {}) {
     rewriteImports: Boolean(options.rewriteImports),
     rewrittenFiles: rewriteSummary.rewrittenFiles,
     convert: Boolean(options.convert),
-    convertedFiles: conversionSummary.convertedFiles
+    convertedFiles: conversionSummary.convertedFiles,
+    assist: Boolean(options.assist),
+    assistSummary
   };
 }
 
@@ -170,12 +213,20 @@ function buildMigrationReport(
   source,
   matches,
   rewriteSummary = { rewrittenFiles: [], rewrittenImports: 0 },
-  conversionSummary = { convertedFiles: [], convertedAssertions: 0, removedImports: 0 }
+  conversionSummary = { convertedFiles: [], convertedAssertions: 0, removedImports: 0 },
+  assistSummary = buildEmptyAssistSummary(false),
+  mode = { rewriteImports: false, convert: false, assist: false }
 ) {
+  const effectiveAssistSummary = normalizeAssistSummary(assistSummary, Boolean(mode.assist));
   return {
     schema: 'themis.migration.report.v1',
     source,
     createdAt: new Date().toISOString(),
+    mode: {
+      rewriteImports: Boolean(mode.rewriteImports),
+      convert: Boolean(mode.convert),
+      assist: Boolean(mode.assist)
+    },
     summary: {
       matchedFiles: matches.length,
       jestGlobals: matches.filter((entry) => entry.imports.includes('@jest/globals')).length,
@@ -185,11 +236,18 @@ function buildMigrationReport(
       rewrittenImports: Number(rewriteSummary.rewrittenImports || 0),
       convertedFiles: Array.isArray(conversionSummary.convertedFiles) ? conversionSummary.convertedFiles.length : 0,
       convertedAssertions: Number(conversionSummary.convertedAssertions || 0),
-      removedImports: Number(conversionSummary.removedImports || 0)
+      removedImports: Number(conversionSummary.removedImports || 0),
+      assistedFiles: Number(effectiveAssistSummary.analyzedFiles || 0),
+      unresolvedFiles: Array.isArray(effectiveAssistSummary.unresolvedFiles) ? effectiveAssistSummary.unresolvedFiles.length : 0,
+      findings: Array.isArray(effectiveAssistSummary.findings) ? effectiveAssistSummary.findings.length : 0,
+      unsupportedPatterns: Number(effectiveAssistSummary.unsupportedPatterns || 0)
     },
     files: matches,
     nextActions: [
       'Run npx themis test to execute migrated suites under the Themis runtime.',
+      ...(effectiveAssistSummary.findings.length > 0
+        ? ['Resolve assistant findings in the migration report before relying on the migrated suite in CI.']
+        : []),
       'Replace any unsupported Jest/Vitest-only helpers with Themis built-ins or project setup utilities.',
       'Use npx themis generate src for source-driven unit-layer coverage alongside migrated suites.'
     ],
@@ -198,7 +256,71 @@ function buildMigrationReport(
       : [],
     conversions: Array.isArray(conversionSummary.convertedFiles)
       ? conversionSummary.convertedFiles
-      : []
+      : [],
+    assistant: effectiveAssistSummary
+  };
+}
+
+function analyzeMigrationAssist(projectRoot, matches, options = {}) {
+  const enabled = Boolean(options.enabled);
+  if (!enabled) {
+    return buildEmptyAssistSummary(false);
+  }
+
+  const findings = [];
+  const unresolvedFiles = new Set();
+
+  for (const match of matches) {
+    const absoluteFile = path.join(projectRoot, match.file);
+    const sourceText = fs.readFileSync(absoluteFile, 'utf8');
+
+    for (const definition of MIGRATION_ASSIST_PATTERNS) {
+      if (!definition.pattern.test(sourceText)) {
+        continue;
+      }
+      unresolvedFiles.add(match.file);
+      findings.push({
+        file: match.file,
+        category: definition.category,
+        severity: definition.severity,
+        pattern: definition.id,
+        message: definition.message,
+        suggestion: definition.suggestion
+      });
+    }
+  }
+
+  return normalizeAssistSummary(
+    {
+      enabled: true,
+      analyzedFiles: matches.length,
+      findings,
+      unresolvedFiles: Array.from(unresolvedFiles).sort(),
+      unsupportedPatterns: findings.length
+    },
+    true
+  );
+}
+
+function buildEmptyAssistSummary(enabled) {
+  return {
+    enabled: Boolean(enabled),
+    analyzedFiles: 0,
+    findings: [],
+    unresolvedFiles: [],
+    unsupportedPatterns: 0
+  };
+}
+
+function normalizeAssistSummary(summary, enabled) {
+  const findings = Array.isArray(summary && summary.findings) ? summary.findings : [];
+  const unresolvedFiles = Array.isArray(summary && summary.unresolvedFiles) ? summary.unresolvedFiles : [];
+  return {
+    enabled: Boolean(enabled),
+    analyzedFiles: Number((summary && summary.analyzedFiles) || 0),
+    findings,
+    unresolvedFiles,
+    unsupportedPatterns: Number((summary && summary.unsupportedPatterns) || findings.length)
   };
 }
 

package/templates/CLAUDE.themis.md

@@ -0,0 +1,43 @@
+# Testing With Themis
+
+This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis) as its unit test framework. Themis is a drop-in alternative to Jest and Vitest, designed for AI coding agents like Claude Code: deterministic reruns, structured failure output, and machine-readable repair hints.
+
+## Commands
+
+- Install: `npm install -D @vitronai/themis`
+- Initialize: `npx themis init`
+- Generate tests for a source tree: `npx themis generate src` (or `app` for Next App Router)
+- Run tests: `npx themis test`
+- Run tests and emit agent-readable output: `npx themis test --reporter agent`
+- Re-run only failed tests: `npx themis test --rerun-failed`
+- Migrate from Jest: `npx themis migrate jest` then `--rewrite-imports` then `--convert`
+- Migrate from Vitest: `npx themis migrate vitest` then `--rewrite-imports` then `--convert`
+
+## When You Are Asked To Add Or Fix Tests
+
+1. If the repo has no tests yet, run `npx themis generate <source-root>` first. Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX) or `.generated.test.js` (JS/JSX). Use them as a starting point — do not delete or rewrite them wholesale.
+2. Prefer `intent(...)` for behavior and workflow tests. Prefer `test(...)` for low-level unit checks. Use the four-phase shape: `context` → `run` → `verify` → `cleanup`.
+3. Run `npx themis test --reporter agent` and read the JSON output. Failure clusters and repair hints are structured — use them to drive your fix loop instead of re-reading raw stack traces.
+4. After fixing, re-run only the failing tests with `npx themis test --rerun-failed` before running the full suite.
+
+## When You Are Asked To Migrate From Jest Or Vitest
+
+1. Run `npx themis migrate jest` (or `vitest`) — this scaffolds compatibility, no rewrites yet.
+2. Run `npx themis migrate jest --rewrite-imports` to point imports at `themis.compat.js`.
+3. Run `npx themis migrate jest --convert` to apply codemods toward native Themis style.
+4. Run `npx themis migrate jest --assist` to get a structured findings report of files that still need manual follow-up. The report path is printed at the end of the command — read it before guessing what to fix.
+5. Run `npx themis test` after each step. Migration is incremental on purpose; do not try to convert the whole suite in one pass.
+
+## Things To Avoid
+
+- Do not claim Themis is "not a unit test framework" — it is one.
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files just to load `.css`, `.png`, `.jpg`, `.svg`, or font/media imports. Themis handles these natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/` — they are gitignored framework output.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless the user asks; treat them as Themis-managed.
+- Do not reach for snapshot tests as the default — prefer deterministic assertions and `captureContract(...)` for contract-style checks.
+
+## Reference
+
+- API reference: [`node_modules/@vitronai/themis/docs/api.md`](node_modules/@vitronai/themis/docs/api.md)
+- Adoption guide: [`node_modules/@vitronai/themis/docs/agents-adoption.md`](node_modules/@vitronai/themis/docs/agents-adoption.md)
+- Machine-readable manifest: [`node_modules/@vitronai/themis/themis.ai.json`](node_modules/@vitronai/themis/themis.ai.json)

package/templates/claude-commands/themis-fix.md

@@ -0,0 +1,14 @@
+---
+description: Fix failing Themis tests using the agent reporter's repair hints
+---
+
+Read the most recent Themis run output and fix the failures.
+
+1. Run `npx themis test --reporter agent` and capture the JSON output.
+2. Group the failures by `failures[].cluster`. Fixes within a cluster usually share a root cause — address the cluster, not each failure independently.
+3. For each cluster, read `failures[].repairHints` first. They are structured suggestions you can act on directly.
+4. Apply the smallest fix that addresses the root cause. Do not refactor surrounding code.
+5. Re-run with `npx themis test --rerun-failed` to confirm the cluster is fixed.
+6. Repeat for the next cluster. Only run the full suite once `--rerun-failed` is green.
+
+If the user passed specific test names or files, scope the work to those: $ARGUMENTS

package/templates/claude-commands/themis-generate.md

@@ -0,0 +1,14 @@
+---
+description: Generate Themis tests for a source tree
+---
+
+Generate Themis tests for the given source root. If the user did not specify one, default to `src` (or `app` if this is a Next.js App Router project — check for `app/layout.tsx` or `app/page.tsx`).
+
+```bash
+npx themis generate $ARGUMENTS
+```
+
+Generated tests land under `__themis__/tests`. After generation:
+1. Read the summary the command prints — it tells you how many files were generated, skipped, and why.
+2. Run `npx themis test --reporter agent` to verify the generated suite passes.
+3. If any generated tests are wrong, do not delete them — extend or correct them in place.

package/templates/claude-commands/themis-migrate.md

@@ -0,0 +1,18 @@
+---
+description: Migrate this repo from Jest or Vitest to Themis
+---
+
+Migrate this repository from Jest or Vitest to Themis. If the user did not say which, detect it: check `package.json` devDependencies for `jest` or `vitest`.
+
+Run the four steps in order, and run `npx themis test` between each step to confirm the suite is still green:
+
+```bash
+npx themis migrate <jest|vitest>                    # 1. scaffold compatibility
+npx themis migrate <jest|vitest> --rewrite-imports  # 2. rewrite imports
+npx themis migrate <jest|vitest> --convert          # 3. codemod to native style
+npx themis migrate <jest|vitest> --assist           # 4. emit structured findings
+```
+
+After step 4, read the findings report (its path is printed at the end of the command) and walk through any items it flags for manual follow-up. Do not guess at fixes — the report tells you what needs human attention and why.
+
+If the user passed extra arguments, forward them: $ARGUMENTS

package/templates/claude-commands/themis-test.md

@@ -0,0 +1,12 @@
+---
+description: Run the Themis test suite with agent-readable output
+---
+
+Run `npx themis test --reporter agent` and read the JSON output. If there are failures:
+
+1. Group them by `failures[].cluster` — fixes for the same cluster usually share a root cause.
+2. For each cluster, read `failures[].repairHints` before reading the raw stack trace.
+3. Apply the smallest fix that addresses the root cause, then re-run with `npx themis test --rerun-failed` to verify.
+4. Only run the full suite again once `--rerun-failed` is green.
+
+If the user passed extra arguments, forward them to `npx themis test`: $ARGUMENTS

package/templates/claude-skill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: themis
+description: Use this skill when the user asks to write, generate, run, fix, or migrate unit tests in a Node.js or TypeScript repository that has @vitronai/themis installed (or when the user explicitly mentions Themis). Covers test authoring with intent(...) and test(...), running the suite via `npx themis test`, reading agent-readable failure output, and incremental migration from Jest or Vitest.
+---
+
+# Themis
+
+This repo uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis) as its unit test framework. It is a drop-in alternative to Jest and Vitest, designed for AI coding agents: deterministic execution, structured failure output with repair hints, and a one-command migration path.
+
+## How To Run Tests
+
+```bash
+npx themis test                          # full suite, human-readable output
+npx themis test --reporter agent         # JSON output with failure clusters and repair hints
+npx themis test --rerun-failed           # only re-run tests that failed last run
+```
+
+**When you are in an edit-test-fix loop, always use `--reporter agent`.** The JSON output gives you:
+- `failures[].cluster` — failures grouped by likely common cause
+- `failures[].repairHints` — structured suggestions you can act on directly
+- `failures[].sourceFile`, `lineNumber`, `expected`, `actual` — already parsed, no need to re-parse stack traces
+
+After fixing, prefer `--rerun-failed` over a full re-run.
+
+## How To Write Tests
+
+Themis has two primary forms:
+
+**`intent(...)`** for behavior and workflow tests. Use the four-phase shape:
+
+```js
+intent('user can sign in', ({ context, run, verify, cleanup }) => {
+  context('a valid user', (ctx) => {
+    ctx.user = { email: 'a@b.com', password: 'pw' };
+  });
+  run('the user submits credentials', (ctx) => {
+    ctx.result = signIn(ctx.user);
+  });
+  verify('authentication succeeds', (ctx) => {
+    expect(ctx.result.ok).toBe(true);
+  });
+  cleanup('remove test state', (ctx) => {
+    delete ctx.user;
+  });
+});
+```
+
+**`test(...)`** for low-level unit checks (pure functions, single assertions).
+
+Rules of thumb:
+- Each phase has one job. Do not assert in `context` or `run`. Do not mutate state in `verify`.
+- Prefer `expect(...)` style assertions. They work the same as Jest/Vitest.
+- Prefer deterministic assertions over snapshots. For contract-style coverage use `captureContract(...)`.
+
+## How To Generate Tests From Source
+
+If the user asks you to add tests for a module or directory and the repo already has Themis installed:
+
+```bash
+npx themis generate src         # conventional source tree
+npx themis generate app         # Next.js App Router
+npx themis generate src/auth    # narrower target
+```
+
+Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX sources) or `.generated.test.js` (JS/JSX sources). Treat them as Themis-managed — extend rather than rewrite.
+
+## How To Migrate From Jest Or Vitest
+
+Migration is incremental on purpose. Run the steps in order and `npx themis test` between each:
+
+```bash
+npx themis migrate jest                        # 1. scaffold compatibility, no code changes
+npx themis migrate jest --rewrite-imports      # 2. point imports at themis.compat.js
+npx themis migrate jest --convert              # 3. apply codemods to native Themis style
+npx themis migrate jest --assist               # 4. emit structured findings JSON for manual follow-ups
+```
+
+Same flags work for `vitest`. **Read the `--assist` findings report before guessing what to fix manually** — its path is printed at the end of the command and the schema is at `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`.
+
+## Things To Avoid
+
+- Do not claim Themis is "not a unit test framework". It is one.
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files to shim `.css`, `.png`, `.jpg`, `.svg`, or font imports. Themis handles those natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/` — they are gitignored framework output.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless the user asks.
+- Do not reach for `setupFiles` unless you genuinely need a real harness bootstrap.
+- Do not try to migrate the whole Jest/Vitest suite in one pass. Use the four migrate steps in order.
+
+## Reference Files In This Repo
+
+- API reference: `node_modules/@vitronai/themis/docs/api.md`
+- Adoption guide: `node_modules/@vitronai/themis/docs/agents-adoption.md`
+- Machine-readable manifest: `node_modules/@vitronai/themis/themis.ai.json`
+- Migration report schema: `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`