
factoryhub
io.github.Mindburn-Labs/factoryhub
Find, read, validate, export and run AI factories with your own model. Runs stop at human decisions.
Documentation
AI factories, shared.
The open format, engine, command line and MCP server for AI factories:
small teams of AI agents written as plain files that anyone can read, run, change and share.
Quickstart · Docs · Spec · Factories · Integrations · Contributing
What a factory is
A factory turns what a person gives into a finished, checked document. It says who does what, in what order, what gets checked, and where the person decides, in three kinds of plain files:
meeting-to-actions/
factory.yaml name and what it is for
flow.yaml inputs and steps
agents/<name>/agent.md one role per agent
Here is part of a real one, factories/meeting-to-actions/flow.yaml,
with some fields left out and its task texts shortened:
flow: mindburn.flow/v1
title: Meeting to actions
version: "1.1.1"
inputs:
notes:
type: longtext
help: "The meeting notes or transcript, as rough as they are."
steps:
extraction:
title: Extract what was agreed
agent: analyst
kind: work
task: |
Read the notes and pull out four lists. Decisions: ...
followup:
title: Write the follow-up
agent: writer
kind: deliver
needs: [extraction]
task: |
Write the follow-up. Sections, in this order: ...
check_extraction:
title: Check against the notes
agent: reviewer
kind: check
needs: [followup]
checks: followup
task: |
Compare the entire follow-up with the original notes. ...
Steps run in the order their needs allow, in parallel where they can. A
check sends weak work back to be redone. An approve step stops the run
until the person decides; nothing decides for them unless they ask for it
with --yes. Every finished run
writes a receipt: the hash of the factory, every step, every check verdict,
every decision and the deliverable. Concepts explains the
parts; the spec has every field.
Quickstart
You need Node.js 22 or newer and git.
git clone https://github.com/Mindburn-Labs/factoryhub && cd factoryhub
npm ci
npx factoryhub inspect meeting-to-actions
Then run it with your own model key, or a model on your machine:
export ANTHROPIC_API_KEY=... # or OPENAI_API_KEY, or OPENROUTER_API_KEY
npx factoryhub run meeting-to-actions -i notes=@notes.txt
npx factoryhub run meeting-to-actions --provider ollama --model <model>
Make your own with npx factoryhub new my-factory; it validates and runs from
the start. More in the quickstart.
What is in this repository
| Part | What it does |
|---|---|
spec/ | The factory format v1alpha1: a readable specification, JSON Schemas for factory.yaml, flow.yaml and the single-file form, conformance fixtures that test the schemas against the engine, the skill export mapping, and an RFC process. |
packages/engine | The engine with no dependencies: parses a factory, runs its flow on Anthropic or any OpenAI-compatible model, writes and verifies receipts. The factoryhub site runs a copy of this engine. |
packages/cli | factoryhub: list, inspect, validate, run, resume, new, pack, export --as skill, search, get. Reference. |
packages/mcp | A local stdio MCP server: list, read, validate, export and run factories from any MCP client. Runs stop at every decision and resume with the person's answer. Reference. |
factories/ | The house factories, each checked by npm run validate and the CI workflow, with a generated index.json. |
integrations/ | An Agent Skill, a Claude Code plugin, OpenClaw and Hermes Agent skills, MCP client entries, and nine examples for seven agent frameworks. |
The house factories
| Factory | What it does | Inputs required | Steps | Asks you to approve | Web tools |
|---|---|---|---|---|---|
client-file-readiness | Compares what a client sent against your checklist, reports what is missing, from the wrong period or unclear, and drafts the message asking for it. | 3 of 4 | 3 | no | none |
competitor-teardown | Reads your website and up to three competitors, then writes a decision-ready brief showing where you win, where you lose and what to change this week. | 2 of 3 | 5 | no | web_fetch, web_search |
homepage-audit | Reads your home page the way a first-time visitor does and returns a prioritised list of fixes with the exact new wording. | 1 of 3 | 4 | no | web_fetch |
inbox-triage | Sorts a batch of customer messages by urgency and type, drafts a reply to each in your tone, and lists what needs a human decision. | 2 of 3 | 4 | no | none |
launch-kit | Turns a product description into a launch kit with positioning, a landing page draft, a launch email, three follow-ups and posts for social channels, all in one voice. | 2 of 5 | 6 | yes | web_fetch |
meeting-to-actions | Turns rough meeting notes or a transcript into decisions, owned actions with dates, open questions and a follow-up message ready to send. | 1 of 2 | 3 | no | none |
newsletter-note | Writes a short newsletter note, under 120 words, that tells your readers what your new video, podcast or talk is about and points them to it, using only the facts sheet. | 1 of 3 | 2 | no | none |
outreach-pack | Turns checked market research and launch materials into an outreach pack. | 2 of 3 | 3 | no | none |
prospect-brief | Researches one company you want to sell to and writes a one-page brief plus a first email and follow-up that mention real, checkable facts about them. | 2 of 3 | 7 | yes | web_fetch, web_search |
release-desk | Puts the posts, the short-video script and the newsletter note written from one video into a single release packet: the week at a glance, every piece checked against the others and the facts sheet, and every claim listed with the words it rests on, for you to approve once. | 1 of 4 | 3 | yes | none |
short-video-cut | Writes a 30-second script for TikTok, Reels or Shorts and a cut list from the facts sheet of one video, podcast or talk: a hook, three beats and a closing line, each clip with the timestamp and the exact words where it starts and ends. | 1 of 3 | 2 | no | none |
video-facts | Reads the transcript of one video, podcast or talk and writes a facts sheet: every number, result, claim and quote the speaker states, in their own words, with each hedge kept and a timestamp or the first words for each. | 1 of 1 | 2 | no | none |
video-to-posts | Turns the transcript of one video, podcast or talk into a week of posts for X, LinkedIn, a short video and a newsletter, using only what the speaker said. | 1 of 2 | 4 | yes | none |
week-of-posts | Writes an X thread, two single posts and a LinkedIn post from the facts sheet of one video, podcast or talk, in the speaker's voice, saying nothing the facts sheet does not say. | 1 of 3 | 2 | no | none |
Add yours: a factory in five minutes.
Use it from your agent
Each integration is marked with what was actually tested at this commit. "Tested locally" means exercised on a maintainer's machine with the version and result recorded in the status matrix; "documented only" means written from the tool's current docs and not exercised. CI has not run yet, so nothing is marked "tested in CI".
| Where | How | Status |
|---|---|---|
| Claude Code | plugin with the skill and the MCP server | tested locally |
| Gemini CLI | MCP entry | tested locally |
| Codex | MCP entry | tested locally (ran a factory to its approval step) |
| Cursor | MCP entry | documented only |
| VS Code | MCP entry | documented only |
| Claude Desktop | MCP entry | documented only |
| OpenClaw | skill | tested locally (skills-ref validator) |
| Hermes Agent | skill | tested locally (its parser, validator and skills guard) |
| Any agent that reads skills | Agent Skill, or factoryhub export --as skill | tested locally (skills-ref validator) |
| Vercel AI SDK, OpenAI Agents SDK (JS and Python), LangChain (JS and Python), smolagents, Hugging Face, CrewAI, LlamaIndex | framework examples over MCP | listing tools: tested locally; agents: documented only |
Setup for each: docs/integrations.md.
factory.mindburn.org
Mindburn Labs runs a hosted factoryhub at factory.mindburn.org, currently in
private preview. factoryhub search and factoryhub get read its published
catalogue; while the preview lasts they need the access key you were given,
in FACTORYHUB_ACCESS_KEY. Everything else in this repository works without
it.
Contributing
Contributions are welcome: factories, fixes, docs, integrations and format proposals. Start with CONTRIBUTING.md. Changes to the format go through RFCs. The roadmap lists what comes next.
Community
- Code of Conduct
- Governance
- Getting help
- Security: report vulnerabilities privately
- Changelog
License
Apache-2.0. Each factory declares its own license in its
flow.yaml; the house factories declare MIT. The ClawHub skill files in
integrations/openclaw/factoryhub are
MIT-0, as ClawHub requires. See NOTICE.
factoryhubnpm install factoryhub