docs(skills): add language-specific research guides and reference docs

Go, Rust, and Python lang docs with research tables, quick-check
commands, install patterns, schema fields, and common issues.
Includes checklists, FAQ, testing patterns, and Brewfile.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: aRustyDev

context/skills/pkgmgr-homebrew-formula-dev/reference/Brewfile

@@ -0,0 +1,3 @@
+# bash
+# jq
+# yq

context/skills/pkgmgr-homebrew-formula-dev/reference/checklists/local-validation.md

@@ -0,0 +1,48 @@
+## Local Validation
+
+### Step 1: Sync to Tap Location
+
+Formula files must be in the Homebrew tap location for testing:
+
+```bash
+mkdir -p /opt/homebrew/Library/Taps/arustydev/homebrew-tap/Formula/<letter>/
+cp Formula/<letter>/<name>.rb /opt/homebrew/Library/Taps/arustydev/homebrew-tap/Formula/<letter>/
+```
+
+**Note:** On Apple Silicon Macs the prefix is `/opt/homebrew`, on Intel Macs it's `/usr/local`. Check with `brew --prefix`.
+
+### Step 2: Run Audit
+
+```bash
+brew audit --new --formula arustydev/tap/<name>
+```
+
+This checks for common formula issues but NOT style violations.
+
+### Step 3: Run CI Syntax Check (Critical)
+
+```bash
+brew style arustydev/tap
+```
+
+This runs rubocop against ALL files in the tap — same as CI. This catches issues that `brew audit` misses.
+
+### Step 4: Test Installation
+
+```bash
+brew install --build-from-source arustydev/tap/<name>
+# For HEAD-only:
+brew install --HEAD arustydev/tap/<name>
+```
+
+### Step 5: Run Formula Tests
+
+```bash
+brew test arustydev/tap/<name>
+```
+
+### Step 6: Verify Binary
+
+```bash
+<name> --help
+```

context/skills/pkgmgr-homebrew-formula-dev/reference/faq/common.md

@@ -0,0 +1,25 @@
+## Common Issues
+
+### CI Failures from Rubocop
+
+**Problem:** `brew style` fails on markdown files containing Ruby code blocks.
+
+**Cause:** `brew style` uses rubocop-md which lints code fenced as `ruby` in markdown files. The tap's `.rubocop.yml` exclusions do NOT apply — `brew style` uses Homebrew's central config.
+
+**Solution:** Use `text` instead of `ruby` for code fence language in any markdown documentation.
+
+### Line Length Errors
+
+**Problem:** Lines longer than 118 characters.
+
+**Solution:** Split long strings or use Homebrew's allowed patterns (URLs, sha256 lines, etc. are exempt).
+
+### Test Block Failures
+
+**Problem:** Formula installs but `brew test` fails.
+
+**Solution:** Check if the binary exits non-zero on `--help` and use `shell_output("...", exit_code)`. Ensure test creates necessary files and uses `testpath`.
+
+### Typed/Frozen String Headers
+
+The `# typed: strict` and `# frozen_string_literal: true` headers are **optional** for tap formulas. They are not enforced by `brew style` and many tap formulas omit them. Include them for consistency if the tap already uses them, otherwise omit.

context/skills/pkgmgr-homebrew-formula-dev/reference/langs/go.md

@@ -0,0 +1,69 @@
+## Go Formula Patterns
+
+### Researching a Go Project
+
+| What | Where to Look | Command / File |
+|------|---------------|----------------|
+| Build system confirmation | Repo root | Look for `go.mod` — confirms it's a Go module |
+| Binary name(s) | `cmd/` directory or repo root | `ls cmd/` — each subdirectory is typically a binary |
+| Main package location | `cmd/<name>/main.go` or `main.go` at root | If root: no path arg needed; if `cmd/`: use `"./cmd/<name>"` |
+| Version injection | `main.go` or `internal/version` | `grep -r 'version' main.go` — look for `var version` to set via `-X` ldflags |
+| CGO usage | Source files | `grep -r 'import "C"'` or `grep -r '#cgo'` — if found, need system library deps |
+| Build tags | Source files, CI config | `grep -r '//go:build'` or check CI for `-tags` flags |
+| Runtime dependencies | Import statements, docs | `grep -r 'os/exec'` for external tool calls; check README for runtime requirements |
+| Completions | CLI framework used | If using cobra: look for `GenBashCompletion`; if using urfave/cli: check for `EnableBashCompletion` |
+| Test command | README, `--help` output | Most Go CLIs support `--help` or `--version`; check if exit code is 0 |
+
+**Quick check sequence:**
+
+```bash
+# Confirm Go project and find binaries
+gh api repos/OWNER/REPO/contents/go.mod --jq '.name' 2>/dev/null && echo "Go project"
+gh api repos/OWNER/REPO/contents/cmd --jq '.[].name' 2>/dev/null || echo "main.go at root"
+
+# Check for version variable
+gh api repos/OWNER/REPO/contents/main.go --jq '.content' | base64 -d | grep -i 'version'
+```
+
+### Dependencies
+
+```text
+depends_on "go" => :build
+```
+
+### Install Block
+
+```text
+def install
+  system "go", "build", *std_go_args(ldflags: "-s -w -X main.version=#{version}"), "./cmd/binary"
+end
+```
+
+- If `main.go` is at repo root: omit the path argument
+- If `main.go` is at `./cmd/<name>/`: include `"./cmd/<name>"`
+- `-s -w` strips debug info for smaller binary
+- `-X main.version=#{version}` injects version at build time
+
+### JSON Schema Fields (`install-go`)
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `ldflags` | `"-s -w -X main.version=#{version}"` | Linker flags |
+| `cmd_path` | `"./cmd/..."` | Go package path to build |
+| `output` | formula name | Output binary name |
+| `tags` | — | Go build tags (e.g. `["netgo", "osusergo"]`) |
+| `env` | — | Environment variables (e.g. `{"CGO_ENABLED": "0"}`) |
+
+### Mustache Partial
+
+The `langs/go.mustache` partial renders `std_go_args(ldflags:)` with optional `cmd_path`.
+
+### Common Issues
+
+- **Binary name differs from formula name:** Check for `cmd/` subdirectories — the directory name is usually the binary name
+- **CGO dependencies:** If the project uses CGO, add system library deps and ensure `CGO_ENABLED` is not set to `0`
+- **Multiple binaries:** Use `cmd_path: "./cmd/..."` to build all, or specify individual paths
+
+### Reference
+
+See `reference/templates/formulas/go.rb` for a pipeline-generated example.

