\n A host-neutral SDLC toolkit for coding agents. \n Free, MIT, no account, no server, no telemetry.\n
\n\n
\n \n \n \n \n \n
\n\n---\n\nCoding agents are good at writing code and bad at remembering how *your* team ships it. Bravros\nsupplies the missing half: a set of **35 workflow skills** that give the agent a repeatable\nlifecycle, and a small **Go kernel** for the handful of operations a prompt must never be trusted\nto improvise — atomic locks, human-presence gates, and preserve-before-delete.\n\nSkills are authored in this public repository and ship **embedded in the binary**, so installing\nis one signed download and refreshing them needs no network at all. There is no dashboard, no\nlicence check, and nothing to log into.\n\n---\n\n## ⚡ Install\n\nThe binary carries the skills and templates **inside it**. One download, no clone, no GitHub\ntoken, no account — and every byte is minisign-verified before it lands. See\n[Verify the trust chain](#-verify-the-trust-chain).\n\n### macOS and Linux\n\n```bash\nbash -c \"$(curl -fsSL https://install.bravros.dev)\"\n```\n\nThe installer downloads and verifies the binary, puts it in `~/.claude/bin`, adds that directory\nto your `PATH`, writes an uninstaller next to it, and then hands off to `bravros setup` — the\ncomponent wizard, which is where every question is asked.\n\nThe older piped form still works and still reaches the wizard:\n\n```bash\ncurl -fsSL https://install.bravros.dev | sh\n```\n\nBoth are supported on purpose. Under `curl … | sh` the pipe *is* stdin, so nothing in the script\ncould ever prompt; `bash -c \"$(…)\"` uses command substitution, which leaves stdin attached to\nyour terminal. The advertised form is therefore `bash -c \"$(…)\"`, and the script additionally\nruns its own body with `/dev/tty` bound as stdin when stdin is not a terminal, so the bookmarked\npipe keeps working. On a CI runner with no controllable terminal both forms fall through non-interactively,\ninstall the binary, and print the command to finish setup by hand.\n\nOr with Homebrew:\n\n```bash\nbrew install bravros/tap/bravros\n```\n\nA Homebrew-managed install is detected: the script **aborts instead of shadowing it**, because\ntwo `bravros` binaries on `PATH` means `brew upgrade` moves one and the installer moves the\nother, and which one runs depends on `PATH` order you never see.\n\n### Windows — WSL is the recommended path\n\nInstall [WSL](https://learn.microsoft.com/windows/wsl/install), then run the Linux one-liner\nabove inside it. WSL is a first-class tier; native Windows is not.\n\n\nNative Windows (supported, but a documented degraded tier)\n\n```powershell\nirm https://install.bravros.dev/install.ps1 | iex\n```\n\n> **Prerequisite / known issue.** This one-liner depends on `install.bravros.dev` routing\n> `/install.ps1` to the release asset. That route is an outstanding infrastructure task and is\n> **not confirmed working** — if it 404s, download `install.ps1` from the\n> [latest release](https://github.com/bravros/bravros/releases/latest) and run it locally. The\n> asset itself ships correctly on every release and is covered by `checksums.txt`.\n\n`install.ps1` is a near line-by-line mirror of `install.sh` — same trust chain, same install\nlayout (`%USERPROFILE%\\.claude\\bin`, mirroring the POSIX `~/.claude/bin`), same hand-off to\n`bravros setup`. It targets PowerShell 5.1, which ships in the box. A scoop- or winget-managed\ninstall is detected and refused rather than shadowed, exactly like Homebrew on POSIX.\n\nWhat is specifically worse than the POSIX path — the three known items, not a vague warning:\n\n1. **The SessionStart hook has no desktop-app guard.** On macOS and Linux the hook is\n `sh -c 'case \"$__CFBundleIdentifier\" in com.anthropic.*) exit 0;; esac; exec $HOME/.claude/bin/bravros …'`\n so it is a no-op inside the Claude desktop app. `cmd.exe` cannot parse a shell `case`, and the\n `__CFBundleIdentifier` condition is macOS-only, so the Windows hook is the bare command\n `%USERPROFILE%\\.claude\\bin\\bravros.exe …` with no guard\n (`cli/internal/managed/settings_windows.go`).\n2. **`bravros update` leaves a `.old-*` file behind, and has a crash window POSIX does not.** On\n POSIX, `rename(2)` atomically replaces the running executable and the process keeps its\n unlinked inode — there is never an instant with no binary on disk. Windows locks a running\n image against replacement, so the update must rename the current binary aside first, install\n over the freed name, and then fail to delete the sideline (a running image cannot delete its\n own file). The leftover `bravros.exe.old-` is swept on a later run, and a crash between\n the two renames is a real, if narrow, window (`cli/internal/selfupdate/binary.go`).\n3. **minisign is bootstrapped by download.** POSIX gets minisign from your package manager. On\n Windows the installer fetches a **pinned** `minisign.exe` from jedisct1's official win64\n release and checks it against a SHA-256 pinned in the script before using it. It fails closed\n — a stale pin aborts rather than degrading to no verification — but it is one more download\n than the POSIX path needs, and the pin must be bumped on each minisign release.\n\n\n\n### Download the archive directly\n\nReleases publish **6 archives** — `.tar.gz` for macOS and Linux, `.zip` for Windows. The asset\nnames stay machine-shaped so that the installer, GoReleaser and the Homebrew formula can all\ncompute them; the friendly names below are for humans only.\n\n| You have | Download |\n|---|---|\n| **Mac (M series)** | `bravros-darwin-arm64.tar.gz` |\n| **Mac (Intel)** | `bravros-darwin-amd64.tar.gz` |\n| **Linux** | `bravros-linux-amd64.tar.gz` |\n| **Linux (ARM)** | `bravros-linux-arm64.tar.gz` — **newly supported** |\n| **Windows** | `bravros-windows-amd64.zip` |\n| **Windows (ARM)** | `bravros-windows-arm64.zip` |\n\nAll six live under\n[`releases/latest/download/`](https://github.com/bravros/bravros/releases/latest), alongside\n`install.sh`, `install.ps1`, `checksums.txt` and `checksums.txt.minisig`. Extract the binary to\n`~/.claude/bin` (`%USERPROFILE%\\.claude\\bin` on Windows), then run `bravros setup`.\n\n### What you actually get\n\n`bravros setup` is the wizard the installer hands off to. It writes into `~/.claude` from the\npayload **embedded in the binary** — no network, no source checkout — and asks you which of four\ncomponents you want:\n\n| Component | Goes to | What it is |\n|---|---|---|\n| `cli` | `~/.claude/bin` | The binary itself. Required; the installer already placed it. |\n| `claude-skills` | `~/.claude/skills` | The agent skills, at scope `core` (default, 18 skills) or `all` (35). |\n| `claude-templates` | `~/.claude/templates` | Git hooks and project templates used by `bravros init` and the commit-msg gate. |\n| `claude-settings` | `~/.claude/settings.json` | The managed settings block (the SessionStart hook), deep-merged into any existing file. |\n\nThere is one selection axis — components — and no plugin-category picker. `core` is the default\nskill scope on purpose: an always-on skill list has a context budget, and blowing it silently\nhides your least-used skills. `--skills=all` opts into the long tail. The picker previews each\nchoice live (an \"enter now installs:\" line shows exactly what and where), and the run ends with\na result table — component, `CHANGED` / `ALREADY CORRECT` / `SKIPPED`, destination, reason — so a\nrun that skipped everything can never read as success; emptying the selection needs an explicit\nconfirmation.\n\nNon-interactive forms, for CI and for dotfile scripts:\n\n```bash\nbravros setup --all --yes # everything, skills scope=all\nbravros setup --components=claude-skills,claude-settings --yes # a subset\nbravros setup --skills=all --yes # every skill, default components\nBRAVROS_COMPONENTS=claude-skills bravros setup --yes # same, via the environment\n```\n\nRe-running `setup` is idempotent and **never destructively overwrites**: a file that already\nexists and differs is left exactly as it is, and the payload's version is written beside it as\n`.new` and reported. `settings.json` is deep-merged entry by entry, never replaced. Your\nchoice is recorded in `~/.claude/state/setup.json`, which is what the SessionStart refresh reads\nlater. A plugin-managed Claude Code install is **detected and warned about** — bravros never\nwrites into a directory a plugin host owns.\n\nSetup also reconciles the `# >>> bravros-managed-global >>>` block in your global `CLAUDE.md`\nagainst the toolkit's own copy — no clone needed, since both the source block and the merge\nscript ship embedded in the binary — updating the managed section while leaving everything you\nwrote outside it untouched.\n\nThen, once per repository:\n\n```bash\nbravros init\n```\n\nThat detects your stack, writes `.bravros/config.json`, and installs the `commit-msg` and\n`pre-push` hooks under `.bravros/hooks/` via `core.hooksPath`. No global state, nothing outside\nthe repo.\n\n### Keeping it current\n\nBravros updates itself:\n\n| | What it does | Network? |\n|---|---|---|\n| `bravros selfupdate` | Runs from the SessionStart hook, at most once every 24h. If a newer release exists and has cleared a ~6h canary window, it downloads it, verifies the minisign signature, atomically swaps the binary — keeping the outgoing one as `bravros.prev` for one-generation rollback — and re-runs itself from the new binary to refresh components. Prints exactly one line: `🔄 bravros vX → vY (auto)`. | Yes, only when a swap happens |\n| `bravros update` | You run it by hand: same download-verify-swap, on demand. `--force` reinstalls even when already current. | Yes |\n\nThe installer scripts are version-aware the same way: `bash -c \"$(curl …)\"` resolves the latest\ntag and prints `already current (vX.Y.Z) — no download needed` or `updating vX.Y.Z → vA.B.C`,\nthen still hands off to the idempotent `bravros setup` as the repair path.\n\n`bravros update` refuses when a package manager owns the binary and names the right command\ninstead (`brew upgrade bravros`); brew/scoop installs are likewise never auto-swapped by\n`selfupdate`, only notified. Turn either off with `BRAVROS_NO_UPDATE_CHECK=1`, or set\n`\"auto_update\": false` in `setup.json` to keep `selfupdate` notify-only. Skills ship inside the\nbinary, so they can never drift from the CLI — a skill fix merged upstream reaches every machine\nwithin a day, zero-touch.\n\n### Other hosts\n\nGemini CLI has its own extension system:\n\n```bash\ngemini extensions install https://github.com/bravros/bravros --auto-update\n```\n\nThe Claude Code plugin marketplace lane is retired — `curl | sh` (or Homebrew) is the only\nsupported install path for Claude Code now. If you installed via `/plugin install bravros`\nbefore, `bravros setup` detects it, prints the exact removal command\n(`/plugin marketplace remove bravros-marketplace`), and migrates the machine to the installer\nmodel.\n\nNever run both for the same skills — the CLI detects a plugin-managed install and refuses to\nwrite there, but pointing two updaters at one tree is a conflict, not redundancy.\n\n---\n\n## 🚀 The loop\n\n```\n/recon ➔ /orchestrate ➔ /pr ➔ /finish\n```\n\n```bash\n/recon the checkout total is wrong for orders with a coupon\n```\n\n`/recon` takes a symptom, a screenshot, a stack trace, or a feature idea and produces **one\ndossier folder** — `.planning/P-NNNN-/` — carrying the brief, the constraints that must not\nchange, the closed decisions, the traps, and phased tasks with per-phase verify commands.\n\nIf it's a defect, `/recon` hands the hunt to `/scout`, which queries the code graph, traces the\nreal execution path, and **certifies** the cause with runtime proof before anything is written\ndown. No certification, no diagnosis — it reports `UNCERTIFIED` rather than shipping a guess.\n\n```bash\n/orchestrate .planning/P-0001-coupon-total/\n```\n\n`/orchestrate` executes that folder: it dispatches phases to subagents by complexity marker,\nverifies each phase against its own `Verify:` command, and commits as it goes. `/pr` opens the\npull request; `/finish` merges it and records the outcome.\n\nNothing about the loop is mandatory. `/quick` exists for a two-line fix, and `/backlog` for an\nidea you are not ready to act on.\n\n---\n\n## 🧰 What you can do with it\n\n**Ship a change end to end**\n\n| | |\n|---|---|\n| `/recon` | Turn a bug report, screenshot, or feature idea into a reviewed dossier with phases and acceptance criteria |\n| `/scout` | Find the culprit and certify it with runtime proof — never edits code |\n| `/orchestrate` | Execute a dossier phase by phase, verifying each one before moving on |\n| `/quick` | Small contained fix, no ceremony |\n| `/commit` `/ship` `/push` | Formatted commits, enforced by hook rather than hope |\n| `/pr` `/pr-review` `/address-pr` `/local-review` | Open, review, and answer review feedback |\n| `/finish` `/promote` `/after-merge` | Merge, release to production behind a human gate, and run the post-deploy checklist |\n\n**Keep a repo healthy**\n\n| | |\n|---|---|\n| `/backlog` | Park ideas with enough structure to judge later |\n| `/triage-sweep` | Drain a stale issue and backlog queue, verifying every close against live code |\n| `/batch-merge-prs` `/prune-merged` | Land a queue of PRs, then clean up the branches |\n| `/doctor-plus` `/verify-install` | Health-check the toolkit and the workspace |\n| `/context` | Generate or audit `CLAUDE.md` / `AGENTS.md` from the actual code |\n| `/worktree` | Isolated worktrees with real provisioning |\n\n**Understand a codebase**\n\n| | |\n|---|---|\n| `/graphify-this-project` | Build a queryable knowledge graph of the code, committed and refreshed on merge |\n| `/graphify-status` | Report label coverage across every graph on the machine |\n| `/interview-me` | Stress-test a plan round by round until nothing is silently assumed |\n| `/advise-project-approach` | Stack and architecture advice grounded in real comparables |\n\nAdd the category plugins for the rest, or ignore them. `bravros --help` lists the kernel verbs.\n\n---\n\n## 🛠️ Why there is a CLI at all\n\nMost of the toolkit is prose, because a 2026 model sequences work better than a step list does.\nThe Go binary exists only for the things a prompt genuinely cannot do:\n\n| Category | Verbs | Why it must be code |\n|---|---|---|\n| **Format & identity** | `commit`, `nextid` | Commit format is enforced by a hook, not a suggestion. IDs are reserved atomically across worktrees. |\n| **Human presence** | `promote`, `destructive`, `pr-review` | The session must be **unable** to mint its own authority. Tokens come from a separate terminal you control. |\n| **Atomicity** | `merge-lock` | Two sessions must not merge at once. |\n| **Preserve before delete** | `discard`, `trash`, `clean-untracked` | Content git has never seen is copied to `.trash/` before anything removes it. |\n| **Provisioning** | `worktree`, `branch`, `config`, `init`, `hooks` | Real filesystem and git work. |\n| **Distribution** | `setup`, `update`, `selfupdate`, `deploy`, `install` | Installer machinery: the component wizard, the signed self-replace, and the embedded-payload refresh. |\n| **Secrets** | `secrets set`, `secrets sa-token` | Keyring and `op://` resolution — values never touch a prompt. |\n\nIf a rule can be enforced by code, it lives in the binary. If it can't, it's stated once as a\nhard constraint in a skill and nowhere else.\n\n---\n\n## 🔒 Safety\n\n**The agent cannot authorize its own dangerous actions.** That's the design, not a policy note.\n\n- **Production merges need you.** `main` is protected by GitHub branch rules and a `pre-push` hook\n that refuses `refs/heads/main`. That pair is the control that actually holds, because branch\n protection lives on a server the agent does not run on. Layered on top, `bravros promote unlock`\n refuses to mint a token when it detects an agent session, so a session cannot casually\n self-authorize. **Know the limit:** the token is an unsigned JSON file on disk — a guardrail\n against accidents and drive-by self-approval, not a cryptographic barrier. Branch protection is\n what stands between an agent and production; the token is what stops it happening by mistake.\n- **Deletion preserves first.** `discard`, `trash`, and `clean-untracked` copy into `.trash/`\n before removing anything, and are reversible. Permanently destroying content that git has never\n seen requires a single-use token, again minted out of band.\n- **Commit hygiene is enforced, not requested.** The `commit-msg` hook rejects malformed subjects\n and strips AI attribution trailers. A skill that says \"never do X\" without a mechanism behind it\n is labelled as lore, not presented as protection.\n- **Secrets stay out of context.** `secrets` and `sa-token` resolve from your keyring or 1Password\n at the point of use; values are never pasted into a prompt or committed.\n- **Installers are the highest-risk code path**, so they behave accordingly: settings files are\n merged, never overwritten, and a backup is written before any change.\n\n## 🕵️ Privacy\n\n**Bravros makes no network calls to us, because there is no \"us\" to call.** There is no server, no\naccount, no licence check, no dashboard.\n\n- ❌ No analytics, no crash reporting, no usage or command tracking\n- ❌ No file paths, file contents, or prompts leave your machine\n- ❌ No third-party SDKs in the binary — grep it yourself\n- ✅ The only outbound traffic is **GitHub releases**: fetching a release archive when you run\n `bravros update`, and one \"is there a newer version\" check at most once a day (off with\n `BRAVROS_NO_UPDATE_CHECK=1`). Skills come from the binary you already have, so refreshing them\n is a local file copy. All of it is watchable on the wire.\n\nVerify it the same way you would verify anyone's claim — run the CLI behind mitmproxy, Charles, or\nWireshark and watch the wire.\n\n---\n\n## 🔐 Verify the trust chain\n\nEvery release is signed with minisign. `install.sh`, `install.ps1` and `bravros update` all check\nthat signature before anything is written to disk, against a public key pinned in the script and\ncompiled into the binary. To verify by hand:\n\n```bash\nPUBKEY=\"RWQqHlahq4RjNnCasO/8yMsgtLGfdHejILKMxxpsulIs1rII6IgMO26G\"\n\ncurl -LO https://github.com/bravros/bravros/releases/latest/download/checksums.txt\ncurl -LO https://github.com/bravros/bravros/releases/latest/download/checksums.txt.minisig\n\nminisign -Vm checksums.txt -P \"$PUBKEY\"\n# expected: Signature and comment signature verified\n# Trusted comment: Bravros release v2.9.0\n```\n\nThe same key is published at [bravros.dev/security](https://bravros.dev/security). Because the\nsource is public, you can also just build it yourself: `cd cli && go build .`\n\n---\n\n## 📦 What's in this repo\n\n| Path | What it is |\n|---|---|\n| `skills/` | The 35 skills — source of truth. Each is a `SKILL.md` plus `references/` loaded on demand. 18 carry `core: true`. |\n| `cli/` | The Go kernel. `cli/internal/payload/` holds the synced copy of `skills/` + `templates/` that gets embedded into the binary. |\n| `plugins/` | Generated per-category plugin trees. Do not edit — `tools/skillgen` rewrites them. |\n| `tools/skillgen` | Generates the per-host always-on files and lints skills for host-specific tokens. |\n| `tools/cataloggen` | Builds `docs/catalog/catalog.json` from skill frontmatter. |\n| `.claude-plugin/` | Claude Code marketplace + plugin manifests. |\n| `gemini-extension.json` | Gemini CLI extension manifest. |\n| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules` | Generated per-host contracts. Edit the source, not these. |\n| `install.sh`, `install.ps1`, `.goreleaser.yml` | Signed release and install path — POSIX and native Windows. |\n\nSkills are authored **host-neutral**: no harness-specific tool names, no absolute paths. CI fails\nthe build if one slips in, which is the only reason the same skill runs unchanged on four hosts.\n\n---\n\n## 📜 License\n\nMIT — see [LICENSE](LICENSE). Contributions welcome via issues and pull requests; the skill catalog\nis curated, so open an issue before a large addition.\n",
"bytes": 20817,
"sha": "9ebb48ed61c09dd69bd70b69b5df708371325a14cb282e60a2fe9311502601ae",
"repo_slug": "bravros/bravros",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_bravros_bravros_be45a89f/readme"
}
![\"Bravros\"](\"docs/catalog/logo.jpg\"){kind=logo}
\n![\"MIT\"](\"https://img.shields.io/badge/license-MIT-22C55E?style=for-the-badge\"){kind=icon}
![\"35](\"https://img.shields.io/badge/skills-35-3B82F6?style=for-the-badge\"){kind=icon}
![\"Go](\"https://img.shields.io/badge/cli-Go-00ADD8?style=for-the-badge&logo=go&logoColor=white\"){kind=icon}
![\"Signed\"](\"https://img.shields.io/badge/releases-minisign-8B5CF6?style=for-the-badge&logo=letsencrypt&logoColor=white\"){kind=icon}
![\"No](\"https://img.shields.io/badge/telemetry-none-64748B?style=for-the-badge\"){kind=icon}