Harmonist Agent Orchestration

---
name: harmonist-agent-orchestration
description: Skill for using Harmonist — portable AI agent orchestration with mechanical protocol enforcement, 186 curated specialists, and zero runtime dependencies.
triggers:
  - set up harmonist in my project
  - add multi-agent orchestration with harmonist
  - how do I use harmonist agents
  - configure harmonist for my codebase
  - install harmonist agent framework
  - harmonist protocol enforcement setup
  - add AI agent specialists to my project
  - orchestrate agents with harmonist
---

# Harmonist Agent Orchestration

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Harmonist is a portable multi-agent orchestration framework for AI coding assistants (Cursor, Claude Code, Copilot, Windsurf, Aider, and others). Its defining property: **protocol enforcement is a mechanical gate**, not a prompt suggestion. IDE-level hooks block a turn from completing if required reviewers didn't run, memory wasn't updated, or supply-chain checks failed. It ships 186 curated domain-specialist agents across 16 categories, uses pure Python stdlib with zero third-party dependencies, and runs on macOS, Linux, WSL, and native Windows.

---

## Installation

### Option 1 — Cursor Agent Mode (recommended)

```bash
cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.git

# Open project in Cursor → Agent mode
# Paste contents of harmonist/integration-prompt.md
# Follow the AI walkthrough; start a NEW chat when done.

Option 2 — CLI Integration

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

Option 3 — Manual

Follow harmonist/GUIDE_EN.md step by step.

Requirements:

• Python 3.9+ (no third-party packages)
• Bash 3.2+ (macOS/Linux/WSL) or pure-Python hook_runner.py (native Windows)
• Git
• An AI coding assistant that supports subagent dispatch

---

What Happens During Integration

The AI assistant:

1. Reads harmonist/agents/index.json (186 agents, routing table).
2. Asks which roles are active: engineering / design / product / marketing / sales / support / finance / testing / academic.
3. Selects matching specialists and writes a project-specific AGENTS.md.
4. Bootstraps .cursor/memory/ with session tracking scaffolding.
5. Installs enforcement hooks in .cursor/hooks/.
6. Records state in .cursor/pack-version.json.

---

Project Structure

harmonist/
├── agents/
│   ├── index.json              # 186-agent routing table (category × role × tags)
│   ├── scripts/
│   │   ├── integrate.py        # CLI integration entry point
│   │   ├── upgrade.py          # SHA-verified upgrade with supply-chain guard
│   │   ├── install_extras.py   # On-demand specialist install (also SHA-verified)
│   │   └── memory.py           # Schema-validated memory write path
│   └── <category>/
│       └── <agent-slug>.md     # Individual agent definition files
├── .cursor/
│   ├── hooks/                  # Mechanical enforcement hooks
│   │   ├── stop                # Gate: checks reviewers, memory, supply chain
│   │   └── hook_runner.py      # Pure-Python Windows fallback
│   └── memory/                 # Structured session memory store
├── MANIFEST.sha256             # Supply-chain hashes for every shipped file
├── AGENTS.md                   # Orchestrator: protocol, invariants, routing
├── integration-prompt.md       # Paste-to-integrate prompt for AI assistants
└── GUIDE_EN.md                 # Manual integration guide

---

Key Scripts & CLI Commands

memory.py — Schema-Validated Memory

The only supported write path for agent memory. Validates against memory/SCHEMA.md, rejects duplicates, scans for ~30 secret patterns.

# Append a memory entry (from inside a hook or agent script)
python3 harmonist/agents/scripts/memory.py append \
  --type decision \
  --session-id "$SESSION_ID" \
  --task-seq 3 \
  --body "Chose postgres over sqlite for concurrent write safety."

# Read the active correlation ID (LLM reads this; never writes it)
python3 harmonist/agents/scripts/memory.py get-correlation-id

# List recent entries
python3 harmonist/agents/scripts/memory.py list --last 10

Memory entry types: state, decision, pattern, incident.

Correlation IDs are generated by hooks as <session_id>-<task_seq> where session_id = <unix-seconds><pid4>. The LLM reads but never writes the ID.

upgrade.py — Supply-Chain-Safe Upgrade

# Upgrade Harmonist files with SHA verification before any copy
python3 harmonist/agents/scripts/upgrade.py \
  --pack harmonist \
  --project .

# A tampered agent file (hash mismatch vs MANIFEST.sha256) is REFUSED
# and never written into the project.

install_extras.py — On-Demand Specialist Install

# Install an additional specialist agent (SHA-verified)
python3 harmonist/agents/scripts/install_extras.py \
  --agent blockchain-security-auditor \
  --project .

integrate.py — CLI Integration

python3 harmonist/agents/scripts/integrate.py \
  --pack harmonist \
  --project /path/to/your-project \
  --roles engineering,testing,security

---

Agent Catalogue — 186 Specialists

Agents are selected by domains × roles × tags from agents/index.json.

Categories

Category	Example Agents
Orchestration	scout, repo-map
Review	qa-verifier, security-reviewer, strict-reviewer
Engineering	backend-engineer, frontend-engineer, devops-engineer
Blockchain	blockchain-security-auditor, zk-steward
Mobile/XR	visionos-spatial-engineer, ios-engineer, android-engineer
China Market	wechat-mini-program-developer, xiaohongshu-specialist
PHP/Web	laravel-livewire-specialist
Game	roblox-systems-scripter
Marketing (30+)	seo-specialist, douyin-specialist, content-strategist
Finance	finance-analyst, revenue-modeler
Sales	sales-engineer, crm-specialist
Product	product-manager, ux-researcher
Support	support-engineer, documentation-writer
Academic	research-analyst, paper-reviewer

Querying agents/index.json

import json
from pathlib import Path

index = json.loads(Path("harmonist/agents/index.json").read_text())

# Find all agents tagged 'security'
security_agents = [
    a for a in index["agents"]
    if "security" in a.get("tags", [])
]

# Find agents for a specific domain
blockchain_agents = [
    a for a in index["agents"]
    if a.get("category") == "blockchain"
]

# Get agent by slug
def get_agent(slug: str) -> dict:
    return next((a for a in index["agents"] if a["slug"] == slug), None)

agent = get_agent("blockchain-security-auditor")
print(agent["description"])

---

Mechanical Protocol Enforcement

How the stop Hook Works

Located at .cursor/hooks/stop, this hook runs after every code-changing turn:

1. Parses subagent dispatch markers from the session transcript.
2. Checks whether qa-verifier was dispatched.
3. Checks whether all required reviewers ran.
4. Checks whether session-handoff.md was updated.
5. Verifies supply-chain hashes for any modified agent files.

If any check fails, it returns a followup_message and blocks turn completion. loop_limit: 3 caps retries; on exhaustion, an incident is recorded in memory and surfaced next session.

Windows — Pure-Python Fallback

# On native Windows, hook_runner.py replaces the .sh hooks
python3 harmonist/agents/scripts/hook_runner.py --event stop --session-id "$SESSION_ID"

Both paths are tested against identical scenarios in CI (430+ assertions).

---

Memory System

Schema

Every entry must satisfy memory/SCHEMA.md. Fields:

correlation_id: "<session_id>-<task_seq>"   # written by hook, never by LLM
type: state | decision | pattern | incident
timestamp: "<ISO-8601>"
body: "<content>"                            # scanned for secrets
tags: []                                     # optional

Secret Scanning (built into memory.py append)

Blocked patterns include:

• AWS access keys (AKIA…)
• GitHub PATs (ghp_…, github_pat_…)
• Stripe tokens (sk_live_…)
• Slack webhooks (hooks.slack.com/…)
• GCP service account JSON
• Azure connection strings
• Telegram bot tokens
• Discord tokens
• Generic high-entropy tokens with secret: prefix
• DB connection strings with embedded credentials

Placeholder fences suppress scanning — safe for templates:

# These write cleanly without triggering secret scan
body = "Connect via ${DATABASE_URL} using key <API_KEY>"

Reading Memory in Agent Scripts

import subprocess, json

result = subprocess.run(
    ["python3", "harmonist/agents/scripts/memory.py", "list", "--last", "20", "--json"],
    capture_output=True, text=True
)
entries = json.loads(result.stdout)

# Filter decisions from current session
session_id = "17430000001234"  # from get-correlation-id
decisions = [
    e for e in entries
    if e["type"] == "decision" and e["correlation_id"].startswith(session_id)
]

---

Supply-Chain Integrity

Every file in the Harmonist distribution has a SHA-256 hash in MANIFEST.sha256. No file enters a project without verification.

Verifying Manually

import hashlib
from pathlib import Path

def verify_file(filepath: str, manifest_path: str = "harmonist/MANIFEST.sha256") -> bool:
    manifest = {}
    for line in Path(manifest_path).read_text().splitlines():
        if line.strip() and not line.startswith("#"):
            hash_val, fname = line.split(None, 1)
            manifest[fname.strip()] = hash_val

    target = Path(filepath)
    if not target.exists():
        return False

    actual = hashlib.sha256(target.read_bytes()).hexdigest()
    rel = str(target.relative_to("harmonist"))
    expected = manifest.get(rel)
    return actual == expected

# Example
print(verify_file("harmonist/agents/review/security-reviewer.md"))
# False if tampered → upgrade.py refuses to copy it

---

AGENTS.md — Orchestrator Configuration

After integration, AGENTS.md at your project root drives everything. Key sections the AI writes:

## Active roles
engineering, testing, security

## Domain invariants
- No floating-point arithmetic for monetary values
- All external HTTP calls must use retry logic with idempotency keys
- Security review required before any changes to auth/ directory

## Required reviewers
- qa-verifier: always
- security-reviewer: when path matches auth/**, payments/**

## Memory update policy
- Update session-handoff.md on every stop hook
- Record architectural decisions as type=decision entries

## Agent routing
- domains: [python, postgresql, fastapi]
- prefer: [backend-engineer, devops-engineer, qa-verifier]

---

IDE Integration Adapters

Harmonist supports adapters beyond Cursor. After base integration:

Assistant	Adapter file
Claude Code	harmonist/adapters/claude-code.md
GitHub Copilot	harmonist/adapters/copilot.md
Windsurf	harmonist/adapters/windsurf.md
Aider	harmonist/adapters/aider.md
Gemini CLI	harmonist/adapters/gemini-cli.md
Kimi / Qwen	harmonist/adapters/kimi.md

---

Common Patterns

Pattern: Dispatch a specialist and gate on review

# In an orchestrator script or AGENTS.md protocol block:

# 1. Dispatch domain specialist
dispatch("backend-engineer", task="Implement retry logic in payments/client.py")

# 2. Gate: qa-verifier MUST run before stop hook allows completion
dispatch("qa-verifier", task="Verify retry logic correctness and test coverage")

# 3. Gate: security-reviewer required for payments/** path
dispatch("security-reviewer", task="Review payment client for credential leaks")

# If either reviewer is missing, stop hook returns followup_message
# and the turn does not complete.

Pattern: Record a decision to memory

import subprocess

def record_decision(session_id: str, task_seq: int, body: str) -> None:
    subprocess.run([
        "python3", "harmonist/agents/scripts/memory.py", "append",
        "--type", "decision",
        "--session-id", session_id,
        "--task-seq", str(task_seq),
        "--body", body,
    ], check=True)

record_decision(
    session_id="17430000001234",
    task_seq=5,
    body="Chose Redis for session storage; PostgreSQL too slow at p99 for token lookups."
)

Pattern: Install a specialist on demand

# Add the Solidity auditor mid-project when blockchain work starts
python3 harmonist/agents/scripts/install_extras.py \
  --agent blockchain-security-auditor \
  --project .

# SHA is verified against MANIFEST.sha256 before install

---

Troubleshooting

Hook blocks every turn / loop limit hit

The stop hook returns followup_message when checks fail. Read the message — it specifies which check failed. Common causes:

• qa-verifier was not dispatched → add it to the turn's agent sequence.
• session-handoff.md not updated → the orchestrator must write it before stop.
• Supply-chain hash mismatch → run upgrade.py to restore clean files.
• loop_limit: 3 exhausted → check .cursor/memory/ for the recorded incident entry.

memory.py append rejected — secret pattern detected

Error: secret pattern detected in body: aws_access_key

Replace literal secrets with placeholder fences:

# Bad
body = "AWS key: AKIAIOSFODNN7EXAMPLE"

# Good — placeholder fence suppresses scan
body = "AWS key stored in ${AWS_ACCESS_KEY_ID} environment variable"

SHA verification failure on upgrade

REFUSED: hash mismatch for agents/review/security-reviewer.md

The local file was modified after install. To accept upstream:

# Re-clone to a temp dir and re-run upgrade
git clone https://github.com/GammaLabTechnologies/harmonist.git /tmp/harmonist-clean
python3 /tmp/harmonist-clean/agents/scripts/upgrade.py --pack /tmp/harmonist-clean --project .

Python version error

Error: Python 3.9+ required. Install from python.org (macOS: brew install python@3.12)

Each script has a version guard. Upgrade Python — no workaround.

Windows: hooks not firing

On native Windows without WSL, the .sh hooks don't execute. Ensure hook_runner.py is configured as the hook entry point in .cursor/hooks/:

# .cursor/hooks/stop (Windows override)
# Point your IDE hook configuration to:
python3 harmonist/agents/scripts/hook_runner.py --event stop --session-id %SESSION_ID%

Agent slug not found in index

import json
from pathlib import Path

index = json.loads(Path("harmonist/agents/index.json").read_text())
all_slugs = [a["slug"] for a in index["agents"]]
print("\n".join(sorted(all_slugs)))  # browse all 186

---

Reference Links

• Repository: https://github.com/GammaLabTechnologies/harmonist
• Homepage: https://gammalab.ae
• License: MIT
• Manual guide: harmonist/GUIDE_EN.md
• Changelog: harmonist/CHANGELOG.md
• CI: .github/workflows/ci.yml — 430+ test assertions, POSIX + Windows parity