# dietrichgebert/ponytail architecture

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

- Interactive diagram: https://gitdiagram.com/dietrichgebert/ponytail
- Repository: https://github.com/dietrichgebert/ponytail
- Video tour (about a minute): https://gitdiagram.com/dietrichgebert/ponytail/video

## Overview

Ponytail is an AI-agent coding skill and integration plugin: users activate a mode, receive repository-aware instructions, and use focused skills for implementation, review, audit, and related work. Its Claude Code band adds task metrics and a session ledger. The graph preserves the documented skill branches and the sampled activation, mode, map, and band components. Some integration and skill internals were not sampled, so only documented or index-supported relationships are connected.

Main entry points: [`hooks/ponytail-config.js`](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-config.js) (Mode configuration), [`hooks/ponytail-activate.js`](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-activate.js) (Session activation), [`hooks/band/board.ts`](https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/board.ts) (Task board), [`hooks/ponytail-instructions.js`](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-instructions.js) (Instruction builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Agent guidance"]
  node_ponytail_skill["Core skill<br/>[SKILL.md]"]
  node_review["Code review<br/>[SKILL.md]"]
  node_audit["Repository audit<br/>[SKILL.md]"]
  node_debt["Debt reduction<br/>[SKILL.md]"]
  node_gain["Code gain<br/>[SKILL.md]"]
  node_help["Skill help<br/>[SKILL.md]"]
end

subgraph group_runtime["Agent runtime"]
  node_activation["Session activation"]
  node_instructions["Instruction builder"]
  node_repo_map["Codebase map<br/>[ponytail-map.js]"]
  node_mode_tracker["Mode tracker"]
  node_runtime_state["Mode state"]
  node_configuration["Mode configuration<br/>[ponytail-config.js]"]
  node_subagent["Subagent guidance"]
end

subgraph group_band["Task band"]
  node_band_import["Session import"]
  node_band_register["Band registration<br/>[register.tsx]"]
  node_band_metrics["Band metrics<br/>[metrics.ts]"]
  node_task_board["Task board<br/>[board.ts]"]
  node_band_logo["Band graphics<br/>[logo.ts]"]
  node_ledger[("Band ledger")]
end

subgraph group_integrations["Host integrations"]
  node_pi_extension["Pi extension<br/>[index.js]"]
  node_cursor_hooks["Cursor hooks<br/>[cursor-hooks.js]"]
end

node_developer(("Developer"))
node_agent(("AI coding agent"))

node_developer -->|"requests work"| node_agent
node_agent -->|"uses guidance"| node_ponytail_skill
node_agent -->|"requests review"| node_review
node_agent -->|"requests audit"| node_audit
node_agent -.->|"requests debt"| node_debt
node_agent -.->|"requests gain"| node_gain
node_agent -.->|"requests help"| node_help
node_activation -->|"builds context"| node_instructions
node_activation -->|"runs map"| node_repo_map
node_activation -->|"reads defaults"| node_configuration
node_mode_tracker -->|"reads config"| node_configuration
node_mode_tracker -->|"writes mode"| node_runtime_state
node_activation -->|"reads mode"| node_runtime_state
node_instructions -->|"normalizes mode"| node_configuration
node_subagent -->|"uses builder"| node_instructions
node_pi_extension -->|"reads settings"| node_configuration
node_pi_extension -->|"loads guidance"| node_instructions
node_cursor_hooks -->|"resolves config"| node_configuration
node_band_import -->|"writes sessions"| node_ledger
node_band_register -->|"uses board"| node_task_board
node_band_register -->|"uses metrics"| node_band_metrics
node_band_metrics -->|"uses helpers"| node_task_board
node_task_board -->|"renders logo"| node_band_logo
node_task_board -.->|"reads sessions"| node_ledger

click node_ponytail_skill "https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail/SKILL.md"
click node_review "https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-review/SKILL.md"
click node_audit "https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md"
click node_debt "https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md"
click node_gain "https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-gain/SKILL.md"
click node_help "https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-help/SKILL.md"
click node_activation "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-activate.js"
click node_instructions "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-instructions.js"
click node_repo_map "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-map.js"
click node_mode_tracker "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js"
click node_runtime_state "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-runtime.js"
click node_configuration "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-config.js"
click node_subagent "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-subagent.js"
click node_pi_extension "https://github.com/dietrichgebert/ponytail/blob/main/pi-extension/index.js"
click node_cursor_hooks "https://github.com/dietrichgebert/ponytail/blob/main/scripts/cursor-hooks.js"
click node_band_import "https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-band-import.js"
click node_band_register "https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/register.tsx"
click node_band_metrics "https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/metrics.ts"
click node_task_board "https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/board.ts"
click node_band_logo "https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/logo.ts"

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_ponytail_skill,node_review,node_audit,node_debt,node_gain,node_help toneBlue
class node_activation,node_instructions,node_repo_map,node_mode_tracker,node_runtime_state,node_configuration,node_subagent toneAmber
class node_band_import,node_band_register,node_band_metrics,node_task_board,node_band_logo,node_ledger toneMint
class node_pi_extension,node_cursor_hooks toneRose
class node_developer,node_agent toneIndigo
```

## Components

### Agent guidance

- [Core skill](https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail/SKILL.md): `skills/ponytail/SKILL.md`
- [Code review](https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-review/SKILL.md): `skills/ponytail-review/SKILL.md`
- [Repository audit](https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md): `skills/ponytail-audit/SKILL.md`
- [Debt reduction](https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md): `skills/ponytail-debt/SKILL.md`
- [Code gain](https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-gain/SKILL.md): `skills/ponytail-gain/SKILL.md`
- [Skill help](https://github.com/dietrichgebert/ponytail/blob/main/skills/ponytail-help/SKILL.md): `skills/ponytail-help/SKILL.md`

### Agent runtime

- [Session activation](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-activate.js): `hooks/ponytail-activate.js`
- [Instruction builder](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-instructions.js): `hooks/ponytail-instructions.js`
- [Codebase map](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-map.js): `hooks/ponytail-map.js`
- [Mode tracker](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js): `hooks/ponytail-mode-tracker.js`
- [Mode state](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-runtime.js): `hooks/ponytail-runtime.js`
- [Mode configuration](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-config.js): `hooks/ponytail-config.js`
- [Subagent guidance](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-subagent.js): `hooks/ponytail-subagent.js`

### Task band

- [Session import](https://github.com/dietrichgebert/ponytail/blob/main/hooks/ponytail-band-import.js): `hooks/ponytail-band-import.js`
- [Band registration](https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/register.tsx): `hooks/band/register.tsx`
- [Band metrics](https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/metrics.ts): `hooks/band/metrics.ts`
- [Task board](https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/board.ts): `hooks/band/board.ts`
- [Band graphics](https://github.com/dietrichgebert/ponytail/blob/main/hooks/band/logo.ts): `hooks/band/logo.ts`
- **Band ledger**

### Host integrations

- [Pi extension](https://github.com/dietrichgebert/ponytail/blob/main/pi-extension/index.js): `pi-extension/index.js`
- [Cursor hooks](https://github.com/dietrichgebert/ponytail/blob/main/scripts/cursor-hooks.js): `scripts/cursor-hooks.js`

### Other components

- **Developer**
- **AI coding agent**

## Connections

- Developer → AI coding agent: requests work (evidence: `README.md`)
- AI coding agent → Core skill: uses guidance (evidence: `README.md`)
- AI coding agent → Code review: requests review (evidence: `README.md`)
- AI coding agent → Repository audit: requests audit (evidence: `README.md`)
- AI coding agent → Debt reduction: requests debt
- AI coding agent → Code gain: requests gain
- AI coding agent → Skill help: requests help
- Session activation → Instruction builder: builds context (evidence: `hooks/ponytail-activate.js`)
- Session activation → Codebase map: runs map (evidence: `hooks/ponytail-activate.js`)
- Session activation → Mode configuration: reads defaults (evidence: `hooks/ponytail-activate.js`)
- Mode tracker → Mode configuration: reads config (evidence: `hooks/ponytail-mode-tracker.js`)
- Mode tracker → Mode state: writes mode (evidence: `hooks/ponytail-mode-tracker.js`)
- Session activation → Mode state: reads mode (evidence: `hooks/ponytail-activate.js`)
- Instruction builder → Mode configuration: normalizes mode (evidence: `hooks/ponytail-instructions.js`)
- Subagent guidance → Instruction builder: uses builder (evidence: `hooks/ponytail-subagent.js`)
- Pi extension → Mode configuration: reads settings (evidence: `pi-extension/index.js`)
- Pi extension → Instruction builder: loads guidance (evidence: `pi-extension/index.js`)
- Cursor hooks → Mode configuration: resolves config (evidence: `scripts/cursor-hooks.js`)
- Session import → Band ledger: writes sessions (evidence: `hooks/ponytail-band-import.js`)
- Band registration → Task board: uses board (evidence: `hooks/band/register.tsx`)
- Band registration → Band metrics: uses metrics (evidence: `hooks/band/register.tsx`)
- Band metrics → Task board: uses helpers (evidence: `hooks/band/metrics.ts`)
- Task board → Band graphics: renders logo (evidence: `hooks/band/board.ts`)
- Task board → Band ledger: reads sessions