vibecoding-devtools 1.0.1 → 1.1.0

package/installer/json-merge.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { hashContent } from './state.mjs';
 
 // Keep source ranges so edits never reserialize unrelated settings or hooks.
-function parse(text) {
+export function parse(text) {
   JSON.parse(text.replace(/^\uFEFF/, ''));
   let offset = text.charCodeAt(0) === 0xFEFF ? 1 : 0;
   const whitespace = () => { while (/\s/.test(text[offset] ?? '') && offset < text.length) offset++; };
@@ -53,7 +53,7 @@ function parse(text) {
   return root;
 }
 
-const property = (node, key) => node.children.find((child) => child.key === key);
+export const property = (node, key) => node.children.find((child) => child.key === key);
 const normalizePath = (file) => file.replace(/\\/g, '/');
 function ownsHook(hook, action) {
   if (!hook || typeof hook !== 'object') return false;
@@ -115,7 +115,7 @@ export function jsonMergeSnapshot(current, action) {
   return { hash: hashContent(JSON.stringify(entries.map((entry) => entry.fingerprint))), count: entries.length };
 }
 
-function removeChild(text, parent, entry) {
+export function removeChild(text, parent, entry) {
   const index = parent.children.indexOf(entry);
   const next = parent.children[index + 1];
   const previous = parent.children[index - 1];
@@ -150,7 +150,7 @@ function removeEmptyContainers(text, paths) {
   return text;
 }
 
-function append(text, parent, key, value) {
+export function append(text, parent, key, value) {
   const eol = text.includes('\r\n') ? '\r\n' : '\n';
   const unit = text.match(/\n([ \t]+)"/)?.[1] ?? '  ';
   const lineStart = text.lastIndexOf('\n', parent.start) + 1;

package/installer/plan.mjs

@@ -1,11 +1,13 @@
 // Read-only planning performs no writes, network calls, execution or real-home access.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { isUtf8 } from "node:buffer";
 import { readState, hashContent } from "./state.mjs";
 import { convertAntigravityRule, readFrontmatter, buildCodexBlock } from "./convert.mjs";
 import { hookActions } from './hooks.mjs';
 import { jsonMergeSituation } from './json-merge.mjs';
+import { envListSituation } from './env-list.mjs';
 
 const CLIS = ["claude", "codex", "agy"];
 const uniqueList = (items = []) => [...new Set(items)].sort();
@@ -84,6 +86,7 @@ function situationOf(action, items) {
   let previous = items.find((item) => item.type === action.type && samePath(item.destination, action.destination));
   if (previous?.pending && previous.hashBefore === hashContent(current)) previous = previous.previous;
   if (action.type === 'json-merge') return jsonMergeSituation(current, action, previous);
+  if (action.type === 'env-list') return envListSituation(current, action, previous);
   if (action.type === "block") {
     if (!isUtf8(current)) return "conflict";
     const block = extractBlock(current.toString("utf8"));
@@ -135,11 +138,25 @@ export function reconcileUpdate(plan, { home }) {
     item.type === 'block' ? item.marker ?? START : null]);
   const wanted = new Set(actions.filter((a) => a.destination).map(key));
   const removals = state.items.filter((item) => item.owner === 'kit'
-    && ['copy', 'write', 'block', 'json-merge'].includes(item.type) && !wanted.has(key(item)))
+    && ['copy', 'write', 'block', 'json-merge', 'env-list'].includes(item.type) && !wanted.has(key(item)))
     .map((item) => ({ ...item, operation: 'remove', situation: 'remove' }));
   return Object.assign([...removals, ...actions], { warnings: plan.warnings, preparation: plan.preparation });
 }
 
+// ECC's GateGuard asks for facts before the first edit of each file. These trees have no import value and agents
+// write to them all the time: Claude Code's temp directory (scratchpad), its auto memory and the Maestri role folders.
+// The temp directory follows CLAUDE_CODE_TMPDIR as Claude Code documents it: <dir>/claude-<uid> on Unix,
+// <dir>/claude on Windows, with /tmp or the system temp directory as <dir>.
+export function gateguardExemptions({ home, maestri, env = process.env, platform = process.platform,
+  uid = process.getuid?.() }) {
+  const slash = (file) => file.replace(/\\/g, "/").replace(/\/+$/, "");
+  const windows = platform === "win32";
+  const base = slash(env.CLAUDE_CODE_TMPDIR || (windows ? os.tmpdir() : "/tmp"));
+  const temp = windows ? `${base}/claude` : uid == null ? null : `${base}/claude-${uid}`;
+  return [...(temp ? [`${temp}/**`] : []), `${slash(home)}/.claude/projects/*/memory/**`,
+    ...(maestri ? ["**/.maestri/**"] : [])];
+}
+
 export function buildPlan(choices, detection, paths) {
   const { home, kit, ecc, project } = paths;
   if (!home || !kit) throw new Error("paths.home and paths.kit are required");
@@ -206,6 +223,12 @@ export function buildPlan(choices, detection, paths) {
         add("copy", "kit", cli, path.join(kit, "skills", skill.name),
           path.join(destinationSkills, skill.name), null, `Kit skill: ${skill.name}`);
       }
+      // Agents message each other through the maestri CLI, which runs outside Codex's sandbox. The rules go to the
+      // user layer in either scope so every workspace's agents get them.
+      if (cli === "codex" && choices.maestri) {
+        add("copy", "kit", cli, path.join(kit, "installer", "codex-maestri.rules"),
+          path.join(home, ".codex", "rules", "vibecoding-devtools-maestri.rules"), null, "Maestri command rules for Codex");
+      }
     }
     if (eccClis.includes(cli)) {
       const packages = uniqueList(["common", ...(cli === "claude" ? ["web"] : []),
@@ -249,6 +272,13 @@ export function buildPlan(choices, detection, paths) {
     }
   }
   actions.push(...hookActions(choices, { home, kit, project }));
+  // Any ECC on Claude: the ECC plugin brings GateGuard even with the kit's ECC hooks off. The paths are this machine's,
+  // so they go to the user settings in either scope, never to a project's file.
+  if (eccClis.includes("claude")) {
+    actions.push({ type: "env-list", owner: "kit", cli: "claude", destination: path.join(home, ".claude", "settings.json"),
+      key: "GATEGUARD_EXEMPT_GLOBS", values: gateguardExemptions({ home, maestri: choices.maestri }),
+      description: "GateGuard exemptions for scratch, memory and Maestri files" });
+  }
   const plan = actions.map((action) => ({ ...action, situation: situationOf(action, state.items) }));
   if (warnings.length) plan.warnings = warnings;
   return plan;

package/installer/team-checks.mjs

@@ -0,0 +1,86 @@
+// Read-only prerequisites of the team install: the CLIs, the models the launch commands name, and ECC in Claude Code.
+// Everything that touches the machine goes through `tools`, so tests inject fakes instead of running real CLIs.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { findIn, pathDirectories } from './detect.mjs';
+
+const binaryOf = (command) => command.trim().split(/\s+/)[0];
+const modelOf = (command) => command.match(/(?:^|\s)(?:--model|-m)[ =](\S+)/)?.[1];
+
+// The commands the install launches: presets, and agents that carry their own command instead of a preset.
+const launchCommands = (manifest) => [
+  ...manifest.presets.map((p) => ({ label: `preset "${p.name}"`, command: p.command })),
+  ...manifest.agents.filter((a) => a.command).map((a) => ({ label: `agent "${a.name}"`, command: a.command })),
+];
+
+// Model ids a CLI lists: `codex debug models` prints JSON with `slug`; `agy models` prints `<id>\t<name>` lines.
+const MODEL_LISTS = {
+  codex: { source: 'codex debug models', read: (tools) => JSON.parse(tools.codexModels()).models.map((m) => m.slug) },
+  agy: { source: 'agy models', read: (tools) => tools.agyModels().split('\n').filter((l) => l.includes('\t'))
+    .map((l) => l.split(/\s+/)[0]) },
+};
+
+const attempt = (what, fn) => {
+  try {
+    return { value: fn() };
+  } catch (e) {
+    return { problem: `could not run ${what}: ${(e.stderr?.toString().trim() || e.message).split('\n')[0]}` };
+  }
+};
+
+// Missing items, all together; an empty list means the run may start. `rolesOnly` creates roles and launches nothing,
+// so it needs only the maestri binary.
+export function missingPrerequisites(manifest, tools, { maestri = 'maestri', rolesOnly = false } = {}) {
+  const launches = rolesOnly ? [] : launchCommands(manifest);
+  const bins = [...new Set([maestri, ...launches.map((l) => binaryOf(l.command))])];
+  const absent = new Set(bins.filter((bin) => !tools.onPath(bin)));
+  const problems = [...absent].map((bin) => `${bin} is not on PATH`);
+
+  const catalogs = new Map();
+  for (const { label, command } of launches) {
+    const bin = binaryOf(command);
+    const model = modelOf(command);
+    if (absent.has(bin) || !model || !MODEL_LISTS[bin]) continue;
+    if (!catalogs.has(bin)) {
+      const { source, read } = MODEL_LISTS[bin];
+      catalogs.set(bin, attempt(source, () => new Set(read(tools))));
+    }
+    const { value, problem } = catalogs.get(bin);
+    if (problem) {
+      if (!problems.includes(problem)) problems.push(problem);
+    } else if (!value.has(model)) {
+      problems.push(`${label}: model "${model}" is not in ${MODEL_LISTS[bin].source}`);
+    }
+  }
+
+  if (bins.includes('claude') && !absent.has('claude')) {
+    const { value, problem } = attempt('claude plugin list', () => tools.claudePlugins());
+    if (problem) problems.push(problem);
+    else if (!/\becc@/.test(value)) {
+      problems.push('ECC is not installed in Claude Code (claude plugin list shows no ecc@): '
+        + 'the Team Maestro role uses /ecc:plan');
+    }
+  }
+  return problems;
+}
+
+// A path as given, or a name found on PATH (PATHEXT on Windows).
+function onPath(bin, env, platform) {
+  if (/[\\/]/.test(bin)) return fs.existsSync(bin);
+  try {
+    return Boolean(findIn(bin, pathDirectories(env), { env, platform }));
+  } catch {
+    return false;
+  }
+}
+
+const BIG_OUTPUT = 64 * 1024 * 1024;
+const runCli = (bin, args) => execFileSync(bin, args,
+  { encoding: 'utf8', maxBuffer: BIG_OUTPUT, stdio: ['ignore', 'pipe', 'pipe'] });
+
+export const realTools = ({ env = process.env, platform = process.platform } = {}) => ({
+  onPath: (bin) => onPath(bin, env, platform),
+  codexModels: () => runCli('codex', ['debug', 'models']),
+  agyModels: () => runCli('agy', ['models']),
+  claudePlugins: () => runCli('claude', ['plugin', 'list']),
+});

package/installer/team.mjs

@@ -0,0 +1,260 @@
+// Install the kit's Maestri team from team/team.json through the maestri CLI: roles, presets, agents, ropes, notes,
+// portal and partitura. Maestri may run on another computer; this runs where the agent CLIs and `maestri` run.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { missingPrerequisites, realTools } from './team-checks.mjs';
+
+export const TEAM_HELP = `Usage: vibecoding-devtools team [--roles-only] [--update-roles] [--dry-run]
+Run inside a Maestri terminal in Maestro mode, on the machine where the agent CLIs run.
+--roles-only    Create the team's missing global roles only
+--update-roles  Also rewrite what differs from the kit: installed roles (restarts the agents that use them), the Maestro
+                preset command and the Task Runner settings file
+--dry-run       Print the full maestri commands without running them
+Without --roles-only it also writes the Task Runner settings file to ~/.vibecoding-devtools/team/, creates the Maestro
+preset, recruits the agents, notes and portal you do not reach yet, wires them, and saves the global partitura unless
+one with its name exists.
+Before any change, also with --dry-run, it checks read-only that the CLIs, the models in team.json and ECC in Claude
+Code exist; missing items or conflicts stop the run with exit 1. If a run fails midway, run the same command again: it
+skips what exists and finishes the rest.`;
+
+const FLAGS = ['--roles-only', '--update-roles', '--dry-run'];
+
+// `- "Name"` entries of `maestri role|preset|partitura list`.
+export const listedNames = (output) => [...output.matchAll(/^\s*- "([^"]+)"/gm)].map((m) => m[1]);
+
+// Top-level sections of `maestri list` (what the caller reaches); nested `⎿` lines belong to other agents' trees.
+export function canvasEntries(output) {
+  const found = { agents: new Map(), notes: new Set(), portals: new Set(), ficharios: new Set() };
+  let section = null;
+  for (const line of output.split('\n')) {
+    if (/^\S/.test(line)) section = /^Connected (agents|notes|portals)/.exec(line)?.[1] ?? null;
+    else if (section && !line.trimStart().startsWith('⎿')) {
+      const fichario = /^\s*fichário "([^"]+)":/.exec(line);
+      const entry = /^\s*- name: "([^"]+)"(?:, role: "([^"]+)")?/.exec(line);
+      if (fichario) found.ficharios.add(fichario[1]);
+      else if (entry && section === 'agents') found.agents.set(entry[1], entry[2] ?? null);
+      else if (entry) found[section].add(entry[1]);
+    }
+  }
+  return found;
+}
+
+export const roleText = (role, protocol) => `${role.trimEnd()}\n\n${protocol.trimEnd()}`;
+
+// `maestri preset show` prints `Command: ...` and `Maestro: on|off`.
+export const presetShown = (output) => ({
+  command: output.match(/^Command: (.*)$/m)?.[1]?.trim(),
+  maestro: /^Maestro: on$/m.test(output),
+});
+
+// maestri decodes \n and \\ in note content; keep backslashes literal.
+const noteText = (text) => text.trimEnd().replaceAll('\\', '\\\\');
+
+// Session settings live in a stable file under the home folder, not in the kit's (npx cache) folder.
+export const settingsPath = (home, file) => path.join(home, '.vibecoding-devtools', 'team', path.basename(file));
+
+// One shell argument that POSIX shells and PowerShell read the same way.
+function shellArgument(value) {
+  if (/["`$]/.test(value)) throw new Error(`The path ${value} has a character the agent command cannot quote.`);
+  return /^[\w./\\:@-]+$/.test(value) ? value : `"${value}"`;
+}
+
+function agentCommand(agent, home) {
+  if (!agent.settingsFile) return agent.command;
+  return agent.command.replace('{settings}', () => shellArgument(settingsPath(home, agent.settingsFile)));
+}
+
+// Files the team needs on the machine that runs the agents: [{ path, content }].
+export const teamFiles = (manifest, read, home) => manifest.agents.filter((a) => a.settingsFile).map((a) => ({
+  path: settingsPath(home, a.settingsFile),
+  content: `${JSON.stringify(JSON.parse(read(a.settingsFile)), null, 2)}\n`,
+}));
+
+const presetDiffers = (found, preset) => found.command !== preset.command || found.maestro !== Boolean(preset.maestro);
+
+const kitRoles = (manifest, read) => {
+  const protocol = read(manifest.protocol);
+  return manifest.agents.map(({ role, roleFile }) => ({ role, text: roleText(read(roleFile), protocol) }));
+};
+
+// Everything that would make the run touch something that is not the kit's: checked before any change.
+export function teamConflicts(manifest, read, existing, options = {}) {
+  const { rolesOnly = false, updateRoles = false, home = os.homedir() } = options;
+  const conflicts = [];
+  for (const { role, text } of kitRoles(manifest, read)) {
+    if (existing.roles.has(role) && existing.roles.get(role) !== text && !updateRoles) {
+      conflicts.push(`role "${role}" exists with other text; rerun with --update-roles to replace it`);
+    }
+  }
+  if (rolesOnly) return conflicts;
+  for (const preset of manifest.presets) {
+    const found = existing.presets.get(preset.name);
+    if (found && presetDiffers(found, preset) && !updateRoles) {
+      conflicts.push(`preset "${preset.name}" exists with another command or Maestro setting; `
+        + 'rerun with --update-roles to replace it');
+    }
+  }
+  for (const { path: file, content } of teamFiles(manifest, read, home)) {
+    if (existing.files.has(file) && existing.files.get(file) !== content && !updateRoles) {
+      conflicts.push(`settings file ${file} exists with other content; rerun with --update-roles to replace it`);
+    }
+  }
+  const { agents, notes, portals, ficharios } = existing.canvas;
+  const kinds = { agent: agents, note: notes, portal: portals, fichário: ficharios };
+  const misused = (name, kind) => Object.entries(kinds).find(([k, set]) => k !== kind && set.has(name))?.[0];
+  for (const agent of manifest.agents) {
+    if (agents.has(agent.name) && agents.get(agent.name) !== agent.role) {
+      conflicts.push(`agent "${agent.name}" exists with role "${agents.get(agent.name)}", not "${agent.role}"`);
+    }
+  }
+  const named = [...manifest.agents.map((a) => [a.name, 'agent']), ...manifest.notes.map((n) => [n.name, 'note']),
+    ...manifest.fichario.pages.map((n) => [n.name, 'note']), [manifest.fichario.name, 'fichário'],
+    ...manifest.portals.map((x) => [x.name, 'portal'])];
+  for (const [name, kind] of named) {
+    const other = misused(name, kind);
+    if (other) conflicts.push(`${other} "${name}" you reach has a name the kit needs for its ${kind}`);
+  }
+  return conflicts;
+}
+
+// Pure plan: maestri argument lists, skipping what already exists.
+export function teamCommands(manifest, read, existing, options = {}) {
+  const { rolesOnly = false, updateRoles = false, home = os.homedir() } = options;
+  const commands = [];
+  for (const { role, text } of kitRoles(manifest, read)) {
+    if (!existing.roles.has(role)) commands.push(['role', 'create', role, text, '--scope', 'global']);
+    else if (updateRoles && existing.roles.get(role) !== text) commands.push(['role', 'write', role, text]);
+  }
+  if (rolesOnly) return commands;
+
+  for (const preset of manifest.presets) {
+    const found = existing.presets.get(preset.name);
+    const maestro = preset.maestro ? 'on' : 'off';
+    const settings = ['--command', preset.command, '--maestro', maestro];
+    if (!found) commands.push(['preset', 'create', preset.name, ...settings, '--quick-start', 'off']);
+    else if (updateRoles && presetDiffers(found, preset)) commands.push(['preset', 'set', preset.name, ...settings]);
+  }
+  for (const agent of manifest.agents.filter((a) => !existing.canvas.agents.has(a.name))) {
+    const launch = agent.preset ? ['--preset', agent.preset] : ['--command', agentCommand(agent, home)];
+    commands.push(['recruit', agent.name, '--role', agent.role, '--color', agent.color, '--icon', agent.icon, ...launch]);
+  }
+  const others = manifest.agents.map((a) => a.name).filter((n) => n !== manifest.maestro);
+  for (const [a, b] of [...others.map((n) => [manifest.maestro, n]), ...manifest.peers]) commands.push(['connect', a, b]);
+  for (const note of manifest.notes) {
+    if (!existing.canvas.notes.has(note.name)) commands.push(['note', 'create', noteText(read(note.file)), '--name', note.name, '--color', note.color]);
+    for (const agent of note.connect) commands.push(['connect', note.name, agent]);
+  }
+  for (const page of manifest.fichario.pages.filter((p) => !existing.canvas.notes.has(p.name))) {
+    commands.push(['note', 'create', noteText(read(page.file)), '--name', page.name, '--stack', manifest.fichario.name]);
+  }
+  for (const agent of manifest.fichario.connect) commands.push(['connect', manifest.fichario.name, agent]);
+  for (const portal of manifest.portals) {
+    if (!existing.canvas.portals.has(portal.name)) commands.push(['portal', 'create', portal.url, portal.name]);
+    for (const agent of portal.connect) commands.push(['connect', agent, portal.name]);
+  }
+  const { partitura } = manifest;
+  if (!existing.partituras.has(partitura.name)) {
+    commands.push(['partitura', 'create', partitura.name, ...manifest.agents.map((a) => a.name), '--without-me',
+      '--scope', 'global', '--commands', 'on', '--note-text', 'on', '--chat-history', 'off',
+      '--description', partitura.description, '--icon', partitura.icon, '--color', partitura.color]);
+  }
+  return commands;
+}
+
+// Settings files to write: the ones missing, and with --update-roles the ones that differ. Never with --roles-only.
+export function teamFileWrites(manifest, read, existing, options = {}) {
+  const { rolesOnly = false, updateRoles = false, home = os.homedir() } = options;
+  if (rolesOnly) return [];
+  return teamFiles(manifest, read, home).filter(({ path: file, content }) => !existing.files.has(file)
+    || (updateRoles && existing.files.get(file) !== content));
+}
+
+const quoted = (a) => (/^[\w./#@:-]+$/.test(a) ? a : JSON.stringify(a));
+const shown = (args, full) => `maestri ${args.map((a) => quoted(full || a.length <= 60 ? a : `${a.slice(0, 57)}...`)).join(' ')}`;
+
+const readIfExists = (file) => {
+  try {
+    return fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+  } catch (e) {
+    if (e.code === 'ENOENT') return undefined;
+    throw e;
+  }
+};
+
+const writeTeamFile = ({ path: file, content }) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+};
+
+// Everything read-only: prerequisites, then what Maestri and the home folder hold now. Throws before any change.
+function planInstall({ manifest, read, run, bin, home, tools, options }) {
+  const missing = missingPrerequisites(manifest, tools, { maestri: bin, rolesOnly: options.rolesOnly });
+  if (missing.length) throw new Error(`Nothing changed. Missing prerequisites:\n- ${missing.join('\n- ')}`);
+  const list = run(bin, ['list']);
+  if (!/maestro: true/.test(list.split('\n\n')[0])) throw new Error('Run this from a Maestri terminal in Maestro mode.');
+  const roleNames = new Set(listedNames(run(bin, ['role', 'list'])));
+  const presetNames = new Set(listedNames(run(bin, ['preset', 'list'])));
+  const files = teamFiles(manifest, read, home).map((f) => [f.path, readIfExists(f.path)])
+    .filter(([, text]) => text !== undefined);
+  const existing = {
+    roles: new Map(manifest.agents.filter((a) => roleNames.has(a.role))
+      .map((a) => [a.role, run(bin, ['role', 'show', a.role]).replace(/^Role: [^\n]*\n\n/, '').trimEnd()])),
+    presets: new Map(manifest.presets.filter((p) => presetNames.has(p.name))
+      .map((p) => [p.name, presetShown(run(bin, ['preset', 'show', p.name]))])),
+    files: new Map(files),
+    canvas: canvasEntries(list),
+    partituras: new Set(listedNames(run(bin, ['partitura', 'list']))),
+  };
+  const conflicts = teamConflicts(manifest, read, existing, options);
+  if (conflicts.length) throw new Error(`Nothing changed. Conflicts:\n- ${conflicts.join('\n- ')}`);
+  return [
+    ...teamFileWrites(manifest, read, existing, options).map((file) => {
+      const text = `${existing.files.has(file.path) ? 'replace' : 'write'} ${file.path}`;
+      return { full: text, brief: text, go: () => writeTeamFile(file) };
+    }),
+    ...teamCommands(manifest, read, existing, options)
+      .map((args) => ({ full: shown(args, true), brief: shown(args, false), go: () => run(bin, args) })),
+  ];
+}
+
+export async function teamMain(argv, { kit = fileURLToPath(new URL('../', import.meta.url)), out = console.log,
+  err = console.error, env = process.env, home = os.homedir(), tools = realTools({ env }),
+  run = (bin, args) => execFileSync(bin, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }) } = {}) {
+  if (argv.includes('--help')) { out(TEAM_HELP); return 0; }
+  const unknown = argv.filter((a) => !FLAGS.includes(a));
+  if (unknown.length) { err(`Unknown argument: ${unknown[0]}\n${TEAM_HELP}`); return 2; }
+  const options = { rolesOnly: argv.includes('--roles-only'), updateRoles: argv.includes('--update-roles'), home };
+  const dryRun = argv.includes('--dry-run');
+  const dir = path.join(kit, 'team');
+  const read = (file) => fs.readFileSync(path.join(dir, file), 'utf8');
+  const bin = env.MAESTRI_CLI || 'maestri';
+  let steps;
+  try {
+    steps = planInstall({ manifest: JSON.parse(read('team.json')), read, run, bin, home, tools, options });
+  } catch (e) {
+    err(e.stderr?.toString().trim() || e.message);
+    return 1;
+  }
+  out('Prerequisites found.');
+  if (!steps.length) out('The team is already installed as the kit defines it.');
+  for (const [index, step] of steps.entries()) {
+    out(dryRun ? step.full : step.brief);
+    if (dryRun) continue;
+    try {
+      step.go();
+    } catch (e) {
+      err(e.stderr?.toString().trim() || e.message);
+      err(`Stopped at step ${index + 1} of ${steps.length} (${index} done). Run the same command again to resume: `
+        + 'it skips what exists and finishes the rest.');
+      return 1;
+    }
+  }
+  if (!options.rolesOnly && !dryRun) {
+    out('Next: answer each new agent\'s startup prompts as the maestri-agent-cli skill describes, sign in to Gemini '
+      + 'in the portal, and run the check in team/README.md (Check section).');
+  }
+  return 0;
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "vibecoding-devtools",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "vibecoding-devtools",
-      "version": "1.0.1",
+      "version": "1.1.0",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "1.8.1"

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "vibecoding-devtools",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Rules, skills, hooks and templates for AI development with Claude Code, Codex and Antigravity.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Or4cu1o/vibecoding-devtools"
+    "url": "git+https://github.com/Or4cu1o/vibecoding-devtools.git"
   },
   "homepage": "https://github.com/Or4cu1o/vibecoding-devtools#readme",
   "bugs": {
@@ -16,6 +16,7 @@
     "installer/*.mjs",
     "!installer/*.test.mjs",
     "installer/third-party.json",
+    "installer/codex-maestri.rules",
     "hooks/*.mjs",
     "!hooks/*.test.mjs",
     "!hooks/README.md",
@@ -24,6 +25,7 @@
     "rules/",
     "skills/",
     "templates/",
+    "team/",
     "README.md",
     "LICENSE",
     "npm-shrinkwrap.json"

package/rules/maestri-usage.md

@@ -10,3 +10,5 @@ Applies only when you are the Maestro in Maestri coordinating other agents. Deta
   managed, and only between tasks.
 - Before an unrelated task, clear the agent's context (command in its CLI reference). Never compact or clear an agent
   in the middle of a task.
+- Do not ask the user a question while a delegated task can still report back: the agent's ask back lands in your
+  input and can overwrite the user's answer. Collect pending replies first, or warn the user that one may arrive.

package/skills/maestri-agent-cli/SKILL.md

@@ -137,8 +137,10 @@ Answering another agent's permission prompt approves an action on the user's beh
 ## 5. Configure, safest first
 
 1. **Launch flags**: model, effort and permission flags in the preset command, applied with
-   `maestri recruit "Name" --command "..."` (or `--replace "Name"`) or a preset. Each reference's **Model and effort**
-   says where the CLI lists its exact model ids and how to pass them: never guess an id.
+   `maestri recruit "Name" --command "..."` or a preset. On a running agent, `maestri recruit --replace "Name"
+   --command "..."` keeps its role, connections and position; it works although `maestri recruit --help` lists only
+   `--preset` and `--account` with `--replace` (verified 2026-11-06). Each reference's **Model and effort** says where
+   the CLI lists its exact model ids and how to pass them: never guess an id.
 2. **The CLI's settings file**, when the reference names it.
 3. **The TUI menu** (`/model`, `/config`...) through `--raw`, step by step.
 

package/skills/maestri-agent-cli/references/antigravity.md

@@ -71,6 +71,30 @@ See the [CLI permission reference](https://antigravity.google/docs/permissions#c
 
 `--dangerously-skip-permissions` auto-approves every tool request. Use only at the user's explicit request.
 
+### Verified limited agent
+
+Verified on Antigravity CLI 1.5.2, Linux, Google AI Pro (2026-11-06), with the global `toolPermission` set to
+`always-proceed`:
+
+```bash
+agy --model <id> --effort <level> --mode accept-edits --add-dir ../../.. --settings <file>
+```
+
+`<file>` is a JSON file with `"toolPermission": "request-review"` and the `permissions` lists; session settings
+override the global value. Prefer a file over inline JSON: inline JSON needs different quoting in POSIX shells and
+PowerShell. Keep the file at a stable path (the kit's `team` command writes it to
+`~/.vibecoding-devtools/team/task-runner-limited.json`), not in a cache that can disappear. Verified with a file in a
+throwaway folder: an allowed command (`ls`) ran, a denied one (`rm -f a.txt`) was refused with `Matches user-configured
+deny rule` and the file stayed, and an unlisted one (`uname -s`) showed the command prompt (headless `-p` auto-denies
+it). A complete allowlist for a helper agent is in `team/settings/task-runner-limited.json`.
+
+### Recruited with a role
+
+- The first start in each role folder (`<workspace>/.maestri/roles/<id>/`) asks `Do you trust the contents of this
+  project?`; Enter trusts it and saves it in `trustedWorkspaces`. A folder Maestri just created holds only the role
+  files.
+- Add `--add-dir ../../..` so the workspace root is part of the agent's workspace.
+
 ## Permission prompts
 
 File edit or creation:

package/skills/maestri-agent-cli/references/codex.md

@@ -48,6 +48,19 @@ Send the text, then `\n` in a separate `--raw` call.
 - Changing the permission mode lowers or raises what the agent may do on the user's behalf: ask the user first.
 - `/approve` approves one retry of a recent auto-review denial.
 
+## Recruited with a role
+
+Verified on Codex 0.167.0, Linux (2026-11-06).
+
+- A recruit with a role starts in `<workspace>/.maestri/roles/<id>/`, and workspace-write covers only that folder. Add
+  `--add-dir ../../..` to the command: `/status` then shows `Workspace [<workspace root>]`. A folder every Codex agent
+  may write goes in `~/.codex/config.toml` as `[sandbox_workspace_write]` `writable_roots = ["<path>"]`.
+- `AGENTS.md` from the role folder and from the repository both load (`/status` → `Agents.md`).
+- Startup can stop on **Hooks need review** (`1 hook is new or changed`). With the ECC plugin, its `SessionStart` hook
+  asked again at every start: Codex re-syncs the plugin cache on launch and the stored content hash no longer matches.
+  Esc skips it (that hook does not run; trusted hooks keep running); `t` in the review panel trusts it until the next
+  start. Trusting is a persistent choice: ask the user once, then repeat it at each start.
+
 ## Autonomous launch and command rules
 
 Verified on Codex 0.166.0, Windows (2026-11-06): local help, isolated rule checks and a live recruited agent.
@@ -185,6 +198,9 @@ Codex Document Control and Safety Settings. Maestri's skills in the list come fr
 - With `--no-daemon` the startup warning is:
   `Running without the shared background server: Bedrock sign-in requires embedded mode.`
 
+- Startup warning `Codex could not find bubblewrap on PATH` on Linux: Codex falls back to its bundled bubblewrap.
+  Installing the OS package removes the warning.
+
 ## Not yet observed
 
 Limit-reached screen, logged-out screen, API or network errors.

package/skills/maestri-protocol/SKILL.md

@@ -34,8 +34,8 @@ were given, or a question that is not a task) starts with one header line:
 - Summary: one line, no secrets.
 
 Details, evidence and lists go on the following lines; in PowerShell, use real line breaks, not `\n`. Keep the whole
-message inside quotes and avoid double quotes, backticks and `$` in it, which break the shell command. Never send a bare
-`ok` or `done`. One report per task; post progress with `maestri floor status`.
+message inside double quotes and avoid unescaped double quotes, backticks and `$` in it, which break the shell command.
+Never send a bare `ok` or `done`. One report per task; post progress with `maestri floor status`.
 
 ```text
 maestri ask "Maestro" "~ Hawk | DONE | T-12 | login screen wired, tests green, PR #412 open"
@@ -46,18 +46,23 @@ maestri ask "Maestro" "~ Kite | ACK | design-spec | reply format adopted"
 ## Delegating a task
 
 Give each task a ref (a task id like `T-12`, or the PR, branch or decision it concerns) and end the prompt with this
-footer, filled in with your name and the ref. Do this in `--batch` prompts too, and never ask for a bare `ok` reply.
+footer, filled in with your name (the address it reports to), the agent's name (who writes the report) and the ref.
+Do this in `--batch` prompts too, and never ask for a bare `ok` reply.
 
 ```text
 ref: T-12
 When done, load the maestri-protocol skill and report back with:
-maestri ask "Your Name" "~ Your Name | STATUS | T-12 | one-line summary"
+maestri ask "Your Name" "~ Agent Name | STATUS | T-12 | one-line summary"
 STATUS is one of DONE, PENDING, BLOCKED, ERROR, ACK. Details go on the following lines.
 ```
 
-Your name is under `You:` in `maestri list`; when the agent is in another workspace, use the `Name @ Workspace` address
-shown right under `You:` instead. The footer carries the whole format, so the agent can follow it even if it does not
-load this skill.
+When the prompt itself is wrapped in double quotes, escape the footer's quotes (`\"`) or write that one line with
+single quotes; the protocol hook accepts both. Your name is under `You:` in `maestri list`; when the agent is in another
+workspace, use the `Name @ Workspace` address shown right under `You:` instead. The footer carries the whole format, so
+the agent can follow it even if it does not load this skill.
+
+Pass each message as a literal argument. The protocol hook cannot read a message built at run time, such as
+`"$(cat task.md)"` or a variable, so such a message skips the check without warning.
 
 ## Receiving a message