What Is the Purpose of the AGENTS.md File in Ponytail?

The AGENTS.md file serves as the canonical, always-on rule set that defines Ponytail's "lazy senior dev mode" across all supported AI assistant platforms.

The primary purpose of the AGENTS.md file in the DietrichGebert/ponytail repository is to establish a single, human-readable source of truth that governs how AI coding agents interact with your codebase. This compact markdown document drives Ponytail's philosophy of efficient, reuse-oriented development consistently across multiple platforms without requiring duplicate configurations.

Core Functions of AGENTS.md

Defining the "Lazy Senior Dev Mode"

At the heart of AGENTS.md lies the "lazy senior dev mode"—a concise checklist that instructs agents to work efficiently by following principles like YAGNI (You Aren't Gonna Need It), reusing existing code, and preferring the standard library over new dependencies. According to the source code at AGENTS.md#L1-L13, these rules establish a mindset where agents avoid over-engineering and leverage what's already available in the project.

Providing Always-On Context

Unlike plugin-specific configurations that require explicit installation, AGENTS.md operates as an always-on resource that many agents load automatically at startup. For instance, OpenCode loads AGENTS.md automatically without additional configuration, as documented in README.md#L178-L179. Similarly, the Gemini CLI points its contextFileName parameter directly to this file in gemini-extension.json#L5, ensuring the rules inject as persistent context for every interaction.

Serving as the Source of Truth

The file acts as the single source of truth for all rule variations throughout the repository. Copies of these guidelines appear in locations like .qoder/rules/ponytail.md and skill-specific SKILL.md files. The helper script scripts/check-rule-copies.js#L15-L31 verifies that these distributed copies remain identical to the canonical AGENTS.md, preventing configuration drift.

Integration Patterns Across AI Platforms

Gemini CLI Configuration

The Gemini extension manifest demonstrates how platforms reference the file directly:

{
  "name": "pony‑tail‑gemini",
  "contextFileName": "AGENTS.md",
  "commands": ["commands/*.toml"],
  "skills": ["skills/"]
}

This configuration tells the Gemini CLI to inject the contents of AGENTS.md as always-on context for every session.

Node.js Loading Pattern

Agent integrations typically read the file using standard filesystem operations:

const fs = require('fs');
const path = require('path');

// Ponytail agents typically read the file from the repo root
const agentsPath = path.join(__dirname, '..', 'AGENTS.md');
const rules = fs.readFileSync(agentsPath, 'utf8');

console.log('Loaded Ponytail rules:\n', rules);

This pattern appears in both the Qoder plugin and the check-rule-copies.js script.

Synchronization and Maintenance

Maintaining consistency requires automated verification. The scripts/check-rule-copies.js utility compares the compact rule text in derivative files against the canonical source:

// scripts/check-rule-copies.js (excerpt)
const agents = read('AGENTS.md');
const sources = [
  ['skills/ponytail/SKILL.md', skill],
  ['AGENTS.md', agents],
];
sources.forEach(([relPath, content]) => {
  if (content !== agents) {
    console.error(`${relPath} drifted from AGENTS.md`);
  }
});

As implemented in DietrichGebert/ponytail, this ensures that platforms like Qoder, CodeWhale, Swival, VS Code Codex, and JetBrains Junie all operate from identical instructions without duplicating logic, as outlined in docs/agent-portability.md#L17-L33.

Summary

• AGENTS.md functions as the canonical guideline document for the Ponytail ecosystem, establishing a unified "lazy senior dev mode" across all supported agents.
• The file provides always-on context that platforms like OpenCode and Gemini CLI automatically load at startup, eliminating setup friction.
• It serves as the single source of truth for rule copies distributed throughout the repository in paths like .qoder/rules/ponytail.md.
• A verification script ensures that derivative files remain synchronized with the master file, maintaining consistency across Qoder, CodeWhale, Swival, VS Code Codex, and JetBrains Junie integrations.

Frequently Asked Questions

What is the "lazy senior dev mode" in Ponytail?

The "lazy senior dev mode" is a development philosophy encoded in AGENTS.md that instructs AI agents to write efficient, maintainable code by following principles like YAGNI, reusing existing implementations, and preferring standard library solutions over new dependencies. This approach minimizes code bloat and leverages existing project assets.

Which AI platforms automatically load AGENTS.md?

OpenCode automatically loads AGENTS.md without requiring plugin installation, while the Gemini CLI references it explicitly through the contextFileName field in gemini-extension.json. The file also supports Qoder, CodeWhale, Swival, VS Code Codex, and JetBrains Junie through manual integration patterns.

How does Ponytail ensure rule copies stay synchronized?

The repository includes scripts/check-rule-copies.js#L15-L31, which runs validation checks to ensure that copies in skills/ponytail/SKILL.md and .qoder/rules/ponytail.md remain identical to the canonical AGENTS.md file. This automated verification prevents configuration drift across the ecosystem.

Can I use AGENTS.md with custom agent integrations?

Yes, because AGENTS.md is a human-readable markdown file located at the repository root, any new agent integration can reference it directly as documented in docs/agent-portability.md#L17-L33, obtaining the same instruction set without duplicating logic or creating platform-specific configurations.

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