vibecoding-devtools 1.0.2 → 1.1.0

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.2",
+  "version": "1.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "vibecoding-devtools",
-      "version": "1.0.2",
+      "version": "1.1.0",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "1.8.1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibecoding-devtools",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Rules, skills, hooks and templates for AI development with Claude Code, Codex and Antigravity.",
   "license": "MIT",
   "repository": {
@@ -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
 

package/team/README.md

@@ -0,0 +1,139 @@
+# Web development team
+
+A permanent multi-agent team for the Maestri canvas: one Maestro and twelve specialists for web apps, APIs,
+automations, bots and services. This folder is the versioned source of the team. Maestri holds the live copy as global
+roles and the global partitura `vibecoding-devtools`.
+
+## Layout
+
+| Path | Content |
+|---|---|
+| `roles/<role>.md` | Role prompt of each agent, without the shared block |
+| `roles/_team-protocol.md` | Block appended to every role when it is installed |
+| `notes/team-roster.md` | Permanent `Team Roster` note: agents, pools, topology, approvals, contingencies |
+| `notes/project-context/*.md` | Blank pages of the `Project Context` fichário, filled per project |
+| `team.json` | Manifest: agents, launch commands, colors, ropes, notes, portal and partitura |
+| `settings/task-runner-limited.json` | Antigravity session allowlist for the Task Runner; installed as a file in `~/.vibecoding-devtools/team/` |
+| `partitura/vibecoding-devtools.maestripartitura` | Export of the partitura from the Maestri app: roles, commands, notes, portal, ropes |
+
+The prompts rely on the kit rules (`base`, `risk-process`, `testing`, `maestri-messaging`) and the
+`maestri-protocol`, `risk-triage`, `security-surfaces`, `maestri-agent-cli` and `maestri-budget` skills, installed for
+every CLI by the kit installer; they do not repeat them.
+
+## Agents
+
+| Agent | Role | Launch command |
+|---|---|---|
+| Regente | Team Maestro | preset `Team Maestro` (Maestro on): `claude --model claude-opus-5-5 --effort high --permission-mode auto --add-dir ../../..` |
+| Vitral | Frontend Engineer | `claude --model claude-sonnet-5-5 --effort high --permission-mode auto --add-dir ../../..` |
+| Bússola | UX/UI Designer | `claude --model claude-opus-5-5 --effort high --permission-mode auto --add-dir ../../..` |
+| Alicerce | Backend Architect | `claude --model claude-sonnet-5-5 --effort high --permission-mode auto --add-dir ../../..` |
+| Sentinela | AppSec Auditor | `claude --model claude-opus-5-5 --effort medium --permission-mode auto --add-dir ../../.. --disallowedTools Edit Write NotebookEdit` |
+| Crivo | Code Reviewer | same as Sentinela |
+| Guindaste | DevOps Engineer | `claude --model claude-sonnet-5-5 --effort medium --permission-mode auto --add-dir ../../..` |
+| Forja | Backend Engineer | `codex --no-daemon --approve-for-me -m gpt-6.1-sol -c model_reasoning_effort=medium --add-dir ../../..` |
+| Ensaio | QA Engineer | same as Forja |
+| Aquarela | Visual Asset Designer | `codex --no-daemon --approve-for-me -m gpt-6.1-sol -c model_reasoning_effort=low --add-dir ../../..` |
+| Retina | Visual QA Inspector | `agy --model gemini-4-argon-medium --effort medium --mode auto --add-dir ../../..` |
+| Sonda | Research Analyst | `agy --model gemini-4-argon-high --effort high --mode auto --add-dir ../../..` |
+| Formiga | Task Runner | `agy --model gemini-3.8-flash-medium --effort medium --mode accept-edits --add-dir ../../.. --settings <file>` |
+
+- Recruits start in `<workspace>/.maestri/roles/<id>/`, so `--add-dir ../../..` always points at the workspace root.
+  Every Claude command has it too. It is variadic: keep it before `--disallowedTools` or last. The preset
+  `Team Maestro` (its own name, so the kit never creates or changes a generic preset such as `Maestro Opus High`)
+  carries it as well; start a Maestro with it from a role folder, since from the workspace root `../../..` points
+  three folders above it.
+- `<file>` is `task-runner-limited.json` in `~/.vibecoding-devtools/team/` (a path, quoted if it has spaces), written by
+  `team` from `settings/task-runner-limited.json`: a stable path that does not depend on the npx cache and works in
+  POSIX shells and PowerShell. Commands outside its allowlist prompt.
+- Model ids change: check `codex debug models` and `agy models` before reusing a command.
+
+## Topology
+
+Regente connects to every agent. Peer ropes: Vitral with Bússola, Alicerce, Ensaio, Crivo and Retina; Bússola with
+Retina and Aquarela; Alicerce with Forja, Guindaste and Sentinela; Forja with Ensaio, Crivo and Sentinela; Guindaste
+with Sentinela and Crivo. Sonda and Formiga talk only to Regente. `Team Roster` is wired to Regente; the
+`Project Context` fichário to Regente and every agent except Sonda, Aquarela and Formiga; the `Gemini` portal to
+Aquarela.
+
+## Install
+
+Run on the machine where the agent CLIs run, from a Maestri terminal in Maestro mode. Maestri itself may run on another
+computer (see [Maestri on a remote machine](../docs/maestri-remote.md)).
+
+```bash
+npx vibecoding-devtools team --dry-run      # preview the maestri commands
+npx vibecoding-devtools team --roles-only   # create or update the global roles
+npx vibecoding-devtools team                # also preset, agents, ropes, notes, portal and partitura
+```
+
+`team/team.json` is the manifest the command reads. Before running any `maestri` command, also with `--dry-run`, it
+checks read-only that everything the launch commands need exists, lists what is missing together and stops with exit 1:
+
+- each CLI on `PATH` (`maestri`, `claude`, `codex`, `agy`);
+- each Codex model in `codex debug models` and each Antigravity model in `agy models`; Claude models are not checked,
+  since there is no offline list;
+- ECC in Claude Code (`claude plugin list` shows `ecc@`), because the Team Maestro role uses `/ecc:plan`.
+
+`--roles-only` launches nothing and needs only `maestri`. Then, before changing anything, it stops on conflicts: a role
+with other text, a preset with another command or Maestro setting, a Task Runner settings file with other content (each
+replaced with `--update-roles`), and an agent you reach with another role. It writes the settings file when missing,
+leaves identical roles and files alone and skips agents, notes and the portal you already reach and a partitura that
+already has the name. `--dry-run` prints `write <path>` for the file and writes nothing. Then answer each agent's
+startup prompts and sign in to Gemini in the portal.
+
+### Resume after a failure
+
+The run is safe to repeat. If a step fails midway (a recruit that errors, a lost connection), the command prints the
+`maestri` error, the step it stopped at and `Run the same command again to resume`. Running the same command again
+skips what exists (roles, preset, settings file, agents, notes, portal, partitura), `maestri connect` on an existing
+rope prints `already connected` and exits 0, and the rest is created. A conflict or a missing prerequisite still stops
+before any change.
+
+Without the CLI, import `partitura/vibecoding-devtools.maestripartitura` in the Maestri app. The file carries the 13
+role prompts with the team protocol, the launch commands, the notes and the portal, matching `roles/`, `notes/` and
+`team.json`; it holds no chat history.
+
+## Check
+
+After an install, as the Maestro (Regente) or the installer:
+
+1. `npx vibecoding-devtools team --dry-run` prints only `connect` lines: roles, preset, agents, notes, portal and
+   partitura match the kit.
+2. Each agent's screen shows its model and effort, and the expected mode (`auto mode on`, `Workspace [...] (Approve for
+   me)` in Codex `/status`, `auto` or `accept-edits` in Antigravity).
+3. Regente sends one `maestri ask --batch` with a ref to every agent asking, without changing files, for its role in
+   one line, its working folder and writable project root, the first line of `Requirements` when `Project Context` is
+   wired to it, and whom it reports to. Every answer matches its role and the topology above.
+4. One peer exchange works, for example Vitral asks Bússola where the design system lives and relays the answer.
+
+## Use in a project
+
+Insert the partitura into the project's workspace, from the Maestri palette or as a Maestro:
+
+```bash
+maestri partitura insert "vibecoding-devtools"
+```
+
+Then fill the instance block of `Requirements` with Regente. The portal keeps the browser session of the computer
+running Maestri; sign in to Gemini there once.
+
+## Update
+
+Edit the role files or `team.json`, then run `npx vibecoding-devtools team --roles-only --update-roles` to rewrite the
+installed roles that differ. A full `team --update-roles` also replaces the Maestro preset with `maestri preset set`
+when its command changed, and the Task Runner settings file when its content changed.
+Maestri restarts the agents that use a rewritten role, and their chat context is lost: run it between tasks.
+Agents already recruited keep the command they were launched with (the preset command applies to new terminals only).
+To apply a changed command, run `maestri recruit --replace "<agent>" --command "<command>"` for that agent between
+tasks, with the command from the table above and, for Formiga, the path of the settings file. Save the partitura again
+with `maestri partitura update "vibecoding-devtools" <agents> --without-me` when agents, ropes or notes change, then
+export it again from the Maestri app over `partitura/vibecoding-devtools.maestripartitura`.
+
+## Known limits
+
+- Maestri roles have no color; tier colors are listed in `Team Roster`.
+- Sentinela and Crivo lose the Edit and Write tools only; the shell can still write, so read-only is role-enforced.
+- Codex runs in the workspace-write sandbox without shell network by default; installs ask for approval.
+- Gemini images captured through the portal are rendered pixels: no transparency, possibly below the original size.
+  Downloads from the portal land on the computer running Maestri, not on the server.

package/team/notes/project-context/acceptance-criteria.md

@@ -0,0 +1,6 @@
+# Acceptance Criteria
+
+Owner: Regente, with Ensaio. Each criterion is testable and has an id.
+
+| Id | Criterion (given / when / then) | Verified by | Status | Evidence |
+|---|---|---|---|---|

package/team/notes/project-context/code-standards.md

@@ -0,0 +1,8 @@
+# Code Standards
+
+Owner: Alicerce (backend) and Vitral (frontend); Crivo reviews against it. Canonical: repository `AGENTS.md` and
+linters. Record here only what the linters do not enforce.
+
+- Commands (lint, typecheck, test, build): see `AGENTS.md`.
+- Risk map: see `AGENTS.md`.
+- Project-specific rules:

package/team/notes/project-context/contracts-integrations.md

@@ -0,0 +1,10 @@
+# Contracts & Integrations
+
+Owner: Alicerce. Canonical: OpenAPI and schema files in the repository. Changes are announced to Forja, Vitral and
+Regente before they land.
+
+| Contract | File | Version | Consumers |
+|---|---|---|---|
+
+| External service | Client folder | Official docs | Notes |
+|---|---|---|---|

package/team/notes/project-context/decisions.md

@@ -0,0 +1,7 @@
+# Decisions
+
+Owner: Regente. Architecture records live in repository `docs/adr/` (Alicerce); this log indexes every decision,
+accepted risk and approved contingency.
+
+| Date | Ref | Decision | Reason | Approved by |
+|---|---|---|---|---|

package/team/notes/project-context/design-system.md

@@ -0,0 +1,8 @@
+# Design System
+
+Owner: Bússola. Canonical: repository `DESIGN.md` (impeccable). This page only points to it.
+
+- `DESIGN.md` path:
+- Prototypes path:
+- Breakpoints:
+- Current tokens summary (color, type, spacing):

package/team/notes/project-context/ops-runbook.md

@@ -0,0 +1,10 @@
+# Ops Runbook
+
+Owner: Guindaste. Canonical: repository `docs/runbook/`.
+
+| Environment | URL | Deploy method | Rollback | Health check |
+|---|---|---|---|---|
+
+- Backups (what, where, how often, restore test date):
+- Secrets location (store name only, never values):
+- Monitoring and alerts:

package/team/notes/project-context/requirements.md

@@ -0,0 +1,23 @@
+# Requirements
+
+Owner: Regente. Canonical: repository `docs/requirements.md` when it exists; this page indexes it.
+
+## Instance (fill first)
+
+- Project:
+- Repository path / workspace:
+- Default branch:
+- Run locally (command, URL, ports):
+- Artifacts path (screenshots, reports):
+
+## Goal
+
+## Users
+
+## In scope
+
+## Out of scope
+
+## Constraints (stack, deadline, budget, compliance)
+
+## Open questions