Harmonist Agent Orchestration

```markdown
---
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

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

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

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

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

### `integrate.py` — CLI Integration

```bash
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`

```python
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

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

```yaml
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:

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

### Reading Memory in Agent Scripts

```python
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

```python
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:

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

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

```python
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

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

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

```bash
# 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/`:

```python
# .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

```python
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
```