# Core Components of the Ponytail Architecture: Skills, Hooks, and the Lazy Senior Dev Stack

> Explore the core components of the Ponytail architecture: markdown skills, JS hooks, and adapter glue. Discover how it enforces the lazy senior dev philosophy in LLM environments. Learn more today.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: architecture
- Published: 2026-09-10

---

**The Ponytail architecture consists of markdown-based skill definitions, JavaScript runtime hooks for state management, and host-specific adapter glue that together enforce the "lazy senior dev" philosophy across any LLM-powered environment.**

The Ponytail repository by DietrichGebert implements a portable, intensity-controlled coding assistant built on a "skill-plus-hook" pattern. Understanding the core components of the Ponytail architecture reveals how the system maintains persistent behavioral rules across different AI agents while allowing users to toggle enforcement levels dynamically.

## Skill Definitions: The Behavioral Core

**Skills** form the heart of the Ponytail architecture. These are markdown-based instruction files that define behavior for the main command and its auxiliary utilities.

The repository organizes skills into discrete units within the `skills/` directory:

- **[`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md)** – Defines the main `/ponytail` command and implements the ladder logic (YAGNI → stdlib → native → dependency → one-liner)
- **[`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md)** – Powers the `/ponytail-review` diff-analysis utility
- **[`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md)** – Drives the `/ponytail-audit` repository-wide over-engineering scanner
- **[`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md)**, **[`skills/ponytail-gain/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-gain/SKILL.md)**, and **[`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md)** – Provide technical debt tracking, benchmark scoreboards, and command reference functionality

Each skill file contains the complete behavioral specification for its respective command, making the system modular and editor-agnostic.

## Runtime Hooks: The Enforcement Layer

While skills define *what* to do, **hooks** ensure *when* and *how* the rules apply. Located in the `hooks/` directory, these JavaScript components inject the always-on instruction set and manage session state.

### Runtime Injection Hook

The **[`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js)** file handles the core enforcement mechanism. It injects the active instruction set into every LLM turn, ensuring the "lazy senior dev" principles apply consistently across the conversation regardless of context window changes.

### Mode State Management

Intensity control relies on **[`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js)**, which implements a lightweight state machine persisting the chosen level across turns. This component manages four distinct states:

- `lite` – Minimal enforcement
- `full` – Standard lazy-dev rules
- `ultra` – Aggressive optimization checks
- `off` – Disabled state

The tracker responds to the `PONYTAIL_DEFAULT_MODE` environment variable and overrides from slash commands.

### Activation and Configuration

Two additional hooks handle initialization and user preferences:

- **[`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js)** – Runs on the first user prompt to toggle Ponytail on or off and prints the status line in supported hosts
- **[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)** – Reads optional user configuration from `~/.config/ponytail/config.json` or environment variables to set default modes

### Status Line Integration

For terminal visibility, **[`hooks/ponytail-statusline.sh`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-statusline.sh)** (Bash) and **`hooks/ponytail-statusline.ps1`** (PowerShell) render the current intensity level directly in the host UI, providing immediate visual feedback about the active enforcement mode.

## Host Adapter Layer: Cross-Agent Portability

The Ponytail architecture achieves portability through **adapter-specific glue** files that map core skills and hooks to various AI agent implementations. These metadata files bridge the gap between Ponytail's generic skill definitions and host-specific plugin systems:

- **[`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json)** – Registration manifest for Claude and Codex implementations
- **[`hooks/qoder-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/qoder-hooks.json)** – Hook mappings for Qoder agents
- **[`hooks/gemini-extension.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/gemini-extension.json)** – Extension metadata for Gemini integrations

This adapter layer allows identical skill behavior across disparate LLM hosts without modifying the underlying markdown or JavaScript logic.

## Fallback Mechanisms for Instruction-Only Agents

Not all agents support dynamic skill loading. For these environments, the **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)** file provides a compact, plain-text instruction set containing the essential always-on rules. This fallback ensures that even "instruction-only" agents—those unable to load [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) files or execute hooks—can still adhere to the core lazy senior dev philosophy.

## Command Interface and Usage

Users interact with the Ponytail architecture through slash commands defined in the skill files and surfaced via host plugins:

Activate Ponytail with default settings:

```text
/ponytail

```

Switch to minimal enforcement:

```text
/ponytail lite

```

Run a repository-wide optimization audit:

```text
/ponytail-audit

```

Display benchmark improvements:

```text
/ponytail-gain

```

Access the command reference:

```text
/ponytail-help

```

## Summary

The Ponytail architecture achieves its portable, intensity-controlled behavior through three integrated layers:

- **Markdown skills** in `skills/ponytail/` and related directories define behavioral logic using declarative instruction files
- **JavaScript hooks** in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js), [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js), and companion files enforce persistent rules and manage state across conversation turns
- **Adapter metadata** like [`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json) enables deployment across Claude, Codex, Gemini, and other LLM hosts without code changes
- **Fallback systems** including [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) ensure compatibility with restricted agent environments

Together, these components create a lightweight yet robust system for enforcing coding discipline that travels with the developer across different AI-powered tools.

## Frequently Asked Questions

### What is the difference between Ponytail skills and hooks?

**Skills are markdown files** that define behavioral instructions and command specifications, while **hooks are JavaScript files** that enforce those instructions at runtime. According to the Ponytail source code, skills live in the `skills/` directory (like [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md)) and describe what the system should do, whereas hooks in the `hooks/` directory (like [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js)) handle the technical implementation of injecting those rules into every LLM turn and tracking state persistence.

### How does Ponytail persist intensity levels across conversation turns?

The **[`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js)** component implements a small state machine that stores the current intensity level (`lite`, `full`, `ultra`, or `off`) between interactions. This hook runs continuously during the session and can be overridden by the `PONYTAIL_DEFAULT_MODE` environment variable or the `~/.config/ponytail/config.json` configuration file read by [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).

### Can Ponytail run on AI agents that do not support skill files?

Yes. Agents that cannot load markdown skill files or execute JavaScript hooks can still use Ponytail through **[`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)**, a compact plain-text file containing the essential always-on rules. This fallback mechanism ensures the "lazy senior dev" philosophy applies even in restricted environments that only accept direct text instructions.

### Where does Ponytail store user configuration settings?

Ponytail reads optional configuration from **`~/.config/ponytail/config.json`** or the `PONYTAIL_DEFAULT_MODE` environment variable, processed by **[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)**. These settings supply the default intensity mode when a new conversation begins, though users can override this dynamically using slash commands like `/ponytail lite` or `/ponytail ultra`.