README.md

April 1, 2026 · View on GitHub

AgentFlow

Your Kanban board builds your code.

The first AI development pipeline that uses your project management tool as the orchestration layer.
Full observability. Deterministic quality gates. Zero custom infrastructure.

Quick Start • Architecture • Getting Started • Gap Registry • Comparison

What is AgentFlow?

AgentFlow turns your existing Kanban board (Asana, GitHub Projects, Linear, Jira) into a fully autonomous AI development pipeline. Instead of building custom orchestration infrastructure, AgentFlow treats your project management tool as a distributed state machine — tasks move through stages, AI agents read and write state via comments, and humans intervene through the same UI they already use.

The result: Complete pipeline observability from your phone. Crash recovery for free (state lives in your PM tool, not in memory). Human override at any point by dragging a card.

Why AgentFlow?

Most AI coding tools either give you a chatbot or a black-box agent. AgentFlow gives you a visible, auditable pipeline where:

Every decision is a comment on a task card
Every stage transition is a card moving between columns
Every retry carries accumulated context from previous attempts
Every cost is tracked per-task with automatic guardrails
Every failure pattern is captured and fed back into the system

You don't need to trust a black box. Open your Kanban board and watch the pipeline work.

Key Features

Pipeline Orchestration

7-stage Kanban pipeline: Backlog → Research → Build → Review → Test → Integrate → Done
Stateless orchestrator: One-shot sweep via crontab — no daemon, no session dependency, crash-proof
Transitive priority dispatch: Tasks that unblock the most work get built first (automatic critical path)
Conflict-aware scheduling: Parallel tasks touching the same files are serialized automatically

Quality Gates

Deterministic before probabilistic: tsc + eslint + tests run as hard gates before any AI review — catches ~60% of issues at near-zero cost
Adversarial AI review: Reviewers must "list 3 things wrong before deciding to pass"
Coverage gate: 80% threshold on new files before promotion to Test stage
Integration testing: Full suite runs on main after every merge — auto-reverts on failure

Observability & Cost Tracking

Full pipeline observability from your phone — every task card shows current stage, assigned agent, retry count, and accumulated cost
Per-task cost tracking with stage cost ceilings (Sonnet default: Research ~$0.10, Build ~$0.40, Review ~$0.10, Test ~$0.05, Integrate ~$0.03)
Automatic cost guardrails: Warning at $3/$8, hard stop at $10/$20 (Sonnet/Opus) with human escalation
Real-time status dashboard pinned to each project
Heartbeat monitoring: Dead agents detected and reassigned within 10 minutes

System Learning

Feedback loops with accumulated context: Every retry carries what was tried, what failed, and what to do differently
System-level retrospectives: Every 10 completed tasks, common failure patterns are extracted to LEARNINGS.md
Cross-task learning: Builders and reviewers read LEARNINGS.md before starting work
Spec drift detection: SHA-256 hash comparison catches requirement changes mid-sprint

Safety & Recovery

Auto-revert on integration failure: git revert (new commit, never force-push)
Graceful shutdown: Active workers finish, unstarted tasks return to backlog
Blocked task detection: After 2 failed attempts, tasks escalate to human review
Scope creep detection: PR diff files compared against predicted files list
Secret management: Mock values in tests, environment variables in code, manual verification flags for real API tasks

Architecture

graph TB
    subgraph board["Your Kanban Board"]
        B[Backlog] --> R[Research] --> BU[Build] --> RE[Review] --> T[Test] --> I[Integrate] --> D[Done]
        RE -->|reject| BU
        T -->|fail| BU
        I -->|fail| BU
        NH[Needs Human] -.->|drag card| B
    end
    
    CR["Crontab (every 15 min)"] -->|reads state| board
    CR -->|dispatches| W2["Worker T2 (Build)"]
    CR -->|dispatches| W3["Worker T3 (Build)"]
    CR -->|dispatches| W4["Worker T4 (Review)"]
    CR -->|dispatches| W5["Worker T5 (Test)"]
    
    W2 & W3 & W4 & W5 -->|"state flows through"| board

