npm - @event4u/agent-config - Versions diffs - 1.15.0 → 1.17.0 - Mend

@event4u/agent-config 1.15.0 → 1.17.0

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 (354) hide show

package/.agent-src/skills/quality-tools/SKILL.md CHANGED Viewed

@@ -52,8 +52,8 @@ Use the **first matching** command style:
 | `symplify/easy-coding-standard` | `vendor/bin/ecs` | `vendor/bin/ecs check --fix` |
 **Priority:** If a project ships a `quality:*` wrapper (Artisan or Composer script), always prefer it —
-wrappers typically add
-git-aware execution, caching, automatic baseline regeneration, and memory management.
+wrappers typically add git-aware execution, caching, automatic baseline regeneration, and memory
+management on top of the native tools.
 If none of the above is installed → skip quality checks, inform the user.

package/.agent-src/skills/react-shadcn-ui/SKILL.md CHANGED Viewed

@@ -9,35 +9,59 @@ source: package
 ## Compatibility
 - **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
-- Audit step (`directives/ui/audit.py`) reads the line above and compares it with `state.ui_audit.shadcn_inventory.version`; major mismatch triggers a soft halt before this skill runs.
+- The audit step (`directives/ui/audit.py`) reads the line above and
+  compares it with `state.ui_audit.shadcn_inventory.version`; a major
+  mismatch triggers a soft halt before this skill runs.
 ## When to use
-Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.py`, `review.py`, or `polish.py` dispatches to this skill, or when a React project clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*` dependencies, a `components/ui/` folder of generated primitives).
+Use when `state.stack.frontend == "react-shadcn"` and `directives/ui/apply.py`,
+`review.py`, or `polish.py` dispatches to this skill, or when a React project
+clearly uses shadcn/ui (presence of `components.json`, `@radix-ui/*`
+dependencies, a `components/ui/` folder of generated primitives).
 Do NOT use when:
 - Project is Blade + Livewire + Flux (use `flux` / `livewire` / `blade-ui`).
 - Project is Vue (use the Vue stack skills).
-- Plain React without shadcn/ui — fall back to manual composition; this skill assumes the primitive set exists.
+- Plain React without shadcn/ui — fall back to manual composition; this skill
+  assumes the primitive set exists.
 ## Gotcha
-- shadcn/ui is **not** an npm package. Primitives are copied into `components/ui/` and edited in-place. Do not `npm install shadcn-ui`. Run `npx shadcn@latest add <primitive>` to scaffold; then edit.
-- Major-version drift between this skill's `## Compatibility` line and the project's installed primitives is a real risk. Audit step writes `state.ui_audit.shadcn_inventory` with the detected version — when it diverges by a major, audit emits a soft halt before this skill runs.
-- shadcn/ui composes Radix primitives. Accessibility built in via Radix but only when wrapper components used correctly (`asChild`, `<DialogTrigger>` instead of bare `<button>`).
-- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`) and CSS custom properties on `:root` and `.dark` (`--background`, `--foreground`, `--primary`, `--ring`, …). Audit writes them into `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
-- Dark mode is class-based (`<html class="dark">`). Every color must come from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
-- Every interactive primitive must declare a focus-visible state via `focus-visible:ring-2 focus-visible:ring-ring`; comes free with generated primitives but easy to remove during a refactor.
+- shadcn/ui is **not** an npm package. Primitives are copied into
+  `components/ui/` and edited in-place. Do not `npm install shadcn-ui`.
+  Run `npx shadcn@latest add <primitive>` to scaffold; then edit.
+- Major-version drift between this skill's `## Compatibility` line and
+  the project's installed primitives is a real risk. The audit step
+  writes `state.ui_audit.shadcn_inventory` with the detected version —
+  when it diverges by a major, audit emits a soft halt before this
+  skill runs.
+- shadcn/ui composes Radix primitives. Accessibility is built in via Radix
+  but only when you use the wrapper components correctly (`asChild`,
+  `<DialogTrigger>` instead of a bare `<button>`).
+- Tailwind tokens come from `tailwind.config.{js,ts}` (`theme.extend.colors`)
+  and CSS custom properties on `:root` and `.dark` (`--background`,
+  `--foreground`, `--primary`, `--ring`, …). Audit writes them into
+  `state.ui_audit.design_tokens`. Use those tokens; do not hardcode values.
+- Dark mode is class-based (`<html class="dark">`). Every color must come
+  from `bg-background`, `text-foreground`, etc. — never raw `bg-white`.
+- Every interactive primitive must declare a focus-visible state via
+  `focus-visible:ring-2 focus-visible:ring-ring`; that comes for free with
+  the generated primitives but is easy to remove during a refactor.
 ## Covered primitives
