@event4u/agent-config 1.33.0 → 1.35.0

package/.agent-src/skills/fe-design/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: fe-design
 description: "Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py."
+personas:
+  - frontend-engineer
 source: package
+domain: engineering
 ---
 
 # Frontend Design Skill (Reference)
@@ -200,7 +203,7 @@ Step indicator (1 — 2 — 3)
 
 When `directives/ui/design.py` (or any caller) cites this skill:
 
-1. **Confirm the audit ran first** — `state.ui_audit` from [`existing-ui-audit`](../existing-ui-audit/SKILL.md) is mandatory. Stop and request the audit if missing.
+1. **Inspect `state.ui_audit` first** — review the audit produced by [`existing-ui-audit`](../existing-ui-audit/SKILL.md); it is mandatory. Stop and request the audit if missing.
 2. **Pick the smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste the whole skill.
 3. **Defer to audit findings** — when the audit pins a project pattern (token, primitive, layout convention), use it. The heuristics here are fallbacks for gaps, not overrides.
 4. **Defer to the stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from the dispatched impl skill, never from this reference.

package/.agent-src/skills/feature-planning/SKILL.md

@@ -2,6 +2,7 @@
 name: feature-planning
 description: "Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap."
 source: package
+domain: product
 ---
 
 # feature-planning

package/.agent-src/skills/file-editor/SKILL.md

@@ -2,6 +2,7 @@
 name: file-editor
 description: "Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled."
 source: package
+domain: process
 execution:
   type: assisted
   handler: shell

package/.agent-src/skills/finishing-a-development-branch/SKILL.md

@@ -2,6 +2,7 @@
 name: finishing-a-development-branch
 description: "Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'."
 source: package
+domain: process
 ---
 
 # finishing-a-development-branch

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

@@ -2,6 +2,7 @@
 name: flux
 description: "Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives."
 source: package
+domain: engineering
 ---
 
 # flux

