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 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/<name>/SKILL.md; the folder name equals the name field, and the name carries no prefix, so it stays short and easy to remember (owner decision, 11/11/2026, replacing the rule of 01/11/2026 that every name starts with fnl-; on Claude Code the plugin namespace /finolabs-vibecode:<name> avoids collisions). Each skill keeps its older name as a thin, user-only alias in skills/fnl-<name>/SKILL.md that only loads <name> with the same arguments; an alias folder holds nothing else. Skills refer to each other by their current 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 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 scoped exceptions that say they may deny: the auto gate, the compaction stop, the heavy-job gate and the away question gate.
• 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 scoped exceptions that say they may deny blocks, and no code for the auto 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 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 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 hook outside the scoped exceptions that say they may deny 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 and the context probe below run 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 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 setup (Judge: jev with its own valid Consent: yes (<date>) line in the ## Assignment matrix section of the canonical host config under the data root, read only from that file, design in docs/specs/assignment-matrix.md; if the data root cannot be resolved or its pointer is invalid, the call is off; an absent, invalid or unconsented matrix, or Judge: host, means no call; the older ## Agent roles section is never read and its consent is never inherited (owner decision, 13/11/2026: legacy ## Agent roles retired)) 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, an away evaluation among closed options: the probability of each option, given to the deciders as data and never settling the choice alone, owner decision 14/11/2026, design in docs/specs/afk-per-project.md), 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 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 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 setup changes (see README.md); a skill never hard-codes another location.
• Fifth scoped exception, the third that may deny (owner decision, 08/11/2026; design in docs/specs/heavy-jobs.md part D): the opt-in heavy-job gate on Claude Code. It is off unless the user turned it on in setup with a consent question of its own and a shown preview, recorded as Heavy-job gate: on in ## Heavy jobs of the canonical host config under the data root; if that cannot be resolved it is off. It is one PreToolUse hook for the Bash tool in its own group, never in the metrics group, installed and removed by a script that offers a dry run and keeps a backup. It may deny one Bash call only when the command is listed as heavy in that section (or in the built-in default list) and is not wrapped in the plugin's heavy_run.py launch form, whose grammar (interpreter and path forms, an optional outer run_env.py --, and the options between run and --) the spec defines and the gate follows, and the denial carries one fixed message that names heavy_run.py. It never denies any other tool, a prompt, a session start or the user's own stop, never edits or runs the command, and never stores, logs or sends the command text: it matches it in memory and exits. It reads only the canonical host config and allows on every error, on a missing or unreadable config, and on any command it cannot classify with certainty. FNL_HEAVY_GATE=off disables it and --remove takes it out. It does not cover Codex, Antigravity or a Bash call that reaches the same work through another tool. It sends nothing anywhere. No code for it lands before this rule is merged.
• Sixth scoped exception, the fourth that may deny (owner decision, 09/11/2026; design in docs/specs/away-decisions.md): the away question gate on Claude Code. It is one PreToolUse hook for the AskUserQuestion tool in its own group. It may deny that one call, with one fixed message that points to the away decision procedure, only while a valid, unexpired away lease exists under the canonical data root; starting the lease is the user's opt-in. It allows when there is no lease and on an expired, stopped or unreadable lease and on every error. It never reads the question, denies no other tool, prompt, session start or the user's own stop, and sends nothing anywhere. It appends one ledger line holding only the time and the lease's start time. FNL_AWAY_GATE=off disables it. It does not cover Codex or Antigravity. No code for it lands before this rule is merged.
• Seventh scoped exception (owner decision, 11/11/2026; design in docs/specs/context-probe.md): the context probe. context_snapshot.py probe reads the current session's context size by running the user's own program once per call, only when the coordinator or the user runs it, never from a hook, a timer or a worker. Claude Code: the fixed argv claude -p /context --resume <session id> --fork-session --no-session-persistence --output-format json, which runs no model turn. Codex: codex app-server with fixed payloads in this order and nothing else: initialize with a constant client name and version, initialized, thread/read and thread/goal/get for the session's own thread, and only when that thread is idle or not loaded and has no goal, thread/resume with the thread id as its only parameter (no model, configuration, instructions, path or history override); it takes the first inbound thread/tokenUsage/updated for that thread, discards all other output, answers no server request and sends no turn; any other state or an unknown answer stops before resume. The session id comes from the session-start hook, which prints one validated Session id: line, so the id enters the host's model context, which the host may keep. Execution follows the quota probe's rules (an owner-checked absolute executable confirmed at setup, no shell, an allowlisted environment, a neutral working folder, a 30-second limit with the process group killed, a 64 KiB output cap). MCP servers the user configured for that program may start and stop with it. The probe writes the existing context snapshot fields (used and window tokens, whole percent, time, short sanitized version, host) under a hashed session id, never the breakdown, the raw id or any content. The programs contact their providers with the user's own account; the plugin sends nothing. Antigravity is not covered. FNL_CONTEXT_PROBE=off stops it. No code for it lands before this rule is merged.
• Eighth scoped exception (owner decision, 12/11/2026; design in docs/specs/compaction-nudge.md): the compaction nudge on Claude Code. It is one UserPromptSubmit hook in its own group, never in the metrics group, on by default and off with FNL_COMPACT_NUDGE=off. It reads the session's transcript only to find the token counts of the latest assistant entry: it opens the regular file named by the hook's transcript_path only when it is not a symlink and lies inside the host's projects folder of the running config directory, reads at most the last 256 KiB, parses each line as JSON and keeps only the integer usage fields (input, cache creation, cache read and output tokens); it never reads, keeps, logs or sends any other field or any content. It reads the effective compaction threshold from the user's, project's and local Claude Code settings files and the managed settings when readable, taking only autoCompactEnabled and autoCompactWindow, and from the environment only the presence and integer value of CLAUDE_CODE_AUTO_COMPACT_WINDOW, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE and DISABLE_AUTO_COMPACT; when auto-compaction is off or no threshold can be resolved it prints nothing. When the used tokens reach 80% of the threshold it prints one fixed line with a whole percent asking the agent to run tidy before the host compacts (handover, write back decisions and lessons, state of runs and pull requests, then offer compaction); it prints again only after a 90% band or after a compaction resets the count. The band mark is an integer written atomically in the data root's private state folder under a hash of the session id, holding no content; if the mark cannot be written, or any check fails, it prints nothing. It never blocks or denies a prompt, a tool, a session start or a stop, always exits 0, records no metrics event and sends nothing anywhere. On Codex (owner decision, 15/11/2026; design in the same spec, section "Codex") the same nudge is one UserPromptSubmit hook in its own group of the Codex manifest, never in the metrics group, with the same bands, message, mark, failure rule and off switch; Codex adds plain stdout to the model's context as developer text. It opens the regular file named by the hook's transcript_path only when it is not a symlink and lies inside the sessions folder of the Codex home (CODEX_HOME, else ~/.codex), reads at most the last 256 KiB, parses each line as JSON and keeps only the integers last_token_usage.total_tokens and model_context_window of the latest token_count event; it never reads, keeps, logs or sends any other field or any content. Its threshold is the top-level integer model_auto_compact_token_limit of the Codex home's config.toml, the only key it takes from that file, capped at 90% of the context window, else 90% of the context window (Codex's default, unverified on each version); a profile's value is not read. It does not cover Antigravity (Antigravity keeps the compaction stop). PRIVACY.md (section "Compaction nudge") and the spec carry this text from the pull request that records this rule. No code for it lands before this rule is merged.

Reviews

Pull requests follow review-gate "Pull requests"; reviewers may post their review comments on them. Pull requests may take the low-risk lane of review-gate. The lane covers changelog and root-document edits, manifest version bumps (the three plugin manifests' top-level "version", such as the post-release bump to the next -dev version) and, by owner decision of 15/11/2026, a post-release record: the one Status: line of a docs/specs/release-X.Y.Z.md record changed from its prepared form to released; tagged vX.Y.Z on YYYY-MM-DD; ..., with only that release's row in docs/specs/index.md changed the same way; any other docs change stays outside the lane (enforcer: merge_check.py --lane).

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. While an away lease with Merge yes is live, the same standing relay covers a security review by another model family (owner, 15/11/2026: the lease's Merge answer already delegates reviews and merges). In every other case, including a lease with Merge no, 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/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/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/commit-messages/SKILL.md: atomic commits, imperative subject lines, no secrets, env files or generated output.

Agent skills

This repository uses the finolabs-vibecode skills. Routing on: use coding-router. Pull requests follow review-gate "Pull requests"; reviewers may post code/security reviews. Pull requests may take the low-risk lane of review-gate. Help: /finolabs-vibecode:help (Codex $help).