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.

Part of the Muggle AI open-source ecosystem. Built while developing MuggleTest — 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.

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 — an AI-powered QA testing platform — across 6 production services.

Quick Start

Option A: npm install (recommended)

npm install @muggleai/teams

Update to latest: npm update @muggleai/teams

Option B: Git clone (for contributors)

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.

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:

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.

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

How is muggle-ai-teams different?

muggle-ai-teams does not replace these projects — it builds on them. We merged the best parts of Superpowers (workflow discipline) and Everything Claude Code (agents, skills, hooks) into a unified, deduplicated system, then added:

• Project-config-driven routing — each project declares its scopes, agents, and directories; the workflow bootstraps new projects automatically
• Cost tiers with upfront estimates — Quick/Standard/Full with realistic dollar ranges you see before work starts
• Behavioral learning system — your corrections graduate to always-loaded rules files, not unreliable memory
• Domain-based rule loading — 80% reduction in always-loaded context
• Non-coding task support — content, strategy, and design tasks use the same orchestrated workflow

Under the hood

The workflow coordinates specialist claude code agents, enforces quality gates automatically, and learns from your corrections over time. Every session improves the next one.

Always loaded (every conversation):
  core.md              # Universal principles, honest pushback
  behavior.md          # Debugging discipline, communication, output quality
  agents-routing.md    # Scope-first agent dispatch
  model-selection.md   # Opus/Sonnet/Haiku routing

Loaded on demand:
  coding.md            # TypeScript/React standards
  testing.md           # TDD, coverage gates
  git.md               # Commit, branch, PR conventions
  quality-gates.md     # Pre-commit checks
  planning.md          # Research-first workflow
  context-management.md
  agents-advanced.md   # Multi-agent orchestration
  security-php.md, coding-style-php.md, patterns-php.md, hooks-php.md, testing-php.md

muggle-ai-teams/
  agents/         <- single source of truth
  commands/
  skills/
  rules/

~/.claude/
  agents/ -> muggle-ai-teams/agents/     (global)
  commands/ -> muggle-ai-teams/commands/
  skills/ -> muggle-ai-teams/skills/
  rules/ -> muggle-ai-teams/rules/

your-project/.claude/
  agents/ -> muggle-ai-teams/agents/     (project)
  skills/ -> muggle-ai-teams/skills/

QA integration and ecosystem

When muggle-ai-works is installed, the workflow integrates automated QA testing at every stage:

• Per-slice QA — each implementation slice is tested against your running app before committing
• Regression sweep (Full tier) — after all slices, replay all project test scripts to catch cross-slice interaction bugs
• Publish results — QA results are published to Muggle AI cloud and linked in the PR description

Install: npm install @muggleai/works

Muggle AI open-source ecosystem:

muggle-ai-teams handles how work gets done (design → implement → review → deliver). muggle-ai-works handles QA verification (test generation, browser replay, cloud results). Together, they form a complete ai agent orchestration workflow with built-in quality assurance.

Want QA testing without managing any of this? Try MuggleTest — no setup, no agents, no configuration required.

FAQ

Which platforms does this work with?

Full support: Claude Code. The orchestrated workflow — parallel autonomous coding agent dispatch, per-slice QA, task tracking, hooks, MCP integration — requires Claude Code's Agent tool, Skill tool, TaskCreate, and hook system.

Partial support: Cursor. Reads the agent and skill files and supports MCP (so muggle-ai-works tools work). Cannot spawn subagent specialists in parallel, run hooks, or track workflow tasks. Use the step files as manual guidance rather than automated orchestration.

Not supported: Codex, Trae, and others. The workflow files are readable markdown — any AI assistant can follow them as instructions — but automated orchestration won't work without the tools above. Contributions to port the orchestration layer are welcome.

How much does a typical workflow run cost?

Costs depend on task complexity and which tier the triage recommends:

• Quick ($0.50 – $2): Small fixes, config changes, typos. Direct execution, done in minutes.
• Standard ($5 – $20): Normal features, refactors, content rewrites. Full research-design-build-test-review cycle.
• Full ($50 – $100+): Architecture changes, security-sensitive work, multi-service features. Adds expert panel review and regression sweep.

You see the estimate and confirm the tier before any work begins.

Will this overwrite my existing ~/.claude/ files?

No. setup.sh backs up your existing agents/, commands/, skills/, and rules/ to .bak directories before creating symlinks. To undo: remove the symlinks, rename the backups. Your original setup is preserved.

Will 207 skills eat my entire context window?

No. Skills load on demand — Claude Code reads them only when a matching task triggers them. At rest, zero skill tokens are in your context. During a workflow run, only the current step file (~50 lines) is active.

I already use Superpowers or Everything Claude Code. Do I install both?

No. muggle-ai-teams already includes merged, deduplicated versions of both. Installing them separately creates conflicts. If those projects release new skills you want, add the files to the muggle-ai-teams directories — they are picked up automatically.

Can I add my own agents and skills?

Yes. Add files directly to muggle-ai-teams/agents/ or muggle-ai-teams/skills/. Since they are symlinked to ~/.claude/, Claude Code picks them up immediately. Your additions are version-controlled alongside everything else.

Does the full workflow run even for a small bug fix?

No. Quick tasks auto-route to direct execution. Standard features skip panel review and use lighter research. Only architectural or security-sensitive changes run the full workflow. The triage happens automatically — you confirm the tier before proceeding.

What if I'm mid-project on the old workflow and want to switch?

Run scripts/migrate-to-new-workflow.sh. It detects your existing plans, maps them to the new step structure, and moves them to the new project-scoped paths. You resume where you left off.

Credits

muggle-ai-teams builds on excellent open-source work:

Core foundations

• everything-claude-code by @affaan-m — Source of many agents, commands, skills, and hooks. Anthropic hackathon winner with 28 subagents, 116+ skills, and a continuous learning system.

• superpowers by Jesse Vincent / Prime Radiant — Workflow skills including TDD, systematic debugging, code review, and parallel dispatch patterns. The discipline backbone of the workflow.

• Get Shit Done by TACHES — Context engineering and multi-agent orchestration patterns. Inspired the fresh-context-per-step approach and research-driven planning.

Skills and integrations

• claude-seo by @AgriciDaniel — 12 SEO audit, planning, and optimization skills.
• geo-seo-claude by @zubair-trabzada — 14 Generative Engine Optimization skills for AI-age search visibility.
• ui-ux-pro-max by @nextlevelbuilder — UI/UX design intelligence with 50+ styles, 161 color palettes, and 99 UX guidelines.
• SkillsMP — Skills marketplace used in the research step to find community skills relevant to each feature.

Platform and tools

• Claude Code by Anthropic — The platform that makes all of this possible.
• Context7 — Live documentation lookup used by the docs-lookup agent and /docs command.

About

Built by the team behind MuggleTest — an AI-powered QA testing platform that makes software testing accessible to every team, no coding required.

Both muggle-ai-teams and muggle-ai-works were created and refined while building MuggleTest — a multi-service platform spanning 6 sub-projects with frontend, backend, MCP servers, Electron apps, and documentation.

License

MIT — Use it, fork it, make it yours.

If this helps your Claude Code workflow, consider giving it a star. It helps others find it.