@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.
- package/README.md +86 -15
- package/dist/index.js +242 -212
- 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
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
tool, and for a human typing `git`.
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
`git
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
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` | `
|
|
402
|
+
| `PAYO_AGENT_TIMEOUT_MS` | `420000` | Wall-clock cap per file (ms) |
|
|
332
403
|
|
|
333
404
|
### Your data stays yours
|
|
334
405
|
|