# Bot-Generator-Bot: a compiler for typed agent manifests

> The second version of Bot-Generator-Bot turns a bot idea into a runnable agent by compiling a normalised specification into a manifest with a digest, validating the output against a typed schema, and exposing the result through a CLI and an MCP server. The original project was a collection of 39 prompts, and those are kept unchanged for provenance.

**ruvnet/Bot-Generator-Bot** — The ultimate bot generator bot prompt. Use this prompt to create powerful ChatGPT bots for anything you can imagine.

- Repository: https://github.com/ruvnet/Bot-Generator-Bot
- Stars: 586 · Forks: 127
- Language: JavaScript
- License: not declared
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ruvnet-bot-generator-bot

## From a prompt collection to a compiler

The repository is the second version of a project that started as something else, and the README is upfront about it. The original 2023 project was a prompt collection, and this preview adds working software while preserving that collection under a prompts directory for historical reference, with the note that those older prompts are not reviewed execution policies or qualified medical or legal systems. What the software does is described in one sentence, that you choose a template, define typed outputs, then export a standalone agent or run it through the CLI or MCP. The runtime underneath is the real one, in that it uses the actual MetaHarness kernel, native RuVector memory and optional RuFlo routing, and the two rules that matter are stated plainly: model calls require explicit operator configuration, and compilation stays offline. That separation is the design. Nothing is sent anywhere while a specification is turned into a manifest, so the part of the pipeline that touches an untrusted description is also the part that cannot cause a side effect. The capability table adds the details, with 50 tools, 42 prompt templates and three resources exposed through the CLI and MCP, and a capability list that names a deterministic compiler, typed output validation and an operator tool policy as the three pieces that carry the safety argument.

## Deterministic compilation and the typed output contract

The compiler input is a small object with a spec key containing name, purpose, context, examples, output and tools, and the README points to a complete JSON example in the fixtures directory. The output side is a typed contract, with field types limited to string, number, integer and boolean, all fields required, and extra fields rejected rather than ignored. The validation behaviour is stated as a list of what it refuses, missing or extra fields, invalid types and unsafe numbers, and the size limits are concrete: an input cap of 32 KiB, strings of 8 KiB, nesting 12 levels deep, and output schemas of 16 fields. The determinism claim is the part that makes the rest auditable, that the same normalised specification produces an identical manifest and an identical SHA256. That is what lets you store a manifest, show its digest, and later check that it has not changed. The README is careful about what that proves, stating that the verify command checks manifest consistency and not authorship, since an attacker can create a different consistent manifest. So the digest is a change detector and a provenance handle, not a signature.

## The tool policy, and why requests never grant authority

The operator tool policy is the third pillar, and the README describes it in a way that is worth reading twice. Requests must be in a fixed catalog and in the operator allowlist, and requests never grant authority. The distinction is between what a specification may ask for and what the operator has agreed to. To let a specification request the search tool you set BOT_ALLOWED_TOOLS to search locally, and the agent runtime separately enforces the operator grant, so the two have to agree. The runtime's supported tool is the local memory search, and the other catalog tools are reserved and fail closed in this runtime, which means a request for them is refused rather than ignored. There is also a rule about secrets, that no tokens or provider credentials belong in a specification, which is the correct way to keep a spec portable and keeps the compile step free of anything sensitive. Read together, the policy is a capability model in the style of a policy engine, with a catalog of what exists, an allowlist of what is permitted, a separate runtime enforcement, and a fail closed default for everything else.

## The runtime stack: MetaHarness, RuVector and RuFlo

The capability table names the components, and the dependency list in the package manifest is where the versions are. The agent runtime is built on the MetaHarness kernel, with host adapters, agent profiles, session replay and an authenticated field memory adapter, and the package manifest pins @metaharness/kernel at 0.1.3 and @claude-flow/cli at 3.25.6. Memory is RuVector, described as private manifest-scoped lexical retrieval with native vector search, with @ruvector/core at 0.1.32 and a platform specific native package, ruvector-core-linux-x64-gnu at 0.1.30, which is a visible reminder that the native memory layer is a Linux x64 binary today. Routing is RuFlo, described as an optional pinned upstream keyword routing hook, which means it is a hook into something else rather than a router the project owns. The Autogenous row is also about not doing too much, with pinned upstream fitness gates and no automatic promotion, so a candidate that passes the gates is not promoted on its own. The protocol side is the Model Context Protocol, with the client and server packages both at 2.0.0, and the server is described as using local stdio, waiting for protocol messages, and explicitly not being a web server or a published npm launcher.

## The quick start, and the platform it needs

The qualified agent runtime requires Linux x64 and Node 24, and the README notes that optional dependency trees are omitted by the repository install configuration, which is why the install step uses ignore-scripts. The quick start is a short list of commands, and it is written to be run in order.

```sh
npm ci --ignore-scripts
node src/cli.mjs templates
node src/cli.mjs compile < fixtures/support-request.json > bot-manifest.json
node src/cli.mjs validate < fixtures/output-request.json
npm test
npm run benchmark
```

The first command installs exactly what is locked, with scripts disabled, the second lists the templates, the third compiles a fixture specification into a manifest, the fourth validates a fixture output against the typed contract, and the last two run the test suite and the benchmark. The manifest is written to a file, which is the point: the artefact is a file you can store, diff and pass to a deployment. The test script in the package manifest is node --test with the test files matched in the test directory, and the benchmark is a subcommand of the same CLI, and the start script runs the MCP server. The other documentation worth knowing about is the host guide, docs/HOSTS.md, which covers installation qualification and scope for Claude, Codex and ChatGPT, and docs/PROMPTING.md, which describes the evaluated contract that the prompts are held to.

