melech-buy-vs-build

Files (2)

• SKILL.md
• lanes.md · references/

SKILL.md (first lines)

# Buy vs Build

An agent asked to "add background jobs" will happily write a `tasks` table, a
polling worker, a retry column, and a dead-letter flag. It works. It is also
BullMQ, or Trigger.dev, or Cloud Tasks, or the queue library already sitting in
`package.json` — rebuilt badly, and now owned forever.

Nobody makes the call deliberately. Repo-level review only ever asks *"does
this already exist in our code?"*, and model memory answers external questions
with confident, stale, sometimes invented package names. The expensive,
hard-to-reverse decision — own the implementation, or hand the capability to a
third party — gets made by default instead of on evidence.

`melech-buy-vs-build` owns that decision. It looks **outward** — finding what the
rest of the world already shipped for the capability, verified against live
sources — and it runs one **inward** check first: *adopt-vs-rebuild*, is this
already covered by a dependency or vendor you already have? Then it brings back
a shortlist and a verdict: adopt, or keep building.

Think *"is there an AI for that?"* — but for the build-vs-buy call, and
grounded in evidence instead of vibes.

---

## Two Intents

Both intents are **outward** research feeding one build-vs-buy verdict. Whichever
fires, run the inward **adopt-vs-rebuild** check first (step 2) — a capability you
already own beats anything you would go find or build.

| Intent | Trigger | Goal |
|---|---|---|
| **Intercept** | Code, a plan, or a diff exists and may be reinventing something. | Name what was (re)built, find the incumbents, decide adopt vs. keep building. |
| **Explore** | Open-ended: "what's out there for X", "any new tools for X", "how do people do X now". | Map the space, surface the notable and the recent, arm the user to choose. |

Do not ask which intent applies when it is obvious from the input. A diff or a
proposal means intercept. A bare capability question means explore.

---

## The One Rule That Decides Everything

**Search the capability, not the noun.**

The single reason this research fails is searching the user's own vocabulary.
An agent that greps the web for `"postgres polling table worker"` finds
blog posts. An agent that recognizes the capability as **durable background job
execution** finds the entire category.

So before any search: translate the implementation into the canonical term the
industry uses for it.

| What the agent built | What to actually search |
|---|---|
| Rows in a table + a polling worker + retry count | job queue, background jobs, durable task execution |
| Custom event bus with handler registry | pub/sub, message broker, event bus |
| Hand-rolled retry-with-jitter wrapper | retry library, resilience/backoff library |
| Bespoke role/permission matcher | authorization / policy engine, RBAC / ReBAC |
| Cron-ish `setInterval` + lockfile | job scheduler, distributed cron, workflow orchestration |
| Diff-and-apply state machine for a wizard | state machine library, workflow engine |
| Custom CSV/Excel export writer | spreadsheet / serialization library |

If unsure of the canonical term, the **first** search is for the term itself:
*"what is it called when …"*. Get the vocabulary right, then fan out.

---

## Workflow

```text
1. Name the capability  ─►  2. Read the ground truth  ─►  3. Fan out lanes  ─────────►  4. Reduce  ─►  5. Shortlist + verdict  ─►  6. Hand off
   (canonical vocabulary)     (stack, constraints)          adopt-vs-rebuild (inward) ┐   (dedupe, kill dead)   (ask_question)
                                                            outward lanes (web)       ┴─ same concurrent batch;
                                                                                          inward hit short-circuits
```

### 1. Name the capability

State in one line what the thing *does*, stripped of the local implementation.
List 2–5 canonical search terms and any obvious synonyms. Show this to the user
before fanning out — a wrong capability name wastes the whole run.

### 2. Read the ground truth (inline, must be first)

This quick read stays on the main thread because the outward lanes cannot be
briefed without it. Gather the constraints that will decide fit:

- **Language and runtime**, and what is already in the manifests
  (`package.json`, `requirements.txt`/`pyproject.toml`, `go.mod`, `Cargo.toml`,
  `Gemfile`, `pom.xml`)
- **Infrastructure already paid for**: cloud provider, Postgres/Redis/Kafka,
  vendors already in the bill
- **Hard constraints**: self-host only, data residency, licensing policy,
  air-gapped, no new vendors, budget
- **Scale reality**: 100 jobs/day and 100k jobs/second do not shortlist the same
  tools

If this cheap read already surfaces a blatant hit — the capability is *literally*
a direct dependency or an obviously enabled vendor feature — stop here and report
it. Do not fan out to buy something you already own. Otherwise, carry the
constraints into step 3 and let the deep adopt-vs-rebuild check run concurrently.

### 3. Fan out parallel lanes

Dispatch independent research lanes concurrently — one subagent per lane, each
running **multiple web searches** along its own path (except adopt-vs-rebuild,
which is mostly local). Lanes hunt different *kinds* of answers, not different
keywords. The inward lane and the outward lanes launch in the **same concurrent
batch**, so you do not pay the inward check as serial latency.

| Lane | What it hunts |
|---|---|
| **Adopt-vs-rebuild** *(inward, privileged)* | The deep version of the step-2 check: transitive deps, framework/stdlib built-ins, a vendor plan that already covers this, an internal monorepo library. Mostly local work plus targeted doc lookups. **Short-circuit authority** — see below. |
| **Canon** | The category's standard name and the 3–8 options every comparison lists. Awesome-lists, category pages, "X vs Y" roundups. |
| **Ecosystem** | Libraries and OSS in *this project's* language. Package registries, GitHub, framework-native answers. |
| **Commercial** | Managed services, dev tools, SaaS, cloud primitives. Includes the boring cloud answer nobody mentions. |
| **Verdicts** | What practitioners actually say: HN/Reddit threads, "we migrated off X", postmortems, why people regret each option. |
| **Counter-case** | Why rolling your own is sometimes right here, and the known failure modes of the incumbents. Keeps the shortlist honest. |

From AdirD/agent-shell-hamelech, MIT.

More from AdirD/agent-shell-hamelech