@uge/payo 2.3.0 → 2.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +86 -15
  2. package/dist/index.js +242 -212
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -25,6 +25,7 @@ project's conventions instead of guessing.
25
25
 
26
26
  - [What is Payo?](#what-is-payo)
27
27
  - [Why Payo?](#why-payo)
28
+ - [How Payo differs from a generic skills pack](#how-payo-differs-from-a-generic-skills-pack)
28
29
  - [Who is this for?](#who-is-this-for)
29
30
  - [Quick Start](#quick-start)
30
31
  - [How to use — a walkthrough](#how-to-use--a-walkthrough)
@@ -85,6 +86,62 @@ layout, _your_ testing and git rules every time — without you stopping to expl
85
86
  them. You keep vibe coding at full speed; the output just fits the project
86
87
  instead of fighting it.
87
88
 
89
+ ## How Payo differs from a generic skills pack
90
+
91
+ There are plenty of ways to get skills and rule files into a repo: curated
92
+ collections, awesome-lists, starter templates, a rules pack someone published.
93
+ They all hand you the **same markdown everyone else gets** — written for a
94
+ generic project, then left for you to adapt. Payo isn't a catalog you install.
95
+ It's a generator that writes _your_ skills, from _your_ repo.
96
+
97
+ **1. Your skills are written, not downloaded.** Payo doesn't ship skill content.
98
+ It runs the agent CLI you already have installed and authenticated — `claude`,
99
+ `codex`, `cursor-agent`, `copilot`, `agy` — over your answers, several skills at
100
+ a time, retrying and logging each attempt. The result is authored for this
101
+ project on this machine, under your account.
102
+
103
+ **2. Only the skills your project needs exist at all.** Every skill is gated on
104
+ your answers: no database means there is no `data-layer/` skill — not a stub, not
105
+ an "N/A" section, no directory. Same for auth, state management, API
106
+ conventions, logging, testing. A pack gives you all of them and expects you to
107
+ delete the two-thirds that don't apply; Payo never creates them. The interview
108
+ works the same way: a bank of **200+ stack-tailored questions** across **100+
109
+ tech modules**, from which you're asked only the handful your stack pulls in.
110
+
111
+ **3. Real commands and real paths, not placeholders.** Because Payo knows your
112
+ package manager, framework, and ORM, the guidance says `pnpm exec eslint .` —
113
+ not `npx eslint .`, and not `<your lint command>`. It says `cargo test`, `php
114
+ artisan migrate`, `bin/rails db:migrate`, and lists your monorepo's actual
115
+ package directories. The generation prompt explicitly forbids guidance for any
116
+ tool that isn't in your stack, so nothing generic leaks back in.
117
+
118
+ **4. It reads your repo, including habits you never wrote down.** On an existing
119
+ project, Payo detects your stack from the manifests and infers your
120
+ branch-naming and commit-message conventions by parsing your **local** git
121
+ history (which never enters an AI prompt). In **Detect everything** mode your
122
+ code is the source of truth: anything Payo can't find is **skipped**, not filled
123
+ with a plausible default — so it won't prescribe `/v1` API versioning, a testing
124
+ setup, or a folder layout your project never adopted.
125
+
126
+ **5. Guidance that's enforced, not just suggested.** A skills pack is prose, and
127
+ an agent can skip prose. When you enable a guardrail, Payo also writes the
128
+ mechanism that makes it fire: a git hook — in the runner you pick — that
129
+ hard-blocks the commit or push, and a native pre-tool gate for Claude, Cursor,
130
+ and Copilot. It plans both
131
+ layers together, so each check runs in exactly one place — the agent is told not
132
+ to re-run what a hook already runs.
133
+
134
+ **6. One canonical copy, every tool.** One `SKILL.md` per topic under
135
+ `.agents/skills/`, with Claude Code and Windsurf pointed at it by symlink. No
136
+ per-tool duplicates to edit twice and no copies to drift apart — which is
137
+ exactly what a multi-format rules pack leaves you maintaining.
138
+
139
+ **7. Re-runnable, and nothing leaves your machine.** Re-running Payo doesn't
140
+ duplicate a hook or clobber your config: hook edits are matched per check, native
141
+ gates upsert, and retired files are cleaned up on your say-so. An interrupted run
142
+ resumes from `.payo/`. There's no Payo backend, no account, and no telemetry —
143
+ without an agent CLI installed, nothing leaves your machine at all.
144
+
88
145
  ## Who is this for?
89
146
 
90
147
  - **Devs starting a new repo** who want their AI assistant productive from
@@ -253,7 +310,8 @@ present.
253
310
  Optionally, Payo adds a **change-audit** skill (`.agents/skills/change-audit/SKILL.md`):
254
311
  if you opt in, it asks when to run — before every commit or before pushing — and the
255
312
  agent uses it at that point to check your pending change against the relevant project
256
- skills and flag anything that conflicts.
313
+ skills and flag anything that conflicts. It reads the diff and reports — it never runs
314
+ your tests, linter or formatter, because your git hook already does.
257
315
 
258
316
  ### Guardrails enforced by hooks, not just prose
259
317
 
@@ -261,21 +319,34 @@ Skills are guidance the assistant _should_ follow — but an agent can skip pros
261
319
  when you enable a guardrail, Payo also writes the hook that makes it fire regardless:
262
320
 
263
321
  - **A git hook (mechanical, hard block).** When you turn on the gitleaks scan or the
264
- verify-before-commit/push step, Payo writes a **`lefthook.yml`** (or, if your repo
265
- already uses **husky**, **pre-commit**, or native `.git/hooks`, merges into _that_
266
- runner instead — never clobbering your setup). It runs `gitleaks` and your test
267
- command at the stage you chose and **blocks the commit/push on failure** — for every
268
- tool, and for a human typing `git`. Payo writes the config; you wire it up once with
269
- `lefthook install` (Payo tells you the command; it installs nothing itself).
270
- - **A native tool hook (soft confirm).** For **Claude, Cursor, and Copilot**, Payo
271
- writes a `PreToolUse` hook that pops a **confirm prompt** right when the agent runs
272
- `git commit` / `git push` (to run change-audit or confirm the push) or a destructive
273
- query (DB-safety). It stores no state and runs no model — it just makes the prompt
274
- appear so the guardrail isn't silently skipped. Tools without a soft-confirm hook
275
- (Codex, Antigravity, Windsurf) are covered by the git hook above.
322
+ verify-before-commit/push step, Payo asks **which runner** should carry the checks —
323
+ **Lefthook**, **Husky**, **pre-commit**, plain **`.githooks/`** scripts, or none at
324
+ all — and writes that runner's config running `gitleaks`, your test command, your
325
+ linter and a format check at the stage you chose, **blocking the commit/push on
326
+ failure** — for every tool, and for a human typing `git`. No option is marked
327
+ "recommended": which runner your team wants is a convention, not something Payo
328
+ should decide. Payo writes the config and tells you the one command that activates
329
+ it — `lefthook install`, `npx husky`, `pre-commit install`, or
330
+ `git config core.hooksPath .githooks` — and installs nothing itself.
331
+
332
+ **If your repo already has hooks** — **lefthook**, **husky**, **pre-commit**,
333
+ **simple-git-hooks** or native `.git/hooks` — Payo reads what each stage already
334
+ runs and, by default, **leaves your setup completely untouched**. Anything it
335
+ already covers is simply never added; for anything missing, Payo asks whether to
336
+ append it or leave the file alone, and leaving it alone is the recommended answer.
337
+ - **A native tool hook.** For **Claude, Cursor, and Copilot**, Payo writes a
338
+ `PreToolUse` hook that fires when the agent runs `git commit` / `git push` or a
339
+ destructive query. Confirm-push and DB-safety raise a **confirm prompt for you**.
340
+ Change-audit instead **denies the command once** with an instruction back to the
341
+ agent — a confirm prompt would just be approved and the audit skipped — and the
342
+ retry for that same change goes through. It stores nothing outside `.git/` and runs
343
+ no model. Tools without a pre-tool hook (Codex, Antigravity, Windsurf) are covered
344
+ by the git hook above.
276
345
 
277
346
  Both are **idempotent** — re-running Payo never duplicates a hook — and are written
278
- only for the guardrails you actually enabled.
347
+ only for the guardrails you actually enabled. Whatever a hook runs, the generated
348
+ skills tell the agent **not** to run it as well, so the same checks never execute
349
+ twice; anything no hook covers stays an explicit instruction to the agent.
279
350
 
280
351
  The question Payo asks — _"Which agent CLI should Payo use to generate content?"_ —
281
352
  picks only **which installed CLI authors the content**. The output above works with
@@ -328,7 +399,7 @@ A few environment variables tune AI generation:
328
399
  | ----------------------- | -------- | ------------------------------------ |
329
400
  | `PAYO_CONCURRENCY` | `4` | Max parallel agent subprocesses |
330
401
  | `PAYO_RETRIES` | `1` | Extra attempts after a failed run |
331
- | `PAYO_AGENT_TIMEOUT_MS` | `120000` | Wall-clock cap per file (ms) |
402
+ | `PAYO_AGENT_TIMEOUT_MS` | `420000` | Wall-clock cap per file (ms) |
332
403
 
333
404
  ### Your data stays yours
334
405