From e733c6b40b22333baadf11cb61f9125dd92ae59d Mon Sep 17 00:00:00 2001 From: DietrichGebert Date: Mon, 15 Jun 2026 02:44:43 +0200 Subject: [PATCH] docs: commands reference + portability accuracy (#41) * docs: add a Commands reference to the README The commands were only mentioned scattered through prose, and two install blurbs had gone stale (OpenCode omitted /ponytail-debt, Gemini omitted audit and debt). Add one canonical Commands table (all five commands + what each does + which hosts support them) and point the install blurbs at it so they stop drifting as commands are added. Co-Authored-By: Claude Opus 4.8 (1M context) * docs: add pi to the portability table, de-stale the Gemini row pi was a supported integration (pi-extension, README install, registers all the commands) but had no row in the Supported Adapters table. The Gemini row also enumerated an outdated command list; point it at commands/*.toml generically so it stops drifting. --------- Co-authored-by: Claude Opus 4.8 (1M context) --- README.md | 22 +++++++++++++++------- docs/agent-portability.md | 3 ++- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 32daff9..5a5d9c7 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ Run OpenCode from a checkout of this repo (the plugin reuses its `hooks/` and `s { "plugin": ["./.opencode/plugins/ponytail.mjs"] } ``` -Injects the ruleset every turn at the active level; adds `/ponytail`, `/ponytail-review`, and `/ponytail-audit`. OpenCode also auto-loads this repo's `AGENTS.md`, so the rules hold even without the plugin. The plugin adds the `lite/full/ultra/off` levels. +Injects the ruleset every turn at the active level; adds the `/ponytail` commands (see [Commands](#commands)). OpenCode also auto-loads this repo's `AGENTS.md`, so the rules hold even without the plugin. The plugin adds the `lite/full/ultra/off` levels. ### Gemini CLI @@ -107,15 +107,11 @@ Injects the ruleset every turn at the active level; adds `/ponytail`, `/ponytail gemini extensions install https://github.com/DietrichGebert/ponytail ``` -Loads the ruleset as always-on context every session and registers `/ponytail` and `/ponytail-review`; the `skills/` ship too, activated when a task needs them. +Loads the ruleset as always-on context every session and registers the `/ponytail` commands; the `skills/` ship too, activated when a task needs them. That was it. He'd be proud. He won't say it. -Active every session. `/ponytail-review` finds what to delete in your diff, `/ponytail-audit` does the same for the whole repo, `/ponytail-debt` harvests the `ponytail:` shortcuts you've deferred so they don't rot. `/ponytail ultra` exists for when the codebase has wronged you personally. `/ponytail-help` explains the rest. - -In Codex, invoke the skills as `@ponytail`, `@ponytail-review`, -`@ponytail-audit`, `@ponytail-debt`, and `@ponytail-help`. Startup and -mode-change text shows the current mode. +Active every session, with a handful of commands (see [Commands](#commands)). `/ponytail ultra` exists for when the codebase has wronged you personally. Startup and mode-change text shows the current mode. Cursor, Windsurf, Cline, Copilot, Aider, Kiro: copy the matching rules file from this repo ([`.cursor/rules/`](.cursor/rules/), [`.windsurf/rules/`](.windsurf/rules/), [`.clinerules/`](.clinerules/), [`.github/copilot-instructions.md`](.github/copilot-instructions.md), [`AGENTS.md`](AGENTS.md), [`.kiro/steering/`](.kiro/steering/)). @@ -127,6 +123,18 @@ Antigravity and VS Code with the Codex extension: both read `AGENTS.md`, which t Which files map to which agent: [Agent portability](docs/agent-portability.md). +## Commands + +| Command | What it does | +|---------|--------------| +| `/ponytail [lite \| full \| ultra \| off]` | Set the intensity, or turn it off. No argument reports the current level. | +| `/ponytail-review` | Review the current diff for over-engineering, hands back a delete-list. | +| `/ponytail-audit` | Audit the whole repo for over-engineering, not just the diff. | +| `/ponytail-debt` | Harvest the `ponytail:` shortcuts you've deferred into a ledger, so "later" doesn't become "never". | +| `/ponytail-help` | Quick reference for the commands above. | + +Commands need a skill-capable host (Claude Code, Codex, OpenCode, Gemini, pi). In Codex they're skills, invoke with `@` (`@ponytail-review`). The instruction-only adapters (Cursor, Windsurf, Cline, Copilot, Kiro, Antigravity) load the always-on ruleset without the commands. + ## Development When changing the compact rule text, keep the agent copies aligned: diff --git a/docs/agent-portability.md b/docs/agent-portability.md index 989d28e..6c0fd75 100644 --- a/docs/agent-portability.md +++ b/docs/agent-portability.md @@ -11,7 +11,8 @@ to load in a given agent. | Claude Code | `.claude-plugin/`, `commands/`, `hooks/` | Full plugin install with session activation, mode tracking, commands, and statusline support. | | Codex | `.codex-plugin/plugin.json`, `hooks/hooks.json`, `hooks/`, `skills/` | Plugin install with the same skills plus lifecycle hooks for activation and mode tracking. | | OpenCode | `.opencode/plugins/ponytail.mjs`, `.opencode/command/`, `hooks/`, `skills/` | Server plugin injects the ruleset each turn via `experimental.chat.system.transform` and persists `/ponytail` switches; reuses the shared instruction builder. | -| Gemini CLI | `gemini-extension.json`, `AGENTS.md`, `commands/`, `skills/` | Extension manifest points `contextFileName` at `AGENTS.md` for always-on rules, and reuses the existing `commands/*.toml` (`/ponytail`, `/ponytail-review`) and `skills/`, which Gemini CLI auto-discovers. | +| pi | `pi-extension/`, `skills/`, `hooks/` | Package extension: injects the ruleset each turn through the shared instruction builder and registers the `/ponytail` commands. | +| Gemini CLI | `gemini-extension.json`, `AGENTS.md`, `commands/`, `skills/` | Extension manifest points `contextFileName` at `AGENTS.md` for always-on rules, and reuses the existing `commands/*.toml` and `skills/`, which Gemini CLI auto-discovers. | | Cursor | `.cursor/rules/ponytail.mdc` | Always-on project rule. | | Windsurf | `.windsurf/rules/ponytail.md` | Project rule. | | Cline | `.clinerules/ponytail.md` | Project rule. |