Fabrik

Automated Claude Code SDLC driver powered by GitHub Issues and Projects.

Fabrik watches a GitHub Project board and drives Claude Code through configurable
workflow stages. Issues are the unit of work — the issue body is the spec, comments
are user input, and the board columns define the workflow.

📖 Documentation, guides, and examples → fabrik.handarbeit.io

Quick Start

Requires Go 1.26.1+, the Claude Code CLI, and a GitHub token with repo and project scopes.

# Install
go install github.com/handarbeit/fabrik@latest

# Initialize stage configs, plugin, and project config template
# Pass your GitHub Project URL to auto-populate owner, project, and owner_type:
fabrik init --user you https://github.com/orgs/your-org/projects/5
# Or run without a URL for full interactive prompts (TTY) / blank template (non-TTY)
fabrik init
# Creates .fabrik/stages/, .fabrik/plugin/, and .fabrik/config.yaml

# Edit .fabrik/config.yaml with your project settings (commit this file)
# Add your GitHub token to a gitignored .env:
echo 'FABRIK_TOKEN=ghp_...' >> .env
echo '.env' >> .gitignore

# Run (settings come from .fabrik/config.yaml)
fabrik

# Or override specific values with flags
fabrik --stages ./.fabrik/stages --yolo

Configuration summary:

• .fabrik/config.yaml — non-secret project settings (commit to git)
• .env — secrets only (FABRIK_TOKEN / GITHUB_TOKEN; must be gitignored)
• Precedence: CLI flag > env var > .env > config.yaml > defaults

Auto-upgrade

Use --auto-upgrade to have Fabrik self-upgrade at startup and when idle:

fabrik --auto-upgrade ...

At startup and after 2 idle polls, Fabrik upgrades itself automatically and re-execs:

• Release binaries: checks GitHub Releases for a newer version and downloads it.
• Dev builds (built from source via go build): detects local or remote commits
  ahead of the running binary and rebuilds in place from origin/main.

