factorialDocs
Back to the site Book a demo
Docs menu
Getting started
Architecture
Set up
Configure
Use

Getting started Introduction

Introduction

Factorial is an orchestrator for the Agent Development Life Cycle. GitHub issues move through a process you define, AI coding agents do the work of each step, and people approve at gates.

What Factorial does

Factorial runs on top of GitHub. It does not replace your tickets, your branches or your reviews.

  • A ticket is a GitHub issue.
  • Each ticket follows a process. The process comes from the config in your repository.
  • Each step of the process runs an agent or waits for a person.
  • All work stays in GitHub, as branches and pull requests.
  • Factorial checks each result itself before the ticket moves on. It does not trust the report of an agent.

Architecture shows how the parts fit together.

Terms

Project
One GitHub repository that an operator connects to Factorial. Connect a repository shows how.
Ticket
A GitHub issue that Factorial admits and moves through a process. Tickets and gates explains the labels that show where it is.
Process (lane)
The path a ticket follows, from the issue to the merged change. One process is one file in the repository. A project can have more than one. Lanes explains how an issue picks one.
Step
One stage of a process. A step runs an agent, waits for a person, runs a named action or waits for a condition. Step kinds lists the four kinds.
Gate
A step that waits for a person to review a pull request. Gates explains the two decisions.
Agent
An AI coding agent with a prompt, and with the skills and tools that it may use. Agents describes how to define one.
Runtime
The place where an agent runs, and the adapter that starts, watches and stops it. Runtimes lists the four runtimes.
Postcondition
A check that must hold before a step is done. Factorial evaluates it against what it observes on GitHub. Postconditions explains how.
The .factorial/ folder
The folder in your repository that holds the processes, the agents and the tool servers. Where the config lives shows its layout.
The factorial branch
The protected branch that Factorial reads the .factorial/ folder from. It is not the default branch of the repository. Connect a repository explains how to set it up.

One ticket, start to finish

This is the path of one ticket through a simple process.

  1. A product owner files an issue that describes the change. The issue must meet the entry condition of the process. In the sample process, that means the label factorial:new and an assignee.
  2. Factorial admits the issue and labels it with the name of the first step.
  3. An agent does the work, pushes a branch and opens a pull request.
  4. Factorial checks the postconditions of the step against GitHub.
  5. A reviewer approves the pull request at the gate.
  6. Factorial merges the pull request and moves the ticket to the next step.
  7. The next steps repeat this pattern: an agent works, Factorial checks, and a person approves where the process has a gate.
  8. The ticket reaches the end of the process and is done.

An example lane shows a longer path, step by step.

Where to start

Start at the page for your role.

Organisation owner
Create the GitHub App for Factorial. See GitHub App.
Operator
Run the factory and connect your repositories. See Run the factory and Connect a repository.
Process author
Define the processes and the agents. See Processes and Agents.
Reviewer
Review the pull requests at the gates. See Tickets and gates and Dashboard.