# Where Is the Main Ponytail Ruleset Defined? Inside DietrichGebert/ponytail

> Discover where the main Ponytail ruleset is defined in the DietrichGebert/ponytail repository. Find the single source of truth for agent behavioral constraints in this hidden markdown file.

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

---

**The main Ponytail ruleset is defined in the hidden markdown file [`/.agents/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.agents/rules/ponytail.md), which serves as the single source of truth for all behavioral constraints injected into sub-agents.**

Ponytail is an AI coding assistant framework that enforces a "lazy senior dev" personality across agent interactions. Understanding where the main Ponytail ruleset is defined allows you to customize behavioral constraints without touching source code. The repository DietrichGebert/ponytail stores this configuration as a plain markdown file consumed by the **Ponytail MCP** and multiple runtime hooks.

## Where the Main Ponytail Ruleset Is Defined

### The Primary File at [`/.agents/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.agents/rules/ponytail.md)

The core definition resides in the hidden path [`/.agents/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.agents/rules/ponytail.md). This markdown file contains the `PONYTAIL MODE ACTIVE` banner and the complete behavioral constraints injected into every sub-agent. Because it uses plain markdown, you can edit the ruleset directly, and updates propagate instantly to every component that consumes it.

The file is organized into sections marked with intensity-level headers (`#lite`, `#full`, `#ultra`). These markers allow the runtime to filter content dynamically based on the selected intensity setting.

### WindSurf Compatibility Mirror

A duplicate of the main Ponytail ruleset exists at [`/.windsurf/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.windsurf/rules/ponytail.md) to support tooling that parses WindSurf rule files. While the `.agents` path serves as the primary source, this mirror ensures external editors and AI assistants can locate the configuration. Both files contain identical content and should be kept in sync.

## How the Ruleset Is Parsed and Filtered

### Intensity-Based Section Extraction

The **Ponytail MCP** component reads the ruleset using the `loadRuleset` function exported from [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js). This function filters the markdown by intensity before injection:

```javascript
import fs from 'fs';
import path from 'path';

const RULES_PATH = path.resolve(__dirname, '../../.agents/rules/ponytail.md');
export const loadRuleset = (intensity = 'full') => {
  const raw = fs.readFileSync(RULES_PATH, 'utf-8');
  // The file contains sections marked with #lite, #full, #ultra.
  const filtered = raw.split(/^#(lite|full|ultra)$/m)
                     .filter((_, i, arr) => arr[i - 1] === `#${intensity}`)[1];
  return filtered.trim();
};

```

The splitter regex `/^#(lite|full|ultra)$/m` targets section headers, allowing the function to return only the rules matching the requested intensity level (defaulting to `full`).

## Runtime Injection Mechanisms

### Sub-Agent Request Hooks

When Ponytail mode is toggled on, the `subagentHook` function in [`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js) intercepts each sub-agent request. It loads the filtered ruleset and prepends it to the prompt:

```javascript
import { loadRuleset } from '../ponytail-mcp/instructions.js';

export const subagentHook = async (request) => {
  if (request.context?.ponytailActive) {
    const rules = loadRuleset(request.context?.ponytailIntensity);
    request.prompt = `${rules}\n\n${request.prompt}`;
  }
  return request;
};

```

This ensures the behavioral constraints appear as hidden context before the user's actual query reaches the LLM.

### Hidden Session Context

For session initialization, the `activatePonytail` function in [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) emits the ruleset using `session.emitHiddenContext()`:

```javascript
import { loadRuleset } from '../ponytail-mcp/instructions.js';

export const activatePonytail = (session) => {
  const rules = loadRuleset(session.intensity);
  // Emit as hidden context so the LLM sees it but the UI stays clean
  session.emitHiddenContext(rules);
};

```

This method injects the main Ponytail ruleset without cluttering the user interface, maintaining the persona transparently.

## Architecture Overview

- **[`/.agents/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.agents/rules/ponytail.md)**: Where the main Ponytail ruleset is defined; the master markdown file with intensity sections.
- **[`/.windsurf/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.windsurf/rules/ponytail.md)**: Mirror location for WindSurf-compatible tooling.
- **[`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js)**: Exports `loadRuleset(intensity)` to read and filter the ruleset by intensity level.
- **[`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js)**: Implements `subagentHook` to prepend rules to outgoing sub-agent requests.
- **[`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js)**: Implements `activatePonytail(session)` to emit rules as hidden session context.

## Summary

- The **main Ponytail ruleset** is defined in [`/.agents/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.agents/rules/ponytail.md), a plain markdown file using intensity markers (`#lite`, `#full`, `#ultra`).
- The **`loadRuleset`** function in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) filters these sections based on the active intensity parameter before runtime injection.
- **Runtime hooks** in [`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js) and [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) consume this function to inject rules into agent prompts and hidden session context.
- The **WindSurf mirror** at [`/.windsurf/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.windsurf/rules/ponytail.md) provides alternative tool compatibility without duplicating logic.

## Frequently Asked Questions

### Where exactly is the main Ponytail ruleset file located?

The file is located at [`/.agents/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.agents/rules/ponytail.md) in the repository root. This path is hardcoded in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) as `RULES_PATH`. A secondary copy exists at [`/.windsurf/rules/ponytail.md`](https://github.com/DietrichGebert/ponytail/blob/main//.windsurf/rules/ponytail.md) for WindSurf tooling support.

### How does the system filter rules by intensity level?

The `loadRuleset` function splits the markdown on headers matching `/^#(lite|full|ultra)$/m`, then filters the resulting array to extract only the segment following the header that matches the requested intensity. This allows a single file to serve multiple configuration profiles.

### Which components read the ruleset file?

The [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) module reads the file directly and exports the parsing logic. This is imported by [`hooks/ponytail-subagent.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-subagent.js) (which prepends rules to sub-agent requests) and [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) (which emits rules as hidden context during session startup).

### Why is the ruleset stored as markdown instead of JSON?

Storing the main Ponytail ruleset as markdown allows direct editing of system prompts without escaping or structural constraints. The intensity headers provide a simple parsing mechanism that supports multi-line text blocks naturally, unlike JSON which would require complex escaping for multi-line prompts.