{ "markdown": "# Buy vs Build\n\n

\n \n \"It's\n \n
\n xkcd 3233: “Make It Myself” · explained · CC BY-NC 2.5\n

\n\n[![CI](https://github.com/stdin/buy-vs-build/actions/workflows/ci.yml/badge.svg)](https://github.com/stdin/buy-vs-build/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n**Stop your coding agent from reinventing the invoice.**\n\nBuy vs Build is an always-on ruleset for AI coding agents. Before the agent writes code, it has to ask:\n\n> Can this be solved with a built-in, platform feature, installed dependency, open source library, or commercial product before we own it forever?\n\nThat one pause catches a lot of expensive mistakes: custom date pickers, homemade auth, duplicate validators, tiny libraries that bring a dependency tree with them, and \"temporary\" infrastructure that somehow becomes a team.\n\nBuy vs Build does not worship dependencies. It does not worship in-house code. It makes the agent choose deliberately.\n\n## The problems it solves\n\nAI agents are fast — and that speed runs straight into ownership cost. Left alone, an agent will happily:\n\n- **Reinvent what already exists** — a custom date picker instead of a native input, a helper instead of the standard library, OAuth by hand because the prompt said \"simple login.\"\n- **Pick the impressive tool over the right one** — WebSockets for a one-way feed, NoSQL \"for scale\" on relational data, a message queue for a nightly cron job.\n- **Adopt dependencies it never vetted** — an unmaintained, single-maintainer, or vulnerable package pulled in for three lines of code (the [left-pad story](https://en.wikipedia.org/wiki/Npm_left-pad_incident), on repeat).\n- **Leave no trace of why** — six months later nobody knows why a service was chosen, or when to revisit it.\n\nEach one is a bill that arrives later: a migration, an incident, an audit finding, a dependency you can't remove. Buy vs Build adds the missing engineering reflex — **reuse first, pick the option that fits, vet what you adopt, and write the call down — build only when the constraints justify owning it.**\n\n## What you get\n\n| It stops the agent from… | …by |\n| --- | --- |\n| Reinventing built-ins, platform features, and existing dependencies | Walking a reuse ladder before writing new code |\n| **Picking the flashy tool over the right one** | Matching the option to the requirement (SSE vs WebSockets, SQL vs NoSQL, cron vs queue) |\n| **Adopting a dependency it never researched** | Checking health, maintainers (bus factor), known vulnerabilities, license, and footprint — for **any language** |\n| Ignoring your team's real constraints | Reading a per-project `.buyvsbuild.json` (weight security, ban or prefer dependencies, mark what's core) |\n| Losing the reasoning behind a choice | Recording decisions as durable ADRs |\n| Slipping risky dependencies through review | A PR check that flags new dependencies (npm, PyPI, Go, Maven, Cargo, NuGet, RubyGems) added without a decision note — and posts their health, security, and license-compatibility signals. In `strict` mode, missing dependency notes fail CI. |\n| Carrying ownership risk in dependencies you already have | An audit (`npm run audit:deps`) that ranks every dependency by ownership risk and names the lower rung you could drop to |\n| Forgetting to revisit a decision when its trigger fires | A revisit check (`npm run revisit`) that surfaces ADRs whose date- or version-based trigger has come due |\n| Mistaking a good recommendation for a good result | A post-implementation reflex: confirm the choice actually cut code, failure modes, and operating burden — a sound option can still be integrated badly |\n| Being unprovable marketing | A behavior benchmark (Codex + Claude, with an optional LLM judge) that measures the change |\n\nThe three that matter most: **it picks the right tool for the job, it researches dependencies before you own them, and it works across every agent you use** — the same rule ships to Codex, Claude Code, Gemini, Cursor, GitHub Copilot, and more.\n\n## Quick Start\n\nInstall the agent rule and optional PR dependency check in any repository:\n\n```bash\nnpx buy-vs-build init\n```\n\nThat writes:\n\n- `AGENTS.md` with the buy-before-build rule for agent hosts that read it.\n- `.buyvsbuild.json` so the project can tune strictness and ownership priorities.\n- `.github/workflows/buy-vs-build-review.yml`, which comments on new dependencies\n that lack a decision note and fails CI when `.buyvsbuild.json` is `strict`.\n\nFor instruction-only setup without the GitHub Action:\n\n```bash\nnpx buy-vs-build init --agents-only\n```\n\n## Decide First: Core vs Context\n\nThe ladder below tells you *how far to reach for reuse*. Two questions decide *whether to reuse at all*:\n\n- **Core or context?** Core is the differentiation customers choose you for. Context is everything they expect but never reward — auth, email, parsing, config. Build core; reuse context.\n- **Commodity or novel?** Commodity capabilities are standardized and stable. Novel ones are still changing or specific to you. Reuse commodities; build novelty.\n\n| | Commodity | Novel |\n| ----------- | --------------------------------------------------------------- | ------------------------------------------------ |\n| **Core** | Reuse the substrate, build the thin layer that differentiates. | Build in-house — this is the moat. |\n| **Context** | Reuse aggressively: built-in → platform → dependency → commercial. | Do the minimum: defer, stub, or simplest reuse. |\n\nThen scale scrutiny to **reversibility**: a two-way-door choice (easy to swap or delete) decides fast; a one-way-door commitment (deep platform, data-format, or vendor lock-in) earns rigor and a written exit plan.\n\n## The Rule\n\nOnce you know what you are choosing to own, walk the reuse ladder. Stop at the first rung that satisfies the requirement:\n\n1. **Do nothing**: skip speculative requirements and scaffolding.\n2. **Use built-ins**: prefer language built-ins and the standard library.\n3. **Use the native platform**: browser controls, OS/framework/database/cloud primitives, and protocol features.\n4. **Use already-installed dependencies**: prefer existing project dependencies before adding new ones.\n5. **Use open source**: add a mature library only when it lowers total ownership cost.\n6. **Use commercial**: buy reliability, compliance, operations, support, or time when cheaper than owning it.\n7. **Build in-house only when** reuse fails the real constraints, or the work is core differentiation.\n\nFor non-obvious choices, the agent compares fit, total cost of ownership, security, licensing, maintenance, integration, maturity, reversibility, and exit risk. After implementing, it verifies the choice actually paid off — fewer lines, fewer failure modes, less to operate — because a sound option can still be integrated badly. The decision note records that tradeoff so a reviewer can check it later.\n\nExample decision note:\n\n```text\nDecision: use native-platform: native date input.\nTradeoff: accessibility and browser behavior are good enough for a due-date field.\nRejected: open-source date picker because it adds styling, keyboard, and date-edge ownership.\nRevisit if product needs range selection or non-Gregorian calendar support.\n```\n\n## Safety Boundaries\n\nThis is not \"do less at any cost.\" Buy-vs-build thinking must never cut:\n\n- Trust-boundary validation\n- Security and privacy requirements\n- Data-loss protection\n- Accessibility\n- Production observability\n- Explicit user requirements\n\nCheap code that loses customer data is not cheap. It is just a delayed invoice.\n\n## Tune It Per Project\n\nDrop a `.buyvsbuild.json` at your repo root to adapt the rule to your real\nconstraints. The SessionStart hook injects it alongside the rule, so the agent\nsees your policy on every turn.\n\n```json\n{\n \"strictness\": \"strict\",\n \"priorities\": [\"security\", \"speed\"],\n \"preferredDependencies\": [\"zod\", \"date-fns\"],\n \"bannedDependencies\": [\"moment\"],\n \"alwaysBuild\": [\"our deal-scoring formula\"],\n \"alwaysReuse\": [\"auth\", \"email delivery\", \"payments\"],\n \"notes\": \"We are SOC2; weight compliance and observability heavily.\"\n}\n```\n\nEvery field is optional. A regulated shop can weight security and force reuse of\nauth; a startup can prioritize speed; a team can pin its standardized\ndependencies and ban the ones it has been burned by. Malformed config is ignored,\nnever fatal.\n\n## Supported Agent Surfaces\n\nThis repo ships the same rule through the files each host already knows how to read.\n\n| Host | Files |\n| --- | --- |\n| Codex | `.codex-plugin/plugin.json`, `skills/buy-vs-build/`, `hooks/hooks.json`, `AGENTS.md` |\n| Claude Code | `.claude-plugin/plugin.json`, `CLAUDE.md`, lifecycle hook config |\n| Gemini CLI / Antigravity | `gemini-extension.json`, `GEMINI.md`, `AGENTS.md` |\n| GitHub Copilot | `.github/copilot-instructions.md` |\n| Cursor | `.cursor/rules/buy-vs-build.mdc` |\n| Windsurf | `.windsurf/rules/buy-vs-build.md` |\n| Cline | `.clinerules/buy-vs-build.md` |\n| Kiro | `.kiro/steering/buy-vs-build.md` |\n| OpenCode | `opencode.json`, `.opencode/plugins/buy-vs-build.mjs` |\n| OpenClaw | `.openclaw/skills/buy-vs-build/` |\n| Pi-style harnesses | `package.json` `pi.skills` |\n| Generic agents | `AGENTS.md` |\n\nThe hook files are included for hosts that support lifecycle injection. Hosts that only read instruction files still get the rule, just without startup fanfare.\n\n## Install\n\n### GitHub Action\n\nAdd the dependency review check directly:\n\n```yaml\nname: Buy vs Build PR Review\n\non:\n pull_request:\n\npermissions:\n contents: read\n pull-requests: write\n\njobs:\n review:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v5\n with:\n fetch-depth: 0\n - uses: actions/setup-node@v5\n with:\n node-version: 22.x\n - uses: stdin/buy-vs-build/.github/actions/dependency-review@main\n env:\n BASE_SHA: ${{ github.event.pull_request.base.sha }}\n HEAD_SHA: ${{ github.event.pull_request.head.sha }}\n PR_BODY: ${{ github.event.pull_request.body }}\n GITHUB_TOKEN: ${{ github.token }}\n```\n\n### Codex\n\n```bash\ncodex plugin marketplace add stdin/buy-vs-build\n```\n\nOpen `/plugins`, install Buy vs Build, and start a new session. If your Codex surface reads `AGENTS.md`, cloning the repo or copying `AGENTS.md` into a project is enough for instruction-only mode.\n\n### Claude Code\n\nUse the Claude plugin flow with this repository as the source, or copy `CLAUDE.md` into the target project for instruction-only mode.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/stdin/buy-vs-build\n```\n\n### OpenCode\n\nRun OpenCode from a checkout of this repo, or add this plugin path to your project `opencode.json`:\n\n```json\n{\n \"plugin\": [\"./.opencode/plugins/buy-vs-build.mjs\"]\n}\n```\n\nThe OpenCode plugin injects the ruleset into the system prompt every turn and registers this repo's `skills/` path.\n\n### Instruction-Only Hosts\n\nCopy the matching file into your project:\n\n- GitHub Copilot: `.github/copilot-instructions.md`\n- Cursor: `.cursor/rules/buy-vs-build.mdc`\n- Windsurf: `.windsurf/rules/buy-vs-build.md`\n- Cline: `.clinerules/buy-vs-build.md`\n- Kiro: `.kiro/steering/buy-vs-build.md`\n- Generic: `AGENTS.md`\n\nThis is the lowest-tech install path, which is appropriate for a project about not overbuilding things.\n\n## Commands / Skills\n\nSkill-capable hosts can use:\n\n| Skill | Use it when |\n| --- | --- |\n| `$buy-vs-build` | Apply the core rule while coding. |\n| `$buy-vs-build-right-tool` | Pick the option that fits the requirement's shape, not the flashy default (SSE vs WebSockets, SQL vs NoSQL, cron vs queue). |\n| `$buy-vs-build-review` | Review a diff for avoidable custom code, unnecessary dependencies, or a choice integrated badly. |\n| `$buy-vs-build-audit` | Audit a repo or subsystem for ownership mistakes. |\n| `$buy-vs-build-decision` | Draft a short decision memo. |\n| `$buy-vs-build-gain` | Summarize benchmark cases and measured impact. |\n| `$buy-vs-build-adr` | Record a non-obvious decision as a durable ADR in `docs/decisions/`. |\n| `$buy-vs-build-dependency` | Research a package's health, security, license, and footprint before adopting it. |\n\n## Benchmarks\n\nLocal overhead is intentionally tiny:\n\n- Instruction generation: about `0.009ms` average.\n- Hook process startup: about `28ms` average.\n\nThe 13 behavior cases in `benchmarks/behavior-cases.json` cover overbuild traps (date input, CSV export, validation, password-reset email, OIDC, proprietary scoring), right-tool traps (SSE vs WebSockets, REST vs GraphQL, SQL vs NoSQL, webhook vs polling, cron vs queue), and built-in-over-dependency (UUID, string padding).\n\nLatest live validation:\n\n- Run: [behavior-claude-2026-06-19T10-23-39-792Z.md](benchmarks/results/behavior-claude-2026-06-19T10-23-39-792Z.md)\n- Agent: Claude Code `2.1.183`, model `claude-haiku-4-5`, Node `v24.12.0`, macOS arm64.\n- 13 cases: baseline `33/65`, Buy vs Build enabled `55/65` (**+22**). Correct rung/option hits: `11/13 → 12/13`.\n- Every case improved or held, and the biggest lifts are the traps the rule targets — built-in UUID `0→3`, relational store `2→5`, the right-tool cases `+2` each.\n- Run on a small model on purpose: the rule's lift shows clearest there and runs stay cheap. For quality-aware scoring instead of keyword matching, add `--judge`.\n\nRun it yourself:\n\n```bash\nnpm run benchmark:behavior # Codex CLI\nnpm run benchmark:behavior:claude # Claude CLI (small model by default)\nnpm run benchmark:behavior:claude:judge # Claude CLI, rubric-based LLM judge\nnpm run benchmark:behavior:gate # Dry regression gate used by npm test\n```\n\nImportant honesty note: this benchmark scores final recommendations, not code diffs, token spend, or incident reduction. It is still useful because it tests the thing this plugin promises first: does the agent make the buy-vs-build decision visible before it starts owning code? The reflex to check the *implemented* outcome — did it actually cut code, failure modes, and operating burden? — now lives in the rule and the review skill, but measuring that outcome directly is future work. Marketing is allowed to wear shoes; it is not allowed to fly.\n\n## Development\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\n`npm test` also runs a dry behavior benchmark gate so rule changes cannot silently\ndrop below the expected score threshold.\n\nRun the local overhead benchmark:\n\n```bash\nnpm run benchmark\n```\n\nRun the live behavior benchmark (Codex CLI or Claude CLI):\n\n```bash\nnpm run benchmark:behavior\nnpm run benchmark:behavior:claude\n```\n\nScore recommendations with the rubric-based LLM judge instead of the keyword heuristic (more robust, calls the model once per response):\n\n```bash\nnpm run benchmark:behavior:claude:judge\n```\n\nCheck benchmark report generation without calling a model:\n\n```bash\nnpm run benchmark:behavior:dry\nnpm run benchmark:behavior:claude:dry\nnpm run benchmark:behavior:gate\n```\n\nAudit the dependencies a repo already owns (ranks every direct dependency by ownership risk and names the rung it could drop to; reads `package.json`, `package-lock.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`, and NuGet project files):\n\n```bash\nnpm run audit:deps # audit the current directory\nnode scripts/audit-deps.js path/to/repo\n```\n\nSurface decisions whose revisit trigger has come due (date- or dependency-version-based; the rest are flagged for a human look):\n\n```bash\nnpm run revisit\n```\n\nCheck copied rule files for drift:\n\n```bash\nnode scripts/check-rule-copies.js\n```\n\nValidate the Codex skill and plugin (paths are relative to your Codex install):\n\n```bash\npython3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/buy-vs-build\npython3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .\n```\n\nWhen changing the compact rules, edit `rules/buy-vs-build.md` first, then update the copied instruction files. The drift check will complain if they diverge, which is its one job and it takes that job very seriously.\n\n## FAQ\n\n**Is this anti-open-source?**\nNo. It is pro-ownership clarity. Use open source when it lowers total cost and risk. Avoid it when it turns three obvious lines into another thing to patch forever.\n\n**Is this anti-commercial tools?**\nNo. A paid service can be the cheapest option when it buys reliability, compliance, support, or operations you do not want to own.\n\n**When should we build in-house?**\nWhen the behavior is core product differentiation, the code is smaller and clearer than a dependency, or reuse fails security, privacy, licensing, latency, offline, portability, data-residency, or integration constraints.\n\n**Will this slow agents down?**\nThe local rule overhead is tiny. The decision may add a sentence. That sentence is cheaper than a migration.\n\n## License\n\n[MIT](LICENSE).\n", "bytes": 17455, "sha": "493f73e686afe86f57e39b29d590fc7d76377c5885f8e4121d3ec7ff4b6f8d6d", "repo_slug": "stdin/buy-vs-build", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_stdin_buy_vs_build_ef849352/readme" }