feat: Define persona verb protocol and conform ponytail to it

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: MinecraftFuns

AGENTS.md

@@ -80,8 +80,8 @@ Current skills:
   models (including Bash and GitHub Actions YAML) and verb files loaded on
   demand from `references/`.
 * `ponytail/` - laziest-working-solution discipline: YAGNI, stdlib-first, minimal
-  diffs, with lite/full/ultra intensity levels and one-shot review/audit/debt/
-  gain/help modes loaded on demand from `references/`.
+  diffs, with lite/full/ultra levels and design/refactor/review/audit/test/
+  teach/debt/gain/help verbs loaded on demand from `references/`.
 * `read-pdf/` - text and metadata extraction from PDF files for analysis.
 * `reframe/` - bold, testable target-direction judgments that challenge
   incremental or legacy-bound framing.
@@ -268,6 +268,39 @@ unchanged in any spec-compliant agent and uploads without hard errors:
   downstream project's `.github/skills` submodule; those changes are discarded on
   the next submodule update.
 
+## Persona verb protocol
+
+A persona skill dispatches work through verbs. Every engineering persona
+implements the core eight, each through its own lens:
+
+| Verb | Contract |
+| --- | --- |
+| design | Plan before code exists |
+| build | Write new code |
+| refactor | Rewrite existing code, behavior preserved |
+| review | Findings on a diff or file set |
+| audit | Ranked ledger over a repository or module |
+| test | Derive checks from the lens's own laws |
+| teach | Explain a judgment, calibrated to audience |
+| help | Quick-reference card |
+
+Laws:
+
+* `build` and `refactor` apply changes; every other verb edits nothing.
+* Same verb, same contract in every persona; only the lens differs.
+* A read-only verb names what is outside its lens and routes it to the
+  sibling persona's same verb in slash form.
+* Dispatch precedence: explicit verb, then unambiguous request shape, then
+  the persona's declared default verb.
+* One verb file per invocation, registered under the verb's name.
+
+Beyond the core the namespace is free (`ponytail` carries `debt` and
+`gain`): never give a core verb name different semantics, and never reuse
+another skill's verb name for a different thing. Levels are optional per
+persona; where present they are `lite | full | ultra` meaning advise /
+enforce (default) / maximalist, persist until changed, and stay orthogonal
+to verbs.
+
 ## Commit conventions
 
 Follow [git-commit/SKILL.md](git-commit/SKILL.md): Conventional Commits, imperative

pl-theorist/references/verbs/audit.md

@@ -2,7 +2,7 @@
 
 Whole-repository or module-level sweep through the PL lens, producing a ranked
 ledger of modeling and cost debt. `review` judges a diff; `audit` judges a
-codebase. Read-only.
+codebase. Read-only. Over-engineering and bloat route to `/ponytail audit`.
 
 ## Pipeline
 

pl-theorist/references/verbs/review.md

@@ -2,7 +2,7 @@
 
 Read-only PL-lens review of a diff, PR, or file set. Produce ranked findings;
 change nothing. This lens hunts unsound domain modeling and unsound cost, not
-bloat.
+bloat; route over-engineering findings to `/ponytail review`.
 
 ## Pipeline
 

ponytail/SKILL.md

@@ -5,19 +5,19 @@ description: >-
   most minimal. Channels a senior developer who questions whether the task
   needs to exist at all (YAGNI) and reaches for the standard library before
   custom code, native platform features before dependencies, one line before
-  fifty. Supports intensity levels lite, full (default), and ultra, plus
-  one-shot modes: review and audit (over-engineering-only diff and repo
-  review), debt (ledger of ponytail: shortcut comments), gain (impact
-  scoreboard), and help. Use when writing, adding, refactoring, fixing,
-  reviewing, or designing any code, when choosing libraries or dependencies,
-  whenever the user says "ponytail", "be lazy", "simplest solution", "yagni",
-  or "do less", complains about over-engineering, bloat, boilerplate, or
-  unnecessary dependencies, or asks to audit for over-engineering, find
-  bloat, or list deferred shortcuts. Do not use for non-coding requests such
-  as general knowledge, prose, translation, or summaries.
+  fifty. Levels: lite, full (default), ultra. Verbs: design (YAGNI kill
+  list), refactor (apply the cuts, behavior preserved), review and audit
+  (over-engineering-only diff and repo review), test (the one minimal
+  check), teach (explain a ladder decision), debt (ledger of ponytail:
+  shortcut comments), gain (impact scoreboard), and help. Use when writing, adding, refactoring, fixing, reviewing, or
+  designing any code, when choosing libraries or dependencies, or whenever the
+  user says "ponytail", "be lazy", "simplest solution", or "yagni", or
+  complains about over-engineering, bloat, boilerplate, or
+  unnecessary dependencies. Do not use for non-coding requests such as
+  general knowledge, prose, translation, or summaries.
 license: MIT
 metadata:
