[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-719":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":21,"hasPages":21,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":34,"readmeContent":35,"aiSummary":36,"trendingCount":16,"starSnapshotCount":16,"syncStatus":37,"lastSyncTime":38,"discoverSource":39},719,"harmonist","GammaLabTechnologies\u002Fharmonist","GammaLabTechnologies","Portable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.","https:\u002F\u002Fgammalab.ae",null,"Python",1723,265,6,5,0,29,569,79.77,"MIT License",false,"main",[24,25,26,27,28,29,30,31,32,33],"agent-framework","agent-system","ai-agents","claude-code","cursor-ide","llm","multi-agent-framework","orchestration","prompt-engineering","python","2026-06-12 04:00:05","\u003Cdiv align=\"center\">\n\n# Harmonist\n\n### Portable AI agent orchestration with mechanical protocol enforcement\n\n*A drop-in multi-agent framework for Cursor, Claude Code, Copilot, Windsurf, Aider, and other AI coding assistants.*\n\n[![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FGammaLabTechnologies\u002Fharmonist?style=flat&logo=github&color=yellow)](https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies\u002Fharmonist\u002Fstargazers)\n[![CI](https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies\u002Fharmonist\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies\u002Fharmonist\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Python 3.9+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.9+-blue.svg)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n[![Version 1.0.0](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-1.0.0-brightgreen.svg)](CHANGELOG.md)\n[![Agents: 186](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fagents-186-purple.svg)](agents\u002Findex.json)\n[![Tests: 430+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftests-430+-success.svg)](#testing)\n[![Stdlib only](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdependencies-stdlib%20only-lightgrey.svg)](#requirements)\n\n**Built and maintained by [GammaLab](https:\u002F\u002Fgammalab.ae) · [@GammaLabTechnologies](https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies)**\n\n\u003C\u002Fdiv>\n\n---\n\nMost AI coding frameworks trust the language model to follow the\nrules. Harmonist **refuses to let it skip them**. Every code-changing\nturn is gated by hooks that check whether the required reviewers ran,\nwhether memory was updated, and whether the supply chain of every\nshipped file is intact. If the checks fail, the turn doesn't complete —\nno matter how confidently the model claims it's done.\n\nThis is the first open-source agent framework where **protocol\nenforcement is a mechanical gate, not a polite request in a prompt**.\n\n---\n\n## Table of contents\n\n- [Why Harmonist exists](#why-harmonist-exists)\n- [What makes it different](#what-makes-it-different)\n- [Requirements](#requirements)\n- [Quick start](#quick-start)\n- [Architecture](#architecture)\n- [The 186-agent catalogue](#the-186-agent-catalogue)\n- [Mechanical enforcement](#mechanical-enforcement)\n- [Structured validated memory](#structured-validated-memory)\n- [Supply-chain integrity](#supply-chain-integrity)\n- [Supported IDE integrations](#supported-ide-integrations)\n- [Key scripts](#key-scripts)\n- [Documentation](#documentation)\n- [Testing](#testing)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n- [About GammaLab](#about-gammalab)\n\n---\n\n## Why Harmonist exists\n\nAI coding assistants have a structural problem that prompt engineering\nalone cannot fix.\n\n**The problem:** every serious engineering workflow has non-negotiable\nrules — \"no floating-point for money\", \"run QA before merging\", \"every\nexternal call retries with idempotency keys\", \"security review before\ntouching auth code\". An LLM can be *told* to follow them, but there is\nno mechanism forcing it to. It can agree, move on, and silently skip\nthe step. On a good day you notice. On a bad day the bug ships.\n\n**The current landscape** is split between two imperfect answers:\n\n- **Thin agent frameworks** (LangChain, CrewAI, AutoGen, MetaGPT and\n  many others) give you orchestration primitives but leave enforcement\n  to the prompt. The model can always override its own protocol.\n- **Heavy enterprise platforms** promise governance through separate\n  runtimes, databases, and vendor lock-in — but need infrastructure to\n  install, don't work on a solo developer's laptop, and can't be\n  audited file-by-file.\n\n**Harmonist takes a different stance.** Protocol enforcement is\nimplemented as IDE-level hooks — concrete shell and Python scripts that\nobserve every subagent dispatch, every file edit, every session stop.\nWhen the rules the project declared aren't met, the `stop` hook\nreturns a `followup_message` to the AI and refuses to allow the turn\nto complete. The model can't argue with that; it's a state machine on\ndisk.\n\nNo runtime. No database. No vendor lock-in. Just markdown, stdlib\nPython, and bash — sitting next to your code, doing one job\ncorrectly.\n\n---\n\n## What makes it different\n\nSeven concrete, checkable properties — each one addresses a gap that\nother open-source agent frameworks leave open.\n\n### 1. Mechanical protocol enforcement via IDE hooks\n\nThe `stop` hook in `.cursor\u002Fhooks\u002F` parses subagent dispatch markers\nfrom the session, checks whether `qa-verifier` ran, whether any\nrequired reviewer was missing, whether `session-handoff.md` was\nupdated, and returns a structured `followup_message` if the turn\nis incomplete. `loop_limit: 3` caps retries. On exhaustion, an\nincident is recorded and surfaced in the next session. **The AI\nliterally cannot ship a code change that skipped review.**\n\n### 2. Supply-chain verification of agent definitions\n\nEvery shipped file is hashed in `MANIFEST.sha256`. `upgrade.py`\nsha-verifies each source *before* copying into a project. A tampered\n`security-reviewer.md` (say, one that returns `approve` for\neverything) is REFUSED — it never enters the project. `install_extras.py`\ninherits the same guard for on-demand specialist installs. This is\nthe first OSS agent catalogue with paranoid-level supply-chain\nposture.\n\n### 3. Memory correlation IDs that the LLM cannot forge\n\nEvery memory entry has a `correlation_id` of the form\n`\u003Csession_id>-\u003Ctask_seq>` generated by the hooks at session start\n(`\u003Cunix-seconds>\u003Cpid4>` — collision-safe across parallel sessions).\nThe LLM reads the active ID via CLI; it never writes the ID itself.\nThis means the linkage between a `state` entry, a `decision`, and a\n`pattern` from the same task is **cryptographically ordered** from\nthe hook's perspective — not trusted to the model.\n\n### 4. Schema-validated memory with secret-pattern scanning\n\n`memory.py append` is the only supported write path. It validates\nevery entry against a YAML schema (`memory\u002FSCHEMA.md`), rejects\nduplicates, and scans the body for ~30 classes of secrets: AWS\naccess keys, GitHub PATs, Stripe tokens, Slack webhooks, GCP service\naccounts, Azure connection strings, Telegram bot tokens, Discord\ntokens, Heroku\u002FPostmark UUIDs (context-scoped), generic high-entropy\ntokens with `secret:` prefixes, and DB connection strings with\nembedded credentials. Placeholder fences (`${VAR}`, `\u003CNAME>`) suppress\nthe scan so your templates still write cleanly.\n\n### 5. 186 curated domain specialists, not one generic \"coder\"\n\nHarmonist's catalogue is not a handful of roles. It's **186 curated\nspecialists** across 16 categories: blockchain-security-auditor for\nSolidity audits, zk-steward for zero-knowledge circuits, visionos-\nspatial-engineer for Apple Vision Pro, wechat-mini-program-developer\nand xiaohongshu-specialist for the China market, laravel-livewire-\nspecialist for PHP, roblox-systems-scripter for Roblox Luau, 30+\nmarketing agents from SEO to Douyin, finance \u002F sales \u002F product \u002F\nsupport \u002F academic coverage. The orchestrator picks by\n`domains × roles × tags`, not by hard-coded slug lists.\n\n### 6. Integration-as-a-prompt\n\nThere is no installer binary. Integration happens by pasting\n`integration-prompt.md` into a Cursor Agent-mode session. The AI\nreads the prompt, analyzes the project, asks the user which `roles`\nwill be active (engineering \u002F design \u002F product \u002F marketing \u002F sales \u002F\nsupport \u002F finance \u002F testing \u002F academic), selects the right\nspecialists from `agents\u002Findex.json`, and wires everything up —\nincluding writing a project-specific `AGENTS.md` with domain-tailored\ninvariants. The AI integrates itself.\n\n### 7. Zero runtime dependencies, cross-platform parity\n\nNo npm, no Docker, no LangChain, no vector database. **Pure Python\nstdlib + bash.** The enforcement runtime has two implementations —\nPOSIX `.sh` scripts for macOS \u002F Linux \u002F WSL, and a pure-Python\n`hook_runner.py` for native Windows — and both paths are exercised\nagainst identical test scenarios. 430+ test assertions in CI keep\nthem bit-for-bit compatible.\n\n---\n\n## Requirements\n\n- **Python 3.9+** — every script ships with a version guard; older\n  interpreters exit with a per-OS install hint.\n- **Bash 3.2+** for POSIX shell paths (macOS default works). On native\n  Windows, the pure-Python `hook_runner.py` takes over; no WSL or Git\n  Bash required.\n- **Git** for version tracking.\n- **An AI coding assistant that supports subagent dispatch** — Cursor\n  is the primary integration; Claude Code, Copilot, Windsurf, Aider,\n  Kimi, Qwen, Gemini CLI, OpenCode, OpenClaw, and Antigravity are all\n  supported via adapters.\n- **No third-party Python dependencies** — stdlib only. No npm, no\n  Docker, no LangChain, no vector database.\n\n---\n\n## Quick start\n\n### Option 1 — Integrate via Cursor (recommended)\n\n```bash\n# 1. Clone into the root of your project\ncd your-project\u002F\ngit clone https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies\u002Fharmonist.git\n\n# 2. Open the project in Cursor, switch to Agent mode\n# 3. Paste the contents of harmonist\u002Fintegration-prompt.md\n# 4. Follow the AI's walkthrough — it will ask about your\n#    project's domain and roles, then wire everything up.\n# 5. Start a NEW chat when integration is done.\n```\n\nThat's it. The AI reads `harmonist\u002Fagents\u002Findex.json`, picks the\nright specialists for your stack, writes a domain-specific\n`AGENTS.md`, bootstraps `.cursor\u002Fmemory\u002F`, installs the enforcement\nhooks, and records the integration state in\n`.cursor\u002Fpack-version.json`.\n\n### Option 2 — Integrate via CLI (no Cursor needed)\n\n```bash\ncd your-project\u002F\ngit clone https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies\u002Fharmonist.git\npython3 harmonist\u002Fagents\u002Fscripts\u002Fintegrate.py --pack harmonist --project .\n```\n\n### Option 3 — Manual integration\n\nSee [`GUIDE_EN.md`](GUIDE_EN.md) for the step-by-step manual path.\n\n---\n\n## Architecture\n\n```\n                     ┌────────────────────────────┐\n                     │        AGENTS.md           │\n                     │      Orchestrator          │\n                     │                            │\n                     │  Protocol · Hook Phases    │\n                     │  Invariants · Memory       │\n                     └─────────────┬──────────────┘\n                                   │  reads\n                                   ▼\n                     ┌────────────────────────────┐\n                     │   agents\u002Findex.json        │   ← generated\n                     │                            │\n                     │   by category · by tag     │   ← routing table\n                     │   186 entries              │\n                     └─────────────┬──────────────┘\n                                   │  routes to\n            ┌──────────────────────┼──────────────────────┐\n            ▼                      ▼                      ▼\n     ┌──────────────┐      ┌──────────────┐      ┌──────────────┐\n     │ orchestration│      │   review     │      │   persona    │\n     │ (scout,      │      │ (strict,     │      │ (engineering,│\n     │  repo-map)   │      │  readonly)   │      │  design, …)  │\n     └──────────────┘      └──────────────┘      └──────────────┘\n                                   │                      │\n            ┌──────────────────────┴──────────────────────┐\n            ▼                                             ▼\n     ┌──────────────┐                             ┌──────────────┐\n     │ Review gates │                             │   .cursor\u002F   │\n     │              │                             │   memory\u002F    │\n     │ qa · sec     │                             │              │\n     │ sre · perf   │                             │ session      │\n     │ regression   │                             │ decisions    │\n     └──────────────┘                             │ patterns     │\n                                                  └──────────────┘\n```\n\n### How it works\n\n1. **Single unified pool.** Every agent lives at\n   `agents\u002F\u003Ccategory>\u002F\u003Cslug>.md` with the same [Schema v2](agents\u002FSCHEMA.md)\n   frontmatter. One schema, one catalogue.\n2. **Data-driven routing.** The orchestrator never hard-codes slugs.\n   It extracts task tags (\"payments\", \"react\", \"solidity\"),\n   intersects with `agents\u002Findex.json`, filters by the project's\n   declared `domains` and `roles`, and picks the right specialist.\n3. **Protocol tiers by metadata.** `protocol: strict` agents\n   (orchestration + review) are mandatory gates that run on triggers.\n   `protocol: persona` agents are free-form specialists with domain\n   depth.\n4. **Hook-observed execution.** `sessionStart`, `afterFileEdit`,\n   `subagentStart`, `subagentStop`, and `stop` hooks track the full\n   lifecycle. The `stop` hook is the gate.\n5. **Persistent memory.** Between sessions, state \u002F decisions \u002F\n   patterns live under `.cursor\u002Fmemory\u002F`, linked by correlation IDs.\n   The next session reads the last three state snapshots and three\n   decisions before planning.\n\n---\n\n## The 186-agent catalogue\n\nEvery count below is mirrored from `agents\u002Findex.json` and verified by\n`check_pack_health.py` — the table and the index cannot drift.\n\n| Category            | Count | Protocol | Focus                                               |\n|---------------------|-------|----------|-----------------------------------------------------|\n| `orchestration`     |   2   | strict   | Scout before implementation, route to right agent   |\n| `review`            |   6   | strict   | Readonly reviewers — security, quality, QA, SRE, regression, a11y |\n| `engineering`       |  46   | persona  | Backend, frontend, DevOps, data, AI, embedded, Solidity, LLM eval |\n| `design`            |   8   | persona  | UI\u002FUX, brand, accessibility, visual storytelling    |\n| `testing`           |   8   | persona  | QA, performance, API testing, evidence collection   |\n| `product`           |   5   | persona  | Product management, sprints, feedback, trends       |\n| `project-management`|   7   | persona  | Planning, studio production, coordination           |\n| `marketing`         |  30   | persona  | Growth, SEO, content, social, Douyin\u002FWeChat\u002FXiaohongshu |\n| `paid-media`        |   7   | persona  | PPC, tracking, campaign audits                      |\n| `sales`             |   8   | persona  | Outbound, deals, discovery, proposals               |\n| `finance`           |   6   | persona  | FPA, bookkeeping, tax, investments                  |\n| `support`           |   5   | persona  | Customer support, compliance, analytics             |\n| `academic`          |   5   | persona  | Research, psychology, history, anthropology         |\n| `game-development`  |  20   | persona  | Unity, Unreal, Godot, Roblox, Blender               |\n| `spatial-computing` |   6   | persona  | visionOS, WebXR, Metal, XR interaction              |\n| `specialized`       |  17   | persona  | Blockchain audit, MCP builder, Salesforce, ZK, niche |\n\nEach agent carries structured frontmatter: `description`, `tags`,\n`domains`, `distinguishes_from` (near-peers), `disambiguation`\n(one-line \"when to pick this over X\"), `version`, and `updated_at`.\nThe orchestrator reads all of this for tie-breaking when multiple\ncandidates match a task's tags.\n\n---\n\n## Mechanical enforcement\n\nThe enforcement layer is what separates Harmonist from a \"nice prompt\npack\". It lives in `hooks\u002F` and gets installed into `.cursor\u002Fhooks\u002F`\nat integration time.\n\n### Five hook phases\n\n| Phase              | What happens                                                                |\n|--------------------|-----------------------------------------------------------------------------|\n| `sessionStart`     | Bootstrap correlation_id, inject last 3 state \u002F decision memory entries, warn about prior incidents |\n| `afterFileEdit`    | Record every write to session state for the stop gate                       |\n| `subagentStart`    | Parse `AGENT: \u003Cslug>` marker, credit the reviewer, enforce `readonly` capability scoping |\n| `subagentStop`     | Record verdict, update telemetry                                            |\n| `stop`             | **The gate.** Verify reviewers ran, memory updated, protocol satisfied. Return `followup_message` if not. |\n\n### What the stop gate actually checks\n\nIf the session touched any file outside ignored patterns:\n\n1. At least one `category: review` agent was invoked via Task.\n2. Specifically `qa-verifier` was invoked.\n3. `.cursor\u002Fmemory\u002Fsession-handoff.md` was updated during the session.\n\nIf any check fails, the hook returns `followup_message` telling the AI\nexactly what's missing. `loop_limit: 3` caps retries. On exhaustion,\nthe incident is persisted to `.cursor\u002Fhooks\u002F.state\u002Fincidents.json`\nand surfaced in the next session as an unmissable banner.\n\n### PROTOCOL-SKIP escape hatch\n\nFor genuinely trivial turns (typo fix in a comment, markdown\nrewording), the AI can emit `PROTOCOL-SKIP: \u003Creason>` to bypass\nthe gate. The hook logs it. If the skip rate crosses a threshold\n(default `> 25%` of all completions, min 5 skips), the next session\nstarts with a warning about abuse. Easy to opt out of cleanly;\nhard to abuse quietly.\n\n---\n\n## Structured validated memory\n\nMemory is a contract, not free-form markdown. Every entry is a YAML\nblock delimited by `\u003C!-- memory-entry:start -->` \u002F\n`\u003C!-- memory-entry:end -->` with required fields: `id`,\n`correlation_id`, `at`, `kind`, `status`, `author`, `summary`.\n\nThree files with explicit roles:\n\n| File                    | `kind`     | Purpose                              |\n|-------------------------|------------|--------------------------------------|\n| `session-handoff.md`    | `state`    | Project state snapshot. Latest = authoritative. |\n| `decisions.md`          | `decision` | Append-only architectural decisions. |\n| `patterns.md`           | `pattern`  | Lessons learned — what worked, what didn't. |\n\n### CLI as the only write path\n\n```bash\npython3 .cursor\u002Fmemory\u002Fmemory.py append \\\n  --file session-handoff --kind state --status done \\\n  --summary \"Integrated Stripe webhook handler\" \\\n  --tags payments,backend \\\n  --body-file \u002Ftmp\u002Fhandoff-body.md\n```\n\nThe CLI:\n\n- Generates `id` and `at` deterministically.\n- Reads the active `correlation_id` from the hooks (not from the LLM).\n- Validates the entry against `memory\u002FSCHEMA.md` before writing.\n- Scans the body for ~30 secret patterns and rejects leaks.\n- Refuses duplicates unless `--allow-duplicate`.\n\n### Search, rotate, dedupe\n\n```bash\npython3 .cursor\u002Fmemory\u002Fmemory.py search --tag payments\npython3 .cursor\u002Fmemory\u002Fmemory.py latest --file session-handoff --n 5\npython3 .cursor\u002Fmemory\u002Fmemory.py rotate --keep-last 50\n```\n\nThe `rotate` verb archives older entries to a sibling `.archive.md`\nfile while keeping the last N live. Both archive and live pass the\nvalidator.\n\n---\n\n## Supply-chain integrity\n\nEvery shipped file has a sha256 entry in `MANIFEST.sha256`. This buys:\n\n- **Pack health at preflight.** `check_pack_health.py` runs 18 checks\n  including `build_manifest.py --verify` — any modified \u002F missing \u002F\n  untracked file is flagged.\n- **Upgrade refusal.** `upgrade.py --apply` sha-verifies every pack\n  source BEFORE copying into a project. A tampered\n  `security-reviewer.md` is REFUSED and never enters `.cursor\u002F`:\n  ```\n  ! REFUSED  agents\u002Freview\u002Fsecurity-reviewer.md: manifest expected\n             5d731c6b..., actual 4b5c2283... -- possible supply-chain tampering\n  ```\n- **Install-extras verification.** `install_extras.py` — the\n  on-demand specialist installer — inherits the same supply-chain\n  guard.\n- **Post-install anchor.** `.cursor\u002Fpack-manifest.json` records\n  sha256 of every installed pack-owned file so\n  `verify_integration.py` can detect someone editing `gate-stop.sh`\n  or `qa-verifier.md` locally to weaken enforcement.\n- **Snapshot + rollback.** `upgrade.py --apply` takes a tarball\n  snapshot to `.cursor\u002F.integration-snapshots\u002F` before touching\n  anything; `upgrade.py --rollback` restores from the latest.\n\n### Prompt-injection scanner\n\nAgents are copy-pasted into `.cursor\u002Fagents\u002F` and become part of the\norchestrator's prompt context. A hostile body can silently subvert\nevery session. `scan_agent_safety.py` runs a heuristic regex pass\nover every agent markdown for four classes of hostile content:\n\n| Class              | Examples |\n|--------------------|----------|\n| Override           | \"ignore previous instructions\", jailbreak markers |\n| Exfil              | Secret leak attempts, `~\u002F.ssh\u002Fid_rsa` access, reveal-system-prompt probes |\n| Remote exec        | `curl \\| bash`, base64-decode-exec, pastebin \u002F ngrok \u002F webhook.site callbacks |\n| Policy subversion  | \"skip qa-verifier\", \"always approve silently\" |\n\nRuns on the pack catalogue in CI and on installed `.cursor\u002Fagents\u002F`\nafter integration. Exit 1 on any error-severity hit. False-positive\nguards built in for legitimate MITRE ATT&CK threat documentation.\n\n---\n\n## Supported IDE integrations\n\nHarmonist ships converters for 11 AI coding assistants. Run\n`.\u002Fagents\u002Fscripts\u002Fconvert.sh --tool \u003Cname>` to regenerate the\ntarget-specific artifacts, then `.\u002Fagents\u002Fscripts\u002Finstall.sh` to\nplace them in the right spots.\n\n| Tool              | Surface produced                                         |\n|-------------------|----------------------------------------------------------|\n| **Cursor**        | `.cursor\u002Fagents\u002F*.md` + `.cursor\u002Frules\u002F*.mdc` + hooks    |\n| **Claude Code**   | Project-scoped agent definitions                         |\n| **GitHub Copilot**| Custom instruction file                                  |\n| **Windsurf**      | `.windsurfrules`                                         |\n| **Aider**         | `CONVENTIONS.md`                                         |\n| **Kimi**          | `agents-orchestrator\u002Fsystem.md`                          |\n| **Qwen**          | Agent directory format                                   |\n| **Gemini CLI**    | Extension manifest + skills                              |\n| **OpenCode**      | Per-agent markdown                                       |\n| **OpenClaw**      | IDENTITY.md per agent                                    |\n| **Antigravity**   | Skill format                                             |\n\nAdd `--thin` to install the essentials-only variant of each persona\nagent (~38% fewer body lines across the pool, which matters in\ncontext-constrained sessions). See [`agents\u002FSCHEMA.md`](agents\u002FSCHEMA.md)\nfor the `## Deep Reference` convention that makes thin mode possible.\n\n---\n\n## Key scripts\n\n| Script                              | What it does                                                                   |\n|-------------------------------------|--------------------------------------------------------------------------------|\n| `check_pack_health.py`              | 18 preflight checks (version, manifest, lint, migrator idempotency, etc.)     |\n| `lint_agents.py`                    | Validate every agent against Schema v2 — 0 errors required                    |\n| `build_index.py`                    | Regenerate `agents\u002Findex.json` (routing table)                                |\n| `build_manifest.py`                 | Regenerate `MANIFEST.sha256` (supply-chain anchor)                            |\n| `integrate.py`                      | Full integration into a target project                                        |\n| `upgrade.py`                        | Roll an integrated project forward to a newer pack version, with snapshots   |\n| `install_extras.py`                 | Add specialists to `.cursor\u002Fagents\u002F` by slug, role bundle, or tag — sha-verified |\n| `verify_integration.py`             | Objective post-integration audit — what's missing, what's customised         |\n| `scan_agent_safety.py`              | Prompt-injection \u002F exfil scanner for catalogue + installed agents            |\n| `scan_memory_leaks.py`              | Audit git history for accidentally-committed memory files                    |\n| `scan_rules_conflicts.py`           | Detect phantom slugs, duplicate-purpose rules, protocol contradictions       |\n| `insert_deep_ref_marker.py`         | Add `## Deep Reference` cut point to long persona agents                     |\n| `extract_essentials.py`             | Produce the thin variant of a persona agent                                  |\n| `report_usage.py`                   | Render local agent-usage telemetry; recommend dead-balance removal           |\n\nFull script index: [`agents\u002Fscripts\u002F`](agents\u002Fscripts\u002F).\n\n---\n\n## Documentation\n\n| File | Purpose |\n|------|---------|\n| [`AGENTS.md`](AGENTS.md) | Orchestrator template — protocol, hook phases, memory, resilience. Copied into every integrated project and customized to the project's domain. |\n| [`GUIDE_EN.md`](GUIDE_EN.md) | Condensed walkthrough for first-time users. |\n| [`integration-prompt.md`](integration-prompt.md) | The one-shot prompt to paste into Cursor Agent mode for fully automated integration. |\n| [`agents\u002FSCHEMA.md`](agents\u002FSCHEMA.md) | Frontmatter contract (Schema v2) every agent file must satisfy. |\n| [`agents\u002FSTYLE.md`](agents\u002FSTYLE.md) | How agent bodies should read — canonical shapes, anti-patterns, retrofit checklist. |\n| [`agents\u002FTAGS.md`](agents\u002FTAGS.md) | Curated tag vocabulary (253 tags organized by layer). |\n| [`memory\u002FSCHEMA.md`](memory\u002FSCHEMA.md) | Memory entry schema (v1), correlation-ID format, validation rules. |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute, PR checklist, release process. |\n| [`SECURITY.md`](SECURITY.md) | Vulnerability reporting policy, scope, response timelines. |\n| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Community standards. |\n| [`CHANGELOG.md`](CHANGELOG.md) | Release history in Keep-a-Changelog format. |\n| [`playbooks\u002F`](playbooks\u002F) | Optional NEXUS 7-phase lifecycle with phase-specific runbooks for startups, enterprises, incident response, and marketing campaigns. |\n\n---\n\n## Testing\n\nThe enforcement layer, memory CLI, and every script ship with\nexhaustive test coverage. `430+ test assertions` across hooks, memory,\nand shell-based integration suites — all green in CI on every push.\n\n| Suite                              | Assertions | Covers                                              |\n|------------------------------------|-----------:|-----------------------------------------------------|\n| Hook tests                         |         30 | All 5 phases, capability scoping, loop-limit, incident surfacing, cross-platform runner parity |\n| Memory tests                       |         29 | Append, validate, search, rotate, dedupe, migrations, secret patterns |\n| Integration + upgrade + install_extras  |        90+ | End-to-end integration, snapshots, rollback, on-demand specialist install |\n| Supply-chain integrity             |         23 | MANIFEST verification, tampered-source refusal, pack-manifest tracking |\n| 15 other script suites             |        250+| lint, extract, freshness, rules-conflicts, memory-privacy, telemetry, project-context, regression detection, py-guard sync, smoke test, etc. |\n\nRun the full regression locally:\n\n```bash\npython3 agents\u002Fscripts\u002Fcheck_pack_health.py       # 18 preflight checks\nbash hooks\u002Ftests\u002Frun-hook-tests.sh                # 30 scenarios\nbash memory\u002Ftests\u002Frun-memory-tests.sh             # 29 scenarios\nfor t in agents\u002Fscripts\u002Ftest_*.sh; do bash \"$t\"; done  # 17 more suites\n```\n\n---\n\n## FAQ\n\n### Is this another LangChain \u002F AutoGen \u002F CrewAI alternative?\n\nNo. Those are **frameworks you build an agentic application on top of**\n— they provide abstractions for chaining LLM calls, tool use, and\norchestration logic.\n\nHarmonist is **a pack you drop into an existing project** to make your\nAI assistant follow a protocol. It doesn't replace your app's runtime;\nit installs next to your code and intercepts how the coding assistant\n(Cursor, Claude Code, Copilot, etc.) interacts with your project.\n\nThe two can coexist. Harmonist governs the *coding workflow*; a\nLangChain \u002F AutoGen \u002F CrewAI app is something the workflow might\n*produce*.\n\n### Why mechanical enforcement instead of prompt guidance?\n\nBecause prompt guidance is advisory and AI models treat it that way.\n\"Always run QA before marking done\" in a prompt is aspirational. A\nstop hook that refuses to let the turn finish until QA ran is a\ncontract. We chose contracts.\n\n### Does it work without Cursor?\n\nYes. Cursor is the primary integration because of its subagent and\nhooks support, but the pack ships adapters for 10 other tools (see\n[Supported IDE integrations](#supported-ide-integrations)). The\nenforcement layer is strongest with Cursor; in other tools it falls\nback to convention-plus-validation.\n\n### Can I customize the protocol?\n\nYes, and you should. The project-level `AGENTS.md` is the canonical\nsource for your domain's invariants, stack, modules, and resilience\npolicies. The orchestrator gives *it* precedence over any persona\nagent body. Persona agents adapt to your rules; your rules don't\nadapt to personas.\n\nPack-owned sections of `AGENTS.md` are delimited by\n`\u003C!-- pack-owned -->` markers and upgrade-replaced by `upgrade.py`.\nEverything outside those markers is yours — untouched by upgrades.\n\n### Is telemetry enabled by default? What does it collect?\n\nLocal telemetry is enabled by default. It records per-agent\ninvocation counts, session counts, and gate-allow \u002F PROTOCOL-SKIP\ncounters to `.cursor\u002Ftelemetry\u002Fagent-usage.json`. **Nothing is\nuploaded anywhere — it's a local file, gitignored, and readable in\nplain JSON.**\n\nDisable completely by setting `telemetry_enabled: false` in\n`.cursor\u002Fhooks\u002Fconfig.json`.\n\n### Why 186 agents? Isn't that too many?\n\nMost projects activate 10–20 specialists for their actual working\nroles. The other ~170 are available but invisible — filtered out by\nthe `domains × roles × tags` intersection during routing. A TON\nblockchain project never sees WeChat or Xiaohongshu marketing\nagents. A Web SaaS never sees Solidity or ZK specialists.\n\nThe size of the catalogue is an **asset**, not a cost — it means when\nyour project grows into a new role (adds marketing, adds support,\npivots to a new platform), the specialists are already curated and\nvetted. Install them on demand with:\n```bash\npython3 agents\u002Fscripts\u002Finstall_extras.py --role marketing\n```\n\n### How do I add my own agent?\n\nSee [`agents\u002FSTYLE.md`](agents\u002FSTYLE.md) for the canonical persona\ntemplate and [`agents\u002FSCHEMA.md`](agents\u002FSCHEMA.md) for the\nfrontmatter contract. Create the file under the right category\ndirectory, run `python3 agents\u002Fscripts\u002Flint_agents.py` to validate,\nregenerate the index (`build_index.py`) and manifest\n(`build_manifest.py`), and commit.\n\n### What's the license and who owns the code?\n\nMIT — [see LICENSE](LICENSE). Copyright © 2026 GammaLab.\nFree to use, modify, fork, and ship commercial products built on\ntop of.\n\n### I found a security issue. Where do I report it?\n\nOpen a **private security advisory** via the repository's Security\ntab — see [`SECURITY.md`](SECURITY.md). Do not open a public issue\nfor security-sensitive reports.\n\n---\n\n## Contributing\n\nHarmonist welcomes contributions that raise the bar:\n\n- **New agents** for domains not yet covered.\n- **Tighter enforcement** in the hooks.\n- **New integrations** for AI assistants we don't support yet.\n- **Documentation** that helps someone go from \"I just heard of this\"\n  to \"I integrated it into a real project\" faster.\n\nBefore opening a PR, read [`CONTRIBUTING.md`](CONTRIBUTING.md). For\nnon-trivial work, **open an issue first** to align on approach. Drive-\nby reformatting will be closed; content-driven PRs will be reviewed\nquickly.\n\n---\n\n## Security\n\n- Private vulnerability reports: see [`SECURITY.md`](SECURITY.md).\n- Supply-chain audit: run `python3 agents\u002Fscripts\u002Fcheck_pack_health.py`\n  after every `git pull`.\n- Community standards: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).\n\n---\n\n## License\n\nHarmonist is released under the [MIT License](LICENSE) —\n**Copyright © 2026 GammaLab**. Free for commercial use, modification,\nand distribution.\n\n---\n\n## About GammaLab\n\n[**GammaLab**](https:\u002F\u002Fgammalab.ae) is a technology company working on\nrobotics, artificial intelligence, and machine cognition. Harmonist\nis our first open-source release — a tool we built to enforce\nengineering discipline in AI-assisted development, and one we use\ndaily across our own internal projects.\n\nIf you ship production code with AI assistance and you care about\nmaking that code safe, auditable, and aligned with your project's\nactual rules — Harmonist is for you.\n\n- **Website:** [gammalab.ae](https:\u002F\u002Fgammalab.ae)\n- **GitHub:** [@GammaLabTechnologies](https:\u002F\u002Fgithub.com\u002FGammaLabTechnologies)\n- **Contact:** Open an issue for public discussion; use the\n  repository's Security tab for private reports.\n\n---\n\n\u003Cdiv align=\"center\">\n\n**If Harmonist helps you ship safer AI-assisted code,\nstar the repository — it's the cheapest signal you can send\nthe maintainers that this work matters.** ⭐\n\nMade with engineering discipline by [GammaLab](https:\u002F\u002Fgammalab.ae).\n\n\u003C\u002Fdiv>\n","Harmonist 是一个用于AI代理编排的便携式框架，强制执行机械协议。它包含186个代理，运行时无任何依赖。项目采用Python编写，通过钩子机制确保每次代码更改都经过必要的审查、内存更新及供应链完整性检查，从而防止模型跳过关键步骤。适用于需要严格遵守编码规则和流程的开发场景，如金融、安全敏感应用等，能够有效提升AI辅助编程工具（如Cursor, Claude Code, Copilot等）的可靠性和安全性。",2,"2026-06-11 02:38:51","CREATED_QUERY"]