-Validated against the following shadcn primitives at the declared version:
+This skill is validated against the following shadcn primitives at the
+declared version:
-- **Form / inputs:** `Button`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Select`, `Switch`, `Label`, `Form` (react-hook-form wrapper + `zodResolver`).
-- **Overlay:** `Dialog`, `Sheet`, `Popover`, `Tooltip`, `DropdownMenu`, `AlertDialog`.
+- **Form / inputs:** `Button`, `Input`, `Textarea`, `Checkbox`,
+  `RadioGroup`, `Select`, `Switch`, `Label`, `Form` (react-hook-form
+  wrapper + `zodResolver`).
+- **Overlay:** `Dialog`, `Sheet`, `Popover`, `Tooltip`, `DropdownMenu`,
+  `AlertDialog`.
 - **Layout:** `Card`, `Separator`, `Tabs`, `Accordion`, `ScrollArea`.
-- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`, `Avatar`, `Skeleton`, `Progress`.
+- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`,
+  `Avatar`, `Skeleton`, `Progress`.
 - **Feedback:** `Toast` (sonner), `Alert`.
 ## Not covered — fall back to manual composition
@@ -45,63 +69,110 @@ Validated against the following shadcn primitives at the declared version:
 - Marketing-only components (Hero, Pricing, Features) — outside shadcn/ui.
 - `Calendar` / `DatePicker` — composition skill required, not generated.
 - `Combobox` — built from `Command` + `Popover`; case-by-case.
-- Streaming / partial-prerender boundaries — use the project's framework patterns (Next.js / Remix), not shadcn/ui.
+- Streaming / partial-prerender boundaries — use the project's framework
+  patterns (Next.js / Remix), not shadcn/ui.
 ## Procedure: render a shadcn/ui component for the design brief
 ### Step 0: Inspect
-1. Read `state.ui_audit.shadcn_inventory.version` and confirm it matches the version in `## Compatibility` within the same major. If audit flagged a mismatch, user already chose to proceed — note that in `state.changes`.
-2. Read `state.ui_audit.design_tokens` — every color, spacing, and radius in rendered output must reference a token from this map.
+1. Read `state.ui_audit.shadcn_inventory.version` and confirm it matches
+   the version in `## Compatibility` within the same major. If audit
+   flagged a mismatch, the user already chose to proceed — note that
+   in `state.changes`.
+2. Read `state.ui_audit.design_tokens` — every color, spacing, and radius
+   in the rendered output must reference a token from this map.
 3. Read `state.ui_design`:
    - `components` → the primitive list to compose.
-   - `microcopy` → button labels, empty-state text, validation messages. **Lock — render verbatim.**
+   - `microcopy` → button labels, empty-state text, validation messages.
+     **Lock — render verbatim.**
    - `states` → empty / loading / error / success / disabled coverage.
    - `a11y` → ARIA labels, keyboard nav, focus order.
 ### Step 1: Compose primitives
