How to Contribute to the Ponytail Project: A Complete Developer's Guide

Contributing to Ponytail requires modifying skills, hooks, or adapter manifests, then running the rule-copy checker and Jest test suite to ensure all host-specific files remain synchronized across the four-layer architecture.

The Ponytail project by DietrichGebert is an agent-portable plugin that supplies "lazy senior dev" skills to AI coding assistants. When you contribute to the Ponytail project, you are modifying a multi-layered system that spans markdown-based skills, JavaScript hooks, and JSON/YAML manifests for various AI hosts including Claude, Codex, OpenCode, and Gemini.

Understand the Four-Layer Architecture

Ponytail's codebase is organized into four distinct layers. Every contribution must maintain consistency across all layers to ensure portability across AI agents.

The Skills Layer

The skills layer contains markdown-based instructions that drive agent behavior. The core implementation lives in skills/ponytail/SKILL.md, with companion files for specialized behaviors like ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, and ponytail-help. These files define the actual capabilities agents expose to users.

The Hooks Layer

The hooks layer provides host-specific lifecycle injections. Key files include hooks/ponytail-runtime.js (which injects the ruleset each turn) and hooks/ponytail-activate.js. These JavaScript files manage how skills activate during an agent's execution cycle.

The Adapters and Plugins Layer

The adapters layer exposes skills and hooks to specific hosts through manifest files. This includes plugin.yaml, plugin.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, and .grok-plugin/marketplace.json. Each manifest maps the core functionality to host-specific APIs.

The Build and Validation Layer

The build layer ensures repository consistency through automation. The scripts/check-rule-copies.js utility verifies that host-specific rule files (like .cursor/rules/ponytail.mdc and .windsurf/rules/ponytail.md) match the canonical AGENTS.md. The scripts/build-openclaw-skills.js generator creates OpenClaw skill packages from the skills/ directory.

Step-by-Step Contribution Workflow

Follow this sequence when submitting changes to the DietrichGebert/ponytail repository:

1. Fork and Clone the Repository

Start with a clean local environment:

git clone https://github.com/<your-username>/ponytail.git
cd ponytail

2. Install Dependencies

Install the development toolchain:

npm ci

3. Edit Source Files

Make your changes to the appropriate layer. If adding a new skill, create the directory under skills/ with a SKILL.md file. If modifying activation logic, edit files in hooks/.

4. Validate Rule Copies

Run the consistency checker to verify that all host-specific rule files match AGENTS.md:

node scripts/check-rule-copies.js

This script exits with code 0 if all copies are up-to-date. Use the --fail-on-diff flag in CI environments to abort builds if any host rule diverges from the canonical source.

5. Run the Test Suite

Execute the comprehensive Jest test suite covering skill loading, hook execution, and CLI adapters:

npm test

6. Rebuild OpenClaw Skills

If you modified or added a skill, regenerate the OpenClaw artifacts:

node scripts/build-openclaw-skills.js

For targeted rebuilds during development, use the --only flag:

node scripts/build-openclaw-skills.js --only ponytail-newfeature

7. Update Documentation

Synchronize README.md, docs/*.md, and AGENTS.md so downstream agents receive updated instructions. If adding a new skill, list it in the Portable Behavior table of docs/agent-portability.md.

Key Files for Contributors

Understanding these critical files accelerates your contribution process:

• AGENTS.md – The canonical compact rule set that every host-specific configuration copies. Located at the repository root.
• skills/ponytail/SKILL.md – Core skill implementation defining the "lazy senior dev" behavior.
• hooks/ponytail-runtime.js – Runtime hook injecting the ruleset into each agent turn.
• scripts/check-rule-copies.js – Validation script ensuring synchronization between AGENTS.md and host-specific rule files like .cursor/rules/ponytail.mdc.
• package.json – Defines npm scripts, Jest configuration, and development dependencies.

Practical Code Examples

Registering a new skill in the Claude plugin manifest:

{
  "name": "ponytail-newfeature",
  "description": "A new skill that does X",
  "hooks": ["hooks/ponytail-runtime.js"],
  "skills": ["skills/ponytail-newfeature/SKILL.md"]
}

Defining a new command in TOML format:

# commands/ponytail-newfeature.toml

name = "ponytail-newfeature"
description = "Demo command showing how to wire a new skill"
mode = "full"

Validating rule copies with strict mode:

node scripts/check-rule-copies.js --fail-on-diff

Summary

• Four layers require synchronization: Skills (markdown instructions), Hooks (JavaScript lifecycle), Adapters (JSON/YAML manifests), and Build Scripts (validation and generation).
• Always run validation: Execute node scripts/check-rule-copies.js after editing to ensure host-specific rules match AGENTS.md.
• Test thoroughly: Run npm test to verify skill loading, hook execution, and OpenClaw generation.
• Rebuild artifacts: Use scripts/build-openclaw-skills.js when modifying skills to regenerate distribution packages.
• Document changes: Update README.md, AGENTS.md, and docs/agent-portability.md to reflect new capabilities.

Frequently Asked Questions

Do I need to manually update all host-specific rule files?

No. You edit the canonical AGENTS.md file, then run node scripts/check-rule-copies.js to verify that host-specific files (like .cursor/rules/ponytail.mdc and .windsurf/rules/ponytail.md) match. If they diverge, the script reports which files need synchronization.

What happens if I forget to run the rule-copy checker?

Your pull request will likely fail CI validation. The check-rule-copies.js script is designed to exit with a non-zero status when it detects differences between AGENTS.md and host-specific copies, preventing out-of-sync configurations from merging.

Can I contribute a new skill without modifying hooks?

Yes, if the skill uses existing activation patterns defined in hooks/ponytail-runtime.js. However, you must register the skill in the appropriate adapter manifests (such as .claude-plugin/plugin.json or plugin.yaml) and add the skill path to the Portable Behavior table in docs/agent-portability.md.

How do I test my changes against multiple AI hosts?

Run the full Jest test suite with npm test to validate logic across all supported hosts. For manual testing, install the plugin in each target environment (Claude Desktop, Codex CLI, etc.) using the respective manifest files in your local clone, then verify that commands appear in the agent's interface.

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