convez.ai
AgenteAutomaçãoAvançado
martymcenroe

AssemblyZero

martymcenroe/AssemblyZero

Orquestração enterprise de múltiplos agentes Claude e Gemini com governança completa

Ver no GitHub
BomPluginScore · de 0 a 100

Framework de orquestração multi-agent parametrizável para coordenar 12+ agentes Claude e Gemini em paralelo sob uma única identidade. Inclui governança enforçada, verificação cruzada entre modelos, arquitetura Secret Guard para proteção de credenciais e gates de validação que não podem ser pulados.

Instalação

$npx convez-ai martymcenroe/AssemblyZero

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
113
Forks
2
Acompanhando
0
Saúde
57%
Último commit
há 3 dias
Versão
—
Issues abertas
734
Contribuidores
3

Casos de uso

  • Automação de desenvolvimento de software com múltiplos agentes especializados
  • Processamento paralelo de tarefas de engenharia (features, bugs, docs, reviews)
  • Verificação cruzada de design e código entre modelos diferentes
  • Implementação de governança e auditoria em sistemas de IA autônomos

Veredito

Ferramenta sólida de produção com 70 dias de desenvolvimento contínuo, 912 commits e 493 issues fechadas. Relevante para engenheiros que precisam orquestrar múltiplos agentes com garantias de governança e segurança, mas requer expertise avançada em arquitetura distribuída e integrações multi-modelo.

README

A tradução para o português deste README ainda está na fila.

AssemblyZero

CI

Multi-Agent Orchestration Platform for Enterprise AI Development

Run 12+ AI agents concurrently. One identity. Full governance. Measurable ROI.


Start Here

You are...Start with
Engineering Leader evaluating AI adoptionWhy AssemblyZero?
AI Strategy / Operations implementing Claude EnterpriseAI Strategy & Operations
Technical Architect designing agent infrastructureTechnical Architecture
Security & Compliance approving AI toolingSecret Guard Architecture
Practitioner building with Claude CodeQuick Start

Production Evidence: 70 Days, 64 Active, 493 Issues Closed

This isn't theoretical. AssemblyZero has been under continuous development for 70 days with contributions on 64 of them (91.4%). Only 6 days off since January 10, 2026.

MetricValue
Issues closed493
Commits912
PRs merged283
Tests5,090+ across 134 files
Active days64 of 70 (91.4%)

Daily Activity Log → · Metrics → · March 2026 Velocity →


The Headline: Multi-Agent + Multi-Model

graph TD
    subgraph Intent["HUMAN ORCHESTRATOR"]
        O["Human Intent<br/>& Oversight"]
    end

    subgraph LG["LANGGRAPH WORKFLOWS"]
        W["5 State Machines<br/>SQLite Checkpointing"]
    end

    subgraph Agents["CLAUDE AGENTS (12+)"]
        A["Feature | Bug Fix<br/>Docs | Review"]
    end

    subgraph Gemini["GEMINI VERIFICATION"]
        G["LLD Review | Code Review<br/>Security | Quality"]
    end

    subgraph Gov["GOVERNANCE GATES"]
        M["Requirements | Implementation<br/>Reports | Audit Trail"]
    end

    O --> LG
    LG --> Agents
    Agents --> Gemini
    Gemini --> Gov

What makes AssemblyZero different:

CapabilityWhat It Means
12+ Concurrent AgentsMultiple Claude agents work in parallel on features, bugs, docs — all under one user identity
Gemini Reviews ClaudeEvery design doc and code change is reviewed by Gemini before humans see it
Enforced GatesLLD review, implementation review, report generation — gates that can't be skipped
Secret Guard ArchitectureTwo-layer hook system protecting credentials from AI session transcripts — 12/17 bypass vectors blocked
Cerberus PR GovernanceGitHub App auto-approves PRs after CI validation — no human bottleneck
Prompt EconomicsSystem prompt caching (90% savings), Haiku routing, batch generation, budget guards
34 Governance AuditsOWASP, GDPR, NIST AI Safety — adversarial audits that find violations

The Problem We Solve

AI coding assistants like Claude Code and GitHub Copilot are transforming development. But enterprise adoption stalls because:

ChallengeReality
No coordinationMultiple agents conflict and duplicate work
No governanceSecurity teams can't approve ungoverned AI
No verificationAI-generated code goes unreviewed
No metricsLeadership can't prove ROI
Permission frictionConstant approval prompts destroy flow state

