@diffci.com/diffci 0.1.10 → 0.1.11

package/README.md

@@ -12,7 +12,13 @@ the opt-in `pilot` and `verify-savings` commands execute tests.
 From an existing repository checkout, with Node.js 22.5+ and Git installed:
 
 ```bash
-npx @diffci.com/diffci@latest observe --no-send
+npx @diffci.com/diffci@latest check
+```
+
+For AI coding agents, seed the repository with default instructions:
+
+```bash
+npx @diffci.com/diffci@latest init
 ```
 
 For the fastest self-serve runtime pilot, run one paired check from the repository root:
@@ -43,6 +49,9 @@ comparison, add `--base <base-sha> --head <head-sha>`. DiffCI prints the selecti
 and the path to a JSON report outside your checkout. `REFUSED` or `ERROR` is not a successful analysis;
 check the reported status even when the command exits successfully. See the
 [support matrix](docs/language-support.md) for setup requirements and supported workloads.
+`check` is an agent-friendly alias for `observe --no-send`: it runs no tests, changes no CI behavior,
+and sends nothing by default. See [`docs/ai-agents.md`](docs/ai-agents.md) for Claude Code, Codex,
+Cursor, GitHub Copilot, and similar tools.
 
 **Measured example:** a controlled Cal.com replay showed **44.2% net reduction in a job-equivalent
 install + pretest + test workload**, including analysis overhead. This is one sandbox comparison,
@@ -216,6 +225,8 @@ DiffCI is intended to be installable as infrastructure, not only as a hosted sha
 
 ```bash
 npx @diffci.com/diffci@latest observe
+npx @diffci.com/diffci@latest check
+npx @diffci.com/diffci@latest init
 npx @diffci.com/diffci@latest verify-workflow
 ```
 

package/dist-client/src/client/cli.js

@@ -13,6 +13,8 @@
  * the observer is exactly what Phase 02 shipped: a local analysis whose output never leaves the runner.
  *
  * Commands:
+ *   init               seed a repository with AI-agent instructions for using DiffCI
+ *   check              agent-friendly alias for observe --no-send
  *   observe            analyse the checkout and write an observation report
  *   verify-savings     run a paired full-versus-selected timing check
  *   verify-workflow    check that a DiffCI job in this repository's workflows cannot affect other jobs
@@ -97,6 +99,106 @@ function defaultReportPath(env) {
     const stamp = env.GITHUB_RUN_ID ? `${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT ?? "1"}` : String(Date.now());
     return join(base, `diffci-observation-${stamp}.json`);
 }
