Contributing to Harmonist

June 9, 2026 · View on GitHub

Thanks for taking the time to contribute. Harmonist is a portable AI agent orchestration pack — changes here affect every project that integrates it, so the bar for merging is intentionally strict.

This file is the short contract. Technical depth (agent schema, style, protocol) lives in:

  • agents/SCHEMA.md — frontmatter contract every agent must satisfy.
  • agents/STYLE.md — how the body of an agent should read (required sections, anti-patterns, retrofit checklist).
  • README.md — architecture overview and scripts reference.

Before you start

  1. Read CODE_OF_CONDUCT.md. By participating, you agree to it.
  2. For non-trivial work (new agent, new script, behaviour change, hook change), open an issue first describing the plan. This saves everyone time — we can flag concerns before you write code.
  3. Drive-by cosmetic edits (emoji removal, rewording 179 personas at once) will be closed without review. Do content-driven edits only.

How to contribute

Add or update an agent

  1. Pick the right agents/<category>/ directory. Categories are fixed (see agents/SCHEMA.md#category-enum); propose a new one only with a strong case.
  2. Start from agents/STYLE.md's lightweight template. Use plain ASCII headings, no personality-theatre sections.
  3. Frontmatter must satisfy Schema v2. Run the linter: 
    python3 agents/scripts/lint_agents.py
  4. Add a ## Deep Reference marker if the body exceeds ~80 non-blank lines (the --thin converter depends on it). Run: 
    python3 agents/scripts/insert_deep_ref_marker.py agents/<cat>/<slug>.md
  5. Regenerate the routing index and the manifest: 
    python3 agents/scripts/build_index.py
python3 agents/scripts/build_manifest.py

Change scripts / hooks / enforcement

  1. Every script change must pass: 
    python3 agents/scripts/check_pack_health.py        # 19 checks
bash hooks/tests/run-hook-tests.sh                 # 30 scenarios
bash memory/tests/run-memory-tests.sh              # 29 scenarios
  2. Any new behaviour needs a matching test case in the relevant test_*.sh under agents/scripts/ or hooks/tests/.
  3. Python scripts include a 3.9+ version guard. Never add third-party dependencies — stdlib only.

Fix bugs

  1. Reproduce first. A bug report without reproduction steps will be closed asking for one.
  2. Add a failing test before the fix, so the regression stays closed.
  3. For security-relevant bugs, follow SECURITY.md and open a private security advisory instead of a public issue.

Pull request checklist

  • Linter clean: python3 agents/scripts/lint_agents.py — 0 errors.
  • Pack healthy: python3 agents/scripts/check_pack_health.py — 19/19.
  • Relevant test suites pass (see the list under "Change scripts").
  • Index and manifest regenerated and committed.
  • If a user-facing behaviour changed: CHANGELOG.md updated.
  • If schema changed: version bumped + migrator updated.
  • PR description explains why, not just what.

What the maintainers will reject

  • PRs that disable, bypass, or weaken the enforcement layer (qa-verifier, hooks, memory validator) without an explicit review discussion first.
  • Edits to shipped agents/review/*.md or agents/orchestration/*.md that change their strict behaviour, unless scoped to the exact issue being fixed.
  • Committed build output (converted agent files, generated docs) — these are produced by convert.sh locally and are gitignored.
  • Bulk reformatting of the persona catalogue in a single PR — each category gets its own PR with the before/after lint output.
  • Adding third-party Python dependencies. The pack is stdlib-only by design.

Release process (maintainers only)

  1. python3 agents/scripts/check_pack_health.py — must be 19/19.
  2. Full regression: bash every agents/scripts/test_*.sh, hooks/tests/run-hook-tests.sh, memory/tests/run-memory-tests.sh.
  3. Update CHANGELOG.md: move [Unreleased] entries under a new version heading with today's date (ISO).
  4. Bump VERSION (SemVer). Breaking schema changes require a major bump and a migrator registered in migrate_schema.py or memory/migrations.py.
  5. Regenerate MANIFEST.sha256 and commit.
  6. Tag the release as vX.Y.Z and push.

Questions

Open an issue on the repository. For private matters, use a security advisory (see SECURITY.md).