Faber

AI-native workflow automation that runs in production

⚠️ Migration Notice

Python agent/tool definitions are being migrated to @fractary/forge.

Starting with FABER v1.x, agent and tool definitions will be managed by Forge:

• v1.x: Dual-mode support (legacy Python + Forge TypeScript)
• v2.0: Forge required, Python definitions removed

For migration instructions, see docs/MIGRATION-FABER-FORGE.md.

---

Repository Structure

This is a monorepo containing JavaScript and Python SDKs, plus the CLI:

faber/
├── cli/                     # CLI (@fractary/faber-cli)
│   ├── src/                # TypeScript source
│   ├── dist/               # Compiled output
│   └── package.json        # @fractary/faber-cli
├── sdk/
│   ├── js/                 # JavaScript/TypeScript SDK
│   │   ├── src/           # TypeScript source
│   │   ├── dist/          # Compiled output
│   │   └── package.json   # @fractary/faber (v2.0+)
│   └── py/                # Python SDK
│       ├── faber/         # Python package
│       ├── tests/         # Python tests
│       └── pyproject.toml # faber
├── specs/                 # Design specifications
├── docs/                  # Documentation
└── package.json           # Monorepo root

Development

CLI:

npm run build:cli    # Build CLI
npm run test:cli     # Test CLI
npm run lint:cli     # Lint CLI

JavaScript SDK:

npm run build:js     # Build SDK
npm run test:js      # Test SDK
npm run lint:js      # Lint SDK

Python SDK:

cd sdk/py
pip install -e ".[dev]"
pytest

Run all builds:

# From root
npm run build
npm run test
npm run lint

---

What is FABER?

FABER enables AI agents to do meaningful work autonomously while knowing exactly when to involve humans.

Unlike simple automation tools that chain API calls, FABER orchestrates AI agents that actually reason about your work. Unlike raw AI frameworks, FABER provides the guardrails enterprises need to deploy with confidence.

From issue to PR, autonomously.

The Problem

Approach	What Happens
Deterministic Automation (Zapier, Make)	Works for simple tasks, breaks when reasoning is required
Raw AI Agents (LangGraph, AutoGen)	Powerful but unpredictable—enterprises won't adopt
AI + Approve Everything	Human becomes the bottleneck, defeats the purpose

The FABER Solution

FABER takes a different approach: AI operates autonomously within defined boundaries, escalates intelligently when boundaries are approached.

• Structural Guardrails: The FABER methodology (Frame → Architect → Build → Evaluate → Release) prevents chaos through process
• Boundary Guardrails: Hard limits the AI cannot cross (production deploys, cost thresholds)
• Intelligent Guardrails: AI reasons about its own confidence and risk, deciding when to proceed vs. escalate

The result: 90% autonomous operation, 10% human involvement—focused on decisions that actually matter.

Who is FABER For?

Development Teams

Automate complex development tasks—from understanding an issue to shipping a PR. Focus on interesting problems while AI handles the routine work.

Technical Operations

Automated incident response, deployment pipelines, and infrastructure changes with human oversight on critical decisions.

Platform Engineers

Build AI-powered workflows that your entire organization can use, with the safety and observability enterprises require.

Key Concepts

The FABER Methodology

Every workflow follows five phases:

Phase	Purpose
Frame	Understand the problem before acting
Architect	Plan the approach before building
Build	Implement to specification
Evaluate	Validate before shipping
Release	Controlled delivery

Earned Autonomy

Trust is earned, not assumed:

1. Day 1: Conservative—more human checkpoints
2. Week 4: Established patterns—less intervention needed
3. Month 6: Mature—90% autonomous, 10% escalation

Autonomy Levels

Level	Description
dry-run	Preview what would happen without executing any changes
assisted	Pause for user confirmation at each significant step
guarded	Proceed automatically for safe operations; confirm destructive ones
autonomous	Execute to completion within established boundaries

Installation

npm install @fractary/faber

Quick Start

CLI Workflow (Recommended)

FABER uses a two-phase approach: plan (CLI) + execute (Claude Code):

# 1. Plan workflow (creates plan, branch, worktree)
fractary-faber workflow-plan --work-id 258

# 2. Execute workflow (in Claude Code session)
cd ~/.claude-worktrees/fractary-myproject-258
claude
/fractary-faber-workflow-run 258

Batch Planning:

# Plan multiple workflows at once
fractary-faber workflow-plan --work-id 258,259,260

# Or search by labels
fractary-faber workflow-plan --work-label "workflow:etl,status:approved"

Benefits:

• ✅ Plan 10+ workflows in one command
• ✅ Each workflow runs in isolated worktree
• ✅ Parallel execution across multiple Claude sessions
• ✅ Claude focuses only on execution (no planning confusion)

SDK Usage

import { FaberWorkflow } from '@fractary/faber';

// Run a complete FABER workflow
const workflow = new FaberWorkflow();
const result = await workflow.run({
  workId: '123',
  autonomy: 'assisted'
});

Additional CLI Commands

# Check workflow run status
fractary-faber run-inspect --work-id 258

# Manage work items
fractary-faber work issue fetch 123
fractary-faber work comment create 123 --body "Starting"

# Repository operations
fractary-faber repo branch create feat/fix-123
fractary-faber repo pr create "Fix issue" --body "Resolves #123"

See CLI Reference for comprehensive documentation.

SDK Modules

The FABER SDK provides modular primitives for building AI-powered workflows:

