@event4u/agent-config 1.16.0 → 1.18.0

package/.agent-src/skills/md-language-check/SKILL.md

@@ -16,29 +16,32 @@ execution:
 
 ## When to use
 
-Fire **before** saving any `.md` file under:
+Fire this skill **before** writing or saving any `.md` file under:
 
-- `.agent-src.uncompressed/` (source of truth)
+- `.agent-src.uncompressed/` (source of truth — skills, rules, commands, guidelines, templates, contexts)
 - `.agent-src/` (compressed projection)
 - `.augment/` (local agent projection)
-- `agents/` (project roadmaps, contexts, sessions)
+- `agents/` (project-specific roadmaps, contexts, sessions)
 
-Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md`
-files are ALWAYS English" + § Detection heuristic, every `.md` in
-those trees must be English. Bilingual content lives only in labeled
+Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md` files
+are ALWAYS English" and § Detection heuristic, every `.md` file in those
+trees must be English. Bilingual content lives only in labeled
 `DE: … · EN: …` anchor blocks.
 
 Do NOT use when:
 
-- Editing project content outside the trees above
-- Reviewing non-`.md` files (checker rejects them)
+- Editing project content outside the trees listed above (READMEs of
+  consumer projects, application docs that follow a different policy)
+- Reviewing chat history files (`.agent-chat-history` is JSONL, not `.md`)
+- Inspecting non-`.md` files — the checker rejects them with a warning
 
 ## Procedure
 
 ### 1. Identify the file(s) about to be saved
 
-Collect every `.md` path the agent is about to create or modify this
-turn. Multiple files → one invocation.
+Collect the absolute or repo-relative path of every `.md` file the
+agent is about to create or modify in this turn. Multiple files in
+one turn → pass them all to a single invocation.
 
 ### 2. Run the checker
 
@@ -46,58 +49,77 @@ turn. Multiple files → one invocation.
 python3 scripts/check_md_language.py <path> [<path> …] [--format json]
 ```
 
-Exit codes: `0` clean, `1` violations (save **blocked** until fixed
-or suppressed), `3` internal error.
+Exit codes:
+
+- `0` → no German content detected, save proceeds
+- `1` → violations found, save is **blocked** until they are resolved
+  or explicitly suppressed
+- `3` → internal error (unreadable file, decode failure)
 
 ### 3. Resolve findings
 
-| Kind | Cause | Fix |
+For every violation:
+
+| Kind | Likely cause | Fix |
 |---|---|---|
-| `umlaut` | German prose in body | Translate to English |
-| `de_word` | German function word in unquoted prose | Translate; or move into `DE: … · EN: …` block |
+| `umlaut` | German prose leaked into body text | Translate the sentence to English |
+| `de_word` | German function word in unquoted prose | Translate; or move into a `DE: … · EN: …` block if intentional bilingual anchor |
 
-Meta-doc that **must** quote German tokens (e.g. the heuristic in
-`language-and-tone.md` itself) → append
-`<!-- md-language-check: ignore -->` to that single line. Never as a
-wholesale silencer.
+If the line is meta-documentation that **must** quote German tokens
+(e.g. the detection heuristic in `language-and-tone.md` itself),
+append `<!-- md-language-check: ignore -->` at the end of that single
+line — never as a wholesale silencer.
 
 ### 4. Re-run and confirm
 
-After every fix re-run on the same paths. Save proceeds only on `0`.
+After every fix, re-run the checker on the same paths. Save only
+proceeds on exit `0`.
 
 ## Allowed escape hatches
 
-- **Labeled anchor** — lines starting with `DE:` / `- DE:` / `* DE:`
-  (and the same for `EN:`) auto-skipped.
-- **Fenced code blocks** — exempt; shell snippets, JSON fixtures,
-  quoted user input pass through.
-- **Inline code** — backtick spans stripped before scanning.
-- **Per-line marker** — `<!-- md-language-check: ignore -->` on lines
-  that genuinely quote German tokens (rare).
+- **Labeled anchor block** — lines starting with `DE:` / `- DE:` /
+  `* DE:` (and the same for `EN:`) are skipped automatically. Use this
+  for intent-based opt-in / opt-out anchors.
+- **Fenced code blocks** — `\`\`\` … \`\`\`` content is exempt, so
+  shell snippets, JSON fixtures, and quoted user input in code
+  blocks pass through untouched.
+- **Inline code** — backtick spans are stripped before scanning;
+  identifiers like `für_test` inside backticks do not flag.
+- **Per-line marker** — append `<!-- md-language-check: ignore -->`
+  to a line that genuinely needs to quote a German token in body
+  prose (rare; reserved for the rules that document the heuristic).
 
 ## Output format
 
 1. One-line summary: `clean` or `N violation(s) found`
 2. Per violation: `file:line — kind \`match\`` plus the offending line
 3. Next action: translate, move into a `DE:`/`EN:` block, add the
