finolabs-vibecode

Agent context for contributing to this repository. User-facing documentation is in README.md.

What this repository is

One plugin with a skill set that gives AI coding agents a single engineering practice: routing of coding work, agent delegation, session hygiene, versioning, commit messages, code and security review gates, verification, and open source readiness. It also carries optional, consent-based usage metrics (hooks that record metadata only, and a local dashboard that fnl-status opens). It ships to Claude Code (.claude-plugin/plugin.json), Codex (.codex-plugin/plugin.json) and Antigravity (.antigravity-plugin/plugin.json) from one skills/ folder. Keep each host's manifest in its own folder: a root plugin.json would be read by both Codex and Antigravity, whose schemas conflict.

Conventions

• Every rule a skill states names its enforcer: a host setting, a hook, the review gate, or agent judgment. A rule enforced only by agent judgment is marked advisory and never promised as automatic.
• Compose before you build. Before adding a capability, look for a native host command or a trusted published skill that already does it: a known organization or author, an OSI license, active maintenance, readable instructions, no hidden network or credential behavior. Point to it by name with its source and install command, keep a fallback in our skill that holds the same quality bar without it, and credit it in the README. Our skills own routing, depth, delegation, gates and conventions.
• Every skill lives in skills/fnl-<name>/SKILL.md; the folder name equals the name field, and every name starts with fnl-. Skills refer to each other by their fnl- names.
• Each skill folder is self-contained, so it works when installed alone through skills.sh: nothing in it points outside its own folder. A file two skills need is copied into both (CI checks the copies match); a skill that needs another names it as a dependency.
• Each skill stays focused, with a trigger-rich description that leads with what the skill does and lists the distinct cases that should fire it. Disclose reference material into references/ and executable helpers into scripts/.
• Host-specific facts (paths, commands, shims, allow-rules) belong in the host config described by fnl-delegate, never in skill bodies.
• Content is generic: no organization, customer or personal names, and no machine paths. Examples use synthetic names.
• All content is English.
• Usage metrics hold metadata only and stay off until the user consents. A new event field goes through SCHEMA in scripts/fnl_metrics.py and docs/specs/usage-metrics.md, never carries prompt, code, command text or paths, and updates PRIVACY.md. A hook never blocks a session: it exits 0 and fails closed, except for the two scoped exceptions in the next two rules.
• One scoped exception to that hook rule (owner decision, 05/11/2026; design in docs/specs/release-0.1.8.md, package 7): the opt-in auto gate may deny the first file write in a repository when Delegation mode is auto, the user opted in during setup and no decision was recorded for that repository in the last 8 hours (and no denial was issued in that window). It allows on every other path and on any error, never blocks a session start, a stop or a read, and FNL_AUTO_GATE=off removes it. No hook other than the two scoped exceptions blocks, and no code for the gate lands before this rule is merged.
• Second scoped exception (owner decision, 06/11/2026; design in a compaction-stop spec, written with the PRIVACY.md and fnl-setup changes before any code): the opt-in compaction stop on Antigravity, which has no host threshold. It is off unless the user turned it on in fnl-setup with a consent question of its own and a shown preview of the change, recorded in the canonical host config under the data root; if that cannot be resolved it is off. It is one hook in its own group in the user's own Antigravity hook configuration, never in the metrics group, installed and removed by a script that offers a dry run, keeps a backup and accepts only a bounded integer limit the user chose. On Antigravity's pre-invocation event only, at the first model call of a user turn (so the turn ends before the model runs and spends nothing), it may end that turn with one fixed message asking the user to run /compact or start a fresh session, when the transcript is over that limit. It never denies a tool call, a prompt, a session start or the user's own stop or quit, and never reads the transcript's content: it takes only the size of a regular file, not a symlink, inside the host's conversation folder. It stops at most once per conversation until the size has grown 10% beyond the size at the last stop; that mark is written atomically before the message, is reset when the transcript shrinks, is keyed by a hash of the conversation id in the data root's private state folder and holds no content. If the mark cannot be written or any check fails, it allows. It sends nothing anywhere. --remove takes it out and FNL_COMPACT_STOP=off disables it. No other hook blocks, and no code for it lands before this rule is merged.
• The update check is the one network call the plugin makes on its own initiative (the quota probe below runs the user's own programs; the opt-in judge call in the fourth scoped exception below is the only other network call, made only when the coordinator or the user runs it): a detached worker makes a GET to the fixed public GitHub latest-release endpoint, sends nothing about the user, and stores only a timestamp and validated stable tag. It is on by default, separate from metrics consent; FNL_UPDATE_CHECK=off stops it. The session-start hook reads local state only, never waits for the worker, exits 0 and fails closed. See docs/specs/update-check.md.
• Scoped exception to the network rule above (owner decision, 05/11/2026; this text governs, and docs/specs/release-0.1.8.md package 13 may only narrow it): the opt-in quota probe. The data root below is the plugin's data folder, ~/.finolabs/vibecode/ by default.
  • Opt-in: off by default; it runs only when the user turned it on in setup and the host config in the data root records it, read only from that canonical file. If the data root cannot be resolved, or its pointer exists and is invalid, the probe is off.
  • Cadence (owner decision, 07/11/2026, replacing the 4-hour timer; design in docs/specs/quota-on-demand.md): no timer, and no hook starts a reading. A reading starts only when the coordinator is about to route a delegation and a candidate family's cached reading is older than 15 minutes, by running the plugin's quota_probe.py read command for that family, or when the user runs that command; at most one new reading per family per 15 minutes, a successful reading is not repeated within 15 minutes whatever age a caller passes (a lower --max-age-minutes is raised to 15), a failed run retried no sooner than 30 minutes later and a reply of an unexpected shape no sooner than 24 hours later. One reading runs at a time (a single in-flight marker); the command waits for its own run (one command per install of the family, each within the 30-second limit) and never starts a detached worker.
  • Hook: one hook entry in the Claude Code manifest only, for the StopFailure event, may record that Claude Code hit a rate limit, only when the event's error is exactly rate_limit and the probe is on in the canonical host config: the family and the time, nothing else, in the private state folder (no-follow, owner-checked, locked, atomic, input capped; any failure writes nothing). It starts no process and sends nothing. The marker is advisory: a repository can influence the error, so a newer successful reading of that family overrides it, it never excludes more than the family from routing offers, and the user's statement wins. The coordinator treats a marker as out of quota until the family's cached reset time when that lies within five hours after the marker, else for one hour after the marker. Every other hook only reads the cache.
  • Commands: only these commands of the user's own programs: agy -p /usage --output-format json; claude -p "/usage" --output-format json once for the default install and once per config folder the user listed (each absolute, owned by the user, not a symlink, not group- or world-writable and outside every git work tree, at most four in all, cached under the user's own labels; CLAUDE_CONFIG_DIR is set explicitly to each listed folder and left unset for the default install, whose folder and login the program resolves itself); and codex app-server limited to the initialize and initialized messages and the account/rateLimits/read request, ignoring every request the server sends.
  • Execution: each executable is resolved once at setup to an owner-checked absolute path the user confirmed, run with a fixed argv, no shell, an allowlisted environment, a neutral empty working folder, a 30-second limit with its whole process group killed, and a 64 KiB output cap. An executable inside a git work tree is refused, except under the Homebrew prefix (owner decision, 07/11/2026): the only git work tree allowed is the one rooted at exactly /opt/homebrew, so a nested repository (a tap, a clone) stays refused; the resolved target and any interpreter must lie inside that prefix, with no symlink leaving it; every component from the prefix to the file is owned by the user and not world-writable, and may be group-writable only when its group is admin; the preview shows the path for the user to confirm.
  • Data: the cache, the single in-flight marker, the rate-limit markers and the backoff times live in the data root's private state folder, never in a location a repository can redirect; the plugin stores only group names, windows, remaining fractions, reset times, the source, the time of the reading, the next allowed attempt and error class, the family and time of a rate-limit marker, and the user's own labels.
  • Network: those programs contact their providers with the user's own accounts; the plugin makes no network call and sends nothing about the user. FNL_QUOTA_PROBE=off stops the probe. No other command is run, no other network call is added beyond the scoped exceptions in this list, and no code for the probe lands before this rule is merged.