-1. Import primitives from project's `components/ui/` path (`@/components/ui/button`, …) — never from `shadcn` or `radix-ui`.
-2. Compose Radix-style: `<Dialog>` → `<DialogTrigger asChild>` → `<DialogContent>` → `<DialogHeader>` → `<DialogTitle>`. Never wrap `DialogTrigger` around a pre-styled `<button>`; pass `asChild`.
-3. Use variant API of `Button` (`variant="default" | "destructive" | "outline" | "secondary" | "ghost" | "link"`); do not override with raw Tailwind for the variant set.
-4. Forms: `useForm` (react-hook-form) + `zodResolver(schema)` → `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` → `<FormControl>` → `<FormMessage>`. Validation messages come from the zod schema, mirrored to design-brief microcopy.
+1. Import primitives from the project's `components/ui/` path
+   (`@/components/ui/button`, …) — never from `shadcn` or `radix-ui`.
+2. Compose Radix-style: `<Dialog>` → `<DialogTrigger asChild>` →
+   `<DialogContent>` → `<DialogHeader>` → `<DialogTitle>`. Never wrap
+   `DialogTrigger` around a pre-styled `<button>`; pass `asChild`.
+3. Use the variant API of `Button` (`variant="default" | "destructive" |
+   "outline" | "secondary" | "ghost" | "link"`); do not override with
+   raw Tailwind for the variant set.
+4. Forms: `useForm` (react-hook-form) + `zodResolver(schema)` →
+   `<Form>` → `<FormField>` → `<FormItem>` → `<FormLabel>` →
+   `<FormControl>` → `<FormMessage>`. Validation messages come from
+   the zod schema, mirrored to the design-brief microcopy.
 ### Step 2: Apply tokens, dark mode, a11y
-1. Colors via semantic classes: `bg-background`, `text-foreground`, `bg-primary text-primary-foreground`, `text-muted-foreground`. No `bg-white` / `text-black` / hardcoded `#fff`.
-2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius` in `tailwind.config.{js,ts}`). Polish refactors hardcoded values when a token equivalent exists.
-3. Dark mode: never branch on a `dark` prop; rely on `.dark` class on root and semantic tokens.
-4. Every interactive primitive: keyboard trigger present (Enter/Space on buttons, Esc on dialogs — Radix free), visible focus ring, `aria-label` from `state.ui_design.a11y` when icon-only.
+1. Colors via semantic classes: `bg-background`, `text-foreground`,
+   `bg-primary text-primary-foreground`, `text-muted-foreground`. No
+   `bg-white` / `text-black` / hardcoded `#fff`.
+2. Spacing / radius from theme tokens (`rounded-lg` mapped to `--radius`
+   in `tailwind.config.{js,ts}`). Polish refactors hardcoded values
+   when a token equivalent exists.
+3. Dark mode: never branch on a `dark` prop; rely on the `.dark` class
+   on the root and semantic tokens.
+4. Every interactive primitive: keyboard trigger present (Enter/Space
+   on buttons, Esc on dialogs — Radix free), visible focus ring,
+   `aria-label` from `state.ui_design.a11y` when icon-only.
 ### Step 3: State coverage
-1. Empty: render design-brief empty-state copy in a `Card` or inline placeholder; never `null`.
-2. Loading: `Skeleton` rows for tables; `Button` `disabled` + `Loader2` icon for submit-in-flight.
-3. Error: `Alert variant="destructive"` with design-brief message; `FormMessage` for field-level errors.
-4. Success: `toast.success(...)` from `sonner` with design-brief confirmation copy.
-5. Disabled: `disabled` prop on trigger plus design-brief reason as `aria-describedby` text.
+1. Empty: render the design-brief empty-state copy in a `Card` or
+   inline placeholder; never `null`.
+2. Loading: `Skeleton` rows for tables; `Button` `disabled` +
+   `Loader2` icon for submit-in-flight.
+3. Error: `Alert variant="destructive"` with the design-brief message;
+   `FormMessage` for field-level errors.
+4. Success: `toast.success(...)` from `sonner` with the design-brief
+   confirmation copy.
+5. Disabled: `disabled` prop on the trigger plus the design-brief
+   reason as `aria-describedby` text.
 ### Step 4: Validate
 1. No raw `<input>` / `<button>` / `<select>` outside the primitive set.
 2. No hardcoded colors / spacing — every value is a token.
 3. Microcopy matches `state.ui_design.microcopy` byte-for-byte.
-4. Dark mode: toggle `.dark` on `<html>`, render the component, every surface still legible (no `text-white on bg-white`).
+4. Dark mode: toggle `.dark` on `<html>`, render the component, every
+   surface still legible (no `text-white on bg-white`).
 5. Keyboard: Tab through every focusable element; focus ring visible.
 ## Output format
