msitarzewski/agency-agents · 168k stars · Beginner · 15 min · 2026-11-15

Install and run an AI agency with msitarzewski/agency-agents

The Agency is a roster of specialist agent personas you install into Claude Code, Copilot, Cursor, OpenClaw, Hermes and a dozen other tools, plus NEXUS playbooks that coordinate them into a gated pipeline.

TL;DR

The Agency is a library of specialist agent personas (frontend, backend, code review, QA, marketing and more) kept as markdown files. A shell installer copies the ones you pick into your coding tool, and the NEXUS playbooks show how to run them as a coordinated team. Start with one division, activate a single agent, then try an orchestrated run.

Why this repo matters

Generic "you are a helpful assistant" prompts give generic work. The README's pitch is that each agent has deep domain expertise, a distinct voice, real deliverables and success metrics. It also solves a distribution problem: one roster, installed into Claude Code, GitHub Copilot, Cursor, OpenClaw, Hermes, Codex, Gemini CLI and others, without rewriting each persona by hand.

Best practices

  • Install only the teams you need. The README offers --division and --agent so you are not loading every division, and warns that OpenCode registers only about 119 agents and silently drops the rest.
  • Preview first. install.sh has a --dry-run flag and --list teams / --list agents to see what exists before it writes.
  • Read the agent file before you rely on it. Each file lists identity, core mission, critical rules, deliverables and success metrics, so you can check it matches your project.
  • Use NEXUS modes by size. The Quick-Start guide matches NEXUS-Full, NEXUS-Sprint and NEXUS-Micro to project scale (12-24 weeks, 2-6 weeks, 1-5 days).
  • Let QA loops gate the work. The playbooks run a Dev-QA loop per task with a maximum of three retries before escalation.
  • Install a runbook's team exactly as listed. strategy/runbooks.json rosters can be passed to install.sh --agents-file.

How-to

Where do I start?

1. Get the repo

Where do the agents live? In a git repo of markdown files grouped by division (engineering, design, marketing, testing and more). If you want no terminal at all, the README says a desktop app (agencyagents.app) installs agents for you; the steps here use the scripts.

git clone https://github.com/msitarzewski/agency-agents
cd agency-agents

Next: See what is available

Try it

Install the engineering division for your tool with --dry-run first, then for real. Open a small project, activate the Code Reviewer agent on a recent diff, and check that the review marks issues as blocker, suggestion or nit as the agent file describes. Then read strategy/playbooks/phase-3-build.md and compare its Dev-QA loop with how you review today.

Pitfalls

  • Installing everything. Loading all divisions can hit tool limits (OpenCode drops agents past about 119) and adds noise; select a division or a runbook roster.
  • Skipping conversion. Tools other than Claude Code and Copilot read generated files from integrations/. The installer tries to run convert.sh itself when they are missing; if that fails, run ./scripts/convert.sh --tool <name> manually.
  • Treating personas as magic. They are prompts with structure; judge the output on your own acceptance criteria.
  • Restarting. If you install for OpenClaw and its gateway is running, the integration README says to run openclaw gateway restart.

Next steps