Core principle: The Kanban board IS the orchestration layer. No separate database, no message queue, no custom infrastructure. State lives where humans already look.

Full architecture docs →

Quick Start

Prerequisites

Claude Code (CLI)
An Asana workspace with MCP integration (or GitHub Projects — adapter coming soon)
Git + Node.js project

Installation

# Clone the repo
git clone https://github.com/UrRhb/agentflow.git

# Copy skills and prompts to your Claude Code config
cp -r agentflow/skills/* ~/.claude/skills/
cp -r agentflow/prompts/* ~/.claude/sdlc/prompts/
cp agentflow/conventions.md ~/.claude/sdlc/conventions.md

Plugin Installation (Recommended)

If you're using Claude Code, install AgentFlow as a native plugin for automatic worker spawning, instant handoffs, and infrastructure-level quality gates:

# Add the AgentFlow marketplace
claude plugin marketplace add UrRhb/agentflow

# Install the plugin
claude plugin install agentflow

# Or manually:
git clone https://github.com/UrRhb/agentflow.git
cd agentflow && ./setup.sh

Plugin mode gives you:

Automatic worker spawning (no iTerm tabs)
Instant handoffs via SendMessage (seconds, not 15 minutes)
Infrastructure-level quality gates (hooks enforce tsc/lint/test/coverage)
Real-time progress tracking
Clean team shutdown

Quick start (plugin mode):

# 1. Create your spec
# 2. Decompose into tasks
claude -p "/spec-to-board"

# 3. Start the pipeline (workers spawn automatically!)
claude -p "/sdlc-orchestrate"

# 4. Watch from your phone (Asana) or terminal
claude -p "/sdlc-health"

Setup

1. Create your spec

Write a SPEC.md for your project — or use Claude to brainstorm one:

You: I want to build [your idea]
Claude: [brainstorms → produces SPEC.md]

2. Decompose into tasks

You: /spec-to-asana
Claude: Reading SPEC.md... Decomposing into atomic tasks...
        Created 14 tasks across 3 sub-phases in Asana.
        Dependencies mapped. Ready to build.

3. Start workers

Open 3-4 terminal windows, each as a worker slot:

# Terminal 2
claude -p "/sdlc-worker --slot T2"

# Terminal 3
claude -p "/sdlc-worker --slot T3"

# Terminal 4 (reviewer)
claude -p "/sdlc-worker --slot T4"

# Terminal 5 (tester)
claude -p "/sdlc-worker --slot T5"

4. Start the orchestrator

# Add to crontab (runs every 15 minutes)
crontab -e
# Add: */15 * * * * ~/.claude/sdlc/agentflow-cron.sh >> /tmp/agentflow-orchestrate.log 2>&1

5. Watch from your phone

Open Asana on your phone. Watch tasks flow through the pipeline. Drag any card to "Needs Human" to intervene.

Stop the pipeline

You: /sdlc-stop
Claude: Graceful shutdown initiated. Active workers finishing...
        3 tasks returned to Backlog. System paused.

Detailed getting started guide →

How It Works

The 7-Stage Pipeline

Stage	What Happens	Gate
Backlog	Task waiting for dependencies + available slot	Dependencies resolved, no file conflicts
Research	Conditional — only runs if task has research triggers	Structured findings posted
Build	AI writes code, creates PR	`tsc + eslint + npm test` (deterministic)
Review	Different AI agent reviews adversarially	Must list 3 issues before passing
Test	Full test suite + visual validation + coverage check	80% coverage on new files
Integrate	Merge to main, run full suite	All tests pass on main
Done	Task complete	—

Task Lifecycle

