factory-community
AGENTS.md2 starsChanged 53 days agoApache-2.0View on GitHub
Factory orchestrates coding agents, and it is built by them. This file is the entry point for any agent that reads AGENTS.md — Codex among them. Read skills/factory-setup/SKILL.md and follow it exactly. That file is the only copy of the install runbook. Claude Code finds it through .claude/skills/factory-setup/SKILL.md, Copilot through .github/prompts/factory-setup.prompt.md and .github/copilot-instructions.md, and you through this line. Three pointers, one set of steps: a fix to the install path is a fix for every agent, which is the same…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- factory-mcp-installSkill
- factory-mcp-uninstallSkill
- factory-setupSkill
- factory-uninstallSkill
- factory-mcp-installSkill
- factory-mcp-uninstallSkill
- factory-setupSkill
- factory-uninstallSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Read skills/factory-setup/SKILL.md and follow it exactly.
- Distinctive: line 53
Every guard is broken and watched to fail: before it is trusted — invert the condition, run the suite, watch the right scenario fail, …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agents working in this repository
Factory orchestrates coding agents, and it is built by them. This file is the entry point for any
agent that reads AGENTS.md — Codex among them.
Installing Factory
Read skills/factory-setup/SKILL.md and follow it exactly.
That file is the only copy of the install runbook. Claude Code finds it through
.claude/skills/factory-setup/SKILL.md, Copilot through .github/prompts/factory-setup.prompt.md
and .github/copilot-instructions.md, and you through this line. Three pointers, one set of steps:
a fix to the install path is a fix for every agent, which is the same rule the codebase holds itself
to — one implementation of one idea.
Two of its rules before you begin: explain the whole plan to the person before running anything, and never accept Factory's security disclaimer for them. Nothing runs until a human has read what an agent run can reach, and that gate exists for every client, including you.
Driving Factory
Factory serves the Model Context Protocol, so you can operate it rather than only install it:
resolve the project you are standing in, see what it can run, create a task, queue it, follow the
run. Point your client at factory mcp and read docs/mcp.md.
Two things it will not let you do, before you try: it will not accept the security disclaimer — that is a person's, and the refusal says so — and it will not approve anything, because an approval an agent can give itself is not a gate.
Setting that up is a runbook of its own:
skills/factory-mcp-install/SKILL.md. It asks one question
before it writes anything — everywhere on this machine, or only in one repository — and defaults to
everywhere. A repository install writes a .mcp.json that will appear in somebody's git status,
which it says before writing rather than after.
skills/factory-mcp-uninstall/SKILL.md is the other
direction, and removes no Factory data at all.
Removing Factory
Read skills/factory-uninstall/SKILL.md and follow it exactly.
Its default is to remove the software and keep the data: a checkout and a global shim are Factory's,
but the scope holds somebody's history and a repository holds their committed definitions and the
artifacts their agents wrote. Name the command for those and leave them alone.
Changing this repository
CONTRIBUTING.md is the real answer and is short. The three rules that decide
whether a change is acceptable, none of them guessable:
- The
.featurefiles are the specification. A behaviour change begins with a scenario, in the language of the problem rather than the implementation. There are no separate spec documents and there never will be. - Every guard is broken and watched to fail before it is trusted — invert the condition, run the suite, watch the right scenario fail, restore. A test that has never failed is a test nobody has checked. Say in the pull request which mutations you ran.
- One implementation of one idea. The recurring failure here is two implementations where the
wrong one is the one nobody reads. Every path flows from
packages/config/src/scopes.ts;process.cwd(),os.homedir()andos.tmpdir()are banned elsewhere by lint. The open core never imports commercial code — widen@factory/plugin-sdkinstead.
Before you push
pnpm typecheck && pnpm lint && pnpm test
pnpm --filter @factory/web test:e2e # if the board changedCI runs the suite on macOS and Linux, the browser scenarios in Chromium, and a first-run job that clones, builds and asks the daemon for a page. Running them locally first is faster than finding out from a red tick.
Where to read next
PROJECT.md is the decision record — every increment, what it cost, and what was
refused. It is long, and it is the fastest way to understand why anything here is shaped the way it
is. docs/ is short and worth reading end to end.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