-   per-line ignore marker, or revert
+   per-line ignore marker, or revert the change
 
 ## Gotchas
 
-- `.md` files only; non-`.md` paths emit a warning and skip
-- Word list is short and conservative — clean run is **necessary
-  but not sufficient**; agent owns the final language judgement
-- Frontmatter (`--- … ---`) is exempt
+- The checker scans `.md` files only; passing a non-`.md` path emits a
+  warning and skips it
+- The detection word list is intentionally short and conservative —
+  a clean run is **necessary but not sufficient**; the agent still
+  owns the final language judgement
+- Frontmatter (`--- … ---` at file head) is exempt; descriptions and
+  YAML keys can use international characters where the schema allows
 
 ## Do NOT
 
-- Do NOT silence by deleting trigger words from
-  `scripts/check_md_language.py`; extend the allow-list instead
-- Do NOT use the ignore marker as a generic mute
-- Do NOT skip the gate "because the file is small"
+- Do NOT silence the checker by deleting trigger words from
+  `scripts/check_md_language.py`; extend the allow-list (anchor
+  blocks, ignore marker) instead
+- Do NOT add the ignore marker to body prose just to push a save
+  through; the marker is for meta-documentation that quotes tokens,
+  not a generic mute
+- Do NOT skip the gate "because the file is small" — `language-and-tone`
+  § Detection heuristic applies to every save under the four trees
 
 ## Cloud Behavior
 
-Cloud surfaces (Claude.ai Web, Skills API) ship without the script,
-so this skill is **inert** there — apply the heuristic from
-[`language-and-tone`](../../rules/language-and-tone.md) manually.
+On cloud surfaces (Claude.ai Web, Skills API) the checker script is
+not shipped, so this skill is **inert** — the agent applies the
+heuristic from [`language-and-tone`](../../rules/language-and-tone.md)
+manually before emitting the file.

package/.agent-src/skills/override-management/SKILL.md

@@ -31,11 +31,11 @@ Changes to `.augment/` affect ALL projects. Use overrides instead.
 
 ## Procedure: Create an override
 
-Before creating, understand the original:
+Before creating an override, understand the original:
 
-1. **Read the original** from `.augment/{type}/{name}` — understand purpose and behavior
-2. **Check existing overrides** in `agents/overrides/{type}/` — avoid duplicates
-3. **Identify what needs changing** — only override specific behavior that differs
+1. **Read the original** from `.augment/{type}/{name}` — understand its purpose, structure, and behavior.
+2. **Check for existing overrides** in `agents/overrides/{type}/` — avoid duplicates.
+3. **Identify what needs changing** — only override the specific behavior that differs for this project.
 
 When loading any skill, rule, or command:
 
@@ -69,7 +69,7 @@ Override files **must match the original filename** exactly:
 |---|---|
 | `.augment/rules/php-coding.md` | `agents/overrides/rules/php-coding.md` |
 | `.augment/skills/eloquent/SKILL.md` | `agents/overrides/skills/eloquent.md` |
-| `.augment/commands/feature-plan.md` | `agents/overrides/commands/feature-plan.md` |
+| `.augment/commands/feature/plan.md` | `agents/overrides/commands/feature/plan.md` |
 | `../../../docs/guidelines/php/controllers.md` | `agents/overrides/guidelines/php-controllers.md` |
 | `.augment/templates/roadmaps.md` | `agents/overrides/templates/roadmaps.md` |
 

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

@@ -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

@@ -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

@@ -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 `docs/guidelines/docs/readme-size-and-splitting.md` for full thresholds,
-splitting strategies, anti-patterns.
+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