# Contributor handoff — msitarzewski/agency-agents

> Canonical page: https://codevetter.com/unpack/agency-agents/agent-handoff

# Contributor handoff — msitarzewski/agency-agents

Scanned commit 053ddbbf392a1688fc7043d81529f47ef2cf86c8 (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

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. — [README.md#L46-L102](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/README.md#L46-L102) [CONTRIBUTING.md#L87-L162](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/CONTRIBUTING.md#L87-L162) [scripts/lib.sh#L1-L14](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lib.sh#L1-L14) [strategy/QUICKSTART.md#L1-L18](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/strategy/QUICKSTART.md#L1-L18)
- 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. — [.gitattributes#L1-L5](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.gitattributes#L1-L5) [scripts/lint-agents.sh#L82-L88](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lint-agents.sh#L82-L88) [CONTRIBUTING.md#L164-L185](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/CONTRIBUTING.md#L164-L185)
- 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. — [.gitignore#L66-L87](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.gitignore#L66-L87) [scripts/convert.sh#L29-L30](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/convert.sh#L29-L30) [integrations/README.md#L59-L65](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/integrations/README.md#L59-L65)
- 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. — [scripts/lib.sh#L5-L6](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lib.sh#L5-L6) [scripts/lib.sh#L171-L174](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lib.sh#L171-L174) [scripts/check-tools.sh#L14-L15](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/check-tools.sh#L14-L15) [scripts/test-install.sh#L10-L13](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/test-install.sh#L10-L13)
- 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. — [.github/workflows/test-install.yml#L23-L30](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/workflows/test-install.yml#L23-L30) [.github/workflows/check-tools.yml#L17-L34](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/workflows/check-tools.yml#L17-L34) [.github/workflows/check-divisions.yml#L17-L20](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/workflows/check-divisions.yml#L17-L20) [.github/workflows/check-runbooks.yml#L17-L20](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/workflows/check-runbooks.yml#L17-L20)
- 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. — [scripts/test-convert-outputs.sh#L32-L45](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/test-convert-outputs.sh#L32-L45) [.github/workflows/check-tools.yml#L28-L31](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/workflows/check-tools.yml#L28-L31) [.github/workflows/lint-agents.yml#L59-L73](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/workflows/lint-agents.yml#L59-L73)
- 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. — [scripts/test-convert-outputs.sh#L67-L69](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/test-convert-outputs.sh#L67-L69) [scripts/check-hermes-plugin.py#L1-L8](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/check-hermes-plugin.py#L1-L8)
- 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. — [scripts/install.sh#L135-L138](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/install.sh#L135-L138) [CONTRIBUTING.md#L40-L45](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/CONTRIBUTING.md#L40-L45) [scripts/check-divisions.sh#L87-L89](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/check-divisions.sh#L87-L89)
- 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. — [scripts/convert.sh#L216-L220](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/convert.sh#L216-L220) [scripts/convert.sh#L262-L263](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/convert.sh#L262-L263) [scripts/lint-agents.sh#L42-L53](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lint-agents.sh#L42-L53)
- 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). — [scripts/lib.sh#L67-L91](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lib.sh#L67-L91) [scripts/lint-agents.sh#L155-L174](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lint-agents.sh#L155-L174) [scripts/convert.sh#L337-L358](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/convert.sh#L337-L358)
- 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. — [scripts/lib.sh#L19-L40](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/lib.sh#L19-L40) [scripts/build-hermes-plugin.py#L47-L54](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/build-hermes-plugin.py#L47-L54) [CONTRIBUTING.md#L98-L102](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/CONTRIBUTING.md#L98-L102)
- 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. — [scripts/test-install.sh#L11-L16](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/test-install.sh#L11-L16) [scripts/install.sh#L1264-L1276](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/scripts/install.sh#L1264-L1276) [SECURITY.md#L26-L30](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/SECURITY.md#L26-L30)
- 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. — [.github/PULL_REQUEST_TEMPLATE.md#L1-L16](https://github.com/msitarzewski/agency-agents/blob/053ddbbf392a1688fc7043d81529f47ef2cf86c8/.github/PULL_REQUEST_TEMPLATE.md#L1-L16)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)