package/.agent-src/skills/form-handler/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: form-handler
+description: "Use when designing or reviewing a form — validation timing, error display, submission lifecycle, optimistic UI, dirty/pristine state, idempotency — even on 'why does submit double-fire?'."
+personas:
+  - frontend-engineer
+source: package
+domain: engineering
+---
+
+# form-handler
+
+> Pick the validation timing, lay out error placement, sequence the
+> submission lifecycle, and decide where (and whether) to use
+> optimistic UI. Stack-agnostic — Livewire, Inertia, React Hook Form,
+> server-rendered Blade — the lens is the same. Pair with
+> [`laravel-validation`](../laravel-validation/SKILL.md) for
+> server-side rules and [`accessibility-auditor`](../accessibility-auditor/SKILL.md)
+> for label / error a11y.
+
+## When to use
+
+- A new form is being designed (login, signup, settings, multi-step
+  wizard) and the validation strategy is unsettled.
+- A form bug shows up: double-submission, lost data on validation
+  fail, error not announced, optimistic update flicker.
+- A wizard or multi-step flow needs state across steps and the
+  ownership of dirty / pristine state is unclear.
+- German triggers: "Formular bauen", "wann validieren?",
+  "Submit feuert doppelt".
+
+Do NOT use when:
+
+- The screen is read-only / display-only — no form, skip.
+- The question is purely server-side validation rules — route to
+  [`laravel-validation`](../laravel-validation/SKILL.md) (or the
+  stack equivalent).
+- The question is form *layout* / spacing — route to
+  [`fe-design`](../fe-design/SKILL.md) or
+  [`tailwind-engineer`](../tailwind-engineer/SKILL.md).
+
+## Procedure
+
+### 1. Identify field types, pick validation timing
+
+Inspect every field on the form (text, password, async-checked,
+file, multi-step) before choosing timing. Three knobs, picked per
+field:
+
+| Timing | When |
+|---|---|
+| On submit only | Forms with privacy concerns (passwords); short forms |
+| On blur | Default — feedback when the user finishes the field |
+| On change (debounced) | Typing-feedback fields (username availability, password strength) |
+
+Avoid validate-on-change for the whole form — premature errors
+shame the user. Username-availability is the canonical exception.
+
+### 2. Lock the error display contract
+
+Per field: error message location (below field), text-based
+(never colour-only), `aria-describedby` wired, focus moves to
+**first** error on submit-fail. Per form: a summary box at top
+that lists every error with anchor links — required for forms
+> 5 fields and any wizard step.
+
+### 3. Sequence the submission lifecycle
+
+Order matters; bake into one helper:
+
+1. Disable the submit button (idempotency).
+2. Run client-side validation; bail on failure with focus to
+   first error.
+3. Mark optimistic state if applicable (step 5).
+4. POST to server.
+5. On 2xx: clear dirty state, show success, route or reset.
+6. On 4xx: surface field errors per the display contract; restore
+   submit button; **do not** lose user input.
+7. On 5xx: keep input, show retry CTA, log to error tracker.
+
+A submit handler that skips step 1 is a duplicate-record bug
+waiting to fire on slow networks.
+
+### 4. Decide on optimistic UI per action
+
+Optimistic UI is only safe when **rollback is cheap and visible**:
+toggling a like, marking read, in-list reorder. It is unsafe for:
+multi-field forms, money movements, anything with downstream
+notifications. Default to non-optimistic; opt in per action with
+a documented rollback path.
+
+### 5. Track dirty state and unsaved-changes guard
+
+Pristine = identical to the server's last-known value. Dirty =
+any difference. On route-leave with dirty form, prompt
+confirmation (browser `beforeunload` for full nav, in-app modal
+for client-side route changes). For wizards, dirty state is
+per-step; submit at step N validates only that step's fields,
+final submit re-validates the whole payload server-side.
+
+## Output format
+
+Return:
+
+1. Validation contract — per-field timing + error-display rules.
+2. Submit lifecycle — the 7-step sequence with any deviations called out.
+3. Risk surface — optimistic-UI rollback path, dirty guard, idempotency,
+   server contract (endpoint, status codes, error shape).
+
+Concrete shape:
+
+```
+Form:               <name / route>
+Validation timing:  per field — <field: timing>
+Error display:      below field + summary box (≥ 5 fields)
+Submit lifecycle:   <list of steps 1–7 with any deviations>
+Optimistic UI:      <none | per action — list with rollback path>
+Dirty guard:        <yes/no — and the route-leave hook>
+Idempotency:        <strategy — disable + token? request id?>
+Server contract:    <endpoint, status codes, error shape>
+```
+
+## Gotcha
+
+- Disabling the submit button without showing a spinner reads as
+  "broken UI"; pair the disable with a visible busy state.
+- Validation-on-change for a password creates a bad UX: errors
+  appear before the user has finished typing. Validate-on-blur
+  with a single re-validate-on-change *after* the first failure.
+- Optimistic UI + slow network = the user sees success then a
+  rollback; that is worse than waiting. Pick optimistic only when
+  the request is < 300 ms p95.
+- Wizard "save & continue" buttons that POST per step double the
+  failure surface; only do this if the back-end can resume.
+  Otherwise hold state client-side and POST once at the end.
+
+## Do NOT
+
+- Do NOT trust client-side validation alone; server-side is the
+  contract. Client-side is UX, not safety.
+- Do NOT clear the form on validation failure; the user's input
+  is sacred until the server says it is safely saved.
+- Do NOT use colour as the only error signal; that is both an a11y
+  failure and a print / colour-blind regression.
+- Do NOT enable optimistic UI by default; the rollback story has
+  to fit on one line, or it does not ship optimistic.

package/.agent-src/skills/funnel-analysis/SKILL.md

@@ -4,6 +4,7 @@ description: "Use when diagnosing where a SaaS or product funnel leaks — visit
 status: active
 tier: senior
 source: package
+domain: product
 ---
 
 # funnel-analysis

package/.agent-src/skills/git-workflow/SKILL.md

@@ -2,6 +2,7 @@
 name: git-workflow
 description: "Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git."
 source: package
+domain: process
 execution:
   type: assisted
   handler: internal

package/.agent-src/skills/github-ci/SKILL.md

@@ -2,6 +2,7 @@
 name: github-ci
 description: "Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'."
 source: package
+domain: devops
 ---
 
 # github-ci

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

@@ -2,6 +2,7 @@
 name: grafana
 description: "Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana."
 source: package
+domain: devops
 ---
 
 # Grafana Skill

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

@@ -2,6 +2,7 @@
 name: guideline-writing
 description: "Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'."
 source: package
+domain: process
 ---
 
 <!-- cloud_safe: degrade -->

