@elalfner/relevo 0.4.0 → 0.6.0

package/scripts/lib/adapters/tools.mjs

@@ -0,0 +1,52 @@
+// The tools of an agent, said in the words of the tool that will run it. Claude Code's subagents have every tool
+// unless told otherwise (`disallowedTools`); Antigravity's have none beyond a small base unless a list is given, so
+// the list is built here. A Claude tool with no entry stops the render: a wrong name can hang a subagent.
+
+/** What a subagent of Claude Code can use when nothing restricts it, as far as Relevo's agents rely on it. */
+export const CLAUDE_AGENT_TOOLS = ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'];
+
+/**
+ * Claude tool -> the Antigravity tools that do the same. Names are the ones the CLI reports in the `init` event of
+ * `agy -p --output-format stream-json` (checked by tests/adapter-antigravity.test.mjs when RELEVO_AGY_CHECK=1).
+ * An empty list means the tool has no counterpart and is left out on purpose.
+ */
+export const ANTIGRAVITY_TOOLS = {
+  Read: ['view_file', 'list_dir'],
+  Write: ['write_to_file'],
+  Edit: ['replace_file_content', 'multi_replace_file_content'],
+  NotebookEdit: [],
+  Bash: ['run_command'],
+  Grep: ['grep_search'],
+  Glob: ['find_by_name']
+};
+
+export class UnmappedToolError extends Error {
+  constructor(tool) {
+    super(`the Claude tool "${tool}" has no entry in the Antigravity tool table (scripts/lib/adapters/tools.mjs)`);
+    this.tool = tool;
+  }
+}
+
+const names = (v) =>
+  (Array.isArray(v) ? v : String(v ?? '').split(','))
+    .map((s) => String(s).trim())
+    .filter(Boolean);
+
+/** The Claude tools an agent ends up with, from its `tools` (a list) or from everything minus `disallowedTools`. */
+export function claudeToolsOf(meta) {
+  if (meta.tools !== undefined) return names(meta.tools);
+  const denied = new Set(names(meta.disallowedTools));
+  return CLAUDE_AGENT_TOOLS.filter((t) => !denied.has(t));
+}
+
+/** The Antigravity tool names for an agent, without repeats, in a stable order. */
+export function antigravityToolsOf(meta) {
+  const out = [];
+  for (const tool of claudeToolsOf(meta)) {
+    if (!(tool in ANTIGRAVITY_TOOLS)) throw new UnmappedToolError(tool);
+    for (const t of ANTIGRAVITY_TOOLS[tool]) if (!out.includes(t)) out.push(t);
+  }
+  const denied = names(meta.disallowedTools);
+  for (const tool of denied) if (!(tool in ANTIGRAVITY_TOOLS)) throw new UnmappedToolError(tool);
+  return out;
+}

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]',
   '',
+  '  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)',
+  '  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',
   '',
@@ -23,13 +25,15 @@ export function parseArgs(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 = 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 (scope !== null && !SCOPES.includes(scope)) return { error: `the scope must be one of ${SCOPES.join(', ')}` };
-  return { command, scope };
+  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. */

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

@@ -13,7 +13,7 @@ import { loadConfig } from './config.mjs';
 import { labelDefinitions } from './labels.mjs';
 import { credentialMode, cloudBuilds, CLOUD_VARIABLE } from './execution-mode.mjs';
 import { SKILL_DIRS, SIZE_BUDGET_BYTES, folderHash, lockDifferences, resolveRoleSkills, skillBudget } from './role-skills.mjs';
-import { ROLES, profileLocations, profileLookups, resolveProfile } from './stack-profile.mjs';
+import { ROLES, profileLocations, profileLookups, repositoryProfilePath, resolveProfile } from './stack-profile.mjs';
 
 export const REQUIRED_SKILLS = ['openspec-explore', 'grill-with-docs', 'grilling', 'domain-modeling'];
 export const SKILL_INSTALL = {
@@ -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);
@@ -314,11 +320,32 @@ 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) };
       });
+      // The cloud and a fresh clone read the repository's layer from git, not from this working copy. `null` means
+      // git could not say (no git, or not a repository).
+      if (resolved.profile.layers.includes('repository')) {
+        const path = repositoryProfilePath(platform.stack);
+        if (!f.git) entry.repositoryLayerTracked = null;
+        else if (tryRun(() => { p.tool('git', ['ls-files', '--error-unmatch', path]); return true; }, false)) entry.repositoryLayerTracked = true;
+        else entry.repositoryLayerTracked = tryRun(() => { p.tool('git', ['rev-parse', '--is-inside-work-tree']); return true; }, false) ? false : null;
+      }
     }
     f.platformFacts.push(entry);
   });
@@ -378,6 +405,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);
@@ -404,6 +433,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.
@@ -440,13 +482,22 @@ function platformChecks(f) {
     }
     const layers = e.profile.layers.map((l) => (l === 'plugin' ? 'default of the plugin' : `.relevo/stacks/${e.stack}.md`)).join(' + ');
     r.push(pass(`platform.${e.name}.profile`, `platform ${e.name} (${e.stack}, ${e.path}): profile = ${layers}`));