graph LR
    A["[SLOT:--] Backlog"] -->|assign T2| B["[SLOT:T2] Build"]
    B -->|"PR created"| C["Lint Gate: tsc + eslint + tests"]
    C -->|LINT:PASS| D["Review (T4)"]
    D -->|"3 issues, all minor"| E["Coverage Gate"]
    E -->|COV:PASS| F["Test (T5)"]
    F -->|TEST:PASS| G["Merge PR"]
    G --> H["Integration Check"]
    H -->|INTEGRATE:PASS| I["Done [\$5.75]"]

What Happens When Things Fail

graph TD
    REJ["REVIEW:REJECT<br/>'SQL injection in user input'"] --> R1["RETRY:1"]
    R1 --> CTX["Accumulated context posted"]
    CTX --> SLOT["Slot cleared, different worker assigned"]
    SLOT --> BACK["Task moves back to Build"]
    BACK --> COST{"Cost > hard stop?"}
    COST -->|Yes| HUMAN["COST:CRITICAL → Needs Human"]
    COST -->|No| REBUILD["New worker rebuilds with retry context"]

Comparison

Feature	AgentFlow	GSD	Superpowers	Aperant
Orchestration layer	Your Kanban board (Asana/Linear/Jira)	CLI waves	CLAUDE.md prompts	Electron app
Pipeline observability	Full (phone, web, desktop)	Terminal only	File-based	Desktop app
Deterministic quality gates	tsc + lint + tests before AI review	None	None	None
Per-task cost tracking	Built-in with guardrails	None	None	None
Adversarial review	Different agent, must find 3 issues	Same agent	Same agent	Same agent
Integration testing	Auto-revert on main breakage	None	None	None
System-level learning	LEARNINGS.md retrospectives	None	None	None
Crash recovery	Free (state in PM tool)	Restart from scratch	Re-read files	Restart app
Human intervention	Drag a card	Kill process	Edit files	Click button
Spec drift detection	SHA-256 hash comparison	None	None	None
Multi-project support	Native (portfolio view)	Single project	Single project	Single project
Parallel agents	4+ workers with conflict detection	Wave-based	Sequential	Sequential
Custom infrastructure	None (uses existing PM tool)	CLI tool	Markdown files	Electron + SQLite
Adapter ecosystem	Asana, GitHub Projects (planned), Linear (planned)	GitHub only	Any git repo	Local only
Worker spawning	Automatic (plugin) or manual (standalone)	Manual	Manual	Manual

When to Use What

AgentFlow: You want full pipeline observability, deterministic quality gates, cost tracking, and the ability to monitor/intervene from your phone. Best for teams and solo devs running multiple projects.
AgentFlow + Superpowers: You want the best of both — AgentFlow orchestrates across tasks, Superpowers optimizes each worker's methodology. See integration guide below.
GSD: You want a simple CLI tool for wave-based task execution. Good for quick prototyping.
Superpowers: You want a methodology-as-prompt approach with minimal setup. Good for single-project focus.
Aperant: You want a desktop GUI for agent management. Good for visual workflow preference.

Superpowers Integration

AgentFlow and Superpowers operate at different layers and are designed to stack:

graph TB
    subgraph outer["OUTER LOOP — AgentFlow"]
        direction TB
        OL["Kanban board • dispatch • transitions • cost gates"]
        subgraph w2["Worker T2"]
            SP2["Superpowers: brainstorm → plan → execute → verify"]
        end
        subgraph w3["Worker T3"]
            SP3["Superpowers: brainstorm → plan → execute → verify"]
        end
        subgraph w4["Worker T4"]
            SP4["Superpowers: code-review + adversary rules"]
        end
    end

AgentFlow decides: "Task APP-007 goes to Worker T2 now" Superpowers decides: "Inside T2, I'll brainstorm → plan → execute with sub-agents → verify"

What Each Layer Controls

