@event4u/agent-config 1.9.1

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

@@ -0,0 +1,205 @@
+---
+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
+---
+
+# laravel-reverb
+
+## When to use
+
+Use this skill for anything specific to **Laravel Reverb** as the WebSocket server:
+- Reverb installation, configuration, and environment setup
+- Reverb server deployment and scaling
+- Reverb-specific debugging and monitoring
+- Pusher protocol compatibility questions
+
+For **general WebSocket patterns**, broadcasting events, channel authorization,
+and Laravel Echo client setup, see the [websocket](../websocket/SKILL.md) skill.
+
+## Procedure: Set up Reverb
+
+1. **Install** — `php artisan install:broadcasting` or manual setup (see below).
+2. **Configure** — Set environment variables for Reverb host, port, app credentials.
+3. **Start server** — `php artisan reverb:start`.
+4. **Connect client** — Configure Laravel Echo with Reverb credentials.
+5. **Verify** — Confirm WebSocket connection in browser console, test event delivery.
+
+Laravel Reverb is Laravel's first-party, blazing-fast WebSocket server. It uses the
+**Pusher protocol**, making it compatible with Laravel Echo and any Pusher-compatible client.
+A single Reverb server can handle thousands of concurrent connections.
+
+## Installation
+
+```bash
+php artisan install:broadcasting
+```
+
+This scaffolds:
+- `config/broadcasting.php` with Reverb driver
+- `config/reverb.php` with server settings
+- `routes/channels.php` for channel authorization
+- `.env` variables for Reverb
+
+## Configuration
+
+### Environment variables
+
+```env
+REVERB_APP_ID=455493
+REVERB_APP_KEY=your-app-key
+REVERB_APP_SECRET=your-app-secret
+REVERB_HOST="localhost"
+REVERB_PORT=8080
+REVERB_SCHEME=http
+
+# Client-side (Vite)
+VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
+VITE_REVERB_HOST="${REVERB_HOST}"
+VITE_REVERB_PORT="${REVERB_PORT}"
+VITE_REVERB_SCHEME="${REVERB_SCHEME}"
+```
+
+### config/reverb.php
+
+Note: `REVERB_HOST` / `REVERB_PORT` are for client connections (hostname/port the client connects to).
+`REVERB_SERVER_HOST` / `REVERB_SERVER_PORT` are for the server binding (interface/port the server listens on).
+
+```php
+'servers' => [
+    'reverb' => [
+        'host' => env('REVERB_SERVER_HOST', '0.0.0.0'),
+        'port' => env('REVERB_SERVER_PORT', 8080),
+        'hostname' => env('REVERB_HOST'),
+        'options' => [
+            'tls' => [],
+        ],
+        'max_request_size' => 10_000,  // bytes
+        'scaling' => [
+            'enabled' => env('REVERB_SCALING_ENABLED', false),
+            'channel' => env('REVERB_SCALING_CHANNEL', 'reverb'),
+        ],
+        'pulse_ingest_interval' => 15,
+    ],
+],
+```
+
+### config/broadcasting.php
+
+```php
+'connections' => [
+    'reverb' => [
+        'driver' => 'reverb',
+        'key' => env('REVERB_APP_KEY'),
+        'secret' => env('REVERB_APP_SECRET'),
+        'app_id' => env('REVERB_APP_ID'),
+        'options' => [
+            'host' => env('REVERB_HOST'),
+            'port' => env('REVERB_PORT', 443),
+            'scheme' => env('REVERB_SCHEME', 'https'),
+            'useTLS' => env('REVERB_SCHEME', 'https') === 'https',
+        ],
+    ],
+],
+```
+
+## Running the server
+
+```bash
+# Start Reverb (foreground)
+php artisan reverb:start
+
+# Start with verbose output (debugging)
+php artisan reverb:start --debug
+
+# Production — use Supervisor or systemd
+# Reverb is a long-running process, it must be managed by a process monitor
+```
+
+### Supervisor config (production)
+
+```ini
+[program:reverb]
+command=php /path/to/artisan reverb:start
+autostart=true
+autorestart=true
+user=www-data
+redirect_stderr=true
+stdout_logfile=/var/log/reverb.log
+stopwaitsecs=3600
+```
+
+## Horizontal scaling
+
+Enable Redis-based scaling to run multiple Reverb instances behind a load balancer:
+
+```env
+REVERB_SCALING_ENABLED=true
+REVERB_SCALING_CHANNEL=reverb
+```
+
+Requires a shared Redis instance accessible by all Reverb servers.
+Connections and channel subscriptions are synced across servers via Redis pub/sub.
+
+## Monitoring with Pulse
+
+Reverb has built-in Laravel Pulse integration. Add the Reverb Pulse cards:
+
+```php
+// In your Pulse dashboard
+<livewire:reverb.connections />
+<livewire:reverb.messages />
+```
+
+## SSL/TLS in production
+
+Reverb itself does **not** handle TLS. Use a reverse proxy (Nginx, Traefik, Caddy)
+to terminate SSL and proxy WebSocket connections to Reverb:
+
+```nginx
+location /app {
+    proxy_pass http://127.0.0.1:8080;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_read_timeout 60s;
+    proxy_send_timeout 60s;
+}
+```
+
+## Core rules
+
+- **Reverb is a long-running process** — always use Supervisor/systemd in production.
+- **TLS via reverse proxy** — Reverb doesn't handle SSL directly.
+- **Scale with Redis** — enable `REVERB_SCALING_ENABLED` for multi-server setups.
+- **Monitor with Pulse** — use the built-in Pulse cards for connection/message metrics.
+- **Pusher protocol** — any Pusher-compatible client works (Laravel Echo, pusher-js, etc.).
+- **Max request size** — default 10KB, increase for large payloads if needed.
+
+## Output format
+
+1. Reverb configuration with server and scaling settings
+2. Broadcasting channel definitions and client integration
+
+## Auto-trigger keywords
+
+- Reverb
+- reverb:start
+- WebSocket server
+- Reverb scaling
+- Reverb deployment
+- Reverb configuration
+
+## Gotcha
+
+- Reverb requires a persistent process — it's not compatible with serverless deployments.
+- The model forgets to configure the `REVERB_HOST` and `REVERB_PORT` environment variables.
+- WebSocket connections bypass middleware — don't rely on session auth for channel authorization.
+
+## Do NOT
+
+- Do NOT expose Reverb directly to the internet without a reverse proxy for TLS.
+- Do NOT run `reverb:start` without a process monitor in production.
+- Do NOT confuse Reverb config with Pusher SaaS — Reverb is self-hosted.
+- Do NOT skip Redis when running multiple Reverb instances.

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

