@herbertgao/pi-extensions 2026.10.1 → 2026.10.2

package/node_modules/@dietrichgebert/ponytail/skills/ponytail-review/SKILL.md

@@ -1,62 +1,101 @@
 ---
 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.
+  Quality review of a change: is the logic right, is it safe, does it hold
+  under real load, is risky code tested, is it fast enough, and is every line
+  needed. Reads the connected code, not only the diff. Each finding is
+  explained in plain English. Use for "review this", "code review", "review
+  the last commit", "review my PR", "is this over-engineered", /ponytail-review.
 ---
 
-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
-
-`<N>. L<line>: <tag> <what>. <replacement>.`, or `<N>. <file>:L<line>: ...` for
-multi-file diffs. Number findings `1.`, `2.`, ... across the whole report, so the
-user can say "fix 2 and 5".
-
-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.
-- `reuse:` equivalent helper, util, or pattern already in this repo. Name the path.
-- `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?"
-
-✅ `1. L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
-
-✅ `2. L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
-
-✅ `3. L18-29: reuse: slugify helper duplicates src/lib/slug.ts slugify. Delete it, import the existing one.`
-
-✅ `4. repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
-
-✅ `5. L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
-
-✅ `6. 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.
+Review a change like the senior developer who will be paged when it breaks.
+Order of importance: correct, safe, holds under load, tested, fast, lean.
+Lean still matters: every extra line must be read, tested and fixed later.
+This is a report the user asked for, so give it in full.
+
+## 1. Understand first
+
+- Review what the user names: uncommitted or staged changes, a branch, a PR
+  link, or files. Nothing named: the uncommitted changes, or the last commit
+  if there are none.
+- Read the diff, then the code it touches: callers of every changed function,
+  the functions it calls, the tests, the README.
+- Trace the real flow: where data comes in, what is stored, what goes out.
+- A change can break code it does not touch. When a signature, return value
+  or behavior changes, grep every caller.
+- Find the expected load in the repo (README, deploy config): one person
+  running a script, or many users and processes at once. Judge scale against
+  that, and say which load you assumed.
+
+## 2. Look for
+
+1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
+   rounding, time zones), a caller broken by the change, a fix applied in one
+   caller while the shared function stays broken.
+2. **Risk:** security holes (injection, weak randomness, secrets, missing
+   checks on input from users), data loss (errors swallowed, writes in the
+   wrong order, no transaction).
+3. **Scale:** fine for one user, wrong for many: check-then-write races, the
+   same work done by every process, memory or lists that only grow, a query
+   per item, O(n^2) on big input, per-process state that must be shared.
+4. **Missing test:** risky new logic (a branch, a parser, money, security,
+   data writes, a bug fix) with no test that fails when it breaks. One good
+   test, not coverage.
+5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
+   loop) are suggestions; some software counts every millisecond.
+6. **Lean:** code that should not exist or should be smaller.
+   - delete: dead code, unused options, speculative features
+   - reuse: the repo already has this helper (name the path)
+   - stdlib / native: the standard library or platform already does it; a
+     new dependency for a few lines
+   - yagni: abstraction with one implementation, config nobody sets
+   - merge: near-copies that must change together
+   - split: one function doing several unrelated jobs, so it is hard to read
+     or test. Split by job, never by line count, and never into helpers that
+     exist only to make a function shorter.
+
+## 3. Check before you report
+
+- Every finding needs a concrete case: "this input or situation leads to this
+  wrong result". No case, no finding.
+- Re-read the lines and confirm: the caller exists, the value can really be
+  empty, the code really is unused.
+- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
+  decision, not a finding, unless the expected load already crosses it.
+- Propose the smallest fix that works. Prefer fixes that delete code. Never
+  add layers, frameworks or config the problem does not need.
+- No style taste, no "consider", no vague worries.
+
+## 4. Output
+
+Very simple English: short sentences, everyday words. Explain a technical
+term the first time you use it. The reader may never have seen this code.
+
+Start with `What this change does:` in two or three sentences.
+
+Then the findings in three groups, skip empty groups:
+- **Must fix:** bug, security, data loss, breaks at the expected load.
+- **Should fix:** risky code without a test, real slowness, duplication, a
+  function that mixes jobs, code that should not exist.
+- **Nice to have:** small speed-ups, shorter forms.
+
+Number findings across all groups, so the user can say "fix 2 and 5".
+Every finding has all four parts, each one or two short sentences:
+
+2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
+   - **What this is:** At midnight this job closes the day and bills all orders of that day.
+   - **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
+     at 00:30 in Berlin is billed on the day before.
+   - **Fix:** Compute the day once in the shop's time zone:
+     `datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
+   - **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
+
+End with:
+- `Verdict: Ship.` or `Verdict: fix 1 and 3 first.`
+- `Lean: -<N> lines possible.` when lean findings exist.
+- `Not checked:` one line, if something mattered and you could not check it.
+
+Nothing found: `What this change does:`, then `Looks good. Ship.` and one line
+on what you checked.
+
+Lists findings, changes no code.

package/node_modules/@herbertgao/pi-agency/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Herbert Gao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@herbertgao/pi-agency/README.md

@@ -0,0 +1,40 @@
+# @herbertgao/pi-agency
+
+Search the [Agency Agents](https://github.com/msitarzewski/agency-agents) catalog and dispatch its personas to Pi subagents without reading the catalog or persona files into the main context.
+
+```bash
+pi install npm:@herbertgao/pi-agency
+git clone https://github.com/msitarzewski/agency-agents ~/.agency-agents
+```
+
+The catalog location is fixed at `~/.agency-agents`. `agency_dispatch` also needs the `Agent` tool from [`@herbertgao/pi-subagents`](../pi-subagents), which the `@herbertgao/pi-extensions` aggregate bundles. Requires Pi 0.99.0 or later.
+
+## Tools
+
+`agency_search({ queries, limit?, per_division? })` returns cards (`path`, `name`, `description`, `score`) for each query. It ranks every `<division>/**/*.md` file with `name` and `description` frontmatter by BM25 over name, path, and description. It returns at most `limit` cards per query (default 6) and `per_division` cards per top-level division (default 2). The repository's `integrations`, `strategy`, `examples`, and `scripts` directories are skipped.
+
+`agency_dispatch({ runs, shared?, shared_file?, subagent_type?, isolated?, model?, thinking?, max_turns?, record_dir? })` runs every `runs[i].prompt` as a foreground `Agent` call, all in parallel, and returns when they finish. Foreground calls do not queue completion notifications for the parent session.
+
+- `{{persona}}` is replaced by the body of `runs[i].persona` with its frontmatter removed. The file must resolve inside the catalog, symlinks included, and must not contain `<persona>` or `</persona>`.
+- `{{shared}}` is replaced by `shared` or the text of `shared_file`.
+- Each placeholder must appear exactly once when its value is given and must not appear otherwise. Substitution happens in one pass, so `$&` and placeholder-like text in inserted content stay literal.
+- Defaults are `subagent_type: "general-purpose"` and `isolated: true`, which gives subagents built-in tools only.
+- Each result includes `promptSha256` for the prompt actually sent, plus the run's status, agent id, resolved model, and output.
+- `record_dir` must be absolute. It receives `<id>.prompt.txt` and `<id>.return.txt` with mode `0600`. The call fails before any dispatch if one of those files already exists.
+
+Both tools return `structuredContent`, so codemode scripts receive objects instead of text.
+
+```js
+const { results } = await tools.agency_search({
+  queries: ["OAuth login flows", "database migration safety"],
+})
+const { results: reviews } = await tools.agency_dispatch({
+  shared_file: "/tmp/review/diff.patch",
+  runs: results.map(({ cards: [card] }, i) => ({
+    id: `expert-${i + 1}`,
+    persona: card.path,
+    prompt:
+      "<persona>\n{{persona}}\n</persona>\n\nReview this diff:\n{{shared}}",
+  })),
+})
+```

package/node_modules/@herbertgao/pi-agency/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@herbertgao/pi-agency",
+  "version": "0.1.0",
+  "description": "Search the Agency Agents catalog and dispatch its personas to Pi subagents without loading them into context.",
+  "keywords": [
+    "agency-agents",
+    "pi-extension",
+    "pi-package",
+    "subagents"
+  ],
+  "homepage": "https://github.com/HerbertGao/pi-extensions/tree/master/packages/pi-agency#readme",
+  "bugs": {
+    "url": "https://github.com/HerbertGao/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Herbert Gao",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HerbertGao/pi-extensions.git",
+    "directory": "packages/pi-agency"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "x-origin": "original"
+}