Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"repository": "https://github.com/DietrichGebert/ponytail",
"license": "MIT",
"keywords": ["yagni", "minimalism", "code-review", "productivity"],
"skills": "./skills/",
"skills": "./.codex-plugin/skills/",
"hooks": "./hooks/claude-codex-hooks.json",
"interface": {
"displayName": "Ponytail",
Expand Down
41 changes: 41 additions & 0 deletions .codex-plugin/skills/ponytail-audit/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
name: ponytail-audit
description: >
Whole-repo audit for over-engineering. Like ponytail-review, but scans the
entire codebase instead of a diff: a ranked list of what to delete, simplify,
or replace with stdlib/native equivalents. Use when the user says "audit this
codebase", "audit for over-engineering", "what can I delete from this repo",
"find bloat", "ponytail-audit", or "/ponytail-audit". One-shot report, does
not apply fixes.
---

ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
findings biggest cut first.

## Tags

Same as ponytail-review:

- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
- `stdlib:` hand-rolled thing the standard library ships. Name the function.
- `native:` dependency or code doing what the platform already does. Name the feature.
- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
- `shrink:` same logic, fewer lines. Show the shorter form.

## Hunt

Deps the stdlib or platform already ships, single-implementation interfaces,
factories with one product, wrappers that only delegate, files exporting one
thing, dead flags and config, hand-rolled stdlib.

## Output

One line per finding, ranked: `<tag> <what to cut>. <replacement>. [path]`.
End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`

## Boundaries

Scope: over-engineering and complexity only. Correctness bugs, security holes,
and performance are explicitly out of scope. Route them to a normal review
pass. Lists findings, applies nothing. One-shot.
"stop ponytail-audit" or "normal mode" to revert.
3 changes: 3 additions & 0 deletions .codex-plugin/skills/ponytail-audit/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
policy:
products:
- codex
44 changes: 44 additions & 0 deletions .codex-plugin/skills/ponytail-debt/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
name: ponytail-debt
description: >
Harvest every `ponytail:` comment in the codebase into a debt ledger, so the
deliberate shortcuts and deferrals ponytail leaves behind get tracked instead
of rotting into "later means never". Use when the user says "ponytail debt",
"/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail
ledger", or "what did we mark to do later". One-shot report, changes nothing.
---

Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
its ceiling and upgrade path. This collects them into one ledger so a deferral
can't quietly become permanent.

## Scan

Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
output:

`grep -rnE '(#|//) ?ponytail:' .` (add other comment prefixes if your stack uses them)

Each hit is one ledger row. The comment prefix keeps prose that merely mentions
the convention out of the ledger.

## Output

One row per marker, grouped by file:

`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`

The convention is `ponytail: <ceiling>, <upgrade path>`, so pull the ceiling
and the trigger straight from the comment. Want an owner per row too? add
`git blame -L<line>,<line>`.

Flag the rot risk: any `ponytail:` comment that names no upgrade path or
trigger gets a `no-trigger` tag, those are the ones that silently rot.

End with `<N> markers, <M> with no trigger.` Nothing found: `No ponytail: debt. Clean ledger.`

## Boundaries

Reads and reports only, changes nothing. To persist it, ask and it writes the
ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot. "stop ponytail-debt" or
"normal mode" to revert.
3 changes: 3 additions & 0 deletions .codex-plugin/skills/ponytail-debt/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
policy:
products:
- codex
50 changes: 50 additions & 0 deletions .codex-plugin/skills/ponytail-gain/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
name: ponytail-gain
description: >
Show ponytail's measured impact as a compact scoreboard: less code, less
cost, more speed, from the benchmark medians. One-shot display, not a
persistent mode, and not a per-repo number. Trigger: /ponytail-gain,
"ponytail gain", "what does ponytail save", "show ponytail impact",
"ponytail scoreboard".
---

# Ponytail Gain

Display this scoreboard when invoked. One-shot: do NOT change mode, write flag
files, or persist anything.

The figures are the published benchmark medians (5 everyday tasks: email
validator, debounce, CSV sum, countdown timer, rate limiter; three models:
Haiku, Sonnet, Opus). They are measured, not computed from the current repo.
Source: `benchmarks/` and the README.

## Scoreboard

Render plain ASCII bars. The bar length shows the measured range; the label
carries the exact figure:

```
ponytail gain benchmark median · 5 tasks · 3 models

Lines of code no-skill ████████████████████ 100%
ponytail ██▌················· 6–20% ▼ 80–94%
Cost no-skill ████████████████████ 100%
ponytail █████▌·············· 23–53% ▼ 47–77%
Speed ponytail ▸ 3–6× faster

This repo: /ponytail-debt (shortcuts you deferred)
/ponytail-audit (what's still cuttable)
```

## Honesty boundary

These are benchmark medians, not this repo. NEVER print a per-repo savings
number ("you saved X lines/tokens here"): the unbuilt version was never
written, so there is no real baseline to subtract from in a live repo. The
only real per-repo figures come from `/ponytail-debt` (a counted ledger), and
this card points there instead of inventing one.

## Boundaries

One-shot display. Edits nothing, changes no mode.
"stop ponytail" or "normal mode": revert.
3 changes: 3 additions & 0 deletions .codex-plugin/skills/ponytail-gain/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
policy:
products:
- codex
74 changes: 74 additions & 0 deletions .codex-plugin/skills/ponytail-help/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
name: ponytail-help
description: >
Quick-reference card for all ponytail modes, skills, and commands.
One-shot display, not a persistent mode. Trigger: /ponytail-help,
"ponytail help", "what ponytail commands", "how do I use ponytail".
---

# Ponytail Help

Display this reference card when invoked. One-shot, do NOT change mode,
write flag files, or persist anything.

## Levels

| Level | Trigger | What change |
|-------|---------|-------------|
| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |

Level sticks until changed or session end.

## Skills

| Skill | Trigger | What it does |
|-------|---------|--------------|
| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
| **ponytail-audit** | `/ponytail-audit` | Whole-repo over-engineering audit: ranked list of what to delete. |
| **ponytail-debt** | `/ponytail-debt` | Harvest `ponytail:` shortcut comments into a tracked ledger. |
| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
| **ponytail-help** | `/ponytail-help` | This card. |

Codex mode switching accepts the convenience hook form `$ponytail full` and
the explicit controller form `$ponytail:ponytail full`.
Codex one-shot skills use qualified names such as
`$ponytail:ponytail-review` and `$ponytail:ponytail-help`.
Claude Code and OpenCode use the slash-command forms above (OpenCode ships all
six as slash commands).

## Deactivate

Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
`/ponytail off` also works.

## Configure Default Mode

Default mode = `full`, auto-active every session. Change it:

**Environment variable** (highest priority):
```bash
export PONYTAIL_DEFAULT_MODE=ultra
```

**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
```json
{ "defaultMode": "lite" }
```

Set `"off"` to disable auto-activation on session start, activate manually
with `/ponytail` when wanted.

Resolution: env var > config file > `full`.

## Update

Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.

If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.

## More

Full docs + examples: https://github.com/DietrichGebert/ponytail
3 changes: 3 additions & 0 deletions .codex-plugin/skills/ponytail-help/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
policy:
products:
- codex
57 changes: 57 additions & 0 deletions .codex-plugin/skills/ponytail-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
name: ponytail-review
description: >
Code review focused exclusively on over-engineering. Finds what to delete:
reinvented standard library, unneeded dependencies, speculative abstractions,
dead flexibility. One line per finding: location, what to cut, what replaces
it. Use when the user says "review for over-engineering", "what can we
delete", "is this over-engineered", "simplify review", or invokes
/ponytail-review. Complements correctness-focused review, this one only
hunts complexity.
---

Review diffs for unnecessary complexity. One line per finding: location, what
to cut, what replaces it. The diff's best outcome is getting shorter.

## Format

`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
multi-file diffs.

Tags:

- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
- `stdlib:` hand-rolled thing the standard library ships. Name the function.
- `native:` dependency or code doing what the platform already does. Name the feature.
- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
- `shrink:` same logic, fewer lines. Show the shorter form.

## Examples

❌ "This EmailValidator class might be more complex than necessary, have you
considered whether all these validation rules are needed at this stage?"

✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`

✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`

✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`

✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`

✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`

## Scoring

End with the only metric that matters: `net: -<N> lines possible.`

If there is nothing to cut, say `Lean already. Ship.` and stop.

## Boundaries

Scope: over-engineering and complexity only. Correctness bugs, security holes,
and performance are explicitly out of scope. Route them to a normal review
pass, not this one. A single smoke test or `assert`-based
self-check is the ponytail minimum, not bloat, never flag it for deletion.
Does not apply the fixes, only lists them.
"stop ponytail-review" or "normal mode": revert to verbose review style.
3 changes: 3 additions & 0 deletions .codex-plugin/skills/ponytail-review/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
policy:
products:
- codex
25 changes: 25 additions & 0 deletions .codex-plugin/skills/ponytail/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
name: ponytail
description: >
Explicitly control Ponytail mode for the current Codex thread.
Use when the user invokes $ponytail to inspect, enable, change, or disable
lite, full, or ultra mode, or to configure the default for future threads.
argument-hint: "[lite|full|ultra|off|default <off|lite|full|ultra>]"
license: MIT
---

# Ponytail Controller

This Codex-only skill controls Ponytail's persistent mode for the current thread.
The lifecycle hook performs the transition and supplies the authoritative instructions for the selected mode.
Do not restate or emulate the Ponytail ruleset from this controller.

## Commands

- `$ponytail` reports the current mode without changing it.
- `$ponytail lite`, `$ponytail full`, and `$ponytail ultra` select a mode for the current thread.
- `$ponytail off` disables Ponytail for the current thread.
- `$ponytail default <off|lite|full|ultra>` changes only the default for future threads.

After a mode command, follow the newest `PONYTAIL CONTROL` supplied by the lifecycle hook.
The one-shot review, audit, debt, gain, and help skills do not change the persistent mode.
4 changes: 4 additions & 0 deletions .codex-plugin/skills/ponytail/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
policy:
allow_implicit_invocation: false
products:
- codex
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -22,5 +22,8 @@ ponytail-*.gif
# Claude Code local settings (machine-specific permission grants)
.claude/settings.local.json

# Codex local marketplace generated by scripts/build-codex-local.js
.codex-local-marketplace/

# agentic benchmark workspaces (agent output, kept locally for inspection)
benchmarks/agentic/runs/
9 changes: 6 additions & 3 deletions .openclaw/skills/ponytail-help/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,12 @@ Level sticks until changed or session end.
| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
| **ponytail-help** | `/ponytail-help` | This card. |

Codex uses `@ponytail`, `@ponytail-review`, and `@ponytail-help`; Claude Code
and OpenCode use the slash-command forms above (OpenCode ships all six as
slash commands).
Codex mode switching accepts the convenience hook form `$ponytail full` and
the explicit controller form `$ponytail:ponytail full`.
Codex one-shot skills use qualified names such as
`$ponytail:ponytail-review` and `$ponytail:ponytail-help`.
Claude Code and OpenCode use the slash-command forms above (OpenCode ships all
six as slash commands).

## Deactivate

Expand Down
Loading