+const AGENT_INSTRUCTIONS = `# DiffCI Agent Instructions
+
+Use DiffCI as the default CI/CD validation lens before proposing, committing, or opening pull requests.
+
+Default command:
+
+\`\`\`bash
+npx @diffci.com/diffci@latest check
+\`\`\`
+
+What this does:
+
+- analyzes the current checkout and commit range;
+- writes a JSON report outside the repository by default;
+- prints selected tests, fallback reasons, and proposed commands;
+- sends nothing unless an endpoint and token are explicitly configured;
+- runs, skips, cancels, or reorders no tests.
+
+If DiffCI reports \`REFUSED\` or \`ERROR\`, treat that as an installation or analysis issue and continue with the repository's normal test commands. If DiffCI reports a selected command, prefer using it as evidence for what changed, not as permission to skip required CI.
+`;
+const CURSOR_RULE = `---
+description: Use DiffCI as the default CI/CD validation lens
+alwaysApply: true
+---
+
+Before proposing, committing, or opening pull requests, run:
+
+\`\`\`bash
+npx @diffci.com/diffci@latest check
+\`\`\`
+
+DiffCI is observation-only by default. It analyzes the change, writes a report outside the checkout, and sends nothing without explicit configuration. Do not use a DiffCI selection as permission to skip required project CI.
+`;
+const GITHUB_COPILOT_INSTRUCTIONS = `# Repository CI/CD Validation
+
+Use DiffCI as the default change-aware CI/CD validation lens:
+
+\`\`\`bash
+npx @diffci.com/diffci@latest check
+\`\`\`
+
+DiffCI's default agent command is observation-only. It should inform which tests and CI paths are relevant, while the repository's required checks remain authoritative.
+`;
+const DIFFCI_CONFIG = `{
+  "$schema": "https://diffci.com/schemas/diffci.config.schema.json",
+  "agentDefaultCommand": "npx @diffci.com/diffci@latest check",
+  "mode": "observe",
+  "sendReports": false
+}
+`;
+function diffciWorkflow(version) {
+    return `name: DiffCI observation
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  diffci:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx @diffci.com/diffci@${version} check
+`;
+}
+function writeInitFile(repoPath, relativePath, content, force) {
+    const absolutePath = join(repoPath, relativePath);
+    const existed = existsSync(absolutePath);
+    if (existed && !force)
+        return `kept ${relativePath} (already exists)`;
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, content, "utf8");
+    return `${existed ? "overwrote" : "wrote"} ${relativePath}`;
+}
+function runInit(flags, env) {
+    const repoPath = resolve(typeof flags.repo === "string" ? flags.repo : env.GITHUB_WORKSPACE ?? process.cwd());
+    const force = flags.force === true;
+    const includeWorkflow = flags.workflow === true;
+    const identity = observerIdentity();
+    const writes = [
+        writeInitFile(repoPath, "AGENTS.md", AGENT_INSTRUCTIONS, force),
+        writeInitFile(repoPath, "CLAUDE.md", AGENT_INSTRUCTIONS, force),
+        writeInitFile(repoPath, ".cursor/rules/diffci.mdc", CURSOR_RULE, force),
+        writeInitFile(repoPath, ".github/copilot-instructions.md", GITHUB_COPILOT_INSTRUCTIONS, force),
+        writeInitFile(repoPath, "diffci.config.json", DIFFCI_CONFIG, force),
+    ];
+    if (includeWorkflow)
+        writes.push(writeInitFile(repoPath, ".github/workflows/diffci.yml", diffciWorkflow(identity.version), force));
+    console.log(`DiffCI initialized for AI coding agents in ${repoPath}`);
+    for (const write of writes)
+        console.log(`  ${write}`);
+    if (!includeWorkflow)
+        console.log("  skipped .github/workflows/diffci.yml (pass --workflow to add it)");
+    console.log("\nDefault agent command: npx @diffci.com/diffci@latest check");
+    return 0;
+}
 function formatFinding(finding) {
     const where = finding.job ? `${finding.workflow}#${finding.job}` : finding.workflow;
     return `  [${finding.severity}] ${finding.code} (${where})\n      ${finding.message}`;
@@ -344,6 +446,9 @@ async function runPilot(flags, env) {
 const USAGE = `diffci - observation-only change-aware CI analysis
 
 Usage:
+  diffci init [--repo <path>] [--workflow] [--force]
+  diffci check [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
+               [--redact-paths] [--json] [--quiet] [--fail-on-error]
   diffci pilot --full <command> [--repo <path>] [--out-dir <dir>] [--label <name>]
   diffci observe [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
                  [--redact-paths] [--json] [--quiet] [--fail-on-error]
@@ -354,6 +459,8 @@ Usage:
   diffci verify-workflow [--repo <path>]
   diffci version
 
+init writes AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and diffci.config.json.
+check is the default AI-agent command: it is observe with sending disabled.
 pilot runs observe and verify-savings together, writing reports to ../diffci-output by default.
 observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
 verify-savings runs both commands and reports measured paired runtime; it is an opt-in pilot command.
@@ -372,6 +479,12 @@ async function main() {
         return;
     }
     switch (command) {
+        case "init":
+            process.exitCode = runInit(flags, env);
+            return;
+        case "check":
+            process.exitCode = await runObserve({ ...flags, "no-send": true }, env);
+            return;
         case "pilot":
             process.exitCode = await runPilot(flags, env);
             return;

package/docs/ai-agents.md

@@ -0,0 +1,64 @@
+# DiffCI for AI Coding Agents
+
+DiffCI is the default CI/CD validation lens agents can run before proposing, committing, or opening a
+pull request.
+
+The safe default command is:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+`check` is an alias for `observe --no-send`. It analyzes the change and prints a report summary without
+running tests, skipping tests, cancelling jobs, changing the checkout, or sending data to DiffCI Cloud.
+
+## Install Agent Instructions
+
+From a repository root:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+This writes:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.cursor/rules/diffci.mdc`
+- `.github/copilot-instructions.md`
+- `diffci.config.json`
+
+Existing files are kept. Pass `--force` only when you intentionally want to replace them.
+
+To also add a non-blocking GitHub Actions observer job:
+
+```bash
+npx @diffci.com/diffci@latest init --workflow
+```
+
+Then verify the workflow:
+
+```bash
+npx @diffci.com/diffci@latest verify-workflow
+```
+
+## Agent Policy
+
+Agents should:
+
+- run `diffci check` before PR-ready answers when Git and Node.js are available;
+- read the printed verdict, selected tests, fallback reasons, and report path;
+- use DiffCI output to choose focused follow-up validation;
+- keep the repository's required CI commands authoritative.
+
+Agents should not:
+
+- skip required CI because DiffCI selected fewer tests;
+- treat `REFUSED` or `ERROR` as a passing validation;
+- configure hosted report sending unless the user explicitly supplies an endpoint and token.
+
+## Open Core Boundary
+
+The agent-facing layer belongs in the open-source core: CLI, local reports, JSON output, instruction
+files, and the non-blocking GitHub Action. Hosted history, organization dashboards, PR bots, policies,
+team analytics, managed runners, and support belong to commercial DiffCI.

package/docs/claude-code.md

@@ -0,0 +1,17 @@
+# DiffCI for Claude Code
+
+Install repository instructions:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Default validation command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
+report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Keep the repository's required checks authoritative.

package/docs/codex.md

@@ -0,0 +1,17 @@
+# DiffCI for Codex
+
+Install repository instructions:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Default validation command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
+report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Keep the repository's required checks authoritative.

package/docs/copilot.md

@@ -0,0 +1,18 @@
+# DiffCI for GitHub Copilot
+
+Install repository instructions:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Default validation command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI before PR-ready answers. `init` writes `.github/copilot-instructions.md`; `check` is
+observation-only: it analyzes the change, writes a report outside the checkout, sends nothing by
+default, and does not run, skip, cancel, or reorder tests. Keep the repository's required checks
+authoritative.

package/docs/cursor.md

@@ -0,0 +1,18 @@
+# DiffCI for Cursor
+
+Install repository instructions:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Default validation command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI before PR-ready changes. `init` writes `.cursor/rules/diffci.mdc`; `check` is
+observation-only: it analyzes the change, writes a report outside the checkout, sends nothing by
+default, and does not run, skip, cancel, or reorder tests. Keep the repository's required checks
+authoritative.

package/docs/grok.md

@@ -0,0 +1,17 @@
+# DiffCI for Grok
+
+Install repository instructions:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Default validation command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
+report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Keep the repository's required checks authoritative.

package/llms.txt

@@ -0,0 +1,34 @@
+# DiffCI
+
+DiffCI is an observation-only, change-aware CI analysis tool for AI coding agents and development teams.
+
+Default AI-agent command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Initialization command:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+What agents should know:
+
+- `diffci check` analyzes the repository checkout and writes a JSON observation report.
+- It runs no tests, skips no tests, cancels no jobs, and changes no CI behavior.
+- It sends no report unless `DIFFCI_API_URL` and `DIFFCI_TOKEN` are explicitly configured.
+- Treat selected commands as evidence about the change, not as permission to skip required project CI.
+- If DiffCI reports `REFUSED` or `ERROR`, fall back to the repository's normal validation commands.
+
+Useful docs:
+
+- AI agents: https://diffci.com/docs/ai-agents.html
+- Codex: https://diffci.com/docs/codex.html
+- Claude Code: https://diffci.com/docs/claude-code.html
+- Cursor: https://diffci.com/docs/cursor.html
+- GitHub Copilot: https://diffci.com/docs/copilot.html
+- Grok: https://diffci.com/docs/grok.html
+- Distribution: https://github.com/DiffCI/DiffCI.com/blob/main/docs/distribution.md
+- Language support: https://github.com/DiffCI/DiffCI.com/blob/main/docs/language-support.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffci.com/diffci",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "DiffCI - deterministic change-aware CI planning",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -19,6 +19,13 @@
     "action.yml",
     "dist-client/src/client",
     "README.md",
+    "llms.txt",
+    "docs/ai-agents.md",
+    "docs/codex.md",
+    "docs/claude-code.md",
+    "docs/cursor.md",
+    "docs/copilot.md",
+    "docs/grok.md",
     "docs/distribution.md",
     "docs/npm-adoption.md",
     "docs/language-support.md",