@fractary/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 changes without executing | | assisted | Pause for user confirmation at each step | | guarded | Confirm destructive operations only | | autonomous | Execute 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 README 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 @fractary/faber-cli.

Quick reference:

# Workflow
fractary-faber configure                             # Initialize project
fractary-faber workflow-run --work-id <issue>        # Run workflow
fractary-faber run-inspect --work-id <issue>         # Check status
fractary-faber workflow-resume <workflow-id>          # Resume workflow

# 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 "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