Concern	AgentFlow (outer)	Superpowers (inner)
Task assignment	Which worker gets which task	—
Build methodology	Lifecycle markers + heartbeats	brainstorm → plan → execute → verify
Parallelism	Across tasks (T2 builds one, T3 builds another)	Within a task (sub-agents write code in parallel)
Quality gates	Deterministic (tsc/lint/test) + adversarial review	Structured review methodology
Debugging	Retry context + worker rotation	Systematic debugging methodology
Cost tracking	Per-task with guardrails	—

Complexity Gating

Not every task needs Superpowers' full methodology. AgentFlow gates by task complexity:

Complexity	Superpowers Methodology	Why
S (Simple, <30min)	Skip brainstorm + plan. Direct build.	Overkill adds ~$0.50-1.00 for zero quality gain
M (Medium, <1hr)	Skip brainstorm. Use plan → execute.	Planning helps, brainstorming doesn't
L (Complex, <2hr)	Full: brainstorm → plan → execute → verify	Worth the investment on complex tasks

Integration Gaps (24-31)

Stacking two systems creates 8 new failure modes. All are addressed in AgentFlow's design:

#	Gap	Fix
24	Context window war (both systems load large prompts)	Lazy-load: only load Superpowers prompts matching task complexity
25	Two captains (conflicting workflow control)	AgentFlow owns lifecycle, Superpowers owns methodology
26	Sub-agents skip heartbeats (false dead-worker detection)	Parent worker posts heartbeats independently of sub-agents
27	Plan exceeds task scope (Superpowers plans freely)	Feed predicted files + acceptance criteria as hard constraints
28	Double cost tracking (sub-agents add hidden cost)	Adjusted ceilings: S=$3, M=$5, L=$8 when Superpowers active
29	Retry context fragmentation (sub-agent failures lost)	Parent aggregates all sub-agent outputs before posting
30	Brainstorm overkill on simple tasks	Complexity gating (table above)
31	Conflicting review standards	AgentFlow adversarial rules override; Superpowers provides methodology

Full details for all 45 gaps →

Adapters

AgentFlow uses an adapter pattern to support multiple project management tools. Each adapter implements the same interface for reading/writing pipeline state.

Adapter	Status	Notes
Asana	Available	Full MCP integration, recommended for production
GitHub Projects	Planned	Free alternative, community priority
Linear	Planned	For teams already on Linear
Jira	Planned	Enterprise support
Notion	Planned	For Notion-native teams

Want to build an adapter? See CONTRIBUTING.md.

The 45-Gap Registry

AgentFlow was designed by systematically identifying and closing 45 gaps in AI development pipelines — 23 for the core system, 8 for Superpowers integration, and 14 from production audit findings. Each gap represents a failure mode that existing tools don't address.

#	Gap	Fix
1	AI review has shared blindness with AI builder	Deterministic gates (tsc/lint/test) before AI review
2	No decomposition quality standard	9-field rubric with validation
3	No integration testing after merge	7th stage: full suite on main, auto-revert on failure
4	Unconditional research wastes time/money	Trigger-based: only research when task needs external knowledge
5	No cost visibility	Per-task tracking with stage ceilings and automatic guardrails
6	Parallel tasks can conflict on shared files	Predicted files comparison, automatic serialization
7	Same mistakes repeated across tasks	LEARNINGS.md retrospective every 10 tasks
8	Dead agents block the pipeline	Heartbeat every 5 min, reassign after 10 min timeout
9	AI reviews are too lenient	Adversarial prompt: "list 3 things wrong before deciding to pass"
10	Integration failures leave main broken	Auto-revert via `git revert` (new commit, never force-push)
11	Asana custom fields are fragile	All metadata in description headers, parsed with regex
12	Session-based scheduling dies with session	Stateless orchestrator + real crontab (most critical gap)
13	No visibility into what agents are doing	Comment-thread-as-memory: every action is a tagged comment
14	Runaway costs on stuck tasks	Cost ceilings per stage, warning at $3/$8, hard stop at $10/$20 (Sonnet/Opus)
15	Uncontrolled external API usage	Source priority: codebase → docs → web → GitHub (opt-in only)
16	Circular dependencies in task graph	Topological sort validation during decomposition
17	PRs that exceed task scope	Diff files vs predicted files → `[SCOPE:WARNING]`
18	Impossible tasks retry forever	After 2 failures: evaluate → `[BUILD:BLOCKED]` escalation
19	Secrets leaked in code	Mock values in tests, env vars in code, `[NEEDS:MANUAL_VERIFY]`
20	Wrong task gets built first	Transitive priority: count downstream blocked tasks
21	No dashboard for pipeline status	Pinned Status task updated every sweep
22	No clean shutdown mechanism	`/sdlc-stop` drains workers, returns unstarted to backlog
23	Spec changes mid-sprint go unnoticed	SHA-256 hash comparison, `[SPEC:CHANGED]` flag
	Superpowers Integration Gaps
