@event4u/agent-config 5.10.1 → 6.0.0

package/.agent-src/skills/persona-writing/SKILL.md

@@ -1,158 +0,0 @@
----
-model_tier: inherit
-name: persona-writing
-description: "Use when creating or editing a persona in .agent-src.uncondensed/personas/ — voice / focus / unique questions / output expectations — even when the user just says 'add a reviewer voice for X'."
-domain: process
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-<!-- cloud_safe: degrade -->
-
-# persona-writing
-
-## When to use
-
-* Creating a new persona file in
-  `.agent-src.uncondensed/personas/{id}.md`
-* Rewriting an existing persona (focus shift, output-expectation
-  change — not a typo fix)
-* Deciding whether a new reviewer voice should be a persona at all
-  (vs. a skill of its own)
-
-Do NOT use this skill when:
-
-* The content is a multi-step workflow → use
-  [`skill-writing`](../skill-writing/SKILL.md)
-* The content is a hard obligation the agent must always honor → use
-  [`rule-writing`](../rule-writing/SKILL.md)
-* The content describes the project's role-mode contract → that lives
-  in `docs/contracts/role-contracts.md`, not in personas
-
-## Persona vs skill vs role-mode — critical test
-
-| Intent | Artifact |
-|---|---|
-| "Agent should review through a specific lens" | **Persona** |
-| "Agent should run a multi-step workflow" | **Skill** |
-| "Agent's closing contract differs by role" | **Role-mode** (contract file) |
-
-A persona is **passive reference content** — it never triggers by
-description, never appears in `<available_skills>`. Skills cite
-personas via the `personas:` frontmatter key.
-
-## Procedure
-
-### 0. Drafting protocol
-
-Creating or materially rewriting a persona must go through
-Understand → Research → Draft per the
-[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
-rule. Inspect existing personas under
-`.agent-src.uncondensed/personas/` for overlap before writing a new
-one.
-
-### 1. Decide focus, not topic
-
-A persona owns **one focus**: automation-readiness, adversarial
-challenge, product-owner priorities, etc. If the focus needs three
-sentences, it is two personas.
-
-### 2. Draft the persona file
-
-Required sections:
-
-* `## Focus` — one paragraph, what this lens *cares about* and what
-  it *ignores*.
-* `## Unique questions` — 4–7 questions only this persona would ask.
-  Each question must be decidable against the artifact under review.
-* `## Output expectations` — what the persona produces (verdict
-  format, severity vocabulary, citation discipline).
-
-Optional: `## Anti-patterns this persona catches` — concrete examples
-the persona is calibrated to flag.
-
-### 3. Cite from at least one skill
-
-A persona that is not cited by any skill via the `personas:`
-frontmatter key is dead code. Either wire it into an existing skill
-or do not ship it.
-
-## Frontmatter shape
-
-```yaml
----
-id: <kebab-case-id>
-role: <Human-Readable Role>
-description: "One sentence: what this voice catches that others miss."
-tier: core | specialty
-mode: developer | product-owner | qa | stakeholder | none
-version: "1.0"
-source: package
----
-```
-
-The `mode:` field is advisory only — it suggests which role-mode the
-persona pairs naturally with; it does not bind.
-
-## Output format
-
-A single Markdown file at `.agent-src.uncondensed/personas/{id}.md`:
-
-1. Frontmatter (`id`, `role`, `description`, `tier`, `mode`,
-   `version`, `source`)
-2. `## Focus` — one paragraph, what the lens cares about and ignores
-3. `## Unique questions` — 4–7 decidable questions
-4. `## Output expectations` — verdict format, severity vocabulary
-
-Length: ≤ 80 lines for a tier-core persona; longer signals the focus
-is too broad.
-
-## Gotchas
-
-- **Persona without a citing skill** — a persona that no skill
-  references via `personas:` never loads. Wire it in or do not ship.
-- **Focus drift across rewrites** — adding "and also …" to `## Focus`
-  is the first symptom of a second persona hiding inside the first.
-- **Vibe-based unique questions** — "Does this feel right?" cannot
-  be evaluated against the artifact. Replace with decidable triggers.
-- **Restating role-mode contracts** — closing-contract obligations
-  belong in `docs/contracts/role-contracts.md`, not in the persona
-  body.
-
-## Frugality Standards
-
-Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
-to every persona you author.
-
-**Examples in this artifact:**
-- Per the charter's default-terse rule, `## Focus` opens with what
-  the persona cares about, not "This persona was created to…".
-- Per the cite-don't-restate principle, link rules the persona
-  enforces; do not paste their text into the persona body.
-- Per the cheap-question check, `## Unique questions` lists decidable
-  questions only — drop any that read like vibe checks.
-
-**Pre-save self-check:**
-1. Does `## Focus` open with the lens, or with persona meta-narrative?
-2. Are unique questions decidable against the artifact alone?
-3. Are any questions duplicated from another persona?
-4. Is the persona cited by at least one skill via `personas:`?
-
-## Do NOT
-
-* Author a persona that nobody cites.
-* Restate Iron-Law text from rules inside `## Output expectations`.
-* Use ALL-CAPS Iron-Law fenced blocks — those belong in rules on the
-  [`kernel-membership`](../../../docs/contracts/kernel-membership.md)
-  list.
-* Ship a persona that overlaps an existing one's focus by more than
-  50 % — merge instead.
-
-## Examples
-
-See `.agent-src.uncondensed/personas/ai-agent.md` (automation
-readiness) and `critical-challenger.md` (adversarial review) for
-canonical structure.

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

@@ -1,213 +0,0 @@
----
-model_tier: medium
-name: react-shadcn-ui
-description: "Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack."
-domain: engineering
-workspaces:
-  - engineering
-packs:
-  - react
-trust:
-  level: professional
-install:
-  default: false
-  removable: true
----
-
-# react-shadcn-ui
-
-## Compatibility
-
-- **Tested against:** `shadcn@2.1`, Tailwind CSS `3.x`, React `18+`.
-- 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).
-
-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.
-
-## 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. 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.
-- **Anti-AI-slop: shadcn-default look.** The out-of-the-box shadcn
-  theme + `Inter`-as-system-fallback + neutral grays reads as
-  template across projects. Unless `state.ui_audit.design_tokens`
-  pins the neutral palette as the project's identity, the polish
-  step should match typography and color tokens to the design
-  brief's `aesthetic:` line (from `fe-design` aesthetic-direction).
-  Theme/font drift within a single audited project breaks
-  consistency — variation lives between projects, not between
-  components in the same surface.
-
-## Covered primitives
-
-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`.
-- **Layout:** `Card`, `Separator`, `Tabs`, `Accordion`, `ScrollArea`.
-- **Data display:** `Table` (with `@tanstack/react-table`), `Badge`,
-  `Avatar`, `Skeleton`, `Progress`.
-- **Feedback:** `Toast` (sonner), `Alert`.
-
-## Not covered — fall back to manual composition
-
-- 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.
-
-## 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, 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.**
-   - `states` → empty / loading / error / success / disabled coverage.
-   - `a11y` → ARIA labels, keyboard nav, focus order.
-
-### Step 1: Compose primitives
-
-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 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 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`).
-5. Keyboard: Tab through every focusable element; focus ring visible.
-
-## Output format
-
-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 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
-
-- Do NOT install `shadcn-ui` from npm — primitives are scaffolded.
-- 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 — 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 the project uses shadcn)
-- Radix primitive
-- Tailwind dark mode
-- React Hook Form + zod

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

