agentleFS
xaedalonxaedalon/factory-community/AGENTS.md

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…

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
  1. Very specific:

    Read skills/factory-setup/SKILL.md and follow it exactly.

    line 8
  2. Distinctive:

    Every guard is broken and watched to fail: before it is trusted — invert the condition, run the suite, watch the right scenario fail, …

    line 53

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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:

  1. The .feature files 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.
  2. 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.
  3. 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() and os.tmpdir() are banned elsewhere by lint. The open core never imports commercial code — widen @factory/plugin-sdk instead.

Before you push

pnpm typecheck && pnpm lint && pnpm test
pnpm --filter @factory/web test:e2e     # if the board changed

CI 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.