24	Context window war (stacked prompts)	Lazy-load prompts by task complexity
25	Two captains (conflicting workflow control)	AgentFlow owns lifecycle, Superpowers owns methodology
26	Sub-agents skip heartbeats	Parent worker posts heartbeats independently
27	Plan exceeds task scope	Predicted files + acceptance criteria as hard constraints
28	Double cost tracking (hidden sub-agent cost)	Adjusted ceilings: S=$3, M=$5, L=$8 with Superpowers
29	Retry context fragmentation	Parent aggregates all sub-agent outputs
30	Brainstorm overkill on simple tasks	Complexity gating: S=skip, M=plan only, L=full
31	Conflicting review standards	AgentFlow adversarial rules override Superpowers
	Audit Finding Gaps
32	No worktree cleanup	Worktree removed on Done transition
33	Prompt version skew	Version field in conventions.md, re-read per task
34	No merge lock	`[MERGE_LOCK]` on Status task, 10 min timeout
35	Sub-agent git conflicts	Non-overlapping file sets; sequential fallback
36	No orchestrator health monitoring	`[LAST_SWEEP]` timestamp + external watchdog
37	Comment thread pollution	Read only last 10-20 comments per task
38	Dual sweep collision	`[SWEEP:RUNNING]` mutual exclusion lock
39	Adversarial review ping-pong	PASS WITH NOTES for minor-only issues
40	Prompt injection	Input sanitization check at stage entry
41	LEARNINGS.md context bomb	50-line cap with oldest-first rotation
42	Git revert can fail	`[INTEGRATE:REVERT_FAILED]` → Needs Human
43	Crontab environment/auth failure	Wrapper script sources shell environment
44	Cost ceilings assume wrong model	Dual cost profiles (Sonnet/Opus)
45	Orchestrator cost	Idle sweep optimization, doubles interval when idle

Full gap registry with details →

Project Structure

