@event4u/agent-config 1.19.0 → 1.21.0

package/docs/guidelines/php/php-coding-patterns.md

@@ -0,0 +1,62 @@
+# Php Coding
+
+> Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions
+
+_Origin: migrated from `.agent-src.uncompressed/rules/php-coding.md` per P4.2 of `road-to-kernel-and-router.md`._
+
+# PHP Coding Rules
+
+- Use `declare(strict_types=1)` in every **new** PHP file. Not required when modifying existing files that don't have it.
+- If the project has a `Math` helper class, use it for ALL business calculations. Never use native PHP arithmetic operators (`+`, `-`, `*`, `/`) for business calculations. Search for the `Math` class in the project.
+- Never use `var_dump()`, `print_r()`, or `dd()` — they are disallowed by PHPStan config. Exception: legacy projects where these are already used and no alternative is feasible.
+- Never use `float` for money — use `decimal` or the `Math` helper.
+- Always use `===` / `!==` (strict comparison), Yoda style: `null === $var`.
+- Early return over nested if/else.
+- No one-liner if statements.
+- Single quotes for strings without interpolation. `sprintf()` for complex strings.
+- Variables: `camelCase`. Array keys: `snake_case`. Constants: `UPPER_SNAKE_CASE`.
+- Typed properties, parameters, and return types — always.
+- Constructor property promotion where it makes sense.
+
+## Eloquent Models — Attribute Access
+
+Read `eloquent.access_style` from `.agent-settings.yml` to determine the preferred style.
+Default: `getters_setters`. See the `eloquent` skill for the full reference table and examples.
+
+- **`getters_setters`** (strict): Every attribute has a typed getter + fluent setter. Inside the model: `getAttribute('column_name')`/`setAttribute('column_name', $value)`. Outside: always getters/setters. If a getter doesn't exist yet, create it first.
+- **`get_attribute`**: Use `getAttribute('column_name')`/`setAttribute('column_name', $value)` everywhere, no getters/setters needed.
+- **`magic_properties`**: Laravel default `$model->column_name` everywhere.
+
+### Relationship Getters
+
+- Every relationship MUST have a typed getter method **above** the relationship method.
+- **Inside the getter:** use `$this->getAttribute('relationship_name')`, NEVER `$this->relationship_name`.
+- **Outside the model:** ALWAYS use the getter (`$model->getEquipment()`), NEVER access the magic property (`$model->equipment`).
+- Use `instanceof` checks instead of `null ===` when checking relationship results.
+
+## Eloquent Models — Observers over `booted()`
+
+- Do NOT use `booted()` / `boot()` for model lifecycle hooks (saving, saved, deleted, etc.).
+- Use a dedicated **Observer** class registered via `#[ObservedBy]` attribute.
+- This keeps models slim and lifecycle logic testable and discoverable.
+
+## PHPStan
+
+- Always fix the root cause. Do NOT add entries to `phpstan-baseline.neon`.
+- Adding `ignoreErrors` to `phpstan.neon` is allowed for **structural toolchain limitations** (e.g., Pest runtime bindings). NOT for individual code issues. **If unsure → ask the user.**
+- If a fix is truly impossible (confirmed false positive), use an inline ignore as last resort:
+  ```php
+  // @phpstan-ignore-next-line — false positive: reason here
+  ```
+
+## Testing
+
+- Always write tests in **Pest**, not PHPUnit class syntax — unless the user explicitly asks for PHPUnit.
+- Pest tests in `tests/Unit/` automatically use `UnitTestCase` as the base class (configured in `tests/Pest.php`).
+
+## PHPDoc
+
+- Only add PHPDoc when type hints are insufficient (e.g. generic arrays: `@param array<int, MyObject> $items`).
+- Do NOT add PHPDoc that just repeats the method signature.
+- One docblock per method — never split into multiple `/** */` blocks.
+- Tag order: `@param` → `@return` → `@throws`.

package/docs/hook-payload-capture.md

