A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers. Each agent is a specialized expert with personality, processes, and proven deliverables.
Shell
docs: add tool-integration checklist + stop hardcoding roster counts (#663)
Michael Sitarzewski384dbbd2a8a3
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9df8f912..fbecb4cf 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -31,23 +31,11 @@ This project and everyone participating in it is governed by our Code of ConductHave an idea for a specialized agent? Great! Here's how to add one:1. **Fork the repository**-2. **Choose the appropriate division** (one of the 16 — or propose a new one):- - `academic/` - Research, scholarship, and domain-expert specialists- - `design/` - UX/UI and creative specialists- - `engineering/` - Software development specialists- - `finance/` - Financial planning, accounting, and investment specialists- - `game-development/` - Game design and development specialists- - `gis/` - Geospatial, mapping, and spatial-analysis specialists- - `marketing/` - Growth and marketing specialists- - `paid-media/` - Paid acquisition and media specialists- - `product/` - Product management specialists- - `project-management/` - PM and coordination specialists- - `sales/` - Sales, revenue, and deal specialists- - `security/` - Security architecture, AppSec, pentest, threat intel, and incident response- - `spatial-computing/` - AR/VR/XR specialists- - `specialized/` - Unique specialists that don't fit elsewhere- - `support/` - Operations and support specialists- - `testing/` - QA and testing specialists+2. **Choose the appropriate division** — or propose a new one. Divisions are the+ top-level agent directories (e.g. `engineering/`, `security/`, `gis/`, `marketing/`,+ `finance/`…); browse them to find where your agent fits. The authoritative list —+ with labels, icons, and colors — is [`divisions.json`](divisions.json) at the repo+ root, so it's always current.> **Divisions are defined by `divisions.json`** (repo root) — the single source of> truth for the division set, validated in CI by `scripts/check-divisions.sh`.@@ -238,6 +226,23 @@ quickstart guide wearing an agent costume does not.**Codex Compatibility**: Codex custom agents are generated as standalone TOML files. The Codex integration keeps a minimal 1:1 mapping: `name` and `description` are copied from frontmatter, and the Markdown body becomes `developer_instructions`. Source-only metadata such as `color`, `emoji`, `vibe`, and other unsupported frontmatter fields are omitted.+### Adding a Tool Integration++Want agency-agents to install into a new tool (a CLI, editor, or agent runtime)? First, **[open a Discussion](https://github.com/msitarzewski/agency-agents/discussions)** — new integration platforms are a "discuss first" change (see the PR Process below). Once there's alignment, a clean integration is small — usually **~5 files, never the converted output itself.** The just-merged Mistral Vibe integration is a good worked example to copy.++`tools.json` at the repo root is the single source of truth for the tool set, and `scripts/check-tools.sh` (CI) fails the build if any of the pieces below disagree. Run it — it names every place that must match.++**The checklist:**++1. **`tools.json`** — add an entry with `id`, `label`, `kebab`, `format`, `installKind`, `dest`, plus detect/version/scope and display fields. **Reuse an existing `format`** if your tool's rendered files are byte-identical to another's (e.g. tools that consume `SKILL.md` share `"format": "skill-md"` — no new renderer needed). Set `installKind` to `per-agent`, `roster`, or `plugin`. Set `icon` to `null` unless the [app](https://github.com/msitarzewski/agency-agents-app) ships a brand SVG for it.+2. **`scripts/convert.sh`** — add a `convert_<tool>()` (or reuse a shared `format` renderer) and wire it into the tool list + `--help`.+3. **`scripts/install.sh`** — add an `install_<tool>()` and register it in `ALL_TOOLS` + detection/labeling + `--help`.+4. **`.gitignore`** — add a rule for your tool's generated output under `integrations/<tool>/`. **This step is required and easy to miss.** Converted agent/skill files are generated locally by `convert.sh` and are **never committed** (see "Things we'll always close" below) — only `integrations/<tool>/README.md` is tracked. Match an existing per-tool entry.+5. **`integrations/<tool>/README.md`** — a short doc for the integration (every tool has one; it's the only committed file in the tool's directory).+6. **Run `./scripts/check-tools.sh`** — it must pass. It cross-checks `tools.json` against `install.sh` and `convert.sh` and flags anything missing.++If your PR commits the converted output (the generated `integrations/<tool>/*` files), CI and review will ask you to remove it and add the `.gitignore` rule instead.+### What Makes a Great Agent?**Great agents have**:@@ -279,7 +284,7 @@ For anything beyond that, here's how we keep things smooth:We love ambitious ideas — a [Discussion](https://github.com/msitarzewski/agency-agents/discussions) just gives the community a chance to align on approach before code gets written. It saves everyone time, especially yours.#### Things we'll always close-- **Committed build output**: Generated files (`_site/`, compiled assets, converted agent files) should never be checked in. Users run `convert.sh` locally; all output is gitignored.+- **Committed build output**: Generated files (`_site/`, compiled assets, converted agent files) should never be checked in. Users run `convert.sh` locally; its output is gitignored. When adding a new tool, adding that `.gitignore` rule is your step — see [Adding a Tool Integration](#adding-a-tool-integration).- **PRs that bulk-modify existing agents** without a prior discussion — even well-intentioned reformatting can create merge conflicts for other contributors.- **Near-duplicate "re-skins"**: New agents that are find-replace copies of an existing one (e.g. swapping a country or platform name) rather than genuinely new specialists. Run `scripts/check-agent-originality.sh` before submitting — CI runs it automatically.diff --git a/README.md b/README.mdindex 1d52ac12..d2f65484 100644--- a/README.md+++ b/README.md@@ -91,7 +91,7 @@ Browse the agents below and copy/adapt the ones you need!./scripts/install.sh --tool vibe```-**Install only the teams you need** (not everyone wants all 16 divisions):+**Install only the teams you need** (not everyone wants every division):```bash./scripts/install.sh # interactive wizard: pick tools + teams@@ -649,7 +649,7 @@ Each agent is designed with:## 📊 Stats-- 🎭 **232 Specialized Agents** across 16 divisions+- 🎭 **230+ Specialized Agents** across every division- 📝 **10,000+ lines** of personality, process, and code examples- ⏱️ **Months of iteration** from real-world usage- 🌟 **Battle-tested** in production environments@@ -1037,7 +1037,7 @@ MIT License - Use freely, commercially or personally. Attribution appreciated bu## 🙏 Acknowledgments-What started as a Reddit thread about AI agent specialization has grown into something remarkable — **232 agents across 16 divisions**, supported by a community of contributors from around the world. Every agent in this repo exists because someone cared enough to write it, test it, and share it.+What started as a Reddit thread about AI agent specialization has grown into something remarkable — **230+ agents across every division**, supported by a community of contributors from around the world. Every agent in this repo exists because someone cared enough to write it, test it, and share it.To everyone who has opened a PR, filed an issue, started a Discussion, or simply tried an agent and told us what worked — thank you. You're the reason The Agency keeps getting better.diff --git a/scripts/check-agent-originality.sh b/scripts/check-agent-originality.shindex 4dec38a8..39b030a5 100755--- a/scripts/check-agent-originality.sh+++ b/scripts/check-agent-originality.sh@@ -23,7 +23,7 @@# ORIGINALITY_FAIL default 40 — at/above this %, treated as a duplicate (exit 1)# ORIGINALITY_WARN default 20 — at/above this %, surfaced as a warning (no fail)#-# Calibration: across the existing 184-agent library the worst same-pair+# Calibration: across the existing agent library the worst same-pair# similarity is ~1.5% (median 0%). Anything in the double digits is a strong# anomaly; the defaults leave a wide safety margin against false positives.diff --git a/strategy/EXECUTIVE-BRIEF.md b/strategy/EXECUTIVE-BRIEF.mdindex be943b39..cdf4cf9b 100644--- a/strategy/EXECUTIVE-BRIEF.md+++ b/strategy/EXECUTIVE-BRIEF.md@@ -6,7 +6,7 @@## 1. SITUATION OVERVIEW-The Agency comprises specialized AI agents across 9 divisions — engineering, design, marketing, product, project management, testing, support, spatial computing, and specialized operations. Individually, each agent delivers expert-level output. **Without coordination, they produce conflicting decisions, duplicated effort, and quality gaps at handoff boundaries.** NEXUS transforms this collection into an orchestrated intelligence network with defined pipelines, quality gates, and measurable outcomes.+The Agency comprises specialized AI agents across every division — engineering, design, marketing, security, GIS, product, testing, and more. Individually, each agent delivers expert-level output. **Without coordination, they produce conflicting decisions, duplicated effort, and quality gaps at handoff boundaries.** NEXUS transforms this collection into an orchestrated intelligence network with defined pipelines, quality gates, and measurable outcomes.## 2. KEY FINDINGS@@ -92,4 +92,4 @@ strategy/----*NEXUS: 9 Divisions. 7 Phases. One Unified Strategy.*+*NEXUS: All Divisions. 7 Phases. One Unified Strategy.*diff --git a/strategy/nexus-strategy.md b/strategy/nexus-strategy.mdindex 141db7de..b80a9b27 100644--- a/strategy/nexus-strategy.md+++ b/strategy/nexus-strategy.md@@ -1103,7 +1103,7 @@ Use the NEXUS QA Feedback Loop Protocol format<div align="center">-**🌐 NEXUS: 9 Divisions. 7 Phases. One Unified Strategy. 🌐**+**🌐 NEXUS: All Divisions. 7 Phases. One Unified Strategy. 🌐***From discovery to sustained operations — every agent knows their role, their timing, and their handoff.*