\n\nPonytail Balanced is a compatibility-focused fork of\n[Ponytail](https://github.com/DietrichGebert/ponytail). It keeps the useful\nreuse-first discipline while fixing the failure mode reported most often about\naggressive minimalism: treating explicit requirements, repository contracts,\nor verification as optional because a shorter diff exists.\n\nThis fork is still a preview. It has not independently reproduced the upstream\nperformance benchmark, so it makes no percentage, cost, speed, or “100% safe”\nclaim. See [Fork design notes](docs/balanced-fork.md).\n\n## What changed\n\n- Explicit requirements and acceptance criteria outrank minimalism.\n- Repository conventions, public types/APIs, persistence, auth, validation,\n accessibility, data integrity, and relevant tests are protected scope.\n- `lite`, `full`, and `ultra` now have different policies instead of near-identical\n prompt text; `lite` is the safer default.\n- Mode changes inject the selected policy immediately on supported hook hosts.\n- Runtime state is project-scoped by default, avoiding mode leakage between repos.\n- Review and audit findings require reference evidence; uncertain candidates are\n reported as `inspect:`, not presented as safe deletions.\n- Hermes and Node-based hosts inject the same compact policy rather than the full\n skill document on every turn.\n\n## Decision order\n\nThe agent applies this priority order:\n\n```text\n1. Explicit requirements and acceptance criteria\n2. Repository contracts and established conventions\n3. Correctness, security, accessibility, and data integrity\n4. Reuse code already present in the repository\n5. Prefer standard-library, native, or installed facilities\n6. Add the smallest complete implementation\n```\n\nSimplicity decides *how* to build requested behavior. It does not silently decide\nthat requested behavior no longer matters.\n\n## Modes\n\n| Mode | Intended behavior |\n|---|---|\n| `lite` | Safe default. Honor the requested design and make only local, low-risk simplifications. |\n| `full` | Trace the affected flow end to end and implement the smallest complete interpretation. |\n| `ultra` | Seek deletion and reject speculation, but require whole-tree reference evidence and preserve explicit contracts. |\n| `off` | Do not inject Ponytail guidance. |\n\nSet the default with `PONYTAIL_DEFAULT_MODE=lite|full|ultra|off`, or:\n\n```json\n{ \"defaultMode\": \"lite\" }\n```\n\nSave that as `~/.config/ponytail/config.json` on macOS/Linux or\n`%APPDATA%\\ponytail\\config.json` on Windows. Resolution is environment variable,\nthen config file, then `lite`.\n\nRuntime flags are scoped to the current project. Set\n`PONYTAIL_STATE_SCOPE=legacy` only when compatibility with the old shared flag\npath is required.\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `/ponytail [lite \\| full \\| ultra \\| off]` | Change intensity; no argument activates the configured default (or Lite if configured off). |\n| `/ponytail status` | Report the current/configured mode without switching. |\n| `/ponytail-review` | Review the current diff; deletion findings require evidence. |\n| `/ponytail-audit` | Audit the repository and distinguish verified from unverified candidates. |\n| `/ponytail-debt` | Collect deliberate `ponytail:` shortcuts and upgrade paths. |\n| `/ponytail-gain` | Show the bundled benchmark report with its provenance. |\n| `/ponytail-help` | Show the quick reference. |\n\nSay `stop ponytail` or `normal mode` to disable it. Codex exposes skills with\n`$` syntax, for example `$ponytail-review`.\n\n## Install\n\nClone directly:\n\n```bash\ngit clone https://github.com/powerzxx/ponytail-balanced.git\n```\n\nClaude Code:\n\n```text\n/plugin marketplace add powerzxx/ponytail-balanced\n/plugin install ponytail-balanced@ponytail-balanced\n```\n\nCodex (after adding the marketplace, open Codex and install from `/plugins`):\n\n```bash\ncodex plugin marketplace add powerzxx/ponytail-balanced\ncodex\n```\n\n```text\n/plugins\n```\n\nSelect `ponytail-balanced`, install it, and start a new session. The strict\nCodex manifest loads the bundled skills; invoke them with `$ponytail`,\n`$ponytail-review`, and the related skill names. Automatic lifecycle activation\nis available in the Claude plugin and is not claimed by the Codex package.\n\nGitHub Copilot CLI:\n\n```bash\ncopilot plugin marketplace add powerzxx/ponytail-balanced\ncopilot plugin install ponytail-balanced@ponytail-balanced\n```\n\nOther remote installs:\n\n```bash\npi install git:github.com/powerzxx/ponytail-balanced\ngemini extensions install https://github.com/powerzxx/ponytail-balanced\nhermes plugins install powerzxx/ponytail-balanced --enable\n```\n\nFor OpenCode, add the checkout's absolute\n`.opencode/plugins/ponytail.mjs` path to the `plugin` array in `opencode.json`.\nNo npm package for this fork is claimed or required.\n\nCursor, Windsurf, Cline, Copilot Chat, Kiro, and Qoder can copy the matching\nrule file from the checkout. See [Agent portability](docs/agent-portability.md).\nFor instruction-only use, copy [AGENTS.md](AGENTS.md) into a project.\n\n## Host behavior\n\nThe compact policy builder in `hooks/ponytail-instructions.js` is the canonical\nNode implementation. Claude hooks, Pi, OpenCode, and the MCP server reuse it.\nHermes carries a compact Python equivalent and has parity tests. Qoder receives the\nactive mode through its prompt hook. Codex loads the bundled skills; Claude owns\nthe shared lifecycle hook map. Generated OpenClaw skills are rebuilt from `skills/`.\n\nHosts that only consume repository instruction files receive the balanced priority\norder but may not support runtime mode switching.\n\n## Review output safety\n\n`ponytail-review` and `ponytail-audit` use two distinct labels:\n\n- `delete:` — the repository was searched and the finding has enough evidence to\n recommend removal.\n- `inspect:` — the candidate may be unnecessary, but dynamic registration, public\n consumption, or other evidence is incomplete.\n\nNeither skill should flag required persistence, auth, validation, types, public\ncontracts, accessibility, or tests merely because deleting them shortens code.\n\n## Upstream benchmark provenance\n\nThe files under `benchmarks/` and the historical numbers in them were inherited\nfrom upstream Ponytail. They are useful as reproducible prior work, not as evidence\nfor this fork. The Balanced prompt changes the policy and default mode, so its\nquality, code-size, token, cost, and latency effects need a new controlled run.\n\nUntil that run exists, the honest project claim is narrower: the fork has automated\nregression checks for policy separation, protected requirements, mode switching,\nscoped state, adapters, and generated artifacts.\n\nRun the Balanced-specific size/correctness and behavior harnesses with:\n\n```bash\nnpx promptfoo@latest eval -c benchmarks/promptfooconfig.balanced.yaml --repeat 10\nnpx promptfoo@latest eval -c benchmarks/behavior.yaml --repeat 10\n```\n\nSee [Benchmark provenance and reproduction](benchmarks/README.md) before publishing\nany result.\n\n## Development\n\n```bash\nnpm install\npython -m pip install pandas\nnpm test\nnode scripts/check-rule-copies.js\nnode scripts/build-openclaw-skills.js\n```\n\nPi and MCP packages have their own tests:\n\n```bash\nnpm test --prefix pi-extension\nnpm test --prefix ponytail-mcp\n```\n\nThe correctness benchmark spawns Python for email and CSV checks, and its CSV cases\nrequire `pandas`.\n\n## Status and limitations\n\n- Balanced-specific empirical benchmarks are pending.\n- Project scoping uses a stable hash of the resolved project root; moving a project\n intentionally creates a new scope.\n- Instruction-only hosts cannot provide the same mode lifecycle as hook hosts.\n- Hermes mode commands are associated with sessions in event order because its\n command-handler API does not expose a session identifier.\n\n## Attribution and license\n\nBased on [Ponytail](https://github.com/DietrichGebert/ponytail) by Dietrich Gebert.\nBalanced changes are maintained separately and are not claims about or releases of\nthe upstream project.\n\n[MIT](LICENSE)\n",
"bytes": 8643,
"sha": "af256d8a33c497d191e5f95c63e55b6c65336751fb763a412d013cd1497907a7",
"repo_slug": "powerzxx/ponytail-balanced",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_powerzxx_ponytail_balanced_f712bb1f/readme"
}
![\"Ponytail](\"assets/logo-dark.png\"){kind=logo}
\n ![\"Preview\"](\"https://img.shields.io/badge/status-preview-f59e0b?style=flat-square\"){kind=icon}
![\"MIT](\"https://img.shields.io/badge/license-MIT-111111?style=flat-square\"){kind=icon}