If you are an AI agent asked to install or integrate this pack: read integration-prompt.md and execute its steps. Do not apply AGENTS.template.md as a live rule inside the pack folder — it is the template that becomes the user project's AGENTS.md during integration.

Most AI coding frameworks trust the language model to follow the rules. Harmonist refuses to let it skip them. Every code-changing turn is gated by hooks that check whether the required reviewers ran, whether memory was updated, and whether the supply chain of every shipped file is intact. If the checks fail, the turn doesn't complete — no matter how confidently the model claims it's done.

This is the first open-source agent framework where protocol enforcement is a mechanical gate, not a polite request in a prompt.

Why Harmonist exists

AI coding assistants have a structural problem that prompt engineering alone cannot fix.

The problem: every serious engineering workflow has non-negotiable rules — "no floating-point for money", "run QA before merging", "every external call retries with idempotency keys", "security review before touching auth code". An LLM can be told to follow them, but there is no mechanism forcing it to. It can agree, move on, and silently skip the step. On a good day you notice. On a bad day the bug ships.

The current landscape is split between two imperfect answers:

• Thin agent frameworks (LangChain, CrewAI, AutoGen, MetaGPT and many others) give you orchestration primitives but leave enforcement to the prompt. The model can always override its own protocol.
• Heavy enterprise platforms promise governance through separate runtimes, databases, and vendor lock-in — but need infrastructure to install, don't work on a solo developer's laptop, and can't be audited file-by-file.

Harmonist takes a different stance. Protocol enforcement is implemented as IDE-level hooks — concrete shell and Python scripts that observe every subagent dispatch, every file edit, every session stop. When the rules the project declared aren't met, the stop hook returns a followup_message to the AI and refuses to allow the turn to complete. The model can't argue with that; it's a state machine on disk.

No runtime. No database. No vendor lock-in. Just markdown, stdlib Python, and bash — sitting next to your code, doing one job correctly.

What makes it different

Seven concrete, checkable properties — each one addresses a gap that other open-source agent frameworks leave open.

1. Mechanical protocol enforcement via IDE hooks

The stop hook in .cursor/hooks/ parses subagent dispatch markers from the session, checks whether qa-verifier ran, whether any required reviewer was missing, whether session-handoff.md was updated, and returns a structured followup_message if the turn is incomplete. loop_limit: 3 caps retries. On exhaustion, an incident is recorded and surfaced in the next session. The AI literally cannot ship a code change that skipped review.

2. Supply-chain verification of agent definitions

All runtime-shipped content — agents/, hooks/, memory/, playbooks/, root docs — is hashed in MANIFEST.sha256 (CI configs and repo metadata are pack-repo-only and excluded). upgrade.py sha-verifies each source before copying into a project. A tampered security-reviewer.md (say, one that returns approve for everything) is REFUSED — it never enters the project. install_extras.py inherits the same guard for on-demand specialist installs. This is the first OSS agent catalogue with paranoid-level supply-chain posture.

3. Memory correlation IDs that the LLM cannot forge

Every memory entry has a correlation_id of the form <session_id>-<task_seq> generated by the hooks at session start (<unix-seconds><pid4> — collision-safe across parallel sessions). The LLM reads the active ID via CLI; it never writes the ID itself. This means the linkage between a state entry, a decision, and a pattern from the same task is cryptographically ordered from the hook's perspective — not trusted to the model.

4. Schema-validated memory with secret-pattern scanning

memory.py append is the only supported write path. It validates every entry against a YAML schema (memory/SCHEMA.md), rejects duplicates, and scans the body for ~30 classes of secrets: AWS access keys, GitHub PATs, Stripe tokens, Slack webhooks, GCP service accounts, Azure connection strings, Telegram bot tokens, Discord tokens, Heroku/Postmark UUIDs (context-scoped), generic high-entropy tokens with secret: prefixes, and DB connection strings with embedded credentials. Placeholder fences (${VAR}, <NAME>) suppress the scan so your templates still write cleanly.

5. 193 curated domain specialists, not one generic "coder"

Harmonist's catalogue is not a handful of roles. It's 193 curated specialists across 16 categories: blockchain-security-auditor for Solidity audits, zk-steward for zero-knowledge circuits, visionos- spatial-engineer for Apple Vision Pro, wechat-mini-program-developer and xiaohongshu-specialist for the China market, laravel-livewire- specialist for PHP, roblox-systems-scripter for Roblox Luau, 30+ marketing agents from SEO to Douyin, finance / sales / product / support / academic coverage. The orchestrator picks by domains × roles × tags, not by hard-coded slug lists.

