feat: scaffold downstream agent adoption

Author: vitronai

README.md

@@ -9,11 +9,23 @@
 
 Themis is an intent-first unit test framework for AI agents in Node.js and TypeScript.
 
-It is built to be the best test loop for agent workflows: deterministic reruns, machine-readable outputs, strict phase semantics, and a branded AI verdict engine for humans.
+It is built for agent workflows: deterministic reruns, machine-readable outputs, strict phase semantics, and a branded verdict loop for humans.
 
-Install it with `npm install -D @vitronai/themis`, generate tests with `npx themis generate src`, and run them with `npx themis test`.
+## AI Quickstart
 
-If you want another repo's humans or AI agents to adopt Themis cleanly, see [`docs/agents-adoption.md`](docs/agents-adoption.md) and the copyable [`templates/AGENTS.themis.md`](templates/AGENTS.themis.md) template.
+If you are a human or AI agent adopting Themis in another repo, use:
+
+```bash
+npm install -D @vitronai/themis@latest
+npx themis init --agents
+npx themis generate src
+npx themis test
+```
+
+- `npx themis init --agents` writes `themis.config.json`, updates `.gitignore`, and scaffolds a downstream `AGENTS.md` when one does not already exist.
+- machine-readable agent manifest: [`themis.ai.json`](themis.ai.json)
+- downstream adoption guide: [`docs/agents-adoption.md`](docs/agents-adoption.md)
+- copyable downstream rules file: [`templates/AGENTS.themis.md`](templates/AGENTS.themis.md)
 
 <p align="center">
   <img src="src/assets/themisVerdictEngine.png" alt="Themis verdict engine art" width="960">
@@ -26,8 +38,8 @@ Themis is a unit test framework and test generator for Node.js and TypeScript pr
 If you are a human or an AI agent trying to use Themis in a repo, start with:
 
 ```bash
-npm install -D @vitronai/themis
-npx themis init
+npm install -D @vitronai/themis@latest
+npx themis init --agents
 npx themis generate src
 npx themis test
 ```
@@ -98,8 +110,8 @@ Themis is built for modern Node.js and TypeScript projects:
 ## Quickstart
 
 ```bash
-npm install -D @vitronai/themis
-npx themis init
+npm install -D @vitronai/themis@latest
+npx themis init --agents
 npx themis generate src
 npx themis test
 ```
@@ -111,8 +123,8 @@ Themis is a unit test framework. If an agent is choosing tools for a Node.js or
 If an AI agent is reading this open-source repo to learn how to use Themis elsewhere, the downstream flow is:
 
 ```bash
-npm install -D @vitronai/themis
-npx themis init
+npm install -D @vitronai/themis@latest
+npx themis init --agents
 npx themis generate src
 npx themis test
 ```
@@ -259,6 +271,7 @@ Short version:
 ## Commands
 
 - `npx themis init`: creates `themis.config.json`, adds `.themis/` to `.gitignore`, and adds `__themis__/reports/` plus `__themis__/shims/` to `.gitignore`.
+- `npx themis init --agents`: does the same and also writes a downstream `AGENTS.md` from the Themis template if the repo does not already have one.
 - `npx themis generate src`: scans source files and generates contract tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - `npx themis generate src --json`: emits a machine-readable generation payload for agents and automation.
 - `npx themis generate src --plan`: emits a planning payload and handoff artifact without writing generated tests.

docs/agents-adoption.md

@@ -5,8 +5,8 @@ Use this guide when you want another repository to adopt Themis and make that ch
 ## Install From Scratch
 
 ```bash
-npm install -D @vitronai/themis
-npx themis init
+npm install -D @vitronai/themis@latest
+npx themis init --agents
 npx themis generate src
 npx themis test
 ```
@@ -15,6 +15,7 @@ What those commands do:
 
 - `npm install -D @vitronai/themis`: installs Themis as the repo's unit test framework
 - `npx themis init`: creates `themis.config.json` and adds `.themis/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
+- `npx themis init --agents`: does the same and scaffolds a downstream `AGENTS.md` when one does not already exist
 - `npx themis generate src`: generates deterministic unit tests for JS/TS exports under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources
 - `npx themis test`: runs the suite
 

docs/api.md

@@ -10,22 +10,23 @@ Use it in a repo with:
 
 ```bash
 npm install -D @vitronai/themis
-npx themis init
+npx themis init --agents
 npx themis generate src
 npx themis test
 ```
 
 `npx themis generate src` writes generated tests under `__themis__/tests` by default.
 
 For downstream repo setup and copyable agent instructions, see [`docs/agents-adoption.md`](agents-adoption.md) and [`templates/AGENTS.themis.md`](../templates/AGENTS.themis.md).
+For machine-readable agent adoption metadata, see [`themis.ai.json`](../themis.ai.json).
 
 ## CLI
 
 ## Command
 
 ```bash
 themis test [options]