Organizations run pilots. Developers love the tools. Then adoption plateaus at 10-20% because the infrastructure layer is missing.

AssemblyZero is that infrastructure layer.


Multi-Agent Orchestration

The headline feature: run 12+ AI agents concurrently under single-user identity with full coordination.

How It Works

ComponentFunction
Single-User IdentityAll agents share API credentials, git identity, permission patterns
Worktree IsolationEach agent gets its own git worktree - no conflicts, clean PRs
Credential RotationAutomatic rotation across API keys when quota exhausted
Session CoordinationAgents can see what others are working on via session logs

Agent Roles

RoleContextTasks
Feature AgentFull codebaseNew functionality, refactors
Bug Fix AgentIssue-focusedSpecific bug investigation
Documentation AgentDocs + codeREADME, wiki, API docs
Review AgentPR diffCode review assistance
Audit AgentComplianceSecurity, privacy audits

Result: One engineer orchestrating 12+ agents can accomplish what previously required a team.

Full Architecture Documentation


Gemini Verification Layer

The key differentiator: Claude builds, Gemini reviews.

This isn't just "two models" - it's adversarial verification where one AI checks another's work before humans approve.

Four Review Gates

GateWhenWhat Gemini Checks
Issue ReviewBefore work startsRequirements clarity, scope, risks
LLD ReviewBefore codingDesign completeness, security, testability
Code ReviewBefore PRQuality, patterns, vulnerabilities
Security AuditBefore mergeOWASP Top 10, dependency risks

Why Multi-Model Matters

Single ModelMulti-Model (AssemblyZero)
Claude reviews Claude's workGemini reviews Claude's work
Same blind spotsDifferent model catches different mistakes
Trust the outputVerify the output
"It looks good to me"Structured JSON verdicts: APPROVE/BLOCK

Model Verification

AssemblyZero detects silent model downgrades:

  • Gemini CLI sometimes returns Flash when you request Pro
  • Our tools verify the actual model used in the response
  • If downgraded, the review is flagged as invalid

Gemini Architecture Details


Technical Architecture

LLM Invocation Patterns

ProviderClassUse CaseCost Model
Claude CLI (claude -p)ClaudeCLIProviderDrafting, implementationFree (Max subscription)
Anthropic APIAnthropicProviderAutomatic fallbackPer-token
FallbackFallbackProviderCLI (180s) → API (300s)Free first, paid if needed
GeminiGeminiProviderAdversarial review onlyFree (API quota)

Claude is invoked via claude -p with --tools "" and --strict-mcp-config — no tools, no MCP, deterministic side-effect-free calls. The Anthropic API exists only as a paid fallback for resilience.

LangGraph State Machines

All workflows are LangGraph StateGraph instances with typed state and SQLite checkpointing:

WorkflowNodesPurpose
Issue7Idea → structured GitHub issue
Requirements10Issue → approved LLD (design)
Implementation Spec7LLD → concrete implementation instructions
TDD Implementation13Spec → code + tests + PR
ScoutVariableExternal intelligence gathering

Codebase & Document Intelligence (RAG)

AssemblyZero uses a local RAG system built on ChromaDB and all-MiniLM-L6-v2 embeddings:

  • Document retrieval (The Librarian) — injects relevant ADRs, standards, and past LLDs into design prompts
  • Codebase retrieval (Hex) — AST-based Python indexing with vector search for implementation context
  • Duplicate detection (The Historian) — checks for similar past issues before drafting
  • Token budget management — trims context to fit LLM prompt limits
  • Local-only — no data leaves the developer machine (see ADR-0212)

Full Technical Architecture → | RAG Architecture →


Governance Gates

Three mandatory checkpoints that cannot be bypassed:

Idea → Issue → LLD Review → Coding → Implementation Review → PR → Report Generation → Merge
                ↑                      ↑                           ↑
           Gemini Gate            Gemini Gate                 Auto-Generated

LLD Review Gate

Before writing ANY code:

  1. Design document submitted to Gemini
  2. Gemini evaluates completeness, security, testability
  3. APPROVE → Proceed to coding
  4. BLOCK → Revise design first

Cost of design fix: 1 hour Cost of code fix: 8 hours Cost of production fix: 80 hours

