ponytail-balanced
Complete explicit requirements and repository contracts, then remove accidental complexity.
Open source Open in the app JSON README (API)
About
Complete explicit requirements and repository contracts, then remove accidental complexity.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- powerzxx
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.1
- Stars
- 1
- Last push
- 2026-08-07T09:52:19Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
powerzxx/ponytail-balanced
README
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png">
<img src="assets/logo.png" width="220" alt="Ponytail Balanced">
</picture>
</p>
<h1 align="center">Ponytail Balanced</h1>
<p align="center">
<em>Less accidental complexity. Complete requirements.</em>
</p>
<p align="center">
<img src="https://img.shields.io/badge/status-preview-f59e0b?style=flat-square" alt="Preview">
<img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
</p>
<p align="center">
<a href="README.zh-CN.md">简体中文</a> ·
<a href="README.es.md">Español</a> ·
<a href="README.ko.md">한국어</a>
</p>
Ponytail Balanced is a compatibility-focused fork of
[Ponytail](https://github.com/DietrichGebert/ponytail). It keeps the useful
reuse-first discipline while fixing the failure mode reported most often about
aggressive minimalism: treating explicit requirements, repository contracts,
or verification as optional because a shorter diff exists.
This fork is still a preview. It has not independently reproduced the upstream
performance benchmark, so it makes no percentage, cost, speed, or “100% safe”
claim. See [Fork design notes](docs/balanced-fork.md).
## What changed
- Explicit requirements and acceptance criteria outrank minimalism.
- Repository conventions, public types/APIs, persistence, auth, validation,
accessibility, data integrity, and relevant tests are protected scope.
- `lite`, `full`, and `ultra` now have different policies instead of near-identical
prompt text; `lite` is the safer default.
- Mode changes inject the selected policy immediately on supported hook hosts.
- Runtime state is project-scoped by default, avoiding mode leakage between repos.
- Review and audit findings require reference evidence; uncertain candidates are
reported as `inspect:`, not presented as safe deletions.
- Hermes and Node-based hosts inject the same compact policy rather than the full
skill document on every turn.
## Decision order
The agent applies this priority order:
```text
1. Explicit requirements and acceptance criteria
2. Repository contracts and established conventions
3. Correctness, security, accessibility, and data integrity
4. Reuse code already present in the repository
5. Prefer standard-library, native, or installed facilities
6. Add the smallest complete implementation
```
Simplicity decides *how* to build requested behavior. It does not silently decide
that requested behavior no longer matters.
## Modes
| Mode | Intended behavior |
|---|---|
| `lite` | Safe default. Honor the requested design and make only local, low-risk simplifications. |
| `full` | Trace the affected flow end to end and implement the smallest complete interpretation. |
| `ultra` | Seek deletion and reject speculation, but require whole-tree reference evidence and preserve explicit contracts. |
| `off` | Do not inject Ponytail guidance. |
Set the default with `PONYTAIL_DEFAULT_MODE=lite|full|ultra|off`, or:
```json
{ "defaultMode": "lite" }
```
Save that as `~/.config/ponytail/config.json` on macOS/Linux or
`%APPDATA%\ponytail\config.json` on Windows. Resolution is environment variable,
then config file, then `lite`.
Runtime flags are scoped to the current project. Set
`PONYTAIL_STATE_SCOPE=legacy` only when compatibility with the old shared flag
path is required.
## Commands
| Command | What it does |
|---|---|
| `/ponytail [lite \| full \| ultra \| off]` | Change intensity; no argument activates the configured default (or Lite if configured off). |
| `/ponytail status` | Report the current/configured mode without switching. |
| `/ponytail-review` | Review the current diff; deletion findings require evidence. |
| `/ponytail-audit` | Audit the repository and distinguish verified from unverified candidates. |
| `/ponytail-debt` | Collect deliberate `ponytail:` shortcuts and upgrade paths. |
| `/ponytail-gain` | Show the bundled benchmark report with its provenance. |
| `/ponytail-help` | Show the quick reference. |
Say `stop ponytail` or `normal mode` to disable it. Codex exposes skills with
`$` syntax, for example `$ponytail-review`.
## Install
Clone directly:
```bash
git clone https://github.com/powerzxx/ponytail-balanced.git
```
Claude Code:
```text
/plugin marketplace add powerzxx/ponytail-balanced
/plugin install ponytail-balanced@ponytail-balanced
```
Codex (after adding the marketplace, open Codex and install from `/plugins`):
```bash
codex plugin marketplace add powerzxx/ponytail-balanced
codex
```
```text
/plugins
```
Select `ponytail-balanced`, install it, and start a new session. The strict
Codex manifest loads the bundled skills; invoke them with `$ponytail`,
`$ponytail-review`, and the related skill names. Automatic lifecycle activation
is available in the Claude plugin and is not claimed by the Codex package.
GitHub Copilot CLI:
```bash
copilot plugin marketplace add powerzxx/ponytail-balanced
copilot plugin install ponytail-balanced@ponytail-balanced
```
Other remote installs:
```bash
pi install git:github.com/powerzxx/ponytail-balanced
gemini extensions install https://github.com/powerzxx/ponytail-balanced
hermes plugins install powerzxx/ponytail-balanced --enable
```
For OpenCode, add the checkout's absolute
`.opencode/plugins/ponytail.mjs` path to the `plugin` array in `opencode.json`.
No npm package for this fork is claimed or required.
Cursor, Windsurf, Cline, Copilot Chat, Kiro, and Qoder can copy the matching
rule file from the checkout. See [Agent portability](docs/agent-portability.md).
For instruction-only use, copy [AGENTS.md](AGENTS.md) into a project.
## Host behavior
The compact policy builder in `hooks/ponytail-instructions.js` is the canonical
Node implementation. Claude hooks, Pi, OpenCode, and the MCP server reuse it.
Hermes carries a compact Python equivalent and has parity tests. Qoder receives the
active mode through its prompt hook. Codex loads the bundled skills; Claude owns
the shared lifecycle hook map. Generated OpenClaw skills are rebuilt from `skills/`.
Hosts that only consume repository instruction files receive the balanced priority
order but may not support runtime mode switching.
## Review output safety
`ponytail-review` and `ponytail-audit` use two distinct labels:
- `delete:` — the repository was searched and the finding has enough evidence to
recommend removal.
- `inspect:` — the candidate may be unnecessary, but dynamic registration, public
consumption, or other evidence is incomplete.
Neither skill should flag required persistence, auth, validation, types, public
contracts, accessibility, or tests merely because deleting them shortens code.
## Upstream benchmark provenance
The files under `benchmarks/` and the historical numbers in them were inherited
from upstream Ponytail. They are useful as reproducible prior work, not as evidence
for this fork. The Balanced prompt changes the policy and default mode, so its
quality, code-size, token, cost, and latency effects need a new controlled run.
Until that run exists, the honest project claim is narrower: the fork has automated
regression checks for policy separation, protected requirements, mode switching,
scoped state, adapters, and generated artifacts.
Run the Balanced-specific size/correctness and behavior harnesses with:
```bash
npx promptfoo@latest eval -c benchmarks/promptfooconfig.balanced.yaml --repeat 10
npx promptfoo@latest eval -c benchmarks/behavior.yaml --repeat 10
```
See [Benchmark provenance and reproduction](benchmarks/README.md) before publishing
any result.
## Development
```bash
npm install
python -m pip install pandas
npm test
node scripts/check-rule-copies.js
node scripts/build-openclaw-skills.js
```
Pi and MCP packages have their own tests:
```bash
npm test --prefix pi-extension
npm test --prefix ponytail-mcp
```
The correctness benchmark spawns Python for email and CSV checks, and its CSV cases
require `pandas`.
## Status and limitations
- Balanced-specific empirical benchmarks are pending.
- Project scoping uses a stable hash of the resolved project root; moving a project
intentionally creates a new scope.
- Instruction-only hosts cannot provide the same mode lifecycle as hook hosts.
- Hermes mode commands are associated with sessions in event order because its
command-handler API does not expose a session identifier.
## Attribution and license
Based on [Ponytail](https://github.com/DietrichGebert/ponytail) by Dietrich Gebert.
Balanced changes are maintained separately and are not claims about or releases of
the upstream project.
[MIT](LICENSE)