AgentFlow
Install

Open source · MIT

Stop wrestling coding agents. Ship clean, reviewable PRs.

An opinionated engineering loop that kills scope creep. Grill assumptions upfront, slice work into bite-sized PRs, and ship production-ready code - one verified slice at a time.

Star on GitHub
Works withClaude CodeCodexCursor
~/project · agentflow
❯ "Figure out how our auth works"
  ● Subagent research: tracing session middleware & schemas
  ✓ Research saved to .agentflow/auth/research.md

❯ "Great, let's implement OAuth migration based on this research"        
  ● Grilling architecture before writing code:

  ? 1 · Session schema: modify table or add OAuth rows?
    ▲ Risk: Altering current table invalidates active tokens
    ✓ Recommendation: Add separate oauth_accounts table

  ? 2 · Migration rollout: single commit or phased?
    ✓ Recommendation: Expand-then-contract across 2 PRs

❯ "Agreed, let's go with your recommendations"        
  ● Slicing architecture into 3 discrete PR phases:
    ├─ PR #1 · Token schema & database models
    ├─ PR #2 · OAuth callback & session linking
    └─ PR #3 · Cleanup & legacy deprecation
  ✓ Plan saved to .agentflow/auth/plan.md

❯ "Let's implement PR #1"        
  ● Building slice 1: token encryption & schema
  ● Subagent review: passed clean · 0 defects
  ✓ PR #1 ready to merge

The loop

ResearchGrillPlanPRReviewCommit

Literally every step is optional and invoked with plain words - zero slash commands required. Run deep research, grill edge cases, or jump straight to a single PR: AgentFlow adapts to the task while keeping changes disciplined.

  1. 1
    Research

    Learn how it works

    optional

    Ask the agent to investigate an unfamiliar area. Findings are saved under .agentflow/<feature>/research/ - ready to attach in fresh sessions.

  2. 2
    Grill

    Sharpen the idea

    core

    The agent surfaces assumptions, explains trade-offs, and recommends answers in conversation - until nothing important is left unclear.

  3. 3
    Plan

    Slice the work into PRs

    Larger work is split into PR-sized slices: each one complete, checkable on its own, and briefable to a fresh chat. Saved to .agentflow/<slug>/plan.md.

  4. 4
    Implement

    Implement one slice

    The first unchecked PR and nothing beyond it. Stay in this chat, start a fresh one, or write code directly - the plan travels with you.

  5. 5
    Review

    Subagent review

    A subagent reviews the slice with what changed and why. Local fixes land automatically; critical choices come back as decisions for you.

  6. 6
    Commit

    Your review, then commit

    Read the diff yourself, then commit the way you always do. Git and pull requests remain the center of the workflow.

  7. 7
    Handoff

    Refresh the context

    optional

    When the chat gets noisy, handoff saves what shipped, what changed, and which PR comes next. Attach it to a fresh chat and continue.

    Steps 4–7 repeat until every PR in the plan ships

  8. 8
    Document

    Archive or document

    optional

    Turn the shipped change into a durable project page for the next session - or skip it when no page is needed.

Two paths

One prompt. Two different outcomes.

A real task from production: adding project duplication. See how an unguided agent drifts into silent bugs and tangled diffs, versus how AgentFlow engineers clean, verified PRs.

The identical starting prompt
human input
❯ "Let's implement project duplication so users can duplicate an existing project."
Phase 01

Codebase Discovery

Before touching code: does the agent investigate existing architecture?

Without AgentFlow
0 research · Blind leap

Rushes straight into modifying files

Starts editing code without reading database schemas, S3 asset references, or platform host uniqueness rules.

● Unguided Agent: "Sure! Creating the duplication endpoint, copying S3 buckets, and configuring new custom domains now..."
Msrc/server/routes/projects.ts
Msrc/db/schema.prisma
Msrc/components/editor/ForkModal.tsx

Blindly edits 3 critical files simultaneously on raw assumptions.

With AgentFlow
System research · Constraint discovery

Uncovers hidden constraints and risks

Inspects schemas, writes structured research docs into .agentflow/, and catches critical constraints before writing code.

● Subagent research: tracing schemas & storage

1. Traced storage schema: S3 assets linked via d_files claim IDs
2. Audited cascade routes: projects, workspaces, custom domains
▲ Hidden constraint: deleting original project purges shared S3 files!

✓ Research saved to .agentflow/project-duplication/research/
  ├─ storage-lifecycle.md (S3 multi-claim reference map)
  └─ domain-routing.md (ingress collision risks)

Pausing code edits to clarify trade-offs with developer
Phase 02

Architectural Decisions

When forks arise: does the agent guess in secret or clarify with options?

Without AgentFlow
0 questions · Silent guesswork

Hallucinates assumptions that break data

Makes catastrophic architectural choices in secret without confirming with the developer:

