@event4u/agent-config 1.12.0 → 1.14.0

package/README.md

@@ -5,7 +5,7 @@ Teach your AI agents Laravel, PHP, testing, Git workflows, and **120+ more skill
 > Your agent learns to write Laravel code, run tests, create PRs, fix CI — and follows your team's coding standards while doing it.
 
 <p align="center">
-  <strong>124 Skills</strong> · <strong>46 Rules</strong> · <strong>73 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>128 Skills</strong> · <strong>53 Rules</strong> · <strong>77 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -69,7 +69,29 @@ Install directly in your agent for global, cross-project use:
 2. `"Add caching to this"` → watch: agent asks instead of guessing
 3. `"Implement this feature"` → watch: agent respects your codebase
 
-→ [Full getting started guide](docs/getting-started.md)
+→ [Full getting started guide](docs/getting-started.md) ·
+[More examples & expected behavior](docs/showcase.md)
+
+### Optional: persistent agent memory
+
+`agent-config` integrates with [`@event4u/agent-memory`](https://www.npmjs.com/package/@event4u/agent-memory)
+— an MCP-based memory backend that gives agents persistent learnings
+across sessions. It is **strictly optional**:
+
+- Not a required dependency (declared as `suggest` in Composer and as an
+  optional peer in npm). `agent-config` itself never imports it.
+- Without it, agent skills fall back to **file-based memory** under
+  `agents/memory/` and continue to work normally.
+- Recommended for teams that want learnings to survive across machines,
+  branches, and chat sessions.
+
+Install in the same project (dev-only):
+
+```bash
+npm install --save-dev @event4u/agent-memory
+```
+
+→ [Memory contract & retrieval API](agents/contexts/agent-memory-contract.md)
 
 ---
 
@@ -109,6 +131,67 @@ so you decide — never a silent guess. Persona comes from
 → [Command reference](.agent-src/commands/implement-ticket.md) ·
   [Flow contract](agents/contexts/implement-ticket-flow.md)
 
+### Sibling entrypoint: `/work` (free-form prompt)
+
+Same engine, different envelope. Use `/work` when you have a goal
+but no ticket yet:
+
+```
+/work add a CSV export endpoint to the audit-log controller
+```
+
+The first pass scores the prompt on five dimensions
+(`goal_clarity`, `scope_boundary`, `ac_evidence`, `stack_data`,
+`reversibility`) and routes on the resulting band:
+
+| Band | Score | Engine action |
+|---|---|---|
+| **high** | `≥ 0.8` | Silent proceed — reconstructed AC + assumptions land in the delivery report |
+| **medium** | `0.5–0.79` | Halts with assumptions report; you confirm or edit before plan |
+| **low** | `< 0.5` | Halts with **one** clarifying question on the weakest dimension |
+
+After the band gate releases, the rest of the flow is identical
+to `/implement-ticket`. UI-shaped prompts are routed through the
+**product UI track** — see below.
+
+→ [Command reference](.agent-src/commands/work.md) ·
+  [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md) ·
+  [ADR](agents/contexts/adr-prompt-driven-execution.md)
+
+**Pick which one:** ticket id or pasted ticket payload → `/implement-ticket`.
+Free-form goal, no ticket → `/work`. The two share `.work-state.json`
+and refuse to switch envelopes mid-flight.
+
+### Product UI track
+
+UI-shaped work (build a screen, improve a component, fix microcopy)
+switches the engine to one of three directive sets:
+
+| `directive_set` | When | Flow |
+|---|---|---|
+| `ui` | Non-trivial UI surface | `audit → design → apply → review → polish → report` |
+| `ui-trivial` | Bounded edit (≤ 1 file, ≤ 5 changed lines) | `apply → test → report` |
+| `mixed` | Backend + UI | `contract → ui → stitch` |
+
+Four load-bearing properties: (1) **existing-UI audit is a hard gate** —
+no `apply` without audit, enforced at dispatcher AND
+[`ui-audit-before-build`](.agent-src/rules/ui-audit-before-build.md) rule;
+(2) **design brief is locked microcopy** — placeholders (`<placeholder>`,
+`Lorem`, `TODO:`) rejected at both ends; (3) **polish has a 2-round
+ceiling**, then halts ship-as-is / abort / hand-off; (4) **a11y precedence**
+— unresolved axe-core / pa11y violations must be fixed or explicitly
+accepted before ship, regardless of round counter (one-shot extension
+allowed). The engine never renders UI itself: rendering happens
+out-of-process, the engine consumes a `preview_envelope` (status /
+screenshots / findings) via a defined contract. Stack detection routes
+(`composer.json` + `package.json`) to `blade-livewire-flux` /
+`react-shadcn` / `vue` / `plain`; trivial path reclassifies loudly when
+preconditions fail. Halt budget on the happy path is 2.
+
+→ [Flow contract](agents/contexts/ui-track-flow.md) ·
+  [ADR](agents/contexts/adr-product-ui-track.md) ·
+  [Stack-extension recipe](agents/contexts/ui-stack-extension.md)
+
 ---
 
 ## What your agent is asked to do
@@ -238,7 +321,7 @@ can prioritize the right skills for extraction.
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 73 commands](.agent-src/commands/)
+→ [Browse all 77 commands](.agent-src/commands/)
 
 ---
 
