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
Add strategy/runbooks.json — NEXUS runbook rosters by slug + CI guard (#664)
Michael Sitarzewskicb45d3ea8cc7
diff --git a/.github/workflows/check-runbooks.yml b/.github/workflows/check-runbooks.ymlnew file mode 100644index 00000000..cf44a5cf--- /dev/null+++ b/.github/workflows/check-runbooks.yml@@ -0,0 +1,21 @@+name: Check Runbooks Consistency++# Runs on every PR (no path filter on purpose): renaming or removing an agent+# must trip this check even when nobody touched strategy/runbooks.json, since a+# dangling roster slug breaks the app's one-click team deploy.+on:+ pull_request:+ push:+ branches: [main]++jobs:+ check-runbooks:+ name: runbook rosters reference real agent slugs+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ - name: Validate runbook rosters+ run: |+ chmod +x scripts/check-runbooks.sh+ ./scripts/check-runbooks.shdiff --git a/scripts/check-runbooks.sh b/scripts/check-runbooks.shnew file mode 100755index 00000000..ad1d7c74--- /dev/null+++ b/scripts/check-runbooks.sh@@ -0,0 +1,83 @@+#!/usr/bin/env bash+#+# check-runbooks.sh — enforce that strategy/runbooks.json stays in sync with the+# real agent roster.+#+# strategy/runbooks.json is the machine-readable roster for the NEXUS scenario+# runbooks: the Agency Agents app reads it to turn a runbook into a one-click+# team deploy, mapping each roster slug to a catalog agent. If a slug there+# doesn't resolve to a real agent file, the app can't deploy that team — so this+# check fails the build when:+# 1. runbooks.json is not valid JSON, or an entry is missing a required field+# 2. any roster `agents[]` slug does not match an agent .md filename stem+# 3. any `doc` path does not exist+# 4. a runbook `slug` is duplicated+#+# Slugs are the agent .md filename stem (the corpus id), e.g.+# engineering/engineering-frontend-developer.md -> "engineering-frontend-developer".+# Uses python3 (already required by check-agent-originality.sh) for JSON; no jq,+# so it runs the same on macOS and CI. Mirrors scripts/check-divisions.sh.+#+# Usage: ./scripts/check-runbooks.sh++set -euo pipefail+cd "$(dirname "$0")/.."++command -v python3 >/dev/null 2>&1 || {+ echo "ERROR: python3 is required for the runbooks check." >&2+ exit 2+}++python3 - <<'PYEOF'+import json, os, subprocess, sys++JSON = "strategy/runbooks.json"+errors = []++if not os.path.isfile(JSON):+ print(f"ERROR {JSON} not found"); sys.exit(1)++try:+ data = json.load(open(JSON))+except json.JSONDecodeError as e:+ print(f"ERROR {JSON} is not valid JSON: {e}"); sys.exit(1)++# Real slugs = filename stems of tracked agent .md files under division dirs.+NON_DIVISION = {"integrations", "examples", "strategy", "scripts", ".github"}+tracked = subprocess.check_output(["git", "ls-files", "*/*.md"]).decode().splitlines()+real = {os.path.basename(p)[:-3] for p in tracked if p.split("/")[0] not in NON_DIVISION}++runbooks = data.get("runbooks")+if not isinstance(runbooks, list) or not runbooks:+ print(f"ERROR {JSON} has no 'runbooks' array"); sys.exit(1)++seen_slugs = set()+total_refs = 0+for rb in runbooks:+ rid = rb.get("slug", "<no slug>")+ for field in ("slug", "title", "mode", "doc", "roster"):+ if field not in rb:+ errors.append(f"runbook '{rid}' is missing required field \"{field}\"")+ if rb.get("slug") in seen_slugs:+ errors.append(f"duplicate runbook slug '{rb.get('slug')}'")+ seen_slugs.add(rb.get("slug"))+ doc = rb.get("doc")+ if doc and not os.path.isfile(doc):+ errors.append(f"runbook '{rid}': doc path does not exist: {doc}")+ for g in rb.get("roster", []):+ for slug in g.get("agents", []):+ total_refs += 1+ if slug not in real:+ errors.append(f"runbook '{rid}' / group '{g.get('group','?')}': "+ f"slug '{slug}' does not match any agent .md filename stem")++if errors:+ print(f"FAILED: {len(errors)} runbook consistency error(s). "+ f"strategy/runbooks.json must reference real agent slugs.\n")+ for e in errors:+ print(f" ERROR {e}")+ sys.exit(1)++print(f"PASSED: {len(runbooks)} runbooks, {total_refs} agent slug references — "+ f"all resolve to real agent files.")+PYEOFdiff --git a/strategy/runbooks.json b/strategy/runbooks.jsonnew file mode 100644index 00000000..9547fa45--- /dev/null+++ b/strategy/runbooks.json@@ -0,0 +1,175 @@+{+ "_note": "Machine-readable rosters for the NEXUS scenario runbooks in strategy/runbooks/. Consumed by the Agency Agents app to turn a runbook into a one-click team deploy: it reads the roster, maps each slug to a catalog agent, and installs the set. `agents[]` entries are SLUGS — the agent .md filename stem (the corpus id), e.g. engineering/engineering-frontend-developer.md -> \"engineering-frontend-developer\"; specialized/agents-orchestrator.md -> \"agents-orchestrator\" (note: the stem is NOT always division-prefixed, and display names are prefixed/drift — so rosters reference slugs, which are rename-proof and testable). `mode` is the NEXUS activation mode (Full | Sprint | Micro) that sizes the team; `roster` groups preserve the runbook's phase structure via `activation`. `doc` is the prose runbook the app renders. Keep this in sync with the markdown in strategy/runbooks/; every slug must resolve to a real agent file (scripts/check-runbooks.sh can guard this, mirroring check-divisions.sh). strategy/ holds orchestration doctrine, not installable agents — it is NOT a division (see divisions.json).",+ "runbooks": [+ {+ "slug": "startup-mvp",+ "title": "Startup MVP Build",+ "mode": "NEXUS-Sprint",+ "duration": "4-6 weeks",+ "summary": "Idea to live product with real users, fast — without skipping QA.",+ "doc": "strategy/runbooks/scenario-startup-mvp.md",+ "roster": [+ {+ "group": "Core Team",+ "activation": "always",+ "agents": [+ "agents-orchestrator",+ "project-manager-senior",+ "product-sprint-prioritizer",+ "design-ux-architect",+ "engineering-frontend-developer",+ "engineering-backend-architect",+ "engineering-devops-automator",+ "testing-evidence-collector",+ "testing-reality-checker"+ ]+ },+ {+ "group": "Growth Team",+ "activation": "week 3+",+ "agents": [+ "marketing-growth-hacker",+ "marketing-content-creator",+ "marketing-social-media-strategist"+ ]+ },+ {+ "group": "Support Team",+ "activation": "as needed",+ "agents": [+ "design-brand-guardian",+ "support-analytics-reporter",+ "engineering-rapid-prototyper",+ "engineering-ai-engineer",+ "testing-performance-benchmarker",+ "support-infrastructure-maintainer"+ ]+ }+ ]+ },+ {+ "slug": "enterprise-feature",+ "title": "Enterprise Feature Development",+ "mode": "NEXUS-Sprint",+ "duration": "6-12 weeks",+ "summary": "Ship a major feature into an existing enterprise product with non-negotiable compliance, security, and quality gates, and multi-stakeholder alignment.",+ "doc": "strategy/runbooks/scenario-enterprise-feature.md",+ "roster": [+ {+ "group": "Core Team",+ "activation": "always",+ "agents": [+ "agents-orchestrator",+ "project-management-project-shepherd",+ "project-manager-senior",+ "product-sprint-prioritizer",+ "design-ux-architect",+ "design-ux-researcher",+ "design-ui-designer",+ "engineering-frontend-developer",+ "engineering-backend-architect",+ "engineering-senior-developer",+ "engineering-devops-automator",+ "testing-evidence-collector",+ "testing-api-tester",+ "testing-reality-checker",+ "testing-performance-benchmarker"+ ]+ },+ {+ "group": "Compliance & Governance",+ "activation": "as needed",+ "agents": [+ "support-legal-compliance-checker",+ "design-brand-guardian",+ "support-finance-tracker",+ "support-executive-summary-generator"+ ]+ },+ {+ "group": "Quality Assurance",+ "activation": "as needed",+ "agents": [+ "testing-test-results-analyzer",+ "testing-workflow-optimizer",+ "project-management-experiment-tracker"+ ]+ }+ ]+ },+ {+ "slug": "marketing-campaign",+ "title": "Multi-Channel Marketing Campaign",+ "mode": "NEXUS-Sprint",+ "duration": "2-4 weeks",+ "summary": "Launch a coordinated, brand-consistent campaign across channels that drives measurable acquisition and engagement.",+ "doc": "strategy/runbooks/scenario-marketing-campaign.md",+ "roster": [+ {+ "group": "Campaign Core",+ "activation": "always",+ "agents": [+ "marketing-social-media-strategist",+ "marketing-content-creator",+ "marketing-growth-hacker",+ "design-brand-guardian",+ "support-analytics-reporter"+ ]+ },+ {+ "group": "Platform Specialists",+ "activation": "as needed",+ "agents": [+ "marketing-twitter-engager",+ "marketing-tiktok-strategist",+ "marketing-instagram-curator",+ "marketing-reddit-community-builder",+ "marketing-app-store-optimizer"+ ]+ },+ {+ "group": "Support",+ "activation": "as needed",+ "agents": [+ "product-trend-researcher",+ "project-management-experiment-tracker",+ "support-executive-summary-generator",+ "support-legal-compliance-checker"+ ]+ }+ ]+ },+ {+ "slug": "incident-response",+ "title": "Incident Response",+ "mode": "NEXUS-Micro",+ "duration": "Minutes to hours",+ "summary": "Detection through post-mortem for a production incident — fast response without cutting corners.",+ "doc": "strategy/runbooks/scenario-incident-response.md",+ "roster": [+ {+ "group": "P0 Critical Response",+ "activation": "always",+ "agents": [+ "support-infrastructure-maintainer",+ "engineering-devops-automator",+ "engineering-backend-architect",+ "engineering-frontend-developer",+ "support-support-responder",+ "support-executive-summary-generator"+ ]+ },+ {+ "group": "Verification & Post-Mortem",+ "activation": "post-fix",+ "agents": [+ "testing-evidence-collector",+ "testing-api-tester",+ "testing-workflow-optimizer",+ "product-sprint-prioritizer"+ ]+ }+ ]+ }+ ]+}