AssemblyZero

| You are... | Start with | |------------|------------| | Engineering Leader evaluating AI adoption | Why AssemblyZero? | | AI Strategy / Operations implementing Claude Enterprise | AI Strategy & Operations | | Technical Architect designing agent infrastructure | Technical Architecture | | Security & Compliance approving AI tooling | Secret Guard Architecture | | Practitioner building with Claude Code | Quick 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.

| Metric | Value | |--------|-------| | Issues closed | 493 | | Commits | 912 | | PRs merged | 283 | | Tests | 5,090+ across 134 files | | Active days | 64 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:

| Capability | What It Means | |------------|---------------| | 12+ Concurrent Agents | Multiple Claude agents work in parallel on features, bugs, docs — all under one user identity | | Gemini Reviews Claude | Every design doc and code change is reviewed by Gemini before humans see it | | Enforced Gates | LLD review, implementation review, report generation — gates that can't be skipped | | Secret Guard Architecture | Two-layer hook system protecting credentials from AI session transcripts — 12/17 bypass vectors blocked | | Cerberus PR Governance | GitHub App auto-approves PRs after CI validation — no human bottleneck | | Prompt Economics | System prompt caching (90% savings), Haiku routing, batch generation, budget guards | | 34 Governance Audits | OWASP, 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:

| Challenge | Reality | |-----------|---------| | No coordination | Multiple agents conflict and duplicate work | | No governance | Security teams can't approve ungoverned AI | | No verification | AI-generated code goes unreviewed | | No metrics | Leadership can't prove ROI | | Permission friction | Constant 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

| Component | Function | |-----------|----------| | Single-User Identity | All agents share API credentials, git identity, permission patterns | | Worktree Isolation | Each agent gets its own git worktree - no conflicts, clean PRs | | Credential Rotation | Automatic rotation across API keys when quota exhausted | | Session Coordination | Agents can see what others are working on via session logs |

Agent Roles

| Role | Context | Tasks | |------|---------|-------| | Feature Agent | Full codebase | New functionality, refactors | | Bug Fix Agent | Issue-focused | Specific bug investigation | | Documentation Agent | Docs + code | README, wiki, API docs | | Review Agent | PR diff | Code review assistance | | Audit Agent | Compliance | Security, 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

| Gate | When | What Gemini Checks | |------|------|-------------------| | Issue Review | Before work starts | Requirements clarity, scope, risks | | LLD Review | Before coding | Design completeness, security, testability | | Code Review | Before PR | Quality, patterns, vulnerabilities | | Security Audit | Before merge | OWASP Top 10, dependency risks |

Why Multi-Model Matters

| Single Model | Multi-Model (AssemblyZero) | |--------------|----------------------| | Claude reviews Claude's work | Gemini reviews Claude's work | | Same blind spots | Different model catches different mistakes | | Trust the output | Verify 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

Technical Architecture

LLM Invocation Patterns

| Provider | Class | Use Case | Cost Model | |----------|-------|----------|------------| | Claude CLI (claude -p) | ClaudeCLIProvider | Drafting, implementation | Free (Max subscription) | | Anthropic API | AnthropicProvider | Automatic fallback | Per-token | | Fallback | FallbackProvider | CLI (180s) → API (300s) | Free first, paid if needed | | Gemini | GeminiProvider | Adversarial review only | Free (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:

| Workflow | Nodes | Purpose | |----------|-------|---------| | Issue | 7 | Idea → structured GitHub issue | | Requirements | 10 | Issue → approved LLD (design) | | Implementation Spec | 7 | LLD → concrete implementation instructions | | TDD Implementation | 13 | Spec → code + tests + PR | | Scout | Variable | External intelligence gathering |

Codebase & Document Intelligence (⚠ RAG retired 2026-07-06 → Tiphys)

Retired (ADR-0223). The vector-RAG system below was removed — a similarity engine aimed at a ground-truth problem (grounding the design in real interface signatures). LLD codebase-grounding is now Tiphys: deterministic AST extraction of the real interface surface, no embeddings. The description below is historical.

AssemblyZero previously used 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)

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

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

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

| Metric | Before | After | |--------|--------|-------| | Prompts per session | 15-20 | 2-3 | | Time lost to prompts | 10+ min | < 1 min | | Developer frustration | High | Low |

Permission Friction Deep Dive