@@ -0,0 +1,221 @@
+# Hook payload capture guide
+
+**Purpose:** walk through the live-session payload capture for one platform
+in roughly 5 minutes, so the corresponding entry in
+[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+can move from `docs-verified` to `payload-verified`.
+
+**Scope:** Cursor · Cline · Windsurf · Gemini CLI. Augment Code and Claude
+Code already shipped as `docs-verified` in Phase 1 of the now-archived
+[`road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md).
+Cowork is upstream-blocked separately
+([`#40495`](https://github.com/anthropics/claude-code/issues/40495)) and
+not in scope here.
+
+**Why this is opportunistic:** the payload-verified upgrade is a nice-to-have.
+The shipping `docs-verified` extractors already match the vendor docs —
+captures are insurance against silent vendor-side schema drift. Pick one
+platform when convenient; do not run all four in one sitting unless you
+already have all four IDEs installed and licensed.
+
+## Pre-flight (one-time, ~30 seconds)
+
+```bash
+cd /path/to/agent-config
+
+# Confirm the dispatcher is wired in this project (idempotent — safe to rerun).
+# Replace <platform> with cursor / cline / windsurf / gemini as appropriate
+# when you reach that platform's section.
+python3 scripts/install.py --<platform>
+
+# Confirm the trampoline + project-scope hooks file landed.
+./agent-config hooks:status | grep -E "^[ ✓✅⚠️❌·] (cursor|cline|windsurf|gemini)"
+```
+
+`hooks:status` should report `installed` for the platform you just wired
+(or `missing` if the project-scope file did not land — in that case rerun
+the install with `--force`).
+
+## Common capture loop (steps reused on every platform)
+
+```bash
+# 1. Pick a per-platform capture dir (gitignored; never committed).
+export AGENT_HOOK_CAPTURE_DIR="$HOME/.agent-config-captures/<platform>"
+mkdir -p "$AGENT_HOOK_CAPTURE_DIR"
+
+# 2. Restart / reload the platform so it picks up the env var.
+#    Per-platform commands below.
+
+# 3. Run ONE short, boring session in the platform.
+#    Recommended prompt: "echo hello" or "what time is it".
+#    Goal is to capture the envelope shape, not interesting content.
+
+# 4. Confirm capture files exist.
+ls -1 "$AGENT_HOOK_CAPTURE_DIR" | head
+
+# 5. Redact (replaces user-content fields with <REDACTED>;
+#    envelope keys preserved).
+python3 scripts/redact_hook_capture.py "$AGENT_HOOK_CAPTURE_DIR" --strict
+
+# 6. Pick the smallest representative file.
+ls -1Sr "$AGENT_HOOK_CAPTURE_DIR"/*.redacted.json | head -1
+
+# 7. cat it; copy the JSON; paste into the archived roadmap section
+#    (see § Where to paste below).
+```
+
+The redaction step is non-negotiable. The goal is to lock schemas, not to
+archive conversations.
+
+## Per-platform notes
+
+### Cursor (~5 min)
+
+- **Install:** `python3 scripts/install.py --cursor` (project) or
+  `--cursor-user-hooks` (covers every project you open).
+- **Restart:** quit Cursor (Cmd+Q on macOS), then relaunch from the
+  shell where you exported `AGENT_HOOK_CAPTURE_DIR` so the env var
+  propagates to the renderer process. Reopening a window from the
+  Dock will not inherit the env.
+- **Trigger event:** type a prompt in Cursor's agent panel and let it
+  finish. Expected captures: one `sessionStart`, one
+  `beforeSubmitPrompt`, one `afterAgentResponse` and/or `stop`,
+  zero or more `postToolUse`.
+- **File pattern:** `cursor__afterAgentResponse__<ts>__<pid>.json` is
+  the most useful one to paste.
+- **CLI vs IDE:** Cursor CLI fires only
+  `beforeShellExecution`/`afterShellExecution` — for the
+  per-turn payload you need the IDE.
+
+### Cline (~5 min)
+
+- **Install:** `python3 scripts/install.py --cline` (project) or
+  `--cline-user-hooks` (user-scope, covers every workspace).
+- **Restart:** in VS Code or JetBrains, run "Developer: Reload
+  Window" (Cmd+Shift+P) from a terminal where the env is exported.
+  Cline reads hooks at task start, so a fresh task is required —
+  closing and reopening the side panel is not enough.
+- **Trigger event:** start a new Cline task and let one turn complete.
+  Cline calls them "tasks" not "sessions"; the equivalent boundaries
+  are `TaskStart` → `UserPromptSubmit` → `PostToolUse`* →
+  `TaskComplete`.
+- **File pattern:** `cline__TaskComplete__<ts>__<pid>.json` if you let
+  the task finish; `cline__UserPromptSubmit__<ts>__<pid>.json` is also
+  acceptable (carries the `prompt` envelope).
+- **Windows caveat:** hooks are unsupported on Windows
+  ([`cline/cline#8073`](https://github.com/cline/cline/issues/8073));
+  capture from macOS or Linux.
+
+### Windsurf (~5 min)
+
+- **Install:** `python3 scripts/install.py --windsurf` (project) or
+  `--windsurf-user-hooks` (user-scope at `~/.codeium/windsurf/hooks.json`).
+- **Restart:** quit Cascade fully, then relaunch from the shell with
+  the env exported. The `pre_user_prompt` event fires on every turn —
+  no full restart needed once Cascade is up, but the *first* turn after
+  launch must be the captured one.
+- **Trigger event:** ask Cascade one short question and let it answer.
+  Expected captures: `pre_user_prompt`,
+  `post_cascade_response_with_transcript`. The
+  `_with_transcript` variant is the more useful one to paste because it
+  carries the full response inline.
+- **File pattern:** `windsurf__post_cascade_response_with_transcript__<ts>__<pid>.json`.
+- **Async caveat:** `post_cascade_response` fires asynchronously off
+  the critical path. The capture file might land a second or two after
+  the response renders — wait briefly before running the redact step.
+
+### Gemini CLI (~5 min)
+
+- **Install:** `python3 scripts/install.py --gemini` (project) or
+  `--gemini-user-hooks` (user-scope at `~/.gemini/settings.json`).
+- **Restart:** Gemini CLI is invoked per command — no daemon to
+  restart. Just open a new shell with `AGENT_HOOK_CAPTURE_DIR`
+  exported and run the next session there.
+- **Trigger event:** any short Gemini CLI session
+  (`gemini "what time is it"` or similar). Hooks fire on
+  `SessionStart` → `BeforeAgent` → `AfterTool`* → `AfterAgent` →
+  `SessionEnd`.
+- **File pattern:** `gemini__AfterAgent__<ts>__<pid>.json` carries the
+  per-turn close envelope and is the recommended paste target.
+- **Advisory hooks:** `SessionStart` and `SessionEnd` are advisory only
+  in Gemini CLI — do not be alarmed if those captures look thinner than
+  the others.
+
+## Where to paste the redacted payload
+
+The roadmap is now archived. Paste under the matching phase:
+
+[`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)
+
+- Cursor → § Phase 2 — Cursor
+- Cline → § Phase 3 — Cline
+- Windsurf → § Phase 4 — Windsurf
+- Gemini CLI → § Phase 5 — Gemini CLI
+
+In the chosen phase, paste the redacted JSON inside a fenced
+`json` block under a heading like `### <Platform> payload shape (captured 2026-MM-DD)`,
+then flip the `[ ] Optional upgrade — payload-verified` checkbox to
+`[x]`.
+
+Then update the matching row in
+[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md):
+the `Verification` column moves from `docs-verified` to
+`payload-verified`.
+
+If the captured shape diverges from the docs-verified extractor
+branch, that is the trigger for a code patch — open a tiny new roadmap
+under `agents/roadmaps/` for the divergence work, do **not** edit the
+archived roadmap to track new code work
+(see [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md)).
+
+## Final verify
+
+After pasting and flipping the checkbox:
+
+```bash
+# Lint gates must stay green.
+python3 scripts/lint_hook_manifest.py
+python3 scripts/check_references.py
+python3 scripts/check_portability.py
+
+# Tests still green.
+python3 -m pytest tests/hooks/ -q
+
+# Optional: regenerate the dashboard if the archived roadmap's
+# checkbox change should bubble up. Iron Law from
+# `roadmap-progress-sync` says yes if it does.
+./agent-config roadmap:progress
+```
+
+Per
+[`commit-policy`](../.agent-src/rules/commit-policy.md):
+do **not** commit unless explicitly told to. The user owns the commit
+step.
+
+## Cleanup after capture
+
+```bash
+# Raw captures (not redacted) contain real prompt content.
+# Either delete the directory or leave it for repeat captures.
+rm -rf "$AGENT_HOOK_CAPTURE_DIR"
+
+# Or keep redacted ones only:
+# find "$AGENT_HOOK_CAPTURE_DIR" -type f ! -name '*.redacted.json' -delete
+
+# Unset the env var when done so subsequent sessions do not capture.
+unset AGENT_HOOK_CAPTURE_DIR
+```
+
+The capture directory is gitignored project-wide; raw captures are
+never accidentally committed. The redaction step is still mandatory
+before paste because the redacted output goes into a tracked file
+(the archived roadmap) and would otherwise leak.
+
+## Sources
+
+- Capture engine: [`scripts/hooks/dispatch_hook.py`](../scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
+- Redactor: [`scripts/redact_hook_capture.py`](../scripts/redact_hook_capture.py)
+- Per-platform install logic: [`scripts/install.py`](../scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
+- Platform matrix + payload schemas: [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+- Hook architecture: [`docs/contracts/hook-architecture-v1.md`](contracts/hook-architecture-v1.md)
+- Archived roadmap with per-phase paste sections: [`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)

package/docs/migrations/commands-1.15.0.md

@@ -85,18 +85,23 @@ the deprecation cycle for Phase 1 closes. Tracked in
 [`agents/roadmaps/archive/road-to-governance-cleanup.md`](../../agents/roadmaps/archive/road-to-governance-cleanup.md)
 § F2.
 
-## Related rule split — `chat-history` (post-1.15.0)
-
-The monolithic `rules/chat-history.md` was split into three sibling
-`always` rules in the post-1.15.0 optimization phase:
-
-- [`chat-history-ownership`](../../.agent-src/rules/chat-history-ownership.md) — sole owner of file I/O + first-turn handshake.
-- [`chat-history-cadence`](../../.agent-src/rules/chat-history-cadence.md) — when to persist (SessionStart / StepEnd / append boundaries).
-- [`chat-history-visibility`](../../.agent-src/rules/chat-history-visibility.md) — heartbeat marker contract for user-facing reporting.
-
-Decision record: [`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md).
-Cross-references in commands and contexts now point to
-`chat-history-ownership` as the entry point.
+## Related rule split — `chat-history` (post-1.15.0, superseded)
+
+> **Superseded · 2026-05-04** by
+> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> The three sibling rules (`chat-history-ownership`,
+> `chat-history-cadence`, `chat-history-visibility`) and the heartbeat
+> marker no longer exist. Persistence is now a pure platform-hook
+> contract — `session_start` auto-adopts foreign sessions silently;
+> the agent never reads or writes `agents/.agent-chat-history` cooperatively.
+> Manual recovery lever: `./agent-config chat-history:adopt`.
+
+For historical context: the monolithic `rules/chat-history.md` was
+first split into three sibling `always` rules in the post-1.15.0
+optimization phase, recorded in
+[`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md)
+(also marked superseded). The hook-only roadmap then collapsed all
+three rules into structural-only artefacts.
 
 ## Rollback
 

package/docs/skills-catalog.md

@@ -1,6 +1,6 @@
 # Skills Catalog
 
-All **128 skills** available in this package, in alphabetical order.
+All **129 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`
@@ -10,6 +10,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 |---|---|
 | [`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. |
+| [`ai-council`](../.agent-src/skills/ai-council/SKILL.md) | Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'. |
 | [`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. |
@@ -18,7 +19,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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) | Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic. |
+| [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) | Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic. |
 | [`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. |
@@ -49,7 +50,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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) | Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives. |
+| [`flux`](../.agent-src/skills/flux/SKILL.md) | Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives. |
 | [`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. |
@@ -72,7 +73,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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) | Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation. |
+| [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation. |
 | [`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. |
 | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |

package/llms.txt

@@ -8,6 +8,7 @@ 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.
+ai-council: Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'.
 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.
@@ -16,7 +17,7 @@ api-testing: Use when writing API endpoint tests — integration tests, contract
 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: Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic.
+blade-ui: Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic.
 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.
@@ -47,7 +48,7 @@ fe-design: Reference for frontend-design heuristics — component architecture,
 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: Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives.
+flux: Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives.
 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.
@@ -70,7 +71,7 @@ laravel-scheduling: Use when configuring Laravel task scheduling — cron expres
 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: Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation.
+livewire: Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation.
 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.
 md-language-check: Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.19.0",
+    "version": "1.21.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,