-1. React component file(s) under project's `components/` (or `app/`) tree, importing primitives from `@/components/ui/*`.
-2. Per file, one entry recorded in `state.changes` with `kind="ui"`, `stack="react-shadcn"`, and the design-brief summary.
+1. React component file(s) under the project's `components/` (or `app/`)
+   tree, importing primitives from `@/components/ui/*`.
+2. Per file, one entry recorded in `state.changes` with `kind="ui"`,
+   `stack="react-shadcn"`, and the design-brief summary.
 ### Review pass — a11y findings + preview envelope
-When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Run a11y tool against rendered output (e.g. `axe-core` via Playwright, `@axe-core/react`, `jest-axe`) and translate hits into this shape. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
-Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Run an a11y tool against the
+  rendered output (e.g. `axe-core` via Playwright, `@axe-core/react`,
+  `jest-axe`) and translate hits into this shape. Use the same
+  `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so the
+  engine's de-dup matches pre-existing entries on replay. Omit the
+  envelope on apply passes; the engine's `_apply_a11y_gate` only fires
+  when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
 ## Do NOT
@@ -109,13 +180,15 @@ Polish dispatch: when dispatcher skips `review` because previous review pass ret
 - Do NOT hardcode colors / spacing / radii — use the token map.
 - Do NOT branch on a `dark` prop — use semantic tokens + the `.dark` class.
 - Do NOT rewrite microcopy — it is locked by `state.ui_design`.
-- Do NOT skip `asChild` on `DialogTrigger` / `SheetTrigger` / similar Radix wrappers — breaks the accessibility contract.
-- Do NOT introduce a non-shadcn UI library (MUI, Chakra) into the same surface — pick one system per surface.
+- Do NOT skip `asChild` on `DialogTrigger` / `SheetTrigger` / similar
+  Radix wrappers — it breaks the accessibility contract.
+- Do NOT introduce a non-shadcn UI library (MUI, Chakra) into the same
+  surface — pick one system per surface.
 ## Auto-trigger keywords
 - shadcn / shadcn ui / shadcn/ui
-- React component (when project uses shadcn)
+- React component (when the project uses shadcn)
 - Radix primitive
 - Tailwind dark mode
 - React Hook Form + zod

package/.agent-src/skills/readme-reviewer/SKILL.md CHANGED Viewed

@@ -17,15 +17,15 @@ execution:
 - Auditing README quality across repos
 - Checking for hallucinated setup, commands, or features
-Do NOT use for:
+Do NOT use when:
-- Grammar or formatting proofreading only
+- Only proofreading grammar or formatting
 - Writing a README from scratch → use `readme-writing` or `readme-writing-package`
 ## Goal
-Ensure README is correct (no invented content), aligned with the repo,
-useful for the audience, with a strong quickstart path.
+Ensure the README is correct (no invented content), aligned with the repo,
+useful for the intended audience, and has a strong quickstart path.
 ## Core principles
@@ -39,8 +39,8 @@ useful for the audience, with a strong quickstart path.
 ### 1. Identify README type and audience
-Determine repo type (package, app, CLI, internal, framework) and audience
-(consumers, contributors, team). Check if structure matches type.
+Determine repo type (package, app, CLI, internal, framework) and target audience
+(consumers, contributors, team). Check if README structure matches this type.
 ### 2. Cross-check against repository
@@ -53,16 +53,17 @@ Inspect truth-defining files:
 - Source entrypoints — actual public API
 - Config files, tests, existing docs
-Verify: install steps exist, commands work, features implemented, dependencies real.
+Verify: install steps exist, commands work, features are implemented,
+dependencies are real.
 ### 3. Validate installation and setup
 Check:
-- Install command correct and complete
-- Required post-install steps documented
+- Install command is correct and complete
+- Required post-install steps are documented
 - No hidden setup assumptions
-- Environment/config requirements listed
+- Environment/config requirements are listed
 Flag: missing steps, incorrect steps, implied-but-unwritten steps.
@@ -70,10 +71,10 @@ Flag: missing steps, incorrect steps, implied-but-unwritten steps.
 Check:
-- First example minimal and realistic
+- First example is minimal and realistic
 - Example matches actual API (verify against source)
-- Example doesn't rely on undocumented setup
-- Example not overly complex or abstract
+- Example does not rely on undocumented setup
+- Example is not overly complex or abstract
 Flag: pseudo-code, oversized examples, API mismatches.
@@ -82,8 +83,8 @@ Flag: pseudo-code, oversized examples, API mismatches.
 Check:
 - Runtime versions stated (PHP, Node, etc.)
-- Framework compatibility explicit
-- Dependencies declared
+- Framework compatibility is explicit
+- Dependencies are declared
 Flag: missing compatibility, vague claims ("works with most versions"),
 unconfirmed broad support.
@@ -92,19 +93,19 @@ unconfirmed broad support.
 Check:
-- Strong first screen (what + why + quickstart before scroll)
+- Strong first screen (what + why + quickstart visible before scrolling)
 - Logical section order for repo type
 - No unnecessary sections (padded boilerplate)
 - No missing critical sections
-Common issues: architecture before installation, no quickstart, buried
-usage, generic template sections.
+Common issues: architecture before installation, no quickstart,
+buried usage instructions, generic template sections.
 ### 7. Detect hallucinations
-Search for:
+Explicitly search for:
-- Commands not in repo
+- Commands not present in repo
 - Features not implemented
 - Setup steps not supported by scripts/configs
 - Assumptions about environment or tools
@@ -133,11 +134,11 @@ Structure checks:
 - ToC present if > 150 lines or > 6 top-level (`##`) sections
 - Multi-platform install (> 5 variants) uses a table with deep links, not stacked blocks
 - `<details>` used only for secondary, bulky content — never for install, first example, or requirements