34 Governance Audits

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

Audit Categories

| Category | Count | Focus | |----------|-------|-------| | Security & Privacy | 3 | OWASP, GDPR, License compliance | | AI Governance | 7 | Bias, Explainability, Safety, Agentic risks | | Code Quality | 4 | Standards, Accessibility, Capabilities | | Permission Management | 3 | Friction, Permissiveness, Self-audit | | Documentation Health | 6 | Reports, LLD alignment, Terminology | | Extended | 10 | Cost, Structure, References, Wiki | | Meta | 1 | Audit system governance |

Key Audits

| Audit | Standard | What It Checks | |-------|----------|----------------| | 0808 | OWASP LLM 2025 | AI-specific vulnerabilities | | 0809 | OWASP Agentic 2026 | Agent autonomy risks | | 0810 | ISO/IEC 42001 | AI management system | | 0815 | Internal | Permission friction patterns |

Full Audit Catalog

Metrics & KPIs

"How do I prove ROI to leadership?"

Adoption Metrics

| Metric | What It Shows | |--------|---------------| | Active users / Total engineers | Adoption rate | | Sessions per user per week | Engagement depth | | Features shipped with AI assist | Productivity impact |

Friction Metrics

| Metric | Target | |--------|--------| | Permission prompts per session | < 3 | | Time to first productive action | < 30 seconds | | Session abandonment rate | < 5% |

Quality Metrics

| Metric | What It Shows | |--------|---------------| | Gemini first-pass approval rate | Design quality | | PR revision count | Code quality | | Post-merge defects | Overall quality |

Cost Metrics

| Metric | Calculation | |--------|-------------| | Cost per feature | Total API spend / Features shipped | | Cost per agent-hour | API 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:

| Phase | Status | Capability | Impact | |-------|--------|------------|--------| | 1 | COMPLETE | LangGraph state machines (5 workflows) | Gates structurally enforced | | 2 | COMPLETE | SQLite checkpointing (SqliteSaver) | Long tasks survive interruptions | | 3 | Q2 2026 | Supervisor pattern | Autonomous task decomposition | | 4 | Q2 2026 | LangSmith observability | Full dashboards, traces, cost attribution | | 5 | Q3 2026 | Dynamic tool graphs | Context-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

Documentation

Wiki

Full documentation at AssemblyZero Wiki (50 pages):

| Page | Description | |------|-------------| | Technical Architecture | LLM invocation, LangGraph workflows, codebase intelligence | | Metrics Dashboard | Velocity charts, production numbers | | Multi-Agent Orchestration | The headline feature - 12+ concurrent agents | | Requirements Workflow | LLD → Gemini → Approval flow | | Implementation Workflow | Worktree → Code → Reports → PR | | Governance Gates | LLD, implementation, report gates | | How AssemblyZero Learns | Self-improving governance from verdicts | | LangGraph Evolution | Roadmap to enterprise state machines | | Gemini Verification | Multi-model review architecture | | Quick Start | 5-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

| Role | Organization | Relevance | |------|--------------|-----------| | Director, Data Science & AI | AT&T | Led 45-person team, $10M+ annual savings from production AI | | VP Product | Afiniti | AI-powered platform at scale | | AI Strategic Consultant | TX DOT | 76-page enterprise AI strategy |

Why This Project Exists

Having led enterprise AI adoption, I know the blockers:

| Blocker | AssemblyZero 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

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

| Persona | Function | Status | Issue | |---------|----------|--------|-------| | Om | Human orchestrator — pure intent | Active | — | | Moist von Lipwig | Pipeline orchestration (Issue → PR) | Implemented | #305 | | Brutha | RAG vector store — perfect recall | Implemented | #113 | | The Librarian | Document retrieval for LLDs | Implemented | #88 | | Hex | Codebase intelligence — AST indexing | Implemented | #92 | | The Historian | Duplicate detection before drafting | Implemented | #91 | | Captain Angua | External intelligence scout | Implemented | #93 | | Lu-Tze | Repository hygiene — constant sweeping | Implemented | #94 | | DEATH | Documentation reconciliation | Manual | #114 | | Cerberus | PR governance — three heads, one gate | Implemented | #736 | | Vimes | Regression guardian — deep suspicion | Planned | — | | Ponder Stibbons | Auto-fix compositor | Planned | #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