Skip to content

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.md
index 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 Conduct
Have 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.md
index 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.sh
index 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.md
index 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.md
index 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.*