-- No duplication between README and `/docs/` (drifts over time)
+- No duplication between README and `/docs/` (same content in two places drifts)
 - Each `/docs/` file linked from README is self-contained (not just a fragment)
-→ See `guidelines/docs/readme-size-and-splitting.md` for full thresholds,
-splitting strategies, anti-patterns.
+→ See `docs/guidelines/docs/readme-size-and-splitting.md` for full thresholds,
+splitting strategies, and anti-patterns.
 ## Output format
@@ -159,9 +160,9 @@ splitting strategies, anti-patterns.
 Severity levels:
-- **❌ Critical** — breaks onboarding or factually incorrect
+- **❌ Critical** — breaks onboarding or is factually incorrect
 - **⚠️ Major** — confusing, incomplete, or misleading
-- **ℹ️ Minor** — clarity, formatting, structure
+- **ℹ️ Minor** — clarity improvement, formatting, structure
 ### 3. Confidence
@@ -171,11 +172,11 @@ Severity levels:
 ## Gotcha
-- Model trusts the README instead of verifying against the repo
+- Model tends to trust the README instead of verifying against the repo
 - Model may miss subtle mismatches between examples and real APIs
-- Model focuses on wording/style instead of correctness
-- Well-formatted README with wrong commands worse than ugly but correct
-- Model accepts "looks reasonable" compatibility without checking CI matrix
+- Model may focus on wording/style instead of correctness
+- A well-formatted README with wrong commands is worse than ugly but correct
+- Model may accept "looks reasonable" compatibility without checking CI matrix
 ## Do NOT
@@ -184,4 +185,4 @@ Severity levels:
 - Do NOT accept vague compatibility statements as valid
 - Do NOT focus only on wording while missing structural/correctness issues
 - Do NOT overlook mismatches between examples and actual source code
-- Do NOT soften findings — state issues clearly with severity
+- Do NOT soften findings — state issues clearly with severity

package/.agent-src/skills/readme-writing/SKILL.md CHANGED Viewed

@@ -15,29 +15,34 @@ execution:
 - Creating a new README for an **application, CLI tool, internal tool, template, or framework**
 - Rewriting an outdated or weak README
 - Improving after major repo changes (new tooling, restructure)
