@uge/payo 2.3.1 → 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 +67 -6
  2. package/dist/index.js +202 -180
  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
@@ -262,11 +319,15 @@ Skills are guidance the assistant _should_ follow — but an agent can skip pros
262
319
  when you enable a guardrail, Payo also writes the hook that makes it fire regardless:
263
320
 
264
321
  - **A git hook (mechanical, hard block).** When you turn on the gitleaks scan or the
265
- verify-before-commit/push step, Payo writes a **`lefthook.yml`** running `gitleaks`,
266
- your test command, your linter and a format check at the stage you chose, and
267
- **blocking the commit/push on failure** — for every tool, and for a human typing
268
- `git`. Payo writes the config; you wire it up once with `lefthook install` (Payo
269
- tells you the command; it installs nothing itself).
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.
270
331
 
271
332
  **If your repo already has hooks** — **lefthook**, **husky**, **pre-commit**,
272
333
  **simple-git-hooks** or native `.git/hooks` — Payo reads what each stage already
@@ -338,7 +399,7 @@ A few environment variables tune AI generation:
338
399
  | ----------------------- | -------- | ------------------------------------ |
339
400
  | `PAYO_CONCURRENCY` | `4` | Max parallel agent subprocesses |
340
401
  | `PAYO_RETRIES` | `1` | Extra attempts after a failed run |
341
- | `PAYO_AGENT_TIMEOUT_MS` | `120000` | Wall-clock cap per file (ms) |
402
+ | `PAYO_AGENT_TIMEOUT_MS` | `420000` | Wall-clock cap per file (ms) |
342
403
 
343
404
  ### Your data stays yours
344
405