Harmonist Files

Initial public release. Harmonist ships 186 curated agents, a Schema-v2 frontmatter contract, structured validated memory, and a hook-driven enforcement layer that cannot be skipped by the LLM.

Catalogue

• 186 agents across 16 categories. Unified pool under agents/<category>/<slug>.md, every file conforming to Schema v2. Strict agents (orchestration, review) drive the mandatory gates; persona agents are free-form specialists with domain depth.
• Data-driven routing. agents/index.json is the single routing table the orchestrator consults. Adding or renaming an agent requires zero edits to AGENTS.md.
• Disambiguation metadata. Every agent with near-peers carries distinguishes_from + a one-line disambiguation note so the orchestrator can tie-break between look-alike specialists.
• Domain filter + role filter. The integration prompt asks for both the project's domains (blockchain / gamedev / china-market / healthcare / etc.) and its working roles (engineering, design, product, marketing, sales, support, finance, testing, academic) to select a sensible starter set of specialists, not a one-size-fits-all dump.

Enforcement

• Cursor hooks drive the stop gate. The stop hook parses AGENT: <slug> markers from subagent prompts and refuses to allow turn completion if qa-verifier has not run, if any required reviewer is missing, or if session-handoff.md was not updated. loop_limit: 3 caps retries; on exhaustion, an incident is recorded in .cursor/hooks/.state/incidents.json and surfaced in the next sessionStart as a PROTOCOL-EXHAUSTED banner.
• Cross-platform runner. hooks/scripts/hook_runner.py is a pure-Python implementation of every hook phase, so native Windows works out of the box; WSL / macOS / Linux can stay on the POSIX .sh variants via hooks/hooks.posix.json.
• Capability scoping. Agents marked readonly: true are blocked from writing files; violations are logged.
• PROTOCOL-SKIP abuse guard. The escape hatch for trivial turns is tracked in telemetry; excessive use triggers a warning injected into the session bootstrap context.

Memory

• Schema v1 memory contract. .cursor/memory/*.md entries are YAML blocks delimited by <!-- memory-entry:start --> / <!-- memory-entry:end --> with 7 required frontmatter fields. validate.py enforces every rule and is wired into the stop hook.
• Hook-generated correlation IDs. correlation_id has the form <session_id>-<task_seq>, generated at session start (<unix-seconds><pid4> — collision-safe across parallel sessions) and advanced by the stop gate. The LLM cannot invent IDs.
• CLI as the only write path. memory.py append validates before writing, scans for ~30 classes of secrets (AWS / GitHub / Stripe / GCP / Azure / Slack / Telegram / Discord / SendGrid / DigitalOcean / npm / PyPI / DB DSNs / generic high-entropy tokens / vendor-scoped UUIDs for Heroku, Postmark, etc.), and rejects placeholder-fenced content correctly so ${STRIPE_KEY} still writes cleanly.
• Search + rotate + dedupe. memory.py search filters by tag / kind / correlation / summary; rotate archives older entries; dedupe refuses identical-summary appends unless --allow-duplicate.

Supply-chain integrity

• MANIFEST.sha256 covers every shipped file. check_pack_health.py runs build_manifest.py --verify on every preflight; a tampered source is flagged.
• Upgrade guard. upgrade.py --apply sha-verifies every pack source BEFORE copying into .cursor/. A tampered security-reviewer.md is REFUSED.
• Install-extras guard. install_extras.py inherits the same sha-verification for on-demand specialist installs.
• Post-install anchor. .cursor/pack-manifest.json records the sha of every installed pack-owned file so verify_integration.py can detect someone weakening enforcement after install.
• Snapshot + rollback. upgrade.py --apply takes a pre-apply tarball snapshot under .cursor/.integration-snapshots/; upgrade.py --rollback restores from the most recent snapshot.

Prompt-injection scanner

• scan_agent_safety.py runs a heuristic regex pass over every agent markdown for four classes of hostile content: override (jailbreak markers, "ignore previous instructions"), exfil (secret leak attempts, .env access), remote exec (pastebin / ngrok / webhook.site callbacks, curl | bash, base64-decode-exec), policy subversion ("skip qa-verifier", "always approve silently"). Runs in CI; exit 1 on any error-severity hit. False-positive guards for legitimate MITRE ATT&CK threat docs.

Integrations

• 11 IDE targets via converters under agents/integrations/: Cursor, Claude Code, GitHub Copilot, Windsurf, OpenCode, Aider, Kimi, Qwen, Gemini CLI, Antigravity, OpenClaw.
• Thin-variant mode. convert.sh --thin ships the essentials-only body of each persona agent (everything up to ## Deep Reference); typical saving ~38% across the pool.

Style + schema

• Schema v2 — agents/SCHEMA.md. Required frontmatter plus optional metadata (version, updated_at, deprecated, distinguishes_from, disambiguation, domains, color, emoji, vibe). Slug (filename stem) is the identity key used for routing; name is a human-readable display label.
• Style guide — agents/STYLE.md. Defines the two canonical shapes (strict vs persona), anti-patterns to avoid (personality theatre, adjective soup, emoji-prefixed headings, aspirational sections, cross-agent hand-off lists), a lightweight persona template, and a retrofit checklist.
• Deep Reference convention. Every persona agent with ≥ 80 non-blank body lines carries a ## Deep Reference marker. Thin variants cut at the marker; insert_deep_ref_marker.py adds the marker to any long persona automatically.

Tooling

• check_pack_health.py — 18 preflight checks (VERSION parses as SemVer, every directory + script present + executable, index / manifest fresh, lint clean, migrator idempotent, agent catalogue free of deprecated tech and prompt-injection patterns, README / AGENTS.md category counts match index.json).
• lint_agents.py — Schema v2 validator for every agent.
• build_index.py — deterministic routing-table generation.
• build_manifest.py — sha256 covering every shipped file (262 tracked files at 1.0.0).
• integrate.py / upgrade.py / deintegrate.py — full integration lifecycle.
• verify_integration.py — objective post-install audit.
• install_extras.py — on-demand specialist installation by slug / role / tag with sha-verification and thin-variant support.
• scan_agent_safety.py, scan_agent_freshness.py, scan_rules_conflicts.py, scan_memory_leaks.py — four complementary scanners for catalogue health and integration hygiene.
• merge_agents_md.py — replaces <!-- pack-owned --> blocks in a project's AGENTS.md with the newest pack version, preserving project-owned prose between marker pairs.
• insert_deep_ref_marker.py — automated cut-point insertion for long persona agents.
• detect_regression_commands.py — infers project test / lint / build commands from manifests for bg-regression-runner.
• onboard.py — walkthrough for teammates joining an already-integrated project.
• refresh_py_guard.py — keeps the 3.9+ version guard in sync across every entry script.

Testing

• ~430 test assertions across hook tests (30 scenarios), memory tests (29 scenarios), and 20 shell-based suites under agents/scripts/test_*.sh. All passing on first clean integration.
• GitHub Actions CI runs the full regression on every pull request and push to main.

Documentation

• Root-level README.md, AGENTS.md, GUIDE_EN.md, integration-prompt.md, CHANGELOG.md, LICENSE, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md.
• Agent-level agents/SCHEMA.md, agents/STYLE.md, agents/TAGS.md.
• Memory-level memory/SCHEMA.md, memory/README.md.
• Optional playbooks/ — the NEXUS 7-phase lifecycle with phase runbooks, coordination docs, and scenario playbooks for startup-MVP, enterprise-feature, incident-response, and marketing-campaign workflows.