@@ -1,242 +0,0 @@
----
-model_tier: high
-name: readme-reviewer
-description: "Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues."
-domain: quality
-execution:
-  type: assisted
-  handler: internal
-  allowed_tools: []
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# readme-reviewer
-
-## When to use
-
-- Reviewing a newly created or rewritten README
-- Validating a README matches the actual repository
-- Auditing README quality across repos
-- Checking for hallucinated setup, commands, or features
-
-Do NOT use when:
-
-- Only proofreading grammar or formatting
-- Writing a README from scratch → use `readme-writing` or `readme-writing-package`
-
-## Goal
-
-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
-
-- Evidence over assumption — verify every claim against the repo
-- Commands must exist — check `Taskfile.yml`, `Makefile`, `package.json scripts`
-- Examples must match real APIs — compare against source code
-- Quickstart quality matters more than completeness
-- A clean-looking README can still be technically wrong
-
-## Procedure
-
-### 1. Identify README type and audience
-
-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
-
-Inspect truth-defining files:
-
-- `package.json` / `composer.json` — name, scripts, dependencies
-- `Dockerfile` / `docker-compose.yml` — runtime setup
-- `Taskfile.yml` / `Makefile` — available commands
-- CI workflows — what gets tested
-- Source entrypoints — actual public API
-- Config files, tests, existing docs
-
-Verify: install steps exist, commands work, features are implemented,
-dependencies are real.
-
-### 3. Validate installation and setup
-
-Check:
-
-- Install command is correct and complete
-- Required post-install steps are documented
-- No hidden setup assumptions
-- Environment/config requirements are listed
-
-Flag: missing steps, incorrect steps, implied-but-unwritten steps.
-
-### 4. Validate usage examples
-
-Check:
-
-- First example is minimal and realistic
-- Example matches actual API (verify against source)
-- Example does not rely on undocumented setup
-- Example is not overly complex or abstract
-
-Flag: pseudo-code, oversized examples, API mismatches.
-
-### 5. Validate compatibility and requirements
-
-Check:
-
-- Runtime versions stated (PHP, Node, etc.)
-- Framework compatibility is explicit
-- Dependencies are declared
-
-Flag: missing compatibility, vague claims ("works with most versions"),
-unconfirmed broad support.
-
-### 6. Evaluate structure and clarity
-
-Check:
-
-- 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 instructions, generic template sections.
-
-### 7. Detect hallucinations
-
-Explicitly search for:
-
-- Commands not present in repo
-- Features not implemented
-- Setup steps not supported by scripts/configs
-- Assumptions about environment or tools
-
-Classify each finding:
-
-- **Confirmed incorrect** — verifiably wrong
-- **Likely incorrect** — no evidence found, needs verification
-- **Unclear** — cannot confirm or deny, needs human input
-
-### 8. Check scope, size, and splitting
-
-- README not overloaded with deep technical detail
-- Complex content belongs in `/docs`, not README
-- Important onboarding info not missing due to over-condensation
-
-Size checks:
-
-- **< 150 lines** — healthy
-- **150–300 lines** — expect a Table of Contents; flag if missing
-- **300–500 lines** — flag as overloaded; deep content should be in `/docs/`
-- **> 500 lines** — flag as broken entry point; hard split required
-
-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/` (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, and anti-patterns.
-
-### 9. Validate every link and detect orphans — MANDATORY
-
-For every internal link in the README:
-
-1. Resolve the path. `test -f` files, `test -d` directories. Strip
-   `#anchor` and `?query` before the check.
-2. For every anchor link (`file.md#section`), grep the target file for
-   the heading slug. Missing slug = broken anchor.
-3. Group findings:
-   - **broken** — target does not exist (❌ Critical)
-   - **anchor-broken** — file exists, anchor does not (⚠️ Major)
-   - **path-drift** — target moved but a valid path exists elsewhere
-     (⚠️ Major, propose the corrected path)
-
-For every documentation file referenced by the README, check whether
-it has any **other** references in the repo (`grep -r` over
-`AGENTS.md`, `docs/`, `.agent-src*/`, `.augment/`, `packages/`).
-Files referenced only by this README are **single-use** — note them
-so they can be moved or inlined later.
-
-For every doc under `/docs/` that the README **does not** link, check
-whether anything else in the repo links it. Files with zero inbound
-references are **orphan-candidates** — surface them, never delete
-silently.
-
-### 10. Currency check — drift detection
-
-The README may have been correct at write-time but drifted since.
-Compare the README's claims to the live repository:
-
-- **Counts** (badges like "Skills: 218") — recount from the source tree
-  and flag any drift > 0
-- **Commands** — every documented `task`, `npm run`, `npx`, or `bash`
-  call must exist in `Taskfile.yml`, `package.json scripts`, or the
-  named script file at its claimed path
-- **Profiles / user-types / packs** — list members against the live
-  directory listing
-- **Version pins** — runtime, framework, peer-dep versions stated in
-  README vs. the manifest's `engines` / `require` / `dependencies`
-- **Visual identity** — banner / hero image references resolve to real
-  files (not 404s in GitHub rendering)
-
-## Output format
-
-1. Produce three subsections in order: Summary, Findings, Confidence; no prose outside them.
-2. Findings table must use the severity vocabulary (❌ Critical / ⚠️ Major / ℹ️ Minor) and cite the exact section name.
-3. Close the report with a *Confidence* block that separates confirmed-correct, needs-verification, and unclear-due-to-missing-context.
-
-### 1. Summary
-
-| Field | Value |
-|---|---|
-| Repo type | {type} |
-| Audience | {audience} |
-| Overall | {short assessment} |
-
-### 2. Findings
-
-| # | Severity | Section | Issue | Fix |
-|---|---|---|---|---|
-| 1 | ❌ Critical | Install | Command `X` does not exist | Replace with `Y` |
-| 2 | ❌ Critical | Profile grid | Link `.agent-src.uncondensed/profiles/` 404s | Repoint to `packages/core/.agent-src.uncondensed/profiles/` |
-| 3 | ⚠️ Major | Badges | "Skills: 218" — live count is 207 | Update badge or note drift |
-| 4 | ⚠️ Major | Usage | Example uses deprecated API | Update to current API |
-| 5 | ℹ️ Minor | Structure | Requirements buried below usage | Move above install |
-| 6 | ℹ️ Minor | Docs | `docs/foo.md` only linked by README | Either inline or keep as standalone |
-
-Severity levels:
-
-- **❌ Critical** — breaks onboarding or is factually incorrect
-- **⚠️ Major** — confusing, incomplete, or misleading
-- **ℹ️ Minor** — clarity improvement, formatting, structure
-
-### 3. Confidence
-
-- What is confirmed correct
-- What needs human verification
-- What is unclear due to missing context
-
-## Gotcha
-
-- Model tends to trust the README instead of verifying against the repo
-- Model may miss subtle mismatches between examples and real APIs
-- 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
-
-- Do NOT assume README is correct without checking the repo
-- Do NOT ignore missing or broken setup steps
-- 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