6. Integration-as-a-prompt

There is no installer binary. Integration happens by pasting integration-prompt.md into a Cursor Agent-mode session. The AI reads the prompt, analyzes the project, asks the user which roles will be active (engineering / design / product / marketing / sales / support / finance / testing / academic), selects the right specialists from agents/index.json, and wires everything up — including writing a project-specific AGENTS.md with domain-tailored invariants. The AI integrates itself.

7. Zero runtime dependencies, runs natively on every OS

No npm, no Docker, no LangChain, no vector database. Pure Python stdlib (with optional POSIX .sh conveniences). Integration, upgrade, conversion, install, and the enforcement runtime all run natively on Windows, macOS, and Linux — no WSL or Git Bash required. The enforcement runtime has two implementations — POSIX .sh scripts for macOS / Linux / WSL, and a pure-Python hook_runner.py that is the active path on every OS (and the only one on native Windows). upgrade.py renders .cursor/hooks.json with a Python launcher that actually exists on the host (py -3 / python on Windows, python3 on POSIX). .gitattributes pins eol=lf so a Windows checkout can't break MANIFEST.sha256. Both hook paths are exercised against identical scenarios, and a native-Windows CI job runs the full install path end-to-end.

Requirements

• Python 3.9+ — every script ships with a version guard; older interpreters exit with a per-OS install hint.
• Bash 3.2+ is optional — only needed for the POSIX .sh conveniences and the shell test harness (macOS default works). All integration, upgrade, conversion, and install tooling is pure Python, and on native Windows the pure-Python hook_runner.py is the active hook path; no WSL or Git Bash required.
• Git for version tracking.
• An AI coding assistant that supports subagent dispatch — Cursor is the primary integration; Claude Code, Copilot, Windsurf, Aider, Kimi, Qwen, Gemini CLI, OpenCode, OpenClaw, and Antigravity are all supported via adapters.
• No third-party Python dependencies — stdlib only. No npm, no Docker, no LangChain, no vector database.

Quick start

The pack folder may have any name — docs refer to it as <PACK_DIR>. Examples below assume the folder is named harmonist (what git clone produces). The protocol template ships as AGENTS.template.md; the file generated in YOUR project during integration is named AGENTS.md.

Option 1 — Integrate via Cursor (recommended)

# 1. Clone into the root of your project (keep it as a SUBFOLDER —
#    do not unpack the pack's files into your project root)
cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.git

# 2. Open the project in Cursor, switch to Agent mode
# 3. Paste the contents of harmonist/integration-prompt.md
# 4. Follow the AI's walkthrough — it will ask about your
#    project's domain and roles, then wire everything up.
# 5. Start a NEW chat when integration is done.

That's it. The AI reads harmonist/agents/index.json, picks the right specialists for your stack, writes a domain-specific AGENTS.md (from AGENTS.template.md), bootstraps .cursor/memory/, installs the enforcement hooks, and records the integration state in .cursor/pack-version.json.

Option 2 — Integrate via CLI (no Cursor needed)

cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.git
python3 harmonist/agents/scripts/integrate.py --pack harmonist --project .

(If your pack folder has a different name, pass it via --pack <PACK_DIR>.)

On native Windows (PowerShell / cmd, no WSL or Git Bash), use the Python launcher — every script is pure stdlib and cross-platform:

cd your-project\
git clone https://github.com/GammaLabTechnologies/harmonist.git
py -3 harmonist\agents\scripts\integrate.py --pack harmonist --project .

Option 3 — Manual integration

See GUIDE_EN.md. Note: hand-copying files produces an unenforced setup (no hooks, rules, or .gitignore hardening), so the guide routes the "manual" path through integrate.py + verify_integration.py and lists what they automate.