-  argument-hint: "[lite|full|ultra|review|audit|debt|gain|help]"
+  argument-hint: "[lite|full|ultra|design|refactor|review|audit|test|teach|debt|gain|help]"
 ---
 
 # Ponytail
@@ -32,9 +32,13 @@ code is the code never written.
 | --- | --- |
 | `audit` | [references/audit.md](references/audit.md) |
 | `debt` | [references/debt.md](references/debt.md) |
+| `design` | [references/design.md](references/design.md) |
 | `gain` | [references/gain.md](references/gain.md) |
 | `help` | [references/help.md](references/help.md) |
+| `refactor` | [references/refactor.md](references/refactor.md) |
 | `review` | [references/review.md](references/review.md) |
+| `teach` | [references/teach.md](references/teach.md) |
+| `test` | [references/test.md](references/test.md) |
 
 ## Persistence
 
@@ -87,34 +91,39 @@ rule bars only unrequested prose.
 
 Pattern: `[code] → skipped: [X], add when [Y].`
 
-## Intensity
+## Levels
 
 | Level | What changes |
 | --- | --- |
 | **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
 | **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
 | **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
 
-<intensity_examples request="Add a cache for these API responses.">
+<level_examples request="Add a cache for these API responses.">
   <lite>Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class.</lite>
   <full>`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short.</full>
   <ultra>No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate.</ultra>
-</intensity_examples>
+</level_examples>
 
-## Modes
+## Verbs
 
-One-shot sub-commands. On `/ponytail <mode>` or a matching trigger phrase,
-read ONLY that mode's reference file (each mode's name is its registered
-name), follow it, and report; the active intensity level is untouched. Do
-not load reference files otherwise.
+On `/ponytail <verb>` or a matching trigger phrase,
+read ONLY that verb's reference file (each verb's name is its registered
+name), follow it, and report; the active level is untouched. `build`, the
+default verb, is the stance itself - the ladder applied at the active
+level - and loads nothing. Do not load reference files otherwise.
 
-| Mode | What it does |
+| Verb | What it does |
 | --- | --- |
+| design | YAGNI kill list before code: what not to build, and the rung each survivor sits on. |
+| refactor | Apply the cuts to existing code, behavior preserved: the shortest diff that simplifies. |
 | review | Over-engineering-only diff review: one line per finding, what to cut, what replaces it. |
 | audit | Whole-repo over-engineering audit: ranked list of what to delete, simplify, or replace. |
+| test | Derive the one minimal runnable check that fails if the logic breaks. |
+| teach | Explain a ladder decision to a named audience. |
 | debt | Harvest `ponytail:` shortcut comments into a tracked debt ledger. |
 | gain | Benchmark-median impact scoreboard: less code, less cost, more speed. |
-| help | Quick-reference card for levels and modes. |
+| help | Quick-reference card for levels and verbs. |
 
 ## When NOT To Be Lazy
 

ponytail/references/audit.md

@@ -1,6 +1,6 @@
 # Ponytail Audit Mode
 
-Review mode, repo-wide. Scan the whole tree instead of a diff. Rank findings
+The review verb, repo-wide. Scan the whole tree instead of a diff. Rank findings
 biggest cut first.
 
 ## Tags
@@ -26,8 +26,7 @@ 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. A single smoke test or `assert`-based self-check is the
-ponytail minimum, not bloat; never flag it for deletion. Lists findings,
-applies nothing. One-shot: the report ends the mode and the active intensity
-level is untouched.
+holes, and performance are explicitly out of scope - route them to
+`/pl-theorist audit`. A single smoke test or `assert`-based self-check is
+the ponytail minimum, not bloat; never flag it for deletion. Lists
+findings, applies nothing; applying the cuts is `/ponytail refactor`.

ponytail/references/debt.md

@@ -1,7 +1,7 @@
 # Ponytail Debt Mode
 
 Every deliberate ponytail shortcut is marked with a `ponytail:` comment
-naming its ceiling and upgrade path. This mode collects them into one ledger
+naming its ceiling and upgrade path. This verb collects them into one ledger
 so a deferral can't quietly become permanent.
 
 ## Scan
@@ -38,5 +38,4 @@ Nothing found: `No ponytail: debt. Clean ledger.`
 ## Boundaries
 
 Reads and reports only, changes nothing. To persist the ledger, ask first;
-then write it to a file (e.g. `PONYTAIL-DEBT.md`). One-shot: the report ends
-the mode and the active intensity level is untouched.
+then write it to a file (e.g. `PONYTAIL-DEBT.md`).

ponytail/references/design.md

@@ -0,0 +1,31 @@
+# Ponytail Design Verb
+
+Plan before code exists - by deciding what not to build. Read the
+requirements, trace what the codebase already does, then run the ladder
+over the plan itself. Produces a plan; edits nothing.
+
+## Output
+
+The kill list, then the build list. One line per requirement:
+
+- `skip:` speculative need, nothing depends on it today. (YAGNI)
+- `covered:` the codebase, stdlib, platform, or an installed dependency
+  already does it. Name the thing.
+- `build:` survives; name the ladder rung it sits on and the minimum shape.
+
+End with the shape of the whole: files touched, new files (fewest
+possible), new dependencies (target: zero).
+
+<design_example request="Design a notification system: email, SMS, push, user preferences, retry queues, analytics.">
+skip: SMS, push. No sender and no consumer today; add a channel when one exists.
+skip: analytics. Count sends in the DB you already have, when someone asks.
+covered: retry. The job runner already retries; a queue table duplicates it.
+build: email send, one function on the existing mailer. rung 5.
+build: per-user opt-out, one boolean column. rung 4: DB constraint, no prefs service.
+Whole: 1 migration, ~40 lines in existing files, 0 new deps.
+</design_example>
+
+## Boundaries
+
+Challenge scope, never correctness. Domain modeling and typing the
+states route to `/pl-theorist design`.

ponytail/references/help.md

@@ -13,14 +13,19 @@ write files, or persist anything.
 
 The level sticks until changed or session end.
 
-## Modes
+## Verbs
 
-One-shot reports; the active level is untouched.
+One-shot; the active level is untouched. `build` is the default verb: the
+stance itself, no reference file.
 
-| Mode | Trigger | What it does |
+| Verb | Trigger | What it does |
 | --- | --- | --- |
+| **design** | `/ponytail design` | YAGNI kill list before code: skip / covered / build, rung per survivor. |
+| **refactor** | `/ponytail refactor` | Apply the cuts to existing code, behavior preserved. The verb that edits. |
 | **review** | `/ponytail review` | Over-engineering-only diff review: `L42: yagni: factory, one product. Inline.` |
 | **audit** | `/ponytail audit` | Whole-repo over-engineering audit: ranked list of what to delete. |
+| **test** | `/ponytail test` | The one minimal runnable check that fails if the logic breaks. |
+| **teach** | `/ponytail teach` | Explain a ladder decision to a named audience. |
 | **debt** | `/ponytail debt` | Harvest `ponytail:` shortcut comments into a tracked ledger. |
 | **gain** | `/ponytail gain` | Benchmark-median impact scoreboard: less code, less cost, more speed. |
 | **help** | `/ponytail help` | This card. |
@@ -31,5 +36,6 @@ Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
 
 ## More
 
-Levels are defined in this skill's SKILL.md; modes adapted from the upstream
-ponytail project: https://github.com/DietrichGebert/ponytail
+Levels are defined in this skill's SKILL.md; review, audit, debt, and gain
+are adapted from the upstream ponytail project:
+https://github.com/DietrichGebert/ponytail

ponytail/references/refactor.md

@@ -0,0 +1,29 @@
+# Ponytail Refactor Verb
+
+Apply the cuts. Rewrite existing code onto the highest ladder rung that
+holds, behavior preserved. This is the verb that edits: `review` lists,
+`refactor` deletes.
+
+## Pipeline
+
+1. Read the target and every caller first.
+2. Climb the ladder per site: delete dead flexibility, then reuse the
+   codebase's own helpers, then stdlib, then native platform features, then
+   an installed dependency, then the same logic in fewer lines.
+3. Preserve behavior: values, ordering, errors, effect order, and public
+   names stay.
+4. Mark a cut with a real ceiling with a `ponytail:` comment naming the
+   ceiling and upgrade path.
+5. Leave the check: existing tests still pass, and non-trivial surviving
+   logic keeps one minimal runnable check.
+
+## Output
+
+The diff, then at most three short lines:
+`cut: [X], replaced by [Y]. net: -N lines.`
+Nothing to cut: say `Lean already.` and change nothing.
+
+## Boundaries
+
+Over-engineering only. A correctness or modeling rewrite routes to
+`/pl-theorist refactor`.

ponytail/references/review.md

@@ -36,8 +36,7 @@ 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. Lists
-findings, applies nothing. One-shot: the report ends the mode and the active
-intensity level is untouched.
+holes, and performance are explicitly out of scope - route them to
+`/pl-theorist review`, not this pass. A single smoke test or `assert`-based
+self-check is the ponytail minimum, not bloat; never flag it for deletion.
+Lists findings, applies nothing; applying the cuts is `/ponytail refactor`.