CodeVetter · Repo Unpack · Contributor handoff
msitarzewski/agency-agents
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.
- PR template expects, for an agent change, the agent name, category, the CONTRIBUTING template, frontmatter name/description/color, concrete examples, and a claim the agent was tried in a real scenario. That last item is not enforced by CI.