@event4u/agent-config 1.9.1

package/.agent-src/rules/language-and-tone.md

@@ -0,0 +1,104 @@
+---
+type: "always"
+description: "Language and tone — informal German Du, English code comments, .md files always English"
+alwaysApply: true
+source: package
+---
+
+# Language and Tone
+
+## Iron Law — mirror the user's language, ALWAYS
+
+```
+MIRROR THE LANGUAGE OF THE USER'S LAST MESSAGE. ALWAYS.
+BEFORE SENDING ANY REPLY, RUN THE PRE-SEND GATE BELOW.
+A REPLY IN THE WRONG LANGUAGE IS A RULE VIOLATION, NOT A SLIP.
+```
+
+**Overrides** conversation momentum, tool-output habits, convenience.
+First thing to check on every reply, last thing to check before sending.
+
+### Pre-send gate — MANDATORY before every reply
+
+Run silently **before** emitting any tokens:
+
+1. **Detect** — language of user's last message.
+   German signals: "ich", "Du", "nicht", "warum", "wie", "ist", umlauts.
+   English signals: "I", "you", "is", "the", "how".
+   Mixed → mirror the **dominant** language; tie → German wins (project default).
+2. **Check** — is drafted prose (not code, not file contents) in that language?
+3. **Rewrite** — if no, rewrite whole prose before sending. No exceptions, no
+   "just this sentence", no "the technical term is English anyway".
+4. **Confirm** — first sentence must be in target language. No English opener
+   before switching mid-paragraph.
+
+### The rule, spelled out
+
+- User writes German → **MUST** respond in German (informal "Du", never "Sie").
+  "Du" capitalized at sentence start, lowercase otherwise.
+- User writes English → respond in English.
+- User switches mid-conversation → switch on the **very next** reply. No
+  grace period, no "let me finish this thought in the old language".
+- Code blocks, command output, file contents, quoted tool output stay in
+  their native language. Only the **prose around them** mirrors the user.
+- "I've been answering in English for a while" is NOT a reason to keep going.
+  Trigger is the **latest user message**, not conversation momentum.
+- Numbered option lists (per `user-interaction`) mirror the user's language —
+  `.md` source is English, rendered reply is translated at runtime.
+
+### When the user calls out a language slip
+
+1. Acknowledge **once**, briefly, in the correct language ("Entschuldigung" /
+   "Sorry"). One sentence, no excuses.
+2. Switch immediately on the same reply.
+3. Do **not** re-explain the mistake in the wrong language.
+4. Do **not** promise "from now on" — just do it. Only behaviour changes
+   prove compliance.
+5. If user asks to harden the rule, harden it on this turn — don't defer.
+
+### 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.
+
+## Other language rules
+
+- All code comments must be in English.
+- All `.md` documentation files must be in English (see section below). If
+  an existing file is in German, translate it when you touch it.
+- Use two spaces after icons like ❌, ✅, ⚠️ in CLI output. One space is not enough. For other icons, one space is fine.
+- Avoid double and triple blank lines in code and output — one blank line is enough.
+- Every file MUST end with exactly one newline — no trailing blank lines.
+
+## `.md` files are ALWAYS English — no exceptions
+
+**Every** piece of text inside `.md` files in `.augment/` and `agents/` must be in English.
+This includes:
+
+- Headings, paragraphs, and bullet points
+- **Example option labels** (e.g., `> 1. Yes — start implementing`, NOT `> 1. Ja — mit der Umsetzung starten`)
+- **Example prompts and questions** (e.g., `"Found X unresolved comments."`, NOT `"X offene Kommentare gefunden."`)
+- **Template placeholders and sample output** (e.g., `Progress:`, NOT `Fortschritt:`)
+- **ASCII art labels** in formatted output blocks (e.g., `CHANGES:`, NOT `ÄNDERUNGEN:`)
+- **Table headers and content**
+
+The agent translates to the user's language **at runtime** when presenting options.
+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
+```

package/.agent-src/rules/laravel-translations.md

@@ -0,0 +1,48 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Laravel language files, translations, i18n, lang/de, lang/en, __() helper, localization, multilingual text"
+source: package
+---
+
+# Laravel Language Files
+
+## Key format — always inline (dot notation)
+
+Language lines **must always use flat dot-notation keys**. Never use nested arrays.
+
+**Correct** (`lang/en/report.php`):
+```php
+return [
+    'type.daily_report' => 'Daily Report',
+    'type.care_report'  => 'Care Report',
+];
+```
+
+**Wrong** — nested arrays are forbidden:
+```php
+return [
+    'type' => [
+        'daily_report' => 'Daily Report',
+        'care_report'  => 'Care Report',
+    ],
+];
+```
+
+## Both languages are mandatory
+
+Every language line **must exist in both** `lang/de/` and `lang/en/`.
+When you add a key to one file, immediately add the translated key to the other.
+
+Missing translations are a bug — the app ships to both German and English users.
+
+## Referencing language lines
+
+Use the `__()` helper with the dot-notation key:
+
+```php
+__('report.type.daily_report')
+__('email.report.created.subject', ['number' => $number])
+```
+
+Never hardcode user-visible strings in PHP — always use language files.

package/.agent-src/rules/markdown-safe-codeblocks.md

@@ -0,0 +1,18 @@
+---
+type: "auto"
+description: "Generating markdown output that contains code blocks — prevent broken nesting"
+alwaysApply: false
+source: package
+---
+
+# Markdown Safe Codeblocks
+
+When generating markdown with code blocks:
+
+- **NEVER** nest triple backticks inside triple backticks — this breaks rendering and copy/paste.
+- If content already contains triple backticks, use one of:
+  - Plain text blocks (indented by 4 spaces) — **preferred**
+  - `~~~` fences instead of backtick fences
+  - Four backticks (``````) as outer fence
+- Prefer stability over pretty formatting.
+- Always validate: no broken rendering, no prematurely closed blocks, entire content is selectable and copyable.

package/.agent-src/rules/minimal-safe-diff.md

@@ -0,0 +1,87 @@
+---
+type: "always"
+alwaysApply: true
+description: "Minimal safe diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code"
+source: package
+---
+
+# Minimal Safe Diff
+
+A diff is **safe** when every line in it is traceable to the stated task.
+Every other line is scope creep and must be removed or moved to a separate
+change.
+
+## The rule
+
+- The diff contains the **smallest** change that solves the stated problem.
+- Every modified file must be **directly required** by the task — not
+  "while I was in there".
+- Never reformat, rename, or restructure untouched code in the same diff.
+- Never change dependencies, versions, or tooling "because it was outdated".
+- Never consolidate or split unrelated code paths as a side effect.
+- Never delete code that *looks* dead without proof it is unreachable.
+
+## Before writing the diff
+
+Ask yourself, in order:
+
+1. **What is the minimum set of files that must change for the stated task?**
+   If your answer includes files with no causal link to the task, stop and
+   remove them.
+2. **What is the minimum number of lines per file?** If you are editing a
+   method, edit the method — not the surrounding class.
+3. **Is any of this a refactor?** If yes, it belongs in its own commit or
+   PR, clearly labeled as a refactor, with no behavior change.
+
+## When the task seems to require a larger change
+
+- A rename, restructure, or framework upgrade that crosses the minimal-diff
+  line is a **separate, explicit** task — ask the user before expanding.
+- A bug fix that exposes a broader design problem stays a bug fix. Log the
+  design problem as a follow-up (ticket, note, TODO) and ship the fix alone.
+- A new feature that tempts you to "clean up" the module first: resist.
+  Add the feature, commit it, then propose the cleanup as a separate change.
+
+## Auto-formatter or linter rewrites unrelated code
+
+Revert those hunks before staging. The diff you present is the diff you own.
+If project policy forbids partial formatting, split into two commits:
+*format only* · *behavior change*.
+
+## Red flags in your own diff — reject them
+
+Files the task never mentioned · import reordering, whitespace, or comments
+outside the edited region · "small improvements" to neighboring methods ·
+test-only mixed with behavior changes in one commit · renames outside the
+task scope · dependency bumps "because it was close to the cache".
+
+## When in doubt
+
+Ask. A minimal diff plus one follow-up is cheaper than a sprawling diff the
+reviewer has to untangle.
+
+## Break-glass exception
+
+This rule stays in force during production incidents. "Break-glass mode"
+narrows verification (see `verify-before-complete`) — it does **not**
+license drive-by edits.
+
+Allowed during break-glass:
+
+- The **smallest** change that stops the bleeding — one file, one
+  method, one guard — preferred over any refactor.
+- A fast revert to a known-good commit, even if it undoes unrelated
+  improvements shipped in the same PR.
+
+Not allowed, even in break-glass:
+
+- "While I'm in there" cleanups, reformatting, or dependency bumps.
+- Expanding the fix to neighboring modules without evidence they are
+  part of the incident.
+- Merging the hotfix with pending refactors from another branch.
+
+After the incident, open a **follow-up PR** for any scope that was
+intentionally deferred and reference the break-glass commit in its
+description.
+
+See also: `scope-control` · `downstream-changes` · `think-before-action` · `preservation-guard` · `verify-before-complete`.

package/.agent-src/rules/missing-tool-handling.md

@@ -0,0 +1,62 @@
+---
+type: auto
+source: package
+description: "When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently"
+---
+
+# Missing Tool Handling
+
+When a CLI tool is needed and **not installed** (`command not found`,
+`which X` empty), **STOP and ask** before working around it or installing it.
+
+## The rule
+
+- **Never install silently.** Installing changes the user's system —
+  requires explicit permission (`scope-control`).
+- **Never silently work around** a missing tool with a brittle substitute
+  (awk for YAML, `grep` for JSON, string splicing) when a proper tool is
+  the standard answer. The workaround hides the dependency.
+- **Ask with numbered options** (`user-interaction`). State the tool, why
+  it fits, the install command, and the workaround cost.
+
+## When it applies
+
+- Shell returns `command not found` for a tool the task genuinely needs
+  (yq, jq, rtk, gh, docker, mkcert, terraform, …).
+- A skill or spike needs the idiomatic tool but it's absent locally.
+- You're about to substitute a verbose script for a single tool call
+  because the tool isn't there.
+
+## When it does NOT apply
+
+- Nice-to-have — clean substitute already present (e.g. `jq` available →
+  no `yq` needed just for JSON).
+- Tool is forbidden by project policy (check `scope-control` and
+  tool-allowlists first).
+- Missing library dependency → use `composer`, `npm`, `pip` per package
+  rules, still with explicit permission.
+
+## How to ask
+
+```
+> `yq` is not installed. It's the cleanest way to parse the ticket YAML
+> in the Bash prototype — the alternative is shelling out to python3,
+> which adds ~50ms to every run.
+>
+> 1. Install via `brew install yq` (recommended — one-time, stays on PATH)
+> 2. Use the python3 fallback — slower but no install needed
+> 3. Drop YAML — convert fixtures to JSON, use `jq` only
+> 4. Skip this path — I propose a different approach
+```
+
+After the user picks: if **install**, wait for confirmation or run the
+documented command only if explicitly authorised this turn. If
+**workaround**, record the decision in the artefact (comment or ADR).
+
+## Capture the learning
+
+If the same tool keeps missing across tasks, flag it in the project's
+setup docs or `.agent-settings.yml` prerequisites.
+
+See also: `scope-control` · `ask-when-uncertain` · `user-interaction` ·
+`tool-safety`.

package/.agent-src/rules/model-recommendation.md

@@ -0,0 +1,70 @@
+---
+type: "always"
+description: "Model recommendation — detect task complexity, suggest optimal model (Opus/Sonnet/GPT), check on task changes and command invocations"
+alwaysApply: true
+source: package
+---
+
+# Model Recommendation
+
+Detect the current model from your system prompt identity (e.g., "Claude Opus" → `opus`,
+"Claude Sonnet" → `sonnet`, "GPT" → `gpt`, "Gemini" → `gemini`).
+
+If the detected model is `gemini`, immediately trigger the Gemini warning (see below).
+
+## When to act
+
+**BEFORE starting any work**, classify the task the user is asking for:
+
+- **opus**: refactoring, architecture, complex debugging, code review, multi-file changes
+- **sonnet**: daily coding, bug fixes, tests, simple features, quality checks, PRs, commits, config
+- **gpt**: complex agent flows, automations, research
+
+**This check is MANDATORY** — not optional, not "nice to have". It runs:
+- On the **first user message** of a conversation
+- On **every clear topic/task change** (e.g., from refactoring to "create PR")
+- **When a command is invoked** (e.g., `/create-pr` → sonnet task)
+
+**⚠️ COMMAND INVOCATIONS ARE TASK CHANGES.** When the user invokes a command (e.g., `/create-pr`,
+`/commit`, `/fix-ci`), ALWAYS re-evaluate the model before executing. Commands like `/create-pr`,
+`/commit`, `/fix-pr-comments` are sonnet tasks — even if the previous task was opus-level.
+This is the most commonly missed check. Do NOT skip it.
+
+**Priority over commands rule**: This check runs BEFORE the `slash-commands` rule. If a model switch
+is recommended, show the suggestion first. Only after the user responds, execute the command.
+
+**If ambiguous** (could be opus or sonnet): default to **sonnet** — cheaper, and the user can escalate.
+
+If the recommended model ≠ detected model, suggest switching **before doing any work**:
+
+```
+> 💡 This looks like {task type} — best suited for **{recommended model}**.
+> You're currently on **{detected model}**.
+>
+> 1. I've switched to {recommended} — continue
+> 2. Stay on {detected model}
+```
+
+**⛔ STOP AND WAIT.** After showing this suggestion, your response ENDS.
+Do NOT read files, create tasks, start coding, or do anything else in the same response.
+The ONLY content after the numbered options is the end of your message.
+Wait for the user to pick 1 or 2 before proceeding.
+
+→ Full mapping and heuristics: `.augment/contexts/model-recommendations.md`
+
+## Switch confirmation
+
+- If user picks **1**: accept and continue. No follow-up question.
+- If user picks **2**: accept. Don't ask again until the task type changes.
+- **Never ask more than once per task** unless the task type changes significantly.
+
+## Downgrade after Opus
+
+After completing an opus-level phase (architecture done, root cause found, refactoring plan ready),
+suggest switching back to sonnet for implementation. Same numbered options.
+
+## Gemini warning
+
+If detected model is `gemini`: warn that Gemini is **not recommended** for this project.
+Suggest switching to the best model for the current task (opus/sonnet/gpt).
+Show the same numbered options as above. Repeat once if dismissed — then accept.

package/.agent-src/rules/package-ci-checks.md

@@ -0,0 +1,80 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first"
+source: package
+---
+
+# Package CI Checks
+
+Before **any** push/PR in agent-config: run ALL CI checks locally.
+
+```
+NEVER push without running ALL CI checks locally first.
+```
+
+## Required checks
+
+### 1. Sync
+
+```bash
+task sync-check            # .agent-src/ matches .agent-src.uncompressed/
+task sync-check-hashes     # compression hashes are clean
+```
+
+### 2. Consistency
+
+```bash
+python3 scripts/check_compression.py   # compressed variants are valid
+python3 scripts/check_references.py     # no broken cross-references
+python3 scripts/check_portability.py    # no project-specific references in shared files
+```
+
+### 3. Linter (0 FAIL required)
+
+```bash
+python3 scripts/skill_linter.py --all   # 0 FAIL required
+```
+
+### 4. Tests
+
+```bash
+python3 -m pytest tests/ --tb=short     # all tests must pass
+```
+
+### 5. README
+
+```bash
+python3 scripts/readme_linter.py README.md --root .
+```
+
+## Quick one-liner
+
+```bash
+task sync-check && task sync-check-hashes && \
+python3 scripts/check_compression.py && \
+python3 scripts/check_references.py && \
+python3 scripts/check_portability.py && \
+python3 scripts/skill_linter.py --all && \
+python3 -m pytest tests/ --tb=short && \
+python3 scripts/readme_linter.py README.md --root .
+```
+
+## After editing skills/rules in .agent-src.uncompressed/
+
+1. Edit uncompressed file
+2. Edit compressed file in `.agent-src/` to match
+3. `task sync-mark-done -- {relative-path}` — update hash
+4. `task sync-check-hashes` — verify
+
+**Skip step 3 → CI WILL fail.**
+
+## After editing scripts/compress.py
+
+Run `python3 -m pytest tests/test_compress.py -v` **immediately** — don't wait.
+
+## Do NOT
+
+- Push "to see if CI passes" — wastes pipeline minutes
+- Skip hash checks for "small changes"
+- Assume tests pass because linter passes

package/.agent-src/rules/php-coding.md

@@ -0,0 +1,63 @@
+---
+type: "auto"
+description: "Writing or reviewing PHP code — strict types, naming, comparisons, early returns, Eloquent conventions"
+alwaysApply: false
+source: package
+---
+
+# 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/.agent-src/rules/preservation-guard.md

@@ -0,0 +1,29 @@
+---
+type: "auto"
+alwaysApply: false
+description: "When merging, refactoring, compressing, or restructuring skills, rules, commands, or guidelines — prevent quality loss"
+source: package
+---
+
+# Preservation Guard
+
+Transformations (merge, refactor, compress, split) must produce output **at least as strong** as input.
+
+## Checklist — verify before completing
+
+- [ ] Strongest validation step preserved
+- [ ] Strongest example preserved
+- [ ] Strongest anti-pattern / "Do NOT" preserved
+- [ ] Essential decision hints (if/when/unless) preserved
+- [ ] Required sections preserved
+- [ ] Single clear responsibility preserved
+- [ ] Strong language ("MUST"/"NEVER") not weakened
+
+## Reject if
+
+- Validation, example, or anti-pattern removed without replacement
+- Decision logic weakened
+- Scope broadened by merging unrelated concerns
+- Strong language downgraded
+
+→ Skills: `skill-management`, `skill-reviewer` · Command: `/compress` · Linter: `check_compression_quality()`