## Installing the skill and registering the MCP server

The skill is the piece a host such as Claude Code or Codex reads, and the installer is pinned to a version of the skills tool.

```sh
npx -y skills@1.5.25 add ruvnet/Bot-Generator-Bot --skill bot-generator --agent claude-code codex --copy --yes
npx -y skills@1.5.25 list --json
```

For a reproducible installation the README suggests discovering and installing the local copy from a checkout you have reviewed instead.

```sh
npx -y skills@1.5.25 add ./skills --list
npx -y skills@1.5.25 add ./skills --skill bot-generator --agent claude-code codex --copy --yes
```

The commands use project scope, so Claude Code receives the skill under .claude/skills/bot-generator and Codex under .agents/skills/bot-generator, and you invoke it as a slash command in one and a dollar prefixed command in the other. The README also flags a subtlety that matters for anyone doing this in a regulated setting, that pinning the installer does not pin the GitHub repository revision, so you should keep the reviewed checkout commit when reproducibility matters. The MCP server is registered separately, against an absolute path, and the README is explicit that installing a skill provides guidance only, while the tools become callable once the repository dependencies are installed and the server is registered.

```sh
claude mcp add --transport stdio --scope project bot-generator -- node /absolute/path/Bot-Generator-Bot/src/cli.mjs mcp
codex mcp add bot-generator -- node /absolute/path/Bot-Generator-Bot/src/cli.mjs mcp
```

There is also a configuration file form for hosts that support one.

```toml
[mcp_servers.bot-generator]
command = "node"
args = ["/absolute/path/Bot-Generator-Bot/src/cli.mjs", "mcp"]
```

## What the generated agents are allowed to do

The README draws the boundary of the generated agents explicitly, and it is worth reading before you build anything on top. The migrated skills create drafts, educational assistance and simulations within their stated scope, and they do not claim to deploy APIs, book meetings, send messages, provide licensed professional services or run generated code, and the README says those effects require separately available and authorised host integrations. The 39 original prompts are all preserved, each with a curated typed agent template, an installable skill and a dedicated MCP builder, with the complete catalog in docs/CATALOG.md mapping every original source to its skill and tool. The original text remains unchanged for provenance while modernised contracts define the supported behaviour, and each domain skill carries its own workflow, output schema, demonstration and original source digest. Building one is a single call, with each build tool for a template taking an empty object and returning a validated manifest without calling a model.

```sh
node src/cli.mjs build_business_plan_bot > business-agent.json
```

The other two verbs complete the workflow, with template used to customise a specification before compiling, agent_plan to package a returned manifest, and agent_run for a bounded model task with operator configuration. The catalog is also exposed as a resource under a custom URI scheme, ruv://bot-generator-bot/catalog. Taken together, the shape is a toolchain for producing checked, typed, reviewable agent specifications rather than a chat interface, and the safety story rests on the compile step being offline, the tool policy being fail closed, and the operator grant being enforced separately from the request.

## Conclusion

Adopt this project if you are building agent tooling and want a specification to compile into a checked, digest bearing manifest rather than a wall of prompt text, and if you are willing to run a Linux x64 machine with Node 24 and to review the checkout yourself. It does not fit a team that wants a hosted bot builder, because the runtime, the memory and the routing are local dependencies you install and pin, and it does not fit anyone who expects the generated agents to act on the world, since the migrated skills are explicitly scoped to drafts, educational assistance and simulations. Before you use it, read docs/PROMPTING.md for the evaluated contract, and remember that pinning the skills installer does not pin the repository revision, so keep the reviewed commit yourself.

## FAQ

### What does the second version of Bot-Generator-Bot do?

It turns a bot idea into a runnable MetaHarness agent by choosing a template, defining typed outputs, and exporting a standalone agent or running it through the CLI or MCP. The runtime uses the MetaHarness kernel, native RuVector memory and optional RuFlo routing, with model calls requiring explicit operator configuration and compilation staying offline.

### What does the compiler input look like?

The input is a spec object with name, purpose, context, examples, output and tools, with a complete JSON example in the fixtures directory. Output fields support string, number, integer and boolean, all fields are required, extra fields are rejected, and the limits are a 32 KiB input, 8 KiB strings, 12 levels of nesting and 16 fields in an output schema.

### How are tool requests authorised in Bot-Generator-Bot?

A request has to be in the fixed catalog and in the operator allowlist, and requests never grant authority. Setting BOT_ALLOWED_TOOLS to search locally permits a specification to request the catalog's search tool, and the agent runtime enforces the operator grant separately, with the other catalog tools reserved and failing closed in this runtime.

### How do I install the bot-generator skill and run the CLI?

The quick start needs Linux x64 and Node 24, and runs npm ci --ignore-scripts, then the CLI commands for templates, compile and validate, then npm test and npm run benchmark. The skill is installed with npx -y skills@1.5.25 add ruvnet/Bot-Generator-Bot --skill bot-generator --agent claude-code codex --copy --yes, and the MCP server is registered separately against an absolute path.

### What do the migrated Bot-Generator-Bot skills deliberately not do?

The README states that the migrated skills create drafts, educational assistance and simulations within their stated scope, and that they do not claim to deploy APIs, book meetings, send messages, provide licensed professional services or run generated code, since those effects need separately available and authorised host integrations. The 39 original prompts are kept unchanged for provenance.

## Sources

- [Issues](https://github.com/ruvnet/Bot-Generator-Bot/issues)
- [README](https://github.com/ruvnet/Bot-Generator-Bot/blob/main/README.md)
- [ruvnet/Bot-Generator-Bot on GitHub](https://github.com/ruvnet/Bot-Generator-Bot)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ruvnet-bot-generator-bot