Core Concepts

Core Concepts

Faber is built around five first-class concepts that work together to create portable, maintainable AI agent systems.

The Five Concepts

1. Roles

Roles are individual AI agent definitions that encapsulate:

• Agent identity (org, system, name)
• Supported platforms (GitHub, Linear, Jira, etc.)
• Contexts (domain knowledge, procedures, documentation)
• Tasks (discrete units of work)
• Flows (multi-step processes)

Example role structure:

roles/issue-manager/
  agent.yml           # Agent definition
  contexts/           # Knowledge and procedures
  tasks/              # Task definitions
  flows/              # Multi-step workflows

2. Tools

Tools provide platform integrations and utilities:

• MCP (Model Context Protocol) servers for platforms
• Custom utilities and helpers
• Platform adapters

Tools enable roles to interact with external systems like GitHub, Linear, AWS, etc.

3. Evals

Evals define testing and evaluation scenarios:

• Test cases for agent behavior
• Expected outcomes
• Validation criteria
• Performance benchmarks

Evals ensure agents behave correctly across different frameworks.

4. Teams

Teams compose multiple roles into collaborative units:

• Multi-agent coordination
• Role specialization
• Shared context and communication
• Team-level workflows

Example: A DevOps team might include issue-manager, code-reviewer, and deployment-agent roles.

5. Workflows

Workflows orchestrate cross-team processes:

• Complex, multi-team operations
• Sequential and parallel execution
• Conditional logic and branching
• Integration points between teams

Example: A release workflow might coordinate between development, QA, and operations teams.

Three-Dimensional Abstraction

Faber provides abstraction across three dimensions:

Framework Abstraction

Deploy the same agent definition to:

• Claude Code (.claude/agents/)
• LangGraph (langgraph/graphs/)
• CrewAI (crewai/agents/)
• Custom frameworks (via plugins)

Platform Abstraction

Work with any platform via MCP:

• Issue trackers (GitHub, Linear, Jira)
• Version control (GitHub, GitLab, Bitbucket)
• Cloud providers (AWS, GCP, Azure)
• Custom platforms (via MCP servers)

Organization Abstraction

Customize without forking:

• Overlays for company-specific adaptations
• Binding system for dynamic configuration
• Inheritance and composition
• Version control friendly

Seven Context Categories

Contexts organize agent knowledge into seven categories:

1. Specialists - Domain-specific expertise loaded on-demand
2. Platforms - Platform integration guides and adapters
3. Standards - Company standards and conventions
4. Patterns - Design patterns and architectures
5. Playbooks - Operational procedures and runbooks
6. References - API docs, framework guides
7. Troubleshooting - Issue resolution guides

Overlay System

Overlays enable customization without forking:

.faber/overlays/acme/issue-manager.yml

contexts:
  specialists:
    - acme-domain-knowledge
  standards:
    - acme-issue-conventions
bindings:
  default_project: "ACME"
  issue_labels: ["bug", "feature", "enhancement"]

Overlays are applied during build, creating customized agents while maintaining upstream compatibility.

Build Process

The Faber build process:

1. Load agent definition from agent.yml
2. Apply organization overlays
3. Resolve bindings and variables
4. Transform to target framework format
5. Generate framework-specific artifacts
6. Validate output against framework requirements

Next Steps

• CLI Reference → - Complete command reference
• Examples → - Real-world use cases
• GitHub → - Source code and issues