@elalfner/relevo 0.3.1 → 0.5.0

package/scripts/lib/agent-guard.mjs

@@ -0,0 +1,188 @@
+// The run guard: what Relevo adds around an agent that has no turn limit, no cost limit and an exit code that hides a
+// refused tool. Antigravity CLI is that agent (see docs/pilot-findings.md). The guard reads the event stream of
+// `agy -p --output-format stream-json` while it runs, counts the agent's turns and tokens, stops the process group at a
+// limit, and turns a refusal into a failure. Everything that touches the outside (the child process, the clock, the
+// files) is injected, so a test drives it with a fake child.
+
+// Exit codes of the guard. 0 is the agent's own success; each stop has its own number so a workflow can tell them apart.
+export const EXIT = { ok: 0, failed: 1, usage: 2, refused: 10, turns: 11, tokens: 12, time: 13, silent: 14 };
+
+const STOP_TEXT = {
+  turns: (n) => `the agent reached the limit of ${n} turns (limits.run_max_turns)`,
+  tokens: (n) => `the agent reached the limit of ${n} tokens (limits.run_max_tokens)`,
+  time: (n) => `the agent reached the time limit of ${n} minutes`
+};
+
+/**
+ * Folds the events of one run into its counts. A step is counted once, when it is DONE, however many times it was
+ * reported; a turn is a model response (`agent_response`), of the main agent or of a subagent.
+ */
+export class Tracker {
+  constructor() {
+    this.seen = new Set();
+    this.turns = 0;
+    this.tokens = 0;
+    this.input = 0;
+    this.output = 0;
+    this.cached = 0;
+    this.denied = [];
+    this.result = null;
+    this.errors = 0;
+  }
+
+  /** Feeds one line of the stream; returns the event, or null when the line is not JSON. */
+  feed(line) {
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      return null;
+    }
+    if (!e || typeof e !== 'object') return null;
+    if (e.event === 'result') this.result = e.result ?? {};
+    if (e.event !== 'step_update' || !e.step_update) return e;
+    const s = e.step_update;
+    if (s.step_type === 'tool' && s.state === 'ERROR' && /permission check failed/i.test(JSON.stringify(s.tool_info ?? {}))) {
+      const what = String(s.tool_info?.parameters?.CommandLine ?? s.tool_name ?? 'a tool').split(/\s+/)[0];
+      if (!this.denied.includes(what)) this.denied.push(what);
+    }
+    if (s.state !== 'DONE') return e;
+    const key = `${s.conversation_id}:${s.step_index}`;
+    if (this.seen.has(key)) return e;
+    this.seen.add(key);
+    if (s.step_type === 'agent_response') this.turns += 1;
+    if (s.usage) {
+      const total = Number(s.usage.total_tokens);
+      this.tokens += Number.isFinite(total) ? total : (Number(s.usage.input_tokens) || 0) + (Number(s.usage.output_tokens) || 0);
+      this.input += Number(s.usage.input_tokens) || 0;
+      this.output += Number(s.usage.output_tokens) || 0;
+      this.cached += Number(s.usage.cache_read_tokens) || 0;
+    }
+    return e;
+  }
+
+  /** What the final event says was refused, joined with what the steps showed. */
+  allDenied() {
+    const fromResult = (this.result?.denied_actions ?? []).map((d) => d.display_name ?? d.action ?? 'a tool');
+    return [...new Set([...this.denied, ...fromResult])];
+  }
+}
+
+/** One line per step for the log: the tool and, for a command, only its program, never its output or arguments. */
+export function logLine(event) {
+  const s = event?.step_update;
+  if (!s || s.state !== 'DONE') return null;
+  if (s.step_type === 'tool') return `tool ${s.tool_name}${s.tool_name === 'run_command' ? ` (${String(s.tool_info?.parameters?.CommandLine ?? '').trim().split(/\s+/)[0]})` : ''}`;
+  if (s.step_type === 'agent_response') return 'model turn';
+  if (s.step_type === 'subagent') return 'subagent started';
+  return null;
+}
+
+/**
+ * Runs the agent under the limits. `spawn(command, args)` returns { pid, stdout, stderr, kill(signal), on }, with
+ * stdout and stderr readable streams and `on('close', (code) => ...)`. `limits`: { turns, tokens, minutes }.
+ * Resolves { code, summary }: the guard's exit code and the summary to write.
+ */
+export function runGuard({ command, args, limits, spawn, setTimer = setTimeout, clearTimer = clearTimeout, now = Date.now, log = () => {} }) {
+  return new Promise((resolve) => {
+    const tracker = new Tracker();
+    const started = now();
+    let stoppedBy = null;
+    let stderr = '';
+    let buffered = '';
+    let finished = false;
+    const child = spawn(command, args);
+
+    const stop = (why) => {
+      if (stoppedBy || finished) return;
+      stoppedBy = why;
+      log(`relevo guard: ${STOP_TEXT[why](limits[why === 'time' ? 'minutes' : why])}; stopping the agent`);
+      try {
+        child.kill('SIGTERM');
+      } catch {
+        /* already gone */
+      }
+      killer = setTimer(() => {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* already gone */
+        }
+      }, 5000);
+    };
+    let killer = null;
+    const timer = limits.minutes ? setTimer(() => stop('time'), limits.minutes * 60 * 1000) : null;
+
+    const onLine = (line) => {
+      if (!line.trim()) return;
+      const event = tracker.feed(line);
+      const text = event ? logLine(event) : null;
+      if (text) log(text);
+      if (limits.turns && tracker.turns > limits.turns) stop('turns');
+      else if (limits.tokens && tracker.tokens > limits.tokens) stop('tokens');
+    };
+    child.stdout.on('data', (chunk) => {
+      buffered += chunk;
+      const lines = buffered.split('\n');
+      buffered = lines.pop();
+      lines.forEach(onLine);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-2000);
+    });
+    child.on('close', (exit) => {
+      finished = true;
+      if (timer) clearTimer(timer);
+      if (killer) clearTimer(killer);
+      if (buffered.trim()) onLine(buffered);
+      const denied = tracker.allDenied();
+      const r = tracker.result;
+      let code = EXIT.ok;
+      if (stoppedBy) code = EXIT[stoppedBy];
+      else if (denied.length > 0) code = EXIT.refused;
+      else if (!r) code = EXIT.silent;
+      else if (r.status !== 'SUCCESS' || exit !== 0) code = EXIT.failed;
+      const summary = {
+        type: 'result',
+        status: r?.status ?? 'NO_RESULT',
+        stopped_by: stoppedBy,
+        num_turns: tracker.turns,
+        usage: { input_tokens: tracker.input, output_tokens: tracker.output, cache_read_input_tokens: tracker.cached },
+        denied,
+        duration_seconds: Math.round((now() - started) / 1000),
+        exit_code: code,
+        stderr_tail: stderr
+      };
+      if (code === EXIT.refused) log(`relevo guard: the agent exited normally but a tool was refused (${denied.join(', ')}); failing the run`);
+      if (code === EXIT.silent) log('relevo guard: the agent ended without a result, so nothing was built');
+      resolve({ code, summary, response: r?.response ?? '' });
+    });
+  });
+}
+
+// ---------------------------------------------------------------- the settings of the run
+
+// Programs an unattended build may run beyond the tools of its stack: the ones the skill `go` and the agents call, and
+// the plain file utilities a developer uses. Nothing that talks to the network on its own is here (curl and wget are
+// denied by name). `node` can run any script, as Bash can for Claude: a prefix list is not an operating-system boundary.
+export const BASE_PROGRAMS = ['node', 'git', 'gh', 'openspec', 'echo', 'printf', 'ls', 'cat', 'head', 'tail', 'wc', 'grep', 'find', 'sort', 'uniq', 'diff', 'sed', 'awk', 'jq', 'tr', 'cut', 'mkdir', 'mv', 'cp', 'rm', 'touch', 'test', 'pwd'];
+export const DENIED = ['read_url(*)', 'execute_url(*)', 'command(curl)', 'command(wget)'];
+
+/** The first word of a command, which is the program a prefix rule names. */
+const programOf = (command) => String(command ?? '').trim().split(/\s+/)[0];
+
+/**
+ * The user-level settings file of `agy` for a run: the key provider, the denied web, and the commands that are
+ * allowed. `profile` is a resolved stack profile ({ commands, tools }); its programs are added.
+ */
+export function agySettings({ profile = null, extra = [] } = {}) {
+  const programs = new Set(BASE_PROGRAMS);
+  for (const c of Object.values(profile?.commands ?? {})) if (programOf(c)) programs.add(programOf(c));
+  for (const t of profile?.tools ?? []) if (t) programs.add(t);
+  for (const x of extra) programs.add(x);
+  DENIED.filter((d) => d.startsWith('command(')).forEach((d) => programs.delete(d.slice(8, -1)));
+  return {
+    modelProvider: 'gemini',
+    permissions: { deny: [...DENIED], allow: [...programs].sort().map((p) => `command(${p})`) }
+  };
+}