context/skills/pkgmgr-homebrew-formula-dev/reference/langs/python.md

@@ -0,0 +1,97 @@
+## Python Formula Patterns
+
+### Researching a Python Project
+
+| What | Where to Look | Command / File |
+|------|---------------|----------------|
+| Build system | Repo root | `pyproject.toml` (modern), `setup.py`/`setup.cfg` (legacy) |
+| Binary name(s) | `pyproject.toml` `[project.scripts]` or `setup.py` `entry_points` | The key is the binary name, the value is the module path |
+| Python version | `pyproject.toml` `requires-python` | Map to Homebrew's `python@3.XX` — use latest compatible |
+| Direct dependencies | `pyproject.toml` `[project.dependencies]` or `requirements.txt` | Each becomes a `resource` block unless already in homebrew-core |
+| Resource URLs | PyPI | `https://pypi.org/project/<pkg>/#files` — use the `.tar.gz` sdist, not wheel |
+| Completions | CLI framework | If using `click`: look for `shell_complete`; if using `argparse`: check for custom completion |
+| Native extensions | `setup.py` or `pyproject.toml` build-backend | If using `setuptools` with C extensions: needs compiler deps |
+| Test command | README, `--help` output | Check if tool supports `--version` or `--help` |
+
+**Quick check sequence:**
+
+```bash
+# Confirm Python project, find entry points
+gh api repos/OWNER/REPO/contents/pyproject.toml --jq '.content' | base64 -d | grep -A10 '\[project.scripts\]'
+
+# Find Python version requirement
+gh api repos/OWNER/REPO/contents/pyproject.toml --jq '.content' | base64 -d | grep 'requires-python'
+
+# List dependencies
+gh api repos/OWNER/REPO/contents/pyproject.toml --jq '.content' | base64 -d | grep -A30 '\[project\]' | grep -A20 'dependencies'
+```
+
+**Generating resource blocks:** After initial formula creation, use `brew update-python-resources <formula>` to auto-generate resource blocks from PyPI.
+
+### Dependencies
+
+```text
+depends_on "python@3.12"
+```
+
+### Install Block
+
+```text
+include Language::Python::Virtualenv
+
+def install
+  virtualenv_install_with_resources
+end
+```
+
+- `virtualenv_install_with_resources` creates a venv, installs resource blocks, then installs the formula
+- Check `pyproject.toml`, `setup.py`, or `setup.cfg` for the project's build system
+
+### JSON Schema Fields (`install-python`)
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `python_version` | `"python3"` | Python version dependency |
+| `using` | `"virtualenv"` | Install method (`virtualenv`, `pip`, `setuptools`) |
+| `site_packages` | `false` | Allow access to system site-packages |
+| `resources` | — | Python package dependencies (defined at formula level) |
+
+### Mustache Partial
+
+The `langs/python.mustache` partial renders `virtualenv_install_with_resources`.
+
+### Resource Blocks
+
+Python formulas need `resource` blocks for pip dependencies not in homebrew-core:
+
+```text
+resource "certifi" do
+  url "https://files.pythonhosted.org/packages/certifi-2024.2.2.tar.gz"
+  sha256 "..."
+end
+```
+
+Generate resource blocks with:
+
+```bash
+brew update-python-resources <formula-name>
+```
+
+### Entry Points
+
+Check `pyproject.toml` `[project.scripts]` for the binary names the formula will install:
+
+```toml
+[project.scripts]
+my-tool = "my_package.cli:main"
+```
+
+### Common Issues
+
+- **Missing resources:** Python dependencies must be declared as `resource` blocks — they're not auto-resolved
+- **Version pinning:** Use the exact source tarball versions that match the project's requirements
+- **Site packages:** Set `site_packages: true` only when the formula needs access to Homebrew-installed Python packages
+
+### Reference
+
+See `reference/templates/formulas/python.rb` for a pipeline-generated example.