S3 Data Loss:Links fork directly to original S3 URLs without multi-claim tracking. Deleting the original project will permanently purge assets in the fork.
Host Collision:Auto-generates duplicate domain DNS configs, colliding with platform host uniqueness rules.
With AgentFlow
Proactive inquiry · Settled plan

Surfaces critical forks & locks contract

Translates research into targeted questions with recommended paths, then locks decisions in a plan:

● Agent: "Before I write code, I found a critical S3 storage constraint. Let's settle two architectural forks:"
? Q1 - Asset storage: share S3 claims or duplicate file bytes?
✓ (b) Share claims via d_files + patch delete trigger [Recommended]
? Q2 - Custom domains: how should routing behave on fork?
✓ (a) Duplicate project only; defer domain to manual publish [Recommended]
Developer approved recommendationsLocked into 2 PR slices
Phase 03

Execution & Review

When shipping: is it a massive unreviewed dump or verified PR slices?

Without AgentFlow
Monolithic dump · 0 reviews

One tangled 48-file change set

A massive, chaotic change set mixing frontend buttons, DB schemas, broken migrations, and hardcoded tokens:

48 files modified+1,840 / -620 lines
✕DB migrations, UI buttons, and runner sync tangled together
✕Hardcoded runner tokens committed directly in clone script
✕Zero subagent review or automated verification before handoff
With AgentFlow
Sliced PR loop · Self-auditing

Build SliceReviewCommitNext Slice

Executes in small, isolated pull requests. Each slice is audited by a subagent before moving to the next:

PR #1 · Storage safetymerged

Patched deletion to retain shared S3 claims. Isolated migration.

PR #2 · Duplicate APImerged

POST /duplicate endpoint with safe rollback and sanitized tokens.

Subagent review passed clean on each slice
Phase 04

Final Outcome

What actually lands in the repository?

Without AgentFlow
Crooked commit · Revert required

Unmergeable code, wasted engineering time

The implementation is dangerous to merge. The developer must roll back the branch and start over from scratch.

Result: Revert required · 0 PRs merged

Hidden S3 deletion bug would destroy user assets. All 48 files reverted.

With AgentFlow
Production-ready · Merged

Two clean PRs with zero regressions

Every edge case accounted for, shared S3 storage 100% safe, clean git history, and ready for production deployment.

Result: Ready to deploy · 2 discrete PRs

2 bite-sized PRs, 0 lost bytes, verified review loop, and 100% human control.

Without AgentFlow: 48 files scrambled

Zero questions asked upfront. S3 lifecycle broken, domain rules ignored, and hours spent undoing a messy commit.

With AgentFlow: 2 verified, bite-sized PRs

Codebase researched and architectural forks settled before line 1 of code. Safe S3 reuse, self-auditing reviews, and total human control.

The capabilities

One skill. Built-in capabilities.

AgentFlow is a single skill that orchestrates the entire engineering loop. You talk in plain words - the agent investigates, clarifies, and delivers in verified slices.

Research

Explore unfamiliar code and save findings to .agentflow/research/

Grill

Question assumptions and clarify architectural trade-offs in chat

Plan

Slice larger work into reviewable, PR-sized milestones

Code review

Subagent audits the slice for defects, risks, and regressions

Handoff

Pass context seamlessly when continuing work in a fresh session

TDD

Drive implementation one red-green test slice at a time

Document

Turn completed work into permanent project documentation

Install AgentFlow once into the agents you already use.

The principles

What AgentFlow believes

Specs ≠ shipped code

Research and plans are working artifacts first. Commit them, keep them local, or delete them after the PR - AgentFlow never prescribes their lifetime.

Ceremony is a tax

No spec tree to adopt, no commands to learn before code starts. You clarify the task and the agent carries the workflow from there.

Discipline lives in the loop

Decisions settle before implementation. Scope stays one reviewable slice, and that slice is reviewed before the next begins. Optional steps can be skipped - the order cannot.

Compare

Not an all-in-one system

Spec-driven frameworks move intent into documents and drive the agent from them. AgentFlow adds a small, opinionated loop to the way you already build software.

vs OpenSpec

OpenSpec manages proposals, requirements, designs, and completed changes - when specs are the center of the process. AgentFlow stays on one plan and a handoff: no spec tree to adopt.

vs Spec Kit

Spec Kit runs a full phase-based process - constitution, specs, plans, tasks. AgentFlow gives the order of work and leaves the rest of your process where it already lives.

vs unstructured chat

Fine for a small fix. On larger changes, chat loses decisions and grows unreviewable scope. AgentFlow keeps both out of history - one slice at a time.

Install

One command, then just work

Pick the agents you use, choose project or global scope, and let AgentFlow guide your next task.

Init installs every skill through the skills CLI, then asks whether to set up docs - it writes AGENTFLOW.md and adds a pointer to AGENTS.md. Updates are non-interactive after setup.