AgentFlow OS

AgentFlow OS is a repo-native autonomous engineering team.

You give it one product idea. It uses GitHub Issues, GitHub Projects, branches, PRs, and local AI CLIs to move from idea to backlog, UX, UI, architecture, implementation, review, and merge-ready pull requests.

AgentFlow does not depend on OpenCode or a central API orchestrator. It shells out to the vendor CLIs you already use:

• Claude Code CLI: claude
• Codex CLI: codex
• Antigravity/Gemini CLI: agy or gemini
• GitHub CLI: gh

The core rule is simple: deterministic workflow logic lives in Bash; model judgment lives in role prompts.

It does not matter which assistant or terminal you start from. You can run AgentFlow from Codex, Claude Code, a normal shell, or npx; the AgentFlow router still chooses agy, claude, or codex per role, effort, and active profile.

What AgentFlow Builds

For each idea, AgentFlow coordinates these roles:

• Product Owner: decomposes the idea into epics and stories
• UX Designer: produces flows and screen inventory
• UI Designer: produces design tokens and 3 visual variants
• Architect: produces architecture docs and ADRs
• Database Engineer: owns schema and migrations
• Backend Engineer: owns APIs and services
• Frontend Engineer: owns app UI implementation
• DevOps Engineer: owns CI, Docker, deploy, environments
• QA Engineer: owns E2E journey verification
• Docs Engineer: owns user and developer documentation
• Engineering Reviewer: reviews every PR using a different provider from the builder
• CTO: reviews structural PRs and audits architecture drift

Safety Model

AgentFlow is designed around hard guardrails:

• one story, one branch, one PR
• no direct work on the default branch
• every story has acceptance criteria and a Scope line
• every implementation writes tasks/<issue>/research.md
• every implementation writes tasks/<issue>/plan.md
• reviewers run in read-only mode where the runtime supports it
• reviewer provider must differ from builder provider
• .github/, .agentflow/, and scripts/ are protected by CODEOWNERS
• architecture must be approved before normal product stories run
• fix loops are capped at 2 rounds
• final merge stays human by default

Repository Layout

