fabrik

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.

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.