@event4u/agent-config 1.9.1

package/docs/skills-catalog.md

@@ -0,0 +1,136 @@
+# Skills Catalog
+
+All **122 skills** available in this package, in alphabetical order.
+Click a skill name to open its SKILL.md and read the full guidance.
+
+> **Regenerate:** `python3 scripts/generate_catalog.py`
+> This file is auto-generated from `SKILL.md` frontmatter — do not edit manually.
+
+| Skill | What your agent learns |
+|---|---|
+| [`adversarial-review`](../.agent-src/skills/adversarial-review/SKILL.md) | ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback. |
+| [`agent-docs-writing`](../.agent-src/skills/agent-docs-writing/SKILL.md) | Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure. |
+| [`analysis-autonomous-mode`](../.agent-src/skills/analysis-autonomous-mode/SKILL.md) | ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work. |
+| [`analysis-skill-router`](../.agent-src/skills/analysis-skill-router/SKILL.md) | Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'. |
+| [`api-design`](../.agent-src/skills/api-design/SKILL.md) | Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design. |
+| [`api-endpoint`](../.agent-src/skills/api-endpoint/SKILL.md) | Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs. |
+| [`api-testing`](../.agent-src/skills/api-testing/SKILL.md) | Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing. |
+| [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) | Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling. |
+| [`authz-review`](../.agent-src/skills/authz-review/SKILL.md) | Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows. |
+| [`aws-infrastructure`](../.agent-src/skills/aws-infrastructure/SKILL.md) | Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS. |
+| [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) | Use when creating or editing Blade views, components, partials, layouts, or view logic — even when the user says 'add a new page' or 'render this data' without naming Blade. |
+| [`blast-radius-analyzer`](../.agent-src/skills/blast-radius-analyzer/SKILL.md) | Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency. |
+| [`bug-analyzer`](../.agent-src/skills/bug-analyzer/SKILL.md) | Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs. |
+| [`check-refs`](../.agent-src/skills/check-refs/SKILL.md) | Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions. |
+| [`code-refactoring`](../.agent-src/skills/code-refactoring/SKILL.md) | Use when the user says "refactor this", "rename class", or "move method". Safely refactors PHP code — finds all callers, updates downstream dependencies, and verifies with quality tools. |
+| [`code-review`](../.agent-src/skills/code-review/SKILL.md) | Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards. |
+| [`command-routing`](../.agent-src/skills/command-routing/SKILL.md) | Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns. |
+| [`command-writing`](../.agent-src/skills/command-writing/SKILL.md) | Use when creating or editing a slash command in .agent-src.uncompressed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'. |
+| [`composer-packages`](../.agent-src/skills/composer-packages/SKILL.md) | Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'. |
+| [`context-authoring`](../.agent-src/skills/context-authoring/SKILL.md) | Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel. |
+| [`context-document`](../.agent-src/skills/context-document/SKILL.md) | Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation. |
+| [`conventional-commits-writing`](../.agent-src/skills/conventional-commits-writing/SKILL.md) | Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits. |
+| [`copilot-agents-optimization`](../.agent-src/skills/copilot-agents-optimization/SKILL.md) | Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience. |
+| [`copilot-config`](../.agent-src/skills/copilot-config/SKILL.md) | 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'. |
+| [`dashboard-design`](../.agent-src/skills/dashboard-design/SKILL.md) | Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling. |
+| [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
+| [`database`](../.agent-src/skills/database/SKILL.md) | 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'. |
+| [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
+| [`description-assist`](../.agent-src/skills/description-assist/SKILL.md) | 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'. |
+| [`design-review`](../.agent-src/skills/design-review/SKILL.md) | 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. |
+| [`devcontainer`](../.agent-src/skills/devcontainer/SKILL.md) | 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'. |
+| [`developer-like-execution`](../.agent-src/skills/developer-like-execution/SKILL.md) | 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. |
+| [`docker`](../.agent-src/skills/docker/SKILL.md) | Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'. |
+| [`dto-creator`](../.agent-src/skills/dto-creator/SKILL.md) | Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping. |
+| [`eloquent`](../.agent-src/skills/eloquent/SKILL.md) | Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions. |
+| [`fe-design`](../.agent-src/skills/fe-design/SKILL.md) | Use when designing frontend interfaces — component architecture, layout patterns, form design, table patterns, responsive strategies, and UX principles for Blade/Livewire/Flux/Tailwind. |
+| [`feature-planning`](../.agent-src/skills/feature-planning/SKILL.md) | Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap. |
+| [`file-editor`](../.agent-src/skills/file-editor/SKILL.md) | Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled. |
+| [`finishing-a-development-branch`](../.agent-src/skills/finishing-a-development-branch/SKILL.md) | Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'. |
+| [`flux`](../.agent-src/skills/flux/SKILL.md) | Use when writing Laravel Flux UI components — the official Livewire component library by the Laravel team. Covers components, slots, and variants. |
+| [`git-workflow`](../.agent-src/skills/git-workflow/SKILL.md) | Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git. |
+| [`github-ci`](../.agent-src/skills/github-ci/SKILL.md) | Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'. |
+| [`grafana`](../.agent-src/skills/grafana/SKILL.md) | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
+| [`guideline-writing`](../.agent-src/skills/guideline-writing/SKILL.md) | Use when creating or editing a guideline in .agent-src.uncompressed/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'. |
+| [`jira-integration`](../.agent-src/skills/jira-integration/SKILL.md) | Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking. |
+| [`jobs-events`](../.agent-src/skills/jobs-events/SKILL.md) | Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling. |
+| [`judge-bug-hunter`](../.agent-src/skills/judge-bug-hunter/SKILL.md) | Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'. |
+| [`judge-code-quality`](../.agent-src/skills/judge-code-quality/SKILL.md) | Use when a diff needs a readability review — naming, single-responsibility, DRY, dead code, mismatch with codebase conventions — dispatched by /review-changes, /do-and-judge, /judge. |
+| [`judge-security-auditor`](../.agent-src/skills/judge-security-auditor/SKILL.md) | Use when a diff may introduce security risk — authZ, injection, secrets, unsafe deserialization, SSRF, XSS, mass assignment — dispatched by /review-changes, /do-and-judge, /judge. |
+| [`judge-test-coverage`](../.agent-src/skills/judge-test-coverage/SKILL.md) | Use when a diff may lack tests — missing assertions, uncovered branches, over-mocking, no regression test for a bug fix — dispatched by /review-changes, /do-and-judge, /judge, even without 'tests'. |
+| [`laravel`](../.agent-src/skills/laravel/SKILL.md) | Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure. |
+| [`laravel-horizon`](../.agent-src/skills/laravel-horizon/SKILL.md) | Use when working with Laravel queues in production — Horizon dashboard, worker supervision, job metrics, balancing strategies — even when the user just says 'my jobs are piling up'. |
+| [`laravel-mail`](../.agent-src/skills/laravel-mail/SKILL.md) | Use when building Laravel emails — Mailables, Markdown templates, queued sending, attachments, previews — even when the user says 'send this as an email' without naming Mailables. |
+| [`laravel-middleware`](../.agent-src/skills/laravel-middleware/SKILL.md) | Use when creating or modifying Laravel middleware — request/response filtering, groups, priority, terminable middleware, or route-level assignment. |
+| [`laravel-notifications`](../.agent-src/skills/laravel-notifications/SKILL.md) | Use when sending notifications via mail, Slack, database, or custom channels — with queuing, on-demand recipients, and notification preferences. |
+| [`laravel-pennant`](../.agent-src/skills/laravel-pennant/SKILL.md) | Use when working with feature flags — Laravel Pennant, gradual rollouts, A/B testing, scope-based flags — even when the user just says 'hide this behind a flag' without naming Pennant. |
+| [`laravel-pulse`](../.agent-src/skills/laravel-pulse/SKILL.md) | Use when setting up Laravel Pulse — real-time dashboard, built-in cards, custom recorders, performance insights — even when the user just says 'I need app monitoring' without naming Pulse. |
+| [`laravel-reverb`](../.agent-src/skills/laravel-reverb/SKILL.md) | Use when configuring Laravel Reverb — the first-party WebSocket server with Pusher protocol compatibility, horizontal scaling, and Pulse monitoring. |
+| [`laravel-scheduling`](../.agent-src/skills/laravel-scheduling/SKILL.md) | Use when configuring Laravel task scheduling — cron expressions, frequency helpers, overlap prevention, maintenance mode, or output handling. |
+| [`laravel-validation`](../.agent-src/skills/laravel-validation/SKILL.md) | 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. |
+| [`learning-to-rule-or-skill`](../.agent-src/skills/learning-to-rule-or-skill/SKILL.md) | 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. |
+| [`lint-skills`](../.agent-src/skills/lint-skills/SKILL.md) | Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata. |
+| [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates. |
+| [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
+| [`mcp`](../.agent-src/skills/mcp/SKILL.md) | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
+| [`merge-conflicts`](../.agent-src/skills/merge-conflicts/SKILL.md) | Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow. |
+| [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
+| [`module-management`](../.agent-src/skills/module-management/SKILL.md) | Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions. |
+| [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) | Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations. |
+| [`openapi`](../.agent-src/skills/openapi/SKILL.md) | Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI. |
+| [`override-management`](../.agent-src/skills/override-management/SKILL.md) | Creates and manages project-level overrides for shared skills, rules, and commands — extending or replacing originals from .augment/ with project-specific behavior in agents/overrides/. |
+| [`performance`](../.agent-src/skills/performance/SKILL.md) | Use when optimizing application performance — caching strategies, eager loading, query optimization, Redis patterns, or background job design. |
+| [`performance-analysis`](../.agent-src/skills/performance-analysis/SKILL.md) | ONLY when user explicitly requests: performance audit, bottleneck analysis, or N+1 query detection. NOT for regular feature work. |
+| [`pest-testing`](../.agent-src/skills/pest-testing/SKILL.md) | Use when writing, generating, or improving Pest tests for Laravel — clear intent, good coverage, maintainable structure, and alignment with project testing conventions. |
+| [`php-coder`](../.agent-src/skills/php-coder/SKILL.md) | Writes or edits PHP code — controllers, classes, type hints, SOLID refactors, modern idioms — even without naming PHP. NOT for writing tests (use pest-testing) or explaining PHP concepts. |
+| [`php-debugging`](../.agent-src/skills/php-debugging/SKILL.md) | Use when debugging PHP with Xdebug — breakpoints, step-through, dual-container setup, IDE configuration, header-based routing — even when the user just says 'why does this blow up on request X'. |
+| [`php-service`](../.agent-src/skills/php-service/SKILL.md) | Use when the user says 'create service', 'new service class', or needs a PHP service following SOLID principles with proper DI and repository usage. |
+| [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
+| [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) | Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research. |
+| [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
+| [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) | Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns. |
+| [`project-analysis-nextjs`](../.agent-src/skills/project-analysis-nextjs/SKILL.md) | Use for deep Next.js analysis: server vs client boundaries, routing, data fetching, caching, rendering modes, and hydration/runtime issues. |
+| [`project-analysis-node-express`](../.agent-src/skills/project-analysis-node-express/SKILL.md) | Use for deep Node.js / Express project analysis: boot flow, middleware order, async behavior, data layer, auth/security, and Node-specific runtime failure patterns. |
+| [`project-analysis-react`](../.agent-src/skills/project-analysis-react/SKILL.md) | Use for deep React analysis: component tree, state flow, props flow, hooks usage, rendering behavior, and React-specific failure patterns. |
+| [`project-analysis-symfony`](../.agent-src/skills/project-analysis-symfony/SKILL.md) | Use for deep Symfony project analysis: kernel/bootstrap, container wiring, routing/request flow, Doctrine, security, Messenger, and Symfony-specific failure patterns. |
+| [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) | Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks. |
+| [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) | ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work. |
+| [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
+| [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
+| [`readme-reviewer`](../.agent-src/skills/readme-reviewer/SKILL.md) | Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues. |
+| [`readme-writing`](../.agent-src/skills/readme-writing/SKILL.md) | Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience. |
+| [`readme-writing-package`](../.agent-src/skills/readme-writing-package/SKILL.md) | Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding. |
+| [`receiving-code-review`](../.agent-src/skills/receiving-code-review/SKILL.md) | Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'. |
+| [`requesting-code-review`](../.agent-src/skills/requesting-code-review/SKILL.md) | Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'. |
+| [`review-routing`](../.agent-src/skills/review-routing/SKILL.md) | Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML. |
+| [`roadmap-management`](../.agent-src/skills/roadmap-management/SKILL.md) | Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking. |
+| [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
+| [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
+| [`security`](../.agent-src/skills/security/SKILL.md) | Use when applying security best practices — authentication, authorization via Policies, CSRF protection, input sanitization, rate limiting, or secure coding. |
+| [`security-audit`](../.agent-src/skills/security-audit/SKILL.md) | ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work. |
+| [`sentry-integration`](../.agent-src/skills/sentry-integration/SKILL.md) | Use when the user shares a Sentry URL, says "check Sentry", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis. |
+| [`sequential-thinking`](../.agent-src/skills/sequential-thinking/SKILL.md) | ONLY when user explicitly requests: step-by-step reasoning, structured problem decomposition, or iterative analysis. NOT for regular coding tasks. |
+| [`skill-improvement-pipeline`](../.agent-src/skills/skill-improvement-pipeline/SKILL.md) | ONLY when user explicitly requests: run the skill improvement pipeline after a learning was detected. Orchestrates capture, classify, create, validate, and apply. |
+| [`skill-management`](../.agent-src/skills/skill-management/SKILL.md) | Use when compressing, decompressing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained. |
+| [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
+| [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
+| [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
+| [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) | Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — model pairing and parallelism from .agent-settings.yml. |
+| [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
+| [`technical-specification`](../.agent-src/skills/technical-specification/SKILL.md) | Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure. |
+| [`terraform`](../.agent-src/skills/terraform/SKILL.md) | Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform. |
+| [`terragrunt`](../.agent-src/skills/terragrunt/SKILL.md) | Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt. |
+| [`test-driven-development`](../.agent-src/skills/test-driven-development/SKILL.md) | Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'. |
+| [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
+| [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
+| [`traefik`](../.agent-src/skills/traefik/SKILL.md) | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
+| [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
+| [`upstream-contribute`](../.agent-src/skills/upstream-contribute/SKILL.md) | Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package. |
+| [`using-git-worktrees`](../.agent-src/skills/using-git-worktrees/SKILL.md) | Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'. |
+| [`"validate-feature-fit"`](../.agent-src/skills/"validate-feature-fit"/SKILL.md) | Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit |
+| [`verify-before-complete`](../.agent-src/skills/verify-before-complete/SKILL.md) | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
+| [`websocket`](../.agent-src/skills/websocket/SKILL.md) | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
+
+---
+
+← [Back to README](../README.md)

package/docs/troubleshooting.md

@@ -0,0 +1,167 @@
+# Troubleshooting
+
+Common problems and how to resolve them. If your case is not covered,
+please open an [issue](https://github.com/event4u-app/agent-config/issues)
+and include the output of:
+
+```bash
+composer show event4u/agent-config            # or: npm ls @event4u/agent-config
+php --version
+python3 --version
+bash scripts/install --verbose --dry-run
+```
+
+---
+
+## Agent doesn't seem to pick up the rules or skills
+
+### Check 1: Are the files actually in the project?
+
+```bash
+ls -la .augment/rules/        # should list real files (rules are copied)
+ls -la .augment/skills/       # should list symlinks
+ls -la .claude/rules/         # Claude users: should list symlinks
+ls -la .cursor/rules/         # Cursor users: should list symlinks
+cat  .windsurfrules           # Windsurf users: should be a populated file
+cat .github/copilot-instructions.md  # Copilot users: should exist
+```
+
+If any of these are missing or empty, the installer either didn't run or
+was interrupted. Re-run it:
+
+```bash
+php vendor/bin/install.php --verbose
+# or
+bash scripts/install --verbose
+# or, to regenerate everything (overwrites existing bridge files):
+bash scripts/install --force
+```
+
+### Check 2: Does your agent actually read these directories?
+
+| Tool | Expected location |
+|---|---|
+| Augment Code | `.augment/rules/`, `.augment/skills/`, `.augment/commands/` |
+| Claude Code | `.claude/rules/`, `.claude/skills/` (symlinks into `.augment/`) |
+| Cursor | `.cursor/rules/*.mdc` |
+| Cline | `.clinerules/` |
+| Windsurf | `.windsurfrules` (single concatenated file) |
+| Gemini CLI | `GEMINI.md` (symlinked to `AGENTS.md`) |
+| GitHub Copilot | `.github/copilot-instructions.md` + `AGENTS.md` |
+
+If a path is missing for your tool, re-running the installer recreates it.
+
+### Check 3: Is the plugin-level install masking the project install?
+
+If you installed the Augment / Claude Code / Copilot CLI plugin globally
+AND also installed the package in the project, the agent may pick up the
+plugin copy instead of the project copy. This is usually fine — both
+should be the same version — but if they have drifted, pin the project
+version explicitly and reinstall the plugin.
+
+---
+
+## `composer require` / `npm install` runs, but no files were created
+
+Several security-conscious setups disable post-install hooks:
+
+```bash
+composer config allow-plugins.false
+# or in ~/.npmrc:
+ignore-scripts=true
+```
+
+In that case, the post-install hook never runs. Execute the installer
+manually:
+
+```bash
+php vendor/bin/install.php          # for Composer
+# or for npm — invoke the orchestrator directly:
+bash node_modules/@event4u/agent-config/scripts/install
+```
+
+The [`scripts/postinstall.sh`](../scripts/postinstall.sh) wrapper prints a
+loud error block when the underlying installer fails, so if you saw no
+output at all, scripts are likely disabled on your side.
+
+---
+
+## Broken symlinks after `composer update` / `npm update`
+
+When the package version changes, symlinks that pointed to the old
+vendor path may break. Re-run the installer — it is idempotent:
+
+```bash
+php vendor/bin/install.php
+# or
+bash scripts/install
+```
+
+The installer replaces stale symlinks with fresh ones pointing at the
+current vendor path.
+
+---
+
+## Installation on Windows
+
+Native Windows is not a first-class target. The installer relies on Bash
+and Unix-style symlinks. Recommended setup:
+
+1. **WSL2** (preferred): install Ubuntu or a distribution of your choice,
+   clone the project inside the WSL filesystem, and run `composer
+   install` / `npm install` from WSL.
+2. **Git Bash**: works for the basic install, but symlinks require
+   Developer Mode (Windows 10 1703+) or admin privileges. Without either,
+   Git Bash falls back to copies, which means updates will not propagate
+   automatically — re-run the installer after each update.
+3. **Plain PowerShell / cmd**: not supported.
+
+If you need native Windows support without WSL, please open an issue —
+we cannot validate changes without access to a Windows setup.
+
+---
+
+## `Python 3 is required but was not found`
+
+The bridge installer is Python-based and needs Python 3.8+ on PATH.
+
+- **macOS 12.3+**: Python 3 is pre-installed as `python3`.
+- **Linux**: `apt install python3` / `dnf install python3` / equivalent.
+- **Windows**: install from [python.org](https://www.python.org/downloads/)
+  or from the Microsoft Store; ensure "Add python.exe to PATH" is
+  checked.
+
+The portability check, compression pipeline, and test suite also depend
+on Python 3 — it is required for contributors, not just consumers.
+
+---
+
+## Uninstalling the package
+
+There is no dedicated uninstall command yet. Remove the package and
+clean up manually:
+
+```bash
+# 1. Remove the dependency
+composer remove event4u/agent-config
+# or
+npm uninstall @event4u/agent-config
+
+# 2. Remove generated content from the project
+rm -rf .augment .claude .cursor .clinerules .windsurfrules GEMINI.md
+rm -f .agent-settings .agent-settings.yml .agent-settings.backup.key-value
+rm -f .github/copilot-instructions.md
+# Remove the "# event4u/agent-config" block from .gitignore manually
+```
+
+Keep `AGENTS.md` if you customized it — it is yours, not the package's.
+
+---
+
+## Still stuck?
+
+Open an [issue](https://github.com/event4u-app/agent-config/issues) with:
+
+- your OS and shell,
+- PHP / Node / Python versions,
+- full output of `bash scripts/install --verbose --dry-run`.

package/llms.txt

@@ -0,0 +1,130 @@
+# agent-config — Skill Index
+
+Machine-readable index of all skills in this package. Each line:
+  <skill-name>: <one-line description>
+
+Source: .agent-src/skills/<name>/SKILL.md
+Catalog: docs/skills-catalog.md
+
+adversarial-review: ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback.
+agent-docs-writing: Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure.
+analysis-autonomous-mode: ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work.
+analysis-skill-router: Use when picking which analysis or project-analysis-* skill fits a request — routes by scope, framework, and symptom — even if the user just says 'analyze this' or 'dig into the codebase'.
+api-design: Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design.
+api-endpoint: Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs.
+api-testing: Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing.
+artisan-commands: Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling.
+authz-review: Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows.
+aws-infrastructure: Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS.
+blade-ui: Use when creating or editing Blade views, components, partials, layouts, or view logic — even when the user says 'add a new page' or 'render this data' without naming Blade.
+blast-radius-analyzer: Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency.
+bug-analyzer: Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs.
+check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
+code-refactoring: Use when the user says "refactor this", "rename class", or "move method". Safely refactors PHP code — finds all callers, updates downstream dependencies, and verifies with quality tools.
+code-review: Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards.
+command-routing: Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns.
+command-writing: Use when creating or editing a slash command in .agent-src.uncompressed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'.
+composer-packages: Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'.
+context-authoring: Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel.
+context-document: Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation.
+conventional-commits-writing: Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits.
+copilot-agents-optimization: Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience.
+copilot-config: 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'.
+dashboard-design: Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling.
+data-flow-mapper: Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line.
+database: 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'.
+dependency-upgrade: Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification.
+description-assist: 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'.
+design-review: 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.
+devcontainer: 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'.
+developer-like-execution: 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.
+docker: Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'.
+dto-creator: Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping.
+eloquent: Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions.
+fe-design: Use when designing frontend interfaces — component architecture, layout patterns, form design, table patterns, responsive strategies, and UX principles for Blade/Livewire/Flux/Tailwind.
+feature-planning: Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap.
+file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
+finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'.
+flux: Use when writing Laravel Flux UI components — the official Livewire component library by the Laravel team. Covers components, slots, and variants.
+git-workflow: Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git.
+github-ci: Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'.
+grafana: Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana.
+guideline-writing: Use when creating or editing a guideline in .agent-src.uncompressed/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'.
+jira-integration: Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking.
+jobs-events: Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling.
+judge-bug-hunter: Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'.
+judge-code-quality: Use when a diff needs a readability review — naming, single-responsibility, DRY, dead code, mismatch with codebase conventions — dispatched by /review-changes, /do-and-judge, /judge.
+judge-security-auditor: Use when a diff may introduce security risk — authZ, injection, secrets, unsafe deserialization, SSRF, XSS, mass assignment — dispatched by /review-changes, /do-and-judge, /judge.
+judge-test-coverage: Use when a diff may lack tests — missing assertions, uncovered branches, over-mocking, no regression test for a bug fix — dispatched by /review-changes, /do-and-judge, /judge, even without 'tests'.
+laravel: Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure.
+laravel-horizon: Use when working with Laravel queues in production — Horizon dashboard, worker supervision, job metrics, balancing strategies — even when the user just says 'my jobs are piling up'.
+laravel-mail: Use when building Laravel emails — Mailables, Markdown templates, queued sending, attachments, previews — even when the user says 'send this as an email' without naming Mailables.
+laravel-middleware: Use when creating or modifying Laravel middleware — request/response filtering, groups, priority, terminable middleware, or route-level assignment.
+laravel-notifications: Use when sending notifications via mail, Slack, database, or custom channels — with queuing, on-demand recipients, and notification preferences.
+laravel-pennant: Use when working with feature flags — Laravel Pennant, gradual rollouts, A/B testing, scope-based flags — even when the user just says 'hide this behind a flag' without naming Pennant.
+laravel-pulse: Use when setting up Laravel Pulse — real-time dashboard, built-in cards, custom recorders, performance insights — even when the user just says 'I need app monitoring' without naming Pulse.
+laravel-reverb: Use when configuring Laravel Reverb — the first-party WebSocket server with Pusher protocol compatibility, horizontal scaling, and Pulse monitoring.
+laravel-scheduling: Use when configuring Laravel task scheduling — cron expressions, frequency helpers, overlap prevention, maintenance mode, or output handling.
+laravel-validation: 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.
+learning-to-rule-or-skill: 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.
+lint-skills: Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata.
+livewire: Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates.
+logging-monitoring: Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers.
+mcp: Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows.
+merge-conflicts: Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow.
+migration-creator: Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness.
+module-management: Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions.
+multi-tenancy: Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations.
+openapi: Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI.
+override-management: Creates and manages project-level overrides for shared skills, rules, and commands — extending or replacing originals from .augment/ with project-specific behavior in agents/overrides/.
+performance: Use when optimizing application performance — caching strategies, eager loading, query optimization, Redis patterns, or background job design.
+performance-analysis: ONLY when user explicitly requests: performance audit, bottleneck analysis, or N+1 query detection. NOT for regular feature work.
+pest-testing: Use when writing, generating, or improving Pest tests for Laravel — clear intent, good coverage, maintainable structure, and alignment with project testing conventions.
+php-coder: Writes or edits PHP code — controllers, classes, type hints, SOLID refactors, modern idioms — even without naming PHP. NOT for writing tests (use pest-testing) or explaining PHP concepts.
+php-debugging: Use when debugging PHP with Xdebug — breakpoints, step-through, dual-container setup, IDE configuration, header-based routing — even when the user just says 'why does this blow up on request X'.
+php-service: Use when the user says 'create service', 'new service class', or needs a PHP service following SOLID principles with proper DI and repository usage.
+playwright-testing: Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns.
+project-analysis-core: Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research.
+project-analysis-hypothesis-driven: Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'.
+project-analysis-laravel: Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns.
+project-analysis-nextjs: Use for deep Next.js analysis: server vs client boundaries, routing, data fetching, caching, rendering modes, and hydration/runtime issues.
+project-analysis-node-express: Use for deep Node.js / Express project analysis: boot flow, middleware order, async behavior, data layer, auth/security, and Node-specific runtime failure patterns.
+project-analysis-react: Use for deep React analysis: component tree, state flow, props flow, hooks usage, rendering behavior, and React-specific failure patterns.
+project-analysis-symfony: Use for deep Symfony project analysis: kernel/bootstrap, container wiring, routing/request flow, Doctrine, security, Messenger, and Symfony-specific failure patterns.
+project-analysis-zend-laminas: Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks.
+project-analyzer: ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work.
+project-docs: Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs.
+quality-tools: Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned.
+readme-reviewer: Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues.
+readme-writing: Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience.
+readme-writing-package: Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding.
+receiving-code-review: Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'.
+requesting-code-review: Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'.
+review-routing: Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML.
+roadmap-management: Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking.
+rtk-output-filtering: Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns.
+rule-writing: Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'.
+security: Use when applying security best practices — authentication, authorization via Policies, CSRF protection, input sanitization, rate limiting, or secure coding.
+security-audit: ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work.
+sentry-integration: Use when the user shares a Sentry URL, says "check Sentry", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis.
+sequential-thinking: ONLY when user explicitly requests: step-by-step reasoning, structured problem decomposition, or iterative analysis. NOT for regular coding tasks.
+skill-improvement-pipeline: ONLY when user explicitly requests: run the skill improvement pipeline after a learning was detected. Orchestrates capture, classify, create, validate, and apply.
+skill-management: Use when compressing, decompressing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained.
+skill-reviewer: Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations.
+skill-writing: Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'.
+sql-writing: Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL.
+subagent-orchestration: Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — model pairing and parallelism from .agent-settings.yml.
+systematic-debugging: Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'.
+technical-specification: Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure.
+terraform: Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform.
+terragrunt: Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt.
+test-driven-development: Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'.
+test-performance: Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives.
+threat-modeling: Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation.
+traefik: Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing.
+universal-project-analysis: ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills.
+upstream-contribute: Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package.
+using-git-worktrees: Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'.
+"validate-feature-fit": Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit
+verify-before-complete: Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs.
+websocket: Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'.

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@event4u/agent-config",
+    "version": "1.9.1",
+    "description": "Shared agent configuration — skills, rules, commands, guidelines, and templates for AI coding tools",
+    "license": "MIT",
+    "private": false,
+    "files": [
+        ".agent-src/",
+        ".augment-plugin/",
+        ".claude-plugin/",
+        "bin/",
+        "config/",
+        "docs/",
+        "scripts/",
+        "templates/",
+        "AGENTS.md",
+        "CHANGELOG.md",
+        "CONTRIBUTING.md",
+        "LICENSE",
+        "README.md",
+        "composer.json",
+        "llms.txt"
+    ],
+    "scripts": {
+        "postinstall": "bash scripts/postinstall.sh"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    }
+}