@elalfner/relevo 0.4.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "relevo",
   "displayName": "Relevo",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An automatic issue-to-merge workflow where an agent builds and people verify.",
   "author": {
     "name": "Elias Alfaro"

package/README.es.md

@@ -33,6 +33,8 @@ npm install -g @elalfner/relevo
 relevo install
 ```
 
+Para usar Relevo desde Antigravity (el IDE, la App o la CLI), ejecuta `relevo init`: pregunta qué herramientas usa tu equipo e instala un plugin generado para cada una. Los detalles están en [Instalación](docs/install.es.md#otras-herramientas-antigravity).
+
 Reinicia Claude Code en tu proyecto y ejecuta `/relevo:doctor` para ver qué falta todavía. Qué necesitas y los primeros pasos están en [Instalación](docs/install.es.md).
 
 ## Cómo funciona

package/README.md

@@ -33,6 +33,8 @@ npm install -g @elalfner/relevo
 relevo install
 ```
 
+To use Relevo from Antigravity (the IDE, the App or the CLI), run `relevo init`: it asks which tools your team uses and installs a plugin rendered for each. Details in [Install](docs/install.md#other-tools-antigravity).
+
 Restart Claude Code in your project and run `/relevo:doctor` to see what is still missing. What you need and the first steps are in [Install](docs/install.md).
 
 ## How it works

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elalfner/relevo",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Relevo: an automatic issue-to-merge workflow where an agent builds and people verify.",
   "type": "module",
   "license": "MIT",

package/scripts/agent-guard.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// The run guard and the settings of an Antigravity run. Usage:
+//   node scripts/agent-guard.mjs settings --out <file> [--platform <name>] [--config relevo.yml] [--plugin-root <dir>]
+//       writes the user-level settings of `agy` for the run: the key provider, the denied web and the allowed commands
+//   node scripts/agent-guard.mjs run --prompt <text> --timeout-minutes <n> --summary <file> [--config relevo.yml]
+//       [--max-turns <n>] [--max-tokens <n>] [--github-output <file>] [--agy <path>]
+//       starts `agy -p` under the limits and writes the summary of the run (the same shape that run-usage.mjs reads).
+//       The limits are limits.run_max_turns and limits.run_max_tokens of relevo.yml; a flag can only make one lower.
+// exit codes of `run`: 0 success, 1 the agent failed, 10 a tool was refused, 11 turn limit, 12 token limit, 13 time limit,
+// 14 no result; 2 bad usage. The agent's output is never printed: the log has one line per step, and the final answer.
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXIT, agySettings, runGuard } from './lib/agent-guard.mjs';
+import { loadConfig } from './lib/config.mjs';
+import { resolveProfile } from './lib/stack-profile.mjs';
+
+const [mode, ...rest] = process.argv.slice(2);
+const arg = (name) => {
+  const i = rest.indexOf(`--${name}`);
+  return i === -1 ? undefined : rest[i + 1];
+};
+const usage = (message) => {
+  console.error(`${message}\nusage: agent-guard.mjs settings --out <file> [--platform <name>] | run --prompt <text> --max-turns <n> --max-tokens <n> --timeout-minutes <n> --summary <file>`);
+  process.exit(EXIT.usage);
+};
+const positive = (name, fallback = null) => {
+  const given = arg(name);
+  const v = given === undefined && fallback !== null ? fallback : Number(given);
+  if (!Number.isFinite(v) || v <= 0) usage(`--${name} must be a number greater than zero${fallback === null ? '' : ' (or set it in relevo.yml)'}`);
+  return v;
+};
+const lower = (flag, fromConfig) => (arg(flag) === undefined || fromConfig === null ? positive(flag, fromConfig) : Math.min(positive(flag), fromConfig));
+
+if (mode === 'settings') {
+  const out = arg('out');
+  if (!out) usage('settings needs --out');
+  const pluginRoot = resolve(arg('plugin-root') ?? resolve(dirname(fileURLToPath(import.meta.url)), '..'));
+  let profile = null;
+  const configPath = resolve(arg('config') ?? 'relevo.yml');
+  if (existsSync(configPath)) {
+    const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+    if (!loaded.ok) usage(`relevo.yml is invalid:\n${loaded.errors.map((e) => `  ${e.message}`).join('\n')}`);
+    const names = Object.keys(loaded.config.platforms);
+    const name = arg('platform') ?? (names.length === 1 ? names[0] : undefined);
+    if (!name || !loaded.config.platforms[name]) usage(`the platform must be one of: ${names.join(', ')}`);
+    const base = dirname(configPath);
+    const read = (p) => {
+      const file = p.startsWith('/') ? p : resolve(base, p);
+      return existsSync(file) ? readFileSync(file, 'utf8') : null;
+    };
+    const resolved = resolveProfile({ platform: loaded.config.platforms[name], pluginRoot, read });
+    if (!resolved.ok) usage(resolved.errors.join('\n'));
+    profile = resolved.profile;
+  }
+  mkdirSync(dirname(resolve(out)), { recursive: true });
+  writeFileSync(resolve(out), `${JSON.stringify(agySettings({ profile }), null, 2)}\n`);
+  console.log(`settings written to ${out}`);
+  process.exit(0);
+}
+
+if (mode === 'run') {
+  const prompt = arg('prompt');
+  const summaryFile = arg('summary');
+  if (!prompt || !summaryFile) usage('run needs --prompt and --summary');
+  let fromConfig = { turns: null, tokens: null };
+  const configPath = resolve(arg('config') ?? 'relevo.yml');
+  if (arg('config') !== undefined || existsSync(configPath)) {
+    if (!existsSync(configPath)) usage(`relevo.yml not found at ${configPath}`);
+    const loaded = loadConfig(readFileSync(configPath, 'utf8'));
+    if (!loaded.ok) usage(`relevo.yml is invalid:\n${loaded.errors.map((e) => `  ${e.message}`).join('\n')}`);
+    fromConfig = { turns: loaded.config.limits.run_max_turns ?? null, tokens: loaded.config.limits.run_max_tokens ?? null };
+  }
+  const limits = { turns: lower('max-turns', fromConfig.turns), tokens: lower('max-tokens', fromConfig.tokens), minutes: positive('timeout-minutes') };
+  const agy = arg('agy') ?? 'agy';
+  const args = ['-p', prompt, '--output-format', 'stream-json', '--print-timeout', `${Math.ceil(limits.minutes) + 1}m`];
+  const start = (command, a) => {
+    const child = spawn(command, a, { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.on('error', (err) => child.stderr.emit('data', `${err.message}\n`));
+    return { pid: child.pid, stdout: child.stdout, stderr: child.stderr, kill: (signal) => process.kill(-child.pid, signal), on: (ev, cb) => child.on(ev, cb) };
+  };
+  const { code, summary, response } = await runGuard({ command: agy, args, limits, spawn: start, log: (line) => console.error(line) });
+  mkdirSync(dirname(resolve(summaryFile)), { recursive: true });
+  writeFileSync(resolve(summaryFile), `${JSON.stringify(summary, null, 2)}\n`);
+  if (arg('github-output')) appendFileSync(arg('github-output'), `execution_file=${resolve(summaryFile)}\n`);
+  if (response) console.log(response);
+  console.error(`relevo guard: ${summary.num_turns} turns, ${summary.usage.input_tokens + summary.usage.output_tokens} tokens, ${summary.duration_seconds}s, exit ${code}`);
+  process.exit(code);
+}
+
+usage(`unknown mode "${mode ?? ''}"`);

package/scripts/cli.mjs

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
-// relevo install | update | doctor | version. See scripts/lib/cli.mjs. `install` without --scope asks where, in a
-// terminal, with the project preselected.
+// relevo init | install | update | doctor | version. See scripts/lib/cli.mjs and scripts/lib/init-tools.mjs. `install`
+// and `init` without --scope ask where, in a terminal, with the project preselected; `init` also asks for the tools.
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { USAGE, execute, isInsideGitRepo, parseArgs, resolveScope, scopeChoices } from './lib/cli.mjs';
-import { select } from './lib/select.mjs';
+import { TOOLS, initScopeChoices, parseInitArgs, repoRoot, resolveInitScope, runInit, runUpdate } from './lib/init-tools.mjs';
+import { select, selectMany } from './lib/select.mjs';
 
 const here = (p) => fileURLToPath(new URL(p, import.meta.url));
-const parsed = parseArgs(process.argv.slice(2));
+const argv = process.argv.slice(2);
+const parsed = argv[0] === 'init' ? parseInitArgs(argv.slice(1)) : parseArgs(argv);
 if (parsed.error) {
   process.stderr.write(`${parsed.error}\n${USAGE}\n`);
   process.exit(2);
@@ -24,11 +27,48 @@ const run = (cmd, args) => {
 };
 const has = (cmd) => spawnSync(cmd, ['--version'], { encoding: 'utf8' }).error === undefined;
 const version = JSON.parse(readFileSync(here('../package.json'), 'utf8')).version;
+const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+const deps = { run, has, version, doctorScript: here('./doctor.mjs'), cwd: process.cwd(), packageRoot: here('..'), home: homedir(), root: repoRoot(run) };
+const cancel = () => {
+  process.stdout.write('Cancelled: nothing was installed.\n');
+  process.exit(130);
+};
+const finish = ({ code, lines }) => {
+  process.stdout.write(`${lines.join('\n')}\n`);
+  process.exit(code);
+};
+
+if (parsed.command === 'init') {
+  const inRepo = isInsideGitRepo(run);
+  let { tools, scope } = parsed;
+  if (!tools) {
+    if (!interactive) {
+      process.stderr.write(`init needs --tools without a terminal: ${TOOLS.map((t) => t.value).join(', ')}\n`);
+      process.exit(2);
+    }
+    tools = await selectMany({ title: 'Which tools does your team use?', choices: TOOLS, initial: ['claude'], input: process.stdin, output: process.stdout });
+    if (tools === null) cancel();
+    if (tools.length === 0) {
+      process.stdout.write('No tool chosen: nothing was installed.\n');
+      process.exit(0);
+    }
+  }
+  const resolved = resolveInitScope({ given: scope, interactive: interactive && !parsed.yes, inRepo });
+  if (resolved.ask) {
+    const choices = initScopeChoices({ cwd: process.cwd(), inRepo });
+    scope = await select({ title: 'Where should Relevo be installed?', choices, defaultIndex: Math.max(0, choices.findIndex((c) => c.value === resolved.preferred)), input: process.stdin, output: process.stdout });
+    if (scope === null) cancel();
+  } else {
+    scope = resolved.scope;
+    if (resolved.reason) process.stdout.write(`relevo: ${resolved.reason}.\n`);
+  }
+  finish(runInit({ tools, scope, force: Boolean(parsed.force) }, deps));
+}
 
 let { scope } = parsed;
 if (parsed.command === 'install' && has('claude')) {
   const inRepo = isInsideGitRepo(run);
-  const resolved = resolveScope({ given: scope, interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY), inRepo });
+  const resolved = resolveScope({ given: scope, interactive, inRepo });
   if (resolved.ask) {
     const choices = scopeChoices({ cwd: process.cwd(), inRepo });
     scope = await select({
@@ -38,16 +78,12 @@ if (parsed.command === 'install' && has('claude')) {
       input: process.stdin,
       output: process.stdout
     });
-    if (scope === null) {
-      process.stdout.write('Cancelled: nothing was installed.\n');
-      process.exit(130);
-    }
+    if (scope === null) cancel();
   } else {
     scope = resolved.scope;
     if (resolved.reason) process.stdout.write(`relevo: ${resolved.reason}.\n`);
   }
 }
 
-const { code, lines } = execute({ command: parsed.command, scope }, { run, has, version, doctorScript: here('./doctor.mjs'), cwd: process.cwd() });
-process.stdout.write(`${lines.join('\n')}\n`);
-process.exit(code);
+if (parsed.command === 'update') finish(runUpdate({ scope, force: Boolean(parsed.force) }, deps));
+finish(execute({ command: parsed.command, scope }, deps));

package/scripts/doctor.mjs

@@ -6,6 +6,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { adapterFacts } from './lib/adapters/install.mjs';
 import { gatherFacts, readOnlyGh, renderReport, runChecks } from './lib/doctor.mjs';
 
 const arg = (name) => {
@@ -31,7 +32,16 @@ const readFolder = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e
   return e.isFile() ? [{ path: e.name, content: readFileSync(path) }] : [];
 });
 
+const repoTop = (() => {
+  try {
+    return tool('git', ['rev-parse', '--show-toplevel']).trim() || null;
+  } catch {
+    return null;
+  }
+})();
+
 const facts = gatherFacts({
+  adapters: () => adapterFacts({ root: repoTop, home: homedir() }),
   tool,
   gh: readOnlyGh(gh),
   exists: existsSync,

package/scripts/init.mjs

@@ -59,6 +59,7 @@ try {
 
 const templates = {
   config: readFileSync(`${root}/templates/relevo.yml`, 'utf8'),
+  agentBlocks: answers.agentBuild && answers.agentBuild !== 'claude' ? readFileSync(`${root}/templates/agents/${answers.agentBuild}-step.yml`, 'utf8') : null,
   workflows: Object.fromEntries(WORKFLOW_FILES.map((f) => [f, readFileSync(`${root}/templates/workflows/${f}`, 'utf8')])),
 };
 const keepPaths = ['openspec/specs/.gitkeep', 'openspec/changes/archive/.gitkeep'];

package/scripts/lib/adapters/antigravity.mjs

@@ -0,0 +1,99 @@
+// Renders Relevo as a native Antigravity plugin: plugin.json, the skills, the agents and a copy of what the scripts
+// need. Pure: it returns the text files and what to copy, and the caller writes them. What is changed, and why, was
+// seen on Antigravity CLI 1.4.4 (docs/pilot-findings.md): the script path variable is not substituted, an agent needs
+// its own tool list, `relevo:dev` is not a valid agent name, and a subagent call does not block.
+import { antigravityToolsOf } from './tools.mjs';
+
+export const PLUGIN_NAME = 'relevo';
+export const COPIED_DIRS = ['scripts', 'stacks', 'templates'];
+export const COPIED_FILES = ['LICENSE', 'NOTICE'];
+
+// The skill `go` tells the agent to wait for each subagent. In Antigravity the call returns at once and the result
+// arrives later as a message, so the wait has to be said in other words. The heading is looked for exactly: if the
+// source changes it, the render fails instead of keeping a sentence that is wrong here.
+const FOREGROUND_HEADING = '## Subagents run in the foreground';
+const FOREGROUND_FOR_ANTIGRAVITY = `${FOREGROUND_HEADING}
+
+Call \`relevo-dev\` and \`relevo-qa\` with \`invoke_subagent\`, one at a time. In Antigravity, subagents run in the background and the report arrives later as a message. After calling \`invoke_subagent\`, do NOT poll with \`manage_subagents\` or loop in any way; simply output that you are waiting for the subagent's report and end your turn without further tool calls. Antigravity will automatically reactivate you when the subagent finishes. Once reactivated with the subagent report, verify it, terminate the subagent using \`manage_subagents\` (\`Action: "kill"\`, \`ConversationIds: ["<subagent_id>"]\`) to free context, and proceed to the next step. If you cannot get a report or the subagent fails, take the failure path.
+`;
+
+const WHERE_RUNS_HEADING = '## Where it runs';
+const WHERE_RUNS_FOR_ANTIGRAVITY = (pluginDir) => `${WHERE_RUNS_HEADING}
+
+In the cloud the workflow starts this skill with the decision already made. A person can also start it on their machine: \`node ${pluginDir}/scripts/go-local.mjs <issue>\` runs it in a separate git worktree, with the same limits and tool lists as the workflow, and removes the worktree when it ends cleanly. Started by hand without that script, it needs a clean working tree (the preflight below stops otherwise).
+
+**When \`$ARGUMENTS\` has \`--local\`**, do not build in this session: run \`node ${pluginDir}/scripts/go-local.mjs <issue>\`, show what it prints, and stop. The build happens in the process that script starts, in its own worktree and with the closed tool lists, which a plain session does not have.
+
+**In an interactive Antigravity chat session** (started by hand without \`--decision\` and without \`--local\`), do not switch branches or build directly in this workspace root (multiple chat tabs share this workspace and will collide). Instead, isolate the build in an ephemeral worktree:
+1. Call \`invoke_subagent\` with \`TypeName: "self"\`, \`Role: "relevo-builder"\`, and \`Workspace: 'share'\`, passing the build instructions for the issue.
+2. Call \`schedule\` with \`DurationSeconds: 1200\` and \`TimerCondition: "<builder_conversation_id>"\` as a watchdog timer.
+3. Yield your turn without further tool calls. If the builder completes, the timer cancels early and you are reactivated with its report. If the timer fires, the builder timed out.
+4. Call \`manage_subagents\` with \`Action: "kill"\` and \`ConversationIds: ["<builder_conversation_id>"]\` to destroy the ephemeral worktree and clean up session state.
+5. If the builder succeeded, report the outcome here; if it timed out or failed, take the failure path. The repository root remains clean on its base branch.
+`;
+
+const TOOL_WORDS = { Read: 'view_file', Write: 'write_to_file', Edit: 'replace_file_content' };
+
+const q = (s) => JSON.stringify(String(s));
+
+/** The path of the plugin is written into a shell command, so it must not need quoting. */
+function checkPluginDir(dir) {
+  if (!dir || !/^\//.test(dir) && !/^[A-Za-z]:[\\/]/.test(dir)) throw new Error(`the plugin folder must be an absolute path, got "${dir}"`);
+  if (/[\s"'`$&;|<>()\\]/.test(dir.replace(/^[A-Za-z]:\\/, ''))) {
+    throw new Error(`the plugin folder "${dir}" has a space or a shell character, which the commands in the skills cannot carry; choose another folder`);
+  }
+}
+
+/** The text of a skill, an agent or a reference, as Antigravity needs it. */
+export function adaptText(text, { pluginDir }) {
+  let out = String(text).split('${CLAUDE_PLUGIN_ROOT}').join(pluginDir);
+  out = out.replace(/relevo:(dev|qa)(?![\w-])/g, 'relevo-$1');
+  for (const [from, to] of Object.entries(TOOL_WORDS)) out = out.split(`\`${from}\``).join(`\`${to}\``);
+  if (out.includes(FOREGROUND_HEADING)) {
+    const re = new RegExp(`${FOREGROUND_HEADING}\\n\\n[^\\n]*\\n`);
+    if (!re.test(out)) throw new Error(`"${FOREGROUND_HEADING}" is no longer followed by one paragraph: update the Antigravity renderer`);
+    out = out.replace(re, FOREGROUND_FOR_ANTIGRAVITY);
+  }
+  if (out.includes(WHERE_RUNS_HEADING)) {
+    const re = new RegExp(`${WHERE_RUNS_HEADING}\\n\\n[\\s\\S]*?(?=\\n\\n## OpenSpec commands)`);
+    if (!re.test(out)) throw new Error(`"${WHERE_RUNS_HEADING}" block could not be matched: update the Antigravity renderer`);
+    out = out.replace(re, WHERE_RUNS_FOR_ANTIGRAVITY(pluginDir).trimEnd());
+  }
+  return out;
+}
+
+function skillFile(skill, ctx) {
+  const { meta } = skill;
+  const lines = ['---', `name: ${meta.name ?? skill.name}`, `description: ${q(meta.description)}`];
+  if (meta['argument-hint'] !== undefined) lines.push(`argument-hint: ${q(meta['argument-hint'])}`);
+  if (String(meta['disable-model-invocation']) === 'true') lines.push('disable-model-invocation: true');
+  lines.push('---', '');
+  return { path: `skills/${skill.name}/SKILL.md`, content: `${lines.join('\n')}\n${adaptText(skill.body, ctx).replace(/^\n+/, '')}` };
+}
+
+function agentFile(agent, ctx) {
+  const name = `${PLUGIN_NAME}-${agent.name}`;
+  const tools = antigravityToolsOf(agent.meta);
+  const head = ['---', `name: ${name}`, `description: ${q(agent.meta.description)}`, `tools: [${tools.join(', ')}]`, '---', ''];
+  return { path: `agents/${name}.md`, content: `${head.join('\n')}\n${adaptText(agent.body, ctx).replace(/^\n+/, '')}` };
+}
+
+/**
+ * source: the result of readSource. ctx.pluginDir: the absolute folder where the plugin will live.
+ * Returns { files: [{ path, content }], copy: { dirs, files } } with paths relative to the plugin folder; `copy`
+ * says what to take from the package unchanged.
+ */
+export function renderAntigravity(source, ctx) {
+  checkPluginDir(ctx.pluginDir);
+  const m = source.manifest;
+  const manifest = { name: PLUGIN_NAME, displayName: m.displayName ?? 'Relevo', version: source.version, description: m.description, author: m.author };
+  const files = [{ path: 'plugin.json', content: `${JSON.stringify(manifest, null, 2)}\n` }];
+  for (const skill of source.skills) {
+    files.push(skillFile(skill, ctx));
+    for (const f of skill.files) {
+      files.push({ path: `skills/${skill.name}/${f.path}`, content: f.path.endsWith('.md') ? adaptText(f.content, ctx) : f.content });
+    }
+  }
+  for (const agent of source.agents) files.push(agentFile(agent, ctx));
+  return { files, copy: { dirs: COPIED_DIRS, files: COPIED_FILES } };
+}

package/scripts/lib/adapters/index.mjs

@@ -0,0 +1,6 @@
+// One renderer per tool. A tool that Relevo can set up appears here and nowhere else in the core.
+import { renderAntigravity } from './antigravity.mjs';
+
+export const RENDERERS = {
+  antigravity: { label: 'Antigravity', render: renderAntigravity }
+};

package/scripts/lib/adapters/install.mjs

@@ -0,0 +1,127 @@
+// Puts a rendered plugin where a tool reads it, and keeps a record of what was put there so that an update can tell a
+// file that is out of date from one that a person edited. For the project the plugin is written into
+// `.agents/plugins/relevo/`; for the machine it is staged and installed with `agy plugin install`, which copies it to
+// `~/.gemini/config/plugins/relevo/` (the path the text of the skills already carries, see antigravity.mjs).
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { PLUGIN_NAME, renderAntigravity } from './antigravity.mjs';
+import { readSource } from './source.mjs';
+
+export const RECORD = '.relevo-adapter.json';
+
+export const pluginDirFor = ({ scope, root, home }) =>
+  scope === 'project' ? join(root, '.agents', 'plugins', PLUGIN_NAME) : join(home, '.gemini', 'config', 'plugins', PLUGIN_NAME);
+
+const sha = (buf) => createHash('sha256').update(buf).digest('hex');
+
+/** { 'relative/path': sha256 } of every file under dir, except the record itself. */
+export function hashTree(dir, base = dir) {
+  const out = {};
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) Object.assign(out, hashTree(full, base));
+    else if (e.name !== RECORD && e.name !== '.DS_Store') out[full.slice(base.length + 1).split('\\').join('/')] = sha(readFileSync(full));
+  }
+  return out;
+}
+
+export function readRecord(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, RECORD), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** The recorded files that are missing or whose content changed since they were written. */
+export function editedFiles(dir) {
+  const record = readRecord(dir);
+  if (!record) return [];
+  const now = existsSync(dir) ? hashTree(dir) : {};
+  return Object.entries(record.files).filter(([path, hash]) => now[path] !== hash).map(([path]) => path);
+}
+
+function writeTree(rendered, { packageRoot, dest }) {
+  for (const f of rendered.files) {
+    mkdirSync(dirname(join(dest, f.path)), { recursive: true });
+    writeFileSync(join(dest, f.path), f.content);
+  }
+  for (const d of rendered.copy.dirs) cpSync(join(packageRoot, d), join(dest, d), { recursive: true });
+  for (const f of rendered.copy.files) if (existsSync(join(packageRoot, f))) cpSync(join(packageRoot, f), join(dest, f));
+}
+
+const where = { project: (root) => `.agents/plugins/relevo of ${root}, so commit it to share it`, machine: () => '~/.gemini/config/plugins/relevo, for the IDE, the App and the CLI' };
+
+/**
+ * Renders and installs the Antigravity plugin for the scope ('project' | 'machine'). `update` only changes the
+ * sentence it prints. A file edited by hand stops it unless `force`. Returns { code, lines }; nothing is changed
+ * when it stops before writing.
+ */
+export function installAntigravity({ packageRoot, scope, root, home, run, has, force = false, update = false }) {
+  if (scope === 'machine' && !has('agy')) {
+    return { code: 1, lines: ['Antigravity CLI is required for the machine scope and "agy" was not found on the path.', 'Install it from https://antigravity.google/docs/getting-started?tab=cli and run this command again; nothing was changed.'] };
+  }
+  if (scope === 'project' && !root) return { code: 1, lines: ['The project scope needs a git repository and this folder is not inside one; nothing was changed.', 'Use --scope machine, or run the command inside the repository.'] };
+  const dest = pluginDirFor({ scope, root, home });
+  const edited = editedFiles(dest);
+  if (edited.length && !force) {
+    return { code: 1, lines: [`These files of ${dest} were edited by hand and would be overwritten:`, ...edited.map((f) => `  ${f}`), 'Nothing was changed. Run the command again with --force to overwrite them.'] };
+  }
+  let source;
+  try {
+    source = readSource(packageRoot);
+  } catch (err) {
+    return { code: 1, lines: [`Could not read the Relevo package at ${packageRoot}: ${err.message}`] };
+  }
+  let rendered;
+  try {
+    rendered = renderAntigravity(source, { pluginDir: dest });
+  } catch (err) {
+    return { code: 1, lines: [`Could not render the plugin: ${err.message}`, 'Nothing was changed.'] };
+  }
+  const lines = [];
+  const stageRoot = scope === 'machine' ? mkdtempSync(join(tmpdir(), 'relevo-stage-')) : null;
+  const target = scope === 'machine' ? join(stageRoot, PLUGIN_NAME) : dest;
+  try {
+    if (scope === 'project') rmSync(dest, { recursive: true, force: true });
+    writeTree(rendered, { packageRoot, dest: target });
+    writeFileSync(join(target, RECORD), `${JSON.stringify({ tool: 'antigravity', scope, package: source.version, files: hashTree(target) }, null, 2)}\n`);
+    if (scope === 'machine') {
+      if (existsSync(dest)) {
+        const r = run('agy', ['plugin', 'uninstall', PLUGIN_NAME]);
+        if (r.code !== 0) return { code: r.code || 1, lines: [`"agy plugin uninstall ${PLUGIN_NAME}" failed, so the old plugin was kept:`, r.output.trimEnd()] };
+      }
+      const r = run('agy', ['plugin', 'install', target]);
+      if (r.output.trim()) lines.push(r.output.trimEnd());
+      if (r.code !== 0) return { code: r.code || 1, lines: [...lines, `"agy plugin install" failed. Fix the cause and run the command again: it is safe to repeat.`] };
+      if (!existsSync(join(dest, 'plugin.json'))) {
+        return { code: 1, lines: [...lines, `agy installed the plugin, but not in ${dest}, where the commands of the skills point. Nothing else was done; report this with the version of agy.`] };
+      }
+    }
+  } finally {
+    if (stageRoot) rmSync(stageRoot, { recursive: true, force: true });
+  }
+  lines.push(`Antigravity: ${update ? 'updated' : 'installed'} Relevo ${source.version} in ${where[scope](root)}.`, 'Open Antigravity and type /relevo:doctor.');
+  return { code: 0, lines };
+}
+
+/** What doctor needs about each rendered plugin: { scope, dir, package, edited, missing }. */
+export function adapterFacts({ root, home }) {
+  return findRecords({ root, home }).map(({ scope, dir, record }) => {
+    const now = hashTree(dir);
+    const missing = Object.keys(record.files).filter((p) => !(p in now));
+    const edited = Object.entries(record.files).filter(([p, h]) => p in now && now[p] !== h).map(([p]) => p);
+    return { scope, dir, package: record.package, edited, missing };
+  });
+}
+
+/** The rendered plugins that exist for this repository and this machine: [{ scope, dir, record }]. */
+export function findRecords({ root, home }) {
+  return ['project', 'machine']
+    .filter((scope) => scope === 'machine' || root)
+    .map((scope) => ({ scope, dir: pluginDirFor({ scope, root, home }) }))
+    .map((x) => ({ ...x, record: readRecord(x.dir) }))
+    .filter((x) => x.record?.tool === 'antigravity');
+}

package/scripts/lib/adapters/source.mjs

@@ -0,0 +1,65 @@
+// Reads what Relevo is made of, in Claude Code's format, so that a renderer can write it for another tool. Nothing is
+// written here and nothing is interpreted beyond the frontmatter: a renderer decides what to change.
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from '../yaml-lite.mjs';
+
+/** { head, body }: the frontmatter text (no fences) and what follows it; head is null when there is none. */
+export function splitFrontmatter(text) {
+  const m = String(text).replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  return m ? { head: m[1], body: m[2] } : { head: null, body: String(text) };
+}
+
+const walk = (dir, base = dir) =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) return walk(full, base);
+    return [full.slice(base.length + 1).split('\\').join('/')];
+  });
+
+const isDir = (p) => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * { version, manifest, skills, agents } read from a Relevo checkout or an installed package.
+ * skill: { name, meta, body, files: [{ path, content }] }  (files are everything beside SKILL.md, text only)
+ * agent: { name, meta, body }
+ */
+export function readSource(root) {
+  const manifest = JSON.parse(readFileSync(join(root, '.claude-plugin', 'plugin.json'), 'utf8'));
+  const version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+
+  const skillsDir = join(root, 'skills');
+  const skills = readdirSync(skillsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort()
+    .map((name) => {
+      const dir = join(skillsDir, name);
+      const { head, body } = splitFrontmatter(readFileSync(join(dir, 'SKILL.md'), 'utf8'));
+      if (head === null) throw new Error(`skills/${name}/SKILL.md has no frontmatter`);
+      const files = walk(dir)
+        .filter((f) => f !== 'SKILL.md')
+        .map((path) => ({ path, content: readFileSync(join(dir, path), 'utf8') }));
+      return { name, meta: parse(head), body, files };
+    });
+
+  const agentsDir = join(root, 'agents');
+  const agents = !isDir(agentsDir)
+    ? []
+    : readdirSync(agentsDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((f) => {
+          const { head, body } = splitFrontmatter(readFileSync(join(agentsDir, f), 'utf8'));
+          if (head === null) throw new Error(`agents/${f} has no frontmatter`);
+          return { name: f.slice(0, -3), meta: parse(head), body };
+        });
+
+  return { version, manifest, skills, agents };
+}

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;
+}