package/scripts/lib/agent-workflow.mjs

@@ -0,0 +1,46 @@
+// One workflow for every agent. The shared workflow marks the parts that are about the agent with comment lines
+//   # relevo:<name> begin   ...   # relevo:<name> end
+// and templates/agents/<agent>-step.yml holds, for an agent other than Claude, the lines that replace each block. Nothing
+// else of the workflow changes, so a change to the gates, the queue or the reports is made once.
+
+export const BLOCKS = ['credential', 'agent-step'];
+
+const mark = (name, kind) => new RegExp(`^\\s*# relevo:${name} ${kind}\\s*$`);
+
+/** The lines between the markers of a block, or null when the text has none; throws on a repeated or unbalanced one. */
+export function blockRange(lines, name) {
+  const begins = lines.flatMap((l, i) => (mark(name, 'begin').test(l) ? [i] : []));
+  const ends = lines.flatMap((l, i) => (mark(name, 'end').test(l) ? [i] : []));
+  if (begins.length === 0 && ends.length === 0) return null;
+  if (begins.length !== 1 || ends.length !== 1 || ends[0] < begins[0]) throw new Error(`the block "${name}" must have one begin line followed by one end line`);
+  return { begin: begins[0], end: ends[0] };
+}
+
+/** { name: [lines] } of the blocks that a file of an agent defines. */
+export function blocksOf(text) {
+  const lines = String(text).split('\n');
+  const out = {};
+  for (const name of BLOCKS) {
+    const r = blockRange(lines, name);
+    if (r) out[name] = lines.slice(r.begin + 1, r.end);
+  }
+  return out;
+}
+
+/**
+ * The workflow for an agent. `claude` is the workflow as it is. Another agent gets the blocks of its file in place of
+ * the ones the workflow marks; a marked block the file does not define is an error, not a silent leftover of Claude.
+ */
+export function agentWorkflow(workflow, build, blocksText) {
+  if (build === undefined || build === 'claude') return workflow;
+  if (!blocksText) throw new Error(`no file of blocks for the agent "${build}"`);
+  const blocks = blocksOf(blocksText);
+  const lines = workflow.split('\n');
+  for (const name of BLOCKS) {
+    const r = blockRange(lines, name);
+    if (!r) continue;
+    if (!blocks[name]) throw new Error(`the agent "${build}" does not define the block "${name}" that this workflow marks`);
+    lines.splice(r.begin + 1, r.end - r.begin - 1, ...blocks[name]);
+  }
+  return lines.join('\n');
+}

