@event4u/agent-config 1.9.1

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

@@ -0,0 +1,72 @@
+---
+name: lint-skills
+description: "Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 120
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/skill_linter.py
+    - "--all"
+---
+
+# lint-skills
+
+## When to use
+
+- Validate shape of every skill/rule in `.agent-src.uncompressed/`
+- Verify `execution:` metadata is well-formed
+- Pre-PR local check before CI skill-lint job
+- Investigate reported linter failure
+
+NOT: single file (call `skill_linter.py <path>`), cross-refs (use `check-refs`),
+compression freshness (use `task sync-check`).
+
+## Procedure
+
+1. **Inspect env** — `python3` on PATH, cwd = agent-config repo root (linter
+   resolves `.agent-src.uncompressed/skills/` relative to cwd).
+2. **Dispatch via runtime** —
+
+   ```bash
+   python3 scripts/runtime_dispatcher.py run --skill lint-skills
+   ```
+
+   Handler runs `python3 scripts/skill_linter.py --all`, captures stdout/stderr,
+   returns typed `ExecutionResult`.
+3. **Verify result** —
+   - `status: success` + `exit_code: 0` → all clean
+   - `exit_code: 1` → warnings only — review stdout
+   - `exit_code: 2` → errors — fix flagged files
+   - `status: timeout` → investigate slowdown, do not just raise timeout
+   - `status: error` → interpreter missing or wrong cwd
+
+## Output
+
+1. One-line summary: status, exit code, duration (ms)
+2. Count of skills/rules inspected if known
+3. First 10 errored files: code + message
+4. Next action: fix, re-run, or surface raw stdout
+
+## Gotcha
+
+- `--all` walks full tree — several seconds; bump `timeout_seconds` if repo grew
+- Running outside repo root → zero skills inspected, looks green but is a no-op
+- `exit_code: 1` (warnings) does not fail CI — not the same as "clean"
+
+## Do NOT
+
+- Do NOT call `skill_linter.py` directly when the intent is to exercise the
+  runtime path — go through the dispatcher
+- Do NOT raise `timeout_seconds` to mask slowdowns
+- Do NOT add pipes/redirection — handler uses `shell=False`, argv form only
+
+## References
+
+- Skill: `check-refs` — sibling pilot that runs the cross-ref checker
+- Rule: `runtime-safety` — execution metadata constraints
+- Script: `scripts/skill_linter.py`, `scripts/runtime_dispatcher.py`,
+  `scripts/runtime_handler.py`

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

@@ -0,0 +1,79 @@
+---
+name: livewire
+description: "Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates."
+source: package
+---
+
+# livewire
+
+## When to use
+
+Use when creating or editing Livewire components — reactive state, forms, tables, real-time updates.
+
+Do NOT use when:
+- Static Blade views (use `blade-ui` skill)
+- Flux UI components (use `flux` skill)
+
+## Procedure: Create a Livewire component
+
+### Step 0: Inspect
+
+1. Detect Livewire version — `composer.json` for `livewire/livewire`.
+   - v3: `#[Layout]`, `#[Title]`, property attributes.
+   - v2: `$layout`, `$listeners`, method-based hooks.
+2. Check existing components — `app/Livewire/` or `app/Http/Livewire/`.
+3. Check views — `resources/views/livewire/`.
+
+### Step 1: Create component class
+
+1. `declare(strict_types=1)`, `final` class.
+2. Typed public properties for state — keep minimal.
+3. `#[Locked]` for tamper-proof properties.
+4. `#[Url]` for URL-synced properties.
+
+### Step 2: Implement actions
+
+1. Public methods callable from frontend.
+2. Validate before processing: `$this->validate()`.
+3. `$this->dispatch()` for cross-component communication (v3).
+
+### Step 3: Create view
+
+1. One root element (`<div>`).
+2. `wire:key` on dynamic lists.
+3. `wire:loading` for user feedback.
+4. `wire:model.live` for real-time updates (v3 default is deferred).
+
+### Step 4: Test
+
+- `Livewire::test(ComponentClass::class)`
+- `->set()`, `->call()`, `->assertSee()`, `->assertHasNoErrors()`
+
+## Conventions
+
+→ See guideline `php/livewire.md` for state management, forms, performance, Alpine.js, templates.
+
+## Output format
+
+1. Livewire component class with typed properties and actions
+2. Blade view with wire: bindings and Flux components
+
+## Gotcha
+
+- Public properties serialize between requests — don't put large objects in state.
+- `wire:model` is deferred by default in v3 — use `wire:model.live` for real-time.
+- `$this->redirect()` + `$this->dispatch()` in same method — only redirect executes.
+
+## Do NOT
+
+- Do NOT put heavy computation in `render()` — it runs on every update.
+- Do NOT nest Livewire components deeply — keep the tree shallow.
+- Do NOT expose sensitive data as public properties.
+
+## Auto-trigger keywords
+
+- Livewire
+- reactive component
+- wire:model
+- lifecycle
+- real-time UI

