@event4u/agent-config 1.15.0 → 1.16.0

package/docs/github-topics.md

@@ -13,8 +13,12 @@ ai-coding
 agent-skills
 agent-rules
 governance
+orchestration
 laravel
 php
+nextjs
+nodejs
+typescript
 devcontainer
 augment-agent
 claude-code
@@ -30,8 +34,9 @@ agentskills-standard
 | `agent-skills` | Aligns with the [Agent Skills](https://agentskills.io) community spec |
 | `agent-rules` | Complementary — rules govern behavior, skills provide expertise |
 | `governance` | Differentiates from prompt collections |
-| `laravel` | Primary domain — Laravel projects are the main audience |
-| `php` | Broader PHP audience |
+| `orchestration` | Captures the core identity — a deterministic orchestration contract / state machine |
+| `laravel`, `php` | Reference-implementation stack — currently the deepest skill density |
+| `nextjs`, `nodejs`, `typescript` | Parallel skill sets for JS/TS surfaces (project-analysis, UI directives) |
 | `devcontainer` | One of our 4 core concerns |
 | `augment-agent`, `claude-code`, `copilot` | Tool-specific discovery |
 | `agentskills-standard` | SKILL.md format is compatible with the agentskills.io spec |
@@ -53,8 +58,12 @@ gh repo edit event4u-app/agent-config \
   --add-topic agent-skills \
   --add-topic agent-rules \
   --add-topic governance \
+  --add-topic orchestration \
   --add-topic laravel \
   --add-topic php \
+  --add-topic nextjs \
+  --add-topic nodejs \
+  --add-topic typescript \
   --add-topic devcontainer \
   --add-topic augment-agent \
   --add-topic claude-code \
@@ -69,7 +78,7 @@ curl -X PUT \
   -H "Authorization: Bearer $GITHUB_TOKEN" \
   -H "Accept: application/vnd.github+json" \
   https://api.github.com/repos/event4u-app/agent-config/topics \
-  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","laravel","php","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
+  -d '{"names":["ai-coding","agent-skills","agent-rules","governance","orchestration","laravel","php","nextjs","nodejs","typescript","devcontainer","augment-agent","claude-code","copilot","agentskills-standard"]}'
 ```
 
 ## Verify

package/docs/guidelines/agent-infra/language-and-tone-examples.md

@@ -0,0 +1,79 @@
+# language-and-tone — examples and failure modes
+
+> Reference companion to [`.agent-src/rules/language-and-tone.md`](../../.agent-src/rules/language-and-tone.md).
+> Pulled out so the always-active rule stays under its character budget.
+> Linked from the rule via the **Examples** section; agents do not load this file
+> automatically, only when they want concrete demonstrations or are debugging a
+> language-mirroring drift.
+
+## Failure modes to watch for
+
+- Drafting reply in English first, then "translating the intro" → English
+  phrasing with German words. Draft in target language from the first token.
+- Copy-pasting English option labels from `.md` sources without translating.
+- Mixing languages inside a table or bullet list because "the technical term
+  is English" — surrounding prose must still mirror. Keep proper nouns and
+  code identifiers as-is; translate everything else.
+- Assuming English because "the codebase is English" — codebase language ≠
+  conversation language.
+- Mirroring the **open file** the IDE reports — open files are background
+  context, not chat messages.
+- Mirroring the **roadmap or ticket** being executed — artefacts are English
+  by `.md` rule; chat language is whatever the user wrote.
+
+## `.md` example labels — wrong vs correct
+
+The agent translates option labels to the user's language **at runtime**.
+The `.md` source files are the English blueprint — they define WHAT to say,
+not in which language.
+
+**Wrong** (German in `.md`):
+
+```
+> 1. Interaktiv — bei jedem Kommentar nachfragen
+> 2. Automatisch — alle selbstständig abarbeiten
+```
+
+**Correct** (English in `.md`):
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+Same rule applies to: example prompts and questions, template placeholders,
+ASCII art labels in formatted output blocks, table headers and content.
+
+## Quoted user-input examples — same rule, with one labeled exception
+
+Common drift pattern: a rule documents trigger phrases the agent should
+recognize and writes them as quoted German examples inside English prose.
+**Not allowed**, even when demonstrative.
+
+**Wrong** (DE quote embedded in EN prose):
+
+```md
+Single-decision delegation ("für diesen Schritt entscheide du") →
+handle that step autonomously.
+
+A standing "arbeite selbstständig" never lifts the floor.
+```
+
+**Correct** — two ways:
+
+1. **Translate to English.** Trigger recognition is semantic; the agent
+   matches intent across languages regardless of the example.
+   `("you decide for this step")` works as well as the German.
+2. **Use a labeled `DE: … · EN: …` anchor list** when the multilingual
+   nature of recognition is the point:
+
+   ```md
+   - DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
+   - EN: "work autonomously" · "don't ask" · "just do it"
+   ```
+
+The labeled-anchor block is the **only** allowed location for German prose
+in an English `.md` file. Body text, example sentences, prompt templates,
+agent-rendered strings, and failure modes must be English. Reference
+established phrases abstractly later (e.g. "a standing autonomy directive")
+and link back to the anchor block.

package/{.agent-src → docs}/guidelines/docs/readme-size-and-splitting.md

@@ -2,11 +2,12 @@
 
 ## Purpose
 
-Keep READMEs scannable as repositories grow. A README is an **entry
-point**, not a reference manual. Once it stops working as entry point,
-split — don't scroll.
+Keep READMEs scannable and useful as repositories grow. A README is an
+**entry point**, not a reference manual. Once it stops working as an entry
+point, split — don't scroll.
 
-Referenced by `readme-writing`, `readme-writing-package`, `readme-reviewer`.
+This guideline is referenced by the `readme-writing`, `readme-writing-package`,
+and `readme-reviewer` skills.
 
 ---
 
@@ -41,8 +42,8 @@ Hard triggers — split immediately:
 Soft triggers — review and probably split:
 
 - A section needs its own Table of Contents
-- Reader scrolls past three screens to reach "how do I use it"
-- More than one code block per section explaining variations of the same
+- A reader has to scroll past three screens to reach "how do I use it"
+- More than one code block per section, explaining variations of the same
   thing (indicates reference material, not onboarding)
 
 ---
@@ -64,8 +65,8 @@ README stays < 200 lines. Each `/docs/` file is a self-contained chapter.
 
 ### Strategy 2 — Deep-link tables for multi-platform repos
 
-Supporting many platforms or tool integrations: single table with deep
-links beats inline blocks:
+When supporting many platforms or tool integrations, a single table with
+deep links beats inline blocks:
 
 ```markdown
 | Tool    | Install                | Docs                    |
@@ -78,8 +79,8 @@ Pattern: 1 row per platform, actual how-to in the linked doc.
 
 ### Strategy 3 — Collapsible sections (`<details>`)
 
-Content occasionally needed but crowding the scan path — long install
-options, platform-specific quirks, troubleshooting trees:
+For content that is occasionally needed but crowds the scan path — long
+install options, platform-specific quirks, troubleshooting trees:
 
 ```markdown
 <details>
@@ -90,8 +91,8 @@ Content here — full detail, not shown by default.
 </details>
 ```
 
-Use sparingly. Collapsed content is still in the file; it defers visual
-cost only. Not a substitute for true splitting when content > 30 lines.
+Use sparingly. Collapsed content is still in the file; it just defers the
+visual cost. Not a substitute for true splitting when content is > 30 lines.
 
 ---
 
@@ -104,15 +105,15 @@ Add a ToC when:
 - Reader would need to scroll to find a known section
 
 Place the ToC **after** the one-line summary and **before** the first
-substantive section (usually install or quickstart). Don't add a ToC to
-small READMEs — becomes visual noise.
+substantive section (usually install or quickstart). Do not add a ToC to
+small READMEs — it becomes visual noise.
 
 ---
 
 ## Multi-audience repos
 
 A single README cannot serve "consumers of a package" and "contributors
-to a package" equally. Choose one primary audience for the README,
+to a package" equally well. Choose one primary audience for the README,
 deep-link the other:
 
 - **Package repo** → consumers primary; contributors go to
@@ -120,8 +121,8 @@ deep-link the other:
 - **Application repo** → contributors/team primary; end users (if any)
   go to `docs/user-guide.md`
 
-README must declare its audience within the first screen. Readers in the
-other audience must find their link within the first screen too.
+The README must declare its audience within the first screen. Readers
+in the other audience must find their link within the first screen too.
 
 ---
 
@@ -129,13 +130,13 @@ other audience must find their link within the first screen too.
 
 - **Splitting by accident** — moving content out "because the README is long"
   without a navigation story. Readers get lost.
-- **Splitting and duplicating** — same content in README and `/docs/`.
-  They drift apart. Pick one home.
-- **Deep-link-only README** — README that is just a table of contents
-  linking out. Reader arriving cold must still learn what/why/how-install
+- **Splitting and duplicating** — keeping the same content in README and
+  `/docs/`. They drift apart. Pick one home.
+- **Deep-link-only README** — a README that is just a table of contents
+  linking out. A reader arriving cold must still learn what/why/how-install
   without clicking.
-- **Premature splitting** — `docs/` scaffolding for a 50-line README.
-  Overhead not worth it; come back at 150 lines.
+- **Premature splitting** — creating `docs/` scaffolding for a 50-line
+  README. The overhead is not worth it; come back at 150 lines.
 - **Hiding critical content in `<details>`** — install, first example, and
   requirements are **never** collapsed.
 
@@ -144,10 +145,10 @@ other audience must find their link within the first screen too.
 ## Validation checklist
 
 - [ ] First screen answers what / why / install
-- [ ] Size below "overloaded" threshold, or splitting is in place
+- [ ] Size is below the "overloaded" threshold, or splitting is in place
 - [ ] ToC present if > 150 lines or > 6 top-level sections
 - [ ] No duplication between README and `/docs/`
 - [ ] `<details>` used only for secondary, bulky content
 - [ ] Multi-platform install uses a table, not 10 sequential install blocks
 - [ ] Each `/docs/` file is self-contained and linked from README
-- [ ] Audience explicit; other audience has a visible deep-link
+- [ ] Audience is explicit; the other audience has a visible deep-link

package/docs/guidelines/php/git.md

@@ -0,0 +1,164 @@
+# Git & Version Control Guidelines
+
+> Project-specific Git conventions. Branch naming, commit messages, PR workflow.
+
+**Related Skills:** `git-workflow`, `conventional-commits-writing`
+**Related Rules:** `commit-conventions.md`
+
+## Branch Naming
+
+```
+{type}/{ticket-id}/{short-description}
+```
+
+| Type | When |
+|---|---|
+| `feat/` | New feature |
+| `fix/` | Bug fix |
+| `hotfix/` | Urgent production fix |
+| `chore/` | Maintenance, refactoring, tooling |
+| `docs/` | Documentation changes |
+| `test/` | Test additions/changes |
+
+### Examples
+
+```
+feat/DEV-1234/user-notification-preferences
+fix/DEV-5678/null-pointer-in-import
+chore/refactor-agent-setup
+hotfix/DEV-999/critical-payment-bug
+```
+
+### Rules
+
+- Always include the Jira ticket ID when one exists
+- Use kebab-case for the description part
+- Keep branch names short but descriptive
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+See `commit-conventions` rule for the base format and type table.
+
+### Type selection rules
+
+**`feat`** — a new capability is added; user or system can do something new.
+
+**`fix`** — existing behavior was wrong; bug, regression, or broken edge case corrected.
+
+**`refactor`** — structure changes, readability/maintainability improves, behavior unchanged.
+Do NOT use `refactor` if behavior changes — use `feat` or `fix` instead.
+
+**`docs`** — only documentation changes, no runtime or behavior change.
+
+**`test`** — only tests added/updated, no production behavior changes.
+
+**`ci`** — GitHub Actions, pipelines, CI checks, automation workflows, release jobs.
+
+**`chore`** — maintenance, repo housekeeping, dependency bumps, non-functional cleanup
+that is not better classified as `build`, `ci`, or `docs`.
+
+**`perf`** — measurable performance improvement.
+
+**`build`** — build tooling, packaging, Docker changes.
+
+**`style`** — formatting only, no logic change (e.g. ECS/Rector auto-fixes).
+
+### Scope guidance
+
+Use a scope when it adds clarity. Good scopes:
+
+- Jira ticket ID: `DEV-1234`
+- Module/area: `api`, `auth`, `skills`, `rules`, `ci`, `frontend`, `linter`
+
+Do not add a scope if it adds no value. `fix(core): fix typo` → just `fix: fix typo`.
+
+### Description rules
+
+- Describe **intent**, not implementation detail
+- Describe **what changed**, not every low-level step
+- Avoid generic wording: `update stuff`, `fix issue`, `changes`
+
+Good: `fix(routes): preserve middleware order for api endpoints`
+Bad: `fix: fix things`
+
+### Breaking changes
+
+Use `!` after type/scope or `BREAKING CHANGE:` in footer:
+
+```
+feat(api)!: rename invoice status values
+refactor(auth)!: remove legacy session flow
+```
+
+### Commit splitting
+
+If a change contains multiple unrelated concerns, split into multiple commits.
+
+Bad: `refactor: cleanup skills and fix ci and update docs`
+
+Better:
+```
+refactor(skills): remove duplicate routing helpers
+ci(lint): add skill-lint workflow
+docs(readme): document new lint tasks
+```
+
+### Squash merge titles
+
+- Use Conventional Commit format
+- Summarize the **net effect** of the PR
+- Do not copy vague branch names
+- Do not include issue noise if it hurts readability
+
+### Examples by area
+
+```bash
+# Features
+feat(DEV-2133): send email to customer when product is shipped
+
+# Bug fixes
+fix(import): handle null values in equipment JSON
+
+# Refactoring
+refactor: extract user sync logic into dedicated service
+
+# Skills / Rules / Agent config
+refactor(skills): merge duplicate analysis skills
+feat(rules): add analysis routing quality gate
+fix(skills): restore concrete validation in skill reviewer
+
+# CI / Tooling
+ci(lint): add skill linter workflow
+feat(linter): detect pointer-only skills
+
+# Docs
+docs(roadmap): add phase 3 implementation plan
+docs(readme): clarify source-of-truth workflow
+```
+
+### Decision checklist
+
+Before writing the commit message:
+
+1. Did behavior change? → `feat` or `fix`
+2. Was it only structure/cleanup? → `refactor`
+3. Was it only docs, tests, or CI? → `docs`, `test`, `ci`
+4. Is the scope useful or just noise?
+5. Is this actually multiple commits hiding in one?
+
+### Anti-patterns
+
+- `update stuff` / `fix bug` / `changes` / `refactor everything`
+- Using `chore` for meaningful behavior changes
+- Using `refactor` for bug fixes
+- Using one commit for multiple unrelated concerns
+- Vague squash merge titles that don't describe the net effect
+
+## Pull Requests
+
+- PR title follows commit message format: `feat(DEV-1234): short description`
+- Fill in the PR template (checklist, description, testing notes)
+- Link the Jira ticket in the PR description
+- Ensure all quality gates pass before requesting review
+

package/docs/migrations/commands-1.15.0.md

@@ -82,7 +82,7 @@ A second wave of collapses (`chat-history`, `agents`, `memory`,
 `roadmap`, `module`, `tests`, `context`, `override`, `copilot-agents`,
 `commit`, `judge`, `create-pr`) is scheduled after 1.15.0 ships and
 the deprecation cycle for Phase 1 closes. Tracked in
-[`agents/roadmaps/road-to-governance-cleanup.md`](../../agents/roadmaps/road-to-governance-cleanup.md)
+[`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)

package/docs/showcase.md

@@ -192,10 +192,15 @@ criteria, assumptions, confidence band) before the engine plans.
 
 ## More
 
-The five examples above cover the load-bearing iron laws. The full
-rule set lives in [`.agent-src/rules/`](../.agent-src/rules/) (browse
-the `description:` line in each file's frontmatter to see when it
-auto-triggers); the full skill catalog is in
+The five examples above cover the load-bearing iron laws. For the
+**cycle-by-cycle traces** of the engine commands (`/implement-ticket`,
+`/work`, the UI track, and the blocked path), see
+[`end-to-end-walkthroughs.md`](end-to-end-walkthroughs.md) — each
+walkthrough is anchored to a checked-in golden transcript.
+
+The full rule set lives in [`.agent-src/rules/`](../.agent-src/rules/)
+(browse the `description:` line in each file's frontmatter to see
+when it auto-triggers); the full skill catalog is in
 [`docs/skills-catalog.md`](skills-catalog.md).
 
 **Suggesting an example?** Open a PR adding a new section here. Same

package/docs/skills-catalog.md

@@ -1,6 +1,6 @@
 # Skills Catalog
 
-All **122 skills** available in this package, in alphabetical order.
+All **128 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`
@@ -18,7 +18,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) | 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. |
+| [`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. |
 | [`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. |
@@ -43,15 +43,17 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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. |
+| [`"estimate-ticket"`](../.agent-src/skills/"estimate-ticket"/SKILL.md) | Estimate a Jira/Linear ticket — 'estimate PROJ-123', 'wie groß ist das?', 'should we split this?' — size + risk + split + uncertainty, sibling of /refine-ticket, close-prompt. |
+| [`existing-ui-audit`](../.agent-src/skills/existing-ui-audit/SKILL.md) | Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set. |
+| [`fe-design`](../.agent-src/skills/fe-design/SKILL.md) | Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py. |
 | [`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. |
+| [`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. |
 | [`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'. |
+| [`guideline-writing`](../.agent-src/skills/guideline-writing/SKILL.md) | Use when creating or editing a guideline in docs/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'. |
@@ -70,9 +72,10 @@ 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) | Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates. |
+| [`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. |
 | [`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. |
 | [`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. |
@@ -97,10 +100,13 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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. |
+| [`react-shadcn-ui`](../.agent-src/skills/react-shadcn-ui/SKILL.md) | Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack. |
 | [`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'. |
+| [`"refine-prompt"`](../.agent-src/skills/"refine-prompt"/SKILL.md) | Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'. |
+| [`"refine-ticket"`](../.agent-src/skills/"refine-ticket"/SKILL.md) | Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt. |
 | [`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. |
@@ -115,7 +121,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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. |
+| [`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) — models 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. |
@@ -128,7 +134,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`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. |
+| [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/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'. |
 
 ---

package/docs/ui-track-mental-model.md

@@ -44,7 +44,7 @@ A misclassified `ui-trivial` that grows during edit must reclassify
 
 1. **Skip the audit.** No new component, screen, or partial without
    `state.ui_audit` populated (or `greenfield_decision` recorded).
-   Defense-in-depth: dispatcher refuses *and* `ui-audit-before-build`
+   Defense-in-depth: dispatcher refuses *and* `ui-audit-gate`
    refuses, even when the engine is not in the loop.
 2. **Render the UI.** The engine never opens a browser, never takes a
    screenshot, never runs axe. Rendering and a11y scanning happen
@@ -118,4 +118,4 @@ stack ships as a new skill bundle and a recipe — see
 - [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) — *why* this shape.
 - [`ui-track-flow.md`](contracts/ui-track-flow.md) — slot-by-slot contract.
 - [`ui-stack-extension.md`](contracts/ui-stack-extension.md) — adding a stack.
-- [`ui-audit-before-build`](../.agent-src/rules/ui-audit-before-build.md) — the always-on rule that mirrors the dispatcher gate.
+- [`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) — the always-on rule that mirrors the dispatcher gate.