@uge/payo 1.4.0 → 2.0.0

package/README.md

@@ -59,14 +59,15 @@ over Prisma, that handlers live in `src/routes`, that you write Vitest specs
 beside the file, or that commits follow Conventional Commits. So you re-explain
 it — in chat after chat — and still get code that ignores half of it.
 
-The fix is the guidance files each tool already reads (`CLAUDE.md`,
-`.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`). But writing them
-by hand is tedious, easy to get wrong, and different for every tool. Most people
-never do it, or do it once and let it rot.
+The fix is the guidance files agents read — an `AGENTS.md` entrypoint plus
+[Agent Skills](https://agentskills.io) under `.agents/skills/`. But writing them
+by hand is tedious and easy to get wrong. Most people never do it, or do it once
+and let it rot.
 
-Payo writes them for you in minutes — tailored to your actual stack,
-in each tool's native format — so your assistant follows _your_ conventions from
-the first prompt instead of guessing.
+Payo writes them for you in minutes — tailored to your actual stack, in one
+universal layout that **every skills-compatible tool reads** (Claude Code, Codex,
+Cursor, Copilot, Gemini, Antigravity, Windsurf, …) — so your assistant follows
+_your_ conventions from the first prompt instead of guessing.
 
 ### Vibe coding, without the mess
 
@@ -91,7 +92,7 @@ instead of fighting it.
 - **Teams enforcing conventions** who need every contributor's assistant to
   follow the same folder structure, naming, testing, and git rules.
 - **Multi-tool users** who switch between Claude, Cursor, and Copilot and want
-  the _same_ project guidance expressed in each tool's native format.
+  the _same_ project guidance in one universal layout every tool reads.
 - **Anyone bootstrapping a stack** they haven't wired up before — Payo encodes
   sensible, framework-specific defaults and can scaffold a runnable project.
 
@@ -131,9 +132,10 @@ guidance files straight into your repo.
    summary of every answer. Choose **Edit an answer** to change any response — or
    re-open a section you skipped — right from the review; dependent questions are
    re-asked automatically. Pick **Generate** when it looks right.
-5. **Payo generates the guidance.** It writes each tool's files in their native
-   format and location (see the table below). With the tool's CLI installed,
-   files are generated in parallel by the AI; otherwise solid templates are used.
+5. **Payo generates the guidance.** It writes one universal layout that every
+   skills-compatible tool reads (see the table below). With an agent CLI
+   installed, skills are generated in parallel by the AI; otherwise solid
+   templates are used.
 6. **(Optional) Get a bootstrap prompt.** Payo offers to write a paste-ready
    `bootstrap-prompt.md` you hand to any LLM to scaffold a runnable project that
    honors the guidance it just generated.
@@ -152,18 +154,28 @@ When detection finds a manifest, you get two quick choices:
 
 - **Work with the existing project, or start fresh?** Keep the detected answers, or
   ignore them and answer from scratch.
-- **Detect everything, or just the stack?** Fill in stack facts only, or also
-  pre-fill the convention questions (folder structure and the like) that Payo can
-  infer from your layout.
+- **Detect everything, or just the stack?**
+  - **Detect everything** fills in the whole config with no question-by-question
+    prompts: stack facts and conventions are taken from what Payo detects, and any
+    convention it can't detect is set to a sensible recommended default. You land
+    straight on the review screen and edit anything that's off before generating —
+    everything means everything, confirmed once at the end.
+  - **Just the high-level stack** fills in the stack facts only and interviews you
+    for the convention questions (folder structure and the like).
 
-How detected answers are applied:
+How detected answers are applied in **Just the high-level stack** mode:
 
 - **Stack facts** (language, framework, database, ORM, package manager, test
   runner, linter…) are filled in and **skipped** — they're things a manifest can
   state authoritatively, so there's nothing to ask.
-- **Conventions and preferences** are surfaced as **pre-filled defaults you still
-  confirm** — a manifest can't encode intent, so Payo never silently decides these
-  for you.
+- **Conventions and preferences** are left to the interview — a manifest can't
+  encode intent, so Payo asks rather than guessing.
+
+**Monorepos** are detected too: Payo enumerates workspace members (pnpm / npm /
+yarn / lerna, Cargo, `go.work`, Maven / Gradle), detects each package's stack, and
+uses the real app stack as the primary answers instead of the near-empty root
+manifest. The generated guidance gains a **Workspace Packages** list and monorepo
+conventions.
 
 Detection runs deterministically from your files first. When the chosen AI tool's
 CLI is installed, an **optional second pass** uses **your own** assistant to fill
@@ -174,20 +186,43 @@ deterministic result stands on its own.
 
 ## What gets generated
 
-Each tool gets files in its own native format and location:
+One universal layout, whichever agent CLI you pick — no per-tool formats:
+
+| Path                            | What it is                                                          |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `AGENTS.md`                     | The entrypoint most tools read natively — your project's base rules |
+| `.agents/skills/<id>/SKILL.md`  | One [Agent Skill](https://agentskills.io) per topic, spec frontmatter |
+| `CLAUDE.md`                     | A one-line `@AGENTS.md` import shim so Claude Code picks it up       |
+| `.claude/skills/**`             | Symlinks into `.agents/skills/` (dir copy on Windows) for Claude Code |
+| `.windsurf/skills/**`           | The same shim for Windsurf                                           |
+
+Who reads what, with no extra work:
+
+- **Codex, Cursor, Copilot, Gemini CLI, Antigravity, Devin** → `.agents/skills/` and
+  `AGENTS.md` natively.
+- **Claude Code** → the `CLAUDE.md` shim plus the `.claude/skills/` symlinks
+  (officially supported; it dedupes if it also reads the target directly).
+- **Windsurf** → `AGENTS.md` plus the `.windsurf/skills/` shim.
+
+`AGENTS.md` opens its skills index with a directive telling the agent to consult and
+follow the applicable skills before writing code — so the guidance is used, not just
+present.
+
+Optionally, Payo adds a **change-audit** skill (`.agents/skills/change-audit/SKILL.md`):
+if you opt in, it asks when to run — before every commit or before pushing — and the
+agent uses it at that point to check your pending change against the relevant project
+skills and flag anything that conflicts.
 
-| Tool                 | Files generated                                                  |
-| -------------------- | --------------------------------------------------------------- |
-| Claude (Anthropic)   | `CLAUDE.md` · `.claude/skills/**`                               |
-| Cursor               | `.cursorrules` · `.cursor/rules/**`                             |
-| GitHub Copilot       | `.github/copilot-instructions.md` · `.github/instructions/**`  |
-| Codex CLI            | `AGENTS.md`                                                      |
-| Antigravity (Google) | `AGENTS.md` · `.agents/skills/**`                               |
-| Windsurf             | `.windsurfrules`                                                 |
-| Other / generic      | `AI_RULES.md`                                                    |
+The question Payo asks — _"Which agent CLI should Payo use to generate content?"_ —
+picks only **which installed CLI authors the content**. The output above works with
+every skills-compatible tool regardless of that choice.
 
-> Rich AI generation needs the selected tool's CLI on your `PATH`. Without it,
-> Payo writes well-structured template defaults instead.
+> Rich AI generation needs an agent CLI on your `PATH`. Without one, Payo writes
+> well-structured template defaults into the same layout instead.
+>
+> Regenerating over an older Payo project? It offers to remove the retired
+> per-tool files (`.cursorrules`, `.windsurfrules`, `.cursor/rules/**`,
+> `.github/instructions/**`, `.github/copilot-instructions.md`, `AI_RULES.md`).
 
 ## What it asks about
 
@@ -208,6 +243,8 @@ questions to whatever you pick. Dimensions covered:
 - **Tooling** — package manager, runtime, formatter, linter
 - **TypeScript** — `tsconfig` strictness, target, module resolution, path aliases
 - **Conventions** — folder structure, coding standards, docs, git workflow
+- **Change audit** _(optional)_ — opt into a skill that checks your pending
+  change against the project skills before commit or push
 
 ## AI vs. template generation
 
@@ -250,13 +287,12 @@ generating what's missing. Finished runs clean the directory up automatically.
 
 Payo works today, but it's still early. Here's where it's headed:
 
-- **Deeper existing-project detection.** Payo already detects an established
-  repo's stack and pre-fills the questionnaire (see
+- **Deeper monorepo support.** Payo now enumerates workspace members, detects
+  each package's stack, and writes per-package notes into one root config (see
   [Already have a project?](#already-have-a-project-payo-detects-your-stack)).
-  Next is making that just as sharp on **monorepos**: today detection reads the
-  root manifest, so a workspace whose real stack lives in `apps/*` and
-  `packages/*` underfills. Workspace-aware, multi-root detection — plus broader
-  signal coverage — is the next step.
+  Next is going further: per-package skills and guidance for repos where each
+  workspace wants its own conventions, and workspace enumeration for the
+  remaining ecosystems (Python, PHP, .NET, Ruby).
 - **Broader stack coverage.** More languages, frameworks, ORMs, databases, and
   AI tools, plus deeper, more opinionated defaults for the ones already
   supported — so the guidance fits more of the ecosystem out of the box.