# Ponytail Project Architecture: A Three-Layer Plugin Framework for AI Coding Assistants

> Discover the Ponytail Project Architecture a three-layer plugin framework for AI coding assistants. Learn how it ensures consistent AI behavior across multiple platforms like Claude Code Gemini and Codex.

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

---

**Ponytail is a lightweight, rules-as-code framework consisting of three tightly coupled layers—a central ruleset file ([`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)), host-specific JSON lifecycle hooks, and Markdown-defined skill packages—that enable consistent AI behavior across Claude Code, Codex, Gemini, and other coding assistants.**

The Ponytail project (DietrichGebert/ponytail) solves a fragmentation problem: every AI coding assistant speaks a different dialect, yet developers want the same "lazy senior dev" principles applied everywhere. Rather than building platform-specific plugins, Ponytail treats **rules as code**—human-readable text files that any host can ingest. The entire framework ships in approximately 200 lines of code while supporting dozens of platforms.

## The Three-Layer Architecture

Ponytail's design deliberately minimizes moving parts. Each layer has a single responsibility and communicates through simple file-based contracts.

### Layer 1: Ruleset / Command Core

The foundation is [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md), a plain-text rule file that lives at the repository root. This file contains:

- The **"lazy senior dev" decision ladder**: YAGNI → reuse → stdlib → native → deps → one-liner
- Slash command definitions (`/ponytail`, `/ponytail-review`, `/ponytail-audit`, etc.)
- Mode control instructions for `lite`, `full`, `ultra`, and `off` levels

Every host reads this file on session startup and injects its contents into every LLM turn. This guarantees consistent behavior regardless of which AI assistant a developer uses.

```text

# From AGENTS.md

/ponytail [level]     - Set or query the current mode (lite/full/ultra/off)
/ponytail-review      - Review current diff against lazy principles
/ponytail-audit       - Full codebase audit for technical debt

```

The ruleset is intentionally **host-agnostic**—no platform-specific syntax appears in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md). This single source of truth eliminates drift between implementations.

### Layer 2: Lifecycle Hooks

Host integration happens through small JSON bundles in `hooks/`. Each file describes how that specific platform should load and activate the ruleset:

| Hook File | Target Platform | Activation Method |
|-----------|---------------|-------------------|
| [`hooks/claude-code-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-code-hooks.json) | Claude Code | [`.claude/AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/.claude/AGENTS.md) auto-load |
| [`hooks/codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/codex-hooks.json) | GitHub Codex | `@ponytail` skill invocation |
| [`hooks/gemini-extension.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/gemini-extension.json) | Gemini CLI | Extension manifest registration |

These hooks perform two critical functions on every LLM turn:

1. **Auto-load** the ruleset from [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)
2. **Expose commands** as native skills (syntax varies by host)

For Codex, commands become `@ponytail-review`. For Cursor or Windsurf, they become `$ponytail-review`. The hook translates the universal slash command into the host's native invocation style.

### Layer 3: Skills Package

Six Markdown-defined skills contain the actual implementation logic. Each skill is a self-contained directory with a [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) file:

| Skill | Purpose | Location |
|-------|---------|----------|
| `ponytail` | Mode control and status | [`skills/ponytail/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) |
| `ponytail-review` | Diff review against lazy principles | [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md) |
| `ponytail-audit` | Full codebase audit | [`skills/ponytail-audit/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-audit/SKILL.md) |
| `ponytail-debt` | Technical debt quantification | [`skills/ponytail-debt/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-debt/SKILL.md) |
| `ponytail-gain` | Performance scoreboard display | [`skills/ponytail-gain/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-gain/SKILL.md) |
| `ponytail-help` | Documentation and examples | [`skills/ponytail-help/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-help/SKILL.md) |

Each [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/SKILL.md) contains:

- A prompt template for the LLM
- Default response patterns
- Optional post-processing instructions

Build scripts ([`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js)) generate platform-specific shims from these Markdown sources, enabling publication to npm, ClawHub, Qoder plugins, and other marketplaces without code duplication.

## How the Architecture Works at Runtime

Understanding the Ponytail project architecture requires seeing how the layers interact during actual use.

### Step 1: Rule Injection

When a developer starts a session, the host's hook file triggers:

```json
// hooks/claude-code-hooks.json (simplified)
{
  "name": "ponytail",
  "ruleset": "../AGENTS.md",
  "inject_on_every_turn": true,
  "commands": ["/ponytail", "/ponytail-review", "/ponytail-audit"]
}

```

The host reads [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) and prepends its contents to every subsequent LLM request. This **"always-on" injection** ensures the lazy dev ladder is never forgotten, even in long conversations.

### Step 2: Command Dispatch

When the developer types `/ponytail-review`, the host:

1. Recognizes the slash command from the ruleset
2. Maps it to the appropriate skill file
3. Loads [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail-review/SKILL.md)

The dispatch mechanism varies by platform—Claude Code uses native slash commands, Codex uses `@` mentions, others use `$` prefixes—but all converge on the same skill definition.

### Step 3: Skill Execution

The skill's Markdown contains the actual prompt engineering:

```markdown
<!-- skills/ponytail-review/SKILL.md (excerpt) -->

# ponytail-review

## Prompt

Review the provided diff against these principles:
1. Can this be deleted instead of modified? (YAGNI)
2. Does standard library already provide this?
3. Is a native browser/Node API sufficient?
4. Would a one-liner replace this dependency?

## Output format

- DELETE: <lines> - <reason>
- SIMPLIFY: <lines> - <replacement>
- APPROVE: <lines> - <rationale>

```

The host sends this template to the LLM with context (current diff), receives the response, and optionally applies a JavaScript shim for formatting.

### Step 4: Mode Persistence

The `/ponytail` command accepts a level parameter. The requested mode persists in:

- `~/.config/ponytail/config.json` (user preference file)
- `PONYTAIL_DEFAULT_MODE` environment variable (session override)

On every turn, the rule injector reads this value and adjusts the prompt accordingly—`lite` for minimal commentary, `ultra` for aggressive simplification, `off` for passthrough.

## Supporting Infrastructure

Beyond the three core layers, the repository includes tooling that maintains architectural integrity:

### Build and Sync Scripts

[`scripts/check-rule-copies.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/check-rule-copies.js) ensures that [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) content remains synchronized across all host-specific rule copies. If a platform requires a vendor-formatted version, this script detects divergence and fails CI.

[`scripts/build-openclaw-skills.js`](https://github.com/DietrichGebert/ponytail/blob/main/scripts/build-openclaw-skills.js) generates Node-compatible shims from the Markdown skill definitions, enabling npm publication without manual copying.

### Benchmark Suite

[`benchmarks/README.md`](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/README.md) documents a measurement framework that tracks:

- Lines of code eliminated
- Token consumption reduction
- Cost savings per task
- Time-to-completion improvements

This validates that the architectural simplicity translates to measurable developer productivity gains.

### Example Applications

[`examples/README.md`](https://github.com/DietrichGebert/ponytail/blob/main/examples/README.md) contains runnable demonstrations of Ponytail's minimal output philosophy—such as generating `<input type="date">` instead of importing a date-picker library.

## Extending the Architecture

Adding support for a new AI assistant requires only:

1. **Create a hook file**: `hooks/<new-platform>-hooks.json` that points to [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)
2. **Define command mapping**: Specify how slash commands translate to the host's skill syntax
3. **Optionally republish skills**: Run build scripts to generate platform-specific packages

No changes to [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) or the skill definitions are necessary. This **host-agnostic core** is why Ponytail achieves broad compatibility with minimal code.

## Summary

- **Ponytail's architecture is rules-as-code**: semantics in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md), activation in JSON hooks, behavior in Markdown skills
- **Three layers operate independently**: ruleset, lifecycle hooks, and skill packages communicate through file-based contracts
- **Single source of truth**: [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) ensures consistent "lazy senior dev" principles across all platforms
- **Minimal footprint**: ~200 LOC supports Claude Code, Codex, Gemini, Cursor, Windsurf, Qoder, and others
- **Extensible by design**: new hosts need only a hook file, not core logic changes

## Frequently Asked Questions

### What makes Ponytail different from other AI coding frameworks?

Most frameworks build platform-specific plugins with duplicated logic. Ponytail inverts this: one human-readable ruleset ([`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md)) feeds multiple hosts through thin JSON adapters. The skills themselves are Markdown files, not compiled code, making behavior transparent and version-controllable.

### How does [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) get loaded into every LLM conversation?

The hook files ([`hooks/claude-code-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-code-hooks.json), etc.) declare `inject_on_every_turn: true` (or equivalent per-platform). The host's plugin system reads this directive and prepends the ruleset content to each prompt. This happens automatically—developers don't manually copy-paste instructions.

### Can I modify Ponytail's behavior without forking the repository?

Yes. The `~/.config/ponytail/config.json` file and `PONYTAIL_DEFAULT_MODE` environment variable control mode selection. For deeper customization, you can override specific skill files in your local clone—the hook files will pick up changes in `skills/*/SKILL.md` on the next session start.