muggle-ai-teams

# muggle-ai-teams

**AI workflow for Claude Code — describe what you want, get production-grade results.**

Code, content, design, planning — the workflow researches, designs, builds, tests, reviews, and ships. You describe and approve.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Part of the [Muggle AI](https://www.muggletest.com) open-source ecosystem. Built while developing [MuggleTest](https://www.muggletest.com) — an AI-powered QA testing platform.

---

## Why use muggle-ai-teams?

muggle-ai-teams is an AI agent orchestration workflow for Claude Code. You describe your task in plain English, approve the design, and the workflow handles everything else — research, implementation, testing, and review.

**Low effort.** Describe your task in plain English. Approve the design. That's it. The workflow handles research, implementation, testing, and code review without additional input from you.

**High quality.** Every output goes through research, specialist design, test-driven development, automated QA, and 3-pass code review. The same process that catches bugs in production code runs on every task.

**Transparent cost.** You see the estimate before work begins.

| Task type | Estimated cost |
|-----------|---------------|
| Quick fix, config change, typo | $0.50 – $2 |
| Standard feature, refactor, content | $5 – $20 |
| Complex project, architecture, multi-service | $50 – $100+ |

Works for any task:

- "Optimize my README for SEO" — content
- "Add a logout button to the header" — code
- "Build an investor pitch deck" — non-coding
- "Plan a product launch" — strategy

Battle-tested building [MuggleTest](https://www.muggletest.com) — an [AI-powered QA testing platform](https://www.muggletest.com) — across 6 production services.

---

## Quick Start

### Option A: npm install (recommended)

```bash
npm install @muggleai/teams
```

Update to latest: `npm update @muggleai/teams`

### Option B: Git clone (for contributors)

```bash
git clone https://github.com/multiplex-ai/muggle-ai-teams.git
chmod +x muggle-ai-teams/setup.sh
./muggle-ai-teams/setup.sh
```

After installing, open Claude Code and type `/muggle-ai-teams`. Describe what you want.

<details>
<summary>What does install actually do?</summary>

Both methods install `agents/`, `commands/`, `skills/`, and `rules/` into `~/.claude/` (global) and back up any existing directories before overwriting.

- npm install copies files; update with `npm update @muggleai/teams`
- git clone creates symlinks so edits in the repo are reflected immediately

No build step required. Works on macOS and Linux.
</details>

---

## How does it work?

muggle-ai-teams is a `claude code agents` workflow that routes each task to the right tier, dispatches specialist agents, and enforces quality gates at every step.

**The workflow adapts to task complexity automatically:**

| Tier | Cost | What happens |
|------|------|-------------|
| **Quick** | Small fix, typo, config | Direct execution — single agent, quality gates, done in minutes |
| **Standard** | Normal feature, refactor | Specialist-designed, per-slice QA, skip panel review |
| **Full** | Architecture, security, multi-service | Full panel review, regression sweep, all safeguards |

The orchestrator triages in Step 1A (reads project config + git history, scores complexity) and recommends a tier. You confirm or override.

```
You describe what you want → Auto-triage

Quick     → Execute → Done.
Standard  → Research → Design → Build → Test → Review → Ship
Full      → Research → Design → Panel → Build → Test → Review → Ship
```

The workflow triages complexity, recommends a tier, and waits for your confirmation before writing any code.

**Works for non-coding tasks too.** Say "build me an investor pitch deck" and the same workflow runs — specialists design the structure, execute section by section, review for quality, and deliver the final output. This is a genuine differentiator: most `claude code workflow` tools are built exclusively for code.

<details>
<summary>What happens inside each step?</summary>

**Research** — finds relevant code, docs, and community patterns. Reads your project config, scans affected code areas, and searches for skills relevant to the task.

**Requirements** — restates what "done" looks like. Extracts acceptance criteria from your description and produces explicit scope boundaries (what's in, what's out).

**Design** — specialist agents draft the approach. Routes to the right specialist (frontend, backend, architect) based on your project config. Includes mockups for UI work.

**Expert panel review** (Full tier only) — multiple specialists review the design in parallel and synthesize findings into a verdict.

**Approval** — you confirm before any code is written. No implementation starts until this gate passes.

**Plan** — breaks the work into slices, each with files to touch, test instructions, and completion criteria. Independent slices run in parallel.

**Build** — test-driven development with per-slice QA. Each slice follows TDD (test first, then implement). After each slice passes locally, it's tested against your running app via [muggle-ai-works](https://github.com/multiplex-ai/muggle-ai-works).

**Verify + Review** — quality gates and 3-pass code review. Typecheck, lint, full test suite, then code review covering quality, compliance, and contracts. Findings are fixed before proceeding.

**Ship** — PR created with description and test plan. QA results are published and linked in the PR.

**Learn** — extracts behavioral corrections from the session and writes them to the appropriate rules file so the same issue does not recur.
</details>

**Real examples:**

- "Add dark mode" → Standard → PR with tests, $8
- "Optimize this README" → Standard → rewritten file, $6
- "Investor pitch deck" → Standard → polished deck, $12
- "Migrate auth to OAuth 2.0" → Full → multi-file refactor with regression sweep, $65

### Key slash commands

| Command | What it does |
|---------|-------------|
| `/muggle-ai-teams` | Full orchestrated workflow |
| `/plan` | Research + requirements + implementation plan |
| `/tdd` | Test-driven development (RED → GREEN → IMPROVE) |
| `/code-review` | 3-pass review of uncommitted changes |
| `/build-fix` | Fix build/typecheck errors incrementally |
| `/e2e` | Generate and run Playwright E2E tests |
| `/learn-eval` | Extract patterns from session and save to skills or rules |
| `/save-session` | Save session state for resumption later |
| `/docs` | Look up library docs via Context7 |

---

## How is muggle-ai-teams different?

<details>
<summary>How muggle-ai-teams compares to Superpowers, Everything Claude Code, and Get Shit Done</summary>

| | **muggle-ai-teams** | **[Superpowers](https://github.com/obra/superpowers)** | **[Everything Claude Code](https://github.com/affaan-m/everything-claude-code)** | **[Get Shit Done](https://github.com/gsd-build/get-shit-done)** |
|---|---|---|---|---|
| **Focus** | End-to-end workflow with cost tiers | Development workflow skills | Agent harness optimization | Context engineering |
| **Core idea** | Describe task → approved design → autonomous delivery | Composable skills enforcing systematic dev process | Performance system with instincts, learning, and security | Fresh context per task to prevent quality degradation |
| **Agents** | 29 specialized roles with scope-first routing | Skill-based (no standalone agents) | 28 subagents | Multi-agent orchestration via waves |
| **Skills** | 207 (merged + deduplicated) | ~15 core workflow skills | 116+ | Embedded in prompts |
| **Rules** | 16 domain-split files, loaded on demand | Via skill enforcement | Multi-language rule sets | XML-structured prompts |
| **Learning system** | Behavioral corrections graduate to always-loaded rules | N/A | Instinct-based with confidence scoring | N/A |
| **Portability** | `setup.sh` symlinks to any machine | Plugin install | Plugin + manual setup | Drop-in folder |


[truncated…]