@event4u/agent-config 1.9.1

package/.agent-src/skills/data-flow-mapper/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: data-flow-mapper
+description: "Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line."
+source: package
+---
+
+# data-flow-mapper
+
+> You are an analyst specialized in **static data-flow mapping**.
+> Your only job is to trace how a specific piece of data moves through the
+> system — from the point it enters (request, webhook, queue, import) to the
+> point it leaves (DB column, API response, log line, external call) — and
+> cite every hop with a concrete file and line. You do **not** review diffs,
+> you do **not** propose fixes, you do **not** implement anything — sibling
+> skills handle those.
+
+## When to use
+
+* Before editing code that reads, transforms, or persists user-supplied data
+* Before touching authorization, tenant scoping, or multi-step imports
+* When a bug report describes corrupted, leaked, or mis-scoped data and the
+  root cause is unknown
+* When `threat-modeling` or `authz-review` needs a concrete trace of one asset
+
+Do NOT use when:
+
+* No data crosses a trust boundary — skip entirely
+* You need to enumerate abuse cases — route to
+  [`threat-modeling`](../threat-modeling/SKILL.md)
+* You need end-to-end access-control analysis — route to
+  [`authz-review`](../authz-review/SKILL.md)
+* You need impact analysis of a change across jobs, events, migrations —
+  route to [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md)
+* You need to reproduce a bug interactively — route to
+  [`systematic-debugging`](../systematic-debugging/SKILL.md)
+
+## Procedure
+
+### 1. Pin the data element
+
+Name the exact field or object under analysis — e.g. *"order.total_cents from
+create-order request through to the invoice email"*. If the scope is unclear,
+stop and ask. Never map an imagined flow.
+
+### 2. Identify entry and egress
+
+List every entry point that can introduce the element (route body, webhook
+payload, queue job, CSV import, seeded fixture) and every egress (DB column,
+API response, log channel, external service call, derived record). Cite files.
+
+### 3. Inspect each hop
+
+Trace a single path end-to-end and record each hop in order:
+
+| Hop | What to record |
+|---|---|
+| Source | How the value arrives (param, header, cookie, body, message body) |
+| Validation | Rule set applied; file:line |
+| Normalization | Casting, trimming, canonicalization; file:line |
+| Authorization | Which policy/scope gates this hop; file:line |
+| Transformation | Business logic that derives or mutates it; file:line |
+| Persistence | Table.column or cache key; type + nullable |
+| Retrieval | Query path; scopes applied on read |
+| Egress | Response field, log line, external call; filter/mask applied |
+
+If the path forks (e.g. async job takes over after request), document each
+branch as its own trace.
+
+### 4. Analyze invariants and gaps
+
+For every hop, name:
+
+- Type expected vs type actually carried
+- Trust level (untrusted at entry → trusted after which step?)
+- Silent transformations (type juggling, encoding changes, locale coercion)
+- Missing hops (no validation? no scope on retrieval? no masking on egress?)
+
+## Validation
+
+Before finalizing the map, confirm:
+
+1. Every hop has a file:line citation — no generic "then it goes to the service"
+2. The trace starts at a real entry and ends at a real egress (not in the middle)
+3. Type and nullability are stated at persistence and at egress
+4. Every fork in the path is either traced or explicitly marked out of scope
+5. You have NOT inferred flow from naming alone — every link is verified by reading code
+6. You have NOT produced a generic architecture diagram; this is a specific trace
+
+## Output format
+
+```
+Skill:   data-flow-mapper
+Target:  <data element — one line>
+
+Entries:
+  - <METHOD /route or job/event name>  (file:line)
+Egresses:
+  - <response field / column / log / external>  (file:line)
+
+Trace (entry → egress):
+  1. <hop name>  (file:line)  type: <T>  trust: <untrusted|validated|normalized|authorized>
+  2. ...
+  N. <egress>    (file:line)  filter: <what is stripped/masked or "none">
+
+Forks:
+  - <branch condition> → see Trace 2 below
+  Trace 2: ...
+
+Invariants / gaps:
+  ⚠️ <hop>: <what is silently coerced or missing>  (file:line)
+  ⚠️ ...
+
+Open questions:
+  - <anything that could not be determined from static reading>
+```
+
+Required fields (ordered):
+
+1. **Skill** and **Target** — one-line data-element summary
+2. **Entries** and **Egresses** — every point with file:line
+3. **Trace** — ordered hops, each with file:line, type, trust state
+4. **Forks** — any branching paths, either traced or marked out of scope
+5. **Invariants / gaps** — silent coercions and missing hops with file:line
+6. **Open questions** — anything unresolved by static reading
+
+Runtime confirmation (e.g. *"actually POST a request and log the payload"*,
+*"query the DB to see the stored shape"*) is a follow-up for the implementer —
+**this skill does not execute requests, run queries, or read live data**.
+
+## Gotcha
+
+* **Naming-based inference** — a method called `sanitize()` may not actually
+  sanitize. Read the body, don't trust the name.
+* **Missing fork** — the request path writes to DB; a job reads it and emails
+  it. If you stop at persistence you missed half the trace.
+* **Silent type coercion** — framework middleware often casts strings to
+  ints or trims whitespace. Mark these as explicit hops.
+* **Confusing validation with authorization** — a FormRequest-style validator
+  is a validation hop, not an authorization hop. They are distinct.
+* **Tenancy scope on retrieval** — the write path was tenant-scoped; the read
+  path joined on a global table and leaked. Check both directions.
+* **Stating the map without line numbers** — a hop without file:line is a
+  guess. Reject your own output if any citation is missing.
+
+## Do NOT
+
+* NEVER return `clean` out of politeness when hops are undocumented — mark them `❌ unresolved`
+* NEVER silently fall back to an architecture-level description when asked for a specific-element trace
+* NEVER claim a hop exists based on naming without reading the code
+* NEVER merge multiple entry points into one trace — each entry gets its own trace or an explicit "same path from step N" note
+
+## References
+
+- **OWASP ASVS v4.0.3 V5** — Validation, Sanitization and Encoding — baseline
+  for naming validation / normalization hops.
+  [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
+- [`threat-modeling`](../threat-modeling/SKILL.md),
+  [`authz-review`](../authz-review/SKILL.md),
+  [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md),
+  [`systematic-debugging`](../systematic-debugging/SKILL.md) — sibling analysis skills.

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

@@ -0,0 +1,91 @@
+---
+name: database
+description: "Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'."
+source: package
+---
+
+# database
+
+## When to use
+
+Use when designing schemas, optimizing queries, adding indexes, or troubleshooting database performance.
+
+Do NOT use when:
+- Writing Eloquent models (use `eloquent` skill)
+- Creating migrations only (use `migration-creator` skill)
+
+## Procedure: Optimize a query
+
+### Step 0: Inspect
+
+1. Read project docs in `agents/docs/` for database architecture.
+2. Check `config/database.php` for connection definitions.
+3. Detect engine: check `.env` driver and `docker-compose.yml`.
+
+### Step 1: Diagnose
+
+Run `EXPLAIN` / `EXPLAIN ANALYZE`:
+
+```sql
+EXPLAIN ANALYZE SELECT * FROM projects WHERE customer_id = 42 AND status = 'active';
+```
+
+Check for: full table scans (`type=ALL`), missing indexes (`key=NULL`), filesort, temporary tables.
+
+### Step 2: Fix
+
+- Add missing indexes (most selective column first in composites)
+- Rewrite anti-patterns (subquery → JOIN, `OFFSET` → cursor, `SELECT *` → specific columns)
+- Add eager loading for N+1 queries
+- Always paginate list endpoints
+
+### Step 3: Verify
+
+Re-run `EXPLAIN` and confirm improved plan.
+
+## Schema awareness (anti-hallucination)
+
+**Never guess table or column names.** Verify before writing queries/migrations:
+
+1. **Read migrations** — source of truth
+2. **Read models** — `$table`, `$connection`, `$fillable`, `$casts`, relationships
+3. **Run schema queries** — `php artisan tinker --execute="Schema::getColumnListing('table')"`
+4. **Check project docs** — `agents/docs/` for conventions
+
+| Trap | Reality |
+|---|---|
+| Assuming column exists | Check migration/model first |
+| Wrong table prefix | Customer tables may have prefixes |
+| Wrong connection | `api_database` vs `customer_database` — verify |
+| Inventing pivot tables | Check if they actually exist |
+
+## Conventions
+
+→ See guideline `php/database.md` for indexing, transactions, migrations, multi-connection patterns.
+
+## Output format
+
+1. Migration file or query change with EXPLAIN analysis
+2. Index recommendations with rationale
+
+## Gotcha
+
+- Check existing indexes before adding — duplicates waste write performance.
+- Consider multi-tenant implications — queries may need customer DB scoping.
+- `EXPLAIN` output varies between MariaDB and MySQL.
+- Don't use `TEXT` in WHERE without prefix index.
+
+## Do NOT
+
+- Do NOT guess table/column names — verify against migrations or models first.
+- Do NOT add indexes without checking existing ones — duplicates waste write performance.
+- Do NOT use `float` for money — use `decimal`.
+
+## Auto-trigger keywords
+
+- database
+- MariaDB
+- MySQL
+- migration
+- indexing
+- query optimization

package/.agent-src/skills/dependency-upgrade/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: dependency-upgrade
+description: "Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification."
+source: package
+---
+
+# dependency-upgrade
+
+## When to use
+
+Use this skill when upgrading Composer packages, npm packages, or any project dependency.
+
+Do NOT use when:
+- Installing new dependencies for the first time
+- Routine code changes unrelated to package versions
+
+## Procedure: Upgrade a dependency
+
+### 1. Assess
+
+Before upgrading:
+
+- **Read the changelog** for every version between current and target.
+- **Identify breaking changes** — look for "BREAKING", "BC break", major version bumps.
+- **Check deprecation notices** — code using deprecated APIs needs updating.
+- **Review upgrade guides** — many packages provide migration docs.
+- **Check PHP/Node version requirements** — does the new version need a newer runtime?
+
+### 2. Plan
+
+Categorize changes needed:
+
+| Category | Action |
+|---|---|
+| No breaking changes | Upgrade directly |
+| Deprecation warnings | Upgrade, then fix deprecations |
+| Breaking changes (small) | Fix code, then upgrade |
+| Breaking changes (large) | Create a roadmap, upgrade in steps |
+| Peer dependency conflicts | Resolve conflicts before upgrading |
+
+### 3. Execute
+
+#### Composer (PHP)
+
+```bash
+# Check outdated packages
+composer outdated
+
+# Upgrade a specific package
+composer update vendor/package
+
+# Upgrade with version constraint change
+composer require vendor/package:^3.0
+
+# Dry-run to see what would change
+composer update vendor/package --dry-run
+```
+
+#### npm (JavaScript/TypeScript)
+
+```bash
+# Check outdated packages
+npm outdated
+
+# Upgrade a specific package
+npm update package-name
+
+# Upgrade to a new major version
+npm install package-name@latest
+
+# Check for vulnerabilities
+npm audit
+```
+
+### 4. Verify
+
+After upgrading, run the full verification pipeline:
+
+```bash
+# PHP/Laravel
+vendor/bin/phpstan analyse           # Check for type errors
+vendor/bin/rector process            # Auto-fix refactoring
+vendor/bin/ecs check --fix           # Auto-fix code style
+php artisan test                     # Run all tests
+
+# JavaScript
+npm run build     # Check build succeeds
+npm test          # Run all tests
+npm run lint      # Check code style
+```
+
+### 5. Document
+
+- Note the upgrade in the commit message: `chore: upgrade vendor/package from 2.x to 3.x`
+- If breaking changes required code modifications, describe them in the PR body.
+
+## Multi-package upgrades
+
+When upgrading multiple packages:
+
+- **Upgrade one at a time** — easier to identify which upgrade broke something.
+- **Exception:** Tightly coupled packages (e.g., `laravel/framework` + `laravel/*`) can be upgraded together.
+- **Run tests after each upgrade** — don't batch upgrades and test once at the end.
+
+## Common pitfalls
+
+| Pitfall | Prevention |
+|---|---|
+| Upgrading without reading changelog | Always read the changelog first |
+| Upgrading all packages at once | One package at a time (or tightly coupled groups) |
+| Trusting `composer update` blindly | Use `--dry-run` first, review changes |
+| Ignoring deprecation warnings | Fix deprecations before they become errors |
+| Skipping tests after upgrade | Full test suite + PHPStan after every upgrade |
+| Lock file conflicts | Coordinate upgrades with the team |
+
+## Version constraint guidelines
+
+| Constraint | Meaning | When to use |
+|---|---|---|
+| `^2.0` | `>=2.0.0 <3.0.0` | Default — allows minor + patch updates |
+| `~2.1` | `>=2.1.0 <2.2.0` | Strict — allows only patch updates |
+| `2.1.*` | `>=2.1.0 <2.2.0` | Same as `~2.1` |
+| `>=2.0 <2.5` | Explicit range | When you know specific versions work |
+| `dev-main` | Latest commit | **Never in production** — only for development |
+
+## Security upgrades
+
+For security patches:
+
+- **Prioritize** — security upgrades should be fast-tracked.
+- **Check `composer audit`** / `npm audit` regularly.
+- **Patch versions** (e.g., 2.1.3 → 2.1.4) are usually safe to apply immediately.
+- **Still run tests** — even security patches can break things.
+
+## Vulnerability scanning when adding packages
+
+Before adding a **new** dependency (not just upgrading), run a security audit:
+
+### Composer (PHP)
+
+```bash
+# Check for known vulnerabilities in current dependencies
+composer audit
+
+# After adding a new package, re-check
+composer require vendor/new-package
+composer audit
+```
+
+### npm (JavaScript)
+
+```bash
+# Check before install
+npm audit
+
+# After adding, re-check
+npm install new-package
+npm audit
+```
+
+### What to check for new packages
+
+| Check | How | Why |
+|---|---|---|
+| **Known CVEs** | `composer audit` / `npm audit` | Direct vulnerabilities |
+| **Maintenance status** | GitHub: last commit, open issues | Abandoned packages are a risk |
+| **Dependency tree** | `composer show -t vendor/pkg` / `npm ls new-package` | Transitive dependencies may conflict |
+| **License compatibility** | `composer licenses` / check `package.json` | Legal compliance |
+| **Bundle size** (npm) | `npx bundlephobia new-package` | Impact on frontend bundle |
+
+### Conflict detection
+
+When `composer require` or `npm install` fails with conflicts:
+
+1. **Read the error** — which versions conflict?
+2. **Check if other packages need updating** — `composer why vendor/conflicting-pkg`.
+3. **Use `--dry-run`** first — `composer require vendor/pkg --dry-run`.
+4. **Never use `--ignore-platform-reqs`** in production — only for investigation.
+
+## Output format
+
+1. Updated dependency with version constraint change
+2. Breaking changes addressed with code modifications
+3. Test results confirming compatibility
+
+## Auto-trigger keywords
+
+- dependency upgrade
+- package update
+- breaking changes
+- changelog review
+
+## Gotcha
+
+- Don't upgrade multiple major versions at once — one major version per upgrade cycle.
+- The model tends to skip reading the CHANGELOG — breaking changes hide in minor releases too.
+- Always run the full test suite after upgrading, not just the affected tests.
+- Lock file conflicts after upgrade are expected — resolve by re-running `composer update`.
+
+## Do NOT
+
+- Do NOT manually edit `composer.lock` or `package-lock.json`.
+- Do NOT upgrade to `dev-*` versions in production branches.
+- Do NOT ignore failing tests after an upgrade — fix or revert.

package/.agent-src/skills/description-assist/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: description-assist
+description: "Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'."
+source: package
+---
+
+# description-assist
+
+## When to use
+
+* The user says "make this description pushier", "this description is weak",
+  "will this ever fire", "rewrite the description".
+* Called from within the Draft phase of one of the writing skills
+  (`skill-writing`, `rule-writing`, `command-writing`, `guideline-writing`).
+* Auditing a skill flagged by `audit_skill_descriptions.py` as `too-short`,
+  `no-trigger-prefix`, or `description_too_long` in `skill_linter.py`.
+
+Do NOT use this skill when:
+
+* The user wants to change the body, name, or procedure — one field per turn.
+* The content is not an agent artifact (READMEs, docs, commit messages).
+* The user explicitly asked for a fresh description — write it, don't audit.
+
+## The contract
+
+* **No silent edits.** Every proposed variant is a suggestion presented
+  with numbered options; the user picks before anything is written.
+* **No Claude API grading loop.** You reason from your context only. No
+  separate AI pass evaluates your suggestions.
+* **Max two rounds.** Propose → reject → refine → reject → stop. If the
+  second round is rejected, ask one clarifying question and exit.
+* **One field per turn.** Only `description`. Trigger phrases, name, and
+  body belong to their own turns.
+
+## Procedure
+
+### 1. Read the current description
+
+Open the target file. Read the `description:` value in full. If the value
+is missing, abort and route to the relevant writing skill instead.
+
+### 2. Inspect the description against four criteria
+
+Normative source: [`skill-quality`](../../rules/skill-quality.md) § *Description Triggering*.
+
+| Check | Pass when… |
+|---|---|
+| **Length** | ≤ 200 characters (soft cap; linter warns `description_too_long`) |
+| **Trigger prefix** | Starts with "Use when …" or equivalent trigger phrasing |
+| **Trigger classes** | Names ≥ 2 of: domain, symptom, user phrasing, tool, file type |
+| **Undertrigger tail** | Ends with "… even if the user doesn't say `{name}`" or equivalent |
+
+Report which checks pass / fail in one compact line — **not** a long essay.
+
+### 2b. Check for trigger-eval evidence (skills only)
+
+If the target is a skill, check for a trigger-eval report:
+
+* `.agent-src.uncompressed/skills/{name}/evals/triggers.json` — the expected-trigger corpus
+* `evals/last-run.json` — the most recent runner output (see
+  [`scripts/skill_trigger_eval.py`](../../../scripts/skill_trigger_eval.py))
+
+If `last-run.json` exists and contains failed queries for this skill,
+extract the failure patterns and **use them to inform step 3 variants**.
+
+Example:
+
+```
+Eval evidence (evals/last-run.json, 2026-04-21, router=anthropic):
+  • 3/5 should-trigger passed
+  • failed queries share phrasing: "my E2E keeps flaking on CI"
+  • → one variant in step 3 should incorporate "flaky CI" vocabulary
+```
+
+If no `last-run.json` exists, skip this step silently. Do **not** run the
+evaluator from this skill — eval execution is a separate user action
+(costs API tokens, see `road-to-trigger-evals.md` Phase 2).
+
+For rules, commands, and guidelines: skip this step entirely — they do
+not have evals.
+
+### 3. Propose 2–3 alternatives
+
+Each variant:
+
+* Fixes at least one failed check from step 2.
+* If eval evidence was found in step 2b, **at least one variant must
+  address the dominant failure pattern**. Label it *"addresses eval
+  failure: <pattern>"* in the rationale.
+* Stays under 200 characters.
+* Has a one-line rationale ("adds symptom trigger", "tightens length",
+  "adds undertrigger tail", "addresses eval failure: flaky CI").
+* Is numbered (per [`user-interaction`](../../rules/user-interaction.md) rule).
+
+Format:
+
+```
+Current (156 chars, missing undertrigger tail):
+  "Use when writing Playwright E2E tests — browser automation, visual
+   regression, Page Objects."
+
+> 1. Adds undertrigger tail, 189 chars
+>    "Use when writing Playwright E2E tests — browser automation, visual
+>     regression, Page Objects — even if the user doesn't say Playwright."
+> 2. Adds symptom trigger 'flaky CI', 193 chars
+>    "Use when writing Playwright E2E tests — flaky CI, Page Objects,
+>     fixtures, visual regression — even if the user doesn't say Playwright."
+> 3. Skip — keep current
+```
+
+### 4. Wait for the user
+
+Do not edit the file yet. Wait for the user's numbered pick or free-text
+counter-proposal.
+
+### 5. Apply the picked variant
+
+Only after the user picks:
+
+* Edit the frontmatter in `.agent-src.uncompressed/{kind}/{name}.{md,SKILL.md}`.
+* Re-copy / re-sync as the target artifact's writing skill prescribes.
+* Run `python3 scripts/skill_linter.py {path}` — must report 0 FAIL.
+* Report the diff and exit.
+
+### 6. Max two rounds
+
+If the user rejects all variants twice, ask **one** clarifying question
+(e.g. "What symptom phrase best captures when this skill should fire?")
+and stop. Do not loop further.
+
+## Output format
+
+1. One-line inspection verdict ("3/4 pass, missing undertrigger tail")
+2. Optional one-line eval evidence note if `last-run.json` was found
+3. 2–3 numbered variants with rationale + char count
+4. A "skip — keep current" option
+5. On apply: diff snippet + linter verdict
+
+## Gotchas
+
+* Proposing variants longer than 200 characters — linter will reject.
+* Changing anything except `description` — out of scope, separate turn.
+* Running a secondary AI pass to grade your own proposals — forbidden.
+* Applying a variant without explicit numbered pick from the user.
+* Skipping the linter after apply — must be 0 FAIL.
+* Looping beyond round 2 — the rule caps at two rounds, then clarify and stop.
+
+## Do NOT
+
+* Do NOT call the Claude API to score proposals
+* Do NOT edit the file before the user picks
+* Do NOT propose more than 3 variants in one turn
+* Do NOT change the skill name, body, or trigger phrases in the same turn
+* Do NOT silently strip or reword quotes inside the description value
+* Do NOT run `scripts/skill_trigger_eval.py` from inside this skill — eval
+  execution spends API tokens and is a separate user action
+
+## Examples
+
+Inspection verdict (good — compact):
+
+> 2/4 pass. Missing: trigger prefix ("Use when …"), undertrigger tail.
+> Length OK (142), trigger classes OK (domain + symptom).
+
+Inspection verdict (bad — essay):
+
+> After reviewing the description, I noticed it has several areas that
+> could be improved. For instance, the length is fine, but the phrasing
+> could be stronger. Additionally, we should consider…