@elalfner/relevo 0.4.0 → 0.6.0

package/scripts/lib/go-worktree.mjs

@@ -0,0 +1,85 @@
+// The worktree of an interactive `go` in Claude Code. Implements "An interactive Claude Code run builds in its own
+// worktree" of the execution-modes specification: the skill makes the worktree here, enters it with EnterWorktree, and
+// asks for its removal here when the run ends cleanly.
+//
+// Every process goes through an injected runner so the logic is tested without git or a network:
+//   capture(cmd, args, { cwd }) -> stdout (throws when the command fails)
+
+import { worktreePath } from './worktree-path.mjs';
+
+/** Exit codes of `go-worktree.mjs`. `exists` and `linked` are answers, not failures: the skill reads them. */
+export const EXIT = { ok: 0, failed: 1, usage: 2, exists: 3, linked: 4 };
+
+const fail = (status, message) => ({ status, worktree: null, messages: [message] });
+// git prints progress ("Preparing worktree ...") before the reason, so the reason is the `fatal:` or `error:` line, or the last one.
+function firstLine(err) {
+  const lines = String(err.stderr ?? err.message).trim().split('\n').map((l) => l.trim()).filter(Boolean);
+  return lines.find((l) => /^(fatal|error):/.test(l)) ?? lines.at(-1) ?? 'git failed';
+}
+
+function context(issue, runner) {
+  if (!/^\d+$/.test(String(issue))) return { early: fail(EXIT.usage, 'give the issue number: go-worktree.mjs create|remove <issue>') };
+  try {
+    const repoRoot = runner.capture('git', ['rev-parse', '--show-toplevel'], {}).trim();
+    const [gitDir, commonDir] = runner
+      .capture('git', ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'], { cwd: repoRoot })
+      .trim()
+      .split('\n');
+    return { repoRoot, linked: gitDir !== commonDir };
+  } catch {
+    return { early: fail(EXIT.usage, 'not inside a git repository (or git is older than 2.31)') };
+  }
+}
+
+/**
+ * Make the worktree of an issue from `origin/<base>`. `linked` when the session is already in a linked worktree (the
+ * build runs where it is), `exists` when the worktree of the issue is already there (the same issue twice).
+ */
+export function createWorktree({ issue, config, runner, exists = () => false }) {
+  const ctx = context(issue, runner);
+  if (ctx.early) return ctx.early;
+  if (ctx.linked) {
+    return fail(EXIT.linked, 'this session is already in a linked worktree: build here, no worktree is made');
+  }
+  const base = config.branches.base;
+  const worktree = worktreePath(ctx.repoRoot, issue);
+  if (exists(worktree)) {
+    return {
+      status: EXIT.exists,
+      worktree,
+      messages: [`${worktree} already exists: another run is building #${issue}, or a failed one left it. Finish it or remove it first (git worktree remove --force "${worktree}")`],
+    };
+  }
+  try {
+    // A folder deleted by hand leaves a registration that makes `worktree add` fail; prune only drops those.
+    runner.capture('git', ['worktree', 'prune'], { cwd: ctx.repoRoot });
+    runner.capture('git', ['fetch', 'origin', base], { cwd: ctx.repoRoot });
+    runner.capture('git', ['worktree', 'add', '--detach', worktree, `origin/${base}`], { cwd: ctx.repoRoot });
+  } catch (err) {
+    return fail(EXIT.failed, `could not prepare the worktree: ${firstLine(err)}`);
+  }
+  return { status: EXIT.ok, worktree, base, messages: [] };
+}
+
+/** Remove the worktree of an issue, after a clean end. Run it from the main working tree, not from inside. */
+export function removeWorktree({ issue, runner, exists = () => true }) {
+  const ctx = context(issue, runner);
+  if (ctx.early) return ctx.early;
+  if (ctx.linked) return fail(EXIT.linked, 'leave the worktree first (ExitWorktree with keep), then remove it from the main working tree');
+  const worktree = worktreePath(ctx.repoRoot, issue);
+  if (!exists(worktree)) {
+    // The folder may be gone while git still lists it: drop that registration so the issue can be built again.
+    try {
+      runner.capture('git', ['worktree', 'prune'], { cwd: ctx.repoRoot });
+    } catch (err) {
+      return { status: EXIT.failed, worktree, messages: [`could not prune the worktrees: ${firstLine(err)}; run git worktree prune`] };
+    }
+    return { status: EXIT.ok, worktree, messages: [`${worktree} is not there: nothing to remove`] };
+  }
+  try {
+    runner.capture('git', ['worktree', 'remove', '--force', worktree], { cwd: ctx.repoRoot });
+  } catch (err) {
+    return { status: EXIT.failed, worktree, messages: [`could not remove ${worktree}: ${firstLine(err)}; run git worktree remove --force "${worktree}"`] };
+  }
+  return { status: EXIT.ok, worktree, messages: [] };
+}

package/scripts/lib/init-tools.mjs

@@ -0,0 +1,97 @@
+// `relevo init`: set up Relevo for the tools a team uses, in the project or on the machine, and `relevo update` for the
+// plugins that were rendered. Claude Code keeps being installed by `claude plugin` (see cli.mjs); another tool gets a
+// plugin rendered from the same sources (see adapters/). Everything that talks to the outside is injected.
+import { execute } from './cli.mjs';
+import { findRecords, installAntigravity } from './adapters/install.mjs';
+
+export const TOOLS = [
+  { value: 'claude', label: 'Claude Code: the plugin, which updates itself and adds no files to the repository' },
+  { value: 'antigravity', label: 'Antigravity: the IDE, the App and the CLI, with a plugin rendered for them' }
+];
+export const INIT_SCOPES = ['project', 'machine'];
+
+/** Parses what follows `init`: { tools, scope, yes, force } or { error }. `user` is accepted for `machine`. */
+export function parseInitArgs(rest) {
+  const out = { command: 'init', tools: null, scope: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    const take = (name) => (arg === name ? rest[++i] : arg.slice(name.length + 1));
+    if (arg === '--tools' || arg.startsWith('--tools=')) out.tools = String(take('--tools') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--scope' || arg.startsWith('--scope=')) out.scope = take('--scope');
+    else if (arg === '--yes' || arg === '-y') out.yes = true;
+    else if (arg === '--force') out.force = true;
+    else return { error: `unknown option "${arg}"` };
+  }
+  if (out.scope === 'user') out.scope = 'machine';
+  if (out.scope !== null && !INIT_SCOPES.includes(out.scope)) return { error: `the scope of init must be project or machine` };
+  if (out.tools) {
+    const unknown = out.tools.filter((t) => !TOOLS.some((x) => x.value === t));
+    if (unknown.length) return { error: `unknown tool "${unknown[0]}"; the tools are ${TOOLS.map((t) => t.value).join(', ')}` };
+    if (out.tools.length === 0) return { error: '--tools needs at least one tool' };
+  }
+  return out;
+}
+
+/** Like resolveScope of cli.mjs, with the choices project and machine. */
+export function resolveInitScope({ given = null, interactive = false, inRepo = false }) {
+  if (given) return { scope: given };
+  const preferred = inRepo ? 'project' : 'machine';
+  if (interactive) return { ask: true, preferred };
+  const why = inRepo ? 'this folder is inside a git repository, so the project is used' : 'this folder is not inside a git repository, so the machine is used';
+  return { scope: preferred, reason: `no --scope given and no terminal: ${why}` };
+}
+
+export function initScopeChoices({ cwd, inRepo }) {
+  return [
+    { value: 'project', label: `Project (${cwd})${inRepo ? '' : ' [not a git repository]'}: files in the repository, shared with your team` },
+    { value: 'machine', label: 'Machine: every project of this machine' }
+  ];
+}
+
+/** The top folder of the git repository of the current folder, or null. */
+export function repoRoot(run) {
+  const r = run('git', ['rev-parse', '--show-toplevel']);
+  return r.code === 0 && r.output.trim() ? r.output.trim() : null;
+}
+
+const NEXT_STEP = 'Next: /relevo:init (the skill) sets up the labels and the rules of the repository; it is a separate step from this command.';
+
+/** Sets up each tool, in order, and stops at the first failure. Returns { code, lines }. */
+export function runInit({ tools, scope, force = false }, deps) {
+  const lines = [];
+  for (const tool of tools) {
+    lines.push(`== ${TOOLS.find((t) => t.value === tool).label.split(':')[0]}`);
+    const r =
+      tool === 'claude'
+        ? execute({ command: 'install', scope: scope === 'machine' ? 'user' : 'project' }, deps)
+        : installAntigravity({ packageRoot: deps.packageRoot, scope, root: deps.root, home: deps.home, run: deps.run, has: deps.has, force });
+    lines.push(...r.lines);
+    if (r.code !== 0) return { code: r.code, lines };
+  }
+  lines.push(NEXT_STEP);
+  return { code: 0, lines };
+}
+
+/**
+ * Updates Claude Code as before and renders again the plugins that `init` made. With neither, it says what it always
+ * said. The code is the worst of the parts, and each part says what it did.
+ */
+export function runUpdate({ scope = null, force = false }, deps) {
+  const records = findRecords({ root: deps.root, home: deps.home });
+  if (records.length === 0) return execute({ command: 'update', scope }, deps);
+  const lines = [];
+  let code = 0;
+  if (deps.has('claude')) {
+    lines.push('== Claude Code');
+    const r = execute({ command: 'update', scope }, deps);
+    lines.push(...r.lines);
+    code = r.code;
+  }
+  for (const rec of records) {
+    lines.push(`== Antigravity (${rec.scope})`);
+    const r = installAntigravity({ packageRoot: deps.packageRoot, scope: rec.scope, root: deps.root, home: deps.home, run: deps.run, has: deps.has, force, update: true });
+    lines.push(...r.lines);
+    code = code || r.code;
+  }
+  return { code, lines };
+}

package/scripts/lib/init.mjs

@@ -8,12 +8,14 @@
 import { loadConfig } from './config.mjs';
 import { LEGACY_PLATFORMS } from './platforms.mjs';
 import { labelDefinitions } from './labels.mjs';
+import { agentWorkflow } from './agent-workflow.mjs';
 import { OPENSPEC_INSTALL, REQUIRED_SKILLS, SKILL_INSTALL, WORKFLOW_FILES } from './doctor.mjs';
 
 export const REVIEW_MODES = ['none', 'peer', 'roles'];
 
 export const RUNS = ['cloud', 'local', 'both'];
 export const CREDENTIALS = ['api_key', 'subscription'];
+export const AGENT_BUILDS = ['claude', 'antigravity'];
 const API_KEY_LINE = '          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}';
 const TOKEN_LINE = '          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}';
 
@@ -87,7 +89,12 @@ export function renderConfig(template, answers = {}) {
   if (answers.specWriter !== undefined) out = set(out, 'spec_writer', answers.specWriter ?? 'null');
   if (answers.reviewMode) out = set(out, 'mode', answers.reviewMode);
   if (answers.merger) out = set(out, 'merger', answers.merger);
-  if (answers.runMaxCost !== undefined) out = set(out, 'run_max_cost', answers.runMaxCost);
+  if (answers.agentBuild === 'antigravity') {
+    // The agent has no cost limit: the limit of the run is a number of tokens, and the agent is named in its own group.
+    out = out.replace(/^(\s*)run_max_cost:[^\n]*$/m, '$1run_max_tokens: 2000000          # REQUIRED with agent.build antigravity: tokens per unattended run; choose your own');
+    out = `${out.trimEnd()}\n\n# Which agent builds in the cloud: claude (the default) or antigravity.\nagent:\n  build: antigravity\n`;
+    if (answers.runMaxTokens !== undefined) out = set(out, 'run_max_tokens', answers.runMaxTokens);
+  } else if (answers.runMaxCost !== undefined) out = set(out, 'run_max_cost', answers.runMaxCost);
   if (answers.language) out = set(out, 'language', answers.language);
   const check = loadConfig(out);
   if (!check.ok) throw new Error(`the answers produce an invalid relevo.yml: ${check.errors.map((e) => e.message).join('; ')}`);
@@ -178,6 +185,20 @@ export function planInit({ facts, answers, templates, current, admin }) {
   if (!facts.openspec) items.push(item('install.openspec', 'todo', 'Install the OpenSpec command-line tool', { install: true, command: 'npm install --global @fission-ai/openspec', detail: OPENSPEC_INSTALL }));
   REQUIRED_SKILLS.filter((n) => !facts.skills[n]).forEach((n) => items.push(item(`install.skill.${n}`, 'todo', `Install the ${n} skill`, { install: true, command: n === 'openspec-explore' ? 'openspec init' : 'npx skills add mattpocock/skills', detail: SKILL_INSTALL[n] })));
 
+  const configuredPlatforms = facts.config?.platforms ?? answers.platforms ?? (answers.platform ? { app: LEGACY_PLATFORMS[answers.platform] } : {});
+  const hasSupabase = Object.values(configuredPlatforms).some((p) => p?.stack === 'supabase');
+  if (hasSupabase) {
+    ['supabase', 'supabase-postgres-best-practices'].forEach((skill) => {
+      if (facts.skills?.[skill] === false) {
+        items.push(item(`install.skill.${skill}`, 'todo', `Install the ${skill} skill`, {
+          install: true,
+          command: `npx skills add supabase/agent-skills --skill ${skill}`,
+          detail: SKILL_INSTALL[skill] ?? `run \`npx skills add supabase/agent-skills --skill ${skill}\``,
+        }));
+      }
+    });
+  }
+
   // the plugin, declared in the project so that a teammate who clones the repository is offered it
   if (facts.pluginDeclared?.declared) items.push(item('install.plugin-project', 'ok', 'The repository declares the Relevo plugin (.claude/settings.json)'));
   else if (facts.pluginDeclared?.unreadable) items.push(item('install.plugin-project', 'manual', '.claude/settings.json is not valid JSON: fix it, then run init again to declare the Relevo plugin in the project'));
@@ -187,11 +208,11 @@ export function planInit({ facts, answers, templates, current, admin }) {
   if (facts.configText !== null) items.push(item('config', facts.config ? 'ok' : 'differs', facts.config ? 'relevo.yml exists and is valid' : `relevo.yml exists but is invalid: ${facts.configErrors.join('; ')}`));
   else items.push(item('config', 'todo', 'Create relevo.yml from the answers', { content: renderConfig(templates.config, { base, release, ...answers }) }));
 
-  // optional stack profiles of the repository (created only when asked for, and never committed by init)
+  // optional stack profiles of the repository (created only when asked for; init never commits them, the person does)
   (answers.stackProfiles ?? []).forEach((stack) => {
     const path = `.relevo/stacks/${stack}.md`;
     if ((current.stackProfiles ?? {})[stack]) items.push(item(`stack-profile.${stack}`, 'ok', `${path} exists`));
-    else items.push(item(`stack-profile.${stack}`, 'todo', `Create ${path}, a commented profile that adds to the plugin's (not committed)`, { path, content: stackProfileTemplate(stack) }));
+    else items.push(item(`stack-profile.${stack}`, 'todo', `Create ${path}, a commented profile that adds to the plugin's (left for you to commit)`, { path, content: stackProfileTemplate(stack) }));
   });
 
   // labels
@@ -225,10 +246,13 @@ export function planInit({ facts, answers, templates, current, admin }) {
   const credential = answers.credential ?? 'api_key';
   if (!RUNS.includes(runs)) throw new Error(`runs must be one of ${RUNS.join(', ')} (got "${runs}")`);
   if (!CREDENTIALS.includes(credential)) throw new Error(`credential must be one of ${CREDENTIALS.join(', ')} (got "${credential}")`);
+  const build = answers.agentBuild ?? 'claude';
+  if (!AGENT_BUILDS.includes(build)) throw new Error(`agentBuild must be one of ${AGENT_BUILDS.join(', ')} (got "${build}")`);
   const cloudFiles = ['relevo-go.yml', 'relevo-queue.yml'];
   WORKFLOW_FILES.forEach((file) => {
     if (runs === 'local' && cloudFiles.includes(file)) return;
-    const wanted = file === 'relevo-go.yml' ? credentialLine(templates.workflows[file], credential) : templates.workflows[file];
+    const shared = file === 'relevo-go.yml' ? credentialLine(templates.workflows[file], credential) : templates.workflows[file];
+    const wanted = agentWorkflow(shared, build, templates.agentBlocks);
     const have = current.workflows[file] ?? null;
     if (have === null) items.push(item(`workflow.${file}`, 'todo', `Add .github/workflows/${file}`, { path: `.github/workflows/${file}`, content: wanted }));
     else if (have === wanted) items.push(item(`workflow.${file}`, 'ok', `.github/workflows/${file} is up to date`));
@@ -262,6 +286,9 @@ export function planInit({ facts, answers, templates, current, admin }) {
     if ((facts.secrets ?? []).includes('RELEVO_LINKS_TOKEN')) items.push(item('manual.links-token', 'ok', 'The RELEVO_LINKS_TOKEN secret exists (init never reads it)'));
     else items.push(item('manual.links-token', 'manual', `If ${links.join(', ')} ${links.length > 1 ? 'are' : 'is'} private, create a fine-grained token with read access to issues and pull requests and store it yourself as the secret RELEVO_LINKS_TOKEN (init never reads or writes it; Relevo only reads with it, and public repositories need none)`));
   }
+  if (hasSupabase) {
+    items.push(item('manual.supabase-mcp', 'manual', 'To explore your Supabase database in Claude Code or Antigravity during /relevo:think, consider connecting the Supabase MCP server (see https://supabase.com/docs/guides/ai-tools)'));
+  }
   items.push(item('manual.push', 'manual', 'Commit and push the new files to the default branch: a workflow only runs from there'));
 
   return items;

package/scripts/lib/protected-paths.mjs

@@ -2,10 +2,15 @@
 //
 // Two tiers:
 //   hard  never allowed, whatever the issue says: workflows, the Relevo configuration, the folders of skills and
-//         the file with the project rules (a defect is fixed in the code, not by rewriting the rule).
+//         the file with the project rules (a defect is fixed in the code, not by rewriting the rule), and what carries
+//         the instructions or the permissions of another agent (`.agents/`, `.gemini/`, `AGENTS.md`, `GEMINI.md`):
+//         a run that could edit them could rewrite its own instructions.
 //   soft  dependency manifests and lock files: allowed only when the issue lists them in an `Allow-paths:` line.
 
-export const HARD_PATTERNS = ['.github/', 'relevo.yml', '.relevo/', '.claude/skills/', '.agents/skills/', 'skills-lock.json'];
+export const HARD_PATTERNS = ['.github/', 'relevo.yml', '.relevo/', '.claude/skills/', '.agents/', '.gemini/', 'skills-lock.json'];
+
+// Files that an agent reads from the folder of whatever it edits, so they are protected at any depth.
+export const HARD_ANY_DEPTH = ['AGENTS.md', 'GEMINI.md'];
 
 export const SOFT_FILES = [
   'pubspec.yaml', 'pubspec.lock',
@@ -60,7 +65,8 @@ const matchesHard = (path, pattern) => {
 
 /** The hard rule a path breaks, or null. */
 export function hardRule(path, { rulesFile = null } = {}) {
-  return hardPatterns(rulesFile).find((pattern) => matchesHard(path, pattern)) ?? null;
+  const name = clean(path).split('/').pop();
+  return hardPatterns(rulesFile).find((pattern) => matchesHard(path, pattern)) ?? HARD_ANY_DEPTH.find((f) => f === name) ?? null;
 }
 
 /** Is the file a dependency manifest or lock file (soft tier)? */
@@ -87,7 +93,7 @@ export function checkProtected(paths, { allow = [], rulesFile = null } = {}) {
 
 /** Entries of an `Allow-paths:` list that name (or would cover) a hard-protected path: they can never be allowed. */
 export function hardPathsInAllow(allow, { rulesFile = null } = {}) {
-  const probes = [...HARD_PATTERNS.map((pattern) => (pattern.endsWith('/') ? `${pattern}x` : pattern)), ...ruleFiles(rulesFile)].filter(Boolean);
+  const probes = [...HARD_PATTERNS.map((pattern) => (pattern.endsWith('/') ? `${pattern}x` : pattern)), ...HARD_ANY_DEPTH, ...ruleFiles(rulesFile)].filter(Boolean);
   return (allow ?? []).filter((entry) => hardRule(entry, { rulesFile }) || probes.some((probe) => matchesGlob(probe, entry)));
 }
 

package/scripts/lib/run-usage.mjs

@@ -57,7 +57,7 @@ export function usageLine(usage, { subscription = false } = {}) {
 // Messages the Claude CLI and the API document for a usage limit, a quota or an empty credit balance. These patterns
 // are not from a failed run seen here (see docs/pilot-findings.md); a wrong guess only changes the wording of a
 // comment on a run that already failed.
-const LIMIT_RE = /usage limit|limit reached|rate[ _-]?limit|credit balance is too low|exceeded your (current )?quota|insufficient[ _]quota/i;
+const LIMIT_RE = /usage limit|limit reached|rate[ _-]?limit|credit balance is too low|exceeded your (current )?quota|quota exceeded|resource[ _]exhausted|insufficient[ _]quota/i;
 
 /** Does the log show that a usage limit, a quota or the credit was reached? */
 export function reachedUsageLimit(text) {

package/scripts/lib/select.mjs

@@ -58,3 +58,61 @@ export function select({ title, choices, defaultIndex = 0, input, output, hint =
     draw();
   });
 }
+
+/**
+ * Like `select`, but several choices can be ticked: Space (or the digit of a choice) toggles, Enter confirms.
+ * choices: [{ value, label }]; initial: the values ticked at the start. Resolves the array of ticked values in the
+ * order of `choices` (possibly empty), or null when the person cancels.
+ */
+export function selectMany({ title, choices, initial = [], input, output, hint = 'Arrows to move, Space or a number to tick, Enter to confirm, Esc to cancel' }) {
+  if (!input?.isTTY || typeof input.setRawMode !== 'function') return Promise.reject(new Error('the list needs a terminal'));
+  if (!Array.isArray(choices) || choices.length === 0) return Promise.reject(new Error('the list has no choices'));
+  return new Promise((resolve) => {
+    const ticked = new Set(initial);
+    let index = 0;
+    let drawn = 0;
+    const draw = () => {
+      const lines = [title, ...choices.map((c, i) => `${i === index ? '>' : ' '} [${ticked.has(c.value) ? 'x' : ' '}] ${i + 1}. ${c.label}`), hint];
+      output.write(`${drawn ? UP(drawn) : ''}\r${CLEAR}${lines.join('\n')}\n`);
+      drawn = lines.length;
+    };
+    const finish = (value) => {
+      input.removeListener('keypress', onKey);
+      try {
+        input.setRawMode(false);
+      } finally {
+        input.pause?.();
+        output.write(SHOW);
+      }
+      resolve(value);
+    };
+    const toggle = (i) => {
+      const v = choices[i].value;
+      if (ticked.has(v)) ticked.delete(v);
+      else ticked.add(v);
+    };
+    function onKey(str, key = {}) {
+      try {
+        if (key.ctrl && (key.name === 'c' || key.name === 'd')) return finish(null);
+        if (key.name === 'escape' || str === 'q') return finish(null);
+        if (key.name === 'return' || key.name === 'enter') return finish(choices.map((c) => c.value).filter((v) => ticked.has(v)));
+        if (key.name === 'up' || str === 'k') index = (index + choices.length - 1) % choices.length;
+        else if (key.name === 'down' || str === 'j') index = (index + 1) % choices.length;
+        else if (key.name === 'space' || str === ' ') toggle(index);
+        else if (/^[1-9]$/.test(str ?? '') && Number(str) <= choices.length) toggle(Number(str) - 1);
+        else return undefined;
+        draw();
+      } catch (err) {
+        finish(null);
+        throw err;
+      }
+      return undefined;
+    }
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume?.();
+    input.on('keypress', onKey);
+    output.write(HIDE);
+    draw();
+  });
+}

package/scripts/lib/worktree-path.mjs

@@ -0,0 +1,11 @@
+// Where the worktree of an issue lives: next to the repository, never inside it. Shared by `go-local` and
+// `go-worktree` so that the two cannot name it differently.
+
+import { basename, dirname, join } from 'node:path';
+
+export const WORKTREES_FOLDER = '.relevo-worktrees';
+
+/** The worktree of an issue: `<parent of the repository>/.relevo-worktrees/<repository>-<issue>`. Pure. */
+export function worktreePath(repoRoot, issue) {
+  return join(dirname(repoRoot), WORKTREES_FOLDER, `${basename(repoRoot)}-${issue}`);
+}

package/skills/go/SKILL.md

@@ -27,10 +27,22 @@ Launch `relevo:dev` and `relevo:qa` in the foreground and wait for each report b
 
 ## Where it runs
 
-In the cloud the workflow starts this skill with the decision already made. A person can also start it on their machine: `node ${CLAUDE_PLUGIN_ROOT}/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).
+In the cloud the workflow starts this skill with the decision already made. A person can also start it on their machine: `node ${CLAUDE_PLUGIN_ROOT}/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.
 
 **When `$ARGUMENTS` has `--local`**, do not build in this session: run `node ${CLAUDE_PLUGIN_ROOT}/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 session** (started by hand without `--decision` and without `--local`), do not build in the folder you were started in: another session may be building another issue there, and the person may have changes of their own. Before step 0, make a worktree for the issue:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/go-worktree.mjs create <issue>
+```
+
+- Exit 0: it prints `{"worktree": "<path>", "base": "<base>"}`. Enter it with `EnterWorktree` and its `path` (never its `name`, which would branch from the default branch and not from the base of the project). From then on every step, command and agent works in that folder.
+- Exit 4: the session is already in a linked worktree (a run of `go-local.mjs`, or one the person made). Build where you are, make no worktree, and skip the exit below.
+- Any other exit (for example 3, the worktree of this issue already exists because another run is building it or a failed one left it): show its message and stop without changing anything.
+
+At the end of the run, before the final report, leave the worktree: call `ExitWorktree` with `keep`. Then, from the folder you came from, remove it with `node ${CLAUDE_PLUGIN_ROOT}/scripts/go-worktree.mjs remove <issue>` when the outcome is `built` or a gate decision that stopped before step 2 (nothing was built, so nothing is lost). After the failure path, or if the run stopped for any other reason, leave the worktree on disk and say its path in the report.
+
 ## OpenSpec commands
 
 Use these OpenSpec commands and no others:

package/skills/init/SKILL.md

@@ -33,11 +33,12 @@ If `relevo.yml` already exists and is valid, skip this step. Otherwise ask, in s
 - who builds and reviews (GitHub usernames) and who writes the specs;
 - the review mode: `none` (a solo project), `peer` or `roles`;
 - the language of the hand-off messages (`en` or `es`);
-- the platforms: for each one a name, its stack (look at the project to propose one: the profiles in `${CLAUDE_PLUGIN_ROOT}/stacks/` are the stacks Relevo ships with: `flutter`, `vue` and `laravel`), the folder where it lives (`.` for a repository with one platform, `apps/web` in a monorepo) and, for a stack that has targets, which ones (for Flutter: `android`, `ios`, `web`; for Vue: `web`; Laravel has none). Several platforms in one repository are written down, but `go` builds only a repository with one for now;
+- the platforms: for each one a name, its stack (look at the project to propose one: the profiles in `${CLAUDE_PLUGIN_ROOT}/stacks/` are the stacks Relevo ships with: `flutter`, `vue`, `laravel` and `supabase`), the folder where it lives (`.` for a repository with one platform, `apps/web` in a monorepo) and, for a stack that has targets, which ones (for Flutter: `android`, `ios`, `web`; for Vue: `web`; Laravel and Supabase have none). Several platforms in one repository are written down, but `go` builds only a repository with one for now;
 - where `go` builds: in the cloud, on each person's machine, or both (the default), and, for the cloud, with an API key from the Anthropic Console (the default) or with a subscription token. A subscription's quota is shared by every run and by the interactive use of the account, so `init` sets `limits.concurrent_agents` to 1 for it. Nothing about this goes in `relevo.yml` apart from that number: the installed workflows, the secret that exists and the repository variable `RELEVO_CLOUD_GO` (`off` pauses the cloud at once, with no pull request) decide it;
 - the repositories this one depends on, if any (`owner/repo`, for example the back end of a front end): they are written to `links`, the closed list that `Depends-on: owner/repo#N` is checked against;
-- whether to create a commented `.relevo/stacks/<stack>.md` for each stack, where the project can add its own hygiene to the plugin's profile (optional; it is not committed);
-- the cost limit per unattended run in US dollars: the template's 5 is a placeholder the person must accept or change.
+- whether to create a commented `.relevo/stacks/<stack>.md` for each stack, where the project can add its own hygiene to the plugin's profile (optional; `init` creates it but does not commit it: it is left for the person to commit, because the cloud and teammates read it from git);
+- which agent builds in the cloud, only when the person says they use Antigravity: `claude` (the default) or `antigravity`. With `antigravity` the model key is `GEMINI_API_KEY`, a key made only for Relevo in its own Google Cloud project with a quota, and the limit asked below is a number of tokens (`limits.run_max_tokens`) because that agent has no cost limit; `docs/security.md` says what else it cannot enforce;
+- the cost limit per unattended run in US dollars: the template's 5 is a placeholder the person must accept or change (with `antigravity`, the token limit instead).
 
 Write the answers as JSON to a temporary file **outside the repository**, with the keys `members`, `specWriter`, `reviewMode`, `language`, `platforms` (a map of name to `{ stack, path, targets }`), `links` (a list of `owner/repo`, possibly none), `runs` (`cloud`, `local` or `both`), `credential` (`api_key` or `subscription`), `stackProfiles` (the stacks that get a profile file, possibly none) and, if given, `runMaxCost`. Never put a secret in it.
 
@@ -71,4 +72,4 @@ Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs` and show its output.
 
 ## Report
 
-Finish with: what was created, what was left alone, what the person must still do by hand (always the model credential in the repository secrets, with all whitespace removed from a subscription token, and committing and pushing the new files to the default branch, because a workflow only runs from there), and the doctor result.
+Finish with: what was created, what was left alone, what the person must still do by hand (always the model credential in the repository secrets, with all whitespace removed from a subscription token, and committing and pushing the new files to the default branch, because a workflow only runs from there; name each `.relevo/stacks/<stack>.md` it created among them), and the doctor result.

package/skills/review/SKILL.md

@@ -152,6 +152,16 @@ Only when `decide` exited 0.
 - `evidence.policy: local_only`: delete the `evidence/` folder now. Nothing is attached anywhere.
 - `evidence.policy: attach_to_pr`: GitHub has no API for attaching images, so you cannot upload them. List the files in `evidence/` and ask the person to drag them into the pull request description. Keep the folder until they say they did, then delete it.
 
+### 9. Return to base branch
+
+Restore the working tree to the base branch so the workspace remains clean on the base branch for other tasks or subsequent reviews, but only where that is possible: in the main checkout, and when no other worktree holds the base branch.
+
+```bash
+[ "$(git rev-parse --git-dir)" = "$(git rev-parse --git-common-dir)" ] && ! git worktree list --porcelain | grep -qx "branch refs/heads/<base>" && git switch <base>
+```
+
+If the condition does not hold (a separate worktree, or the base branch is checked out elsewhere), do not switch: say which branch the working tree stays on. If `git switch` fails, say so; it never changes the verdict or the state of the issue, because the pull request already exists.
+
 ## Report
 
 Finish with one short block: the issue, the review verdict, the checklist result, the pull request link (or why none was opened), and the issue's new state.

package/stacks/flutter.md

@@ -4,7 +4,7 @@ commands:
   analyze: flutter analyze --no-pub
   test: flutter test --reporter=compact --no-pub
   format: dart format
-generated: ['*.g.dart', '*.freezed.dart']
+generated: ['*.g.dart', '*.freezed.dart', '*.mocks.dart']
 tools: [flutter]
 requires_skills: []
 skills:
@@ -22,29 +22,67 @@ targets:
 
 ## Verification
 
-Prefer the Dart tooling server's tools when they are available in this session (analysis, running tests, formatting). Otherwise use the commands of this profile: `analyze`, `test` and `format`.
+Run the commands of this profile from the folder of the platform: `analyze`, `test` and `format`. Run `format` on the files you changed, never on generated files.
+
+When the Dart and Flutter MCP server is connected, you may use the tools that write nothing: `analyze_files` for analysis, `lsp` and `read_package_uris` to check an API or a symbol instead of guessing it, and `run_tests` when the server enables it (it is off by default). When a tool is missing, use the command of this profile. No agent uses `dart_format`, `dart_fix`, `pub`, `hot_reload`, `hot_restart` or `launch_app` during a run: they write files or drive an app, and `dart_format` formats the whole project, generated files included.
+
+When annotated models or mocks changed, run `dart run build_runner build --delete-conflicting-outputs` before the tests.
 
 Do not claim the code compiles, analyses clean or passes tests unless you ran the tools and saw it. If neither the tooling server nor Flutter is available, say so plainly in your report.
 
+## Architecture
+
+Follow the architecture that the project's rules declare (MVVM, bloc, riverpod or another). When they declare none, write new code with the structure of Flutter's architecture guide: UI and data in separate layers; data reached through repositories, which call stateless services that wrap each API or plugin; dependencies passed by constructor and kept private; no data logic in widgets. Command and Result objects, and any state-management package, are not required by this profile; use them when the project's rules do.
+
 ## Hygiene for the developer
 
+Lifecycle and state:
+
 - Check `mounted` before using a `BuildContext` or calling `setState` after an `await`.
-- Dispose every controller, stream subscription and listener you create.
+- Dispose every controller, stream subscription and listener you create. A `ChangeNotifierProvider(create:)` disposes its model itself.
+- Never call an API, create a future or show a dialog inside `build()`; start them in `initState` or in an event handler.
 - Avoid the null-assertion operator unless a prior check makes it provably safe.
 - Give every screen loading, empty and error states.
 - Prevent double submission of actions.
-- Keep layouts from overflowing on small screens.
+
+Layout:
+
+- Keep layouts from overflowing on small screens: wrap a long `Text` or other unconstrained child of a `Row` or `Column` in `Expanded` or `Flexible`.
+- Give a `ListView` or `GridView` inside a `Column` a bound (`Expanded` or a fixed height), and a `TextField` inside a `Row` a width (`Expanded` or `SizedBox`).
+- Put `Expanded` and `Flexible` directly in a `Row`, `Column` or `Flex`, and `Positioned` directly in a `Stack`.
+- Give each scroll view its own `ScrollController`.
+
+Performance:
+
+- Build long lists and grids with the builder constructors, not with a list of children.
+- Keep `build()` cheap, and call `setState` as low in the tree as the change allows.
+- Split large widgets into smaller widget classes rather than helper methods that return widgets.
+- Keep `Opacity` and clipping out of animations; use `AnimatedOpacity` or a semi-transparent colour.
+- Move heavy work, such as decoding a large JSON response, off the UI isolate with `Isolate.run`. On the web it still runs on the main thread.
+
+Web:
+
+- Use `package:web` and `dart:js_interop`; `dart:html` and `package:js` prevent the Wasm build.
+- Do not use `dart:io` or `Platform` in code that runs on the web; check `kIsWeb` or use a conditional import.
+
+Tests:
+
 - Write unit and widget tests for the scenarios the platform allows. A scenario that can only be seen on a device or in another app is covered by correct code, and is verified later in the on-device review.
+- Make fakes of repositories and services for tests; a mock is also acceptable. A plugin throws `MissingPluginException` in unit and widget tests, so put it behind the project's own class and fake that class.
 
 ## What the auditor looks for in the diff
 
-- **Async and lifecycle**: a `BuildContext` use or `setState` after an `await` without a `mounted` check.
+- **Async and lifecycle**: a `BuildContext` use or `setState` after an `await` without a `mounted` check; a network call, a new future, `setState` or `showDialog` inside `build()`.
 - **Leaks**: a controller, stream subscription or listener created and never disposed.
 - **Null safety**: an unchecked null-assertion operator that can throw at runtime.
-- **Layout**: unconstrained content that can overflow on a small screen.
+- **Layout**: unconstrained content that can overflow on a small screen; a `ListView` or `GridView` in a `Column` without a bound; a `TextField` in a `Row` without a width; `Expanded`, `Flexible` or `Positioned` outside a compatible parent; one `ScrollController` attached to several scroll views.
 - **States**: missing loading, empty or error states; an action that can be triggered twice.
+- **Performance**: a long list built from a list of children; costly work in `build()`; `setState` high in the tree for a local change; `Opacity` or clipping inside an animation; a large JSON decode on the UI isolate.
+- **Web**: an import of `dart:html` or `package:js`; `dart:io` or `Platform` in code that runs on the web.
+- **Tests**: a test that calls a real plugin, network or service instead of a fake or a mock.
+- **Architecture**: report only what breaks a rule the project wrote down. Whatever the project declares, an HTTP or GraphQL client called from a widget is a finding.
 - **Android specifics**: an external-app launch with no handling for the app being missing, permission use without handling denial, behaviour on the back button.
-- **Generated code**: leave generated files (`*.g.dart`, `*.freezed.dart`) out of the review.
+- **Generated code**: leave generated files (`*.g.dart`, `*.freezed.dart`, `*.mocks.dart`) out of the review.
 
 ## Targets
 

package/stacks/supabase.md

@@ -0,0 +1,63 @@
+---
+stack: supabase
+commands:
+  analyze: supabase db lint
+  test: supabase test db
+  format: npx prettier --write supabase/
+generated: []
+tools: [supabase, docker]
+requires_skills:
+  - supabase
+  - supabase-postgres-best-practices
+skills:
+  dev:
+    - supabase
+    - supabase-postgres-best-practices
+  qa:
+    - supabase
+    - supabase-postgres-best-practices
+  issue:
+    - supabase
+    - supabase-postgres-best-practices
+  review: []
+---
+
+# Supabase
+
+## Verification
+
+Run the verification commands from the platform directory: `analyze` (`supabase db lint`) and `test` (`supabase test db`). These commands require the Supabase CLI and a running Docker daemon.
+
+Do not claim the database schema is valid, clean, or passes tests unless you ran the commands and saw the results. All tests run hermetically against local Docker containers; never point tests at a remote Supabase project.
+
+## Questions for the issue writer
+
+- **Authorization & RLS**: Who is permitted to select, insert, update, and delete rows in these tables? Which Postgres roles (`anon`, `authenticated`) should have access?
+- **Relationships & Deletes**: If a parent row or user is deleted, what is the expected cascade behavior (`CASCADE`, `SET NULL`, or `RESTRICT`)?
+- **Storage & Files**: If files are uploaded, what are the allowed MIME types, max file sizes, and who can overwrite or delete objects?
+- **Query Performance & Filters**: Which columns will be filtered in `WHERE` clauses, sorted, or referenced in RLS policies (`auth.uid() = user_id`)?
+
+## Hygiene for the developer
+
+- Follow the official guidelines from `supabase` and `supabase-postgres-best-practices`.
+- Enable Row Level Security on every public table: `ALTER TABLE <table_name> ENABLE ROW LEVEL SECURITY;`.
+- Avoid using `auth.role()` in policies; use the `TO` clause instead (e.g. `TO authenticated` or `TO anon`).
+- Combine `TO authenticated` with an explicit ownership predicate (e.g. `(select auth.uid()) = user_id`) to prevent broken object-level authorization (BOLA / IDOR).
+- Always include both `USING` and `WITH CHECK` clauses on `UPDATE` policies so users cannot reassign ownership columns.
+- Ensure all views on tables with RLS specify `WITH (security_invoker = true)` (Postgres 15+).
+- Avoid `SECURITY DEFINER` functions in the `public` schema; if required, keep them in a private schema and validate caller identity explicitly.
+- Create an index on every foreign key column and on every column evaluated in RLS policies.
+- Structure all schema changes as versioned, timestamped migrations in `supabase/migrations/`.
+- Maintain test and sample data in `supabase/seed.sql` using idempotent statements (`INSERT ... ON CONFLICT DO NOTHING;`).
+- Write pgTAP test suites in `supabase/tests/` verifying that unauthorized or anonymous callers cannot read or modify protected rows.
+
+## What the auditor looks for in the diff
+
+- **Missing RLS**: Any table created in an exposed schema without `ENABLE ROW LEVEL SECURITY`.
+- **Incomplete Update Policies**: An `UPDATE` policy that defines `USING` but omits `WITH CHECK`.
+- **Permissive Policies**: Policies using `USING (true)` or checking only `TO authenticated` without row-ownership verification on private user data.
+- **Unprotected Views**: Views defined without `security_invoker = true`.
+- **Privilege Escalation**: `SECURITY DEFINER` functions placed in `public` or callable without `auth.uid()` checks.
+- **Missing Indexes**: Foreign key constraints or RLS filter columns without an index.
+- **Destructive Migrations**: `DROP TABLE`, `DROP COLUMN`, or `TRUNCATE` operations without explicit migration plans or rollback safety.
+- **Exposed Secrets**: Hardcoded `service_role` keys, API tokens, or service passwords in code, migrations, or seed files.