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 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.

Category	Count	Protocol	Focus
orchestration	2	strict	Scout before implementation, route to right agent
review	6	strict	Readonly reviewers — security, quality, QA, SRE, regression, a11y
engineering	46	persona	Backend, frontend, DevOps, data, AI, embedded, Solidity, LLM eval
design	8	persona	UI/UX, brand, accessibility, visual storytelling
testing	8	persona	QA, performance, API testing, evidence collection
product	5	persona	Product management, sprints, feedback, trends
project-management	7	persona	Planning, studio production, coordination
marketing	30	persona	Growth, SEO, content, social, Douyin/WeChat/Xiaohongshu
paid-media	7	persona	PPC, tracking, campaign audits
sales	8	persona	Outbound, deals, discovery, proposals
finance	6	persona	FPA, bookkeeping, tax, investments
support	5	persona	Customer support, compliance, analytics
academic	5	persona	Research, psychology, history, anthropology
game-development	20	persona	Unity, Unreal, Godot, Roblox, Blender
spatial-computing	6	persona	visionOS, WebXR, Metal, XR interaction
specialized	24	persona	Blockchain audit, MCP builder, Salesforce, ZK, authorized security testing, privacy engineering, niche

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

Phase	What happens
sessionStart	Bootstrap correlation_id, inject last 3 state / decision memory entries, warn about prior incidents
afterFileEdit	Record every write to session state for the stop gate
subagentStart	Parse AGENT: <slug> marker, credit the reviewer, enforce readonly capability scoping, and cap concurrent subagents
subagentStop	Record verdict, update telemetry
beforeShellExecution	HITL gate. Match the command against the dangerous-command patterns; ask for human confirmation (or deny) before a destructive command runs
stop	The gate. Verify reviewers ran, memory updated, protocol satisfied. Return followup_message if not.

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:

File	kind	Purpose
session-handoff.md	state	Project state snapshot. Latest = authoritative.
decisions.md	decision	Append-only architectural decisions.
patterns.md	pattern	Lessons learned — what worked, what didn't.

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/:

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

• Install-extras verification. `install_e