@@ -0,0 +1,167 @@
+---
+name: laravel-scheduling
+description: "Use when configuring Laravel task scheduling — cron expressions, frequency helpers, overlap prevention, maintenance mode, or output handling."
+source: package
+---
+
+# laravel-scheduling
+
+## When to use
+
+Use this skill when scheduling recurring tasks:
+- Artisan command scheduling
+- Job dispatching on a schedule
+- Closure-based scheduled tasks
+- Overlap prevention and maintenance mode handling
+
+## Procedure: Create a scheduled task
+
+### In routes/console.php (Laravel 11+)
+
+```php
+use Illuminate\Support\Facades\Schedule;
+
+Schedule::command('reports:generate')->dailyAt('06:00');
+Schedule::command('telescope:prune --hours=48')->daily();
+Schedule::command('queue:prune-batches --hours=48')->daily();
+Schedule::job(new CleanupTemporaryFiles())->hourly();
+```
+
+### Frequency helpers
+
+| Method | Schedule |
+|---|---|
+| `->everyMinute()` | Every minute |
+| `->everyFiveMinutes()` | Every 5 minutes |
+| `->everyFifteenMinutes()` | Every 15 minutes |
+| `->hourly()` | Every hour |
+| `->hourlyAt(17)` | Every hour at :17 |
+| `->daily()` | Daily at midnight |
+| `->dailyAt('13:00')` | Daily at 1 PM |
+| `->twiceDaily(1, 13)` | Daily at 1 AM and 1 PM |
+| `->weekly()` | Weekly on Sunday at midnight |
+| `->weeklyOn(1, '8:00')` | Weekly on Monday at 8 AM |
+| `->monthly()` | Monthly on the 1st at midnight |
+| `->monthlyOn(4, '15:00')` | Monthly on the 4th at 3 PM |
+| `->quarterly()` | Quarterly |
+| `->yearly()` | Yearly |
+
+### Cron expressions
+
+```php
+Schedule::command('reports:generate')->cron('0 6 * * 1-5'); // Weekdays at 6 AM
+```
+
+## Overlap prevention
+
+```php
+// Prevent overlapping — skip if previous instance is still running
+Schedule::command('import:customers')->hourly()->withoutOverlapping();
+
+// With custom expiration (minutes)
+Schedule::command('import:customers')->hourly()->withoutOverlapping(30);
+```
+
+## Conditional scheduling
+
+```php
+// Only in production
+Schedule::command('reports:send')->daily()->environments(['production']);
+
+// Custom condition
+Schedule::command('sync:data')->hourly()->when(function () {
+    return Config::boolean('services.sync.enabled');
+});
+
+// Skip condition
+Schedule::command('emails:send')->daily()->skip(function () {
+    return app()->isDownForMaintenance();
+});
+```
+
+## Output handling
+
+```php
+// Log output to file
+Schedule::command('reports:generate')
+    ->daily()
+    ->appendOutputTo(storage_path('logs/reports.log'));
+
+// Email output on failure
+Schedule::command('import:data')
+    ->daily()
+    ->emailOutputOnFailure('admin@example.com');
+```
+
+## Maintenance mode
+
+```php
+// Run even during maintenance mode
+Schedule::command('queue:work')->everyMinute()->evenInMaintenanceMode();
+```
+
+## Running the scheduler
+
+```bash
+# The scheduler itself runs every minute via system cron
+* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
+
+# Test locally
+php artisan schedule:work   # Runs scheduler in foreground
+php artisan schedule:list   # Show all scheduled tasks
+php artisan schedule:test   # Run a specific task interactively
+```
+
+## Grouped schedules
+
+```php
+// routes/console.php — include schedule groups
+Schedule::group('reports.php');
+Schedule::group('imports.php');
+
+// routes/console/reports.php
+Schedule::command('reports:daily')->dailyAt('06:00');
+Schedule::command('reports:weekly')->weeklyOn(1, '07:00');
+```
+
+## Core rules
+
+- **Always use `withoutOverlapping()`** for long-running tasks.
+- **Use `environments()`** to restrict production-only tasks.
+- **Log output** for debugging — use `appendOutputTo()`.
+- **Group related schedules** in separate files under `routes/console/`.
+- **Monitor failures** — use `emailOutputOnFailure()` or Horizon for queued jobs.
+- **One cron entry** — only `schedule:run` goes in crontab, everything else in Laravel.
+
+## Output format
+
+1. Schedule definition in console kernel or schedule method
+2. Overlap prevention and maintenance mode configuration
+
+## Auto-trigger keywords
+
+- schedule
+- cron
+- scheduled task
+- recurring job
+- schedule:run
+- withoutOverlapping
+
+### Validate
+
+- Verify schedule runs correctly: `php artisan schedule:list` shows the task.
+- Confirm `withoutOverlapping()` is set for long-running tasks.
+- Check that maintenance mode handling is configured if needed (`evenInMaintenanceMode()`).
+
+## Gotcha
+
+- `withoutOverlapping()` uses cache locks — if the cache is cleared, overlapping can still happen.
+- The model forgets `runInBackground()` for long-running tasks — without it, one task blocks the next.
+- Don't schedule tasks every minute unless absolutely necessary — it wastes server resources.
+
+## Do NOT
+
+- Do NOT add multiple cron entries — use Laravel's scheduler for everything.
+- Do NOT schedule heavy work directly — dispatch a queued job instead.
+- Do NOT forget `withoutOverlapping()` for tasks that may run longer than their interval.
+- Do NOT hardcode times — use environment-based config when schedules vary per environment.

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

