@event4u/agent-config 1.9.1

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

@@ -0,0 +1,228 @@
+---
+name: design-review
+description: "Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more."
+source: package
+---
+
+# design-review
+
+## When to use
+
+Use this skill when:
+- Reviewing pull requests with UI changes
+- Auditing frontend components for design quality
+- Verifying responsive design across viewports
+- Checking accessibility compliance (WCAG 2.1 AA)
+- Testing interaction flows and user experience
+- Conducting visual QA on new features
+
+Do NOT use when:
+- Creating new designs (use `fe-design` skill instead)
+- Reviewing backend/API code only
+- Quick syntax checks (use linters)
+
+## Prerequisites
+
+One of the following browser automation tools:
+- **Playwright MCP** (recommended) — browser automation, screenshots, viewport testing
+- **Chrome DevTools** — screenshot capture, performance analysis
+
+A **live preview URL** is required for testing.
+
+## Procedure: Design review
+
+### Phase 0: Preparation
+
+- Read PR description and git diff.
+- Identify changed components and affected pages.
+- Navigate to preview URL.
+- Take baseline screenshot.
+
+### Phase 1: Interaction
+
+- Test user flows end-to-end.
+- Verify hover, focus, active, and disabled states.
+- Test keyboard navigation (Tab, Enter, Escape, Arrow keys).
+- Check loading states and transitions.
+- Verify form submission and error recovery.
+
+### Phase 2: Responsiveness
+
+Test at three viewports:
+
+| Viewport | Width | Device |
+|---|---|---|
+| Desktop | 1440px | Standard monitor |
+| Tablet | 768px | iPad |
+| Mobile | 375px | iPhone SE |
+
+- Take screenshots at each viewport.
+- Check layout shifts, overflow, and content reflow.
+- Verify touch targets are at least 44x44px on mobile.
+
+### Phase 3: Visual Polish
+
+- **Typography:** Font sizes, weights, line heights, hierarchy.
+- **Spacing:** Consistent margins, padding, alignment.
+- **Colors:** Contrast ratios, brand consistency, dark mode.
+- **Alignment:** Grid alignment, visual balance.
+- **Icons:** Consistent size, style, and spacing.
+
+### Phase 4: Accessibility (WCAG 2.1 AA)
+
+| Criterion | Check |
+|---|---|
+| **1.1.1** | All images have meaningful alt text |
+| **1.3.1** | Semantic HTML (headings, landmarks, lists) |
+| **1.4.3** | Color contrast ≥ 4.5:1 (text), ≥ 3:1 (large text) |
+| **1.4.11** | Non-text contrast ≥ 3:1 (UI components, borders) |
+| **2.1.1** | All functionality available via keyboard |
+| **2.4.3** | Focus order is logical and predictable |
+| **2.4.7** | Focus indicator is visible |
+| **3.3.1** | Error messages identify the field and describe the error |
+| **3.3.2** | Labels and instructions for form inputs |
+| **4.1.2** | ARIA roles, states, and properties are correct |
+
+### Phase 5: Robustness
+
+- **Empty states:** What happens with no data?
+- **Error states:** What happens when things fail?
+- **Content overflow:** Long text, many items, large numbers.
+- **Loading states:** Skeleton screens, spinners, progressive loading.
+- **Boundary values:** Min/max inputs, special characters.
+
+### Phase 6: Code Health
+
+- Component reuse — are existing components used where possible?
+- Design tokens — are colors, spacing, fonts from the design system?
+- CSS patterns — utility classes vs. custom CSS, consistency.
+- Accessibility in code — semantic HTML, ARIA attributes.
+
+### Phase 7: Content & Console
+
+- Grammar and spelling in UI text.
+- Consistent terminology and tone.
+- No placeholder text left in production.
+- Check browser console for JavaScript errors or warnings.
+
+## Communication principles
+
+### Problems over prescriptions
+
+Describe **what's wrong and why it matters**, not how to fix it.
+
+```
+❌ "Change margin to 16px"
+✅ "Spacing feels inconsistent with adjacent elements, creating visual clutter near the CTA."
+```
+
+### Triage matrix
+
+Every issue gets a severity:
+
+| Severity | Meaning | Action |
+|---|---|---|
+| **Blocker** | Must fix before merge | Blocks PR |
+| **High** | Should fix before merge | Strong recommendation |
+| **Medium** | Consider for follow-up | Suggestion |
+| **Nitpick** | Optional polish | Prefix with "Nit:" |
+
+### Evidence-based
+
+Screenshots required for all visual issues. Reference specific viewport and state.
+
+### Start positive
+
+Acknowledge what works well before listing issues.
+
+## Report structure
+
+```markdown
+## Design Review Summary
+[Positive opening + overall assessment]
+
+### 🚫 Blockers
+[Critical issues — must fix]
+
+### ⚠️ High Priority
+[Significant issues — should fix]
+
+### 💡 Suggestions
+[Improvements for follow-up]
+
+### ✨ Nitpicks
+[Minor aesthetic details]
+
+### Testing Evidence
+[Screenshots: Desktop, Tablet, Mobile]
+
+### Next Steps
+1. [Fix blockers]
+2. [Address high-priority]
+
+**Overall: [Ready to merge | Needs revisions]**
+```
+
+
+## Visual QA with browser automation
+
+When Playwright MCP or browser tools are available, use them for automated visual verification:
+
+### Before/After comparison
+
+1. **Capture baseline** — screenshot before changes at all 3 viewports.
+2. **Apply changes** — deploy or hot-reload.
+3. **Capture after** — screenshot at the same viewports and states.
+4. **Compare** — visually diff the screenshots, flag regressions.
+
+### State-based verification
+
+Don't just screenshot the default state. Capture:
+
+| State | How to trigger |
+|---|---|
+| Empty | Remove data, check empty state UI |
+| Loading | Throttle network, capture skeleton/spinner |
+| Error | Force an error response, check error UI |
+| Overflow | Add very long text, many items |
+| Interactive | Hover, focus, open dropdowns |
+
+### Mockup-to-code verification
+
+When implementing from a design mockup or screenshot:
+
+1. **Open the mockup** — use the provided image/screenshot.
+2. **Implement** — build the UI component.
+3. **Side-by-side** — compare mockup vs. implementation at the same viewport.
+4. **Flag deviations** — spacing, colors, typography, alignment differences.
+
+This is especially useful when the user provides a screenshot or Figma export as a reference.
+
+## Output format
+
+1. Design review report following the Report structure section
+2. Severity-rated findings (blocker, suggestion, nit)
+3. Accessibility and responsive compliance summary
+
+## Auto-trigger keywords
+
+- design review
+- UI review
+- UX audit
+- accessibility
+- WCAG
+- responsive
+
+## Gotcha
+
+- Don't review design without understanding the user's constraints (time, resources, scope).
+- The model tends to suggest accessibility improvements that break the existing design system.
+- "Best practice" is not always the right choice — sometimes "good enough" ships faster.
+
+## Do NOT
+
+- Do NOT skip accessibility testing — it's not optional.
+- Do NOT report issues without evidence (screenshots, specific elements).
+- Do NOT prescribe solutions — describe problems and impact.
+- Do NOT block PRs on nitpicks.
+- Do NOT test only at desktop resolution.

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