• Third scoped exception (owner decision, 06/11/2026; design in docs/specs/running-agents.md): the opt-in process snapshot on the dashboard. The dashboard refresh may run ps once per refresh, read-only, as the current user, to count command-line agent processes. It uses a fixed argv, an absolute path owned by root and not a symlink or group- or world-writable, no shell, an allowlisted environment, a neutral working folder, a 2-second limit with the whole process group killed and a 256 KiB output cap. It keeps only fixed family names, counts and elapsed seconds, never arguments, paths, environment values or user-chosen names. It runs only when metrics consent is recorded and fnl-setup has turned the snapshot on (off by default); FNL_AGENT_SNAPSHOT=off stops it. No other command is run, no network call of its own is added, and no code for the snapshot lands before this rule is merged.
• Fourth scoped exception (owner decision, 07/11/2026; design in docs/specs/agent-roles.md part I): the opt-in judge call to TypeSafe. Opt-in: it exists only when the user chose Jev as the judge in fnl-setup (judge: jev in ## Agent roles of the canonical host config under the data root, read only from that file; if the data root cannot be resolved or its pointer is invalid, the call is off; absent or host means no call) and TYPESAFE_API_KEY is set in the environment of the process. Trigger: judge.py makes one HTTPS POST per judgment to the fixed endpoint https://api.typesafe.ai/v1/systemone, only when the coordinator or the user runs it for one site of a closed list (a verification criterion, a navigator question, an uncertain compaction boundary, a delegation grade), never from a hook, a timer or a worker. Payload (enforced by judge.py): the request is built from a closed schema per site, in English, with each field and the whole body capped in size; a field that matches a secret or path pattern makes the call refuse before sending, and tests cover both refusals. Which fields to include is agent judgment (advisory); the script bounds what can leave. Credential: the key is read only from that environment variable, sent only in the request header, and never printed, logged, stored, copied into a packet or passed to a child process. Transport: TLS verification stays on; the call has a fixed timeout, follows no redirect and ignores proxy and certificate-override variables; a different base URL is accepted only through a flag the user types on the command line, only as a literal loopback IP address over http, for tests, and never from the environment or a repository file. Failure: a timeout, a refusal status (401, 429), a missing key, a DNS or TLS failure, or a reply that does not validate (capped, closed schema) ends the call; the fallback is the small host model and the report says so, never silence. A call count per run is capped by judge.py as the spend guard. TypeSafe is the organization-approved data processor named in the owner's user-scope instructions; the plugin sends nothing about the user beyond the payload. PRIVACY.md (section "Judge") and the spec carry this text from the pull request that records this rule, and the fnl-setup consent text lands in the same pull request as the code or before it. FNL_JUDGE=off stops the call. No other network call is added, and no code for the judge call lands before this rule is merged.
• Scoped exception to the metadata-only rule above (owner decision, 06/11/2026; design in docs/specs/dashboard-infographics.md): the dashboard may keep one repository folder name per repository, so that a project can be shown by name. The name is the base name of the repository root found from the directory where the command runs (in a linked worktree that is the worktree folder), sanitized to ASCII letters, digits, space, dot, dash and underscore and cut to 40 characters, stored with the repository code in the private state/projects.json (owner-only file, at most 50 entries) and copied into the dashboard's data.js. Only the user-run fnl-status writes it (refresh.py run --register-here), never a hook, only when metrics consent is recorded, and a label the user set with label --set wins over it. It is never an event field, never leaves the machine, and purge removes both files. No path, no folder list and no other name is kept.
• The plugin's own data and config live under the data root, ~/.finolabs/vibecode/ by default, which only fnl-setup changes (see README.md); a skill never hard-codes another location.

Reviews

Pull requests follow fnl-review-gate "Pull requests"; reviewers may post their review comments on them. Pull requests may take the low-risk lane of fnl-review-gate.

Standing relay (owner, 02/11/2026): when one model family wrote a pull request, a code review by another model family that cannot post may be posted unchanged by the coordinator, with a second line naming the reviewer, who relayed it and this record. Security reviews and every other relay still need the owner's approval per pull request.

Versions

.claude-plugin/plugin.json is the single source of truth for the version; .codex-plugin/plugin.json and .antigravity-plugin/plugin.json must match it. Follow skills/fnl-versioning/SKILL.md for bumps, the changelog and tags. Record every change to the public surface under Unreleased in CHANGELOG.md.

Checks before committing

• claude plugin validate . passes.
• A changed description gets a trigger check: a representative prompt fires the skill, and an unrelated prompt does not.
• skills/fnl-open-source-review/SKILL.md stays green for this repository.
• python3 -m unittest discover -s tests passes, and python3 scripts/check-references.py . passes.

Commits

Follow skills/fnl-commit-messages/SKILL.md: atomic commits, imperative subject lines, no secrets, env files or generated output.