package/.agent-src/skills/logging-monitoring/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: logging-monitoring
+description: "Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers."
+source: package
+---
+
+# logging-monitoring
+
+## When to use
+
+Use when adding logging, configuring monitoring stack, or integrating Sentry/Grafana/Loki.
+
+Do NOT use when:
+- Creating Grafana dashboards (use `grafana` skill)
+- Dashboard design decisions (use `dashboard-design` skill)
+
+## Procedure: Add logging or monitoring
+
+1. Read `config/logging.php` for available channels.
+2. Check for Grafana module: `app/Modules/Grafana/`.
+3. Read `agents/` docs for module-specific logging.
+
+## Monitoring stack
+
+| Tool | Purpose | Integration |
+|---|---|---|
+| **Sentry** | Error tracking | `sentry/sentry-laravel`, `MonitoringHelper` |
+| **Grafana** | Dashboards | Connected to Loki |
+| **Loki** | Log aggregation | `itspire/monolog-loki` via Monolog |
+| **Slack** | Alert notifications | Webhook for error-level |
+
+## Log channels
+
+| Channel | Purpose |
+|---|---|
+| `stack_without_slack` | Daily file + errorlog (no Slack) |
+| `slack` | Error alerts to Slack |
+| `loki` | Send logs to Grafana Loki |
+| `loki_import_*` | Import-specific Loki with custom labels |
+| `daily` | Rotating file logs |
+
+### Loki labels
+
+```php
+'globalLabels' => ['app' => '{project}', 'service' => '{service}', 'env' => $env],
+```
+
+The `service` label differentiates log types in Grafana queries.
+
+### Config flags
+
+| Env Variable | Purpose | Default |
+|---|---|---|
+| `LOG_CLIENT_SOFTWARE_REQUESTS` | Log incoming API requests to DB | `false` |
+| `LOG_EXTERNAL_API_REQUESTS` | Log outgoing external API requests | `true` |
+| `LOG_WEBHOOK_REQUESTS` | Log webhook requests to DB | `false` |
+| `LOG_CHANNEL_IMPORT` | Channel for import logs | `daily` |
+
+## Grafana/Loki dashboard rules
+
+- Hide Loki metadata columns: `labelTypes`, `traceID`, `traceID (field)`.
+- Use correct Loki service labels: `import_result` for final states, `import_snapshot` for cron.
+- Verify column names match data semantics.
+
+## Conventions
+
+→ See guideline `php/logging.md` for log levels, structured context, what to log, Sentry patterns.
+
+### Validate
+
+- Verify log level matches severity (no `Log::error()` for info-level events).
+- Confirm structured context is passed (not string interpolation).
+- Check that no sensitive data (passwords, tokens, PII) appears in log output.
+- Verify Sentry captures include relevant context for debugging.
+
+## Output format
+
+1. Logging configuration or structured log statements
+2. Sentry integration with proper context and breadcrumbs
+
+## Gotcha
+
+- Sentry has 200KB event size limit — large context gets truncated.
+- Structured logging keys must be `snake_case`.
+- Don't create Loki channels without corresponding Grafana dashboard query.
+
+## Do NOT
+
+- Do NOT use Sentry SDK directly — use `MonitoringHelper`.
+- Do NOT interpolate variables into log messages — use context array.
+- Do NOT log at `error` level for expected/handled conditions.
+
+## Auto-trigger keywords
+
+- logging
+- monitoring
+- Sentry
+- Grafana
+- structured logging
+- log levels

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

