Trending-skills 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

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

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

session_id = <unix-seconds><pid4>

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

agents/index.json

Categories

scout

repo-map

qa-verifier

security-reviewer

strict-reviewer

backend-engineer

frontend-engineer

devops-engineer

blockchain-security-auditor

zk-steward

visionos-spatial-engineer

ios-engineer

android-engineer

wechat-mini-program-developer

xiaohongshu-specialist

laravel-livewire-specialist

roblox-systems-scripter

seo-specialist

douyin-specialist

content-strategist

finance-analyst

revenue-modeler

sales-engineer

crm-specialist

product-manager

ux-researcher

support-engineer

documentation-writer

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

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

loop_limit: 3

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

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

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

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

harmonist/adapters/claude-code.md

harmonist/adapters/copilot.md

harmonist/adapters/windsurf.md

harmonist/adapters/aider.md

harmonist/adapters/gemini-cli.md

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

followup_message

• 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

hook_runner.py

.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