Multi-agent orchestration platform for enterprise AI development. Run 12+ AI agents concurrently with full governance, Gemini-powered code review, and enforced quality gates. Solves coordination, verification, and metrics challenges that stall enterprise AI adoption.
Add this skill
npx mdskills install martymcenroe/assemblyzeroComprehensive documentation but lacks the executable agent instructions a skill requires
1# AssemblyZero23[](https://github.com/martymcenroe/AssemblyZero/actions/workflows/ci.yml)45## Multi-Agent Orchestration Platform for Enterprise AI Development67> **Run 12+ AI agents concurrently. One identity. Full governance. Measurable ROI.**89---1011## Production Evidence: 207 Issues in 27 Days1213This isn't theoretical. AssemblyZero has processed **207 issues** (159 closed) in 27 days:1415```16Issues closed per day (Central Time):172026-01-21: 12 ############182026-02-02: 23 #######################192026-02-03: 55 #######################################################202026-02-04: 31 ###############################21```2223**Average velocity:** 5.9 issues/day | **Peak:** 55 issues in one day | **[Full Metrics →](https://github.com/martymcenroe/AssemblyZero/wiki/Metrics)**2425---2627## The Headline: Multi-Agent + Multi-Model2829```mermaid30graph TD31 subgraph Intent["HUMAN ORCHESTRATOR"]32 O["Human Intent<br/>& Oversight"]33 end3435 subgraph LG["LANGGRAPH WORKFLOWS"]36 W["5 State Machines<br/>SQLite Checkpointing"]37 end3839 subgraph Agents["CLAUDE AGENTS (12+)"]40 A["Feature | Bug Fix<br/>Docs | Review"]41 end4243 subgraph Gemini["GEMINI VERIFICATION"]44 G["LLD Review | Code Review<br/>Security | Quality"]45 end4647 subgraph Gov["GOVERNANCE GATES"]48 M["Requirements | Implementation<br/>Reports | Audit Trail"]49 end5051 O --> LG52 LG --> Agents53 Agents --> Gemini54 Gemini --> Gov55```5657**What makes AssemblyZero different:**5859| Capability | What It Means |60|------------|---------------|61| **12+ Concurrent Agents** | Multiple Claude agents work in parallel on features, bugs, docs - all under one user identity |62| **Gemini Reviews Claude** | Every design doc and code change is reviewed by Gemini 3 Pro before humans see it |63| **Enforced Gates** | LLD review, implementation review, report generation - gates that can't be skipped |64| **34 Governance Audits** | OWASP, GDPR, NIST AI Safety - adversarial audits that find violations |6566---6768## The Problem We Solve6970AI coding assistants like Claude Code and GitHub Copilot are transforming development. **But enterprise adoption stalls** because:7172| Challenge | Reality |73|-----------|---------|74| **No coordination** | Multiple agents conflict and duplicate work |75| **No governance** | Security teams can't approve ungoverned AI |76| **No verification** | AI-generated code goes unreviewed |77| **No metrics** | Leadership can't prove ROI |78| **Permission friction** | Constant approval prompts destroy flow state |7980Organizations run pilots. Developers love the tools. Then adoption plateaus at 10-20% because **the infrastructure layer is missing**.8182**AssemblyZero is that infrastructure layer.**8384---8586## Multi-Agent Orchestration8788The headline feature: **run 12+ AI agents concurrently under single-user identity with full coordination**.8990### How It Works9192| Component | Function |93|-----------|----------|94| **Single-User Identity** | All agents share API credentials, git identity, permission patterns |95| **Worktree Isolation** | Each agent gets its own git worktree - no conflicts, clean PRs |96| **Credential Rotation** | Automatic rotation across API keys when quota exhausted |97| **Session Coordination** | Agents can see what others are working on via session logs |9899### Agent Roles100101| Role | Context | Tasks |102|------|---------|-------|103| **Feature Agent** | Full codebase | New functionality, refactors |104| **Bug Fix Agent** | Issue-focused | Specific bug investigation |105| **Documentation Agent** | Docs + code | README, wiki, API docs |106| **Review Agent** | PR diff | Code review assistance |107| **Audit Agent** | Compliance | Security, privacy audits |108109**Result:** One engineer orchestrating 12+ agents can accomplish what previously required a team.110111**[Full Architecture Documentation](https://github.com/martymcenroe/AssemblyZero/wiki/Multi-Agent-Orchestration)**112113---114115## Gemini Verification Layer116117**The key differentiator: Claude builds, Gemini reviews.**118119This isn't just "two models" - it's **adversarial verification** where one AI checks another's work before humans approve.120121### Four Review Gates122123| Gate | When | What Gemini Checks |124|------|------|-------------------|125| **Issue Review** | Before work starts | Requirements clarity, scope, risks |126| **LLD Review** | Before coding | Design completeness, security, testability |127| **Code Review** | Before PR | Quality, patterns, vulnerabilities |128| **Security Audit** | Before merge | OWASP Top 10, dependency risks |129130### Why Multi-Model Matters131132| Single Model | Multi-Model (AssemblyZero) |133|--------------|----------------------|134| Claude reviews Claude's work | Gemini reviews Claude's work |135| Same blind spots | Different model catches different mistakes |136| Trust the output | Verify the output |137| "It looks good to me" | Structured JSON verdicts: APPROVE/BLOCK |138139### Model Verification140141AssemblyZero detects **silent model downgrades**:142- Gemini CLI sometimes returns Flash when you request Pro143- Our tools verify the actual model used in the response144- If downgraded, the review is flagged as invalid145146**[Gemini Architecture Details](https://github.com/martymcenroe/AssemblyZero/wiki/Gemini-Verification)**147148---149150## Technical Architecture151152### LLM Invocation Patterns153154| Provider | Class | Use Case | Cost Model |155|----------|-------|----------|------------|156| **Claude CLI** (`claude -p`) | `ClaudeCLIProvider` | Drafting, implementation | Free (Max subscription) |157| **Anthropic API** | `AnthropicProvider` | Automatic fallback | Per-token |158| **Fallback** | `FallbackProvider` | CLI (180s) → API (300s) | Free first, paid if needed |159| **Gemini** | `GeminiProvider` | Adversarial review only | Free (API quota) |160161Claude 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.162163### LangGraph State Machines164165All workflows are LangGraph `StateGraph` instances with typed state and SQLite checkpointing:166167| Workflow | Nodes | Purpose |168|----------|-------|---------|169| **Issue** | 7 | Idea → structured GitHub issue |170| **Requirements** | 10 | Issue → approved LLD (design) |171| **Implementation Spec** | 7 | LLD → concrete implementation instructions |172| **TDD Implementation** | 13 | Spec → code + tests + PR |173| **Scout** | Variable | External intelligence gathering |174175### Codebase Intelligence (RAG-Like)176177AssemblyZero uses deterministic RAG-like techniques — **not vector embeddings** — for codebase understanding:178- **AST summarization** extracts function signatures and class hierarchies179- **Pattern scanning** finds similar implementations by structure180- **Token budget management** trims context to ~60KB181- **Section-aware truncation** preserves important sections182183**[Full Technical Architecture →](https://github.com/martymcenroe/AssemblyZero/wiki/Technical-Architecture)**184185---186187## Governance Gates188189Three mandatory checkpoints that **cannot be bypassed**:190191```192Idea → Issue → LLD Review → Coding → Implementation Review → PR → Report Generation → Merge193 ↑ ↑ ↑194 Gemini Gate Gemini Gate Auto-Generated195```196197### LLD Review Gate198199Before writing ANY code:2001. Design document submitted to Gemini2012. Gemini evaluates completeness, security, testability2023. **APPROVE** → Proceed to coding2034. **BLOCK** → Revise design first204205**Cost of design fix:** 1 hour206**Cost of code fix:** 8 hours207**Cost of production fix:** 80 hours208209### Implementation Review Gate210211Before creating ANY PR:2121. Implementation report + test report submitted to Gemini2132. Gemini evaluates quality, coverage, security2143. **APPROVE** → Create PR2154. **BLOCK** → Fix issues first216217### Report Generation Gate218219Before merge, auto-generate:220- `implementation-report.md` - What changed and why221- `test-report.md` - Full test output, coverage metrics222223**[Gate Implementation Details](https://github.com/martymcenroe/AssemblyZero/wiki/Governance-Gates)**224225---226227## Permission Friction Management228229**Permission prompts are the #1 adoption killer.**230231Every "Allow this command?" prompt breaks flow state. Developers either:232- Click "Allow" without reading (security risk)233- Get frustrated and stop using the tool (adoption failure)234235### Pattern Detection236237AssemblyZero identifies:238- Commands that always get approved → Add to allow list239- Commands that always get denied → Add to deny list240- Novel patterns → Flag for review241242### Measurable Reduction243244| Metric | Before | After |245|--------|--------|-------|246| Prompts per session | 15-20 | 2-3 |247| Time lost to prompts | 10+ min | < 1 min |248| Developer frustration | High | Low |249250**[Permission Friction Deep Dive](https://github.com/martymcenroe/AssemblyZero/wiki/Permission-Friction)**251252---253254## 34 Governance Audits255256Audits designed with an **adversarial philosophy**: they exist to find violations, not confirm compliance.257258### Audit Categories259260| Category | Count | Focus |261|----------|-------|-------|262| **Security & Privacy** | 3 | OWASP, GDPR, License compliance |263| **AI Governance** | 7 | Bias, Explainability, Safety, Agentic risks |264| **Code Quality** | 4 | Standards, Accessibility, Capabilities |265| **Permission Management** | 3 | Friction, Permissiveness, Self-audit |266| **Documentation Health** | 6 | Reports, LLD alignment, Terminology |267| **Extended** | 10 | Cost, Structure, References, Wiki |268| **Meta** | 1 | Audit system governance |269270### Key Audits271272| Audit | Standard | What It Checks |273|-------|----------|----------------|274| **0808** | OWASP LLM 2025 | AI-specific vulnerabilities |275| **0809** | OWASP Agentic 2026 | Agent autonomy risks |276| **0810** | ISO/IEC 42001 | AI management system |277| **0815** | Internal | Permission friction patterns |278279**[Full Audit Catalog](https://github.com/martymcenroe/AssemblyZero/wiki/Audits-Catalog)**280281---282283## Metrics & KPIs284285**"How do I prove ROI to leadership?"**286287### Adoption Metrics288289| Metric | What It Shows |290|--------|---------------|291| Active users / Total engineers | Adoption rate |292| Sessions per user per week | Engagement depth |293| Features shipped with AI assist | Productivity impact |294295### Friction Metrics296297| Metric | Target |298|--------|--------|299| Permission prompts per session | < 3 |300| Time to first productive action | < 30 seconds |301| Session abandonment rate | < 5% |302303### Quality Metrics304305| Metric | What It Shows |306|--------|---------------|307| Gemini first-pass approval rate | Design quality |308| PR revision count | Code quality |309| Post-merge defects | Overall quality |310311### Cost Metrics312313| Metric | Calculation |314|--------|-------------|315| Cost per feature | Total API spend / Features shipped |316| Cost per agent-hour | API spend / Active agent hours |317| ROI | (Time saved × Engineer cost) / Platform cost |318319**[Full KPI Framework](https://github.com/martymcenroe/AssemblyZero/wiki/Measuring-Productivity)**320321---322323## Architecture: LangGraph State Machines324325AssemblyZero workflows run as LangGraph state machines with SQLite checkpointing:326327| Phase | Status | Capability | Impact |328|-------|--------|------------|--------|329| **1** | **COMPLETE** | LangGraph state machines (5 workflows) | Gates structurally enforced |330| **2** | **COMPLETE** | SQLite checkpointing (SqliteSaver) | Long tasks survive interruptions |331| **3** | Q2 2026 | Supervisor pattern | Autonomous task decomposition |332| **4** | Q2 2026 | LangSmith observability | Full dashboards, traces, cost attribution |333| **5** | Q3 2026 | Dynamic tool graphs | Context-aware tool selection |334335**[Full Roadmap and Vision](https://github.com/martymcenroe/AssemblyZero/wiki/LangGraph-Evolution)**336337---338339## Quick Start340341### 1. Clone and Install342343```bash344git clone https://github.com/martymcenroe/AssemblyZero.git345cd AssemblyZero346poetry install347```348349### 2. Configure Your Project350351```bash352mkdir -p YourProject/.claude353cp AssemblyZero/.claude/project.json.example YourProject/.claude/project.json354# Edit project.json with your project details355```356357### 3. Generate Configs358359```bash360poetry run python tools/assemblyzero-generate.py --project YourProject361```362363### 4. Start Working364365The generated configs include:366- Permission patterns that eliminate friction367- Slash commands for common operations368- Hooks for pre/post tool execution369370**[Detailed Setup Guide](https://github.com/martymcenroe/AssemblyZero/wiki/Quick-Start)**371372---373374## Documentation375376### Wiki377378Full documentation at **[AssemblyZero Wiki](https://github.com/martymcenroe/AssemblyZero/wiki)** (32 pages):379380| Page | Description |381|------|-------------|382| **[Technical Architecture](https://github.com/martymcenroe/AssemblyZero/wiki/Technical-Architecture)** | LLM invocation, LangGraph workflows, codebase intelligence |383| **[Metrics Dashboard](https://github.com/martymcenroe/AssemblyZero/wiki/Metrics)** | Velocity charts, production numbers |384| **[Multi-Agent Orchestration](https://github.com/martymcenroe/AssemblyZero/wiki/Multi-Agent-Orchestration)** | The headline feature - 12+ concurrent agents |385| **[Requirements Workflow](https://github.com/martymcenroe/AssemblyZero/wiki/Requirements-Workflow)** | LLD → Gemini → Approval flow |386| **[Implementation Workflow](https://github.com/martymcenroe/AssemblyZero/wiki/Implementation-Workflow)** | Worktree → Code → Reports → PR |387| **[Governance Gates](https://github.com/martymcenroe/AssemblyZero/wiki/Governance-Gates)** | LLD, implementation, report gates |388| **[How AssemblyZero Learns](https://github.com/martymcenroe/AssemblyZero/wiki/How-AssemblyZero-Learns)** | Self-improving governance from verdicts |389| **[LangGraph Evolution](https://github.com/martymcenroe/AssemblyZero/wiki/LangGraph-Evolution)** | Roadmap to enterprise state machines |390| **[Gemini Verification](https://github.com/martymcenroe/AssemblyZero/wiki/Gemini-Verification)** | Multi-model review architecture |391| **[Quick Start](https://github.com/martymcenroe/AssemblyZero/wiki/Quick-Start)** | 5-minute setup guide |392393### For Different Audiences394395| Audience | Start Here |396|----------|------------|397| **Engineering Leaders** | [Why AssemblyZero?](https://github.com/martymcenroe/AssemblyZero/wiki/For-Enterprise-Leaders-Why-AssemblyZero) |398| **Architects** | [Technical Architecture](https://github.com/martymcenroe/AssemblyZero/wiki/Technical-Architecture) |399| **Security Teams** | [Security & Compliance](https://github.com/martymcenroe/AssemblyZero/wiki/Security-Compliance) |400| **Developers** | [Quick Start](https://github.com/martymcenroe/AssemblyZero/wiki/Quick-Start) |401402---403404## About405406AssemblyZero was built by **Martin McEnroe**, applying 29 years of enterprise technology leadership to the emerging challenge of **scaling AI coding assistants across engineering organizations**.407408### Relevant Experience409410| Role | Organization | Relevance |411|------|--------------|-----------|412| **Director, Data Science & AI** | AT&T | Led 45-person team, $10M+ annual savings from production AI |413| **VP Product** | Afiniti | AI-powered platform at scale |414| **AI Strategic Consultant** | TX DOT | 76-page enterprise AI strategy |415416### Why This Project Exists417418Having led enterprise AI adoption, I know the blockers:419420| Blocker | AssemblyZero Solution |421|---------|------------------|422| "Security won't approve ungoverned AI" | 34 audits, Gemini gates, enforced checkpoints |423| "We can't measure productivity" | KPI framework, friction tracking, cost attribution |424| "Agents conflict with each other" | Worktree isolation, single-user identity model |425| "Developers hate the permission prompts" | Pattern detection, friction analysis, auto-remediation |426| "It's just pilots, not real adoption" | Infrastructure that scales to organization-wide |427428### Technical Foundation429430- **LangChain, LangGraph, LangSmith** - Hands-on implementation experience431- **21 US Patents** - Innovation track record432- **CISSP, CCSP, AWS ML Specialty** - Security and ML credentials433- **GitHub Copilot, Claude Code** - Daily production use434435### The Bottom Line436437**This isn't theoretical. It's production infrastructure I use daily to orchestrate 12+ AI agents with full governance.**438439The code in this repo is the same code that:440- Runs the Gemini verification gates441- Tracks permission friction patterns442- Generates the audit reports443- Manages credential rotation444445**If you're scaling AI coding assistants across an engineering organization, this is the infrastructure layer you need.**446447---448449## The Discworld Personas450451Workflows are named after **Terry Pratchett's Discworld** characters — intuitive metaphors that make system behavior memorable:452453| Persona | Function |454|---------|----------|455| **Vimes** | Regression guard — deep suspicion of everything |456| **Hex** | Codebase intelligence — AST parsing, pattern matching |457| **Ponder** | Mechanical validation — auto-fix before review |458| **Lu-Tze** | Maintenance — constant sweeping prevents disasters |459| **DEATH** | Documentation reconciliation — INEVITABLE. THOROUGH. |460461**[Full Cast →](https://github.com/martymcenroe/AssemblyZero/wiki/Dramatis-Personae)**462463*"A man is not dead while his name is still spoken."*464**GNU Terry Pratchett**465466---467468## License469470PolyForm Noncommercial 1.0.0471
Full transparency — inspect the skill content before installing.