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.

Table of contents

• Why Harmonist exists
• What makes it different
• Requirements
• Quick start
• Architecture
• The 193-agent catalogue
• Mechanical enforcement
• Structured validated memory
• Supply-chain integrity
• Supported IDE integrations
• Key scripts
• Documentation
• Testing
• FAQ
• Contributing
• Security
• License
• About GammaLab

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