@@ -0,0 +1,121 @@
+---
+name: devcontainer
+description: "Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'."
+source: package
+---
+
+# devcontainer
+
+## When to use
+
+Use this skill when working with DevContainer configuration, GitHub Codespaces setup, or development environment standardization.
+
+Do NOT use when:
+- Local Docker setup without Codespaces (use `docker` skill)
+- Production deployment (use `aws-infrastructure` skill)
+
+## Procedure: Modify DevContainer
+
+1. **Gather context** — read `.devcontainer/devcontainer.json`, check `.devcontainer/` for env files and docs, check `agents/overrides/skills/devcontainer.md` for project-specific overrides.
+2. **Identify change type** — classify: image change, feature addition, secret addition, extension change, or env var change.
+3. **Make the change** — edit `devcontainer.json` (or related files). Follow conventions below for secrets, features, and environment variables.
+4. **Build and verify** — run `devcontainer build` to confirm the container builds. Check that extensions load and ports forward correctly.
+5. **Document** — if adding a new secret or dependency, update the onboarding docs in `.devcontainer/`.
+
+## Architecture
+
+### Custom image
+
+DevContainers typically use a **pre-built custom image** hosted on a container registry (GHCR, ECR, Docker Hub). Read `devcontainer.json` for the image URL.
+
+The image should include:
+- Language runtime (PHP, Node.js, Python, etc.)
+- Package managers (Composer, npm, etc.)
+- Common development tools
+
+### Features (installed on top of the image)
+
+Common features:
+
+| Feature | Purpose |
+|---|---|
+| `git` | Git version control |
+| `github-cli` | GitHub CLI (`gh`) for API access |
+| `docker-in-docker` | Run Docker inside the DevContainer |
+
+### Secrets management
+
+Secrets can be managed via:
+- **File mounts**: `.devcontainer/.secrets/<NAME>` → `/run/secrets/<NAME>`
+- **GitHub Codespaces secrets**: configured in the repository settings
+- **Environment variables**: in `.devcontainer/devcontainer.env`
+
+Read `devcontainer.json` for the actual secret definitions and requirements.
+
+### Workspace
+
+- **Workspace folder**: typically `/workspace` or `/workspaces/{repo-name}`
+- **Mount type**: bind mount from local workspace
+- Container name and hostname: defined in `devcontainer.json`
+
+### IDE integration
+
+- VS Code Live Share for collaborative development
+- IDE extensions can be pre-configured in `devcontainer.json`
+
+## Conventions
+
+### Adding new secrets
+
+1. Add the secret definition to `devcontainer.json` → `secrets` section.
+2. Add a bind mount from `.devcontainer/.secrets/<NAME>` to `/run/secrets/<NAME>`.
+3. Document the secret with `description` and `documentationUrl`.
+4. Mark as required or optional.
+
+### Modifying the base image
+
+- If the base image is maintained in a separate repository, do NOT change the image tag without coordination.
+- Prefer adding **features** over modifying the base image.
+
+### Environment variables
+
+- Runtime env vars go in `.devcontainer/devcontainer.env`.
+- Secrets go in `.devcontainer/.secrets/` (gitignored).
+- Do NOT hardcode secrets in `devcontainer.json`.
+
+## Output format
+
+1. Updated devcontainer.json or related configuration files
+2. Summary of changes and rebuild requirements
+
+## Auto-trigger keywords
+
+- DevContainer
+- Codespaces
+- dev environment
+- container setup
+
+### Validate
+
+- Verify the DevContainer builds successfully (`devcontainer build`).
+- Confirm all required extensions and features are installed.
+- Check that port forwarding and volume mounts work as expected.
+
+## Gotcha
+
+- DevContainer rebuilds are slow — test configuration changes incrementally, not all at once.
+- Secrets in devcontainer.json are visible in version control — use Codespaces secrets instead.
+- Extensions in devcontainer.json install on EVERY rebuild — keep the list short.
+
+## Do NOT
+
+- Do NOT commit secret files — they should be gitignored.
+- Do NOT change the workspace mount path without updating all related configs.
+- Do NOT remove required secrets without checking which services depend on them.
+- Do NOT switch base images without team approval.
+
+## Related
+
+- **Skill:** `docker` — Docker setup, multi-stage Dockerfile, compose services
+- **Skill:** `traefik` — local reverse proxy with real domains and HTTPS
+- **Rule:** `docker-commands.md` — commands run inside Docker