Architecture

                     ┌────────────────────────────┐
                     │        AGENTS.md           │
                     │      Orchestrator          │
                     │                            │
                     │  Protocol · Hook Phases    │
                     │  Invariants · Memory       │
                     └─────────────┬──────────────┘
                                   │  reads
                                   ▼
                     ┌────────────────────────────┐
                     │   agents/index.json        │   ← generated
                     │                            │
                     │   by category · by tag     │   ← routing table
                     │   193 entries              │
                     └─────────────┬──────────────┘
                                   │  routes to
            ┌──────────────────────┼──────────────────────┐
            ▼                      ▼                      ▼
     ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
     │ orchestration│      │   review     │      │   persona    │
     │ (scout,      │      │ (strict,     │      │ (engineering,│
     │  repo-map)   │      │  readonly)   │      │  design, …)  │
     └──────────────┘      └──────────────┘      └──────────────┘
                                   │                      │
            ┌──────────────────────┴──────────────────────┐
            ▼                                             ▼
     ┌──────────────┐                             ┌──────────────┐
     │ Review gates │                             │   .cursor/   │
     │              │                             │   memory/    │
     │ qa · sec     │                             │              │
     │ sre · perf   │                             │ session      │
     │ regression   │                             │ decisions    │
     └──────────────┘                             │ patterns     │
                                                  └──────────────┘

How it works

1. Single unified pool. Every agent lives at agents/<category>/<slug>.md with the same Schema v2 frontmatter. One schema, one catalogue.
2. Data-driven routing. The orchestrator never hard-codes slugs. It extracts task tags ("payments", "react", "solidity"), intersects with agents/index.json, filters by the project's declared domains and roles, and picks the right specialist.
3. Protocol tiers by metadata. protocol: strict agents (orchestration + review) are mandatory gates that run on triggers. protocol: persona agents are free-form specialists with domain depth.
4. Hook-observed execution. sessionStart, afterFileEdit, subagentStart, subagentStop, beforeShellExecution, and stop hooks track the full lifecycle. The stop hook is the gate; the beforeShellExecution hook is a human-in-the-loop gate on destructive commands.
5. Persistent memory. Between sessions, state / decisions / patterns live under .cursor/memory/, linked by correlation IDs. The next session reads the last three state snapshots and three decisions before planning.

The 193-agent catalogue

Every count below is mirrored from agents/index.json and verified by check_pack_health.py — the table and the index cannot drift.

Each agent carries structured frontmatter: description, tags, domains, distinguishes_from (near-peers), disambiguation (one-line "when to pick this over X"), version, and updated_at. The orchestrator reads all of this for tie-breaking when multiple candidates match a task's tags.

Mechanical enforcement

The enforcement layer is what separates Harmonist from a "nice prompt pack". It lives in hooks/ and gets installed into .cursor/hooks/ at integration time.

Six hook phases

What the stop gate actually checks

If the session touched any file outside ignored patterns:

1. At least one category: review agent was invoked via Task.
2. Specifically qa-verifier was invoked.
3. .cursor/memory/session-handoff.md was updated during the session.

If any check fails, the hook returns followup_message telling the AI exactly what's missing. loop_limit: 3 caps retries. On exhaustion, the incident is persisted to .cursor/hooks/.state/incidents.json and surfaced in the next session as an unmissable banner.

PROTOCOL-SKIP escape hatch

For genuinely trivial turns (typo fix in a comment, markdown rewording), the AI can emit PROTOCOL-SKIP: <reason> to bypass the gate. The hook logs it. If the skip rate crosses a threshold (default > 25% of all completions, min 5 skips), the next session starts with a warning about abuse. Easy to opt out of cleanly; hard to abuse quietly.

Structured validated memory

Memory is a contract, not free-form markdown. Every entry is a YAML block delimited by <!-- memory-entry:start --> / <!-- memory-entry:end --> with required fields: id, correlation_id, at, kind, status, author, summary.

Three files with explicit roles:

CLI as the only write path

python3 .cursor/memory/memory.py append \
  --file session-handoff --kind state --status done \
  --summary "Integrated Stripe webhook handler" \
  --tags payments,backend \
  --body-file /tmp/handoff-body.md

The CLI:

• Generates id and at deterministically.
• Reads the active correlation_id from the hooks (not from the LLM).
• Validates the entry against memory/SCHEMA.md before writing.
• Scans the body for ~30 secret patterns and rejects leaks.
• Refuses duplicates unless --allow-duplicate.

Search, rotate, dedupe

python3 .cursor/memory/memory.py search --tag payments
python3 .cursor/memory/memory.py latest --file session-handoff --n 5
python3 .cursor/memory/memory.py rotate --keep-last 50

The rotate verb archives older entries to a sibling .archive.md file while keeping the last N live. Both archive and live pass the validator.

Local repo map (code intelligence)

