@event4u/agent-config 1.9.1

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: copilot-agents-optimization
+description: "Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# Copilot & AGENTS Optimizer Skill
+
+## When to use
+
+Use this skill when:
+- Running `/docs-optimize` to refactor AGENTS.md and copilot-instructions.md
+- Adding new content to either file and needing to check if it belongs there
+- After changes to `.augment/` (new skills, rules, guidelines) that may make content in these files redundant
+- When either file exceeds the line budget
+
+
+Do NOT use when:
+- Writing application code
+- Creating new skills or commands
+
+## Procedure: Optimize copilot/agents files
+
+### 0. Analyze current state
+
+Before changing anything:
+
+1. Read `AGENTS.md` — content, line count, what's duplicated vs. unique
+2. Read `.github/copilot-instructions.md` — same analysis
+3. Scan `.augment/` — which skills/rules already cover topics from above
+4. Identify duplication — what exists in both AGENTS.md and `.augment/`?
+
+Only after this analysis, proceed with optimization.
+
+### `AGENTS.md` — Project Entry Point for AI Agents
+
+| Property | Value |
+|---|---|
+| **Audience** | Augment Agent, other AI agents |
+| **Can read `.augment/`?** | ✅ Yes — can follow references |
+| **Line budget** | Max 1000, ideal ≤ 500 |
+| **Purpose** | Project-specific setup, Docker, testing, quality tools |
+
+**What belongs here:**
+- Tech stack and framework versions
+- Development setup (Docker, Make targets, env files)
+- Database and multi-tenancy setup
+- Testing framework, suites, and conventions
+- Quality tool commands (PHPStan, Rector, ECS)
+- Project structure overview (brief, link to module docs)
+- Agent infrastructure overview (layer table, key references)
+
+**What does NOT belong here:**
+- Coding standards (→ `.augment/rules/` and `.augment/guidelines/`)
+- Architecture principles like SOLID, KISS, DRY (→ `.augment/rules/architecture.md`)
+- PHP conventions (→ `.augment/guidelines/php/`)
+- Scope control rules (→ `.augment/rules/scope-control.md`)
+- Language/tone rules (→ `.augment/rules/language-and-tone.md`)
+- Detailed module documentation (→ `app/Modules/README.md`)
+
+### `.github/copilot-instructions.md` — Self-Contained for Copilot
+
+| Property | Value |
+|---|---|
+| **Audience** | GitHub Copilot (Code Review bot + Chat) |
+| **Can read `.augment/`?** | ❌ Code Review cannot, ✅ Chat can |
+| **Line budget** | Max 1000, ideal ≤ 500 |
+| **Purpose** | Coding standards, review rules, architecture constraints |
+
+**What belongs here:**
+- Architecture rules (thin controllers, service layer, policies)
+- PHP 8.2 patterns (readonly, final, enums — with exceptions)
+- Project-specific conventions (custom helpers, environment config, naming)
+- Code review scope and comment behavior rules
+- Language rules (English comments, bilingual PR comments)
+- Known issues / false positives that Copilot should avoid
+- Package management rules
+
+**What does NOT belong here:**
+- Docker setup or Make targets (Copilot doesn't run commands)
+- Testing setup details (Copilot doesn't run tests)
+- Agent infrastructure (Copilot doesn't use agents/)
+- Things auto-enforced by ECS/Rector (code style, formatting, trailing commas)
+- Detailed pattern documentation (too long, Copilot needs concise rules)
+
+## Deduplication Strategy
+
+### Rule: Content lives in ONE canonical place
+
+```
+.augment/rules/         ← Canonical for behavior rules
+.augment/guidelines/    ← Canonical for coding conventions
+.augment/skills/        ← Canonical for domain expertise
+agents/                 ← Canonical for project-specific docs
+```
+
+### When duplication is acceptable
+
+`copilot-instructions.md` **must** duplicate essential rules because Copilot Code Review
+cannot read other files. But keep duplicated content:
+- **Concise** — one-liner summaries, not full explanations
+- **Focused** — only what Copilot needs for code suggestions and PR reviews
+- **Stable** — rules that rarely change (architecture, naming, key conventions)
+
+### When duplication is NOT acceptable
+
+`AGENTS.md` should **never** duplicate `.augment/` content because Augment Agent can read
+both. Instead, reference with a table:
+
+```markdown
+| What | Where |
+|---|---|
+| PHP coding rules | `.augment/rules/php-coding.md` |
+| Controller guidelines | `.augment/guidelines/php/controllers.md` |
+```
+
+## Line Budget Enforcement
+
+| File | 🟢 Good | 🟡 Warning | 🔴 Over budget |
+|---|---|---|---|
+| `AGENTS.md` | ≤ 500 | 501–800 | > 1000 |
+| `copilot-instructions.md` | ≤ 500 | 501–800 | > 1000 |
+
+### Reduction strategies (when over budget)
+
+1. **Extract to `agents/`** — Move project-specific details to dedicated files in `agents/`
+   and link from AGENTS.md (e.g., `agents/docs/database-setup.md`, `agents/docs/testing.md`)
+2. **Remove duplicates** — If content exists in `.augment/`, remove from AGENTS.md
+3. **Compress** — Turn verbose explanations into concise tables or bullet points
+4. **Remove ECS/Rector-enforced rules** — From copilot-instructions.md (auto-fixed anyway)
+5. **Move examples to guidelines** — Detailed code examples belong in `.augment/guidelines/`
+
+## Portability and Stack Coherence
+
+Duplication is not the only way these files go wrong. They also **lie
+about the project** over time:
+
+- **Legacy identifiers** — references to a former repo name, a sibling
+  project in the same monorepo, or content that was copied from another
+  codebase as a starting template and never adapted.
+- **Stack drift** — the file claims "Laravel 11 + MariaDB" but the repo
+  was converted to a Python library; or it names Docker services that
+  no longer exist.
+- **Dead commands** — `make start` in the docs, but `Makefile` no
+  longer has that target.
+
+Before deduplicating, run three scans:
+
+1. **Legacy identifier scan** — compare both files against the package's
+   `FORBIDDEN_IDENTIFIERS` blocklist (see `scripts/check_portability.py`)
+   plus any project names from `agents/` module docs that don't match
+   the current project.
+2. **Stack coherence scan** — auto-detect the actual stack from
+   `composer.json` / `package.json` / `pyproject.toml` / etc. and flag
+   any claim that no longer matches reality.
+3. **Dead-command scan** — verify every `make X`, `task X`, `composer X`,
+   `php artisan X`, or `npm X` still resolves.
+
+Every hit from scan 1 is a 🔴 blocker: leaking another project's name
+into a consumer's own docs is the failure mode this skill exists to
+prevent. Fix or remove those BEFORE any dedup/compress work — there's
+no point deduplicating content that is about to be rewritten.
+
+When the drift is severe (whole sections are wrong), recommend
+`/copilot-agents-init` to scaffold a clean replacement rather than
+patching forever.
+
+## Optimization Checklist
+
+When optimizing either file, check:
+
+- [ ] No identifiers from other projects (FORBIDDEN_IDENTIFIERS blocklist)?
+- [ ] Tech stack claims match actual project dependencies?
+- [ ] All referenced commands/targets exist (Makefile, composer scripts, artisan, task)?
+- [ ] Line count within budget?
+- [ ] No content duplicated with `.augment/rules/`?
+- [ ] No content duplicated with `.augment/guidelines/`?
+- [ ] No content duplicated between the two files unnecessarily?
+- [ ] AGENTS.md references `.augment/` instead of duplicating?
+- [ ] copilot-instructions.md is self-contained for Code Review?
+- [ ] No ECS/Rector-enforced rules in copilot-instructions.md?
+- [ ] Project structure is brief (link to module docs for details)?
+- [ ] All sections still relevant (no outdated references)?
+- [ ] Cross-references to `agents/` docs are valid?
+
+## Related
+
+- **Command:** `/copilot-agents-optimize`
+- **Skill:** `copilot-config` — Copilot behavior and PR review patterns
+- **Skill:** `agent-docs-writing` — documentation hierarchy
+- **Context:** `augment-infrastructure.md` — full `.augment/` overview
+
+
+## Output format
+
+1. Optimized file(s) with deduplication applied and line budget respected
+2. Summary of what was removed, moved, or consolidated
+3. Line count before/after for each file
+
+## Gotcha
+
+- AGENTS.md is read by GitHub Copilot and other tools — changes affect all AI assistants, not just Augment.
+- Don't remove content from AGENTS.md that other tools depend on — verify cross-tool compatibility first.
+- The model tends to over-optimize by removing "obvious" content that other models actually need.
+
+## Do NOT
+
+- Do NOT add content to AGENTS.md that belongs in .augment/ files.
+- Do NOT exceed the recommended line budget for copilot-instructions.md.
+- Do NOT duplicate rules between AGENTS.md and .augment/rules/.
+
+## Auto-trigger keywords
+
+- AGENTS.md optimization
+- copilot-instructions
+- deduplication

package/.agent-src/skills/copilot-config/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: copilot-config
+description: "Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'."
+source: package
+---
+
+# Copilot Skill
+
+## When to use
+
+Use this skill when:
+- Editing `.github/copilot-instructions.md` to improve Copilot behavior
+- Dealing with Copilot PR review comments (via `/fix-pr-bot-comments`)
+- Analyzing Copilot's review patterns to identify recurring false positives
+- Tuning Copilot's code suggestions for the project
+
+
+Do NOT use when:
+- Augment-specific behavior (use Augment rules and skills)
+- Writing application code
+
+## Procedure: Configure Copilot
+
+### Configuration File
+
+**`.github/copilot-instructions.md`** — the single source of truth for Copilot behavior.
+
+### What Copilot Can and Cannot Read
+
+| Context | Copilot Code Review (PR bot) | Copilot Chat (IDE) |
+|---|---|---|
+| `.github/copilot-instructions.md` | ✅ Reads automatically | ✅ Reads automatically |
+| `.augment/rules/` | ❌ Cannot access | ✅ Can read if referenced |
+| `.augment/skills/` | ❌ Cannot access | ✅ Can read if referenced |
+| `.augment/guidelines/` | ❌ Cannot access | ✅ Can read if referenced |
+| `AGENTS.md` | ❌ Cannot access | ✅ Can read if referenced |
+| `agents/` | ❌ Cannot access | ✅ Can read if referenced |
+
+**Key implication:** `copilot-instructions.md` must be **self-contained** for PR reviews.
+It cannot reference `.augment/` files and expect Copilot Code Review to follow them.
+For Copilot Chat users, a hint at the top of the file points to `.augment/` for deeper context.
+
+### What Copilot Controls
+
+| Area | How |
+|---|---|
+| Code suggestions | Follows coding standards, PHP 8.2 patterns, Laravel conventions |
+| PR reviews | Reviews only modified lines + direct dependencies |
+| Comment behavior | Deduplication rules, reply handling, scope control |
+| Language | English code comments, bilingual PR comments (EN + DE) |
+
+### Relationship to `.augment/`
+
+`copilot-instructions.md` and `.augment/` serve different audiences:
+
+| | `copilot-instructions.md` | `.augment/` |
+|---|---|---|
+| **Audience** | GitHub Copilot (bot + chat) | Augment Agent |
+| **Scope** | Coding standards, review rules | Full agent infrastructure |
+| **Self-contained?** | Yes (must be) | Yes (skills reference each other) |
+| **Duplication** | Intentional — Copilot can't read `.augment/` | No duplication needed |
+
+When updating coding rules, check if both files need the change:
+- **Architecture/coding rules** → update both (Copilot needs them self-contained)
+- **Agent workflows/commands** → only `.augment/` (Copilot doesn't use these)
+- **PR review behavior** → only `copilot-instructions.md` (Augment uses `/fix-pr-*` commands)
+
+## PR Review Comment Rules
+
+Copilot is configured with strict comment behavior rules:
+
+### Deduplication
+
+Before creating a comment, Copilot must:
+1. Check if it already commented on the same line/concern
+2. Check if another reviewer already raised the same point
+3. Skip if a duplicate would be created
+
+### Reply Handling
+
+| Developer response | Copilot action |
+|---|---|
+| Accepted suggestion | Acknowledge briefly or resolve |
+| Rejected with reason | Accept the decision, do NOT re-raise |
+| Asked a question | Answer with analysis and examples |
+| Dismissed without explanation | Move on, do NOT re-raise |
+
+### Key Principle
+
+**One comment per concern per location.** Never duplicate, never re-raise rejected suggestions.
+
+## Handling Copilot Bot Comments (as Augment Agent)
+
+When the user asks to fix Copilot's PR review comments (via `/fix-pr-bot-comments`):
+
+### 1. Evaluate Each Comment
+
+For each Copilot comment, determine:
+
+| Category | Action |
+|---|---|
+| **Valid and actionable** | Fix the code as suggested |
+| **Valid but already handled** | Reply explaining it's already addressed (e.g., by ECS/Rector) |
+| **False positive** | Reply explaining why the suggestion doesn't apply |
+| **Style nitpick** | Reply that ECS/Rector handles this automatically |
+| **Out of scope** | Reply that the comment is outside the PR's change scope |
+
+### 2. Reply Format
+
+When replying to Copilot comments on behalf of the user:
+
+```markdown
+{English explanation}
+
+---
+
+🇩🇪 {German translation}
+```
+
+### 3. Common False Positives
+
+Copilot frequently suggests things that conflict with project conventions:
+
+| Copilot suggests | Project convention | Response |
+|---|---|---|
+| Add `null !== $var` with `is_string()` | `is_string()` already excludes null | False positive — redundant check |
+| Register events manually | Laravel 11 uses event discovery | Not needed since Laravel 11 |
+| Use `float` for money | Use `Math` helper class | Project uses BCMath via `Math::*()` |
+| Add PHPDoc repeating signature | Only add PHPDoc when types are insufficient | Redundant documentation |
+| Suggest `array()` syntax | Short syntax `[]` enforced by ECS | Auto-fixed by ECS |
+| Add `final` to mocked classes | Classes mocked by Mockery can't be final | Would break tests |
+
+## Improving Copilot Instructions
+
+When updating `.github/copilot-instructions.md`:
+
+### Structure
+
+- Each section starts with `## ✅ {Title}`
+- Rules are bullet points, concise and actionable
+- Code examples use `✅ Correct` / `❌ Wrong` pattern
+- Keep sections focused — one concern per section
+
+### When to Add New Rules
+
+| Trigger | Action |
+|---|---|
+| Copilot repeatedly makes the same wrong suggestion | Add to "Known Issues" section |
+| New project convention introduced | Add to the relevant section |
+| Copilot ignores scope control | Strengthen "Code Review Scope" section |
+| Copilot creates duplicate comments | Strengthen "Comment Behavior" section |
+
+### When NOT to Add Rules
+
+- Don't add rules for things ECS/Rector auto-fix (Copilot doesn't need to know)
+- Don't add rules that duplicate `AGENTS.md` content (Copilot doesn't read `AGENTS.md`)
+- Don't add overly specific rules for one-off situations
+
+## Relationship to Other Tools
+
+| Tool | Role | Config |
+|---|---|---|
+| **Copilot** | IDE suggestions + PR reviews | `.github/copilot-instructions.md` |
+| **Augment** | Agent workflows + deep analysis | `.augment/` + `agents/` |
+| **Greptile** | PR review bot (if enabled) | Separate config |
+| **ECS** | Code style auto-fix | `ecs.php` (project root) |
+| **Rector** | Code refactoring auto-fix | `rector.php` (project root) |
+| **PHPStan** | Static analysis | `phpstan.neon` (project root) |
+
+Copilot and Augment complement each other:
+- **Copilot** handles real-time suggestions and automated PR reviews
+- **Augment** handles complex workflows, deep analysis, and multi-step tasks
+
+## Related
+
+- **File:** `.github/copilot-instructions.md` — Copilot configuration
+- **Command:** `/fix-pr-bot-comments` — fix bot review comments
+- **Command:** `/fix-pr-comments` — fix all review comments
+- **Skill:** `code-review` — PR review process and conventions
+
+
+## Output format
+
+1. Updated copilot-instructions.md or related config file
+2. Summary of changes and which Copilot behavior is affected
+
+## Gotcha
+
+- copilot-instructions.md is for GitHub Copilot, NOT for Augment — don't mix audiences.
+- Don't duplicate .augment/ content into copilot-instructions.md — it bloats the file and causes drift.
+- Copilot reads the ENTIRE instructions file on every request — keep it under 500 lines.
+
+## Do NOT
+
+- Do NOT let Copilot generate code that violates project coding standards.
+- Do NOT accept Copilot review comments without verifying them against the codebase.
+
+## Auto-trigger keywords
+
+- GitHub Copilot
+- copilot instructions
+- PR review
+- copilot behavior

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

@@ -0,0 +1,116 @@
+---
+name: dashboard-design
+description: "Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling."
+source: package
+---
+
+# dashboard-design
+
+## When to use
+
+Use when designing a new Grafana or admin dashboard, deciding what goes where (Grafana vs. app), or embedding Grafana panels in the Laravel app.
+
+Do NOT use when:
+- Writing Grafana queries/JSON (use `grafana` skill)
+- Building Livewire components (use `livewire` skill)
+
+## Procedure: Design a dashboard
+
+| Domain | Technology | Purpose |
+|---|---|---|
+| **Monitoring** | Grafana + Loki | Infrastructure health, error rates, logs, SLAs |
+| **Business/Admin** | Laravel + Livewire + Tailwind | Customer KPIs, import stats, usage metrics |
+
+### Decision: What goes where?
+
+| Data | Where |
+|---|---|
+| Server metrics, error rates, latency | Grafana |
+| Log analysis, traces | Grafana (Loki) |
+| SLA/uptime tracking | Grafana |
+| Customer-facing KPIs | App dashboard |
+| Import statistics per customer | App dashboard (+ Grafana embed) |
+| User activity, usage metrics | App dashboard |
+
+### Grafana Embedding
+
+```html
+<iframe
+  src="https://grafana.example.com/d-solo/{dashboard-uid}/{panel-id}?orgId=1&from=now-24h&to=now&var-fqdn={{ $customer->fqdn }}&theme=light"
+  width="100%" height="300" frameborder="0"
+></iframe>
+```
+
+Config required: `allow_embedding = true`, `cookie_samesite = none` (cross-origin), anonymous access/auth proxy, tenant variables via URL params, `&theme=light|dark`.
+
+| Scenario | Approach |
+|---|---|
+| Quick KPI overview | Embed Grafana stat panels |
+| Detailed investigation | Link to full Grafana dashboard |
+| Customer-facing | Build in app (full UX control) |
+
+## Admin Dashboard Design (Laravel)
+
+### Widget types
+
+| Widget | Implementation |
+|---|---|
+| Stat card | Livewire + Tailwind |
+| Trend card | Stat + sparkline (Chart.js / Grafana embed) |
+| Table widget | Livewire table with pagination |
+| Chart widget | Chart.js / Grafana embed |
+| Status list | Blade component with color indicators |
+| Activity feed | Livewire with polling/streaming |
+
+### Layout: F-pattern
+
+```
+┌──────────┬──────────┬──────────┬──────────┐
+│ Stat     │ Stat     │ Stat     │ Stat     │  ← KPI row
+├──────────┴──────────┼──────────┴──────────┤
+│ Chart (trend)       │ Chart (breakdown)   │  ← Viz row
+├─────────────────────┼─────────────────────┤
+│ Table (recent)      │ Activity feed       │  ← Detail row
+└─────────────────────┴─────────────────────┘
+```
+
+### Livewire patterns
+
+- `wire:poll.30s` for auto-refresh
+- `wire:init` for lazy loading expensive queries
+- `$dispatch('refresh-stats')` for cross-widget updates
+- Cache expensive aggregations, refresh on schedule
+
+### Validate
+
+- Verify each panel answers exactly one question.
+- Confirm time ranges are explicit, not "last X" without context.
+- Check that critical KPIs are visible without scrolling.
+- Ensure no chart mixes unrelated metrics on the same axis.
+
+## Output format
+
+1. Dashboard layout with panel placement and visualization types
+2. Data source mapping — which metrics/queries feed each panel
+3. Alerting thresholds where applicable
+
+## Gotcha
+
+- Max 8 panels per dashboard — cognitive overload kills usability.
+- Simple table often beats fancy visualization.
+- Always scope to customer/tenant — no unfiltered admin views.
+- Always define time range explicitly.
+
+## Do NOT
+
+- Do NOT create dashboards with more than 8 panels — cognitive overload.
+- Do NOT mix ops metrics with business KPIs on the same dashboard.
+- Do NOT show admin data without tenant scoping.
+
+## Auto-trigger keywords
+
+- dashboard
+- monitoring dashboard
+- visualization
+- KPI
+- metrics display