@@ -0,0 +1,193 @@
+---
+name: mcp
+description: "Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows."
+source: package
+---
+
+# MCP Skill
+
+## When to use
+
+Use this skill when:
+- Deciding which MCP tool to use for a task
+- Combining multiple MCP tools in a workflow
+- Troubleshooting MCP tool errors or unexpected results
+- Building commands or skills that reference MCP tools
+
+## Procedure: Use MCP tools
+
+### Sentry (`augment-partner-remote-mcp-sentry`)
+
+Error tracking and performance monitoring.
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `find_organizations` | Find org slug | First call — needed for all other Sentry tools |
+| `find_projects` | Find project slug | When filtering by project |
+| `find_teams` | Find team slug/ID | Team-based queries |
+| `find_releases` | Recent releases | Check deploy timing, release versions |
+| `get_issue_details` | Full issue: stacktrace, tags | Investigating a specific error |
+| `get_issue_tag_values` | Distribution by tag | Analyzing who/what is affected |
+| `get_trace_details` | Trace overview | Performance investigation |
+| `get_event_attachment` | Download attachments | Screenshots, logs on events |
+| `search_issues` | List issues by criteria | "Show me unresolved errors" |
+| `search_events` | Count/aggregate events | "How many errors today?" |
+| `search_issue_events` | Filter events in an issue | "Events from last hour" |
+| `analyze_issue_with_seer` | AI root cause analysis | When stacktrace alone isn't enough |
+
+**Key pattern:** Always get org slug first → then use other tools.
+**See:** `sentry-integration` skill for investigation workflow.
+
+### Jira (`jira-integration`)
+
+Issue tracking and project management.
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `GET /search/jql` | Search with JQL | Find tickets by criteria |
+| `GET /issue/{key}` | Read ticket details | Get context for a task |
+| `POST /issue` | Create ticket | New bugs, tasks, stories |
+| `PUT /issue/{key}` | Update ticket | Change fields, assignee |
+| `GET /issue/{key}/transitions` | Available status changes | Before transitioning |
+| `POST /issue/{key}/transitions` | Change ticket status | Move to "In Progress", etc. |
+| `POST /issue/{key}/comment` | Add comment | Progress updates, analysis |
+| `GET /project` | List projects | Find project key |
+| `GET /field` | List available fields | Before writing JQL |
+
+**Key pattern:** Check fields (`GET /field`) before writing JQL. Check transitions before changing status.
+**See:** `jira-integration` skill for JQL patterns and ADF format.
+
+### GitHub (`github-api`)
+
+Repository, PR, and CI management.
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `GET /repos/{o}/{r}/pulls` | List PRs | Find open PRs for branch |
+| `POST /repos/{o}/{r}/pulls` | Create PR | Open a new pull request |
+| `GET /repos/{o}/{r}/pulls/{n}/files` | PR changed files | Review what changed |
+| `GET /repos/{o}/{r}/issues` | List issues/PRs | Search by label, assignee |
+| `GET /search/issues` | Search issues/PRs | Complex queries with `q=` |
+| `GET /repos/{o}/{r}/actions/runs` | CI runs | Check build status |
+| `GET /repos/{o}/{r}/actions/jobs/{id}` | CI job details | Read failure logs |
+| `GET /repos/{o}/{r}/commits/{sha}/check-runs` | Check runs | Detailed CI status |
+| `GET /repos/{o}/{r}/commits/{sha}/status` | Commit status | Quick pass/fail check |
+
+**Key pattern:** Use `head=org:branch` to filter PRs by branch. Use `q=is:pr` or `q=is:issue` to separate.
+**See:** `git-workflow` and `code-review` skills.
+
+### Browser / Playwright (`Playwright`)
+
+Web interaction and testing.
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `browser_navigate` | Open URL | Load a page |
+| `browser_snapshot` | Accessibility snapshot | Read page content (better than screenshot) |
+| `browser_click` | Click element | Interact with UI |
+| `browser_type` | Type text | Fill forms |
+| `browser_evaluate` | Run JavaScript | Extract data, manipulate DOM |
+| `browser_take_screenshot` | Visual capture | Document UI state |
+| `browser_network_requests` | Network log | Debug API calls |
+
+**Key pattern:** Use `browser_snapshot` over screenshots — it returns structured data the agent can act on.
+
+### Context7 (`Context_7`)
+
+Library documentation lookup.
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `resolve-library-id` | Find library ID | First — before querying docs |
+| `query-docs` | Query documentation | Get up-to-date API docs and examples |
+
+**Key pattern:** Always resolve library ID first → then query. Max 3 calls per question.
+**Use for:** Laravel, PHP, Livewire, Tailwind, or any library docs.
+
+### Sequential Thinking (`Sequential_thinking`)
+
+Structured problem-solving.
+
+| Tool | Purpose | When to use |
+|---|---|---|
+| `sequentialthinking` | Step-by-step reasoning | Complex problems, planning, analysis |
+
+**Use for:** Breaking down complex tasks, planning before implementation, multi-step reasoning.
+
+## Best Practices
+
+### Tool selection
+
+| Need | Tool |
+|---|---|
+| Error investigation | Sentry → `get_issue_details` |
+| Ticket context | Jira → `GET /issue/{key}` |
+| CI failure | GitHub → `actions/runs` + `actions/jobs/{id}` |
+| Library docs | Context7 → `resolve-library-id` + `query-docs` |
+| Web scraping | Playwright → `navigate` + `snapshot` |
+| Complex planning | Sequential Thinking |
+
+### Combining tools in workflows
+
+```
+Bug investigation:
+  Jira (ticket context) + Sentry (stacktrace) + codebase-retrieval (code)
+
+Feature planning:
+  Jira (requirements) + codebase-retrieval (existing code) + Context7 (library docs)
+
+CI fix:
+  GitHub (failure logs) + codebase-retrieval (failing code) + launch-process (run locally)
+
+PR creation:
+  GitHub (create PR) + Jira (transition to "In Review")
+```
+
+### Error handling
+
+- If an MCP tool returns an error, retry once with corrected parameters
+- If org/project slug is unknown, use `find_organizations` / `find_projects` first
+- Sentry and Jira tools need the correct org — don't guess, look it up
+- GitHub API has rate limits — batch related calls, avoid unnecessary requests
+
+### Permission boundaries
+
+- **Read operations** — always safe, use freely
+- **Write operations** — ask user permission first:
+  - Creating Jira tickets or changing status
+  - Creating GitHub PRs or pushing code
+  - Posting comments on issues/PRs
+
+## Related
+
+- **Skill:** `sentry-integration` — Sentry-specific investigation patterns
+- **Skill:** `jira-integration` — Jira-specific JQL and ticket management
+- **Skill:** `git-workflow` — GitHub PR and branch conventions
+- **Skill:** `copilot-config` — GitHub Copilot integration
+- **Rule:** `no-commit.md` — permission boundaries for write operations
+
+
+## Output format
+
+1. MCP server configuration or tool integration code
+2. Tool capability mapping for the agent workflow
+
+## Gotcha
+
+- MCP servers are token-expensive — prefer CLI equivalents when available (see `rtk-output-filtering` skill).
+- Don't chain 5+ MCP tool calls when a single CLI command could do the same thing.
+- MCP server availability varies — always handle connection failures gracefully.
+- Sentry and Jira MCP provide unique capabilities — those are worth the token cost.
+
+## Do NOT
+
+- Do NOT call MCP tools without understanding their side effects.
+- Do NOT use MCP tools when simpler alternatives exist.
+
+## Auto-trigger keywords
+
+- MCP
+- Model Context Protocol
+- MCP server
+- MCP tools
+- agent tools