bin/aflow                 main CLI
lib/common.sh             shared helpers
lib/runtimes.sh           Claude/Codex/Antigravity adapter layer
lib/routing.sh            role/effort/profile routing logic
lib/board.sh              GitHub Projects v2 helper
config/routing.conf       model routing matrix
roles/*.md                operating contracts for each role
templates/                files copied into target repos by aflow init
docs/                     AgentFlow internal docs
tests/run-tests.sh        local shell test harness
install.sh                installer

Prerequisites

Required:

• Git
• GitHub CLI authenticated with gh auth login
• a GitHub repository
• a GitHub Projects v2 board

Recommended:

• claude CLI authenticated
• codex CLI authenticated
• agy or gemini CLI authenticated

AgentFlow can route around a missing runtime only if your routing config does not require that runtime. Run aflow doctor before trusting daemon mode.

GitHub Project Setup

Create a GitHub Projects v2 board with a single-select field named Status.

Required Status options:

New Issue
Icebox
Product Backlog
Sprint Backlog
In progress
In review
Done

AgentFlow validates these with:

aflow board check

GitHub's Project v2 field API is awkward and easy to misconfigure, so AgentFlow validates the board instead of silently rewriting it.

Install From This Checkout

From the AgentFlow source directory:

./install.sh

This installs to:

~/.agentflow

and links:

~/.local/bin/aflow

If ~/.local/bin is not on your PATH, restart your shell after install or add it manually.

Initialize A Product Repo

Go to the repository you want AgentFlow to manage:

cd your-product-repo
aflow init --owner your-github-user-or-org --project 1
aflow doctor

Use With npx

After the package is published to npm:

npx agentflow-os help
npx agentflow-os init --owner UmarAlaa --project 1
npx agentflow-os config --profile balanced
npx agentflow-os /idea "a habit tracker with social accountability"

Before npm publishing, use the GitHub package directly:

npx github:UmarAlaa/agentflow-os help
npx github:UmarAlaa/agentflow-os doctor

Global install:

npm i -g agentflow-os
aflow help
aflow /idea "build my product idea"

AgentFlow exposes two binary names:

agentflow-os
aflow

So these are equivalent after install:

npx agentflow-os doctor
aflow doctor

aflow init creates:

• .agentflow/config
• tasks/
• docs/ADR/
• docs/design-variants/
• scripts/board.sh
• .github/CODEOWNERS
• .github/PULL_REQUEST_TEMPLATE.md
• .github/ISSUE_TEMPLATE/story.yml
• AGENTS.md
• CLAUDE.md
• required labels

Then apply branch protection:

aflow protect

aflow protect asks GitHub to require PR review and CODEOWNERS review on the default branch.

Profiles And Model Routing

AgentFlow uses GSD-style model profiles with gstack-style specialist roles.

Profiles:

aflow config profiles
aflow config --profile quality
aflow config --profile balanced
aflow config --profile budget
aflow config --profile inherit

Profile meanings:

quality  - strongest default models; best for risky architecture and correctness
balanced - cost/quality split for normal work; default
budget   - cheaper models for high-volume iteration
inherit  - repo follows the global AgentFlow default profile

Set a global default profile outside any initialized repo:

aflow config --profile balanced

Set a repo profile inside a repo:

aflow config --profile quality

Inspect effective config:

aflow config

Preview routing before running a task:

aflow route backend medium
aflow route architect high
aflow route qa low

This prints the active profile, runtime, model, and reasoning tier. The selected runtime is independent of where you invoked AgentFlow from.

Validate Models

Check whether your installed CLIs resolve the configured model IDs:

aflow models

Routing lives in:

~/.agentflow/config/routing.conf

or, from source:

config/routing.conf

The routing matrix maps:

role + effort + profile -> runtime:model:reasoning

Example:

backend.medium = agy:gemini-3.5-flash:medium

First Idea

From your product repo:

aflow idea "a habit tracker with social accountability"

Slash-style equivalent:

aflow /idea "a habit tracker with social accountability"

This starts the design chain:

1. Product Owner creates epics and stories.
2. UX Designer opens a PR with docs/UX.md.
3. UI Designer opens a PR with docs/DESIGN-SYSTEM.md and 3 visual variants.
4. Architect opens a PR with docs/ARCHITECTURE.md and ADRs.

Review and merge those PRs manually. After the architecture PR is merged, open the build gate:

gh issue edit <idea-number> --add-label arch:ready

Plan A Sprint

aflow sprint

The Product Owner moves 3-5 dependency-free stories into Sprint Backlog.

Manual Story Execution

Run one story end to end:

aflow work <issue-number>
aflow review <pr-number>

If review requests changes:

aflow fix <pr-number>
aflow review <pr-number>

After you merge the PR:

aflow done <pr-number>

This closes the linked issue and moves the board card to Done.

Daemon Mode

After you trust manual mode:

aflow daemon

The daemon loop:

1. reconciles merged PRs
2. lists open cards in Sprint Backlog
3. skips blocked, working, or review cards
4. claims an unclaimed story
5. runs the role agent
6. opens a PR
7. runs cross-provider review
8. runs up to 2 fix rounds if requested
9. waits and repeats

Polling interval defaults to 120 seconds:

AF_POLL=30 aflow daemon

Slash-style equivalent:

aflow /daemon

Slash Commands

AgentFlow can install lightweight slash-command templates into a repo:

aflow slash install

This writes:

.agentflow/commands/
.claude/commands/

The templates are thin wrappers. They tell the current assistant to run AgentFlow commands such as:

aflow idea "$ARGUMENTS"
aflow sprint
aflow work "$ARGUMENTS"
aflow daemon

That is intentional. Slash commands should not bind work to the model you opened. They should call aflow, and aflow should route to the right runtime for the task.

Install only one target:

aflow slash install --target agentflow
aflow slash install --target claude

List supported slash commands:

aflow slash list

CTO Review

Structural PRs should get CTO review:

aflow cto <pr-number>

Weekly audit mode:

aflow cto audit

The CTO opens at most 3 issues for architecture drift, critical risk, or missing tests.

Board Commands

aflow board check
aflow board list "Sprint Backlog"
aflow board add <issue-number>
aflow board move <issue-number> "In progress"

Troubleshooting

Run:

aflow doctor

Common failures:

missing gh authentication

Run:

gh auth login

missing or inaccessible GitHub Project statuses

Confirm the project owner, project number, and required Status options.

runtime command not found

Install or authenticate the missing vendor CLI, or change config/routing.conf to avoid it.

FATAL: reviewer route violates cross-provider rule

Your routing config lets a provider review its own code. Change the relevant eng-reviewer.vs-* route.

GATE: Parent idea does not have arch:ready

Merge the architecture PR and label the parent idea:

gh issue edit <idea-number> --add-label arch:ready

Local Tests

Run from this source checkout:

tests/run-tests.sh

On Windows with Git Bash:

& 'C:\Program Files\Git\usr\bin\bash.exe' -lc 'cd /e/Agantic && bash tests/run-tests.sh'

The tests do not call GitHub or any AI runtime. They verify routing, cross-provider review enforcement, label parsing, slugging, and CLI loading.

Current Implementation Boundary

AgentFlow owns orchestration. It does not replace your judgment on:

• whether the generated product plan is strategically right
• whether model output is worth merging
• whether branch protection is strict enough for your repo
• whether paid model usage is acceptable for a given sprint

Keep human merges enabled until the system has passed several real tasks in your own repositories.