Implementation Review Gate

Before creating ANY PR:

  1. Implementation report + test report submitted to Gemini
  2. Gemini evaluates quality, coverage, security
  3. APPROVE → Create PR
  4. BLOCK → Fix issues first

Report Generation Gate

Before merge, auto-generate:

  • implementation-report.md - What changed and why
  • test-report.md - Full test output, coverage metrics

Gate Implementation Details


Permission Friction Management

Permission prompts are the #1 adoption killer.

Every "Allow this command?" prompt breaks flow state. Developers either:

  • Click "Allow" without reading (security risk)
  • Get frustrated and stop using the tool (adoption failure)

Pattern Detection

AssemblyZero identifies:

  • Commands that always get approved → Add to allow list
  • Commands that always get denied → Add to deny list
  • Novel patterns → Flag for review

Measurable Reduction

MetricBeforeAfter
Prompts per session15-202-3
Time lost to prompts10+ min< 1 min
Developer frustrationHighLow

Permission Friction Deep Dive


34 Governance Audits

Audits designed with an adversarial philosophy: they exist to find violations, not confirm compliance.

Audit Categories

CategoryCountFocus
Security & Privacy3OWASP, GDPR, License compliance
AI Governance7Bias, Explainability, Safety, Agentic risks
Code Quality4Standards, Accessibility, Capabilities
Permission Management3Friction, Permissiveness, Self-audit
Documentation Health6Reports, LLD alignment, Terminology
Extended10Cost, Structure, References, Wiki
Meta1Audit system governance

Key Audits

AuditStandardWhat It Checks
0808OWASP LLM 2025AI-specific vulnerabilities
0809OWASP Agentic 2026Agent autonomy risks
0810ISO/IEC 42001AI management system
0815InternalPermission friction patterns

Full Audit Catalog


Metrics & KPIs

"How do I prove ROI to leadership?"

Adoption Metrics

MetricWhat It Shows
Active users / Total engineersAdoption rate
Sessions per user per weekEngagement depth
Features shipped with AI assistProductivity impact

Friction Metrics

MetricTarget
Permission prompts per session< 3
Time to first productive action< 30 seconds
Session abandonment rate< 5%

Quality Metrics

MetricWhat It Shows
Gemini first-pass approval rateDesign quality
PR revision countCode quality
Post-merge defectsOverall quality

Cost Metrics

MetricCalculation
Cost per featureTotal API spend / Features shipped
Cost per agent-hourAPI spend / Active agent hours
ROI(Time saved × Engineer cost) / Platform cost

Full KPI Framework


Architecture: LangGraph State Machines

AssemblyZero workflows run as LangGraph state machines with SQLite checkpointing:

PhaseStatusCapabilityImpact
1COMPLETELangGraph state machines (5 workflows)Gates structurally enforced
2COMPLETESQLite checkpointing (SqliteSaver)Long tasks survive interruptions
3Q2 2026Supervisor patternAutonomous task decomposition
4Q2 2026LangSmith observabilityFull dashboards, traces, cost attribution
5Q3 2026Dynamic tool graphsContext-aware tool selection

Full Roadmap and Vision


Quick Start

1. Clone and Install

git clone https://github.com/martymcenroe/AssemblyZero.git
cd AssemblyZero
poetry install

2. Configure Your Project

mkdir -p YourProject/.claude
cp AssemblyZero/.claude/project.json.example YourProject/.claude/project.json
# Edit project.json with your project details

3. Generate Configs

poetry run python tools/assemblyzero-generate.py --project YourProject

4. Start Working

The generated configs include:

  • Permission patterns that eliminate friction
  • Slash commands for common operations
  • Hooks for pre/post tool execution

Detailed Setup Guide


Documentation

Wiki

Full documentation at AssemblyZero Wiki (50 pages):

PageDescription
Technical ArchitectureLLM invocation, LangGraph workflows, codebase intelligence
Metrics DashboardVelocity charts, production numbers
Multi-Agent OrchestrationThe headline feature - 12+ concurrent agents
Requirements WorkflowLLD → Gemini → Approval flow
Implementation WorkflowWorktree → Code → Reports → PR
Governance GatesLLD, implementation, report gates
How AssemblyZero LearnsSelf-improving governance from verdicts
LangGraph EvolutionRoadmap to enterprise state machines
Gemini VerificationMulti-model review architecture
Quick Start5-minute setup guide