package/.agent-src/skills/merge-conflicts/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: merge-conflicts
+description: "Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow."
+source: package
+---
+
+# merge-conflicts
+
+## When to use
+
+Use this skill when:
+- A merge or rebase produces conflicts
+- The user asks to "resolve conflicts", "fix merge", or "update branch"
+- CI fails because the branch is behind main
+- The `prepare-for-review` command encounters conflicts
+
+## Procedure: Resolve merge conflicts
+
+### 1. Understand the situation
+
+Before touching any conflict:
+
+```bash
+# What files have conflicts?
+git diff --name-only --diff-filter=U
+
+# What branch are we merging from/into?
+git log --oneline -1 HEAD
+git log --oneline -1 MERGE_HEAD   # or REBASE_HEAD for rebase
+```
+
+### 2. Read both sides
+
+For each conflicted file:
+
+1. **Read the full conflict** — not just the markers, but the surrounding context.
+2. **Understand "ours"** — what does the current branch intend?
+3. **Understand "theirs"** — what does the incoming branch intend?
+4. **Check if both changes are needed** — often both sides added different things.
+
+### 3. Resolution strategies
+
+| Situation | Strategy |
+|---|---|
+| Both sides changed the same line differently | **Ask the user** — this is a semantic conflict |
+| Both sides added different code in the same area | **Keep both** — combine the additions in logical order |
+| One side deleted, other side modified | **Ask the user** — deletion intent vs modification intent |
+| Lock file conflicts (`composer.lock`, `package-lock.json`) | **Regenerate** — accept theirs, then run `composer install` / `npm install` |
+| Migration conflicts (same timestamp) | **Rename** — adjust timestamp to avoid collision |
+| Auto-generated files (OpenAPI spec, baselines) | **Regenerate** — resolve source, then regenerate the output |
+| Formatting-only conflicts | **Accept either** — then run quality tools to normalize |
+
+### 4. File-type specific rules
+
+#### PHP files
+
+- After resolving, check that `use` statements are correct (no duplicates, no missing imports).
+- Verify the resolved code compiles: `php -l filename.php`
+- Run PHPStan on the file: `vendor/bin/phpstan analyse` (see `quality-tools` skill)
+
+#### Migrations
+
+- Never merge two migrations that modify the same table into one.
+- If both branches added migrations, keep both — adjust timestamps if they collide.
+- After resolving, run migrations to verify: `php artisan migrate --env=testing`
+
+#### Config files
+
+- `composer.json` — resolve, then run `composer update --lock` to regenerate `composer.lock`.
+- `package.json` — resolve, then run `npm install` to regenerate `package-lock.json`.
+- `.env.example` — keep all new entries from both sides.
+
+#### Test files
+
+- If both sides added tests to the same file, keep all tests.
+- If both sides modified the same test, understand what each test is verifying and combine.
+
+### 5. When to ask the user
+
+**Always ask** when:
+- Both sides changed the **same business logic** differently (semantic conflict)
+- A deletion conflicts with a modification (intent is unclear)
+- The conflict involves **authorization or security** logic
+- You're unsure which side is "correct"
+
+**Resolve without asking** when:
+- Both sides added different, non-overlapping code
+- Lock file / auto-generated file conflicts
+- Import statement ordering
+- Formatting-only differences
+
+### 6. Verify after resolution
+
+After resolving ALL conflicts:
+
+```bash
+# 1. Check no conflict markers remain
+grep -rn "<<<<<<< \|======= \|>>>>>>> " --include="*.php" --include="*.js" --include="*.ts" .
+
+# 2. Syntax check PHP files
+find . -name "*.php" -newer .git/MERGE_HEAD -exec php -l {} \;
+
+# 3. Run quality tools
+vendor/bin/phpstan analyse
+
+# 4. Run tests
+php artisan test
+
+# 5. Complete the merge/rebase
+git add .
+# Don't commit — let the user decide when to commit
+```
+
+## Common pitfalls
+
+| Pitfall | Prevention |
+|---|---|
+| Accepting "ours" blindly | Always read both sides first |
+| Missing a conflict marker | Run `grep -rn "<<<<<<< "` after resolving |
+| Breaking imports | Check `use` statements after merge |
+| Losing new code | Compare the resolved file with both original versions |
+| Forgetting to regenerate lock files | Always run package manager after resolving `*.json` |
+
+## Rebase vs Merge
+
+| Approach | When to use |
+|---|---|
+| `git merge main` | Default — preserves history, safer for shared branches |
+| `git rebase main` | Only when explicitly asked — rewrites history, cleaner log |
+
+**Never rebase without explicit permission** (per `no-commit` rule).
+
+## Output format
+
+1. Resolved conflict with both sides' intent preserved
+2. Summary of resolution strategy per file
+
+## Auto-trigger keywords
+
+- merge conflict
+- resolve conflict
+- rebase conflict
+- conflict markers
+- branch behind main
+- update branch
+
+## Gotcha
+
+- Never resolve conflicts by deleting code you don't understand — ask the user.
+- The model tends to accept "ours" or "theirs" wholesale instead of merging logic from both sides.
+- Always run tests after resolving conflicts — successful merge != correct merge.
+- Lock file conflicts (composer.lock, package-lock.json) should be resolved by re-running the package manager.
+
+## Do NOT
+
+- Do NOT rebase or force-push without explicit permission.
+- Do NOT leave conflict markers (`<<<<<<<`) in any file.
+- Do NOT skip verification (PHPStan + tests) after resolving.