CodeVetter · Repo Unpack evidence
msitarzewski/agency-agents
github.com/msitarzewski/agency-agents ↗ · 362 files · 4.5 MB
🎭 The Agency: AI Specialists Ready to Transform Your Workflow A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers.
Overview
The Agency is a MIT-licensed catalog of 279 Markdown agent personalities plus the bash/Python toolchain that converts and installs them into 16 coding-agent hosts. It is aimed at people who want specialized, opinionated prompts (engineering, marketing, security, GIS, and the rest) inside Claude Code, Cursor, Codex, Gemini, Copilot, Hermes, and similar tools, rather than a running application. What is distinctive is the dual catalog: divisions.json and tools.json are enforced as single sources of truth, converters are deterministic, and Hermes gets one lazy-router plugin instead of hundreds of always-loaded skills.
System map
The repo is a content catalog plus a local installer, not a service. Agent source lives in 18 division directories declared by divisions.json. scripts/convert.sh renders tool-specific files under integrations/ (gitignored except READMEs); scripts/install.sh copies or symlinks them into host config directories. Shared parsing and the installer TUI live in scripts/lib.sh. There is no package manifest, database, or HTTP server. A separate desktop app (agency-agents-app) is documented as a consumer of the same catalogs. CI is six GitHub Actions workflows on ubuntu-latest, with the installer also matrixed onto macos-latest.
- 279 agent files start with YAML frontmatter and sit in 18 division directories whose canonical set is the divisions object in divisions.json (academic through testing), each with label, Lucide icon, and hex color.
- strategy/, integrations/, examples/, and scripts/ are explicitly non-divisions. strategy/ holds NEXUS playbooks and runbooks with no agent frontmatter; integrations/ is convert.sh output. NON_DIVISION_DIRS in check-divisions.sh is examples, scripts, integrations, strategy.
- tools.json is the install contract for 16 hosts. Each entry carries id, kebab, format, installKind (per-agent, roster, or plugin), detect dirs, version bin/args, scope, and dest templates. claude-code and copilot use format identity; hermes is installKind plugin; aider and windsurf are roster.
- scripts/convert.sh is the renderer. It sources lib.sh, hardcodes AGENT_DIRS to the 18 divisions, accepts --tool/--out/--parallel/--jobs, and writes only under integrations/ (or --out). It states it never touches user config dirs.
- scripts/install.sh is the installer. ALL_TOOLS lists the same 16 kebab names. Divisions are parsed at runtime by divisions_from_json from divisions.json (awk/grep/sed, no jq) into ALL_DIVISIONS; AGENT_DIRS then appends strategy, which is_agent_file filters out.
- scripts/lib.sh is the shared bash 3.2 library: get_field, get_body, slugify, agent_slug, is_agent_file, fence_open_p/fence_closes_p, and the installer TUI (tui_begin, read_key, draw_frame). It is sourced, not executed, and has no external dependencies.
- Hermes output is not a per-agent renderer. run_conversions special-cases tool hermes and calls python3 scripts/build-hermes-plugin.py --repo-root --out, which reads divisions.json and emits the agency-agents-router plugin.
- Generated agent payloads are gitignored. .gitignore keeps integrations/*/README.md tracked and ignores per-tool trees such as integrations/opencode/agents/, integrations/cursor/rules/, integrations/hermes/agency-agents-router/, and integrations/aider/CONVENTIONS.md.
- CI entrypoints are the six workflows under .github/workflows: test-install.yml (ubuntu-latest and macos-latest), lint-agents.yml, check-divisions.yml, check-tools.yml, check-runbooks.yml, and check-hermes-config-rewrite.yml. All except lint-agents run on every pull_request and on push to main, with no path filter.
- The recommended user path in README is the separate native app at agencyagents.app / msitarzewski/agency-agents-app, which browses the roster and installs into Claude Code, Cursor, Codex, Gemini, and others. The in-repo path is ./scripts/install.sh and ./scripts/convert.sh.
- There is no application runtime in this repo: no package.json, no server, no database. Persistence of installed agents is the host tool's config directory on disk, and the only machine-readable catalogs shipped here are divisions.json, tools.json, and strategy/runbooks.json.
Feature catalog
User-facing surface is the agent roster, the installer CLI, the converter, NEXUS orchestration docs, and a handful of optional integrations (MCP memory, Chinese Copilot name localization). Agents are activated by pasting or installing their markdown into a host tool, not by an in-repo UI. The installer can target one tool, a division, a slug list, or an agents file, and can dry-run. Hermes exposes four router tools instead of one skill per agent.
- install.sh usage supports --tool (comma-separated), --division, --agent, --agents-file, --link, --path, --interactive/--no-interactive, --no-convert, --dry-run, --list [tools|teams|agents], --parallel, and --jobs. Bare invocation installs all teams into detected tools and opens the wizard on a TTY.
- Interactive install is a three-screen TUI: screen_tools, screen_teams, screen_review. Keys are space/a/n/search/enter. Teams default to all; tools default to whatever is_detected returns. Review toggles copy vs symlink via USE_LINK.
- Claude Code install copies source markdown into ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents (or $CLAUDE_CONFIG_DIR/agents). Copilot copies the same files into both ~/.github/agents and ~/.copilot/agents. Neither tool is produced by convert.sh.
- Project-scoped installs write into the current working directory: OpenCode to .opencode/agents, Cursor to .cursor/rules, Aider to CONVENTIONS.md, Windsurf to .windsurfrules. User-scoped examples include Gemini ~/.gemini/agents, Codex ~/.codex/agents, OpenClaw ~/.openclaw/agency-agents, Osaurus ~/.osaurus/skills.
- convert.sh --tool accepts antigravity, gemini-cli, opencode, cursor, aider, windsurf, openclaw, qwen, zcode, kimi, codex, osaurus, hermes, vibe, or all. Per-agent converters include convert_opencode, convert_cursor, convert_codex, convert_kimi, convert_vibe, convert_openclaw, convert_qwen, convert_zcode.
- Aider output is an index, not full prompts: accumulate_aider writes name, description, division, and a repo-relative source path because inlining every body would be about 3.8 million characters. Windsurf's accumulate_windsurf does inline every body into one .windsurfrules file.
- OpenClaw conversion splits each body into SOUL.md (headers matching identity, learning/memory, communication, style, critical rules) versus AGENTS.md (everything else) plus IDENTITY.md from emoji and vibe. install_openclaw registers new workspaces with openclaw agents add when the binary exists.
- The Hermes plugin exposes exactly four tools: agency_agents_search (query, optional division and limit), agency_agents_inspect (agent or slug, include_body), agency_agents_load (agent or slug, task), and agency_agents_delegate (agent or slug, required task). The committed README records a generated count of 279.
- NEXUS is the multi-agent orchestration layer in strategy/. QUICKSTART.md defines NEXUS-Full (all agents, 12-24 weeks), NEXUS-Sprint (15-25 agents, 2-6 weeks), and NEXUS-Micro (5-10 agents, 1-5 days), activated by prompting Agents Orchestrator.
- strategy/runbooks.json is the machine-readable roster the desktop app uses for one-click team deploy. Shipped scenarios include startup-mvp, enterprise-feature, and the docs scenario-incident-response.md and scenario-marketing-campaign.md. Each runbook has slug, title, mode, doc, and grouped agents with activation.
- MCP memory is an optional, non-installing integration. integrations/mcp-memory/setup.sh only prints instructions and looks for ~/.config/claude/mcp.json, ~/.cursor/mcp.json, or .mcp.json. It expects an external server exposing remember, recall, rollback, and search.
- Chinese localization is a post-install PowerShell step, scripts/i18n/localize-agents-zh.ps1, driven by scripts/i18n/agent-names-zh.json. It rewrites name and description in installed Copilot files under %USERPROFILE%\.github\agents and %USERPROFILE%\.copilot\agents.
Data flow
Source of truth is the division markdown files. lib.sh parses frontmatter and body. convert.sh transforms each agent into a host format under integrations/, except Claude Code and Copilot, which install the source file unchanged. install.sh filters by slug, then copies or symlinks into a host directory resolved from --path, an env override, or a hardcoded default. Hermes is the outlier: bodies are packed into data/agents.json and only the matched specialist is returned or delegated at runtime. Runbook deploys use a different identifier, the filename stem, than the installer slug.
- get_field reads the first YAML frontmatter scalar, strips one matching quote pair, and folds indented continuation lines into a single space-separated value so multi-line descriptions are not truncated. get_body returns everything after the second --- fence.
- agent_slug is get_field name piped through slugify, which lowercases and replaces non-alphanumeric runs with single hyphens. That slug is the install filter key and the filename stem for most converters (frontend-developer), while Antigravity and Osaurus prefix it with agency-.
- The convert loop walks AGENT_DIRS, skips files whose first line is not --- and files with an empty name, then dispatches convert_<tool> or accumulate_<tool>. clean_tool_output first deletes prior output except README.md so renamed agents do not leave orphans.
- OpenCode files are markdown with name, description, mode subagent, and a resolved #RRGGBB color. Cursor files are .mdc with description, empty globs, and alwaysApply false. Gemini CLI files keep name/description frontmatter plus the raw body. Codex writes a TOML file under integrations/codex/agents/<slug>.toml.
- yaml_quote wraps values in single quotes and doubles apostrophes. toml_escape_string shells out to perl -0pe to escape backslashes, quotes, newlines, and other control characters before they are embedded in TOML.
- Install destination order is --path, then a tool-specific env var, then the default. CLAUDE_CONFIG_DIR is treated as the config root and agents are placed in its agents/ subdirectory unless the value already ends in /agents. path_collision_group blocks --path when two tools would write the same filenames (raw-source-md, slug-md, or agency-skill).
- build_selection unions slugs from --division (every agent_slug in those dirs), --agent, and --agents-file. slug_allowed strips a leading agency- prefix. With no filter, SELECTION_ACTIVE stays false and every frontmatter file is installed. Hermes later warns that selection flags are ignored.
- ensure_converted auto-runs convert.sh --tool when integrations/<tool> has no file other than README.md. Claude Code and Copilot return immediately. AUTO_CONVERT defaults true and --no-convert disables it.
- Hermes data flow packs every agent into data/agents.json (slug, name, description, division, color, emoji, vibe, source_path, body). At runtime _load_agents reads that JSON once. Search tokenizes the query and scores name, description, division, vibe, and body[:8000]. Load and delegate call _specialist_prompt, which prepends a 'obey higher-priority system instructions' wrapper and the user task.
- Delegate context is truncated to _MAX_LIFECYCLE_CONTEXT_CHARS (32000) with an explicit truncation marker. The wait budget is _DELEGATION_WAIT_SECONDS 330 and cancellation wait 30. On failure the handler returns the composed prompt instead of the subagent result.
- Runbook slugs are filename stems, not name-slugs. check-runbooks.sh builds the real set with git ls-files '*.md', drops integrations/examples/strategy/scripts/.github, and requires every roster agents[] entry to match a basename without .md. startup-mvp's core team therefore lists engineering-frontend-developer, while install --agent frontend-developer is the name slug of that same file.
- scripts/convert-outputs.sha256 is the drift manifest for generated output. test-convert-outputs.sh records one hash per agent across every tool, one hash per tool's non-agent files, and contract hashes for divisions.json, tools.json, and runbooks.json. Hashes are normalized to forward slashes and LF.
Behavior traces
Three flows dominate: installing into a host, regenerating integration files, and turning the roster into a Hermes plugin that can search and delegate. A fourth, docs-only flow is NEXUS activation by pasting a prompt. The traces below name the functions in call order as they appear in the scripts.
- Install startup: main parses flags, do_list exits early for --list, build_selection computes _ALLOWED_SLUGS, check_integrations requires integrations/ to exist, then either interactive_wizard or the detect loop fills SELECTED_TOOLS. Dry-run prints the plan via selected_agent_count and exits before any write.
- Non-interactive detection calls is_detected per ALL_TOOLS entry, which dispatches detect_claude_code (directory ~/.claude or CLAUDE_CONFIG_DIR), detect_copilot (code binary or ~/.github or ~/.copilot), detect_hermes (hermes binary or HERMES_HOME), and the other detect_* helpers. Zero detections exits 0 with a tip, not an error.
- Wizard order is tui_begin, then screen_tools -> screen_teams -> screen_review. Each screen calls selector, which loops read_key and draw_frame. On install, the wizard commits SELECTED_TOOLS and, if not every team is selected, FILTER_DIVISIONS, then build_selection. No TTY makes interactive_wizard return 1 and main falls through to auto-detect.
- A real install calls install_tool, which calls ensure_converted then the matching install_<tool>. Sequential mode prints progress_bar around each tool. --parallel re-execs install.sh with AGENCY_INSTALL_WORKER=1 via xargs -P, passing worker_flags (--link, --no-convert, --path, --division, --agent, --agents-file).
- Claude Code file loop: for each AGENT_DIRS entry, find *.md, is_agent_file, agent_slug, slug_allowed, install_file (cp, or ln -sf if --link) into the resolved dest. Copilot repeats that write into two directories and counts once.
- Convert startup: main validates --tool against valid_tools, then run_conversions. For a normal tool it clean_tool_output, find-sorts markdown, skips non-frontmatter, and calls the converter. --parallel on tool=all runs every tool except aider and windsurf through xargs, because those two share temp accumulators, then runs them serially.
- OpenClaw convert of one file: get_field name/description, slugify, get_body, then a line loop that uses fence_open_p/fence_closes_p so fenced ## lines are not section breaks, classifies headers into soul vs agents, and writes SOUL.md, AGENTS.md, and IDENTITY.md.
- Hermes install order: ensure_converted may call convert.sh --tool hermes; install_hermes checks plugin.yaml, __init__.py, and data/agents.json exist; if HERMES_PLUGIN_DIR's basename is not agency-agents-router it appends that segment; rm -rf only that directory; cp -R or ln -s; ensure_hermes_plugin_enabled; then a python one-liner prints len(agents.json).
- ensure_hermes_plugin_enabled copies config.yaml to config.yaml.bak.agency-agents-plugin.$$, then an inline Python script finds the plugins: block, repairs lines where '- ' was glued into a scalar, and inserts '- agency-agents-router' at the existing list-item indent. It exits 0 if the plugin is already present and exits 1 without writing when it cannot find an insertion point.
- Hermes delegate order inside the generated plugin: _identifier, _agent_lookup, require task, _specialist_prompt as fallback, import SubagentLaunchRequest, lifecycle.launch, lifecycle.wait(330), on timeout lifecycle.cancel then wait(30), lifecycle.result, and on any exception return either pending or the fallback prompt.
- Lint of one agent: lint_file rejects CRLF, requires an opening ---, requires name/description/color, checks color against names awk-extracted from resolve_opencode_color, warns if Identity, Core Mission, or Critical Rules are absent, warns under 50 words, and warns if no ## header classifies as soul or as agents.
- NEXUS-Sprint startup, as documented rather than executed, is a pasted prompt: activate Agents Orchestrator, skip Phase 0, staff PM/design/engineering/QA/support roles, begin at Phase 1, and require Reality Checker approval before launch. The matching runbook startup-mvp lists agents-orchestrator plus engineering-frontend-developer and testing-reality-checker as always-on.
Testing signals
Tests are shell scripts and one unittest module, not a pytest or npm suite. They are designed for bash 3.2 and no jq. CI runs installer behavior on Linux and macOS, catalog consistency on every PR, and agent lint only when agent or linter paths change. The generated-output eval needs PyYAML and Python 3.11 tomllib and treats manifest drift as advisory on pull requests. Large gaps are the converter installers other than the two identity tools, and the agent prompt bodies themselves, which no test executes.
- test-install.sh is a custom bash harness (pass/fail/xfail_eq, not a framework). It sets HOME to a mktemp sandbox, refuses to touch the real home, and only installs claude-code and copilot so it does not depend on fresh convert.sh output. It checks --help, --list teams against divisions.json, --dry-run writes zero files, default ~/.claude/agents count equals the frontmatter roster, and --path overrides the default.
- test-install.yml also runs bash -n on every scripts/*.sh before the harness, on ubuntu-latest and macos-latest, fail-fast false, for every pull_request and every push to main.
- test-agent-selection.sh asserts --agent definitely-not-an-agent and a bad --agents-file exit non-zero with 'Unknown agent' / 'in agents-file', and that --agent 'Developer Tooling Engineer' dry-runs as Agents: 1. check-tools.yml runs it on every PR and main push.
- test-convert-frontmatter.sh runs convert.sh for gemini-cli, opencode, and qwen into a temp dir and asserts selected frontmatter fields are single-quoted YAML scalars, including description on developer-tooling-engineer and tools on programmatic-display-buyer.
- test-convert-outputs.sh is the generated-product eval: round-trip of description, strict YAML/TOML parse, one output per roster agent per tool, and sha256 drift against scripts/convert-outputs.sha256. It requires python3 with yaml and tomllib. CI passes --drift=advisory on pull_request and strict mode on push to main.
- check-hermes-plugin.py loads build-hermes-plugin.py, builds into a temp dir, calls register on a RecordingContext, asserts the four tool names and JSON-schema shape, and runs a live search for 'backend architecture' then inspect by the returned slug.
- test-hermes-plugin.py is unittest. It imports the committed integrations/hermes/agency-agents-router/__init__.py if present and drives FakeLifecycle through State.SUCCEEDED, FAILED, CANCELLED, timeouts, and launch errors. That generated __init__.py is gitignored, so a clean checkout does not contain the module the test imports until convert.sh --tool hermes has been run.
- check-hermes-config-rewrite.sh is a regression for the plugins.enabled indent bug. The workflow runs it on every PR and main push and documents the two symptoms: wrong indent collapsing enabled into a scalar, and non-idempotent duplicate inserts.
- check-divisions.sh and check-runbooks.sh are CI gates, not unit tests. Divisions must match disk, both AGENT_DIRS arrays, lint-agents.yml path filters, and each division must contain at least one frontmatter file. Runbooks must be valid JSON, have unique slugs, existing doc paths, and roster stems that git ls-files can resolve.
- lint-agents.yml runs only on pull_request, path-filtered to division trees plus scripts/lint-agents.sh, convert.sh, and lib.sh. The lint job lints git-diff changed agent files and then check-agent-originality.sh on those files. A second job lints the entire roster only when the linter, converter, or lib.sh changed.
- check-agent-originality.sh embeds Python that builds 8-word shingles after stripping a fixed ENTITY proper-noun list, then Jaccard-compares candidates to the roster. ORIGINALITY_FAIL defaults to 40 and ORIGINALITY_WARN to 20. Exit 1 at or above the fail threshold. The header says the existing library's worst pair is about 1.5 percent.
- What is not covered: no test executes an agent prompt; test-install.sh never calls install_opencode, install_cursor, install_hermes, or install_openclaw; lint does not run on push to main; and there is no coverage tool, fixture app, or browser suite. Agent markdown under testing/ is a division of QA personas, not this repo's test suite.
Risk map
The highest-impact code is install.sh, because it writes outside the repo, rewrites Hermes config, can delete a plugin directory, and can symlink the catalog into a host. Agent markdown is prompt supply chain: a merged file is copied verbatim into users' coding agents. The two slug systems and the hardcoded AGENT_DIRS copies are the main ways a catalog change silently drops or mis-addresses agents. Tests pin the identity installers well and the other hosts mostly by conversion invariants.
- install.sh writes to $HOME and $PWD by design: ~/.claude/agents, ~/.github/agents, ~/.copilot/agents, ~/.hermes, ~/.openclaw, and project .cursor/rules and .opencode/agents. --path replaces the destination with any caller-supplied directory. --link uses ln -sf, so a later edit in the clone changes the installed agent.
- install_hermes rm -rf's the destination after forcing the basename to agency-agents-router, which is meant to avoid deleting a shared plugins directory. ensure_hermes_plugin_enabled still rewrites the user's config.yaml and only warns if that Python step fails. A backup is config.yaml.bak.agency-agents-plugin.<pid>.
- install_openclaw shells out to openclaw agents list --json and openclaw agents add --workspace --non-interactive when the binary is on PATH. Failure of add is swallowed with || true.
- clean_tool_output runs find ... -exec rm -rf on integrations/<tool> children except README.md. The only guard is a ^[a-z0-9-]+$ match on the tool name so a future caller cannot pass ../. convert.sh --out can redirect that tree anywhere.
- Parallel install interpolates worker_flags unquoted: sh -c '... $AGENCY_INSTALL_EXTRA ...'. A --path value containing spaces or shell metacharacters is split. test-install.sh exists specifically because a path with a space was previously split into two destinations.
- SECURITY.md scopes the threat model to markdown prompts plus shell scripts: no secrets in agent files, no executable code inside markdown, review scripts before merge, and report agent files that attempt prompt injection via a private GitHub advisory rather than a public issue. Nothing in CI scans agent bodies for injection or exfiltration text.
- Hermes search and delegate put attacker-controlled query/task strings next to the full specialist body. _specialist_prompt tells the model to obey higher-priority instructions, but the body itself is unfiltered catalog text, and include_body returns it raw. Delegation imports agent.subagent_lifecycle from the Hermes process.
- Filename-stem IDs and name-slugs diverge. check-runbooks.sh and the desktop app use the .md basename. install.sh --agent and converters use slugify(name). engineering-frontend-developer.md is named Frontend Developer, so its installer slug is frontend-developer. Passing a runbook slug to --agent fails agent_slug_exists unless that string happens to match a name slug.
- Division lists are copied. install.sh reads divisions.json, but convert.sh and lint-agents.sh hardcode AGENT_DIRS. The comment in install.sh says a hardcoded copy previously dropped healthcare (#655/#668). check-divisions.sh is the only thing that keeps the copies aligned, and it does not parse install.sh because that file no longer has a literal division array.
- lint-agents.yml does not run on push to main and does not run at all unless a division path or the linter scripts change. A PR that only edits install.sh will not lint agents. Whole-roster lint uses github.base_ref, which the workflow only defines for pull_request.
- OpenCode silently drops agents above about 119. The installer only warns (capacity_warn, wizard footer, dry-run). It still writes every selected file. Installing the full 279-agent roster into OpenCode is a known partial failure.
- i18n localize-agents-zh.ps1 rewrites installed name and description fields in the user's Copilot directories. That mutates files install.sh just copied and can desync them from the name slug the converters computed. The script is PowerShell and is not invoked by the bash CI workflows.
Extension points
New behavior is meant to plug in at three registries: a division, a tool, or a runbook. Agents themselves are just new markdown files that survive lint. Host-specific rendering is a convert_<tool> function plus an install_<tool> function, keyed by tools.json. Hermes tools are registered in one Python register() function inside the generator, not discovered from disk. Color names are a closed case list inside resolve_opencode_color.
- To add a division, CONTRIBUTING and check-divisions.sh require: create the directory with at least one frontmatter agent, add label/icon/color to divisions.json, and add the name to AGENT_DIRS in both scripts/convert.sh and scripts/lint-agents.sh. The lint workflow path filters must mention <div>/ or check-divisions.sh fails. Do not add strategy or integrations.
- To add a tool, tools.json's _note says: add the entry (id, label, kebab, format, installKind, dest), add convert_<tool> or reuse a format in convert.sh, add install_<tool> in install.sh, then run scripts/check-tools.sh. installKind must be per-agent, roster, or plugin. The same format name must mean byte-identical output.
- install_tool is the dispatch table. A new host does nothing until its kebab appears in ALL_TOOLS, is_detected, tool_label, the main --tool validator, and this case statement. convert.sh has a parallel case inside run_conversions plus the valid_tools array.
- Claude Code and Copilot are the identity format: no converter, install copies the source file. check-tools.sh treats converter tools as a subset of tools.json for that reason. A new identity tool still needs an install_<tool> and an ALL_TOOLS entry, not a convert function.
- Named colors are a closed map in resolve_opencode_color. lint-agents.sh awk-extracts the case arms and rejects any other non-hex color. CONTRIBUTING says a new name must be added to that map in the same PR or OpenCode silently renders grey (#6B7280).
- A new agent is a markdown file in a division, first line ---, with name, description, and color. The template in CONTRIBUTING.md is the section contract convert_openclaw and classify_header_target both key off. Optional frontmatter services is documented as a list of name, url, and tier.
- Nested agent files are already supported. find walks game-development subdirectories (unity, unreal-engine, godot, roblox-studio, blender). Division membership is the top-level directory, not the filename prefix.
- Runbook extension is an object in strategy/runbooks.json plus a prose file under strategy/runbooks/. Required fields are slug, title, mode, doc, and roster. agents[] must be filename stems. check-runbooks.sh fails the build on a dangling slug, missing doc, or duplicate runbook slug.
- Hermes tool extension is inside init_py() in build-hermes-plugin.py. register(ctx) calls ctx.register_tool four times with a schema and handler. plugin_yaml lists the same names under provides_tools. Adding a tool means editing both the generated source strings and check-hermes-plugin.py's expected_tools set.
- OpenClaw section routing is a keyword classifier, duplicated in convert_openclaw and lint-agents.sh classify_header_target. Headers matching identity, learning+memory, communication, style, critical rule, or rules you must follow go to SOUL.md; every other ## header goes to AGENTS.md. A new section title with none of those words will not land in SOUL.md.
- Originality's ENTITY regex is the extension point for market re-skins. Adding a country or platform name there stops a find-replace localization from looking novel. The check is otherwise generic shingle overlap and does not know about divisions.
- examples/ is a documentation extension, not a registry the scripts scan. examples/README.md invites new multi-agent writeups. The installer never reads examples/.
Contributor handoff
Read the two catalogs and the three scripts before editing anything. Keep bash 3.2 and no jq. Do not hand-edit generated integration trees. Treat filename stems and frontmatter slugs as different IDs. Run the small shell checks that match the surface you touched; the full convert-output hash only needs --update when a generator changes, and pull-request CI will not fail an agent PR for drift. The dangerous directory is the user's home, not the repo.
- Files to read first: README.md (install paths), CONTRIBUTING.md (agent template and division rules), divisions.json, tools.json, scripts/lib.sh, the flag block and main of scripts/install.sh, and the converter dispatch in scripts/convert.sh. For orchestration work, also strategy/QUICKSTART.md and strategy/runbooks.json.
- Safe content edits are a single division markdown file that keeps LF endings, required frontmatter, and the persona-versus-operations section split. .gitattributes forces LF on md, yml, yaml, and sh. lint-agents.sh errors on any CR.
- Do not commit generated files. .gitignore excludes the per-tool payloads. Regenerate with ./scripts/convert.sh or ./scripts/convert.sh --tool <name>. The only tracked integration files are the READMEs.
- Bash constraint: comments in lib.sh, check-divisions.sh, check-tools.sh, and test-install.sh all require bash 3.2 and BSD userland. Do not use mapfile, associative arrays, ${var,,}, or jq. Integer timeouts in read_key exist because bash 3.2 has no fractional read -t.
- Minimum checks after a script change: bash -n scripts/*.sh, ./scripts/check-divisions.sh, ./scripts/check-tools.sh, ./scripts/check-runbooks.sh, ./scripts/test-install.sh, bash scripts/test-agent-selection.sh, bash scripts/test-convert-frontmatter.sh, python3 scripts/check-hermes-plugin.py, ./scripts/check-hermes-config-rewrite.sh. test-install.sh is the one that must pass on both Linux and macOS bash.
- After an agent-only edit, run ./scripts/lint-agents.sh on that file and ./scripts/check-agent-originality.sh on that file. You do not need to refresh scripts/convert-outputs.sha256 for CI on a pull request: test-convert-outputs.sh is invoked with --drift=advisory there, and maintainers regenerate at landing. A generator or template change should ship with --update so the tool hash moves in the same commit.
- test-convert-outputs.sh exits 2 unless python3 can import yaml and tomllib, so it needs PyYAML and Python 3.11+. The other Python checks use only the standard library.
- Known trap: healthcare was dropped when a hardcoded division list drifted (#655/#668). If you add a division, update divisions.json and both AGENT_DIRS arrays and the lint workflow. install.sh will pick the JSON up by itself; convert.sh will not.
- Known trap: color names outside resolve_opencode_color fail lint, and unknown names that somehow skip lint become #6B7280 in OpenCode. Hex #RRGGBB always works. The linter's known-name list is parsed from the function body, so formatting that case statement differently can make KNOWN_COLORS empty and skip the name check with a WARN.
- Known trap: fenced code. GDScript and other fences contain ## lines. Both the linter and convert_openclaw must keep using fence_open_p and fence_closes_p. A naive '^## ' scan mis-splits SOUL.md versus AGENTS.md (issue #849, referenced in both files).
- Known trap: get_field only understands a flat 'key: value' scalar plus indented continuations. Nested YAML such as services will not come back as structured data. Hermes parse_agent similarly skips indented frontmatter lines and only keeps the first single-line value.
- Do not point experiments at a real home. test-install.sh sandboxes HOME. install_hermes deletes and replaces the plugin dir and rewrites config.yaml. install_openclaw calls the openclaw CLI. SECURITY.md says never commit credentials and never put executable payloads in agent markdown.
Languages
| Language | Files | Share of source |
|---|---|---|
| Markdown | 325 | docs/config |
| Shell | 14 | 78% |
| YAML | 9 | docs/config |
| JSON | 4 | docs/config |
| Python | 4 | 22% |
Start reading here
Probable source entrypoint: engineering/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
engineering/ (64 files) specialized/ (59 files) marketing/ (36 files)
Source layout — engineering/
| Path | Files |
|---|---|
engineering/engineering-ai-data-remediation-engineer.md | 1 |
engineering/engineering-ai-engineer.md | 1 |
engineering/engineering-api-platform-engineer.md | 1 |
engineering/engineering-ats-validator-architect.md | 1 |
engineering/engineering-autonomous-optimization-architect.md | 1 |
engineering/engineering-backend-architect.md | 1 |
engineering/engineering-china-network-engineer.md | 1 |
engineering/engineering-cms-developer.md | 1 |
engineering/engineering-code-reviewer.md | 1 |
engineering/engineering-codebase-onboarding-engineer.md | 1 |
engineering/engineering-data-engineer.md | 1 |
engineering/engineering-data-visualization-engineer.md | 1 |
engineering/engineering-database-optimizer.md | 1 |
engineering/engineering-database-reliability-engineer.md | 1 |
Repository structure
| Top-level path | Files |
|---|---|
engineering/ | 64 |
specialized/ | 59 |
marketing/ | 36 |
scripts/ | 22 |
game-development/ | 21 |
integrations/ | 19 |
strategy/ | 17 |
gis/ | 13 |
Docs found: CONTRIBUTING.mdREADME.md
CI & config entrypoints
README.md— Repository readme.github/workflows/test-install.yml— GitHub Actions workflow.github/workflows/lint-agents.yml— GitHub Actions workflow.github/workflows/check-divisions.yml— GitHub Actions workflow.github/workflows/check-hermes-config-rewrite.yml— GitHub Actions workflow.github/workflows/check-runbooks.yml— GitHub Actions workflow.github/workflows/check-tools.yml— GitHub Actions workflow
Structural health signals
Average score 7/10 across 4 analyzed source files; 1 hotspot surfaced.
scripts/build-hermes-plugin.py— 599 lines, score 5.9 (Large file, Deep nesting)scripts/check-hermes-config-rewrite.py— 199 lines, score 6.6 (Deep nesting, High churn)scripts/test-hermes-plugin.py— 170 lines, score 7.4 (Deep nesting, Moderate churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
053ddbbf392a2026-09-21 — docs(readme): remove the Related Resources section (#878)652277fba1af2026-09-21 — fix(install): tell aider users when their CONVENTIONS.md is our stale roster (#875)87f8301cad382026-09-20 — chore(eval): regenerate the convert-outputs manifest for #871 and #8721f92396556872026-09-20 — fix(convert): two color names fall through to grey, and nothing checked (#872)d3a3f573e3332026-09-20 — fix(aider): CONVENTIONS.md is a roster index, not 3.8 million characters of agents (#871)