For Different Audiences

See Start Here at the top of this page for persona-based navigation.


About

AssemblyZero was built by Martin McEnroe, applying 29 years of enterprise technology leadership to the emerging challenge of scaling AI coding assistants across engineering organizations.

Relevant Experience

RoleOrganizationRelevance
Director, Data Science & AIAT&TLed 45-person team, $10M+ annual savings from production AI
VP ProductAfinitiAI-powered platform at scale
AI Strategic ConsultantTX DOT76-page enterprise AI strategy

Why This Project Exists

Having led enterprise AI adoption, I know the blockers:

BlockerAssemblyZero Solution
"Security won't approve ungoverned AI"34 audits, Gemini gates, secret guard hooks, 62-repo security audit
"We can't measure productivity"KPI framework, friction tracking, per-call cost attribution
"Agents conflict with each other"Worktree isolation, single-user identity model
"PRs block waiting for human review"Cerberus GitHub App auto-approves after CI validation
"Developers hate the permission prompts"Pattern detection, friction analysis, auto-remediation
"Token costs are unpredictable"Prompt caching (90% savings), budget guards, circuit breakers
"It's just pilots, not real adoption"Infrastructure that scales — 492 issues closed in 68 days

Technical Foundation

  • LangChain, LangGraph, LangSmith - Hands-on implementation experience
  • 21 US Patents - Innovation track record
  • CISSP, CCSP, AWS ML Specialty - Security and ML credentials
  • GitHub Copilot, Claude Code - Daily production use

The Bottom Line

This isn't theoretical. It's production infrastructure I use daily to orchestrate 12+ AI agents with full governance.

The code in this repo is the same code that:

  • Runs the Gemini verification gates
  • Protects secrets via hook-based guard architecture
  • Governs PR merges via the Cerberus GitHub App
  • Optimizes prompt costs (90% savings via caching and routing)
  • Tracks permission friction patterns
  • Generates the audit reports
  • Bypasses Windows' 32K-char limit with a temp-dir CLAUDE.md hack

If you're scaling AI coding assistants across an engineering organization, this is the infrastructure layer you need.


The Discworld Personas

Workflows are named after Terry Pratchett's Discworld characters. Each persona defines the agent's operational philosophy — making system behavior intuitive and memorable.

graph TB
    subgraph Orch["ORCHESTRATION"]
        Om["Om<br/><i>Human</i>"]
        Moist["Moist<br/><i>Pipeline</i>"]
    end

    subgraph Intel["INTELLIGENCE"]
        Lib["Librarian<br/><i>Doc Retrieval</i>"]
        Hex["Hex<br/><i>Code RAG</i>"]
        Hist["Historian<br/><i>Duplicates</i>"]
        Angua["Angua<br/><i>Scout</i>"]
    end

    subgraph Found["FOUNDATION"]
        Brutha["Brutha<br/><i>Vector Store</i>"]
    end

    subgraph Maint["MAINTENANCE"]
        LuTze["Lu-Tze<br/><i>Janitor</i>"]
        DEATH["DEATH<br/><i>Reconciliation</i>"]
    end

    Om --> Moist
    Moist --> Intel
    Lib --> Brutha
    Hex --> Brutha
    Hist --> Brutha
PersonaFunctionStatusIssue
OmHuman orchestrator — pure intentActive—
Moist von LipwigPipeline orchestration (Issue → PR)Implemented#305
BruthaRAG vector store — perfect recallImplemented#113
The LibrarianDocument retrieval for LLDsImplemented#88
HexCodebase intelligence — AST indexingImplemented#92
The HistorianDuplicate detection before draftingImplemented#91
Captain AnguaExternal intelligence scoutImplemented#93
Lu-TzeRepository hygiene — constant sweepingImplemented#94
DEATHDocumentation reconciliationManual#114
CerberusPR governance — three heads, one gateImplemented#736
VimesRegression guardian — deep suspicionPlanned—
Ponder StibbonsAuto-fix compositorPlanned#307

Full Cast & Architecture → | Architecture Diagrams →

"A man is not dead while his name is still spoken." GNU Terry Pratchett


License

PolyForm Noncommercial 1.0.0

Ver o original no GitHub

Bom para

Relacionados