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

Ponytail is a lightweight, rules-as-code framework consisting of three tightly coupled layers—a central ruleset file (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, 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.

# 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. 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	Claude Code	.claude/AGENTS.md auto-load
hooks/codex-hooks.json	GitHub Codex	@ponytail skill invocation
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
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 file:

Skill	Purpose	Location
ponytail	Mode control and status	skills/ponytail/SKILL.md
ponytail-review	Diff review against lazy principles	skills/ponytail-review/SKILL.md
ponytail-audit	Full codebase audit	skills/ponytail-audit/SKILL.md
ponytail-debt	Technical debt quantification	skills/ponytail-debt/SKILL.md
ponytail-gain	Performance scoreboard display	skills/ponytail-gain/SKILL.md
ponytail-help	Documentation and examples	skills/ponytail-help/SKILL.md

Each SKILL.md contains:

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

Build scripts (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:

// 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 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

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:

<!-- 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 ensures that 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 generates Node-compatible shims from the Markdown skill definitions, enabling npm publication without manual copying.

Benchmark Suite

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 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
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 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, 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 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) 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 get loaded into every LLM conversation?

The hook files (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.

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