Most of an agent's budget on an unfamiliar codebase is spent re-discovering it — grep, glob, Read, repeat. repomap.py builds a local, zero-dependency code map (pure Python stdlib: ast + regex + sqlite3 — no tree-sitter, no Node, no native build) so repo-scout and the orchestrator query structure instead of scanning files:

python3 .cursor/repomap/repomap.py build               # index symbols + import graph
python3 .cursor/repomap/repomap.py explore "<question / symbol names>"  # relevant symbols, grouped by file
python3 .cursor/repomap/repomap.py search <SymbolName>  # exact location + signature
python3 .cursor/repomap/repomap.py dependents <file>    # upstream — who imports this
python3 .cursor/repomap/repomap.py impact   <files...>  # transitive blast radius of a change
python3 .cursor/repomap/repomap.py affected <files...>  # which test files a change can break
python3 .cursor/repomap/repomap.py refresh              # incremental (only changed files)

Python files are parsed precisely via the standard ast; other languages use lightweight name-based extraction. The index lives at .cursor/repomap/ (built during integration, gitignored, refreshed incrementally by file hash).

Where it pays off:

• Cheaper scouting. repo-scout answers bounded_context, integration_points, and key_tests from the map in a couple of calls instead of a grep/Read discovery loop.
• Impact-aware enforcement. The stop hook can require that the tests a change actually affects were run — set require_affected_tests: true in .cursor/hooks/config.json. bg-regression-runner uses the same affected query to run only the relevant tests, and sessionStart warns when the map is stale.

This is Harmonist's own clean-room take on the "query a code graph, don't grep" idea — built to its zero-dependency, drop-in-a-box constraints, and wired into the enforcement gate rather than bolted on as a separate runtime.

Supply-chain integrity

All runtime-shipped content has a sha256 entry in MANIFEST.sha256: agents/, hooks/, memory/, playbooks/, and the root docs. CI configs (.github/, .gitlab-ci.yml) and repo metadata are pack-repo-only and deliberately excluded — they never get installed into a host project. This buys:

• Pack health at preflight. check_pack_health.py runs 19 checks including build_manifest.py --verify — any modified / missing / untracked file is flagged.
• Upgrade refusal. upgrade.py --apply sha-verifies every pack source BEFORE copying into a project. A tampered security-reviewer.md is REFUSED and never enters .cursor/:
  copy

  ! REFUSED  agents/review/security-reviewer.md: manifest expected
             5d731c6b..., actual 4b5c2283... -- possible supply-chain tampering
  

• Install-extras verification. install_extras.py — the on-demand specialist installer — inherits the same supply-chain guard.
• Post-install anchor. .cursor/pack-manifest.json records sha256 of every installed pack-owned file so verify_integration.py can detect someone editing gate-stop.sh or qa-verifier.md locally to weaken enforcement.
• Snapshot + rollback. upgrade.py --apply takes a tarball snapshot to .cursor/.integration-snapshots/ before touching anything; upgrade.py --rollback restores from the latest.

Prompt-injection scanner

Agents are copy-pasted into .cursor/agents/ and become part of the orchestrator's prompt context. A hostile body can silently subvert every session. scan_agent_safety.py runs a heuristic regex pass over every agent markdown for four classes of hostile content:

Runs on the pack catalogue in CI and on installed .cursor/agents/ after integration. Exit 1 on any error-severity hit. False-positive guards built in for legitimate MITRE ATT&CK threat documentation.

Supported IDE integrations

Harmonist ships converters for 11 AI coding assistants. Run ./agents/scripts/convert.sh --tool <name> to regenerate the target-specific artifacts, then ./agents/scripts/install.sh to place them in the right spots. On native Windows, call the cross-platform Python entry points directly: py -3 agents\scripts\convert.py --tool <name> then py -3 agents\scripts\install.py. (The .sh scripts are thin POSIX wrappers around the same convert.py / install.py.)

Add --thin to install the essentials-only variant of each persona agent (~38% fewer body lines across the pool, which matters in context-constrained sessions). See agents/SCHEMA.md for the ## Deep Reference convention that makes thin mode possible.

Key scripts

Full script index: agents/scripts/.

Documentation

Testing

The enforcement layer, memory CLI, and every script ship with exhaustive test coverage. 550+ test assertions across hooks, memory, and shell-based integration suites — all green in CI on every push.

Run the full regression locally:

python3 agents/scripts/check_pack_health.py       # 19 preflight checks
bash hooks/tests/run-hook-tests.sh                # 54 scenarios
bash memory/tests/run-memory-tests.sh             # 33 scenarios
for t in agents/scripts/test_*.sh; do bash "$t"; done  # all script suites

