--- name: fnl-setup description: Set up finolabs-vibecode for this machine and repository through a short interview: host config for delegation, local file placement, the agent-skills block in CLAUDE.md or AGENTS.md, and a pointer to user-scoped instructions. Run only when the user asks for it. disable-model-invocation: true --- # Set up finolabs-vibecode Explore, settle the user's choices, confirm, then write. Ask in text when the session has no such tool, the tool is refused or fails, nobody can answer (a delegated or headless run records the open decision and never assumes or invents an answer), or the decision is free text. The enforcer is agent judgment, so this is advisory. **Advisory (agent judgment):** Talk to the user in the language they are using, including questions and option labels; keep command names, flags, file paths, skill names and other technical names unchanged. Script output stays English; report it to the user in their language (advisory, agent judgment). On a bare invocation, ask one question first: "Set up, or check what is already set up?" Recommend **Check** when setup has already been run, otherwise **Set up**. Ask it through the host's native question tool when the session has one (`references/interview.md` says how). Wait for the answer before the setup interview. An explicit Check request goes straight to **Check**: load [references/check.md](references/check.md), follow it and stop. Load that reference only for Check or preferences. **Set up** continues below. Before the mode choice, offer the beginner path once in plain words, through the host's native question tool when the session has one: "Would you like a simpler setup? It leaves settings for other AI helpers, review tools and extra skills until later." Start it only when the user says they are new to coding or accepts the offer. Otherwise let the user choose the mode, through the host's native question tool when the session has one: **detailed** interviews each section, **quick** asks every decision once with its recommended default and writes after one confirmation (offer neutral Yes and No choices with none preselected or marked recommended; a default, a timeout or an auto-selected option never counts as the yes), except that consent to send data to a service (the route judge) is always asked on its own and never bundled. In quick mode, leave unsettled any item the findings cannot fill and name it in the report; the skill that later needs it, given the repository's context, asks the user once. Run setup again only when an agent on the machine is added or changed, a new plugin version adds a field to the host template, or the user wants a skipped section; it updates in place. **Beginner path.** Read [references/plain-language.md](references/plain-language.md) and follow its register for this conversation. Use Quick instead of the detailed interview below. Ask the preferences question below, then only for a final yes to the shown changes, through the host's native question tool when the session has one (Offer neutral Yes and No choices with none preselected or marked recommended; a default, a timeout or an auto-selected option never counts as the yes.) Ask one question at a time; skip a question whose answer is already known. Take the recommended default for the rest, and leave out section C's optional low-risk lane line. Tell the user this path skips A (host config for delegation), E (review tools), F (usage metrics, left off) and G (companions), and that they can run those sections later. End with the handover in section 4. ## 1. Explore Report only what you observe: - **Installed hosts** (section A uses `fnl-scan-agents` for the delegation inventory): `claude plugin list`, `codex plugin list`, `agy plugin list --json`. Note where `finolabs-vibecode` is installed and which agent CLIs exist (`codex`, `agy`, `claude`). - **Route judge**: whether a semantic evaluator skill such as `typesafe-ai` is installed (skill listing only; never look for its credentials). - **Review tools**: which review instruments each installed host has, from the skill listing and `--help` only: Claude Code `/code-review` and `/security-review`, Codex `codex review`, and the `security-audit` skill from Cloudflare. Antigravity has none. - **Companion skills**: which skills in [references/companions.md](references/companions.md) are installed, from the skill and plugin listings. - **Host config**: `host.md` under the root resolved by `scripts/data_root.py`; environment overrides never supply opt-ins. Present, missing, or still holding template placeholders. - **Repository**: the git root; whether it uses Spec Kit (`.specify/` plus installed `speckit-*` skills); which of `CLAUDE.md` and `AGENTS.md` exist and whether one already has an `## Agent skills` section; whether `.finolabs/` is excluded in `.git/info/exclude`. - **Knowledge base**: where the user keeps durable decisions that agents write to: a notes vault or knowledge-base server their user-scoped instructions name, with the access those instructions approve. - **Usage metrics**: whether the plugin's hooks are installed (the whole plugin, on Claude Code, Codex or Antigravity; a single skill installed alone has none) and whether `consent.json` already exists in the resolved data root's `state/` folder, with no environment redirect. Read only its date and retention. - **User-scoped instructions**: whether `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md` (or `$CODEX_HOME/AGENTS.md`) and `~/.gemini/GEMINI.md` (or `~/.gemini/AGENTS.md`) exist, and whether they already point coding work at `fnl-coding-router`. A check that cannot run here (a command or path is unavailable) is listed as **unverified** in one line, and the interview goes on. Done when the findings are listed for the user. ## Data location Before writing setup data, show the effective root and its source from `scripts/data_root.py`. Offer to keep the default (recommended) or move to an absolute local folder the user names, outside every git work tree. Run `python3 -I /scripts/data_location.py preview --to ` and show the file list and `Digest:`. It copies only regular `host.md`, `ledger.jsonl` and files under `state/`, `logs/` and `bin/`; it skips `tmp/` and symlinks. Ask separately whether to copy to that target, through the host's native question tool when the session has one, otherwise in text. Offer neutral Yes and No choices, with none preselected or marked recommended; a default or timeout never counts as consent (agent judgment, advisory). Only after a clear yes run `python3 -I /scripts/data_location.py apply --to --yes --digest `. The script requires the full 64-hex digest (prefixes are refused), checks it again, refuses a non-empty target, copies into private folders and writes the pointer last and atomically. The old folder stays untouched; the user removes it. An invalid pointer disables opt-ins; report it and resolve it with the user before any consent-bearing setup write. ## 2. Grill Settle sections A–G. Sections whose findings are verified are ready first; a section that depends on an unverified item waits until the user supplies that fact. Interview by the rules in [references/interview.md](references/interview.md): map the decisions, look up facts yourself, ask every ready decision in one numbered round with a recommended answer, and finish with a read-back and a yes. **Preferences** (also on the beginner path). Ask one question, through the host's native question tool when the session has one: “How should I hand work to other AI helpers: manual, suggest (recommended), or auto; and should the coding guideline start automatically: on (recommended) or off?” Explain the choices via `fnl-delegate`'s mode section when installed. Use `/fnl-set-mode` to preview and write the confirmed `## Delegation mode` and `## Routing` values in host config after a clear yes; see [references/check.md](references/check.md#settings) for limits and missing-skill handling. Offer neutral Yes and No choices with none preselected or marked recommended; a default, a timeout or an auto-selected option never counts as the yes. **A. Host config** (skip when complete). Skip this section when the `fnl-delegate` skill is not installed. Dependency: `fnl-scan-agents`. Run that skill's procedure with the running host passed explicitly, including its model confirmation, preview and clear yes before its section-only write. If it is unavailable, leave the inventory unverified and point to that command; never guess which families exist. Offer to create the remaining config from `fnl-delegate`'s `references/host-template.md`, preserving the scan section byte for byte, and fill: how this machine invokes the present agents, which agents may coordinate and which delegates each can reach, the parallel limit (5 or fewer), the heavy-job lock path, and the durable folder for briefs and logs. When Antigravity is a delegate, list this repository's test and check commands and ask which to grant it as remembered allow-rules; say that a granted test command runs whatever code the tests contain. Grant only each exact test command, never a wildcard or a general shell, record every granted command in the host config, and keep a grant to this repository: it is not carried to another. After the user names the commands, with `agybird`, the first run that needs one reports `needs_permission` and the user picks "allow and remember" (`--grant-scope remember`); without it, the user adds the literal rules to Antigravity's own settings. The host config only records the answer. When more than one agent coordinates, recommend a host config and ledger path every coordinator's sandbox can read and write. **Quota probe** (section A, after the scan; optional, off by default). Advisory (agent judgment): offer only agents the scan recorded present, as a separate consent question: "Every 4 hours a background step runs each agent's own read-only usage command (`agy`, `claude`, `codex`) to read your usage limits; those programs contact their providers with your own accounts, and the plugin sends nothing about you." For Claude add: "The probe starts each Claude Code install with its usual configuration; the default install runs without `CLAUDE_CONFIG_DIR` and listed extra folders with it set; its hooks, plugins and servers run." Offer neutral Yes and No choices with none preselected or recommended; a default or timeout is not consent. A No leaves probing off. Advisory (agent judgment): after interest in opting in, run `python3 -I /scripts/quota_setup.py preview --agents ` with selected names from `agy claude codex`. Add each extra Claude folder as `--claude-config 'label:/absolute/folder'`; the default install counts toward four. Show the section, including every confirmed executable path and its resolved target, interpreter and config folder, then ask for a clear yes to those exact paths. Preview saves that plan, its creation time and its digest privately in `/state/quota/preview.json` (mode 0600). Apply only that stored preview with `quota_setup.py apply --digest --yes`; a successful apply removes it. The script refuses previews older than 60 minutes and enforces the digest, current host content, canonical root, owner/mode/ancestor checks and folder validation; it re-validates the stored plan, resolves executables only in preview and runs no usage command. Resolution searches the session `PATH`; the confirmed path's basename must equal the selected agent name (`agy`, `claude` or `codex`). The preview shows its resolved target beside it, which the user also confirms; the target may have a versioned filename. Both paths are recorded, and execution uses the checked resolved target. To withdraw consent, preview `--off` and confirm its apply in the same way. The hooks enforce the separate opt-in, stale-cache cadence and backoff; `FNL_QUOTA_PROBE=off` disables it. With neither a cache nor backoff yet, the first reading starts immediately; the hook writes a 30-minute retry reservation before starting its worker. Scan and Check display cached readings, not runtime proof. When the findings show a judge skill such as `typesafe-ai` installed, read [references/route-judge.md](references/route-judge.md) and settle the route judge with it; otherwise record "none" without asking, since routing works without one. Recommend the defaults the template names; leave unknown commands as questions in the file rather than guesses. **B. Local files**. Recommend adding `.finolabs/` to `.git/info/exclude` so briefs and logs stay out of git (a repository that still has the older `.orchestration/` folder keeps that one excluded too, and keeps using it until the user moves it). The shared `.gitignore` changes only if the user asks. **C. Agent skills block**. Offer a short `## Agent skills` section for the agent context file that already exists (prefer the one the repository uses; never create the second file). Draft: ```markdown ## Agent skills This repository uses the finolabs-vibecode skills. When Routing is on, start coding work with `fnl-coding-router`; it routes to the other `fnl-` skills. Pull requests merge only after a code review and a security review are posted on them, as `fnl-review-gate` says; reviewers may post those comments. Type `/fnl-ask` when unsure which skill fits. ``` Offer the optional lane only for a single-owner repository. The script enforces eligibility: root human-facing documents and manifest version bumps, excluding agent context, skills, agents and rules. The reviewer also checks README install instructions; outside authors still need owner approval. **D. User-scoped instructions**. When the findings show no user-scoped instructions, or ones that restate coding rules the plugin now covers, record the need for the handover in section 4. `fnl-setup-instructions` interviews them and writes their working contract for every host; this one only points to it. **E. Review tools**. The `fnl-reviewer` and `fnl-security-reviewer` agents run these instruments as their engine, so a review meets the standard only where they are installed. For each one the findings show missing, strongly recommend installing it and give the command: for `security-audit`, `npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit`; for a host's native review, the host's own update or install path, checked against its docs. Install nothing yourself. Until a tool is installed, the reviewers work by hand and say so in each report. **F. Usage metrics** (optional; skip when the hooks are not installed). Offer to record usage metadata so the user can see how the practice performs on their own machine. Say, in this order: what is recorded (a time, a session id, a short repository code, a skill or agent name, the router's depth, a review verdict, the number of tasks a coordinator kept with a fixed reason and who settled it, judge receipt site, grader, result and followed status; never prompts, code, command text or file paths), where it lives (the state folder on this machine, readable only by the user), that nothing leaves the machine and the dashboard is a local page, and that it stays off until they say yes and `FNL_METRICS=off` turns it off at any time. Then ask for consent and the retention as one question of its own, never bundled with another, through the host's native question tool when the session has one. Offer neutral choices: Yes, 30 days; Yes, 90 days; Yes, 365 days; or No, with none preselected or marked recommended; a default, a timeout or an auto-selected option never counts as the yes. Claude Code records skill and agent use, first edits, commits, review comments, the router's depth, keep and judge receipts; Codex records sessions, first edits, commits, review comments, the router's depth, keep and judge receipts (it reports no skill or agent use), and the user must also trust the plugin's hooks once, with `/hooks`, or they stay off. Antigravity records the same events as Codex, but its hook is not part of the plugin, because a plugin hook's working folder is unverified: with the user's clear yes, after showing what it adds, run `python3 -I /scripts/refresh.py antigravity-hook --yes`. It merges one group, `finolabs-vibecode`, into `~/.gemini/config/hooks.json` with an absolute path to the script, leaves every other group alone and keeps a backup of the file; `--remove` takes it out. The command refuses unless the skill sits inside the `finolabs-vibecode` plugin, so a hook script from some other folder is not written into the user's config by mistake. That file is shared Gemini configuration, so never run it unasked. A declined or skipped section leaves everything off. **G. Companion skills**. Read [references/companions.md](references/companions.md) and record each missing skill whose condition the findings match for the handover in section 4. Install nothing yourself. **Compaction suggestion** (optional). Ask through the host's native question tool when the session has one, otherwise in text, whether the user wants that guidance. Offer neutral Yes and No choices with none preselected or marked recommended; a default, a timeout or an auto-selected option never counts as the yes. After a clear yes, suggest Claude Code's or Codex's native threshold controls from `fnl-session-hygiene` "Context pressure", rechecking their presence on the installed version. Prescribe no value; keep unverified behavior labelled. Antigravity has no supported setting, only `/compact`. The host enforces thresholds; the user makes or confirms shared-setting changes. This skill writes no compaction setting, even after a yes. Enforcer: agent judgment, advisory. ## 3. Confirm and write Show each draft and apply the user's edits. Then write only what was confirmed: the host config (outside the repository), the exclude line, and the agent-skills block (update an existing block in place). After a yes to section F, run `python3 -I /scripts/refresh.py consent --retention ` to record the consent with its date, then `python3 -I /scripts/refresh.py run` once so the dashboard exists; `fnl-status` must be installed beside this skill, and when it is not, say so and skip the section. When the findings show a knowledge base, also record the settled decisions there as `fnl-session-hygiene` "Remember or recall" says (the route judge and the date of consent, which agents coordinate, the parallel limit, the host config path), through the access the user's instructions approve. Write to the one knowledge base those instructions name, and report any write that failed. Install nothing and change no shared settings. ## 4. Report Offer `/fnl-setup` **Check** to see what is configured and what still needs observation on each host. List each file written, each item skipped and why, and anything left for the user (for example installing the plugin on another host, using the commands in the plugin's README). At the end of setup, say an **After your first result** list to the user, marking the Codex instructions step as immediate: - When section D recorded the need, type `/fnl-setup-instructions` to set how the assistants work with you. On Codex, instead type `$fnl-setup-instructions` immediately after setup, before the first task, so it follows the coding router. - Consider each missing companion whose condition the findings match in [references/companions.md](references/companions.md), with its install commands. Include these reminders even when the beginner path skipped section G. - For the beginner path, revisit the skipped sections listed above by running setup again when needed. Usage metrics stay off until the user runs section F, which explains what is recorded and, on Codex and Antigravity, the hook step that turns recording on. End by pointing to the immediate instructions step on Codex; on other hosts, ask the user to describe what they want to build.