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

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 – Defines the main /ponytail command and implements the ladder logic (YAGNI → stdlib → native → dependency → one-liner)
• skills/ponytail-review/SKILL.md – Powers the /ponytail-review diff-analysis utility
• skills/ponytail-audit/SKILL.md – Drives the /ponytail-audit repository-wide over-engineering scanner
• skills/ponytail-debt/SKILL.md, skills/ponytail-gain/SKILL.md, and 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 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, 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 – Runs on the first user prompt to toggle Ponytail on or off and prints the status line in supported hosts
• 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 (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 – Registration manifest for Claude and Codex implementations
• hooks/qoder-hooks.json – Hook mappings for Qoder agents
• 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 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 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:

/ponytail

Switch to minimal enforcement:

/ponytail lite

Run a repository-wide optimization audit:

/ponytail-audit

Display benchmark improvements:

/ponytail-gain

Access the command reference:

/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, 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 enables deployment across Claude, Codex, Gemini, and other LLM hosts without code changes
• Fallback systems including 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) and describe what the system should do, whereas hooks in the hooks/ directory (like 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 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.

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, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}