harmonist-agent-orchestration

What this skill does

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