From 384dbbd2a8a35cd7cd2c842f557ba7217dec7f6a Mon Sep 17 00:00:00 2001 From: Michael Sitarzewski Date: Sun, 5 Jul 2026 12:45:36 -0500 Subject: [PATCH] docs: add tool-integration checklist + stop hardcoding roster counts (#663) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two related drift traps, both from hand-typed numbers/lists that no guard watches: 1. CONTRIBUTING had no "how to add a tool" checklist, and its wording ("all output is gitignored") implied gitignoring was automatic — so tool contributors kept committing generated integrations// output. 2. The division set and agent/division counts were hardcoded in prose in several places and had already gone stale (CONTRIBUTING said "16" and omitted healthcare; EXECUTIVE-BRIEF said "9 divisions"). Changes: - Add an "Adding a Tool Integration" checklist to CONTRIBUTING (discuss-first, reuse an existing `format`, the ~5-file touch list incl. the required .gitignore rule, run check-tools.sh). Harmonize the "committed build output" policy line to point at it. - De-hardcode the division list in CONTRIBUTING — defer to divisions.json. - Stop scattering roster counts: strategy/EXECUTIVE-BRIEF ("9 divisions") and check-agent-originality.sh ("184-agent library") drop the number entirely; README keeps a showcase stat but softens "232 across 16" to "230+ across every division" so it never becomes a lie as the roster grows. Claude-Session: https://claude.ai/code/session_01WKnDRWM4izsB8WAXKszhsq Co-authored-by: Claude Opus 4.8 --- CONTRIBUTING.md | 41 +++++++++++++++++------------- README.md | 6 ++--- scripts/check-agent-originality.sh | 2 +- strategy/EXECUTIVE-BRIEF.md | 4 +-- strategy/nexus-strategy.md | 2 +- 5 files changed, 30 insertions(+), 25 deletions(-) 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_()` (or reuse a shared `format` renderer) and wire it into the tool list + `--help`. +3. **`scripts/install.sh`** — add an `install_()` and register it in `ALL_TOOLS` + detection/labeling + `--help`. +4. **`.gitignore`** — add a rule for your tool's generated output under `integrations//`. **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//README.md` is tracked. Match an existing per-tool entry. +5. **`integrations//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//*` 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
-**🌐 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.*