fabrik-setup

Bootstrapping Fabrik

This skill guides a user through installing Fabrik and standing it up for the first time in their project. Don't run any of these steps yourself unsolicited — walk the user through them, confirm their environment, and let them execute. Authoritative docs live at https://fabrik.handarbeit.io — link the user there rather than reproducing details that may drift.

Before you start

Confirm the user has — or help them obtain — each of these. Don't proceed past step 0 until prerequisites are in place.

1. Claude Code CLI installed and authenticated. They almost certainly have this if they're talking to you, but check with claude --version if uncertain.
2. A GitHub repo and a GitHub Project (v2) board. The board is non-optional — Fabrik is a board orchestrator. If they don't have a Project yet, point them at https://github.com/orgs//projects/new (or the personal equivalent). The board's status column names will need to match the Fabrik stage names later.
3. A GitHub classic personal access token (ghp_...) with repo, project, and workflow scopes. Fine-grained tokens (github_pat_...) are not supported — GitHub Projects v2 GraphQL requires a classic PAT. Create one at https://github.com/settings/tokens (select "Tokens (classic)").
4. gh CLI authenticated (gh auth status) — needed for the binary download path and convenient for many Fabrik workflows.
5. Go 1.26.1+ — only required if they want to build from source instead of downloading a release binary.

If they're missing prerequisites, get them sorted first. Don't paper over a missing PAT with vague instructions; the token type matters and getting it wrong is a common failure mode.

Step 1 — install the binary

Two paths. Strongly prefer the release binary unless the user has a reason to build from source.

Option A — release binary (recommended):

cd ~/bin  # or any directory on PATH
gh release download --repo handarbeit/fabrik \
  --pattern "fabrik_*_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/').tar.gz" \
  -O - | tar xz

Option B — build from source:

git clone https://github.com/handarbeit/fabrik.git
cd fabrik
go build -o fabrik .

Verify with fabrik --version.

Step 2 — initialize the project

From the directory where you want Fabrik to run (typically a sibling to your repo checkouts, not inside one — Fabrik bare-clones repos into .fabrik/repos/ and creates worktrees as siblings):

mkdir ~/my-fabrik-dir && cd ~/my-fabrik-dir
fabrik init --user <github-username> https://github.com/orgs/<org>/projects/<N>

This creates:

• .fabrik/stages/ — stage YAML configs (commit these to git if you want them version-controlled per project)
• .fabrik/plugin/ — the worker-side Claude Code plugin (gitignored; refreshed by fabrik upgrade)
• .fabrik/config.yaml — project config template, populated with values from the Project URL

If the user runs fabrik init without a URL it falls back to interactive prompts, or writes a commented template if non-interactive.

Step 3 — create the .env

Add a gitignored .env next to .fabrik/:

FABRIK_TOKEN=ghp_...

Important: when a .git/ directory is present, Fabrik refuses to start unless .env is listed in .gitignore. This is a token-leak guard, not a bug.

Step 4 — set up the Project board columns

The Project board needs a status column for each stage. The default pipeline expects, in order:

Backlog → Specify → Research → Plan → Implement → Review → Validate → Done

Column names must match name: in the stage YAML files exactly (case-sensitive). On startup, Fabrik validates this and refuses to start if any non-cleanup stage is missing from the board — so it's worth getting right before the first run.

If the user wants a custom pipeline they should edit .fabrik/stages/*.yaml and rename columns to match. This is a deeper customization — point them at the User Guide before going down that road.

Step 5 — first run

cd ~/my-fabrik-dir
fabrik

Fabrik will poll the board every 30s, validate column names against stage YAML, and start dispatching workers when issues land in the Specify column. To kick off the first issue: create one in the repo, add it to the Project, set its status to Specify, and watch.

Useful flags for the first run:

• fabrik --once — single poll cycle, useful for debugging.
• fabrik --verbose — more log detail.
• The TUI dashboard is the default UI; press ? for keybinds.

Compatibility gotcha

Global Claude Code plugins can interfere with worker sessions. The superpowers plugin in particular causes duplicate comments. Check with:

ls ~/.claude/plugins/cache/claude-plugins-official/

If superpowers appears, recommend removing it. This only matters on machines that run Fabrik as a worker host — installing other Claude Code plugins (like this fabrik plugin) for the user's interactive session is fine.

Where to point the user next

Once they're up:

• Authoring an issue Fabrik can act on — switch to the fabrik:fabrik supervisor skill (ambient, will load itself once .fabrik/ exists).
• What labels do — https://fabrik.handarbeit.io/USER_GUIDE#6-labels-reference
• State machine (engine behaviour) — https://fabrik.handarbeit.io/state-machine
• Troubleshooting — https://fabrik.handarbeit.io/troubleshooting

What this skill is not

• Not a runbook for Fabrik in production — auth setup, multi-repo, SSH cloning, observability all live in the User Guide. Point users there when they ask.
• Not for users who already have .fabrik/ — if .fabrik/ exists, Fabrik is already initialized; the user wants the supervisor skill, not setup. If they're trying to re-init or upgrade, point them at fabrik upgrade rather than re-running fabrik init.