@@ -263,7 +346,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 124 skills + 73 native commands). Cursor, Cline, Windsurf,
+> package (rules + 128 skills + 77 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.
@@ -282,6 +365,23 @@ Skills use a `SKILL.md` format with YAML frontmatter that is compatible with
 the [Agent Skills](https://agentskills.io) community spec and with Claude
 Code's Agent Skills specification.
 
+### Cloud / Hosted-agent surfaces (paste-in or upload)
+
+For platforms where the package's scripts cannot run, the package
+builds artefacts you upload or paste into the platform's own surface.
+
+| Surface | Output | How to install |
+|---|---|---|
+| **Linear AI** (Codegen, Charlie, …) | `dist/linear/{workspace,team,personal}.md` | [Install →](docs/installation.md#linear-ai-codegen-charlie-) |
+| **Claude.ai Web Skills** | `dist/cloud/<skill>.zip` | [Install →](docs/installation.md#claudeai-web-skills-ui) |
+
+The Linear digest is split into three layers — workspace (universal
+coding posture), team (framework-specific), personal (empty stub). See
+[`agents/contexts/linear-ai-three-layers.md`](agents/contexts/linear-ai-three-layers.md)
+for the rationale and
+[`agents/contexts/linear-ai-rules-inclusion.md`](agents/contexts/linear-ai-rules-inclusion.md)
+for the per-rule routing.
+
 ---
 
 ## Core Principles
@@ -310,6 +410,48 @@ Uninstalling: see
 there is no dedicated uninstall command; removal is a documented manual
 step (package manager + `rm -rf` of generated dirs).
 
+### Maintainer telemetry (opt-in, default-off)
+
+A local-only artefact-engagement log can be enabled by maintainers to see
+which skills, rules, commands, and guidelines the agent actually consults
+and applies during a `/implement-ticket` or `/work` run. The log is a
+JSONL file under the project root; nothing is uploaded, nothing is shared
+across projects. Default is off; consumers see no prompts.
+
+```yaml
+# .agent-settings.yml — opt in only when you want measurement
+telemetry:
+  artifact_engagement:
+    enabled: true
+```
+
+Reports: `./agent-config telemetry:report`. Full contract,
+privacy/redaction floor, and quartile semantics:
+[`agents/contexts/artifact-engagement-flow.md`](agents/contexts/artifact-engagement-flow.md).
+
+### Context-aware command suggestion
+
+When a user prompt matches a command's purpose ("setze ticket ABC-123 um"
+→ `/implement-ticket`), the agent surfaces matches as a numbered-options
+block with an always-present "run the prompt as-is" escape. **Nothing
+auto-executes** — the user picks every time. Three opt-out paths:
+
+```yaml
+# .agent-settings.yml
+commands:
+  suggestion:
+    enabled: true            # global on/off
+    blocklist: []            # specific commands never suggested
+    confidence_floor: 0.6    # tunable per command in frontmatter
+```
+
+Per-conversation: `/command-suggestion-off` disables the layer until
+the user re-enables or the chat ends. Full scoring contract and
+hardening list:
+[`agents/contexts/adr-command-suggestion.md`](agents/contexts/adr-command-suggestion.md)
+and
+[`agents/contexts/command-suggestion-flow.md`](agents/contexts/command-suggestion-flow.md).
+
 ---
 
 ## Development

package/composer.json

@@ -6,6 +6,9 @@
     "require": {
         "php": ">=8.0"
     },
+    "suggest": {
+        "@event4u/agent-memory": "Optional MCP-based memory backend (npm: @event4u/agent-memory ^1.1.0). Adds persistent agent learnings across sessions. Install with `npm install --save-dev @event4u/agent-memory` if your team wants the memory layer; otherwise agent-config falls back to file-based memory."
+    },
     "bin": [
         "bin/install.php",
         "scripts/agent-config"

package/config/agent-settings.template.yml

@@ -46,6 +46,15 @@ personal:
   # Personal preference — each developer decides for themselves.
   pr_comment_bot_icon: false
 
+  # Autonomous execution — suppress trivial workflow questions (on, off, auto)
+  # on   = act on the obvious next step; never ask "Step 2 or 3?", "should I commit?", etc.
+  # off  = ask trivial workflow questions (legacy behavior)
+  # auto = behaves like 'off' until the user says "arbeite selbstständig" / "work autonomously"
+  #        in the conversation, then switches to 'on' for the rest of the chat.
+  # Blocking decisions (security, scope expansion, push/merge/branch/PR) are NEVER suppressed.
+  # See rules/autonomous-execution.md for the full definition.
+  autonomy: auto
+
 # --- Project / team preferences ---
 project:
   # Path to the PR template file (relative to project root)
@@ -96,6 +105,13 @@ chat_history:
   #   compress = mark for summarization on the next agent turn
   on_overflow: __CHAT_HISTORY_ON_OVERFLOW__
 
+  # Heartbeat marker visibility (token-cost knob)
+  #   on     = print the 📒 marker every reply (~20 tokens/reply, legacy)
+  #   off    = never print (zero tokens, drift only visible by reading the file)
+  #   hybrid = print only on drift states (missing/foreign/returning); silent otherwise
+  # YAML 1.1 booleanizes bare on/off — both are accepted, no quoting needed.
+  heartbeat: hybrid
+
 # --- Optional pipelines ---
 pipelines:
   # Skill improvement pipeline (true, false)
@@ -133,3 +149,32 @@ onboarding:
   # Set to true automatically by /onboard at the end. Flip to false if
   # you want to re-run the flow.
   onboarded: false
+
+# --- Command suggestion (numbered-options shortcut finder) ---
+#
+# When the user's free-form prompt matches an eligible slash command,
+# the agent surfaces a numbered-options block with the recommendation
+# plus an always-present "run as-is" option. The suggestion layer
+# never auto-executes — the user picks. See rules/command-suggestion.md.
+commands:
+  suggestion:
+    # Master switch (true, false). false = the layer is silent; explicit
+    # /commands still work as today.
+    enabled: true
+
+    # Minimum match score (0.0–1.0) before a suggestion surfaces.
+    # 0.6 = default; raise to 0.7 for stricter behaviour, lower to 0.5
+    # if too many useful suggestions are being suppressed.
+    confidence_floor: 0.6
+
+    # Cooldown in seconds between re-suggestions of the same
+    # (command, evidence) pair. Default 600s = 10m.
+    cooldown_seconds: 600
+
+    # Max number of command suggestions before the as-is option.
+    # The as-is option is always extra (so total = max_options + 1).
+    max_options: 4
+
+    # Commands to never suggest. Still work when typed explicitly.
+    # Example: ["/refine-ticket", "/work"]
+    blocklist: []

package/config/gitignore-block.txt

@@ -22,3 +22,7 @@
 .agent-chat-history
 .agent-chat-history.bak
 .agent-chat-history.*.bak
+
+# Agent config — artefact engagement telemetry (default-off, maintainer-only, never commit)
+.agent-engagement.jsonl
+.agent-engagement.jsonl.bak

package/docs/architecture.md

@@ -29,8 +29,32 @@ wired up yet.
     ↓ install.sh (Cursor, Cline, Windsurf, Augment VSCode) / plugin system
 .claude/ .cursor/ .clinerules/  ← Tool-specific symlinks/copies (auto-generated)
 .windsurfrules  GEMINI.md
+    ↓ scripts/build_cloud_bundle.py    (Phase 1 — cloud distribution)
+dist/cloud/<skill>.zip          ← Anthropic Skills bundles (Claude.ai Web / Skills API)
 ```
 
+### Cloud-bundle pipeline
+
+`task build-cloud-bundles-all` produces one ZIP per skill at
+`dist/cloud/<skill>.zip`, ready for upload to Claude.ai Web (Settings →
+Customize → Skills) or the Anthropic Skills API. Per-skill behavior
+follows the cloud-tier classification from `scripts/audit_cloud_compatibility.py`:
+
+| Tier  | Bundle action                                                     |
+|-------|-------------------------------------------------------------------|
+| T1    | Bundle as-is — pure guidance, sandbox-safe                        |
+| T2    | Bundle with prepended sandbox note + package-internal path-swap   |
+| T3-S  | Same as T2; optional script calls degrade gracefully on cloud     |
+| T3-H  | **Skipped** — Phase 2 cloud-aware variant required before bundling |
+
+Cloud-side caps enforced by the builder: `description` ≤ 200 chars
+(Claude.ai Web) with a 1024-char hard cap (Anthropic spec). The sandbox
+note explains to the agent that `.agent-src/`, `agents/`, and `task …`
+references are descriptive — the host has no filesystem access.
+
+CI gate: `task ci-cloud-bundle` runs the builder in `--check` mode and
+fails on any source-side violation, without producing artifacts.
+
 ## What's inside
 
 | Layer | Count | Purpose |
@@ -134,10 +158,13 @@ documented in
 | **Cline** | ✅ | — | — | — | install.sh (symlinks) |
 | **Windsurf** | ✅ | — | — | — | install.sh (concatenated) |
 | **Gemini CLI** | ✅ | — | — | — | install.sh (symlink → AGENTS.md) |
+| **Claude.ai Web / Skills API** | — | ✅ | — | — | `task build-cloud-bundles-all` → `dist/cloud/<skill>.zip` |
 
 Skills use a `SKILL.md` format with YAML frontmatter, compatible with the
 [Agent Skills](https://agentskills.io) community spec and with Claude Code's
-Agent Skills specification.
+Agent Skills specification. Cloud bundles produced by
+`scripts/build_cloud_bundle.py` follow the same format with cloud-side
+adjustments (description budget, sandbox note, package-internal path-swap).
 
 ---
 

package/docs/development.md

@@ -109,7 +109,7 @@ task tool-validate             # Validate tool declarations
 
 ```bash
 task install -- --target <dir> # Run the installer orchestrator on a target
-task install-hooks             # Install git hooks (pre-push sync check)
+task install-hooks             # Install git hooks (pre-commit marketplace lint, pre-push sync check, chat-history bridges)
 ```
 
 ---

package/docs/getting-started.md

@@ -28,6 +28,7 @@ so you can run a few package scripts without installing `go-task`,
 ```bash
 ./agent-config mcp:render          # sync MCP server config into .cursor/ and .windsurf/
 ./agent-config roadmap:progress    # regenerate agents/roadmaps-progress.md
+./agent-config hooks:install       # install pre-commit roadmap-progress hook (opt-in)
 ./agent-config first-run           # guided setup
 ./agent-config help                # full command list
 ```
@@ -98,7 +99,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 46 rules. No configuration needed.
+This is enforced automatically by 53 rules. No configuration needed.
 
 ---
 
@@ -136,7 +137,7 @@ Your agent now understands slash commands:
 | `/chat-history-resume` | Recover context after a crashed or switched session |
 | `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
 
-→ [Browse all 73 commands](../.agent-src/commands/)
+→ [Browse all 77 commands](../.agent-src/commands/)
 
 ---
 

package/docs/installation.md

@@ -149,10 +149,24 @@ auggie plugin install agent-config@event4u-agent-config
 
 ### Claude Code
 
+Two equivalent paths — pick whichever surface you're already in:
+
 ```bash
+# From your shell (CLI)
 claude plugin install agent-config@event4u-agent-config
 ```
 
+```text
+# From inside Claude Code (slash command)
+/plugin marketplace add event4u-app/agent-config
+/plugin install agent-config@event4u-agent-config
+```
+
+The slash-command path is the canonical Claude Code Plugin Marketplace
+flow ([reference](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)).
+It pulls the repo via git-clone and reads the skills directly from
+`.claude/skills/` — no separate ZIP download.
+
 ### Copilot CLI
 
 ```bash
@@ -185,6 +199,78 @@ copilot marketplace add event4u-app/agent-config
 
 ---
 
+## Cloud / Hosted agent installation
+
+For agents running outside your local machine — Claude.ai Web Skills
+and Linear AI — the package's local installer cannot run. Instead,
+the package ships pre-built artefacts you upload or paste into the
+hosted platform's own configuration surface.
+
+These channels are **additional** to project- and plugin-installed
+modes; use them when the agent loop runs on the platform's servers,
+not on your machine.
+
+### Claude.ai Web (Skills UI)
+
+Claude.ai Web supports Skills via manual ZIP upload through the Skills
+UI. The package builds one ZIP per cloud-eligible skill.
+
+1. **Build the bundles**
+
+   ```bash
+   task build-cloud-bundles-all
+   ```
+
+   Output: `dist/cloud/<skill>.zip` per eligible skill. Skills marked
+   `cloud_safe: noop` (filesystem-bound, e.g. `chat-history`,
+   `file-editor`) are bundled with a stripped no-op variant; T3-H
+   skills (hard filesystem dependencies) are excluded by default.
+   See [`scripts/audit_cloud_compatibility.py`](../scripts/audit_cloud_compatibility.py)
+   for per-skill tier and [`scripts/build_cloud_bundle.py`](../scripts/build_cloud_bundle.py)
+   for the gating logic.
+
+2. **Upload to Claude.ai**
+
+   - Open Claude.ai → Skills → Upload Skill
+   - Select one bundle from `dist/cloud/`
+   - Repeat per skill you want available
+
+3. **Verify** — open a fresh Claude.ai conversation and confirm the
+   skill appears in the Skills picker.
+
+### Linear AI (Codegen, Charlie, …)
+
+Linear AI agents read free-form guidance from Linear's workspace
+settings; there is no plugin or upload mechanism. The package ships
+a pre-built digest split into three layers, paste each layer into
+the matching Linear field.
+
+1. **Build the digest**
+
+   ```bash
+   task build-linear-digest
+   ```
+
+   Output:
+   - `dist/linear/workspace.md` — universal coding posture (T1 rules)
+   - `dist/linear/team.md` — framework-specific guidance (Laravel, …)
+   - `dist/linear/personal.md` — stub for individual overrides
+
+2. **Paste into Linear**
+
+   - Open Linear → Settings → Agents → Additional guidance
+   - Paste `workspace.md` into the workspace-level field
+   - Paste `team.md` into your team's field (if framework-specific)
+   - Leave `personal.md` empty unless you have personal overrides
+
+3. **Per-layer rationale** — see
+   [`agents/contexts/linear-ai-three-layers.md`](../agents/contexts/linear-ai-three-layers.md)
+   for the split rationale and
+   [`agents/contexts/linear-ai-rules-inclusion.md`](../agents/contexts/linear-ai-rules-inclusion.md)
+   for which rules go where.
+
+---
+
 ## Alternative install methods
 
 These are fallbacks when the recommended paths above don't work.

package/docs/showcase.md

@@ -0,0 +1,204 @@
+# Showcase — see the package in action
+
+Five copy-paste prompts that demonstrate what `event4u/agent-config`
+actually changes about an agent's behavior. Each example pairs a
+**prompt** with the **expected behavior** and the **rule or skill
+file** the behavior is anchored in — so every claim here is traceable
+back to a file you can read.
+
+These are not transcripts. They describe what a compliant agent does
+(and refuses to do) when the package is installed. If your agent
+does something else, the rule is either not loaded or being violated
+— either is reproducible and fixable.
+
+> Not installed yet? → [Installation](installation.md) ·
+> Settings reference → [`.agent-settings.yml` template](../.agent-src/templates/agent-settings.md)
+
+---
+
+## 1. Autonomy on vs. off — same prompt, two outcomes
+
+Prove that `personal.autonomy` actually suppresses trivial workflow
+questions.
+
+**Setup:** open `.agent-settings.yml`, set `personal.autonomy: on`
+(then later `off` for the second run).
+
+**Prompt** (run twice, once per setting):
+
+```text
+Roadmap "phase-1.md" hat 4 Steps. Arbeite Schritt für Schritt durch.
+```
+
+**Expected behavior — `autonomy: on`:**
+
+- Agent picks the next unchecked step itself, no "Step 2 oder 3?"
+- Runs it, marks `[x]`, moves on.
+- Only stops on blocking decisions: scope expansion, security-sensitive
+  paths, ambiguous requirements (those still get asked, autonomy
+  doesn't override them).
+- Never asks about committing — see Example 2.
+
+**Expected behavior — `autonomy: off`:**
+
+- Agent confirms each step before executing.
+- Surfaces "Soll ich jetzt Step 2 starten?" and waits.
+
+**Anchored in:** [`.agent-src/rules/autonomous-execution.md`](../.agent-src/rules/autonomous-execution.md)
+(trivial vs. blocking decisions, opt-in detection).
+
+---
+
+## 2. Explicit commit grant — never automatic, never asked
+
+Prove that committing is gated by **explicit instruction**, never
+inferred from "we reached a clean stopping point".
+
+**Setup:** any state with uncommitted changes; `personal.autonomy: on`.
+
+**Prompt A** (no commit grant):
+
+```text
+Implementiere Feature X und teste es.
+```
+
+**Expected behavior:**
+
+- Agent implements, runs tests, reports done.
+- Does **not** commit. Does **not** ask "soll ich committen?".
+
+**Prompt B** (explicit grant):
+
+```text
+Implementiere Feature X, teste es, und commit das Ergebnis.
+```
+
+**Expected behavior:**
+
+- Agent implements, tests, **then commits** in logical chunks
+  (Conventional Commits format, no confirmation per chunk).
+
+**Same pattern applies to push, merge, branch creation, PR ops, tags**
+— allowed on explicit instruction, never automatic, never asked. The
+agent doesn't volunteer "soll ich pushen?"; you say "push das" or
+nothing happens.
+
+**Anchored in:** [`.agent-src/rules/commit-policy.md`](../.agent-src/rules/commit-policy.md)
+(four exceptions, never-ask iron law) ·
+[`.agent-src/rules/scope-control.md`](../.agent-src/rules/scope-control.md)
+(git operations permission gate).
+
+---
+
+## 3. Vague request — agent asks instead of guessing
+
+Prove that ambiguous requirements trigger a clarifying question with
+numbered options, not a guess.
+
+**Prompt:**
+
+```text
+Add caching to this.
+```
+
+**Expected behavior:**
+
+- Agent does **not** pick a cache driver, scope, or invalidation
+  strategy on its own.
+- Surfaces numbered options:
+
+  ```text
+  > 1. Redis — durchgehend, geteilt zwischen Workern
+  > 2. Array — Request-lokal, kein externes System
+  > 3. File — persistent ohne Redis-Dependency
+
+  **Empfehlung: 1 — Redis** — …
+  ```
+
+- Recommendation line is mandatory (single-source iron law: exactly
+  one numbered recommendation, no inline `(recommended)` tag).
+
+**Anchored in:** [`.agent-src/rules/ask-when-uncertain.md`](../.agent-src/rules/ask-when-uncertain.md)
+(vague-request trigger table) ·
+[`.agent-src/rules/user-interaction.md`](../.agent-src/rules/user-interaction.md)
+(numbered-options + recommendation iron law).
+
+---
+
+## 4. "done" without verification — agent refuses
+
+Prove that completion claims need **fresh evidence in this message**,
+not "tests should pass".
+
+**Setup:** any code change pending in the working tree.
+
+**Prompt:**
+
+```text
+Bist du fertig? Dann sag es und wir mergen.
+```
+
+**Expected behavior:**
+
+- Agent does **not** say "done", "ready", or "should be fine".
+- Runs the targeted test command for the change in this turn.
+- Runs the quality pipeline (PHPStan / linter / type-checker — whatever
+  the project uses) in this turn.
+- Only after both produce green output does the agent claim
+  completion, and the claim cites the command output by reference.
+- If verification fails, the agent reports the failure verbatim and
+  does not mask it with "kleinere Issues, behebe ich gleich".
+
+**Bypass:** `break-glass: true` (production incident) narrows the
+gate to a targeted test + smoke check + explicit list of skipped
+validations — never skips it entirely.
+
+**Anchored in:** [`.agent-src/rules/verify-before-complete.md`](../.agent-src/rules/verify-before-complete.md)
+(iron law, claim → command mapping, break-glass reduction).
+
+---
+
+## 5. `/work "baue X"` — refine loop instead of blind code
+
+Prove that free-form prompts go through a refinement step (acceptance
+criteria, assumptions, confidence band) before the engine plans.
+
+**Prompt:**
+
+```text
+/work "baue eine API die User-Daten exportiert"
+```
+
+**Expected behavior:**
+
+- Agent does **not** start writing routes, controllers, or migrations.
+- Reconstructs the prompt into:
+  - **Acceptance criteria** — what "done" looks like (e.g. "GET
+    /api/users/export returns CSV", "auth required", "rate-limited").
+  - **Assumptions** — what was inferred (format = CSV? scope = own
+    user only? all users for admins?).
+  - **Confidence band** — high / medium / low, with the gaps named.
+- On low confidence, agent **blocks** and asks before any
+  implementation.
+- Only on high (or user-confirmed medium) confidence does the engine
+  proceed to plan → implement → test → verify → report.
+
+**Anchored in:** [`.agent-src/commands/work.md`](../.agent-src/commands/work.md)
+(Option-A loop, confidence-band gate, no auto-git) ·
+[`.agent-src/skills/refine-prompt/SKILL.md`](../.agent-src/skills/refine-prompt/SKILL.md)
+(AC + assumption reconstruction).
+
+---
+
+## 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
+[`docs/skills-catalog.md`](skills-catalog.md).
+
+**Suggesting an example?** Open a PR adding a new section here. Same
+shape: setup → prompt → expected behavior → anchor file. Keep claims
+traceable; don't ship transcripts that drift the moment a rule
+changes.