CLAUDE.md git:20261105.58da892A

Immutable. This exact content never changes and is served at /api/v1/blob/24062160dfa61f5e.

# 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 one exception in the next rule.
- 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 other hook blocks, and no code for the gate lands before this rule is merged.
- The update check is the one network call the plugin itself makes (the quota probe below runs the user's own programs and is the only scoped exception): 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: after a successful reading at most one new reading every 4 hours; a failed run is retried no sooner than 30 minutes later and a reply of an unexpected shape no sooner than 24 hours later. A detached worker, started by the existing hooks, makes each reading; a hook reads the local cache, exits 0 and fails closed, and never waits for the worker.
  - 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.
  - Data: the cache, the single in-flight worker marker (a nonce a hook must match before it exits early) 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, 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, and no code for the probe lands before this rule is merged.
- 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.