Ki Repo Homebrew Tap

Knowledge Islands Homebrew tap standard

You are helping audit, conform, or scaffold the Homebrew tap repo — homebrew-tap under knowledgeislands/, the distribution repo that carries Formula/*.rb so brew install knowledgeislands/tap/<tool> resolves. The tools whose formulae live here are governed by the sibling ki-repo-tools skill; this skill governs the tap and the formulae inside it.

This skill wraps an external standard. Homebrew already defines what a valid tap and formula are (the Formula Cookbook, brew audit, brew style); this skill does not re-invent that. Its hosted audit checks only the tap's static shape—the things a tap needs beyond a single valid formula. brew style and brew audit --strict are explicit, isolated opt-in diagnostics, never hosted-audit execution. A static finding is source-shape evidence, not package-manager validation. Never present a shape preference as a Homebrew "MUST"; when unsure which a rule is, run Mode REFRESH against the Cookbook.

The full, quotable standard lives in Homebrew tap standard; the line-by-line pass/fail items in Audit Rubric. ki repo audit and ki repo conform execute the mechanical contract. Read those when you need detail; this file is the operating procedure.

The canonical shape at a glance

homebrew-tap/            # named homebrew-<x> — Homebrew requires the prefix for `brew tap <owner>/<x>`
├── Formula/
│   ├── mgit.rb          # one formula per tool, filename = formula name
│   └── <tool>.rb
├── README.md            # Standard Readme shape; a "## Formulae" table lists every formula + its source repo
├── .github/workflows/   # OPTIONAL brew test-bot CI (brew audit/style/install on PR)
└── .ki.toml      # [skills.ki-repo] + [skills.ki-repo-homebrew-tap] (keyless opt-in marker)

A single formula (Formula/mgit.rb) is a Ruby class Homebrew evaluates:

class Mgit < Formula
  desc "Run a git command across many repositories at once"  # ≤ 80 chars, no leading A/An/The
  homepage "https://github.com/knowledgeislands/tools-mgit"
  url "https://github.com/knowledgeislands/tools-mgit/archive/refs/tags/v0.1.0.tar.gz"  # versioned tarball
  sha256 "092a6df6…"                                          # of that tarball
  license "MIT"

  def install
    bin.install "bin/mgit"
  end

  test do
    assert_match "mgit #{version}", shell_output("#{bin}/mgit --version")
  end
end

Three rules define a well-formed tap — most findings are a violation of one:

1. The tap is Formula/*.rb, one formula per tool. The directory Formula/ with at least one .rb is what makes a repo a tap; the filename is the formula name (Formula/mgit.rb → brew install …/mgit). No Formula/ is a hard FAIL — it is not a tap.
2. A formula sources a versioned release, never HEAD. url points at a tagged-release tarball (/archive/refs/tags/vX.Y.Z.tar.gz or /releases/download/…) with its matching sha256. Installing from a branch is unreproducible; that is a finding, not the shape.
3. The formula has the seven required parts. class <Camel> < Formula, desc, homepage, url, sha256, license, a def install, and a test do that exercises the installed binary. brew audit/brew style enforce the finer rules on top (this skill runs them when brew is present).

The name is fixed by Homebrew

Unlike the other repo-structure skills, this skill does not govern the repo name. Homebrew requires a tap repo to be named homebrew-<x> so that brew tap <owner>/<x> and brew install <owner>/<x>/<formula> resolve to it (knowledgeislands/tap → the homebrew-tap repo). The skill governs shape, not name — treat the homebrew- prefix as an external constraint, not something to conform.

Operating modes

Every governance skill carries the universal four AUDIT · CONFORM · EDUCATE · REFRESH; EDUCATE here scaffolds a new tap. Invoked as help / -h / ?, it explains itself and stops — the generated HELP block (name, purpose, invocation, modes, off-ramps), taking no action. With no mode it does the same, then, in an interactive session only, offers the mode choice via AskUserQuestion, prompting for any argument-hint target the chosen mode shows.

The four procedures remain on demand because each coordinates work outside the hosted rubric: AUDIT and CONFORM sequence the repository layer and judgment review, EDUCATE scaffolds a new repository, and REFRESH reconciles a moving external specification. Each file owns one mode so invoking one never loads an unrelated procedure.

Mode AUDIT

→ Read references/mode-audit.md

Mode CONFORM

→ Read references/mode-conform.md

Mode EDUCATE

→ Read references/mode-educate.md

Mode REFRESH

→ Read references/mode-refresh.md

Coverage — what this skill rides and what it defers

This skill rides ki-repo (the tap is first a git repo: README, LICENSE, .gitignore, GitHub settings, security—all ki-repo's) through explicit audit and conform sequencing. It does not ride ki-engineering: a tap has no package.json/TypeScript toolchain, so a bare [skills.ki-repo] + [skills.ki-repo-homebrew-tap] config is complete (the ki-repo-plugins precedent). As recorded by the repo-structure decision, that separate repository coverage is not a catalogue dependency, so frontmatter remains ki-depends-on: [].

• The tools whose formulae live here — the tools-* CLI repos, their bin/<exe>, installer, versioning, and releases — are ki-repo-tools'. This skill checks that a formula exists and is well-formed; whether the tool it installs is a conformant tools-* repo is ki-repo-tools' audit.
• A tap repo's GitHub configuration and standard files (merge policy, topics, secret scanning, README/LICENSE presence) are ki-repo's. This skill checks the tap-specific delta on top.

Notes

• The standard sits on top of a moving external spec (Homebrew's Formula Cookbook, brew audit, brew style/rubocop). When citing a formula requirement, know whether it is spec-driven (traces to a Homebrew source in the source list) or house shape—never present a tap-shape preference as a Homebrew "MUST". Run Mode REFRESH when in doubt.
• TAP-7 never runs Homebrew from hosted audit. Obtain brew style, brew audit --strict, and brew test-bot evidence through an explicitly authorized isolated diagnostic; unavailable package-manager evidence is not a structural PASS.
• Marker [skills.ki-repo-homebrew-tap] is a keyless opt-in table, validate-down (like [skills.ki-repo-mcp]): its presence is the whole config; any key under it is unknown and WARNed.
• The tap README follows Standard Readme — Install and Usage carrying the brew install command, Contributing routing packaging bugs here and tool bugs upstream, and the ## Formulae table as the tap's extra section. That shape is advisory: only the table is mechanical (TAP-6), generic README composition is ki-authoring's, and README presence is ki-repo's.
• No exemplars.md is bundled: the compact complete formula above and the README table in the standard already illustrate the only reusable output shapes, so a separate exemplar would duplicate them.