+- Adapting README for a different audience
-Do NOT use for:
+Do NOT use when:
-- **Packages/libraries** → use `readme-writing-package` instead
-- Minor typos, single-section updates, reference docs in separate files
+- Writing a README for a **reusable package or library** → use `readme-writing-package` instead
+- Fixing minor typos or updating a single section
+- Writing reference docs that belong in separate files
+- Only adding a badge or version bump
 ## Goal
-Accurate, evidence-based, scannable README for the intended audience.
-Reflects the real repository — not assumptions.
+Write a README that is accurate, evidence-based, scannable, and useful for
+the intended audience. Reflects the real repository — not assumptions.
 ## Core principles
-- Analyze first, write second — inspect repo before writing
-- Evidence-based — every command, step, feature must exist in repo
-- Strong quickstart over exhaustive noise — get started in 30 seconds
-- Right scope — overview in README, deep content in dedicated docs
-- Match repo type — package README ≠ app ≠ CLI tool ≠ framework
+- **Analyze first, write second** — inspect the repo before writing a single line
+- **Evidence-based only** — every command, setup step, and feature must exist in the repo
+- **Strong quickstart over exhaustive noise** — a reader should get started in 30 seconds
+- **Right scope** — high-level overview in README, deep content in dedicated docs
+- **Match the repo type** — a package README differs from an app, CLI tool, or framework
 ## Procedure
 ### 1. Identify README type and audience
+Determine repository type:
 | Type | Audience | Priority |
 |---|---|---|
 | **Library/Package** | Developers consuming it | Install → Usage → API |
@@ -49,94 +54,114 @@ Reflects the real repository — not assumptions.
 ### 2. Inspect the repository
-Read truth-defining files:
+Read these files to extract truth:
-- `README.md` (existing), `package.json`, `composer.json`
-- `Dockerfile`, `docker-compose.yml`
-- `Taskfile.yml`, `Makefile`
-- CI workflows, config files, `docs/`, `agents/`
+- `README.md` (existing, if any)
+- `package.json`, `composer.json` — name, description, scripts, dependencies
+- `Dockerfile`, `docker-compose.yml` — runtime setup
+- `Taskfile.yml`, `Makefile` — available commands
+- CI workflows — what gets tested, how
+- `docs/`, `agents/` — existing documentation
+- Config files — what tools are used
-Extract: purpose, install path, commands, requirements, workflows, testing, contribution flow.
+Extract: project purpose, install path, main commands, requirements,
+key workflows, testing/linting commands, contribution flow.
 ### 3. Choose sections
-Only include sections that provide value:
+Only include sections that provide value. Candidates:
 1. **Title + one-line summary** — always
-2. **Why / what problem** — if not obvious from name
-3. **Key features** — if more than trivial
+2. **Why / what problem it solves** — if not obvious from name
+3. **Key features or capabilities** — if more than a trivial tool
 4. **Requirements** — only if non-obvious
 5. **Installation / setup** — always
-6. **Usage / quickstart** — always (most important)
-7. **Configuration** — if applicable
-8. **Development workflow** — if accepts contributions
+6. **Usage / quickstart** — always (most important section)
+7. **Configuration / customization** — if applicable
+8. **Development workflow** — if repo accepts contributions
 9. **Testing / quality** — if tooling exists
 10. **Project structure** — if non-trivial
-11. **Contributing** — if open/team project
+11. **Contributing** — if open or team project
 12. **License** — if applicable
+Do NOT include sections "because READMEs usually have them."
 Skip empty or near-empty sections entirely.
 ### 4. Write evidence-based content
-- Only document commands that exist in the repo
+Rules:
+- Only document commands that actually exist in the repo
 - Only describe setup steps supported by scripts/configs
 - Only claim features confirmed by code or docs
-- Unclear? Inspect more or ask — never invent
+- If something is unclear: inspect more or ask — never invent
+Formatting:
-Formatting: tables for comparisons, code blocks for commands (copy-pasteable),
-short paragraphs (max 3 sentences), directory trees for structure.
+- Tables for structured comparisons (tools, options, features)
+- Code blocks for every command (copy-pasteable)
+- Short paragraphs — max 3 sentences before a break
+- Directory trees for project structure (use `tree` format)
+- Badges only if they link to live CI/release status
-### 5. Optimize for first screen
+### 5. Optimize for the first screen
-Reader must answer within 10 seconds: What is this? Why? How to start?
+A reader scanning the README should answer within 10 seconds:
-First screen (before scroll): title, summary, install or quickstart.
+1. What is this?
+2. Why does it exist?
+3. How do I install/start it?
+The first screen (before scrolling) must contain the title, summary,
+and either install command or quickstart. Everything else comes after.
 ### 6. Size and structure