+    if (e.repositoryLayerTracked === false) {
+      const path = `.relevo/stacks/${e.stack}.md`;
+      const effect = e.profile.layers.includes('plugin') ? `use only the plugin's profile for ${e.stack}, without your rules` : `have no profile for ${e.stack}`;
+      r.push(warn(`platform.${e.name}.profile.tracked`, `platform ${e.name}: ${path} is not tracked by git, so the cloud run and a fresh clone ${effect}`, `commit ${path} and push it with the rest of the repository's Relevo files`));
+    }
     (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}`;
@@ -457,6 +508,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})`));
     });
   });
 
@@ -502,6 +555,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) => {
@@ -564,7 +618,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]) => {
@@ -641,6 +698,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' };

package/scripts/lib/go-local.mjs

@@ -5,16 +5,39 @@
 //   capture(cmd, args, { cwd }) -> stdout (throws when the command fails)
 //   stream(cmd, args, { cwd, env }) -> exit status (the output goes to the terminal); throws with code ENOENT when missing
 
-import { basename, dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { cloudBuilds } from './execution-mode.mjs';
 import { runFlags } from './run-flags.mjs';
+import { WORKTREES_FOLDER, worktreePath } from './worktree-path.mjs';
 
-export const WORKTREES_FOLDER = '.relevo-worktrees';
+export { WORKTREES_FOLDER };
+// The guard is part of the plugin, not of the project that is built, so it is found next to this file.
+const GUARD = fileURLToPath(new URL('../agent-guard.mjs', import.meta.url));
+// The same time limit as the cloud step of the Antigravity agent.
+export const GUARD_TIMEOUT_MINUTES = 50;
 
-/** What a local run will do, without doing it: the worktree and the `claude` command. Pure. */
+/** What a local run will do, without doing it: the worktree and the `claude` or `agy` command. Pure. */
 export function planLocalRun({ issue, repoRoot, config }) {
   const base = config.branches.base;
-  const worktree = join(dirname(repoRoot), WORKTREES_FOLDER, `${basename(repoRoot)}-${issue}`);
+  const worktree = worktreePath(repoRoot, issue);
+  const isAntigravity = config.agent?.build === 'antigravity';
+  const command = isAntigravity
+    ? ['node', [
+        GUARD,
+        'run',
+        '--prompt',
+        `/relevo:go ${issue}`,
+        '--config',
+        'relevo.yml',
+        '--timeout-minutes',
+        String(GUARD_TIMEOUT_MINUTES),
+        // outside the worktree, so a clean end can remove it and the agent finds the tree clean
+        '--summary',
+        join(tmpdir(), `relevo-guard-${basename(repoRoot)}-${issue}.json`),
+      ]]
+    : ['claude', ['-p', `/relevo:go ${issue}`, ...runFlags(config)]];
   return {
     issue,
     base,
@@ -23,9 +46,9 @@ export function planLocalRun({ issue, repoRoot, config }) {
       ['fetch', 'origin', base],
       ['worktree', 'add', '--detach', worktree, `origin/${base}`],
     ],
-    claude: ['claude', ['-p', `/relevo:go ${issue}`, ...runFlags(config)]],
+    claude: command,
     // Without this the agent may start a subagent in the background and end the run before it finishes.
-    env: { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' },
+    env: isAntigravity ? {} : { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' },
   };
 }
 
@@ -45,6 +68,7 @@ export function runLocal({ issue, config, runner, workflowPresent = false, dryRu
     return { status: 2, worktree: null, removed: false, messages: ['not inside a git repository'] };
   }
   const plan = planLocalRun({ issue: String(issue), repoRoot, config });
+  const isAntigravity = config.agent?.build === 'antigravity';
 
   if (dryRun) {
     say(`worktree: ${plan.worktree} (from origin/${plan.base})`);
@@ -84,7 +108,10 @@ export function runLocal({ issue, config, runner, workflowPresent = false, dryRu
     status = runner.stream(plan.claude[0], plan.claude[1], { cwd: plan.worktree, env: plan.env });
   } catch (err) {
     status = err.code === 'ENOENT' ? 127 : 1;
-    say(err.code === 'ENOENT' ? 'the claude command was not found: install Claude Code and the Relevo plugin' : `the run could not start: ${err.message}`);
+    const missing = config.agent?.build === 'antigravity'
+      ? 'the agy or node command was not found: install the Antigravity CLI'
+      : 'the claude command was not found: install Claude Code and the Relevo plugin';
+    say(err.code === 'ENOENT' ? missing : `the run could not start: ${err.message}`);
   }
 
   if (status === 0) {
@@ -97,6 +124,7 @@ export function runLocal({ issue, config, runner, workflowPresent = false, dryRu
       return { status: 0, worktree: plan.worktree, removed: false, messages };
     }
   }
+  if (isAntigravity && status === 2) say('the run guard refused to start (usage error): see its message above');
   say(`the run ended with status ${status}; the worktree is kept for inspection: ${plan.worktree}`);
   return { status, worktree: plan.worktree, removed: false, messages };
 }