# gammalabtechnologies/harmonist architecture

> Architecture diagram of the GitHub repository gammalabtechnologies/harmonist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gammalabtechnologies/harmonist
- Repository: https://github.com/gammalabtechnologies/harmonist

## Overview

Harmonist is a portable AI-agent pack for coding assistants, combining a curated specialist catalogue and project integration tools with IDE-hook protocol enforcement and validated memory. The main workflow is: a user integrates the pack into a project, selects/configures agents, then an assistant works under hooks that gate completion and record task memory. The graph also includes conversion, upgrades, and related pack operations. Edges reflect README statements or shown source references; unsampled subsystem internals are not expanded.

Main entry points: [`agents/scripts/integrate.py`](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/integrate.py) (Integration Runner), [`hooks/scripts/hook_runner.py`](https://github.com/gammalabtechnologies/harmonist/blob/main/hooks/scripts/hook_runner.py) (Hook Runtime), [`agents`](https://github.com/gammalabtechnologies/harmonist/tree/main/agents) (Agent Definitions), [`memory/memory.py`](https://github.com/gammalabtechnologies/harmonist/blob/main/memory/memory.py) (Memory CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Project Integration"]
  node_integration_prompt["Integration Prompt"]
  node_integrate["Integration Runner<br/>[integrate.py]"]
  node_merge_agents["Project Rules Merge<br/>[merge_agents_md.py]"]
  node_upgrade["Pack Upgrade<br/>[upgrade.py]"]
  node_verify["Integration Audit"]
  node_install_extras["Specialist Installer<br/>[install_extras.py]"]
end

subgraph group_catalog["Agent Catalogue"]
  node_agent_catalog[("Specialist Catalogue<br/>[index.json]")]
  node_agent_definitions["Agent Definitions"]
  node_convert["Agent Converter<br/>[convert.py]"]
  node_extract["Essentials Extractor"]
end

subgraph group_enforcement["Protocol Enforcement"]
  node_hook_config["IDE Hook Configuration<br/>[hooks.json]"]
  node_hook_runner["Hook Runtime<br/>[hook_runner.py]"]
  node_strict_slugs["Strict Agent Registry<br/>[strict_slugs.py]"]
end

subgraph group_memory["Validated Memory"]
  node_memory_cli["Memory CLI<br/>[memory.py]"]
  node_memory_validator["Memory Validator<br/>[validate.py]"]
  node_memory_store["Project Memory"]
  node_memory_migrations["Memory Migrations<br/>[migrations.py]"]
end

subgraph group_operations["Pack Operations"]
  node_schema_migrator["Agent Schema Migrator<br/>[migrate_schema.py]"]
  node_pack_health["Pack Health Check"]
  node_rules_scanner["Rules Conflict Scanner"]
  node_regression_detector["Regression Command Detector"]
  node_onboard["Project Onboarding<br/>[onboard.py]"]
  node_playbooks["Workflow Playbooks"]
end

node_developer(("Developer"))
node_assistant(("Coding Assistant"))

node_developer -->|"starts integration"| node_integration_prompt
node_integration_prompt -.->|"automates steps"| node_integrate
node_integrate -->|"merges rules"| node_merge_agents
node_integrate -->|"runs upgrade"| node_upgrade
node_integrate -->|"audits integration"| node_verify
node_developer -->|"adds specialists"| node_install_extras
node_agent_catalog -->|"selects entries"| node_install_extras
node_agent_catalog -.->|"indexes agents"| node_agent_definitions
node_agent_definitions -->|"guides work"| node_assistant
node_agent_definitions -->|"converts formats"| node_convert
node_convert -->|"extracts essentials"| node_extract
node_hook_config -->|"dispatches events"| node_hook_runner
node_assistant -->|"triggers hooks"| node_hook_runner
node_hook_runner -->|"checks memory state"| node_memory_store
node_hook_runner -.->|"checks reviewers"| node_strict_slugs
node_assistant -->|"records entries"| node_memory_cli
node_memory_cli -->|"appends entries"| node_memory_store
node_memory_cli -->|"validates entries"| node_memory_validator
node_memory_migrations -->|"uses schema"| node_memory_validator
node_schema_migrator -->|"supports conversion"| node_convert
node_pack_health -->|"checks registry"| node_strict_slugs
node_onboard -->|"uses registry"| node_strict_slugs
node_developer -->|"uses workflows"| node_playbooks
node_integrate -->|"checks pack"| node_pack_health
node_integrate -.->|"detects commands"| node_regression_detector
node_verify -->|"checks conflicts"| node_rules_scanner

click node_integration_prompt "https://github.com/gammalabtechnologies/harmonist/blob/main/integration-prompt.md"
click node_integrate "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/integrate.py"
click node_merge_agents "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/merge_agents_md.py"
click node_upgrade "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/upgrade.py"
click node_verify "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/verify_integration.py"
click node_install_extras "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/install_extras.py"
click node_agent_catalog "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/index.json"
click node_agent_definitions "https://github.com/gammalabtechnologies/harmonist/tree/main/agents"
click node_convert "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/convert.py"
click node_extract "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/extract_essentials.py"
click node_hook_config "https://github.com/gammalabtechnologies/harmonist/blob/main/hooks/hooks.json"
click node_hook_runner "https://github.com/gammalabtechnologies/harmonist/blob/main/hooks/scripts/hook_runner.py"
click node_strict_slugs "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/strict_slugs.py"
click node_memory_cli "https://github.com/gammalabtechnologies/harmonist/blob/main/memory/memory.py"
click node_memory_validator "https://github.com/gammalabtechnologies/harmonist/blob/main/memory/validate.py"
click node_memory_store "https://github.com/gammalabtechnologies/harmonist/tree/main/memory"
click node_memory_migrations "https://github.com/gammalabtechnologies/harmonist/blob/main/memory/migrations.py"
click node_schema_migrator "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/migrate_schema.py"
click node_pack_health "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/check_pack_health.py"
click node_rules_scanner "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/scan_rules_conflicts.py"
click node_regression_detector "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/detect_regression_commands.py"
click node_onboard "https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/onboard.py"
click node_playbooks "https://github.com/gammalabtechnologies/harmonist/tree/main/playbooks"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_integration_prompt,node_integrate,node_merge_agents,node_upgrade,node_verify,node_install_extras toneBlue
class node_agent_catalog,node_agent_definitions,node_convert,node_extract toneAmber
class node_hook_config,node_hook_runner,node_strict_slugs toneMint
class node_memory_cli,node_memory_validator,node_memory_store,node_memory_migrations toneRose
class node_schema_migrator,node_pack_health,node_rules_scanner,node_regression_detector,node_onboard,node_playbooks,node_developer,node_assistant toneIndigo
```

## Components

### Project Integration

- [Integration Prompt](https://github.com/gammalabtechnologies/harmonist/blob/main/integration-prompt.md): `integration-prompt.md`
- [Integration Runner](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/integrate.py): `agents/scripts/integrate.py`
- [Project Rules Merge](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/merge_agents_md.py): `agents/scripts/merge_agents_md.py`
- [Pack Upgrade](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/upgrade.py): `agents/scripts/upgrade.py`
- [Integration Audit](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/verify_integration.py): `agents/scripts/verify_integration.py`
- [Specialist Installer](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/install_extras.py): `agents/scripts/install_extras.py`

### Agent Catalogue

- [Specialist Catalogue](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/index.json): `agents/index.json`
- [Agent Definitions](https://github.com/gammalabtechnologies/harmonist/tree/main/agents): `agents`
- [Agent Converter](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/convert.py): `agents/scripts/convert.py`
- [Essentials Extractor](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/extract_essentials.py): `agents/scripts/extract_essentials.py`

### Protocol Enforcement

- [IDE Hook Configuration](https://github.com/gammalabtechnologies/harmonist/blob/main/hooks/hooks.json): `hooks/hooks.json`
- [Hook Runtime](https://github.com/gammalabtechnologies/harmonist/blob/main/hooks/scripts/hook_runner.py): `hooks/scripts/hook_runner.py`
- [Strict Agent Registry](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/strict_slugs.py): `agents/scripts/strict_slugs.py`

### Validated Memory

- [Memory CLI](https://github.com/gammalabtechnologies/harmonist/blob/main/memory/memory.py): `memory/memory.py`
- [Memory Validator](https://github.com/gammalabtechnologies/harmonist/blob/main/memory/validate.py): `memory/validate.py`
- [Project Memory](https://github.com/gammalabtechnologies/harmonist/tree/main/memory): `memory`
- [Memory Migrations](https://github.com/gammalabtechnologies/harmonist/blob/main/memory/migrations.py): `memory/migrations.py`

### Pack Operations

- [Agent Schema Migrator](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/migrate_schema.py): `agents/scripts/migrate_schema.py`
- [Pack Health Check](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/check_pack_health.py): `agents/scripts/check_pack_health.py`
- [Rules Conflict Scanner](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/scan_rules_conflicts.py): `agents/scripts/scan_rules_conflicts.py`
- [Regression Command Detector](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/detect_regression_commands.py): `agents/scripts/detect_regression_commands.py`
- [Project Onboarding](https://github.com/gammalabtechnologies/harmonist/blob/main/agents/scripts/onboard.py): `agents/scripts/onboard.py`
- [Workflow Playbooks](https://github.com/gammalabtechnologies/harmonist/tree/main/playbooks): `playbooks`

### Other components

- **Developer**
- **Coding Assistant**

## Connections

- Developer → Integration Prompt: starts integration (evidence: `README.md`)
- Integration Prompt → Integration Runner: automates steps
- Integration Runner → Project Rules Merge: merges rules (evidence: `agents/scripts/integrate.py`)
- Integration Runner → Pack Upgrade: runs upgrade (evidence: `agents/scripts/integrate.py`)
- Integration Runner → Integration Audit: audits integration (evidence: `agents/scripts/integrate.py`)
- Developer → Specialist Installer: adds specialists (evidence: `agents/scripts/install_extras.py`)
- Specialist Catalogue → Specialist Installer: selects entries (evidence: `agents/scripts/install_extras.py`)
- Specialist Catalogue → Agent Definitions: indexes agents
- Agent Definitions → Coding Assistant: guides work (evidence: `README.md`)
- Agent Definitions → Agent Converter: converts formats (evidence: `agents/scripts/convert.py`)
- Agent Converter → Essentials Extractor: extracts essentials (evidence: `agents/scripts/convert.py`)
- IDE Hook Configuration → Hook Runtime: dispatches events (evidence: `README.md`)
- Coding Assistant → Hook Runtime: triggers hooks (evidence: `README.md`)
- Hook Runtime → Project Memory: checks memory state (evidence: `README.md`)
- Hook Runtime → Strict Agent Registry: checks reviewers
- Coding Assistant → Memory CLI: records entries (evidence: `README.md`)
- Memory CLI → Project Memory: appends entries (evidence: `memory/memory.py`)
- Memory CLI → Memory Validator: validates entries (evidence: `README.md`)
- Memory Migrations → Memory Validator: uses schema (evidence: `memory/migrations.py`)
- Agent Schema Migrator → Agent Converter: supports conversion (evidence: `agents/scripts/convert.py`)
- Pack Health Check → Strict Agent Registry: checks registry (evidence: `agents/scripts/check_pack_health.py`)
- Project Onboarding → Strict Agent Registry: uses registry (evidence: `agents/scripts/onboard.py`)
- Developer → Workflow Playbooks: uses workflows (evidence: `README.md`)
- Integration Runner → Pack Health Check: checks pack (evidence: `agents/scripts/integrate.py`)
- Integration Runner → Regression Command Detector: detects commands
- Integration Audit → Rules Conflict Scanner: checks conflicts (evidence: `agents/scripts/verify_integration.py`)