context/skills/pkgmgr-homebrew-formula-dev/reference/langs/rust.md

@@ -0,0 +1,88 @@
+## Rust Formula Patterns
+
+### Researching a Rust Project
+
+| What | Where to Look | Command / File |
+|------|---------------|----------------|
+| Build system confirmation | Repo root | Look for `Cargo.toml` — confirms it's a Rust/Cargo project |
+| Binary name(s) | `Cargo.toml` `[[bin]]` section | May differ from repo name (e.g. `jwt-ui` installs `jui`) |
+| Workspace layout | `Cargo.toml` `[workspace]` | If workspace: find the CLI crate in `members` list, use its path |
+| Features | `Cargo.toml` `[features]` | Check for `default`, optional features like `tls`, `jemalloc` |
+| System dependencies | `build.rs`, CI config | `grep -r 'pkg-config\|system-deps\|cc::Build'` — indicates C library deps |
+| OpenSSL / TLS usage | `Cargo.toml` deps | `grep -i 'openssl\|native-tls\|rustls'` — may need `openssl@3` dep |
+| uses_from_macos | Linked system libs | If uses `zlib`, `libxml2`, `curl` etc. via `-sys` crates |
+| Completions | CLI framework | If using `clap`: look for `clap_complete` in deps; check for `completions` subcommand |
+| Minimum Rust version | `Cargo.toml` `rust-version` or `rust-toolchain.toml` | Homebrew provides latest stable — flag if MSRV is unusual |
+| Test command | README, `--help` output | Most Rust CLIs support `--help` or `--version` |
+
+**Quick check sequence:**
+
+```bash
+# Confirm Rust project, find binary names and features
+gh api repos/OWNER/REPO/contents/Cargo.toml --jq '.content' | base64 -d | grep -A5 '\[\[bin\]\]'
+gh api repos/OWNER/REPO/contents/Cargo.toml --jq '.content' | base64 -d | grep -A20 '\[features\]'
+
+# Check for system deps
+gh api repos/OWNER/REPO/contents/build.rs --jq '.name' 2>/dev/null && echo "Has build.rs — check for C deps"
+```
+
+### Dependencies
+
+```text
+depends_on "rust" => :build
+```
+
+### Install Block
+
+```text
+def install
+  system "cargo", "install", *std_cargo_args
+end
+```
+
+- `std_cargo_args` handles `--root`, `--path`, and `--locked`
+- Check `Cargo.toml` `[[bin]]` — binary name may differ from formula name (e.g. `jwt-ui` installs `jui`)
+
+### JSON Schema Fields (`install-rust`)
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `path` | `"."` | Path to Cargo.toml directory |
+| `features` | — | Cargo features to enable |
+| `all_features` | `false` | Enable all Cargo features |
+| `no_default_features` | `false` | Disable default features |
+| `bins` | — | Specific binaries to install |
+
+### Mustache Partial
+
+The `langs/rust.mustache` partial renders `std_cargo_args` with optional `path` and `features`.
+
+### Feature Selection
+
+When a crate has optional features:
+
+```text
+system "cargo", "install", *std_cargo_args, "--features", "tls,jemalloc"
+```
+
+### Monorepo / Workspace Builds
+
+When building from a subdirectory of a workspace:
+
+```text
+def install
+  cd "crates/cli" do
+    system "cargo", "install", *std_cargo_args
+  end
+end
+```
+
+### Common Issues
+
+- **Lock file version mismatch:** Ensure the Rust toolchain version matches the project's `Cargo.lock`
+- **Vendored dependencies:** Some projects vendor C libraries — check for `build.rs` and add system deps
+- **uses_from_macos:** Rust projects using `openssl` often need `uses_from_macos "zlib"`
+
+### Reference
+
+See `reference/templates/formulas/rust.rb` for a pipeline-generated example.

context/skills/pkgmgr-homebrew-formula-dev/reference/templates/ISSUE_TEMPLATE.md

@@ -0,0 +1,37 @@
+## Test Block Patterns
+
+### Simple help check
+
+```text
+test do
+  assert_match "tool-name", shell_output("#{bin}/tool --help")
+end
+```
+
+### Non-zero exit on help
+
+Some tools exit non-zero when showing help. Pass the expected exit code:
+
+```text
+test do
+  assert_match "tool-name", shell_output("#{bin}/tool --help", 2)
+end
+```
+
+### Version check
+
+```text
+test do
+  assert_match version.to_s, shell_output("#{bin}/tool --version")
+end
+```
+
+### Functional test with file I/O
+
+```text
+test do
+  (testpath/"input.txt").write("test content")
+  output = shell_output("#{bin}/tool #{testpath}/input.txt")
+  assert_equal "expected", output.strip
+end
+```