-Keep README scannable. Past ~150 lines: add Table of Contents. Past ~300
-lines: split deep content to `/docs/` or `references/`. Use `<details>`
-only for secondary, bulky content — never for install, first example, or
-requirements.
+Keep the README scannable. If it grows past ~150 lines, add a Table of
+Contents; past ~300 lines, split deep content out to `/docs/` or
+`references/`. Use `<details>` only for secondary, bulky content (never
+for install, first example, or requirements).
-→ See `guidelines/docs/readme-size-and-splitting.md` for thresholds,
+→ See `docs/guidelines/docs/readme-size-and-splitting.md` for thresholds,
 splitting strategies (reference-split, deep-link tables, collapsibles),
-multi-audience handling, anti-patterns.
+multi-audience handling, and anti-patterns.
 ### 7. Validate
-- [ ] Every command exists in repo (`Taskfile.yml`, `Makefile`, `package.json`, etc.)
-- [ ] Setup steps are reproducible
-- [ ] No invented features or capabilities
+After writing, verify:
+- [ ] Every documented command exists in the repo (`Taskfile.yml`, `Makefile`, `package.json scripts`, etc.)
+- [ ] Setup steps are reproducible (no missing prerequisites)
+- [ ] No features or capabilities are invented
 - [ ] First screen answers: what, why, how-to-start
 - [ ] No dead sections (heading with 1-2 trivial sentences)
-- [ ] Deep content in dedicated docs, not crammed in README
-- [ ] Size below "overloaded" threshold, or splitting in place (see size guideline)
-- [ ] ToC present if > 150 lines or > 6 top-level sections
+- [ ] Scope is right — deep content moved to dedicated docs, not crammed in
+- [ ] Size below the "overloaded" threshold, or splitting is in place (see size guideline)
+- [ ] ToC present if README > 150 lines or > 6 top-level sections
+- [ ] Matches existing tonality if repo has established voice
 - [ ] All file paths and references are valid
 ## Output format
 1. Full README draft
 2. Short note: detected repo type + audience
-3. Uncertainties or assumptions needing confirmation
+3. Any uncertainties or assumptions that need confirmation
 ## Gotcha
-- Model writes generic boilerplate instead of repo-specific docs
-- Model includes commands/steps that don't exist in the repo
-- Model over-documents, burying the quickstart under walls of text
-- Existing README structure can mislead — don't preserve weak structure blindly
-- Package READMEs need install/usage focus, not internal dev workflow
-- Model forgets to validate commands against `Taskfile.yml` / `Makefile` / `package.json`
+- The model tends to write generic boilerplate instead of repo-specific documentation
+- The model tends to include commands or setup steps that don't actually exist in the repo
+- The model tends to over-document and bury the quickstart under walls of text
+- Existing README structure can be misleading — don't preserve weak structure blindly
+- READMEs for packages consumed by others need install/usage focus, not internal dev workflow
+- The model forgets to validate commands against `Taskfile.yml` / `Makefile` / `package.json scripts`
 ## Do NOT
-- Do NOT invent features, setup steps, or commands not in the repo
-- Do NOT copy generic templates without adapting to the project
-- Do NOT overload with deep reference material — link to docs
+- Do NOT invent features, setup steps, or commands not found in the repo
+- Do NOT copy generic README templates without adapting to the actual project
+- Do NOT overload with deep reference material — link to docs instead
 - Do NOT write for "everyone" — choose a real audience
 - Do NOT skip repository inspection before writing
-- Do NOT preserve weak structure just because it exists
-- Do NOT add marketing language ("blazing fast", "revolutionary")
+- Do NOT preserve weak structure from an existing README just because it exists
+- Do NOT add marketing language ("blazing fast", "revolutionary", "next-gen")