agentleFS
xaedalonxaedalon/factory-community/skills/factory-setup/SKILL.md

factory-setup

Skill2 starsChanged 53 days agoApache-2.0View on GitHub

Install Xaedalon Factory on this machine and leave it running — prerequisites, build, user scope, daemon, and a board that answers. Use when the user asks to install, set up, or get Factory working, or invokes /factory-setup. Not for using Factory once it runs (that is `factory setup`, `factory doctor`, and the board).

  • Installs packages

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Check, report, and only then fix — and say what you are installing before you install it.

    line 75
  2. Very specific:

    Node older than 24, or missing: Do not silently install a Node.

    line 83
  3. Very specific:

    If the current directory is already a checkout of factory-community (it has PROJECT.md and pnpm-workspace.yaml), use it and say so.

    line 94
  4. Very specific:

    If that file is absent, run pnpm --filter @factory/web build and report it — the root build is supposed to cover it.

    line 120
  5. Distinctive:

    Start it detached, so it survives the shell you started it in:

    line 148
  6. Distinctive:

    Wait for it, then check both halves:

    line 170
  7. Very specific:

    If they want factory on their PATH rather than node apps/cli/dist/bin.js:

    line 195
  8. Very specific:

    Add a repository on the Projects page, or factory project … from the terminal.

    line 215
  9. Very specific:

    Import the example pipeline if factory setup offered it, or build a workflow in the browser.

    line 216

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “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
SKILL.md

Setting up Factory

You are installing Xaedalon Factory for the person you are talking to, on the machine you are running on, and leaving it working. Factory is one Node process plus a SQLite file; there is no service to register and nothing to configure before the first run.

This runbook is written for any coding agent. The command sequence below is the same one the project's own first-run CI job executes on every commit, so if a step here fails on a supported platform, that is a bug worth reporting rather than something to work around.


Rule one: say what you are about to do, then do it

Before running anything, tell them in plain language — short, no jargon, no list of internal detail:

I'll set up Factory here. In order: check you have Node 24+, pnpm and git; clone the repository into <the directory you propose>; install its dependencies and build it; create your Factory scope at ~/.xaedalon/.factory; start the local daemon on 127.0.0.1:7317; then confirm the board answers and tell you what is left to do.

It installs nothing globally, changes nothing outside that directory and your home scope, and never reaches the network except to fetch the repository and its npm dependencies. I will not start any agent or accept Factory's security notice for you — both are your call.

Name the actual directory you intend to use, and ask before choosing one they did not mention. Then proceed without further prompting unless something below says to stop.

Rule two: three things are theirs to decide, not yours

  1. Never accept the security disclaimer. Factory refuses to start an agent until somebody has read what an agent run can reach. Show them factory accept --show at the end and leave it.
  2. Never queue a task or run a workflow as part of setup. Setup ends with a working installation, not with an agent editing their code.
  3. Never install a coding-agent CLI (Claude Code, Codex, Copilot) without asking. Report which are present and let them choose.

1. Platform

Work out which of three situations you are in, and say which.

macOS or Linux — proceed directly.

Windows — everything must happen inside WSL2. This is not a preference: every shell step Factory runs is bash -c '…', and stopping work signals a POSIX process group. Neither exists on native Windows, so a "successful" native install would fail the first time it ran or stopped anything.

wsl --status
wsl -l -v            # a distribution, "Version 2", and ideally "Running"
  • A WSL2 distribution exists → run every remaining command inside it (wsl -d <name> -- <cmd>, or tell them to open their WSL shell and continue there). Install into the Linux filesystem, e.g. ~/factory, not /mnt/c/... — a repository on the Windows drive makes Node and git slow enough to look broken.
  • No WSL2 → stop and say exactly this: Factory needs WSL2 on Windows. Run wsl --install in an administrator PowerShell, reboot, then ask me again. Do not attempt a native install, and do not install WSL for them without asking — it requires a reboot.

The board is reachable from a Windows browser at http://127.0.0.1:7317 once the daemon runs inside WSL2.

2. Prerequisites

Check, report, and only then fix — and say what you are installing before you install it.

node --version      # must be >= 24. The store uses node:sqlite.
git --version
corepack --version
  • Node older than 24, or missing. Do not silently install a Node. Ask, and prefer their existing manager if you can see one (nvm, fnm, asdf, volta, brew, apt). nvm install 24 && nvm use 24 is the usual answer on macOS and Linux. Node 24 is a hard floor, not a recommendation: on anything older, import 'node:sqlite' throws and the daemon cannot start.
  • pnpm. corepack enable pnpm is enough — the exact version is pinned in the repository's packageManager field and corepack fetches it. Do not npm i -g pnpm.
  • git missing. macOS: xcode-select --install. Debian/Ubuntu: sudo apt-get install -y git. Ask first.

3. Get the repository

If the current directory is already a checkout of factory-community (it has PROJECT.md and pnpm-workspace.yaml), use it and say so. Otherwise:

git clone https://github.com/xaedalon/factory-community.git ~/factory
cd ~/factory

