# barkesh/ponytail architecture

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

- Interactive diagram: https://gitdiagram.com/barkesh/ponytail
- Repository: https://github.com/barkesh/ponytail

## Overview

Ponytail is an AI-agent coding skill with runtime hooks and host-specific adapters. The main workflow is a developer prompt entering an agent, where Ponytail’s activation supplies coding rules and a repository map; the agent then performs the task under those rules. Separate skills support review, audit, debt, gain and help. In Claude Code, the band surfaces session metrics and a local task board. The graph reflects documented behavior and sampled call/import evidence; unsampled adapter wiring is omitted rather than inferred.

Main entry points: [`hooks/band/board.ts`](https://github.com/barkesh/ponytail/blob/main/hooks/band/board.ts) (Task board), [`hooks/ponytail-activate.js`](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-activate.js) (Session activation), [`hooks/ponytail-mode-tracker.js`](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-mode-tracker.js) (Mode tracker), [`hooks/band/register.tsx`](https://github.com/barkesh/ponytail/blob/main/hooks/band/register.tsx) (Band integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Agent workflow"]
  node_skill["Core skill<br/>[SKILL.md]"]
end

subgraph group_capabilities["Skills and reviews"]
  node_review["Review skill<br/>[SKILL.md]"]
  node_audit["Audit skill<br/>[SKILL.md]"]
  node_debt["Debt skill<br/>[SKILL.md]"]
  node_gain["Gain skill<br/>[SKILL.md]"]
  node_help["Help skill<br/>[SKILL.md]"]
end

subgraph group_runtime["Runtime hooks"]
  node_activate["Session activation"]
  node_instructions["Instruction builder"]
  node_map["Repository mapper<br/>[ponytail-map.js]"]
  node_config["Mode configuration<br/>[ponytail-config.js]"]
  node_state["Runtime state"]
  node_tracker["Mode tracker"]
end

subgraph group_band["Metrics band"]
  node_bandimport["Session importer"]
  node_ledger[("Band CSV ledger")]
  node_bandregister["Band integration<br/>[register.tsx]"]
  node_metrics["Metrics helpers<br/>[metrics.ts]"]
  node_board["Task board<br/>[board.ts]"]
  node_logo["Board artwork<br/>[logo.ts]"]
end

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

node_developer -->|"prompts"| node_agent
node_agent -->|"uses skill"| node_skill
node_activate -->|"builds rules"| node_instructions
node_activate -->|"runs map"| node_map
node_activate -->|"reads mode"| node_config
node_tracker -->|"reads and writes"| node_config
node_tracker -->|"uses runtime state"| node_state
node_tracker -->|"loads rules"| node_instructions
node_developer -->|"requests review"| node_review
node_developer -->|"requests audit"| node_audit
node_developer -.->|"requests debt"| node_debt
node_developer -.->|"requests gain"| node_gain
node_developer -.->|"requests help"| node_help
node_bandimport -->|"writes sessions"| node_ledger
node_ledger -->|"supplies CSV"| node_board
node_bandregister -->|"uses board"| node_board
node_bandregister -->|"uses metrics"| node_metrics
node_metrics -->|"uses helpers"| node_board
node_board -->|"renders artwork"| node_logo

click node_skill "https://github.com/barkesh/ponytail/blob/main/skills/ponytail/SKILL.md"
click node_activate "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-activate.js"
click node_instructions "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-instructions.js"
click node_map "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-map.js"
click node_config "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-config.js"
click node_state "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-runtime.js"
click node_tracker "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-mode-tracker.js"
click node_review "https://github.com/barkesh/ponytail/blob/main/skills/ponytail-review/SKILL.md"
click node_audit "https://github.com/barkesh/ponytail/blob/main/skills/ponytail-audit/SKILL.md"
click node_debt "https://github.com/barkesh/ponytail/blob/main/skills/ponytail-debt/SKILL.md"
click node_gain "https://github.com/barkesh/ponytail/blob/main/skills/ponytail-gain/SKILL.md"
click node_help "https://github.com/barkesh/ponytail/blob/main/skills/ponytail-help/SKILL.md"
click node_bandimport "https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-band-import.js"
click node_bandregister "https://github.com/barkesh/ponytail/blob/main/hooks/band/register.tsx"
click node_metrics "https://github.com/barkesh/ponytail/blob/main/hooks/band/metrics.ts"
click node_board "https://github.com/barkesh/ponytail/blob/main/hooks/band/board.ts"
click node_logo "https://github.com/barkesh/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_skill toneBlue
class node_review,node_audit,node_debt,node_gain,node_help toneAmber
class node_activate,node_instructions,node_map,node_config,node_state,node_tracker toneMint
class node_bandimport,node_ledger,node_bandregister,node_metrics,node_board,node_logo toneRose
class node_developer,node_agent toneIndigo
```

## Components

### Agent workflow

- [Core skill](https://github.com/barkesh/ponytail/blob/main/skills/ponytail/SKILL.md): `skills/ponytail/SKILL.md`

### Skills and reviews

- [Review skill](https://github.com/barkesh/ponytail/blob/main/skills/ponytail-review/SKILL.md): `skills/ponytail-review/SKILL.md`
- [Audit skill](https://github.com/barkesh/ponytail/blob/main/skills/ponytail-audit/SKILL.md): `skills/ponytail-audit/SKILL.md`
- [Debt skill](https://github.com/barkesh/ponytail/blob/main/skills/ponytail-debt/SKILL.md): `skills/ponytail-debt/SKILL.md`
- [Gain skill](https://github.com/barkesh/ponytail/blob/main/skills/ponytail-gain/SKILL.md): `skills/ponytail-gain/SKILL.md`
- [Help skill](https://github.com/barkesh/ponytail/blob/main/skills/ponytail-help/SKILL.md): `skills/ponytail-help/SKILL.md`

### Runtime hooks

- [Session activation](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-activate.js): `hooks/ponytail-activate.js`
- [Instruction builder](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-instructions.js): `hooks/ponytail-instructions.js`
- [Repository mapper](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-map.js): `hooks/ponytail-map.js`
- [Mode configuration](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-config.js): `hooks/ponytail-config.js`
- [Runtime state](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-runtime.js): `hooks/ponytail-runtime.js`
- [Mode tracker](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-mode-tracker.js): `hooks/ponytail-mode-tracker.js`

### Metrics band

- [Session importer](https://github.com/barkesh/ponytail/blob/main/hooks/ponytail-band-import.js): `hooks/ponytail-band-import.js`
- **Band CSV ledger**
- [Band integration](https://github.com/barkesh/ponytail/blob/main/hooks/band/register.tsx): `hooks/band/register.tsx`
- [Metrics helpers](https://github.com/barkesh/ponytail/blob/main/hooks/band/metrics.ts): `hooks/band/metrics.ts`
- [Task board](https://github.com/barkesh/ponytail/blob/main/hooks/band/board.ts): `hooks/band/board.ts`
- [Board artwork](https://github.com/barkesh/ponytail/blob/main/hooks/band/logo.ts): `hooks/band/logo.ts`

### Other components

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

## Connections

- Developer → AI agent: prompts (evidence: `README.md`)
- AI agent → Core skill: uses skill (evidence: `README.md`)
- Session activation → Instruction builder: builds rules (evidence: `hooks/ponytail-activate.js`)
- Session activation → Repository mapper: runs map (evidence: `hooks/ponytail-activate.js`)
- Session activation → Mode configuration: reads mode (evidence: `hooks/ponytail-activate.js`)
- Mode tracker → Mode configuration: reads and writes (evidence: `hooks/ponytail-mode-tracker.js`)
- Mode tracker → Runtime state: uses runtime state (evidence: `hooks/ponytail-mode-tracker.js`)
- Mode tracker → Instruction builder: loads rules (evidence: `hooks/ponytail-mode-tracker.js`)
- Developer → Review skill: requests review (evidence: `README.md`)
- Developer → Audit skill: requests audit (evidence: `README.md`)
- Developer → Debt skill: requests debt
- Developer → Gain skill: requests gain
- Developer → Help skill: requests help
- Session importer → Band CSV ledger: writes sessions (evidence: `hooks/ponytail-band-import.js`)
- Band CSV ledger → Task board: supplies CSV (evidence: `hooks/band/board.ts`)
- Band integration → Task board: uses board (evidence: `hooks/band/register.tsx`)
- Band integration → Metrics helpers: uses metrics (evidence: `hooks/band/register.tsx`)
- Metrics helpers → Task board: uses helpers (evidence: `hooks/band/metrics.ts`)
- Task board → Board artwork: renders artwork (evidence: `hooks/band/board.ts`)