@event4u/agent-config 1.33.0 → 1.35.0

package/.agent-src/skills/tailwind-engineer/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: tailwind-engineer
+description: "Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'."
+personas:
+  - frontend-engineer
+source: package
+domain: engineering
+---
+
+# tailwind-engineer
+
+> Apply utility-first discipline. Reach for design tokens before
+> arbitrary values, compose with `@apply` only where it earns its
+> keep, and reject inline `style=` drift. The skill is the **how**
+> for any Tailwind-stack screen; pair with
+> [`existing-ui-audit`](../existing-ui-audit/SKILL.md) for the **what
+> already exists** and [`fe-design`](../fe-design/SKILL.md) for the
+> **why**.
+
+## When to use
+
+- Writing or reviewing Tailwind classes in Blade, Livewire, or React
+  components.
+- A diff introduces inline `style=` for dynamic values, hex codes
+  not in `tailwind.config`, or `!important`.
+- Class lists balloon past ~12 utilities and the component is
+  hard to read or duplicate.
+- German triggers: "stile mit Tailwind", "design tokens nutzen",
+  "warum nicht inline?".
+
+Do NOT use when:
+
+- The stack is not Tailwind (vanilla CSS, CSS-in-JS, MUI) — skip.
+- The question is component shape, not styling — route to
+  [`ui-component-architect`](../ui-component-architect/SKILL.md).
+- An accessibility issue is the symptom (focus ring, contrast, hit
+  area) — route to [`accessibility-auditor`](../accessibility-auditor/SKILL.md).
+
+## Procedure
+
+### 1. Resolve to design tokens first
+
+Inspect `tailwind.config.{js,ts}` (or the equivalent `@theme` block)
+and identify the configured tokens. Map every requested colour,
+radius, spacing, shadow, font-size to a configured token. If the design hands you `#3B82F6`, use
+`bg-blue-500` (or the project's named token). Arbitrary values
+(`bg-[#3B82F6]`, `mt-[17px]`) are a smell — accept only with a
+one-line comment naming the design source.
+
+### 2. Compose, don't inline
+
+Inline `style="..."` is allowed only for **runtime-computed values**
+the build cannot know (server-pushed colour, animated transform
+target). Static values inline are a regression — replace with a
+utility, an arbitrary value, or a token extension.
+
+### 3. Order classes for scan-ability
+
+Group by axis: layout → box-model → typography → colour → state
+→ responsive. Most projects pin this with `prettier-plugin-tailwindcss`;
+if the plugin is configured, run it; if not, follow the order
+manually. Reviewer should read intent in one pass.
+
+### 4. Extract only when duplicated ≥ 3 times
+
+The first two repetitions are noise; the third is a pattern.
+Extract via:
+
+| Mechanism | When |
+|---|---|
+| Component (Blade/Livewire/React) | Different content, same shell |
+| Class string constant | Same shell, different consumers in same file |
+| `@apply` in CSS | Cross-file shared visual primitive (button, badge) |
+| Tailwind plugin | Tokens or variants, not classes |
+
+`@apply` for a one-off is a regression — keep utilities inline
+until the third use earns extraction.
+
+### 5. Responsive + dark + state in that order
+
+Class order within an axis: base → `sm:` → `md:` → `lg:` → `xl:` →
+`dark:` → state (`hover:`, `focus:`, `disabled:`, `aria-*:`).
+Mixing the order makes diffs noisy. State on top of dark on top
+of responsive matches Tailwind's cascade and reads top-down.
+
+## Output format
+
+When reviewing or proposing styles, return:
+
+1. Token map — every colour, spacing, radius, shadow, font-size mapped
+   to its configured token; arbitrary values flagged with the design
+   source they cite.
+2. Class list — ordered (layout → box-model → typography → colour →
+   state → responsive); inline-style use justified per element.
+3. Extraction + risk call-out — component / constant / `@apply` / none
+   with reason; risks named (arbitrary values, `!important`, dark-mode
+   gaps, non-token references).
+
+Concrete shape:
+
+```
+Element:        <selector or component name>
+Token map:      <colour/spacing/etc → config token>
+Class list:     <ordered classes>
+Inline style:   <only if runtime-computed; else "none">
+Extraction:     <component | constant | @apply | none — reason>
+Risks:          <arbitrary values, !important, dark-mode gaps>
+```
+
+## Gotcha
+
+- `space-x-*` / `space-y-*` collide with `flex-wrap` and RTL — use
+  `gap-*` on the flex/grid parent unless the design demands otherwise.
+- `dark:` variants need a token map in both modes; one-sided dark
+  styling is half a feature.
+- Arbitrary values (`mt-[17px]`) survive Tailwind upgrades but
+  break the design system; they accumulate silently.
+- `@apply` inside component CSS interacts with PurgeCSS — keep it
+  in files Tailwind scans, not in vendor CSS.
+
+## Do NOT
+
+- Do NOT add `!important` to win a specificity fight; restructure
+  the cascade or extract the conflicting style.
+- Do NOT introduce a new colour outside `tailwind.config` without
+  also adding the token; one-off hex codes drift the system.
+- Do NOT use `@apply` to avoid utility verbosity inside a single
+  component — extract the component instead.
+- Do NOT ship `style=` for static values; that is a CSS regression
+  the linter will not catch.

package/.agent-src/skills/tech-debt-tracker/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: tech-debt-tracker
+description: "Use when surfacing tech debt as trackable items — interest-vs-principal framing, prioritisation by carrying cost, repayment plan — even if the user just says 'this codebase is a mess'."
+personas:
+  - senior-engineer
+  - product-owner
+  - critical-challenger
+source: package
+domain: process
+---
+
+# tech-debt-tracker
+
+> Turn vague "this is messy" complaints into a **ranked debt ledger**
+> with carrying-cost estimates and a repayment plan the team can
+> execute. Frames debt as **principal** (the gap) plus **interest**
+> (what we keep paying because the gap exists). Output is copy-paste
+> ready; ticket / backlog write-back is user-gated.
+
+## When to use
+
+- The user lists code smells, dead code, or "we should refactor X"
+  and wants them turned into trackable items.
+- A retro surfaced multiple debt complaints; the team needs them
+  ranked, not all addressed at once.
+- A new initiative is about to add features on top of debt; the
+  team wants the carrying cost surfaced before committing.
+- German triggers: "Tech-Debt-Liste", "wo bremst es uns?",
+  "Aufräumen-Plan".
+
+Do NOT use when:
+
+- The user wants a single bug fixed — route to `/bug-fix`.
+- The complaint is about process, not code (slow CI, noisy alerts) —
+  surface as ops debt, not code debt; consider escalating to PO.
+- The "debt" is actually a missing feature — route to `po-discovery`.
+
+## Procedure
+
+### 1. Inspect inputs and collect candidate debt items
+
+Read the input (retro notes, code-review threads, pasted complaints,
+agent observations). Analyze each source for one candidate per
+bullet, no editing yet.
+
+### 2. Classify each item
+
+| Class | Examples |
+|---|---|
+| Code debt | Smells, duplication, dead code, weak tests, missing types |
+| Architecture debt | Coupling, layer violations, missing seams |
+| Operations debt | Manual deploys, alert fatigue, runbook gaps |
+| Knowledge debt | Stale docs, single-owner systems, missing onboarding |
+
+Items spanning two classes split into two entries — never merge.
+
+### 3. Estimate principal and interest
+
+For each item:
+
+- **Principal** — rough effort to repay (S / M / L; days, not hours).
+- **Interest** — what we keep paying *every week / sprint / month*
+  because the debt exists. Quantify or mark `unknown` (unknown
+  interest is itself a finding — surface it).
+
+Carrying cost = `interest × time-until-repaid`. High principal +
+zero interest → leave it. Low principal + recurring interest →
+top of the queue.
+
+### 4. Rank by `interest ÷ principal`
+
+Sort descending. The top ten are the candidates. Items below the
+top ten get a single line each (so they are not lost) but no
+deeper analysis — debt-list bloat is itself a debt.
+
+### 5. Shape a repayment plan
+
+For the top 3-5 items:
+
+- **Repayment shape** — single PR · multi-PR series · campaign ·
+  re-architecture.
+- **Owner role** — engineering · ops · PO · platform team.
+- **Trigger** — what makes us pay this *next* (e.g. "before adding
+  feature X", "when test runtime > 10 min", "next quarterly").
+
+Items without a trigger sit forever. A trigger that is "someday"
+is no trigger — push back.
+
+### 6. Issue a verdict
+
+| Verdict | When to issue |
+|---|---|
+| `track` | Items added to the ledger; no immediate action |
+| `pay-now` | One or more items have a trigger that already fired |
+| `block` | New feature work blocked until top item is repaid (rare) |
+
+### 7. Validate the ledger
+
+Verify before emitting: every top item has a class, principal,
+interest (or `unknown`), trigger, and owner; the ranking matches
+`interest ÷ principal`; tail items have one line each. Ensure no
+"someday" triggers and no agent-owned repayment owners slipped in.
+
+## Output format
+
+The ledger is a single block with these ordered fields:
+
+1. `Inventory:` — count and classes touched
+2. `Top items:` — numbered list ranked by `interest ÷ principal`,
+   each with class, principal, interest, trigger, owner, shape
+3. `Tail:` — one-line bullets for tracked-but-deferred items
+4. `Verdict:` — exactly one of `track` / `pay-now` / `block`
+5. `Next:` — handoff target (`/adr-create` or backlog write-back)
+
+```
+Tech-Debt Ledger
+Inventory: <count> items, <classes touched>
+
+Top items (interest ÷ principal):
+  1. [arch] <item>             Principal: M  Interest: high (3 hrs/sprint)
+        Trigger: <condition>  Owner: <role>  Shape: <PR / series / campaign>
+  2. [code] <item>             Principal: S  Interest: med  ...
+  ...
+
+Tail (tracked, no immediate action):
+  - <item>
+  - <item>
+
+Verdict: track | pay-now | block
+Next:    /adr-create (if a tradeoff lock is needed) | backlog write-back
+```
+
+## Gotcha
+
+- "Refactor X" is not a debt item — it is a wish. The item must
+  name *the gap* and *what it costs*.
+- Interest the team cannot measure is real but invisible. Mark
+  `unknown` and ask a probe ("how often do you hit this?") rather
+  than inventing a number.
+- A debt list with no trigger is paperwork. Reject items the team
+  has no plan to ever repay.
+
+## Do NOT
+
+- Do NOT enumerate every smell in the codebase — the top ten plus
+  a tail is the contract.
+- Do NOT propose repayment owners the agent itself owns; debt
+  repayment belongs to a human role.
+- Do NOT push items into Jira / Linear without explicit ask;
+  output is copy-paste ready, write-back is gated.
+- Do NOT silently inflate principal estimates to discourage repayment
+  the team should do.

package/.agent-src/skills/technical-specification/SKILL.md

@@ -2,6 +2,7 @@
 name: technical-specification
 description: "Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure."
 source: package
+domain: product
 council_depth: deep
 ---
 

package/.agent-src/skills/terraform/SKILL.md

@@ -2,6 +2,7 @@
 name: terraform
 description: "Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform."
 source: package
+domain: devops
 ---
 
 # terraform

package/.agent-src/skills/terragrunt/SKILL.md

@@ -2,6 +2,7 @@
 name: terragrunt
 description: "Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt."
 source: package
+domain: devops
 ---
 
 # terragrunt

package/.agent-src/skills/test-driven-development/SKILL.md

@@ -2,6 +2,7 @@
 name: test-driven-development
 description: "Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'."
 source: package
+domain: quality
 ---
 
 # test-driven-development

package/.agent-src/skills/test-performance/SKILL.md

@@ -2,6 +2,7 @@
 name: test-performance
 description: "Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives."
 source: package
+domain: quality
 ---
 
 # test-performance

package/.agent-src/skills/testing-anti-patterns/SKILL.md

@@ -2,6 +2,7 @@
 name: testing-anti-patterns
 description: "Use BEFORE writing or changing tests, adding mocks, or putting test-only methods on production classes — five Iron Laws and gates against mocking-the-mock, production pollution, silent partial mocks."
 source: package
+domain: quality
 ---
 
 # testing-anti-patterns

package/.agent-src/skills/threat-modeling/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: threat-modeling
 description: "Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation."
+personas:
+  - security-engineer
 source: package
+domain: quality
 council_depth: deep
 ---
 

package/.agent-src/skills/token-optimizer/SKILL.md

@@ -2,6 +2,7 @@
 name: token-optimizer
 description: "Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action."
 source: package
+domain: process
 execution:
   type: assisted
   handler: shell

package/.agent-src/skills/traefik/SKILL.md

@@ -2,6 +2,7 @@
 name: traefik
 description: "Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing."
 source: package
+domain: devops
 ---
 
 # Traefik Skill

package/.agent-src/skills/ui-component-architect/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: ui-component-architect
+description: "Use when shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — even on 'split this component'."
+personas:
+  - frontend-engineer
+source: package
+domain: engineering
+---
+
+# ui-component-architect
+
+> Decide the **shape** of a component tree before the markup is
+> written. Picks composition over inheritance, names the slot
+> contract, draws the controlled/uncontrolled axis, and stops
+> prop bags from growing into god-components. Stack-agnostic —
+> the same lens applies to Blade, Livewire, React, or Vue trees.
+> Pair with [`existing-ui-audit`](../existing-ui-audit/SKILL.md)
+> first; never invent components that already exist.
+
+## When to use
+
+- A new component / screen is being designed and the boundary
+  between parent and children is unclear.
+- An existing component has > 10 props, conditional rendering
+  trees nested ≥ 3 deep, or a `variant`-prop with > 4 values.
+- A primitive (button, card, dialog) is being added to the design
+  system and its API will be reused across teams.
+- German triggers: "wie schneide ich die Komponente?", "Slots
+  oder Props?", "controlled oder uncontrolled?".
+
+Do NOT use when:
+
+- The component is a one-off, used in one place, and unlikely to
+  be reused — over-architecting hurts more than it helps.
+- The question is **styling**, not shape — route to
+  [`tailwind-engineer`](../tailwind-engineer/SKILL.md).
+- The audit step has not run — route to
+  [`existing-ui-audit`](../existing-ui-audit/SKILL.md) first; reusing
+  beats inventing.
+
+## Procedure
+
+### 1. Inspect prior art, state the responsibility in one sentence
+
+Review existing components in the codebase for the same
+responsibility — extend rather than rebuild when a match is found.
+If none exists, write the new component's purpose: *"Renders a
+labelled input with inline error and hint."* If the sentence has an
+"and" joining two unrelated jobs, the component is two components.
+Reject the draft and split before continuing.
+
+### 2. Pick composition over inheritance
+
+Rules of thumb:
+
+| Pattern | When |
+|---|---|
+| Compound components (`Card.Header`, `Card.Body`) | Multiple slots with order semantics |
+| Children + named slots | One main child, plus 1–2 optional regions |
+| Render props / function-as-children | Caller controls rendering of internal state |
+| Polymorphic (`as` prop) | Same shell, different semantic element |
+| Inheritance / class-extension | Almost never — last resort for legacy adapters |
+
+Composition trades verbose call-sites for a tiny, stable component.
+Inheritance trades short call-sites for ABI fragility.
+
+### 3. Draw the controlled / uncontrolled axis
+
+For every piece of state (open, value, selected, expanded), pick:
+
+- **Controlled** — caller passes value + onChange. Caller owns
+  state. Use when state must sync across siblings or persist.
+- **Uncontrolled** — component owns state internally; caller reads
+  via ref or onChange callback. Use for ephemeral state local to
+  the component.
+- **Controlled with default** — both APIs supported via
+  `defaultValue` + optional `value`. The most flexible, also the
+  most code; reserve for design-system primitives.
+
+Mixing controlled / uncontrolled in the same prop without a
+default is the single largest source of "why doesn't my component
+update?" tickets.
+
+### 4. Cap the prop API
+
+Prop budget per component:
+
+| Tier | Cap |
+|---|---|
+| Primitive (Button, Input) | ≤ 6 props + `...rest` to underlying element |
+| Composite (Card, Dialog) | ≤ 8 props; prefer slots for variants |
+| Page section / feature shell | ≤ 4 props; everything else via context |
+
+Over-budget triggers a refactor: extract a config object, push
+state into context, or split into compound parts.
+
+### 5. Name the slot contract
+
+For every slot, document: required vs optional, expected element
+type or component, default rendering when absent, accessibility
+implications (does the slot become the accessible name?). Slots
+without contracts become "stuff a div in there and pray".
+
+## Output format
+
+Return:
+
+1. Responsibility + composition pick — single-sentence purpose, chosen
+   pattern (compound / slots / render-props / polymorphic) with the
+   one-line trade-off.
+2. State + prop API — controlled / uncontrolled / both per state piece,
+   prop list with type and purpose, slot inventory with a11y notes.
+3. Anti-case list — the combinations the component refuses to support
+   (the explicit "no" surface that callers can rely on).
+
+Concrete shape:
+
+```
+Component:        <Name>
+Responsibility:   <one sentence — reject if "and" joins two jobs>
+Pattern:          <compound | slots | render-props | polymorphic>
+State:            value=<controlled|uncontrolled|both>; open=<...>; ...
+Props (≤ tier):   [name: type — purpose]
+Slots:            [name: required? default? a11y note]
+Children:         <count, kind>
+Anti-cases:       <combinations the component refuses to support>
+```
+
+## Gotcha
+
+- `variant` props with > 4 values are usually two components in a
+  trench coat — split when the rendering branches diverge.
+- `as` polymorphism is cheap in TypeScript when typed via generics,
+  expensive without — the type cost is invisible in plain JS.
+- Compound components share state via context; nesting two
+  compound trees of the same family in one parent silently
+  crosses contexts — namespace the context per instance or
+  refuse the nesting.
+- "Render props" + memoization fight; if the function changes
+  every render, the child re-renders too. Stabilize via
+  `useCallback` or hoist.
+
+## Do NOT
+
+- Do NOT design a component without running
+  [`existing-ui-audit`](../existing-ui-audit/SKILL.md) first.
+  Reinventing primitives is the #1 source of design drift.
+- Do NOT use inheritance when composition fits — class-extension
+  hierarchies in UI age badly.
+- Do NOT ship a "kitchen-sink" prop (`config={...}`) just to dodge
+  the prop cap — that hides the API instead of taming it.
+- Do NOT push the architecture into the tracker as code AC — output
+  is a design note for refinement, not implementation steps.

package/.agent-src/skills/unit-economics-modeling/SKILL.md

@@ -4,6 +4,7 @@ description: "Use when modeling CAC, LTV, gross-margin payback, or contribution
 status: active
 tier: senior
 source: package
+domain: product
 ---
 
 # unit-economics-modeling

package/.agent-src/skills/universal-project-analysis/SKILL.md

@@ -2,6 +2,7 @@
 name: universal-project-analysis
 description: "ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills."
 source: package
+domain: discovery
 ---
 
 # universal-project-analysis

package/.agent-src/skills/upstream-contribute/SKILL.md

@@ -2,6 +2,7 @@
 name: upstream-contribute
 description: "Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package."
 source: package
+domain: process
 execution:
   type: assisted
   handler: internal

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -2,6 +2,7 @@
 name: using-git-worktrees
 description: "Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'."
 source: package
+domain: process
 ---
 
 # using-git-worktrees

package/.agent-src/skills/validate-feature-fit/SKILL.md

@@ -2,6 +2,7 @@
 name: "validate-feature-fit"
 description: "Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit"
 source: package
+domain: quality
 execution:
   type: assisted
   handler: internal

package/.agent-src/skills/verify-completion-evidence/SKILL.md

@@ -2,6 +2,7 @@
 name: verify-completion-evidence
 description: "Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs."
 source: package
+domain: quality
 ---
 
 # verify-completion-evidence