rubio-standards
Org-wide repository standards for Rubio-Enterprises: Copier template, audit content (deterministic check.sh + JSON Schemas + Rego policies), per-language observability snippets, and the rubio-standards Claude Code plugin.
What it is
This repo is the single source of truth for Rubio-Enterprises repo standards. It ships four kinds of content, each on its own independent tag stream:
| Layer | Paths | Consumer | Tag stream |
|---|
| Audit | scripts/, schemas/, policy/, data/, audit-side .mise.toml | Rubio-Enterprises/.github/.github/workflows/audit.yml (checkout + run against every consumer PR) | audit/v1.X.Y, floating audit/v1 |
| Template | template/, copier.yml | Consumer repos via copier copy / copier update | template/v1.X.Y, floating template/v1 |
| Docs | README.md, MIGRATION.md, RELEASES.md, CLAUDE.md, docs/ | Humans (and the Claude Code plugin, transitively) — no consumer machine reads these at audit/render time | docs/v1.X.Y, floating docs/v1 |
| Plugin | .claude-plugin/, skills/ | Consumer Claude Code sessions — locally via the operator's chezmoi-managed ~/.claude/settings.json, and in cloud via the committed per-repo .claude/settings.json carrier the template renders | plugin/v1.X.Y, floating plugin/v1 |
Legacy bare v1.X.Y tags (v1.0.0 … v1.1.7) are read-only and remain resolvable for old pins — don't cut new tags in that stream.
The companion repo Rubio-Enterprises/.github ships the reusable workflows that consumers call. Rubio-Enterprises/.github-private ships Terraform-in-CI for repo settings + the self-managed Renovate runner.
Install / quickstart
For greenfield repos:
copier copy --vcs-ref=template/v1 gh:Rubio-Enterprises/standards <new-repo-path>
For existing repos (after one initial Copier copy):
copier update --vcs-ref=template/v1
The full migration guide — including the decision framework for "should this repo migrate at all", known gotchas (forks, lockfile-yamllint, new copier questions on update, archetype-specific quirks), and the failing-audit triage recipe — lives in MIGRATION.md. Read that first if you're starting fresh.
Usage
Claude Code plugin
The rubio-standards plugin reaches Claude Code two ways: locally via the operator's chezmoi-managed ~/.claude/settings.json, and — for cloud sessions (Claude Code on the web, which only see committed files) — via a committed per-repo .claude/settings.json carrier the template renders (the rubio marketplace + rubio-standards@rubio entry, kept in sync from the dotfiles SSOT). From a Claude Code session in any consumer repo:
/audit-standards — runs the deterministic baseline + per-rule audit; prints the report as a markdown table directly in the conversation (no on-disk artifact — copy it from chat if you want to keep it)./audit-standards fix — same, plus low-risk auto-remediation on a chore/standards-audit-YYYY-MM-DD branch (draft PR)./onboard-repo — scaffolds a brand-new repo from the Copier template; opens a PR.
The agent NEVER runs in required or scheduled CI (§6.8 of standards-design.md — cost, determinism, and prompt-injection blast radius all push this). Skills are invoked manually by a human in their local Claude Code session.
Maintainer note: skill changes ship through the plugin/ tag stream, but the bit Claude Code actually reads is .claude-plugin/plugin.json::version, and consumers must run /plugin update to pull a new version (auto-update is off by default for third-party marketplaces). See Plugin release flow in RELEASES.md for the full runbook.
Audit layers (what each one catches)
- Layer A —
scripts/check.sh — deterministic file-presence + banned-files + secret-vocabulary + README skeleton.
- Layer B —
schemas/{package-json,pyproject}.schema.json — intra-document conditionals via JSON Schema if/then (script presence, archetype-implies-shape, runner coherence).
- Layer C —
policy/<lang>/*.rego + data/base/* — relational override-policy comparison via Conftest's --combine + --data.
Run all three from a consumer repo via the reusable audit.yml workflow in Rubio-Enterprises/.github, which pins this repo at audit/v1.
Per-repo rule opt-out (.audit-standards-skip)
Layer A (scripts/check.sh) honours a per-repo opt-out file at the consumer repo root. Drop the rule IDs you want to suppress into .audit-standards-skip, one per line; lines starting with # (and trailing # … inline comments) are stripped. The file is checked into the consumer repo so suppressions stay auditable in code review — there is no hidden CI override.