FAQ

Is this another LangChain / AutoGen / CrewAI alternative?

No. Those are frameworks you build an agentic application on top of — they provide abstractions for chaining LLM calls, tool use, and orchestration logic.

Harmonist is a pack you drop into an existing project to make your AI assistant follow a protocol. It doesn't replace your app's runtime; it installs next to your code and intercepts how the coding assistant (Cursor, Claude Code, Copilot, etc.) interacts with your project.

The two can coexist. Harmonist governs the coding workflow; a LangChain / AutoGen / CrewAI app is something the workflow might produce.

Why mechanical enforcement instead of prompt guidance?

Because prompt guidance is advisory and AI models treat it that way. "Always run QA before marking done" in a prompt is aspirational. A stop hook that refuses to let the turn finish until QA ran is a contract. We chose contracts.

Does it work without Cursor?

Yes. Cursor is the primary integration because of its subagent and hooks support, but the pack ships adapters for 10 other tools (see Supported IDE integrations). The enforcement layer is strongest with Cursor; in other tools it falls back to convention-plus-validation.

Can I customize the protocol?

Yes, and you should. The project-level AGENTS.md is the canonical source for your domain's invariants, stack, modules, and resilience policies. The orchestrator gives it precedence over any persona agent body. Persona agents adapt to your rules; your rules don't adapt to personas.

Pack-owned sections of AGENTS.md are delimited by <!-- pack-owned --> markers and upgrade-replaced by upgrade.py. Everything outside those markers is yours — untouched by upgrades.

Is telemetry enabled by default? What does it collect?

Local telemetry is enabled by default. It records per-agent invocation counts, session counts, and gate-allow / PROTOCOL-SKIP counters to .cursor/telemetry/agent-usage.json. Nothing is uploaded anywhere — it's a local file, gitignored, and readable in plain JSON.

Disable completely by setting telemetry_enabled: false in .cursor/hooks/config.json.

Why 193 agents? Isn't that too many?

Most projects activate 10–20 specialists for their actual working roles. The other ~170 are available but invisible — filtered out by the domains × roles × tags intersection during routing. A TON blockchain project never sees WeChat or Xiaohongshu marketing agents. A Web SaaS never sees Solidity or ZK specialists.

The size of the catalogue is an asset, not a cost — it means when your project grows into a new role (adds marketing, adds support, pivots to a new platform), the specialists are already curated and vetted. Install them on demand with:

python3 agents/scripts/install_extras.py --role marketing

How do I add my own agent?

See agents/STYLE.md for the canonical persona template and agents/SCHEMA.md for the frontmatter contract. Create the file under the right category directory, run python3 agents/scripts/lint_agents.py to validate, regenerate the index (build_index.py) and manifest (build_manifest.py), and commit.

What's the license and who owns the code?

MIT — see LICENSE. Copyright © 2026 GammaLab. Free to use, modify, fork, and ship commercial products built on top of.

I found a security issue. Where do I report it?

Open a private security advisory via the repository's Security tab — see SECURITY.md. Do not open a public issue for security-sensitive reports.

Contributing

Harmonist welcomes contributions that raise the bar:

• New agents for domains not yet covered.
• Tighter enforcement in the hooks.
• New integrations for AI assistants we don't support yet.
• Documentation that helps someone go from "I just heard of this" to "I integrated it into a real project" faster.

Before opening a PR, read CONTRIBUTING.md. For non-trivial work, open an issue first to align on approach. Drive- by reformatting will be closed; content-driven PRs will be reviewed quickly.

Security

• Private vulnerability reports: see SECURITY.md.
• Supply-chain audit: run python3 agents/scripts/check_pack_health.py after every git pull.
• Community standards: CODE_OF_CONDUCT.md.

License

Harmonist is released under the MIT License — Copyright © 2026 GammaLab. Free for commercial use, modification, and distribution.

About GammaLab

GammaLab is a technology company working on robotics, artificial intelligence, and machine cognition. Harmonist is our first open-source release — a tool we built to enforce engineering discipline in AI-assisted development, and one we use daily across our own internal projects.

If you ship production code with AI assistance and you care about making that code safe, auditable, and aligned with your project's actual rules — Harmonist is for you.

• Website: gammalab.ae
• GitHub: @GammaLabTechnologies
• Contact: Open an issue for public discussion; use the repository's Security tab for private reports.