handarbeit/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.

📖 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