package/.agent-src/skills/developer-like-execution/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: developer-like-execution
+description: "Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# developer-like-execution
+
+## When to use
+
+- Implementing features
+- Fixing bugs
+- Refactoring code
+- Analyzing unexpected behavior
+- Debugging backend or frontend issues
+- Creating or refactoring skills, rules, commands, or agent docs
+- Working with APIs, frontend, or backend logic
+
+Do NOT use when only explaining concepts or writing pure reference documentation without execution.
+
+## Goal
+
+Act like a real developer: think before acting, analyze before coding, verify before concluding.
+Avoid unnecessary trial-and-error. Minimize output, token usage, and irrelevant data.
+Develop against expected behavior, ideally test-first.
+
+## Core principles
+
+- Never start coding before understanding the affected system
+- Prefer analysis over guessing
+- Prefer targeted queries over large output dumps
+- Avoid unnecessary loops, retries, and blind experimentation
+- Always verify behavior with real execution when possible
+- Prefer tests first when expected behavior can be defined
+- If requirements are unclear, ask a precise question instead of filling gaps with assumptions
+
+## Tool priority
+
+Use the smallest, most targeted tool that gives the needed evidence.
+If a tool is available as MCP server, prefer it over manual alternatives.
+
+### Verification tool mapping
+
+| What changed | Primary tool | MCP alternative |
+|---|---|---|
+| **Backend/API endpoint** | `curl -s \| jq` | Postman MCP (if configured) |
+| **Frontend/UI** | Manual browser check | Playwright MCP (`navigate` + `snapshot`) |
+| **Execution flow/debugging** | Print statements, logs | Xdebug MCP (breakpoints, variable inspection) |
+| **CLI commands/jobs** | Run command, check exit code | — |
+| **Database** | SQL query, migration status | — |
+| **External APIs** | `Http::fake()` in tests | Postman MCP for manual checks |
+
+### Xdebug workflow (when available)
+
+If Xdebug is available (as MCP or IDE integration):
+
+1. Set breakpoints at the suspected code path
+2. Trigger the request (curl, browser, test)
+3. Inspect variables at breakpoint — don't guess values from reading code
+4. Step through to verify actual execution flow vs. assumed flow
+5. Check: is the data what you expected? Is the branch taken what you expected?
+
+Use Xdebug **before** adding print statements or debug logging.
+It's faster and leaves no cleanup work.
+
+### Playwright for frontend verification
+
+When UI changes are involved:
+
+1. Navigate to the affected page
+2. Take a snapshot of the rendered state
+3. Verify the expected elements are present and interactive
+4. Check console/network for errors
+5. Compare before/after if refactoring
+
+### Prefer targeted output
+
+- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'` — never the full response
+- `rg`, `grep` for text: specific patterns, not full files
+- `head`, `tail`, `cut`, `sort`, `uniq` for narrowing results
+- `--filter`, `--json`, `--format` flags on CLI tools — always use them
+- Laravel: `route:list --json | jq '.[] | select(.uri | test("users"))'`
+- Logs: `rg "request_id=abc123" storage/logs` — never `cat storage/logs/laravel.log`
+
+### Avoid large output by default
+
+Do NOT:
+
+- Dump full JSON if one field is enough
+- Load full route lists when filtering one route is enough
+- Inspect full log files when one request ID or timestamp can isolate the case
+- Re-run broad commands repeatedly without narrowing
+- Load full database tables when a WHERE clause is enough
+
+## Procedure
+
+### 1. Understand the task
+
+- Read the request carefully
+- Identify expected outcome
+- Identify affected system area
+- Identify whether the task is implementation, debugging, refactoring, or analysis
+
+### 2. Check whether requirements are complete
+
+Before acting, verify:
+
+- Expected behavior is clear
+- Acceptance criteria are clear
+- Edge cases are known
+- Affected user flow or API contract is known
+
+If important information is missing:
+
+- Stop execution planning
+- Output a precise clarification request
+- Do NOT silently assume missing requirements
+
+### 3. Analyze BEFORE acting
+
+- Read the affected files
+- Trace data flow and execution path
+- Compare with requirements, tickets, current behavior, tests, existing patterns
+- Identify likely cause and smallest correct change
+- **Consult memory — invariants and prior decisions.** Via
+  [`memory-access`](../../guidelines/agent-infra/memory-access.md), call
+  `retrieve(types=["domain-invariants", "architecture-decisions"], keys=<touched paths>, limit=3)`.
+  A matching `domain-invariant` is a hard constraint — violating it =
+  regression, surface the conflict before proceeding. A matching
+  `architecture-decision` explains *why* the current shape exists; plan
+  around it, do not silently overturn it. Cite matching `id`s in the plan.
+  See [`engineering-memory-data-format`](../../guidelines/agent-infra/engineering-memory-data-format.md)
+  for the schema.
+
+### 4. Define expected behavior first
+
+Prefer test-driven or test-first development whenever practical.
+
+Before changing code, define:
+
+- What should happen
+- What should not happen
+- How success will be verified
+
+Prefer: write or update failing test first → implement against it → run tests again.
+
+If full TDD is not practical: at least write down the expected output before coding.
+
+### 5. Use targeted tools like a real developer
+
+#### Backend examples
+
+```bash
+# Laravel route lookup — targeted, not full dump
+php artisan route:list --json | jq '.[] | select(.uri == "api/users") | {method, uri, name, action, middleware}'
+
+# Config/debug
+php artisan config:show app | grep env
+
+# API inspection — extract only what you need
+curl -s http://localhost/api/users | jq '.[0] | {id, email, status}'
+curl -s http://localhost/api/users/1 | jq '{id, name, roles: [.roles[].name]}'
+
+# Logs — scoped by request ID, timestamp, or error type
+rg "request_id=abc123|OrderFailed" storage/logs
+tail -n 200 storage/logs/laravel.log | rg "payment|timeout"
+
+# Database — targeted queries, not full table dumps
+php artisan tinker --execute="User::where('email', 'test@example.com')->first(['id','email','status'])"
+```
+
+#### Debugging with Xdebug
+
+When available (MCP or IDE), prefer over print/log debugging:
+
+```
+1. Set breakpoint at suspected method
+2. Trigger request: curl -s http://localhost/api/endpoint
+3. Inspect variables at breakpoint
+4. Step through execution to verify actual flow
+5. Remove breakpoint when done — zero cleanup
+```
+
+#### Frontend verification with Playwright
+
+When UI is affected, verify with Playwright (MCP or direct):
+
+- Navigate to affected page
+- Snapshot the rendered state
+- Check: correct elements visible? Interactions work? Console errors?
+- Compare before/after for refactoring
+
+#### General shell filtering
+
+Use `rg` over broad grep, `jq` for JSON, `cut`/`awk`/`sort`/`uniq` to reduce noise.
+Never load full output into context when a filter gives you the answer.
+
+### 6. Form a plan
+
+- What will be changed
+- What will not be changed
+- Which test or verification proves success
+- Which tool gives the smallest useful evidence
+
+### 7. Implement
+
+- Apply focused changes only
+- Follow existing patterns
+- Avoid unrelated rewrites
+- Keep changes scoped to the actual problem
+
+### 8. Write or update tests
+
+Tests are mandatory when behavior changes or bugs are fixed.
+
+Prefer: failing test first → implementation → passing test.
+
+Test types: unit (isolated logic), feature/integration (behavior), UI (frontend), regression (bugs).
+
+If a test cannot be added: state exactly why and explain what verification replaces it.
+
+### 9. Verify with real execution (MANDATORY)
+
+Never trust "it should work" — execute and observe.
+
+| What | How | MCP alternative |
+|---|---|---|
+| Backend/API | `curl -s \| jq`, test endpoint | Postman MCP |
+| Frontend/UI | Browser check | Playwright MCP (navigate + snapshot) |
+| Execution flow | Logs, print debug | Xdebug MCP (breakpoints, step-through) |
+| CLI/Jobs | Run command, check exit code | — |
+| Database | Query result, migration status | — |
+| Skills/rules | Lint, structure check | — |
+
+If a debugging/testing tool is available as MCP server — **prefer it** over manual alternatives.
+
+### 10. Validate
+
+- Result matches requirement
+- Edge cases handled
+- Test coverage sufficient
+- No unnecessary output, retries, or brute force used
+- No important assumption remains hidden
+
+## Output format
+
+1. Task understanding
+2. Analysis summary
+3. Planned change
+4. Test strategy
+5. Implemented change
+6. Verification result
+7. Risks, open questions, or follow-up
+
+## Gotchas
+
+- The model tends to start coding too early → always analyze first
+- The model tends to over-fetch data → always reduce output first
+- The model tends to brute-force retries → prefer targeted inspection
+- The model may skip tests if the fix looks obvious → do not skip them
+- The model may fill unclear requirements with assumptions → ask instead
+
+## Do NOT
+
+- Start coding without understanding the affected system
+- Guess behavior without verifying
+- Load full datasets when partial extraction is enough
+- Rely on long trial-and-error loops
+- Skip tests when behavior changes
+- Skip real verification after changes
+- Modify unrelated parts of the system
+- Hide requirement gaps behind assumptions