Recipes
What a recipe is, which recipes you can run, and when to pick each one.
After reading this page you'll know what a recipe is, which recipes you can trigger yourself, and which one fits the job in front of you.
What a recipe is
A recipe is a bee's playbook: a YAML file in recipes/ that defines what the bee is, what context it reads, and the phases it must work through (the swarm agent's playbook is a pair of markdown phase files in recipes/swarm-agent/ instead). Specialist recipes share the same core three-phase shape (scan/investigate, fix, ship) with explicit action budgets; how Swarm thinks covers the phases, the budgets, and why they exist. The happy path always ends the same way, a PR on GitHub for a human to review, though a run can instead settle with a verdict (for example a verified false positive) when there is nothing to ship. No human writes code. A human always reviews.
Recipes you can run
| Recipe | Use when |
|---|---|
| the swarm agent (default) | Anything that doesn't fit a specialist below. It plans the work itself, then executes the plan step by step. Any request that doesn't name a bee (or names one that doesn't exist) lands here. |
| a11y-bee | You want a WCAG 2.1 AA accessibility audit with mechanical fixes (alt text, labels, ARIA) applied automatically. |
| support-bee | You have a support ticket or bug report and want the root cause found and fixed with tests. |
| tinfoil-bee | Semgrep has flagged a security vulnerability and you want an idiomatic remediation with regression tests. |
| cleaner-bee | You want recent commits on a repo's default branch reviewed for bugs and security issues, one-off or on a schedule. |
You don't have to memorise this table. In Slack, naming a bee (support-bee, a11y-bee, tinfoil-bee, cleaner-bee) routes straight to that recipe; leave the name out and the swarm agent picks up the request. The dashboard's "Run a bee" form offers the same specialists alongside a swarm agent tier, and the Jira trigger routes on a bee-name label; an unlabelled ticket goes to the swarm agent.
From a checkout of the repo you can also dispatch a run directly:
node cli/bin/swarm.js run --recipe tinfoil-bee --repo org/repo --jira ABC-123Building-block recipes
A few recipes in recipes/ are mostly internal machinery rather than bees you pick day-to-day:
- code-writer, test-author, validator: the three roles of the writer → tester → validator topology used for code-modifying jobs. The validator adversarially re-derives what changed with fresh context and only pushes the PR if the work holds up.
- test-fixer: runs a project's unit suite and fixes failing tests. Not in the Slack or dashboard catalogues, and the
swarmCLI rejects it; ask for it by name and the swarm agent dispatches it from the bee catalogue, or run it directly from a checkout withscripts/run-agent.sh --recipe test-fixer --repo <url> --ticket <text>.
You'll see these names in run logs and pipeline events, but you rarely need to invoke them yourself.
See it in action
Invoking a named bee from chat: name the bee and the repo, and the exact recipe runs.
What a bee report looks like: the PR, the changes, and the findings behind each fix.