package/.agent-src/skills/incident-commander/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: incident-commander
+description: "Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'."
+personas:
+  - senior-engineer
+  - critical-challenger
+source: package
+domain: process
+---
+
+# incident-commander
+
+> Run the **coordination layer** during an incident: classify
+> severity, set comms cadence, hold a clean timeline, and draft the
+> post-mortem skeleton when the dust settles. This skill does **not**
+> debug the system — that is the engineer's job. The commander keeps
+> the room oriented so the engineer can think.
+
+## When to use
+
+- Production is degraded or down and someone needs to coordinate.
+- A critical job, queue, or third-party is failing and the team is
+  scrambling.
+- A near-miss happened and a post-mortem is being drafted.
+- German triggers: "Vorfall", "Prod ist down", "wer übernimmt
+  Comms?".
+
+Do NOT use when:
+
+- The system is healthy and the concern is a future outage —
+  route to [`risk-officer`](../risk-officer/SKILL.md) instead.
+- The user wants the bug fixed — route to `/bug-investigate` and
+  `/bug-fix`. The commander coordinates; engineers debug.
+- The incident is a security breach — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md) first; the
+  commander still runs comms but the response shape changes.
+
+## Procedure
+
+### 1. Inspect the signal and classify severity
+
+| SEV | Trigger |
+|---|---|
+| SEV-1 | User-facing outage, data loss risk, revenue impact |
+| SEV-2 | Major degradation, workaround exists |
+| SEV-3 | Single-feature broken, low blast radius |
+| SEV-4 | Internal-only, not user-visible |
+
+Pick the highest SEV any signal supports. Downgrades happen later
+with evidence; never start low to avoid noise.
+
+### 2. Set the comms cadence
+
+- **Internal channel** — single thread; no side-channels.
+- **Update interval** — SEV-1 every 15 min, SEV-2 every 30 min,
+  SEV-3/4 on state change.
+- **Status page** — update on SEV-1 / SEV-2; on by default unless
+  the user opts out with a stated reason.
+- **Stakeholder list** — who hears each update (eng-lead, PO,
+  support, leadership). Pre-decide so updates are not rewritten
+  per-recipient.
+
+### 3. Hold the timeline
+
+Append-only log: timestamp + actor + observation. No edits, no
+"actually it was earlier" — corrections are new entries. Drives
+the post-mortem and prevents memory rewrite.
+
+### 4. Drive to mitigation, not root cause
+
+During the incident, the question is *"what makes the bleeding
+stop?"* Root cause is for after. Document the gap explicitly —
+"mitigated, root cause unknown" is a valid intermediate state.
+
+### 5. Draft the post-mortem skeleton
+
+Once stable:
+
+- **Summary** — one paragraph, blame-free.
+- **Timeline** — copy from step 3.
+- **Impact** — users, duration, data, revenue.
+- **What went well** — at least one item; finding none is a smell.
+- **What went wrong** — process, tooling, signals, gaps.
+- **Action items** — owned, sized, with a trigger for completion.
+
+Hand off the skeleton; the engineer fills root cause and the team
+adds action items.
+
+### 6. Validate the handoff
+
+Before declaring the incident handed off, verify: SEV is set, comms
+cadence is announced, the timeline has at least one entry per
+update, mitigation state is explicit (`active` / `mitigated` /
+`resolved`), and a post-mortem owner is assigned. Ensure no field
+is left as the placeholder default.
+
+## Output format
+
+The incident record is a single block with these ordered fields:
+
+1. `SEV:` — one of `1` / `2` / `3` / `4`
+2. `State:` — one of `active` / `mitigated` / `resolved` / `post-mortem`
+3. `Started:` and `Channel:` — timestamp and single thread/room
+4. `Cadence:` and `Timeline:` — update interval and append-only log
+5. `Mitigation:`, `Root cause:`, `Post-mortem owner:` — explicit values
+   or `unknown`; never blank
+
+```
+Incident
+SEV:       1 | 2 | 3 | 4
+State:     active | mitigated | resolved | post-mortem
+Started:   <timestamp>
+Channel:   <thread / room>
+Cadence:   <interval>
+
+Timeline (append-only):
+  - <ts>  <actor>  <observation>
+  - ...
+
+Mitigation: <action> | unknown
+Root cause: <hypothesis> | unknown — investigation deferred to post-mortem
+Post-mortem owner: <role>
+```
+
+## Gotcha
+
+- The commander does not also debug. Splitting roles keeps the room
+  oriented; one person doing both starves comms.
+- "We do not need a post-mortem" is almost always wrong. Even
+  near-misses earn a one-page write-up.
+- The first SEV classification is rarely the final one — surface
+  upgrades / downgrades explicitly with a reason.
+
+## Do NOT
+
+- Do NOT debug from this skill; route to engineering skills.
+- Do NOT skip status-page updates on SEV-1 because "it'll be quick".
+- Do NOT close an incident without a post-mortem owner assigned.
+- Do NOT edit the timeline after the fact; corrections are new
+  entries.

