# the-agency-ai/the-agency architecture

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

- Interactive diagram: https://gitdiagram.com/the-agency-ai/the-agency
- Repository: https://github.com/the-agency-ai/the-agency

## Overview

TheAgency is a Claude Code multi-agent collaboration framework, with a set of companion applications in the development repository. The main workflow is a Principal working with specialized agent sessions, organizing work in workstreams, coordinating sessions through dispatches and flags, and applying quality gates before work is accepted. Session lifecycle capture and declarative hook rules support that flow. The README documents these capabilities, but the supplied source excerpts chiefly cover Markdown Pal and do not expose the framework’s runtime wiring; the graph therefore omits uncertain internal call relationships.

Main entry points: [`src/agency`](https://github.com/the-agency-ai/the-agency/tree/main/src/agency) (Agent classes), [`src/apps/mdpal/Sources/mdpal`](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/mdpal) (Markdown Pal CLI), [`src/apps/mdpal-app/Sources/MarkdownPalApp`](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal-app/Sources/MarkdownPalApp) (Markdown Pal app), [`src/agency/workstreams`](https://github.com/the-agency-ai/the-agency/tree/main/src/agency/workstreams) (Workstreams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collaboration["Agent collaboration"]
  node_agent_classes["Agent classes"]
  node_workstreams["Workstreams"]
end

subgraph group_coordination["Session coordination"]
  node_iscp["ISCP coordination"]
  node_dispatches["Dispatches"]
  node_flags["Coordination flags"]
  node_local_db[("Local SQLite DB")]
end

subgraph group_quality["Quality and lifecycle"]
  node_reviewers["Reviewer agents"]
  node_quality_gates["Quality gates"]
  node_session_hooks["Session lifecycle hooks"]
  node_hook_rules["Hookify rules"]
end

subgraph group_applications["Companion applications"]
  node_mdpal_cli["Markdown Pal CLI"]
  node_mdpal_engine["Markdown Pal engine"]
  node_mdpal_app["Markdown Pal app"]
  node_slidepal_mac["SlidePal for Mac"]
  node_slidepal_web["SlidePal web"]
  node_ports_tools["Monofolk port tools"]
end

node_principal(("Principal"))
node_claude["Claude Code"]

node_principal -->|"directs work"| node_claude
node_claude -->|"runs agents"| node_agent_classes
node_agent_classes -->|"work in"| node_workstreams
node_agent_classes -->|"coordinate via"| node_iscp
node_iscp -->|"routes work"| node_dispatches
node_iscp -->|"routes flags"| node_flags
node_iscp -->|"stores coordination"| node_local_db
node_agent_classes -->|"invoke review"| node_reviewers
node_reviewers -->|"inform checks"| node_quality_gates
node_claude -->|"captures lifecycle"| node_session_hooks
node_claude -->|"applies rules"| node_hook_rules
node_mdpal_app -->|"invokes commands"| node_mdpal_cli
node_mdpal_cli -->|"uses engine"| node_mdpal_engine

click node_agent_classes "https://github.com/the-agency-ai/the-agency/tree/main/src/agency"
click node_workstreams "https://github.com/the-agency-ai/the-agency/tree/main/src/agency/workstreams"
click node_iscp "https://github.com/the-agency-ai/the-agency/tree/main/src/agency"
click node_dispatches "https://github.com/the-agency-ai/the-agency/tree/main/usr/jordan/captain/dispatches"
click node_flags "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/MarkdownPalEngine/Flag"
click node_reviewers "https://github.com/the-agency-ai/the-agency/tree/main/src/agency"
click node_quality_gates "https://github.com/the-agency-ai/the-agency/tree/main/src/agency"
click node_session_hooks "https://github.com/the-agency-ai/the-agency/tree/main/src/claude/hooks"
click node_hook_rules "https://github.com/the-agency-ai/the-agency/tree/main/src/agency"
click node_mdpal_cli "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/mdpal"
click node_mdpal_engine "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/MarkdownPalEngine"
click node_mdpal_app "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal-app/Sources/MarkdownPalApp"
click node_slidepal_mac "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdslidepal-mac/Sources/MdSlidepalLib"
click node_slidepal_web "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdslidepal-web/src"
click node_ports_tools "https://github.com/the-agency-ai/the-agency/tree/main/src/apps/monofolk-ports/tools"

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_agent_classes,node_workstreams toneBlue
class node_iscp,node_dispatches,node_flags,node_local_db toneAmber
class node_reviewers,node_quality_gates,node_session_hooks,node_hook_rules toneMint
class node_mdpal_cli,node_mdpal_engine,node_mdpal_app,node_slidepal_mac,node_slidepal_web,node_ports_tools toneRose
class node_principal,node_claude toneIndigo
```

## Components

### Agent collaboration

- [Agent classes](https://github.com/the-agency-ai/the-agency/tree/main/src/agency): `src/agency`
- [Workstreams](https://github.com/the-agency-ai/the-agency/tree/main/src/agency/workstreams): `src/agency/workstreams`

### Session coordination

- [ISCP coordination](https://github.com/the-agency-ai/the-agency/tree/main/src/agency): `src/agency`
- [Dispatches](https://github.com/the-agency-ai/the-agency/tree/main/usr/jordan/captain/dispatches): `usr/jordan/captain/dispatches`
- [Coordination flags](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/MarkdownPalEngine/Flag): `src/apps/mdpal/Sources/MarkdownPalEngine/Flag`
- **Local SQLite DB**

### Quality and lifecycle

- [Reviewer agents](https://github.com/the-agency-ai/the-agency/tree/main/src/agency): `src/agency`
- [Quality gates](https://github.com/the-agency-ai/the-agency/tree/main/src/agency): `src/agency`
- [Session lifecycle hooks](https://github.com/the-agency-ai/the-agency/tree/main/src/claude/hooks): `src/claude/hooks`
- [Hookify rules](https://github.com/the-agency-ai/the-agency/tree/main/src/agency): `src/agency`

### Companion applications

- [Markdown Pal CLI](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/mdpal): `src/apps/mdpal/Sources/mdpal`
- [Markdown Pal engine](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal/Sources/MarkdownPalEngine): `src/apps/mdpal/Sources/MarkdownPalEngine`
- [Markdown Pal app](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdpal-app/Sources/MarkdownPalApp): `src/apps/mdpal-app/Sources/MarkdownPalApp`
- [SlidePal for Mac](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdslidepal-mac/Sources/MdSlidepalLib): `src/apps/mdslidepal-mac/Sources/MdSlidepalLib`
- [SlidePal web](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/mdslidepal-web/src): `src/apps/mdslidepal-web/src`
- [Monofolk port tools](https://github.com/the-agency-ai/the-agency/tree/main/src/apps/monofolk-ports/tools): `src/apps/monofolk-ports/tools`

### Other components

- **Principal**
- **Claude Code**

## Connections

- Principal → Claude Code: directs work
- Claude Code → Agent classes: runs agents
- Agent classes → Workstreams: work in
- Agent classes → ISCP coordination: coordinate via
- ISCP coordination → Dispatches: routes work
- ISCP coordination → Coordination flags: routes flags
- ISCP coordination → Local SQLite DB: stores coordination
- Agent classes → Reviewer agents: invoke review
- Reviewer agents → Quality gates: inform checks
- Claude Code → Session lifecycle hooks: captures lifecycle
- Claude Code → Hookify rules: applies rules
- Markdown Pal app → Markdown Pal CLI: invokes commands
- Markdown Pal CLI → Markdown Pal engine: uses engine