When Fabrik is upgraded, it also compares your .fabrik/stages/*.yaml files against the embedded defaults and prints a startup warning for any stage file that is missing fields added in the newer binary. Run fabrik refresh-stages --apply to add the missing keys, then review with git diff and commit. See Stage YAML Drift Warning in the User Guide for details.

Fabrik PM Plugin (Claude Code Companion)

Don't want to install the binary yet? You can still get value from Fabrik by installing the Fabrik PM plugin in your interactive Claude Code session. It gives Claude ambient awareness of your Fabrik-managed project so you can ask things like "what's on the board?", "why is #42 stuck?", or "what's in progress?" without leaving your editor.

Run these in any Claude Code session:

/plugin marketplace add handarbeit/fabrik
/plugin install fabrik@fabrik
/reload-plugins

After install you get:

• fabrik:fabrik skill — auto-activates when .fabrik/ is detected or Fabrik is mentioned. Provides ambient PM awareness of the board, stages, and stuck items.
• fabrik:fabrik-setup skill — one-time onboarding walkthrough for setting up Fabrik from scratch.
• /fabrik:status command — board snapshot: what's in each pipeline stage, which workers are running, which worktrees have uncommitted changes.

The PM plugin is independent of the engine — install it on its own to chat about a Fabrik-managed repo, or pair it with the binary for the full experience. See Install the Fabrik PM Plugin in the User Guide for details and upgrade instructions.

Distinct from fabrik-workflows: the engine's stage skills are embedded in the binary and deployed automatically to .fabrik/plugin/ by fabrik init. You do not — and should not — install fabrik-workflows manually.

How It Works

GitHub Project Board (source of truth)
        | GraphQL poll
    Fabrik (Go CLI, runs locally)
        | stage config match
    Claude Code (invoked per stage, in isolated worktree)
        | output
    GitHub Issue comments + labels + body updates

1. Poll — Fabrik fetches the entire project board via a single GitHub GraphQL query.
2. Match — Each issue's board status is matched to a stage config (YAML file).
3. Worktree — An isolated git worktree is created for each issue (fabrik/issue-N branch).
4. Invoke — Claude Code runs in the worktree with the stage's prompt, model, and tool configuration.
5. Complete — When Claude signals completion, the issue is labeled stage:<name>:complete.
6. Advance — In yolo mode, the issue auto-advances to the next stage. Otherwise, a human moves it.

Big-board efficiency (v0.0.57): On large project boards, the per-poll GraphQL cost drops ~5–10× via a lightweight updatedAt-only probe that gates the full deep-fetch — only items that changed since the last poll trigger a full query. Terminal items (issues in a cleanup/Done column with stage:<name>:complete and no active lifecycle labels) are skipped entirely from both the probe and deep-fetch evaluation.

Cold-start optimization (v0.0.58): On startup, closed Done items are seeded from probe data as terminal without a deep-fetch, reducing cold-start GraphQL cost by ~80–90%. Combined with probe-driven polling, this makes running two Fabrik instances on a single token budget practical.

Webhook Mode (Optional)

Fabrik can receive GitHub events in near-real-time (within ~2 seconds) instead of waiting for the next poll tick by spawning gh webhook forward as a background subprocess. Enable with --webhooks. With the default in-memory board cache active, the webhook stream also drives a reconcile-based health check (default every 3 minutes) that reduces full-board polling to at most once every 60 minutes.

Single-user constraint: GitHub allows only one active gh webhook forward subscription per repository or organization at a time. Coordinate across your team so only one Fabrik instance runs with --webhooks; other instances can run without it and will still process issues via polling. See §10 of the User Guide for full setup, configuration, and troubleshooting details.

Merge Train & Merge Queue (Optional)

On a repo with strict branch protection, landing several ready PRs serially produces an O(N²) rebase-and-retest cascade — each merge invalidates every other ready PR's "up-to-date + green" status, forcing a rebase and a full required-check re-run before the next one can land. Fabrik solves this by batching ready PRs and validating the combined result once instead of retesting each one against every prior merge.

Two landing engines share one Queued board column, and Fabrik picks per repo:

• GitHub's native merge queue (ADR-058) — used automatically when the repo has one enabled (Enterprise Cloud or org-owned public repos). Kill-switch: --merge-queue off.
• Fabrik's internal merge train (ADR-059) — the plan- and host-agnostic fallback for private Team and personal-account repos where GitHub's native queue isn't available. It stages a trial branch per repo, runs one combined Validate, and lands the batch atomically; a red batch is isolated via halving bisection so a single poisoner doesn't block the rest. It is opt-in via --merge-train on, FABRIK_MERGE_TRAIN=on, or merge_train: on in .fabrik/config.yaml.

Native queue routing defaults to auto (it only engages on repos where GitHub's native queue is already enabled); the merge train defaults to off. Both leave the existing serial auto-merge path untouched unless explicitly turned on. See Merge Queue and Merge Train / Queued in the User Guide for setup (including the required Queued board column) and tuning knobs.

Comment Processing

When anyone comments on an issue in an active stage:

1. Fabrik reacts with :eyes: to each new comment (marks as "in review")
2. Adds fabrik:editing label to lock the issue
3. Invokes Claude with a stage-specific comment review prompt
4. Claude performs any requested actions (e.g., linking PRs, running commands)
5. If the issue body needs updating, parses the updated body from Claude's output
6. Updates the issue body on GitHub (or posts output as a comment)
7. Removes fabrik:editing label
8. Reacts with :rocket: to each processed comment (also used to skip already-processed comments on restart)

Comments from all authors trigger processing — human colleagues, code-review bots
(Copilot, Gemini), and other Fabrik instances alike. Only two categories are skipped:
comments that start with 🏭 **Fabrik (Fabrik's own output) and comments that already
carry a 🚀 rocket reaction (already processed).

This allows iterative refinement — comment to answer questions, provide feedback,
or steer the work, and Fabrik incorporates the input into the issue.

Review and Fix

Stages with post_to_pr: true (like the default Review stage) post detailed
output on the linked PR and a brief summary on the issue. The Review stage
also rebases onto the configured base branch and resolves merge conflicts before reviewing,
keeping the PR branch clean.

The Review and Validate stages ship with wait_for_reviews: true enabled by
default. When this option is set, Fabrik uses a three-phase reviewer gate
(re-invocation fires unconditionally; auto-advancement to the next stage still
requires auto-advance to be active):

1. Always-gate: On stage completion, Fabrik adds fabrik:awaiting-review
   and holds auto-advance until the gate clears.
2. Gate evaluation: On each subsequent poll, Fabrik checks the dual
   condition: no requested reviewers are outstanding and at least one
   review has been submitted (this catches bot reviewers like Copilot and
   Gemini that self-trigger via webhook without appearing in the formal
   reviewer list). If the condition isn't met and the per-cycle timeout
   expires, the issue pauses with fabrik:awaiting-input.
3. Re-invocation: When the gate clears and there are unresolved PR
   review thread comments, Fabrik re-invokes the stage agent to address that
   inline feedback and push a new commit, then waits for the next review
   round. Reviews with no inline thread comments—including reviews with only
   top-level review text (for example, bot approvals or summary-only
   comments)—do not trigger re-invocation, and the issue advances normally.
   After each re-invocation cycle, Fabrik posts a PR summary comment with a
   per-thread footer listing how each inline review thread was addressed.

Configuration: --max-review-cycles / FABRIK_MAX_REVIEW_CYCLES (default 5)
caps the number of re-invocation cycles per session. --review-wait-timeout /
FABRIK_REVIEW_WAIT_TIMEOUT (default 15 minutes) sets the per-cycle wait before
pausing. The env var is only consulted when the corresponding CLI flag is absent; if
--review-wait-timeout=0 or --max-review-cycles=0 is explicitly passed, the
built-in default is used and the env var is bypassed. See
USER_GUIDE.md §10 for details.

The Validate stage also ships with wait_for_ci: true enabled by default. Fabrik gates auto-advance and, when applicable, auto-merge on CI checks passing; if checks fail, it re-invokes the stage agent with a structured CI-fix report to address new-regression failures. Non-required check_run failures do not block the gate — Fabrik trusts GitHub's mergeable_state as the authoritative merge-readiness signal, so only failures that branch protection itself considers blocking will prevent auto-merge.

If a stage doesn't complete (e.g., unfixable issues found), it retries after
a cooldown period rather than being permanently skipped.

Steering with Comments

Fabrik responds to natural language. Comment on an issue to steer the work:

• "Please link the PR to this issue" — Claude performs the action
• "Please process PR feedback on PR #18" — Claude reads the PR reviews and fixes the code
• "Let's use approach B instead" — Claude updates the plan accordingly

Each stage sees the full conversation history — previous stage outputs, user
comments, and all — so context carries forward through the pipeline.

Awaiting Input Notifications

When a stage needs user input (FABRIK_BLOCKED_ON_INPUT), Fabrik posts a
🏭 **Fabrik** — @<user>: comment so GitHub delivers a mobile push notification
to the configured operator. For pushes to arrive, Fabrik must run as a different
account than the user being @mentioned — see
USER_GUIDE.md §Stages Waiting for Input
for setup details and the self-mention caveat.

In-Place Restart

Sending SIGHUP to the Fabrik process drains in-flight Claude runs, then
re-execs the binary in place — no terminal disruption, no lost state. Use it
to pick up a new binary after go install without restarting the session.
The terminal alt-screen is properly restored on signal-driven exit, so no
reset is needed after a SIGINT, SIGTERM, or SIGHUP. Plugin-skills are checked and
refreshed non-interactively during restart when no local customizations are detected —
the process never hangs waiting for a prompt. When local customizations are present,
the refresh is skipped to preserve your edits and the [u] custom workflow badge
appears on next TUI startup instead, so operator customizations are never silently
overwritten. See
USER_GUIDE.md §Recovering from Wedged State
for the full escape-hatch procedure.

Default Pipeline

The example stages implement a full SDLC pipeline:

Stage Configuration

Each stage is a YAML file in your stages directory:

name: Research            # Must match a Project board column name
order: 1                  # Processing order (lower = earlier)
skill: fabrik-research    # Plugin skill (recommended; alternative to inline prompt)
prompt: |                 # Inline prompt (used when skill is not set)
  You are a research agent...
comment_skill: fabrik-research-comment  # Skill for comment review (overrides comment_prompt)
comment_prompt: |         # Inline comment-review prompt (used when comment_skill is not set)
  You are reviewing user comments...
model: sonnet             # Optional: claude model to use
max_turns: 50             # Optional: max conversation turns per stage invocation
comment_max_turns: 15     # Optional: max turns when processing user comments (default: min(max_turns,15))
read_only: false          # Optional: stash/restore worktree; use for analysis stages (Specify, Research)
post_to_pr: true          # Optional: post output on linked PR instead of issue
create_draft_pr: true     # Optional: push branch and create draft PR before Claude runs
mark_pr_ready_on_complete: true  # Optional: mark PR ready after stage completes
auto_advance: false       # Optional: override global yolo setting for this stage
                          #   true = always auto-advance; false = never; omit = inherit yolo
cleanup_worktree: false   # Optional: remove worktree instead of invoking Claude (terminal stages)
disable_adaptive_thinking: true  # Optional: disable Claude Code's adaptive thinking budget (default: true)
effort_level: high        # Optional: Claude thinking effort: low, medium, high, max (default: high)
allowed_tools:            # Optional: replaces the default tool set — not additive
  - Read
  - Grep
  - Glob
completion:
  type: claude            # "claude" (default and only supported type)

Permission Posture

Every Claude Code invocation receives --permission-mode dontAsk and an explicit --allowedTools list. Tools outside the allowed set are silently denied — no interactive prompts. This means Fabrik works correctly in headless and shared environments without requiring users to pre-configure permissions in ~/.claude/settings.json.

When a stage omits allowed_tools, Fabrik uses a built-in default covering file operations, git, GitHub CLI, common build systems, and shell utilities. See §7 Permissions in the User Guide for the full list.

When allowed_tools is set, it replaces the default set entirely — it is not additive. Only the listed tools are permitted for that stage.

The fabrik:unrestricted label bypasses this posture entirely, passing --dangerously-skip-permissions instead. Use only when a stage needs tools outside the default set.

Configuration

Fabrik resolves settings in this order (highest to lowest priority):

CLI flag  >  shell env var  >  .env file  >  .fabrik/config.yaml  >  built-in default

Run fabrik init to generate .fabrik/config.yaml in your project. This file holds
all non-secret project settings and should be committed to git. See the
Configuration Reference in the User
Guide for a full field-by-field description with examples and defaults.

Secrets (GitHub tokens) belong in a gitignored .env file only:

# .env (gitignored — keep secrets here)
FABRIK_TOKEN=ghp_...    # Preferred
GITHUB_TOKEN=ghp_...    # Fallback

Safety: When a .git/ directory is present, Fabrik refuses to start if .env exists but is not listed in .gitignore (prevents accidental token leaks). In directories without .git/ — containers, CI workspaces, or bare directories — this check is skipped and .env is loaded normally.

Flags

Prerequisite for yolo auto-merge: GitHub's allow_auto_merge setting must be enabled on the repository before Fabrik can enable native auto-merge on yolo PRs. Enable it under Settings → General → Pull Requests → "Allow auto-merge", or run:

gh api -X PATCH repos/{owner}/{repo} -F allow_auto_merge=true

Fabrik emits a [startup] WARNING if this setting is disabled on any managed repo.

Releases: New releases are announced in the handarbeit/fabrik Discussions "Announcements" category after each successful release.

Subcommands

Built-in Skills

Fabrik ships two user-invocable Claude Code skills (type /skill-name in any Claude Code session in the Fabrik repo):

Operator customizations to built-in skills are protected — upgrades detect local edits and offer guided reconciliation rather than silently overwriting. See Upgrade protection for customized skills.

The main Fabrik dashboard (enabled by default; disable with --notui) shows a live turn counter ([N/M turns]) for each active job in the In Progress pane.

fabrik watch

Monitor a single issue in real time without running the engine:

fabrik watch 42
# or with explicit credentials if not in .fabrik/config.yaml:
fabrik watch 42 --owner myorg --repo myrepo

The watch TUI displays: issue title and labels, live Claude output (streamed from the log file), stage history with duration and cost, linked PR status, CI check results, and comment count. Press i to open an interactive Claude session in the issue's worktree (resumes the current stage's session). Press q to exit.

Labels

Fabrik uses labels to track state:

Multi-User

Multiple people can run Fabrik against the same project board. Stage work is scoped
to each instance's --user — an instance only picks up and runs stages for issues
locked to its configured user. Comment processing, however, is any-author: comments
from colleagues, bots, and other Fabrik instances all trigger processing regardless
of who wrote them. Labels provide lightweight locking to prevent conflicts.

Git Worktrees

Fabrik always bare-clones each managed repository on first access. Run Fabrik from any directory — no need to be inside a git checkout of a managed repo:

1. Repos are discovered lazily from project board items
2. Each repo is bare-cloned to .fabrik/repos/<owner>-<repo>.git on first access
3. Each issue gets an isolated worktree at .fabrik/worktrees/<owner>-<repo>/issue-N/ on branch fabrik/issue-N
4. One worktree manager per discovered repository handles its own lifecycle

This means:

• Multiple issues can be worked on simultaneously without conflicts
• Each issue's changes are on their own branch, ready for PR
• Worktrees persist across polls for Claude session continuity

mkdir my-fabrik-dir && cd my-fabrik-dir
fabrik init
fabrik --owner myorg --project 5 --user me
# Fabrik bare-clones each repo as needed into .fabrik/repos/

Omitting --repo (or leaving repo: commented out in .fabrik/config.yaml) enables multi-repo mode — Fabrik processes all repos discovered on the board. Pass --repo owner/repo to restrict processing to a single repository.

.fabrik/repos/ is gitignored by default — bare clone directories are large and should not be committed.

SSH vs HTTPS

By default, Fabrik bare-clones repos using HTTPS. To use SSH instead ([email protected]:<owner>/<repo>.git), pass --ssh or set git_ssh: true in .fabrik/config.yaml. The FABRIK_GIT_SSH=true environment variable is also supported.

If no git credential helper is configured, Fabrik prints an advisory warning at startup (non-fatal) directing you to configure one or switch to SSH. Existing bare clones are not re-cloned when you change this setting — only new clones are affected.

See USER_GUIDE §3 — Git Clone Protocol (HTTPS vs SSH) for full details.

Formations

Fabrik supports dependency-based sequencing of issues using GitHub's native "Blocked by" relationships. A formation is a coordinated set of issues that execute in parallel where possible and respect ordering constraints automatically — no polling, no manual unblocking.

When all blocking issues are closed, Fabrik guarantees re-evaluation of a blocked issue within ~10× the poll interval (~5 minutes at default settings), then resumes it automatically once dependencies are satisfied. The fabrik:blocked label is managed entirely by the engine (created on first use, no pre-creation needed). The first stage (Specify) always runs regardless of blockers, so an entire formation can be fully specified before execution begins.

Recipe: file issues → add blocked-by edges in GitHub → label all fabrik:yolo → move to Specify → watch it run.

Plan can also decompose an oversized issue autonomously. It emits FABRIK_SPAWN_CHILD_BEGIN/END blocks in its output declaring each sub-issue to create; when the parent advances to Implement, the engine's preImplement step creates each child issue in its target repo, adds it to the board, and links it as a blockedBy dependency of the parent. The sub-issues then flow as a formation automatically.

Validated on the Ambient project: 9 issues, 4 parallel starts, 7 dependency edges — all pipeline constraints respected automatically, ~88 minutes wall-clock, $31 total cost.

See the USER_GUIDE §3 — Dependency-Based Sequencing (Formations) for the full recipe, diagram, and behavior callouts.

When an issue reaches Done, it remains on the board in the Done column. Auto-archive is currently disabled — it was removing items from the board before users could see them. It will be re-enabled once the timing logic is reworked to track actual Done stage completion time.

The Self-Evolving Factory

Fabrik is used to develop Fabrik. Issues filed against this repo go through
the same Specify → Research → Plan → Implement → Review → Validate pipeline that Fabrik
orchestrates. When we filed an issue to add PR comment processing, Fabrik
researched its own codebase, planned the GraphQL changes, and will eventually
implement the feature that lets it read PR comments — gaining a capability it
needs by building it for itself. Ouroboros-as-a-service.

The human's role is product manager, architect, and UX designer all in one:
file issues, answer questions when the Research stage surfaces them, drag cards
across the board, and occasionally comment "please process PR feedback" when
Copilot has opinions. The factory does the rest.

Migration from ./stages

If you used Fabrik before v0.2, your stage configs were in ./stages (the old default)
or ./stages/mystages/ if you used that convention.

mkdir -p .fabrik/stages
# If you used the default ./stages path:
cp ./stages/*.yaml .fabrik/stages/
# If you used ./stages/mystages/:
cp ./stages/mystages/*.yaml .fabrik/stages/
# Or keep the old path by setting FABRIK_STAGES in your .env:
# FABRIK_STAGES=./stages

Documentation

• User Guide — full configuration reference for the pre-v0.2 ./stages workflow (see "Quick Start" and "Migration from ./stages" above for the current ./.fabrik/stages default), workflow patterns, stage details, labels, and troubleshooting
• State Machine — authoritative spec for engine state transitions, label semantics, and review gate behavior
• Troubleshooting — common issues: plugin conflicts, PID lock, merge conflicts, max turns, and more

Architecture Decision Records

See adrs/ for documented decisions and their rationale. Of particular note:

• ADR-058: GitHub Merge Queue Integration — native queue auto-detection and routing, killing the O(N²) rebase-and-retest cascade on queue-enabled repos.
• ADR-059: Fabrik-Internal Merge Train — the plan/host-agnostic batched-landing fallback for repos where GitHub's native queue is unavailable.

Requirements

• Go 1.26.1+
• Claude Code CLI installed and authenticated
• 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)")
• A GitHub Project (v2) with board columns matching your stage names

License

Apache License 2.0. Contributions are accepted under the same license (see CONTRIBUTING.md) — no CLA required.