package/.agent-src/skills/jira-integration/SKILL.md

@@ -2,6 +2,7 @@
 name: jira-integration
 description: "Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking."
 source: package
+domain: process
 ---
 
 # Jira Skill

package/.agent-src/skills/jobs-events/SKILL.md

@@ -2,6 +2,7 @@
 name: jobs-events
 description: "Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling."
 source: package
+domain: engineering
 ---
 
 # jobs-events

package/.agent-src/skills/judge-bug-hunter/SKILL.md

@@ -2,6 +2,7 @@
 name: judge-bug-hunter
 description: "Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'."
 source: package
+domain: quality
 ---
 
 # judge-bug-hunter

package/.agent-src/skills/judge-code-quality/SKILL.md

@@ -2,6 +2,7 @@
 name: judge-code-quality
 description: "Use when a diff needs a readability review — naming, single-responsibility, DRY, dead code, mismatch with codebase conventions — dispatched by /review-changes, /do-and-judge, /judge."
 source: package
+domain: quality
 ---
 
 # judge-code-quality

package/.agent-src/skills/judge-security-auditor/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: judge-security-auditor
 description: "Use when a diff may introduce security risk — authZ, injection, secrets, unsafe deserialization, SSRF, XSS, mass assignment — dispatched by /review-changes, /do-and-judge, /judge."
+personas:
+  - security-engineer
 source: package
+domain: quality
 ---
 
 # judge-security-auditor

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -4,6 +4,7 @@ description: "Use when a diff may lack tests — missing assertions, uncovered b
 personas:
   - qa
 source: package
+domain: quality
 ---
 
 # judge-test-coverage

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

@@ -2,6 +2,7 @@
 name: laravel
 description: "Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure."
 source: package
+domain: engineering
 ---
 
 # laravel

package/.agent-src/skills/laravel-horizon/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-horizon
 description: "Use when working with Laravel queues in production — Horizon dashboard, worker supervision, job metrics, balancing strategies — even when the user just says 'my jobs are piling up'."
 source: package
+domain: engineering
 ---
 
 # laravel-horizon

package/.agent-src/skills/laravel-mail/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-mail
 description: "Use when building Laravel emails — Mailables, Markdown templates, queued sending, attachments, previews — even when the user says 'send this as an email' without naming Mailables."
 source: package
+domain: engineering
 ---
 
 # laravel-mail

package/.agent-src/skills/laravel-middleware/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-middleware
 description: "Use when creating or modifying Laravel middleware — request/response filtering, groups, priority, terminable middleware, or route-level assignment."
 source: package
+domain: engineering
 ---
 
 # laravel-middleware

package/.agent-src/skills/laravel-notifications/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-notifications
 description: "Use when sending notifications via mail, Slack, database, or custom channels — with queuing, on-demand recipients, and notification preferences."
 source: package
+domain: engineering
 ---
 
 # laravel-notifications

package/.agent-src/skills/laravel-pennant/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-pennant
 description: "Use when working with feature flags — Laravel Pennant, gradual rollouts, A/B testing, scope-based flags — even when the user just says 'hide this behind a flag' without naming Pennant."
 source: package
+domain: engineering
 ---
 
 # laravel-pennant

package/.agent-src/skills/laravel-pulse/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-pulse
 description: "Use when setting up Laravel Pulse — real-time dashboard, built-in cards, custom recorders, performance insights — even when the user just says 'I need app monitoring' without naming Pulse."
 source: package
+domain: engineering
 ---
 
 # laravel-pulse

package/.agent-src/skills/laravel-reverb/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-reverb
 description: "Use when configuring Laravel Reverb — the first-party WebSocket server with Pusher protocol compatibility, horizontal scaling, and Pulse monitoring."
 source: package
+domain: engineering
 ---
 
 # laravel-reverb

package/.agent-src/skills/laravel-scheduling/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-scheduling
 description: "Use when configuring Laravel task scheduling — cron expressions, frequency helpers, overlap prevention, maintenance mode, or output handling."
 source: package
+domain: engineering
 ---
 
 # laravel-scheduling

package/.agent-src/skills/laravel-validation/SKILL.md

@@ -2,6 +2,7 @@
 name: laravel-validation
 description: "Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it."
 source: package
+domain: engineering
 ---
 
 # laravel-validation