Propose ~/factory unless they have said where they want it. On Windows this must be a WSL path.

4. Build

corepack enable pnpm
pnpm install
pnpm build

pnpm build produces three things: the engine and daemon, the factory CLI, and the board the daemon serves from the same process. Confirm the third exists, because it is the one that used to be missing:

test -f apps/web/dist/index.html && echo "board built"

If that file is absent, run pnpm --filter @factory/web build and report it — the root build is supposed to cover it.

5. Create their scope

node apps/cli/dist/bin.js init --scope user

--scope user is deliberate. Without it, init inside a git repository creates a project scope in that repository — right for a repository's own workflows, wrong for a first run, because their definitions would then live inside a checkout they will later pull or delete.

This writes config.yaml, workflows/ and phases/ into their user scope. Report the path it prints rather than assuming one, and if you need it later, ask:

node apps/cli/dist/bin.js config path

Usually that is ~/.xaedalon/.factory. It is ~/.factory on a machine that was set up before the directory was renamed and never migrated: the resolver prefers ~/.xaedalon/.factory, falls back to ~/.factory when only that exists, and an explicit FACTORY_HOME beats both (packages/config/src/scopes.ts). Somebody with an older installation who is told their definitions are in the new place will think they have lost them.

6. Start the daemon and prove it answers

Start it detached, so it survives the shell you started it in:

mkdir -p logs
node apps/daemon/dist/bin.js > logs/daemon.log 2>&1 &
echo $! > logs/daemon.pid

Inside the checkout, which is already git-ignored — not ~/.factory. That path is not a scratch directory: on an installation set up before the scope directory was renamed it is the user's live scope, holding their config.yaml, settings.json and history, and writing a log into it is at best untidy. On a machine with neither directory, creating it would leave something that looks like a legacy scope for the resolver to find later.

The mkdir is still load-bearing: the shell's redirect happens before anything else, so a missing directory fails the command and starts no daemon. Both of these were found by running this runbook for real — the first against an empty home, the second by an agent that read the fallback in scopes.ts and refused to write where it was told to.

On Windows-in-WSL, the same command inside the WSL shell. If they would rather run it in the foreground in their own terminal, say so and let them — then skip to the checks below once it is up.

Wait for it, then check both halves:

curl -sf http://127.0.0.1:7317/api/health     # {"ok":true,...}
curl -sf http://127.0.0.1:7317/ | head -c 40  # the board's HTML
  • Health answers, / returns a page saying the board is not built → the build skipped the web bundle. pnpm --filter @factory/web build, then reload.
  • Nothing answers on 7317 → read logs/daemon.log. If the port is taken by something else, start it on another with FACTORY_PORT=7417 and use that port everywhere afterwards.
  • EADDRINUSE and the log says a Factory is already listening → they already have one running. Say so; do not start a second.

7. Ask Factory what is left

node apps/cli/dist/bin.js setup

This is Factory's own answer, not yours: it lists what is missing and the command that fixes each thing, and it asks the provider plugins rather than guessing. Relay it as it stands. Expect it to report which coding-agent CLIs it found — Factory runs the CLI they already have and never installs one.

If they want factory on their PATH rather than node apps/cli/dist/bin.js:

pnpm --filter @factory/cli link --global

Offer it; do not do it unasked, since it writes into their global pnpm directory.

8. Hand it over

Report, briefly and concretely:

  • the board: http://127.0.0.1:7317
  • where things are: the checkout, the scope path config path printed for definitions, and <that scope>/state/factory.db for what happened — both read back rather than assumed
  • how to stop it: factory stop --all stops every agent and cancels its task; killing the daemon process stops the daemon
  • what is theirs to do next, in this order:
    1. factory accept --show — read what an agent run can reach, then factory accept. Nothing will run until they do, and that is on purpose.
    2. Add a repository on the Projects page, or factory project … from the terminal.
    3. Import the example pipeline if factory setup offered it, or build a workflow in the browser.
  • anything you could not finish, named plainly.

Then stop. Do not create a project, do not create a task, and do not queue anything.


If they already have Factory

Say so rather than reinstalling. Verify and repair instead:

git -C <checkout> pull
pnpm install
pnpm build
node apps/cli/dist/bin.js doctor      # what the installation thinks is wrong

A daemon started before an upgrade is running the old code: tell them to restart it, and never restart one that is mid-run without asking — factory task list shows whether anything is running.

What this deliberately does not do

  • It does not make Factory start at login. There is no service or launch agent; a tool that runs coding agents against repositories should start when somebody starts it.
  • It does not open any port other than loopback. Nothing here listens on 0.0.0.0, and if they ask for that, point them at the security documentation first.
  • It does not configure a provider's credentials. Factory never asks for an API key; it runs the agent CLI they have already authenticated.
  • It does not set the execution profile. Default is the profile every project gets; Full Access removes the workspace boundary and is their explicit choice, per project.

Reference

Inside the checkout: docs/install.md for requirements and where things live, docs/quickstart.md for the first task, docs/security/default-profile.md for what an agent may reach, and PROJECT.md for why any of it is shaped this way.

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.