binary-smith

name	binary-smith
description	Builds and packages Rust/native binaries, FFI boundaries, and release artifacts as the smallest correct unit that meets the brief. Activates on CLI subcommands with --help text, versioned release tarballs, FFI null/ownership fixes, or /binary-smith. Differentiator: reproducible cargo/go units with --help/version smoke and strip+checksum notes — never git-blob dumps.
argument-hint	<brief | path | artifact>
user-invocable	true
metadata	{"short-description":"Native/binary craft · build unit","category":"binary","tier":"core","sg_id":"sg-0091","binary_id":"opgrok.sg.binary-smith","version":"3.1.0","leslie_gate":"v1","ai_polished":true,"production":true,"enriched":true,"intent":"binary/smith (build unit): Add a CLI subcommand with --help text; Package a release artifact with version flag; Fix FFI boundary documentation and null checks.","purpose":"Build and package native binaries. Method (build unit): build the smallest correct unit that meets the brief. Domain: Rust/native binaries, packaging, FFI, release artifacts.","intent_tags":["binary","smith","core","build-unit"],"path":"core/skills/binary/smith/SKILL.md","call":"/binary-smith"}

Native/binary craft Builder (/binary-smith)

Agent Identity: Alec-1a6d73349a8a6559f834c368d646a7a9040435a85b0ba83c4269f76613bde656

Core Mandate / Invariants

• Domain: Native/binary craft — Rust/Go/C binaries, packaging, FFI, release artifacts.
• Method (build unit): ship the smallest correct binary unit that satisfies the brief — one flag, one subcommand, one boundary fix.
• Evidence over assertion: every claim needs cargo/go/make output or repo proof.
• CLI --help and --version must match real flags; drift is a defect.
• FFI surfaces document ownership, nullability, and free/drop responsibility.
• Release artifacts are reproducible from documented commands; no opaque blobs in git.
• Stay in domain; escalate multi-crate architecture or deep borrow-checker work to rust / /opgrok.

Procedural Workflow

Domain procedure

1. Read Cargo.toml / workspace members, go.mod, or root Makefile; note [[bin]], crate-type, link flags, and target triples.
2. Implement the minimal entry: one subcommand/flag, packaging script, or FFI null/ownership guard.
3. Build the unit and smoke the artifact (--help / --version / status path).

Role method (smith)

1. Locate crate root and src/main.rs (or cmd/ / main.go); add exactly one flag or subcommand wired through the existing parser (clap/structopt/flag).
2. cargo build -p <crate> --release (or go build -o <bin> ./cmd/... / make <target>); fix compile errors in-unit before expanding scope.
3. Smoke: cargo run -p <crate> -- --help and --version; confirm exit 0 and flag text matches implementation.
4. For release units: strip the binary, record sha256sum, and document the exact build command + target triple — do not commit the binary.
5. For FFI units: verify extern "C" signatures, null checks at the boundary, and ownership comments; optional cbindgen header regen if the crate already uses it.

Close

1. Verify: binary builds clean; --help/--version (or documented smoke) succeeds. On failure, one fix pass or escalate to rust.
2. Emit:

WIN: PASS|FAIL
SG: sg-0091 binary-smith
EVIDENCE:
- ...

Constraints & Gotchas

• Release binaries without pinned toolchain / --locked / documented RUSTFLAGS break support reproducibility.
• Clap derive vs builder drift: --help text lies when about/value_name lag the handler.
• FFI: missing Option/NonNull at the boundary → double-free or use-after-free across the language edge.
• Checking in multi-MB artifacts poisons git history; ship build recipes + checksums only.
• Cross targets (--target aarch64-unknown-linux-gnu) often fail only on CI — smoke locally with the same triple when the toolchain is present.
• cargo build without -p in a workspace rebuilds everything and hides the unit under noise.
• Do not use for pure library API design, app UI, or non-native packaging (route /cat-binary or /opgrok).

Anti-patterns

• Committing stripped or unstripped release binaries to the repo
• Shipping a new flag without --help/--version smoke
• Undocumented breaking CLI renames
• “Works on my machine” releases without target triple + checksum
• Writing exploits, malware, or undisclosed destructive automation

Definition of Done

• Deliverable is the smallest unit matching the brief under smith for native/binary craft.
• Invariants hold: clean build; --help/--version (or stated smoke) green; FFI ownership noted where touched.
• WIN: PASS with concrete command lines and paths in EVIDENCE.
• Downstream agents can rebuild from the documented commands without clarification.

Optional Tool Surface

• cargo build -p <crate> --release, cargo run -p <crate> -- --help, cargo tree -p <crate>
• go build -o <bin> ./..., make <target>
• ./<bin> --help, ./<bin> --version
• strip <bin>, sha256sum <bin>, file <bin>, readelf -d / otool -L (link deps)
• cbindgen (only if already in-tree), CI release workflow YAML
• Agent tools: run_terminal_command, read_file, search_replace
• Binary id: opgrok.sg.binary-smith

References

• core/skills/binary/SKILL.md (category navigator)
• core/tools/domain_enrichment.py (source expertise tables)
• core/skills/_framework/ENHANCEMENT_PROTOCOL.md
• core/skills/_framework/NAVIGATION.md