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

The main Ponytail ruleset is defined in the hidden markdown file /.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

The core definition resides in the hidden path /.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 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. This function filters the markdown by intensity before injection:

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 intercepts each sub-agent request. It loads the filtered ruleset and prepends it to the prompt:

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 emits the ruleset using session.emitHiddenContext():

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: Where the main Ponytail ruleset is defined; the master markdown file with intensity sections.
• /.windsurf/rules/ponytail.md: Mirror location for WindSurf-compatible tooling.
• ponytail-mcp/instructions.js: Exports loadRuleset(intensity) to read and filter the ruleset by intensity level.
• hooks/ponytail-subagent.js: Implements subagentHook to prepend rules to outgoing sub-agent requests.
• 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, a plain markdown file using intensity markers (#lite, #full, #ultra).
• The loadRuleset function in ponytail-mcp/instructions.js filters these sections based on the active intensity parameter before runtime injection.
• Runtime hooks in hooks/ponytail-subagent.js and 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 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 in the repository root. This path is hardcoded in ponytail-mcp/instructions.js as RULES_PATH. A secondary copy exists at /.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 module reads the file directly and exports the parsing logic. This is imported by hooks/ponytail-subagent.js (which prepends rules to sub-agent requests) and 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.

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