@@ -0,0 +1,71 @@
+---
+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
+---
+
+# laravel-validation
+
+## When to use
+
+Use when creating FormRequests, validation rules, or custom rule objects.
+
+Do NOT use when:
+- Authorization logic only (use `security` skill)
+- API response format (use `api-design` skill)
+
+## Procedure: Create a FormRequest
+
+### Step 0: Inspect
+
+1. Check existing FormRequests — match style, naming, authorization, rule structure.
+2. Check existing custom rules — reuse before creating new ones.
+3. Check API error response format — match it.
+
+### Step 1: Create the class
+
+1. Name: `{Action}{Entity}Request` — e.g. `CreateProjectRequest`.
+2. Implement `authorize()` using Policies.
+3. Implement `rules()` with array syntax — never pipe-separated.
+4. Use `prepareForValidation()` only when normalization is truly necessary.
+
+### Step 2: Rules
+
+1. Use Laravel's `Illuminate\Validation\Rules` classes where possible.
+2. Keep rules explicit — prefer clarity over cleverness.
+3. For nested arrays: validate structure AND leaf values.
+4. Extract custom rule objects for complex/reusable logic.
+
+### Step 3: Test
+
+- Test required fields, invalid formats, boundary conditions, conditional rules.
+- Test authorization where relevant.
+- Use focused tests per validation concern.
+
+## Conventions
+
+→ See guideline `php/validations.md` for array syntax, route params, property mapping, custom rules.
+
+## Output format
+
+1. FormRequest class with rules, messages, and authorization
+2. Custom Rule object if validation logic is complex
+
+## Gotcha
+
+- `required` ≠ not `nullable` — `required` means present, `nullable` means value can be null.
+- Custom Rule objects must return `$fail` callback, not throw exceptions.
+- Don't validate data you already trust (e.g., from a verified internal service).
+
+## Do NOT
+
+- Do NOT validate in controllers — use FormRequest classes.
+- Do NOT use `$request->all()` — use `$request->validated()`.
+- Do NOT put business logic in validation classes.
+
+## Auto-trigger keywords
+
+- validation
+- Form Request
+- validation rules
+- custom rule

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: learning-to-rule-or-skill
+description: "Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work."
+source: project
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# learning-to-rule-or-skill
+
+## When to use
+
+Use this skill when:
+
+* A repeated mistake appears across multiple tasks
+* A successful pattern should be reused in the future
+* A new constraint or workflow should be captured permanently
+* Reviewing post-task learnings or retrospectives
+* Deciding whether a learning belongs in a rule or a skill
+* After completing a task — reflecting on what worked or caused friction
+
+Do not use this skill when:
+
+* The learning is one-off and unlikely to repeat
+* The issue is too vague to turn into guidance
+* The content already exists in an equivalent rule or skill
+
+## Goal
+
+* Turn repeated learnings into reusable project guidance
+* Decide correctly between rule, skill, or update to an existing one
+* Prevent the same mistakes from happening again
+* Keep the system small, clear, and non-duplicative
+
+## Preconditions
+
+* A concrete learning, mistake, or successful pattern exists
+* The learning can be stated clearly in one or two sentences
+* Existing rules and skills can be checked for overlap
+
+## Decision matrix
+
+| If the learning is... | Then... | Action |
+|---|---|---|
+| An always-true constraint ("never X", "always Y") | **Rule** | Create/update rule |
+| A repeatable workflow with steps and validation | **Skill** | Create/update skill |
+| A coding convention or reference material | **Guideline** | Create/update guideline |
+| Baseline model knowledge or standard tool usage | **Nothing** | Do not create anything |
+| A refinement of existing guidance | **Update** | Extend the existing file |
+
+### Decision hints
+
+* Same issue appeared at least twice → strongly consider codifying
+* One-off or too narrow → do not create anything yet
+* Standard tool knowledge (jq, docker, git basics) → **Nothing** — the model knows this
+* If unsure between skill and guideline: does it need step-by-step decisions? → Skill. Just conventions? → Guideline
+
+## Procedure
+
+### 0. Promotion Gate (mandatory)
+
+Before proceeding, the learning MUST pass all gates:
+
+| Gate | Question |
+|---|---|
+| Repetition | Occurred 2+ times OR clearly generalizable? |
+| Impact | Improves correctness, reliability, or consistency? |
+| Failure pattern | Prevents a real, observed failure? |
+| Non-duplication | No existing rule/skill/guideline covers this? |
+| Scope fit | Fits rule, skill, or guideline? |
+| Minimal | Update existing preferred over creation? |
+
+If ANY gate fails → **stop**. Do not create or update anything.
+→ See `capture-learnings` rule for rejection criteria.
+
+### 1. State the learning clearly
+
+Write as a concrete sentence.
+
+Good:
+* Nested triple backticks break copyability in generated markdown
+* Route inspection is more reliable via JSON and jq than text parsing
+
+Bad:
+* Markdown is annoying
+* Routing was confusing
+
+### 2. Identify the pattern type
+
+Classify by type:
+* Constraint
+* Workflow
+* Anti-pattern
+* Quality check
+* Environment-specific convention
+
+Tag with feedback category (for tracking/aggregation):
+* `skill-weakness` — skill gave wrong or incomplete guidance
+* `rule-weakness` — rule was too vague or missed a case
+* `routing-issue` — wrong skill was selected
+* `assumption-issue` — agent made bad assumptions
+* `verification-gap` — verification step was missing or weak
+* `optimization-overreach` — optimize command suggested harmful change
+
+### 3. Decide the target
+
+Choose one:
+* New rule (always-true constraint)
+* Update existing rule
+* New skill (step-by-step workflow)
+* Update existing skill
+* New guideline (coding convention / reference)
+* Update existing guideline
+* **Nothing** (baseline knowledge, standard tool usage, one-off)
+
+### 4. Check for overlap
+
+* Does a similar rule already exist?
+* Does a similar skill already exist?
+* Would a small update be better than a new file?
+
+### 5. Draft the content
+
+If rule:
+* Short, durable constraint
+* General, clear, always applicable
+
+If skill:
+* Focused workflow
+* Include: When to use, Procedure, Output format, Gotchas, Do NOT
+
+### 6. Validate usefulness
+
+* Will this improve future outputs?
+* Specific enough to act on?
+* Different from existing guidance?
+* Likely to matter more than once?
+
+### 7. Keep only the smallest effective change
+
+Prefer:
+* Update over duplicate
+* Small focused skill over broad skill
+* Short rule over long rule
+
+### 8. Write the proposal (if scope ≠ nothing)
+
+The output of this skill is a **curated proposal** under
+`agents/proposals/<proposal_id>.md`, using the template at
+`.augment/templates/agents/proposal.example.md` (shipped by the
+package). This is the input to the five-stage pipeline
+(capture → classify → propose → gate → upstream); see
+[`self-improvement-pipeline`](../../guidelines/agent-infra/self-improvement-pipeline.md).
+
+Mandatory fields the draft MUST fill:
+
+* `proposal_id` — stable kebab-case slug, unique in this repo
+* `type` — `rule` | `skill` | `command` | `guideline`
+* `scope` — `project` (stays in `agents/overrides/`) or `package`
+  (contributed upstream via `upstream-contribute`)
+* `source_learning` — path to the `agents/learnings/<date>-<slug>.md`
+  file this proposal was captured from
+* `evidence` — **at least two independent** references (PR, issue,
+  incident, review-comment, test-failure); entries that all resolve
+  to the same PR are rejected by the gate
+* `Proposed artefact` (§4) — the full draft body, no `TODO` / `TBD`
+* `Success signal` (§7) — one metric, one baseline, one target, one
+  evaluation date
+
+Run `python3 scripts/check_proposal.py agents/proposals/<id>.md` (or
+`task check-proposal`) before handing to `upstream-contribute`. The
+script is a hard gate: non-zero exit = the proposal does not move
+to stage `gated`.
+
+## Output format
+
+For the **decision step** (what this skill prints to the user):
+
+1. Learning summary
+2. Decision: rule, skill, update, or no action
+3. Rationale in one to three lines
+4. If decision ≠ "no action": path of the written proposal
+   (`agents/proposals/<proposal_id>.md`) and gate status
+   (`check_proposal.py` exit 0 = ready for review)
+
+The **proposal file itself** follows
+`proposal.example.md` verbatim — all ten sections, YAML frontmatter
+complete, draft body in §4.
+
+## Core rules
+
+* Capture repeated patterns, not random observations
+* Prefer updating existing guidance over creating duplicates
+* Rules are for durable constraints
+* Skills are for repeatable workflows
+* Keep new guidance as small and focused as possible
+
+## Gotchas
+
+* Model tends to create new files when a small update is enough
+* Model tends to turn vague frustrations into bad guidance
+* Model may write documentation instead of reusable instructions
+* Over-capturing weak learnings creates noise and reduces quality
+
+## Do NOT
+
+* Do NOT create a rule or skill for one-off problems
+* Do NOT duplicate existing guidance
+* Do NOT create broad "catch-all" skills
+* Do NOT write vague learnings without a concrete behavioral consequence
+
+## Auto-trigger keywords
+
+* learning
+* retrospective
+* repeated mistake
+* recurring issue
+* create rule from learning
+* create skill from learning
+* codify this
+* capture this pattern
+* after task
+* what did we learn
+* post-mortem
+
+## Anti-patterns
+
+* Creating a skill for every minor annoyance
+* Rule that says "be careful" without concrete constraint
+* Skill that duplicates an existing one with slightly different wording
+* Capturing a learning before it has repeated
+
+## Examples
+
+Learning: "Nested triple backticks broke markdown copyability twice this week."
+Decision: Update existing markdown rule + add markdown-safe skill if none exists.
+
+Learning: "Route checks keep failing when done via text parsing."
+Decision: Create focused skill for Laravel route inspection via JSON and jq.
+
+Learning: "I forgot to run PHPStan once."
+Decision: No action — one-off, already covered by verify-before-complete rule.
+
+## Environment notes
+
+Prefer updating existing rule/skill when possible.
+Create new files only when the learning introduces a clearly distinct pattern.