# Understanding Ponytail's Three-Layer Execution Model: Platform, Agent, and Application

> Explore Ponytail's execution model. Discover how Platform, Agent, and Application layers collaborate to enable LLM-assisted code changes for efficient development.

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

---

**Ponytail executes LLM-assisted code changes through three distinct layers—the Platform layer providing native primitives, the Agent layer injecting rules and skills, and the Application layer receiving minimal, validated diffs.**

The execution model of Ponytail across its three layers enforces strict separation of concerns between the host environment, the LLM assistant, and your production codebase. As implemented in the DietrichGebert/ponytail repository, this architecture implements the "lazy senior dev" principle by requiring the LLM to consult the "ladder" ruleset before generating any user-facing changes.

## The Platform (Native) Layer

The **Platform layer** defines the low-level primitives that already exist on the host system, preventing the reinvention of basic functionality. According to [`docs/platform-native.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/platform-native.md), this layer catalogs CSS cascade layers, native browser features, OS commands, and built-in Node utilities that the other layers can rely on.

By grounding decisions in native capabilities—such as using `<input type="date">` instead of importing a heavy date-picker library—Ponytail ensures the LLM respects platform boundaries before suggesting application changes.

## The Agent (LLM) Layer

The **Agent layer** controls how the LLM interacts with your codebase through an always-on ruleset defined in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md). This layer injects the "pony-tail" instructions into every LLM turn and exposes slash-commands including `/ponytail`, `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`, `/ponytail-gain`, and `/ponytail-help`.

Key responsibilities of this layer include:

- **Intensity Modes**: Controlling the strictness level via `lite`, `full`, `ultra`, or `off` settings
- **The Ladder**: Enforcing three mandatory questions the LLM must answer before writing code
- **Skill Registration**: Loading skill definitions from the `skills/` directory that bridge Agent logic with Application changes

When you activate Ponytail with `/ponytail full`, the Agent layer begins enforcing these constraints on every subsequent turn.

## The Application (User-Code) Layer

The **Application layer** represents the actual codebase you intend to modify. Located in your project directory (demonstrated in the `examples/` folder), this layer never receives direct writes from Ponytail. Instead, the system guides the LLM to produce the smallest, safest possible diff that respects both Platform primitives and Agent rules.

This layer is where the final output appears—minimal code changes that avoid unnecessary dependencies and follow YAGNI (You Aren't Gonna Need It) principles.

## How the Three Layers Execute During an LLM Turn

The execution model follows a predictable pipeline that moves downward through the layers:

1. **Agent Injection**: At the start of an LLM turn, the Agent layer injects the ruleset from [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) and exposes the `/ponytail` command interface.

2. **Platform Reasoning**: The LLM reasons using the native primitives cataloged in [`docs/platform-native.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/platform-native.md), ensuring it does not propose redundant functionality.

3. **Application Generation**: The LLM produces a minimal change targeting the Application layer, guided by the "ladder" questions and intensity mode.

4. **Validation**: Review and audit skills from the `skills/` directory validate that the change respects Platform primitives and Agent rules.

5. **Diff Application**: The validated change is applied to the user project, completing the execution cycle.

Because each layer maintains a single, well-defined responsibility, the system guarantees that no code reaches your Application layer without passing through the Platform and Agent validation gates.

## Practical Examples of Layer Interaction

Activate the Agent layer and set the intensity to `full` mode:

```markdown
/ponytail full

```

Utilize the Platform layer by relying on native browser capabilities instead of external libraries:

```html
<!-- ponytail: browser has one -->
<input type="date">

```

Run the audit skill to validate Application layer changes against the ladder rules:

```markdown
/ponytail-audit

```

## Summary

- The **Platform layer** documented in [`docs/platform-native.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/platform-native.md) provides native primitives including CSS cascade layers and browser APIs.
- The **Agent layer** defined in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) and the `skills/` directory injects the always-on ruleset and slash-commands like `/ponytail-review`.
- The **Application layer** represents the user codebase (as seen in `examples/`) where minimal diffs are ultimately applied.
- Execution flows from Agent ruleset injection → Platform primitive reasoning → Application diff generation → Audit skill validation.

## Frequently Asked Questions

### What files define the three layers in Ponytail?

The Platform layer is defined in [`docs/platform-native.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/platform-native.md), the Agent layer is configured in [`AGENTS.md`](https://github.com/DietrichGebert/ponytail/blob/main/AGENTS.md) with additional logic in the `skills/` directory, and the Application layer is your own project code, with examples shown in the `examples/` folder.

### How does the Agent layer control LLM behavior?

The Agent layer injects an always-on ruleset called the "ladder" that forces the LLM to ask three questions before writing code. It also manages intensity modes (`lite`, `full`, `ultra`, `off`) and registers skills such as `/ponytail-audit` to validate output.

### Why does Ponytail separate Platform primitives from Application code?

This separation prevents the LLM from violating YAGNI principles by suggesting unnecessary libraries when native alternatives exist. By cataloging available primitives in [`docs/platform-native.md`](https://github.com/DietrichGebert/ponytail/blob/main/docs/platform-native.md), the system ensures the LLM reasons about what the host already provides before proposing Application changes.

### Where are the review and audit skills implemented?

The skills are implemented in the `skills/` directory at the repository root. These files define the behavior of commands like `/ponytail-review`, `/ponytail-audit`, `/ponytail-debt`, and `/ponytail-gain` that validate Application layer changes against the Agent layer ruleset.