Module	Purpose	Import
Work	Issue tracking (GitHub, Jira, Linear)	@fractary/faber/work
Repo	Git & PRs (GitHub, GitLab, Bitbucket)	@fractary/faber/repo
Spec	Specification management	@fractary/faber/spec
State	Workflow persistence & checkpoints	@fractary/faber/state
Logs	Session capture & audit trails	@fractary/faber/logs
Storage	Artifact storage with Codex integration	@fractary/faber/storage
Workflow	Full FABER orchestration	@fractary/faber/workflow

Work Module

import { WorkManager } from '@fractary/faber/work';

const work = new WorkManager();
const issue = await work.fetchIssue(123);
await work.createComment(123, 'Starting implementation');
const workType = await work.classifyWorkType(issue); // 'feature' | 'bug' | 'chore'

Repo Module

import { RepoManager } from '@fractary/faber/repo';

const repo = new RepoManager();
await repo.createBranch('feature/add-export', { base: 'main' });
await repo.createPR({ title: 'Add export feature', head: 'feature/add-export' });
await repo.commit({ message: 'Add feature', type: 'feat' });

Workflow Module

import { FaberWorkflow } from '@fractary/faber/workflow';

const faber = new FaberWorkflow({
  config: {
    autonomy: 'guarded',
    phases: {
      frame: { enabled: true },
      architect: { enabled: true, refineSpec: true },
      build: { enabled: true },
      evaluate: { enabled: true, maxRetries: 3 },
      release: { enabled: true, requestReviews: true },
    },
  },
});

// Event handling
faber.addEventListener((event, data) => {
  console.log(`${event}:`, data);
});

// Run workflow
const result = await faber.run({ workId: '123' });

CLI Commands

For comprehensive CLI documentation, see CLI Reference.

Quick reference:

# Workflow (use skills for execution, CLI for inspection/config)
fractary-faber config init                            # Initialize project
fractary-faber run-inspect --work-id <issue>         # Check status
fractary-faber runs verify-complete <run-id>         # Verify completion

# Work tracking
fractary-faber work issue fetch <issue>
fractary-faber work issue create --title "Feature"
fractary-faber work comment create <issue> --body "Update"
fractary-faber work label add <issue> --label "bug"

# Repository
fractary-faber repo branch create <name>
fractary-faber repo pr create --title "Title"
fractary-faber repo commit --message "feat: message"
fractary-faber repo tag create v1.0.0

# Logs
fractary-faber logs capture <workflow-id>
fractary-faber logs read <session-id>

Backlog Management

Plan workflows for prioritized backlogs:

# Plan top 5 priorities
fractary-faber workflow-plan --work-label "status:backlog" --order-by priority --limit 5

# Plan most recently updated issues
fractary-faber workflow-plan --work-label "status:backlog" --order-by updated --limit 10

# Plan oldest issues first (FIFO)
fractary-faber workflow-plan --work-label "status:backlog" --order-by created --order-direction asc --limit 3

Key features:

• Priority ordering: Use priority-1 through priority-10 labels (lower = higher priority, recommend 1-4)
• Date ordering: Sort by created or updated date
• Limit results: Plan manageable batches with --limit
• Flexible filtering: Combine with any label filters

See Backlog Management Guide for complete documentation.

Configuration

Configuration is stored in .fractary/config.yaml:

# .fractary/config.yaml
github:
  organization: your-org
  project: your-repo

faber:
  workflows:
    path: .fractary/faber/workflows
    default: default
    autonomy: guarded
  runs:
    path: .fractary/faber/runs

Platform Support

Platform	Work Tracking	Repository
GitHub	Full	Full
Jira	Planned	-
Linear	Planned	-
GitLab	-	Planned
Bitbucket	-	Planned

Documentation

Getting Started

• Getting Started Guide - Installation and first steps
• Core Concepts - FABER methodology and architecture
• Guardrails System - Three layers of safety

Guides

• API Reference - Complete SDK API documentation (TypeScript & Python)
• CLI Integration - CLI usage patterns and integration
• Configuration - Complete configuration reference
• Troubleshooting - Common issues and solutions

Examples

• Code Examples - Runnable TypeScript and Python examples
  • Simple Workflow - Basic workflow execution
  • Work Tracking - Issue and PR automation
  • Repository Automation - Branch and PR management
  • And more...

Component Documentation

• CLI Reference - Command-line interface
• MCP Server - Model Context Protocol integration
• Python SDK - Python SDK guide

Technical Specifications

• SDK Architecture - Technical architecture overview
• LangGraph Integration - Graph-based workflow orchestration
• Intelligent Guardrails - Confidence-based autonomy system
• Multi-Workflow Orchestration | DAC foundation

Vision & Strategy

• FABER Vision - Mission, philosophy, and strategic positioning

Type Exports

All types are exported for TypeScript consumers:

import type {
  // Workflow
  WorkflowConfig, WorkflowResult, PhaseResult, FaberPhase, AutonomyLevel,

  // Work
  Issue, IssueCreateOptions, Comment, Label, WorkType,

  // Repo
  PullRequest, PRCreateOptions, Branch, BranchCreateOptions,

  // Spec
  Specification, SpecTemplate, ValidationResult,
} from '@fractary/faber';

Domain-Specific Plugins

FABER's core framework can be extended with domain-specific plugins:

Plugin	Description	Install
faber-software	Software development agents	forge install @fractary/faber-software
faber-cloud	Cloud infrastructure automation	forge install @fractary/faber-cloud
faber-content	Content creation workflows	forge install @fractary/faber-content

These plugins provide specialized agents, commands, and workflows for their respective domains while leveraging the core FABER orchestration framework.

License

MIT - see LICENSE for details.

---

Part of the Fractary Ecosystem