agentflow/
├── core/                          # Portable logic (works with any AI IDE)
│   ├── prompts/                   # Stage-specific prompt templates
│   │   ├── decompose.md           # Spec → atomic tasks
│   │   ├── research.md            # Conditional research stage
│   │   ├── build.md               # Build with lint gate + context compaction
│   │   ├── review.md              # Adversarial review
│   │   └── test.md                # Test + integration
│   ├── conventions.md             # System conventions v2
│   └── adapters/                  # PM tool adapter interface
│       ├── interface.md           # Adapter contract definition
│       ├── asana/                 # Asana MCP adapter
│       └── github-projects/       # GitHub Projects adapter (planned)
│
├── plugin/                        # Claude Code native plugin
│   ├── .claude-plugin/
│   │   └── plugin.json            # Plugin manifest
│   ├── .mcp.json                  # MCP auto-configuration
│   ├── agents/                    # Worker agent definitions
│   │   ├── sdlc-orchestrator.md   # Fleet commander (haiku)
│   │   ├── sdlc-builder.md        # Code writer (sonnet)
│   │   ├── sdlc-reviewer.md       # Adversarial reviewer (sonnet, read-only)
│   │   └── sdlc-tester.md         # Test + merge agent (sonnet)
│   ├── hooks/                     # Infrastructure-level quality gates
│   │   ├── lint-gate.md           # Blocks commit without tsc/lint/test
│   │   ├── coverage-gate.md       # Blocks merge without 80% coverage
│   │   └── scope-guard.md         # Warns/blocks unpredicted file edits
│   └── skills/                    # Plugin-aware skills (auto-discovered)
│       ├── spec-to-board/SKILL.md
│       ├── sdlc-orchestrate/SKILL.md
│       ├── sdlc-worker/SKILL.md
│       ├── sdlc-stop/SKILL.md
│       ├── sdlc-health/SKILL.md
│       └── sdlc-demo/SKILL.md
│
├── bin/
│   └── agentflow-cron.sh          # Standalone crontab wrapper
├── skills/                        # Standalone skill files (v1 compat)
├── prompts/                       # Standalone prompt files (v1 compat)
├── conventions.md                 # Root conventions (v1 compat)
├── docs/
│   ├── architecture.md
│   ├── getting-started.md
│   ├── gap-registry.md
│   ├── comparison.md
│   └── patterns/                  # Patterns from Claude Code source
│       ├── coordinator.md
│       ├── progress-tracker.md
│       ├── permission-classifiers.md
│       ├── streaming-status.md
│       ├── complexity-gating.md
│       └── context-compaction.md
├── setup.sh                       # Install script (detects plugin support)
├── README.md
├── CONTRIBUTING.md
└── LICENSE

Contributing

We welcome contributions! The highest-impact areas:

GitHub Projects adapter — makes AgentFlow free to use (no Asana required)
Linear adapter — popular with dev teams
Stage prompt improvements — better review/test prompts
Documentation — tutorials, examples, translations

See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE.

Automation Levels

AgentFlow operates on a spectrum from semi-automated to fully autonomous:

Level	What You Do	What AgentFlow Does
Manual	Write SPEC.md	—
Semi-automated	Run `/spec-to-asana`, open worker terminals, set crontab	Decomposes spec, creates board, validates tasks
Autonomous	Watch from your phone, handle "Needs Human" cards	Everything else — dispatch, build, review, test, merge, revert, retry, learn

What's autonomous today

Orchestrator sweeps (crontab-driven, no human in the loop)
Task dispatch with transitive priority and conflict detection
Build → lint gate → review → coverage gate → test → merge → integration
Feedback loops with accumulated context and worker rotation
Cost tracking with automatic guardrails (warning at $3/$8, hard stop at $10/$20 per Sonnet/Opus profile)
Dead worker detection and reassignment
System-level learning (LEARNINGS.md retrospectives)
Auto-revert on integration failure
Spec drift detection
Graceful shutdown

What's still manual

Starting worker terminals (you open 3-4 iTerm tabs)
Writing the initial SPEC.md
Handling "Needs Human" cards (blocked tasks, cost-critical, spec changes)
Adjusting crontab frequency

Roadmap

Auto-spawn workers: Plugin mode creates agent teams automatically via TeamCreate
GitHub Projects adapter: Free alternative to Asana — no paid PM tool required
Linear adapter: For teams already on Linear
Web dashboard: Real-time pipeline visualization beyond the Kanban board
Multi-language support: Python, Go, Rust project conventions (currently Node.js/TypeScript focused)
Slack/Discord notifications: Pipeline events pushed to team channels
Cost analytics: Historical cost data, trends, and optimization suggestions

Acknowledgments

Built with Claude Code by Anthropic
Inspired by the gaps in existing AI development tools
Designed through systematic CTO-level review (45 gaps identified and addressed)

AgentFlow — Your Kanban board builds your code.
_{Autonomous AI development pipeline with full observability, deterministic quality gates, and cost tracking.}