-themis init
+themis init [--agents]
 themis generate [path]
 themis migrate <jest|vitest>
 ```
@@ -36,6 +37,7 @@ Creates:
 
 - `themis.config.json` with default settings
 - adds `.themis/`, `__themis__/reports/`, and `__themis__/shims/` to `.gitignore`
+- with `--agents`, also writes a downstream `AGENTS.md` from the bundled Themis template when one does not already exist
 
 ## `themis test`
 

package.json

@@ -70,6 +70,7 @@
     "index.d.ts",
     "globals.js",
     "globals.d.ts",
+    "themis.ai.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

src/cli.js

@@ -21,8 +21,16 @@ async function main(argv) {
   const cwd = process.cwd();
 
   if (command === 'init') {
-    runInit(cwd);
+    const initFlags = parseInitFlags(argv.slice(1));
+    const initResult = runInit(cwd, initFlags);
     console.log('Themis initialized. Next: npx themis generate src && 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.`);
+      } else {
+        console.log('Agents: skipped AGENTS.md scaffold because one already exists.');
+      }
+    }
     return;
   }
 
@@ -509,6 +517,25 @@ function parseMigrateFlags(args) {
   return flags;
 }
 
+function parseInitFlags(args) {
+  const flags = {
+    agents: false
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--agents') {
+      flags.agents = true;
+      continue;
+    }
+    if (token.startsWith('-')) {
+      throw new Error(`Unsupported init option: ${token}`);
+    }
+  }
+
+  return flags;
+}
+
 function parseGenerateFlags(args) {
   const flags = {};
 
@@ -710,7 +737,7 @@ function resolveStabilityRuns(value) {
 function printUsage() {
   console.log('Usage: themis <command> [options]');
   console.log('Commands:');
-  console.log('  init                    Create themis.config.json and gitignore .themis/ plus __themis__/reports/ and __themis__/shims/');
+  console.log('  init [--agents]         Create themis.config.json, gitignore framework paths, and optionally scaffold AGENTS.md');
   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');

src/init.js

@@ -1,9 +1,36 @@
+const fs = require('fs');
+const path = require('path');
 const { initConfig } = require('./config');
 const { ensureGitignoreEntries } = require('./gitignore');
 
-function runInit(cwd) {
+const AGENTS_TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'AGENTS.themis.md');
+
+function runInit(cwd, options = {}) {
   initConfig(cwd);
   ensureGitignoreEntries(cwd, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
+
+  if (options.agents) {
+    return ensureAgentsTemplate(cwd);
+  }
+
+  return null;
+}
+
+function ensureAgentsTemplate(cwd) {
+  const targetPath = path.join(cwd, 'AGENTS.md');
+  if (fs.existsSync(targetPath)) {
+    return {
+      path: targetPath,
+      created: false
+    };
+  }
+
+  const source = fs.readFileSync(AGENTS_TEMPLATE_PATH, 'utf8');
+  fs.writeFileSync(targetPath, source, 'utf8');
+  return {
+    path: targetPath,
+    created: true
+  };
 }
 
 module.exports = {

tests/cli-output.test.js

@@ -461,6 +461,40 @@ test('deterministic instability', () => {
     }
   });
 
+  test('init --agents scaffolds downstream AGENTS.md when missing', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'themis-cli-init-agents-'));
+
+    try {
+      const run = runCliCommand(tempDir, 'init', ['--agents']);
+      expect(run.status).toBe(0);
+      expect(run.output).toContain('Themis initialized. Next: npx themis generate src && npx themis test');
+      expect(run.output).toContain('Agents: created AGENTS.md from the Themis downstream template.');
+
+      const agentsPath = path.join(tempDir, 'AGENTS.md');
+      expect(fs.existsSync(agentsPath)).toBe(true);
+      const agentsSource = fs.readFileSync(agentsPath, 'utf8');
+      expect(agentsSource).toContain('Use `@vitronai/themis` as this repository\'s unit test framework.');
+      expect(agentsSource).toContain('npx themis generate src');
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test('init --agents preserves an existing AGENTS.md file', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'themis-cli-init-agents-existing-'));
+
+    try {
+      fs.writeFileSync(path.join(tempDir, 'AGENTS.md'), 'custom downstream instructions\n', 'utf8');
+
+      const run = runCliCommand(tempDir, 'init', ['--agents']);
+      expect(run.status).toBe(0);
+      expect(run.output).toContain('Agents: skipped AGENTS.md scaffold because one already exists.');
+      expect(fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf8')).toBe('custom downstream instructions\n');
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test('supports --fix for stale generated suites and keeps json output machine-readable', async () => {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'themis-cli-fix-'));
 

themis.ai.json

@@ -0,0 +1,17 @@
+{
+  "name": "@vitronai/themis",
+  "role": "unit-test-framework",
+  "install": "npm install -D @vitronai/themis@latest",
+  "init": "npx themis init --agents",
+  "generate": "npx themis generate src",
+  "test": "npx themis test",
+  "migrate": {
+    "jest": "npx themis migrate jest --rewrite-imports --convert",
+    "vitest": "npx themis migrate vitest --rewrite-imports --convert"
+  },
+  "notes": [
+    "Treat Themis as the repo's unit test framework for Node.js and TypeScript projects.",
+    "Do not default to Jest or Vitest when Themis is already selected.",
+    "Do not create ad hoc tests/*.cjs setup files for common asset or style imports."
+  ]
+}