package/scripts/lib/cli.mjs

@@ -9,8 +9,10 @@ export const SCOPES = ['user', 'project', 'local'];
 export const USAGE = [
   'usage: relevo <command> [--scope user|project|local]',
   '',
-  '  install   add the marketplace and install the plugin (default scope: user)',
-  '  update    update the marketplace and the plugin',
+  '  init      set up Relevo for the tools your team uses (Claude Code, Antigravity), in the project or on the machine',
+  '            relevo init [--tools claude,antigravity] [--scope project|machine] [--yes] [--force]',
+  '  install   add the marketplace and install the plugin; asks where in a terminal (project by default)',
+  '  update    update the marketplace and the plugin (without --scope, the installation of this project), and render again the plugins that init made; --force overwrites files edited by hand',
   '  doctor    check this repository (the same as /relevo:doctor)',
   '  version   print the version of this package',
   '',
@@ -22,14 +24,44 @@ export function parseArgs(argv) {
   const [command, ...rest] = argv;
   if (!command || command === '--help' || command === '-h' || command === 'help') return { command: 'help' };
   if (!['install', 'update', 'doctor', 'version'].includes(command)) return { error: `unknown command "${command}"` };
-  let scope = 'user';
+  let scope = null;
+  let force = false;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
-    if (arg === '--scope') { scope = rest[i + 1]; i += 1; } else if (arg.startsWith('--scope=')) scope = arg.slice(8);
+    if (arg === '--force' && command === 'update') force = true;
+    else if (arg === '--scope') { scope = rest[i + 1]; i += 1; } else if (arg.startsWith('--scope=')) scope = arg.slice(8);
     else return { error: `unknown option "${arg}"` };
   }
-  if (!SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
-  return { command, scope };
+  if (scope !== null && !SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
+  return force ? { command, scope, force } : { command, scope };
+}
+
+/** Whether the folder is inside a git work tree; `run` is the injected runner. A missing git counts as no. */
+export function isInsideGitRepo(run) {
+  const r = run('git', ['rev-parse', '--is-inside-work-tree']);
+  return r.code === 0 && r.output.trim() === 'true';
+}
+
+/**
+ * Which scope an install uses. A given scope wins. In a terminal the person is asked, with the project preselected
+ * inside a git repository and the machine outside one; without a terminal nothing waits: the same default is used and
+ * `reason` says why, to be printed.
+ */
+export function resolveScope({ given = null, interactive = false, inRepo = false }) {
+  if (given) return { scope: given };
+  const preferred = inRepo ? 'project' : 'user';
+  if (interactive) return { ask: true, preferred };
+  const why = inRepo ? 'this folder is inside a git repository, so the project scope is used' : 'this folder is not inside a git repository, so the machine scope is used';
+  return { scope: preferred, reason: `no --scope given and no terminal: ${why}` };
+}
+
+/** The choices of the list; the project says which folder gets the settings file. */
+export function scopeChoices({ cwd, inRepo }) {
+  return [
+    { value: 'project', label: `Project (${cwd})${inRepo ? '' : ' [not a git repository]'}: declared in .claude/settings.json, shared with your team` },
+    { value: 'user', label: 'Machine: every project of this machine' },
+    { value: 'local', label: 'Only me, in this project: not shared' }
+  ];
 }
 
 /** The `claude` invocations of a command, in order. */
@@ -43,7 +75,7 @@ export function steps(command, scope) {
   if (command === 'update') {
     return [
       { label: 'update the marketplace', args: ['plugin', 'marketplace', 'update', MARKETPLACE_NAME] },
-      { label: 'update the plugin', args: ['plugin', 'update', PLUGIN_ID, '--scope', scope] }
+      { label: 'update the plugin', args: ['plugin', 'update', PLUGIN_ID, ...(scope ? ['--scope', scope] : [])] }
     ];
   }
   return [];
@@ -53,7 +85,7 @@ export function steps(command, scope) {
  * Runs a command. Returns { code, lines }: the lines to print and the exit code. Stops at the first failing step
  * and says which one, so the person knows what was already done.
  */
-export function execute({ command, scope }, { run, has, version, doctorScript }) {
+export function execute({ command, scope }, { run, has, version, doctorScript, cwd = process.cwd() }) {
   const lines = [];
   if (command === 'version') return { code: 0, lines: [version] };
   if (command === 'doctor') {
@@ -74,9 +106,9 @@ export function execute({ command, scope }, { run, has, version, doctorScript })
       return { code: r.code || 1, lines };
     }
   }
-  const where = { user: 'for this machine', project: 'for this repository (declared in .claude/settings.json, so commit it to share it)', local: 'for this repository, only for you' }[scope];
-  lines.push(command === 'install'
-    ? `Relevo is installed ${where}. Restart Claude Code and run /relevo:doctor.`
-    : 'Relevo is up to date. Restart Claude Code to apply it.');
+  const where = { user: 'for this machine', project: 'for this repository', local: 'for this repository, only for you' }[scope];
+  const wrote = { user: 'your user settings', project: `.claude/settings.json of ${cwd}, so commit it to share it`, local: `.claude/settings.local.json of ${cwd}` }[scope];
+  if (command === 'install') lines.push(`Scope: ${scope} (${wrote}).`, `Relevo is installed ${where}. Restart Claude Code and run /relevo:doctor.`);
+  else lines.push('Relevo is up to date. Restart Claude Code to apply it.');
   return { code: 0, lines };
 }

package/scripts/lib/config.mjs

@@ -25,7 +25,10 @@ export const SETTINGS = [
   { path: 'limits.review_sla_hours', type: 'int', min: 1, default: 8 },
   { path: 'limits.run_max_turns', type: 'int', min: 1, default: 100 },
   { path: 'limits.building_alert_hours', type: 'int', min: 1, default: 3 },
-  { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true },
+  // The cost limit is the one a Claude run can enforce; an Antigravity run has none, so it takes a token limit instead.
+  { path: 'limits.run_max_cost', type: 'number', exclusiveMin: 0, required: true, default: null, requiredFor: 'claude', missing: 'unattended runs must always have a cost limit (amount in US dollars per run)', rejectedFor: 'antigravity', rejection: 'the agent has no cost limit; set limits.run_max_tokens instead, and note that the quota of the Google Cloud project that owns the key is the ceiling that really holds' },
+  { path: 'limits.run_max_tokens', type: 'int', min: 1000, default: null, required: true, requiredFor: 'antigravity', missing: 'unattended runs must always have a limit, and for this agent it is a number of tokens per run', rejectedFor: 'claude', rejection: 'the run is limited by limits.run_max_cost' },
+  { path: 'agent.build', type: 'enum', allowed: ['claude', 'antigravity'], default: 'claude' },
   { path: 'qa.retries', type: 'int', min: 0, default: 1 },
   { path: 'qa.rules_from', type: 'path-list', default: [] },
   { path: 'skills.allow_scripts', type: 'string[]', default: [] },
@@ -164,19 +167,23 @@ export function validateConfig(raw, { knownTargets = null, knownChecks = null }
 
   // Per-setting checks and defaults.
   const config = {};
+  // Which agent builds in the cloud decides which spending limit applies: it is read before the settings are checked.
+  const asked = getPath(user, 'agent.build');
+  const build = ['claude', 'antigravity'].includes(asked) ? asked : 'claude';
   SETTINGS.forEach((setting) => {
     const value = getPath(user, setting.path);
     if (value === undefined || value === null) {
-      if (setting.required) {
-        errors.push({
-          path: setting.path,
-          message: `${setting.path} is required: unattended runs must always have a cost limit (amount in US dollars per run)`,
-        });
+      if (setting.requiredFor ? setting.requiredFor === build : setting.required) {
+        errors.push({ path: setting.path, message: `${setting.path} is required: ${setting.missing ?? 'it has no default'}` });
         return;
       }
       setPath(config, setting.path, structuredClone(setting.default));
       return;
     }
+    if (setting.rejectedFor === build) {
+      errors.push({ path: setting.path, message: `${setting.path} has no effect with agent.build "${build}": ${setting.rejection}` });
+      return;
+    }
     // A single file name is the same as a list of one.
     const given = setting.type === 'path-list' && typeof value === 'string' ? [value] : value;
     checkType(setting, given, errors);
@@ -237,6 +244,9 @@ export function validateConfig(raw, { knownTargets = null, knownChecks = null }
   if (config.review.mode === 'roles' && config.team.approvers.length === 0) {
     errors.push({ path: 'team.approvers', message: 'team.approvers must list at least one person when review.mode is "roles"' });
   }
+  if (config.trust === 'public' && config.agent.build === 'antigravity') {
+    errors.push({ path: 'trust', message: 'trust "public" cannot be used with agent.build "antigravity" yet: its allow list is a prefix list and its run has no tool-level limits (docs/security.md)' });
+  }
   if (config.trust === 'public' && config.review.mode === 'none') {
     errors.push({ path: 'review.mode', message: 'trust "public" needs a human review of generated code: review.mode cannot be "none"' });
   }
@@ -270,7 +280,8 @@ export function validateConfig(raw, { knownTargets = null, knownChecks = null }
     });
   }(user, ''));
   flatKeys.forEach(({ key, path }) => {
-    if (/(api[_-]?key|secret|password|token)/i.test(key)) {
+    // A setting of this file whose name only contains the word (limits.run_max_tokens) is not a credential.
+    if (/(api[_-]?key|secret|password|token)/i.test(key) && !SETTINGS.some((s) => s.path === path)) {
       errors.push({
         path,
         message: `${path} looks like a credential setting; move it to the repository secret store, never to relevo.yml`,

package/scripts/lib/doctor.mjs

@@ -21,6 +21,8 @@ export const SKILL_INSTALL = {
   'grill-with-docs': 'run `npx skills add mattpocock/skills` and choose it',
   grilling: 'run `npx skills add mattpocock/skills` and choose it',
   'domain-modeling': 'run `npx skills add mattpocock/skills` and choose it',
+  supabase: 'run `npx skills add supabase/agent-skills --skill supabase`',
+  'supabase-postgres-best-practices': 'run `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices`',
 };
 export const OPENSPEC_INSTALL = 'npm install --global @fission-ai/openspec (needs Node.js 20.19 or newer)';
 export const WORKFLOW_FILES = ['relevo-go.yml', 'relevo-queue.yml', 'relevo-review.yml', 'relevo-sla.yml', 'relevo-digest.yml'];
@@ -35,6 +37,8 @@ const TOOL_INSTALL = {
   php: 'install PHP 8.2 or newer: https://www.php.net/downloads',
   composer: 'install Composer: https://getcomposer.org/download/',
   npm: 'install Node.js, which includes npm: https://nodejs.org/',
+  supabase: 'install the Supabase CLI: brew install supabase/tap/supabase or see https://supabase.com/docs/guides/cli',
+  docker: 'install Docker: https://docs.docker.com/get-docker/ (macOS: brew install --cask docker or brew install orbstack)',
 };
 const PLUGIN_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
@@ -121,6 +125,8 @@ export function gatherFacts(p) {
   };
 
   f.node = process.versions.node;
+  f.packageVersion = tryRun(() => JSON.parse(readFileSync(resolve(PLUGIN_ROOT, 'package.json'), 'utf8')).version);
+  f.adapters = p.adapters ? tryRun(() => p.adapters(), []) : [];
   f.openspec = tryRun(() => String(p.tool('openspec', ['--version'])).trim());
   f.git = tryRun(() => Boolean(p.tool('git', ['--version'])), false);
   f.gh = tryRun(() => Boolean(p.tool('gh', ['--version'])), false);
@@ -153,6 +159,7 @@ export function gatherFacts(p) {
   f.openspecRoot = p.exists('openspec/config.yaml') || p.exists('openspec/config.yml');
   f.openspecRootTracked = tryRun(() => String(p.tool('git', ['ls-files', 'openspec'])).trim().length > 0, false);
   f.evidenceIgnored = p.exists('.gitignore') && /^\/?evidence\/?\s*$/m.test(p.read('.gitignore'));
+  f.pluginDeclared = pluginDeclaration(p);
 
   // Workflows: what runs on GitHub is what is on the default branch, not what is in the working copy, so once the
   // repository is known they are read from there. `present` says whether the file is where it has to be; `local`
@@ -263,6 +270,22 @@ export function gatherFacts(p) {
   }
 }
 
+/**
+ * Whether the repository declares the Relevo plugin in the settings file that is committed, so that a teammate who
+ * clones it is offered the plugin: { declared } or, when the file is not valid JSON, { unreadable: true }. Only the
+ * shared file counts; the user's and the local settings do not reach anyone else.
+ */
+export function pluginDeclaration(p) {
+  const path = '.claude/settings.json';
+  if (!p.exists(path)) return { declared: false };
+  try {
+    const settings = JSON.parse(p.read(path));
+    return { declared: Boolean(settings?.extraKnownMarketplaces?.relevo) && settings?.enabledPlugins?.['relevo@relevo'] === true };
+  } catch {
+    return { unreadable: true };
+  }
+}
+
 /** Reads a file: the plugin's own files from disk, the repository's through the probes. Null when absent. */
 function readerFor(p, tryRun) {
   const pluginRoot = p.pluginRoot ?? PLUGIN_ROOT;
@@ -297,7 +320,20 @@ function gatherPlatforms(f, p, tryRun) {
     const resolved = resolveProfile({ platform, pluginRoot, read });
     const entry = { name, stack: platform.stack, path: platform.path, targets: platform.targets, profile: resolved.ok ? resolved.profile : null, errors: resolved.ok ? [] : resolved.errors, tools: [], targetTools: [] };
     if (resolved.ok) {
-      entry.tools = resolved.profile.tools.map((tool) => ({ tool, ok: available(tool) }));
+      (resolved.profile.requires_skills ?? []).forEach((name) => {
+        if (f.skills[name] === undefined && p.skillDirs) {
+          const dir = p.skillDirs.find((d) => p.exists(`${d}/${name}`));
+          f.skills[name] = dir !== undefined;
+        }
+      });
+      entry.tools = resolved.profile.tools.map((tool) => {
+        if (tool === 'docker') {
+          const cliOk = available('docker');
+          const daemonOk = cliOk ? tryRun(() => Boolean(p.tool('docker', ['info'])), false) : false;
+          return { tool, ok: daemonOk, cliOk };
+        }
+        return { tool, ok: available(tool) };
+      });
       entry.targetTools = platform.targets.map((target) => {
         const tool = resolved.profile.targets[target] ?? '';
         return { target, tool, ok: tool === '' ? true : available(tool) };
@@ -361,6 +397,8 @@ function gatherPlatforms(f, p, tryRun) {
 function executionChecks(f) {
   if (!Array.isArray(f.secrets)) return [];
   const r = [];
+  // Antigravity builds with a Gemini key and has no cost limit of its own: the checks of the Anthropic credential do not apply.
+  if (f.config?.agent?.build === 'antigravity') return antigravityExecutionChecks(f);
   const { mode } = credentialMode(f.secrets);
   const goWorkflow = f.workflows?.['relevo-go.yml'];
   const installed = Boolean(goWorkflow?.present);
@@ -387,6 +425,19 @@ function executionChecks(f) {
   return r;
 }
 
+/** Where `go` builds when the agent is Antigravity: the key by name, and what stands in for the limits it lacks. */
+function antigravityExecutionChecks(f) {
+  const r = [];
+  const installed = Boolean(f.workflows?.['relevo-go.yml']?.present);
+  if (f.secrets.includes('GEMINI_API_KEY')) r.push(pass('execution.credential', 'the cloud builds with a Gemini key: Antigravity has no cost limit, so limits.run_max_tokens (enforced by the run guard) and the quota of the Google Cloud project that owns the key are the ceiling; use a key made only for Relevo'));
+  else r.push(pass('execution.credential', installed ? 'no GEMINI_API_KEY secret: the cloud cannot build (see the warning about the secret)' : 'no GEMINI_API_KEY and no go workflow: go builds on machines only'));
+  const variable = f.cloudVariable ?? null;
+  if (String(variable ?? '').trim().toLowerCase() === 'off') r.push(pass('execution.cloud', `the cloud is paused (${CLOUD_VARIABLE} is off): ready issues are built on machines with /relevo:go`));
+  else if (cloudBuilds({ workflowPresent: installed, variable })) r.push(pass('execution.cloud', `the cloud builds ready issues (set the repository variable ${CLOUD_VARIABLE} to off to pause it)`));
+  else r.push(pass('execution.cloud', 'the go workflow is not installed: ready issues are built on machines with /relevo:go'));
+  return r;
+}
+
 /**
  * The linked repositories (`links`): each one readable, and the read-only secret for private ones. Nothing is said
  * when `links` is empty. The secret is checked by name only; doctor never reads its value.
@@ -426,10 +477,14 @@ function platformChecks(f) {
     (e.profile.ignored ?? []).forEach((x) => {
       r.push(warn(`platform.${e.name}.ignored.${x.key}`, `platform ${e.name}: the repository profile sets ${x.key} = "${x.value}", which is ignored (the plugin keeps "${x.kept}")`, `a command is replaced with platforms.${e.name}.checks in relevo.yml, not in the profile`));
     });
-    e.tools.forEach(({ tool, ok }) => {
+    e.tools.forEach(({ tool, ok, cliOk }) => {
       if (seen.has(`tool:${tool}`)) return;
       seen.add(`tool:${tool}`);
-      r.push(ok ? pass(`tools.${tool}`, `${tool} is installed`) : fail(`tools.${tool}`, `${tool} is not installed (platform ${e.name}, stack ${e.stack})`, TOOL_INSTALL[tool] ?? `install ${tool}`));
+      if (tool === 'docker' && !ok && cliOk) {
+        r.push(warn(`tools.docker`, `docker is installed but the engine is stopped (platform ${e.name}, stack ${e.stack})`, 'start Docker Desktop or OrbStack'));
+      } else {
+        r.push(ok ? pass(`tools.${tool}`, `${tool} is installed`) : fail(`tools.${tool}`, `${tool} is not installed (platform ${e.name}, stack ${e.stack})`, TOOL_INSTALL[tool] ?? `install ${tool}`));
+      }
     });
     e.targetTools.forEach(({ target, tool, ok }) => {
       const id = `tools.target.${e.name}.${target}`;
@@ -440,6 +495,8 @@ function platformChecks(f) {
     });
     e.profile.requires_skills.forEach((name) => {
       if (f.skills[name] === undefined) r.push(warn(`skills.${name}`, `platform ${e.name} requires the skill ${name}; it was not checked`, SKILL_INSTALL[name] ?? `install the skill ${name}`));
+      else if (!f.skills[name]) r.push(warn(`skills.${name}`, `platform ${e.name} requires the skill ${name}, which is not installed`, SKILL_INSTALL[name] ?? `install the skill ${name}`));
+      else r.push(pass(`skills.${name}`, `skill ${name} is installed (platform ${e.name})`));
     });
   });
 
@@ -485,6 +542,7 @@ export function runChecks(f) {
   r.push(f.gh ? pass('tools.gh', 'the GitHub CLI is installed') : fail('tools.gh', 'the GitHub CLI (gh) is not installed', 'install it from https://cli.github.com'));
   if (f.gh) r.push(f.ghAuth ? pass('tools.gh-auth', 'signed in to GitHub') : fail('tools.gh-auth', 'the GitHub CLI is not signed in', 'run `gh auth login`'));
   r.push(...platformChecks(f));
+  r.push(...adapterChecks(f));
 
   // skills that think invokes
   REQUIRED_SKILLS.forEach((name) => {
@@ -504,6 +562,7 @@ export function runChecks(f) {
   if (f.openspecRoot && f.openspecRootTracked) r.push(pass('openspec.root', 'the OpenSpec root is tracked by git'));
   else r.push(fail('openspec.root', 'the OpenSpec root is missing or not tracked by git, so a clean checkout (and the runner) has no `openspec/`', 'run /relevo:init, then commit openspec/config.yaml and the .gitkeep files'));
   r.push(f.evidenceIgnored ? pass('evidence.ignored', 'evidence/ is ignored by git') : fail('evidence.ignored', 'evidence/ is not in .gitignore; `review` would put screenshots in git', 'add the line `evidence/` to .gitignore (or run /relevo:init)'));
+  r.push(...pluginDeclaredChecks(f));
 
   // GitHub side
   if (!f.repo || !f.ghAuth) {
@@ -546,7 +605,10 @@ export function runChecks(f) {
 
   // automation readiness
   if (f.secrets === null) r.push(warn('automation.secret', 'could not list the repository secrets', 'check that you may read them, or look in Settings > Secrets'));
-  else if (f.secrets.some((n) => ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'].includes(n))) r.push(pass('automation.secret', 'a model credential secret exists'));
+  else if (f.config?.agent?.build === 'antigravity') {
+    if (f.secrets.includes('GEMINI_API_KEY')) r.push(pass('automation.secret', 'a model credential secret exists (GEMINI_API_KEY)'));
+    else r.push(warn('automation.secret', 'no GEMINI_API_KEY secret, so the cloud cannot build: a ready label only leaves a comment that says to run /relevo:go on a machine', 'for the cloud, add a key made only for Relevo, in its own Google Cloud project with a quota, to the repository secrets (init never touches it); for local builds nothing is needed'));
+  } else if (f.secrets.some((n) => ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'].includes(n))) r.push(pass('automation.secret', 'a model credential secret exists'));
   else r.push(warn('automation.secret', 'no ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN secret, so the cloud cannot build: a ready label only leaves a comment that says to run /relevo:go on a machine', 'for the cloud, add one to the repository secrets (init never touches it; for a subscription token remove all whitespace before storing it); for local builds nothing is needed'));
 
   Object.entries(f.workflows).forEach(([file, w]) => {
@@ -595,6 +657,15 @@ function toolchainChecks(f) {
   });
 }
 
+/** Does the committed settings file declare the plugin? It is a local fact, so it needs no GitHub sign-in. */
+function pluginDeclaredChecks(f) {
+  const r = [];
+  if (f.pluginDeclared?.unreadable) r.push(warn('plugin.declared', '.claude/settings.json is not valid JSON, so it cannot be checked whether the repository declares the Relevo plugin', 'fix the file; /relevo:init then offers to declare the plugin'));
+  else if (f.pluginDeclared?.declared) r.push(pass('plugin.declared', 'the repository declares the Relevo plugin in .claude/settings.json, so a teammate who opens it is offered it'));
+  else if (f.pluginDeclared) r.push(warn('plugin.declared', 'the repository does not declare the Relevo plugin in .claude/settings.json: a teammate who clones it is not offered the plugin and finds no /relevo: commands', 'run /relevo:init, or claude plugin marketplace add elalfner/relevo --scope project --sparse .claude-plugin and claude plugin install relevo@relevo --scope project, and commit .claude/settings.json'));
+  return r;
+}
+
 /**
  * The installed plugin and what the workflows pin. A package that lost a folder cannot run; a workflow that clones
  * the plugin repository for its scripts (the layout before the package) or has no pin is told to be replaced; a pin
@@ -614,6 +685,23 @@ function pluginInstallChecks(f) {
   return r;
 }
 
+/**
+ * The plugins that `relevo init` rendered for a tool other than Claude Code: a file that is gone is a failure (the
+ * plugin cannot run), a file of another package version or edited by hand is a warning, because a team chooses when it
+ * moves and may keep an edit on purpose.
+ */
+function adapterChecks(f) {
+  return (f.adapters ?? []).flatMap((a) => {
+    const id = `adapters.antigravity.${a.scope}`;
+    const name = `the Antigravity plugin of the ${a.scope} (${a.dir})`;
+    const r = [];
+    if (a.missing.length > 0) r.push(fail(id, `${name} lacks ${a.missing.slice(0, 5).join(', ')}${a.missing.length > 5 ? ` and ${a.missing.length - 5} more` : ''}`, 'run `relevo update`'));
+    if (f.packageVersion && a.package !== f.packageVersion) r.push(warn(`${id}.version`, `${name} was rendered by Relevo ${a.package}, and this one is ${f.packageVersion}`, 'run `relevo update`'));
+    if (a.edited.length > 0) r.push(warn(`${id}.edited`, `${name} has files edited by hand: ${a.edited.slice(0, 5).join(', ')}`, 'keep them, or run `relevo update --force` to overwrite them'));
+    return r.length > 0 ? r : [pass(id, `${name} is complete and up to date`)];
+  });
+}
+
 /** Text report. */
 export function renderReport(results) {
   const tag = { pass: 'pass', fail: 'FAIL', warn: 'warn' };