Maverick: An AI-Driven Bead-Based Development Workflow Orchestration Framework

Maverick is a Python CLI tool that enables full AI-driven development lifecycle management via the ACP protocol and YAML DSL. It covers everything from generating flight plans from PRDs to code implementation, review, human escalation, and commit organization. At its core is the bead-based workflow graph model, which abstracts work units in development into beads and connects them into a dependency graph, enabling human-AI collaborative work. This solves the process complexity issue caused by the proliferation of AI tools, balancing efficiency gains with development control and code quality.

The Paradox of Software Development

Today, with the emergence of numerous AI-assisted programming tools, developers face the dilemma of more tools but more complex workflows—how to enjoy AI efficiency while maintaining control over the process and quality assurance?

Core Philosophy: Everything is a Bead

Maverick's design philosophy is to abstract any work unit in software development (feature implementation, code review, manual verification, etc.) into a bead, forming a complete workflow through dependency relationships. This abstraction brings two key advantages:

1. Eliminates the fragmentation of traditional development stages, enabling smooth state transitions;
2. Provides a clear interface for human-AI collaboration—when AI encounters obstacles, it creates a manual review bead, and humans can approve/reject/postpone via simple commands.

Maverick divides the development process into four core stages, enabling a complete pipeline from PRD to code commit:

Planning Phase (plan)

Four parallel AI agents in the pre-flight briefing room analyze the PRD: scope definition, codebase analysis, acceptance criteria drafting, and devil's advocacy (risk identification), ultimately generating a flight plan with success criteria and scope.

Refueling Phase (refuel)

Decompose the flight plan into specific work units (including acceptance criteria, file scope, and verification commands), create epic and task-level beads via the bd tool to ensure parallelism and execution order.

Flight Phase (fly)

Iterate over ready beads and execute the implementation → gate checks (formatting/lint/tests) → acceptance criteria check → specification check → review → commit process. If the review fails, automatic fixes are attempted (up to three rounds), and if it still fails, it escalates to manual review.

Landing Phase (land)

The AI curator organizes commit history: compresses fix commits, strips bead IDs, writes standardized commit messages, sorts logical flows, skips immutable commits, and cleans up the runway knowledge base.

Deterministic Specification Compliance

Introduce a project-specific specification checker based on Grep to intercept anti-patterns (e.g., runtime code unwrap() calls, blocking calls in async functions). Encode team conventions into automatically enforced rules to reduce review rounds.

Enriched Code Reviews

Review agents receive full context: work unit specifications, pre-flight briefings (risk assessments), and runway history. After all beads are completed, cross-bead aggregate reviews are performed to check architectural consistency and dead code, identifying issues that are hard to detect in individual reviews.

Elegant Human-in-the-Loop Design

When AI fix attempts are exhausted, a manual assumption bead with full context is created. Humans can intervene via mobile terminals using simple commands (approve/reject/postpone). Rejection triggers a correction bead to flow back, maintaining workflow continuity.

Continuous Flight and Multi-Terminal Collaboration

• Continuous Flight Mode: maverick fly --watch continuously polls for new beads;
• Multi-Terminal Division: One terminal runs AI agents, one handles planning/refueling, one processes the manual review queue, enabling a parallel human-AI workflow.

Technical Implementation Details

• Developed based on Python 3.11+, using Thespian actor system for inter-process message passing (multiprocTCPBase);
• Version control uses Jujutsu (jj), leveraging snapshot/rollback safety features and working in an isolated space without affecting the developer's directory;
• Multi-Provider Routing: Supports task-based allocation of Claude, Copilot, Gemini, allowing flexible selection of AI services.

Runway Knowledge Base

Maintain a runway directory to record bead results, review findings, and fix history, building project-specific context so AI agents gradually learn the codebase's characteristics and improve generation quality.

Maverick represents a paradigm shift from AI-assisted tools to AI-native workflows—not automating existing steps, but reorganizing development processes for the AI era. Elements like the bead model, human-AI collaboration interface, specification checks, and enriched reviews form a complete solution, offering engineering teams that pursue a balance between efficiency and quality a new option worth exploring.