@event4u/agent-config 1.9.1

package/.agent-src/rules/skill-quality.md

@@ -0,0 +1,110 @@
+---
+type: "auto"
+description: "Creating, editing, or reviewing skills — minimum quality standard, every skill must be executable, validated, and self-contained"
+alwaysApply: false
+source: package
+---
+
+# Skill Quality
+
+## Minimum Sharpness
+
+Every skill must answer four questions. If ANY answer is weak, the skill is not done.
+
+| # | Question | Section | Standard |
+|---|---|---|---|
+| 1 | When should I use this? | `When to use` | Concrete trigger, not generic |
+| 2 | What exactly do I do? | `Procedure` | Executable steps with decisions |
+| 3 | How do I verify it worked? | `Procedure` (validation step) | Concrete checks, not "verify it works" |
+| 4 | What common failure must I avoid? | `Gotcha` + `Do NOT` | Real failure patterns, not platitudes |
+
+## Required Sections
+
+Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `Do NOT`.
+
+## Frontmatter Contract
+
+Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.schema.json`.
+See [`agents/docs/frontmatter-contract.md`](../../../agents/docs/frontmatter-contract.md)
+for the human-readable contract across all artefact types. Violations are
+reported by `scripts/skill_linter.py` as `schema_<rule>` errors and fail
+`task validate-schema` / `task ci`.
+
+## Description Triggering
+
+Claude routes skills by reading the frontmatter `description`. Polite, generic,
+or hedged descriptions cause **undertriggering** — the skill never loads when it
+should, and the user never learns it exists.
+
+Make descriptions "pushy" — explicit about when to fire:
+
+- Start with a concrete verb phrase: `Use when ...`, `Creates ...`, `Reviews ...`.
+- Name 2+ concrete triggers — domains, symptoms, file types, user phrasing.
+- End with: `... even if they don't explicitly ask for \`<skill-name>\`.`
+- Avoid hedges: `may help with`, `can be useful for`, `covers various`.
+- **Keep it ≤ 200 characters.** `scripts/skill_linter.py` warns at
+  `description_too_long` above this. If the pushy tail pushes you over, cut
+  adjectives, drop the second example phrasing, or collapse a list — do
+  **not** drop the trigger vocabulary or the `even if ...` tail.
+
+Source: [`skills/skill-creator` in `anthropics/skills`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)
+— description-optimization guidance adopted via
+[`agents/roadmaps/archive/road-to-anthropic-alignment.md`](../../../agents/roadmaps/archive/road-to-anthropic-alignment.md)
+Phase 2.
+
+**Litmus test:** Read the description cold, without the skill's body. If you
+cannot name at least two phrasings a user would realistically type that should
+route to this skill, the description is too polite. Rewrite it.
+
+## Skill Independence
+
+```
+If a skill is not executable without opening a guideline, it is broken.
+```
+
+- Skills MAY reference guidelines for detailed conventions
+- Skills MUST NOT outsource their core workflow to guidelines
+- If removing guideline references makes the skill useless → the skill is too weak
+
+**Litmus test:** Cover all guideline references in the Procedure. Is it still executable?
+If not → the skill needs more own steps, decisions, and validation — not more guideline links.
+
+## Merge Preservation
+
+When merging or refactoring skills, the merged result MUST preserve:
+
+1. **Strongest validation** from each source skill
+2. **Strongest example** (good/bad contrast) from each source
+3. **Strongest anti-pattern** from each source
+4. **All concrete decision criteria** that differ between sources
+
+A merge is invalid if:
+- Validation got weaker than the strongest source
+- Examples were lost without replacement
+- Anti-pattern coverage decreased
+- The merged skill became a generic umbrella doc
+
+## Compression Preservation
+
+When compressing a skill, the compressed version MUST preserve:
+
+- Trigger quality (description + When to use)
+- All procedure steps that contain decisions
+- All concrete validation checks
+- All gotchas and anti-patterns
+- Strongest example (at minimum one good/bad contrast)
+
+Compression may remove:
+- Verbose explanations
+- Redundant examples (keep the strongest)
+- Commentary that doesn't affect execution
+
+## Refactor Safety
+
+When refactoring or optimizing skills:
+
+- NEVER weaken validation to pass linter
+- NEVER remove anti-patterns to reduce size
+- NEVER replace concrete checks with "verify it works"
+- NEVER merge skills if the result is broader than either source
+- ALWAYS run linter before and after — fail count must not increase

package/.agent-src/rules/slash-commands.md

@@ -0,0 +1,30 @@
+---
+type: "auto"
+description: "When user types a slash command like /create-pr, /commit, or pastes command file content"
+alwaysApply: false
+source: package
+---
+
+# Commands
+
+When the user types a command (`/create-pr`, `# create-pr`, or pastes a command file),
+**execute it immediately**. No questions, no opinions, no summaries, no confirmations.
+
+- Match the command file in `.augment/commands/` (or `agents/overrides/commands/`).
+- Read it, follow the steps in order.
+- Ask only when the command itself says "ask the user".
+- If the user pastes the **content** of a command file, treat it as an invocation — not a question.
+- **NEVER** respond with "looks good" or ask "shall I execute?" — just execute.
+- **NEVER** respond with "this is the current version" or "do you want to change something?" — just execute.
+- **NEVER** treat pasted command content as a review request — it's ALWAYS an invocation.
+- The only exception: the user's message contains an explicit instruction about the command
+  (e.g., "update this command" or "review this command"). In that case, follow the instruction instead.
+
+## Open files are irrelevant for command detection
+
+Editor may report an open file (e.g., "user has `compress.md` open"). **Irrelevant** for commands.
+
+- `/compress` typed → **run** compress command — even if `compress.md` is open in editor.
+- Command content in context + open file → **command invocation takes priority**.
+- Do NOT confuse "file is open" with "user wants to discuss this file".
+- User's typed message determines intent — not editor state.

package/.agent-src/rules/think-before-action.md

@@ -0,0 +1,91 @@
+---
+type: "always"
+description: "Always analyze before acting. Prefer targeted inspection, tests, and real verification over guessing or trial-and-error."
+alwaysApply: true
+source: package
+---
+
+# think-before-action
+
+- Always analyze before coding or modifying anything
+- Never guess behavior — verify using code, data, or tools
+- Prefer targeted inspection over brute-force trial-and-error
+- Use efficient tooling (e.g. jq, debugger, logs) instead of loading full data
+- Always verify results after changes (API calls, UI tests, etc.)
+- When behavior can be defined, prefer test-first or test-driven work
+- If requirements are unclear, ask a precise clarification question instead of making hidden assumptions
+- Refactors must preserve behavior, validation, examples, and anti-failure guidance unless there is an explicit reason to change them
+- Do NOT modify code you do not fully understand — read it first, trace the flow, then change it
+
+## The Developer Workflow
+
+Work like a real developer. Follow this order strictly:
+
+1. **Understand** — Read task, ticket, acceptance criteria. Unclear? Ask, don't assume.
+2. **Analyze** — Read affected code, trace data flow, compare with requirements.
+3. **Plan** — What to change, what NOT to change, how to verify.
+4. **Implement** — Focused changes. Follow existing patterns. No unrelated rewrites.
+5. **Verify** — Run tests, hit endpoint, check UI. Real execution, not "should work".
+
+Skipping steps 1-3 = #1 cause of wrong implementations and wasted retries.
+
+## Consult memory before editing
+
+Before writing code for the touched paths, call
+[`memory-access`](../guidelines/agent-infra/memory-access.md):
+
+```python
+from scripts.memory_lookup import retrieve
+priors = retrieve(
+    types=["architecture-decisions", "domain-invariants"],
+    keys=<touched paths>,
+    limit=3,
+)
+```
+
+A matching `architecture-decision` explains *why* the current shape
+exists; a matching `domain-invariant` is a hard constraint you cannot
+violate. Cite the `id` if a match influences the plan. No match → no
+overhead; proceed.
+
+## Verify with real tools
+
+| What changed | How to verify |
+|---|---|
+| **Backend/API** | `curl`, Postman (or Postman MCP), test endpoint |
+| **Frontend/UI** | Playwright MCP or browser — rendered state, interactions |
+| **Logic/flow** | Xdebug (or Xdebug MCP) — trace execution, inspect variables |
+| **CLI/Jobs** | Run command, check side effects, exit code |
+| **Database** | Query result, check migrations |
+
+If debugging/testing tool available as MCP server — prefer it.
+
+If verification not possible: state what is missing and how change should be tested.
+
+## Reduce output — targeted tools over full dumps
+
+Never load full datasets into context. Extract what you need:
+
+- `jq` for JSON: `curl -s /api/users | jq '.[0] | {id, email}'`
+- `rg` / `grep` for text — specific patterns, not full files
+- `head`, `tail`, `cut`, `sort`, `uniq` to narrow results
+- `--filter`, `--json`, `--format` flags on CLI tools
+- Logs: filter by request ID, timestamp, error type — not full files
+
+## No blind retries
+
+- Fail? **Read the error**, analyze cause, then fix
+- Do NOT retry same approach hoping for different result
+- Do NOT loop trial-and-error when one inspection reveals the cause
+- Max 2 retries same approach — then stop and rethink
+
+## Open files are context, not intent
+
+The editor may report an open file. This is **background context only** — NOT the user's intent.
+
+- **User's message determines intent** — not which file is open.
+- User has `README.md` open + types `/compress` → intent is compress, not README.
+- User has `UserController.php` open + asks "how do tests work?" → intent is testing, not the controller.
+- Only treat open file as relevant when the user explicitly references it ("fix this file", "what does this do?").
+
+If analysis is skipped → results are unreliable.

package/.agent-src/rules/token-efficiency.md

@@ -0,0 +1,99 @@
+---
+type: "always"
+description: "Token efficiency — redirect output, minimize tool calls, keep responses concise"
+alwaysApply: true
+source: package
+---
+
+# Token Efficiency
+
+## The Iron Laws
+
+```
+NEVER load full command output into context. Redirect → read summary → targeted details.
+```
+
+```
+NEVER call the same tool more than 2 times in a row with similar parameters.
+If you catch yourself repeating a tool call — STOP, rethink, try a different approach, or ask the user.
+```
+
+### Anti-loop: Extended Reasoning
+
+Do NOT use extended reasoning / chain-of-thought tools for simple tasks like viewing files,
+running commands, or making straightforward edits. They are ONLY for genuinely complex
+multi-step reasoning. If you find yourself calling such tools more than once per task —
+you are looping. Stop immediately and act directly instead.
+
+### Anti-loop: "CRITICAL INSTRUCTION" and self-prompting
+
+If you find yourself generating text that starts with "CRITICAL INSTRUCTION", "I need to",
+"Let me think", "Related tools:", or similar self-directed reasoning inside a tool call
+or as a preamble before acting — **you are in a loop**. This happens after connection errors
+or when the user says something like "continue" / "mach weiter".
+
+**Immediate action:**
+
+1. STOP generating self-instructions.
+2. Read the last user message — what did they actually ask?
+3. Do that ONE thing directly. No planning monologue, no tool selection reasoning.
+4. If you don't know what the user wanted, ask: "Where were we?"
+
+## Fresh Output Over Memory
+
+**CRITICAL**: When a tool or command returns a value (branch name, file path, PR number),
+use that EXACT value in subsequent API calls. NEVER substitute a value from earlier in
+the conversation. Context decay causes silent mismatches — fresh output is the only source of truth.
+
+## Conversation Efficiency
+
+### Act, skip narration
+
+- **Skip repeating the user's request.** They know what they asked.
+- **Just do it** — skip announcing what you're about to do.
+- **Skip explaining obvious tool calls.** Reading a file needs no justification.
+- **Report only outcomes** — skip intermediate step summaries unless the user needs them.
+
+**This rule NEVER overrides user-interaction or command rules.**
+Token efficiency means fewer *unnecessary* words — NOT skipping required questions,
+numbered options, or command steps. When a rule or command says "ask the user", you ask.
+
+### Stop early — max 2 retries
+
+- **Command fails twice with same error** → stop, rethink. Try a different approach.
+- **grep/search returns nothing after 2 attempts** → switch approach or ask the user.
+- **Max 3 diagnostic commands** per error. Read the error, think, act.
+- **One hypothesis at a time.** Pick the most likely, try it. If it fails, ask.
+
+### Keep intermediate output minimal
+
+Read `personal.minimal_output` (default: `true`) and `personal.play_by_play`
+(default: `false`) from `.agent-settings.yml`.
+
+When `personal.minimal_output: true`:
+- Multi-step work: short bullet points only, no paragraphs.
+- No thinking out loud — user doesn't need your reasoning.
+- When `personal.play_by_play: false`: silently investigate, report conclusion only.
+- When `personal.play_by_play: true`: briefly share intermediate findings.
+- At the end: concise summary — what changed, what user needs to know.
+
+### Don't re-read what you already know
+
+- Edited a file → edit tool showed result. Don't re-read.
+- Ran a command → you have output. Don't re-run to "verify".
+- File in context from recent messages → don't reload.
+
+### Minimize tool calls
+
+- Parallel reads — don't read 5 files sequentially.
+- Regex search over full file reads. View specific line ranges.
+- One codebase search call with all symbols — not 5 separate.
+- Short question → short answer. Summary tables only for 3+ items.
+
+### Exceptions
+
+- Small output (< 30 lines): read directly.
+- Debugging: OK to read more context around one error.
+- User explicitly asks for full output: show it.
+
+→ Detailed patterns: `guidelines/agent-infra/output-patterns.md`

package/.agent-src/rules/tool-safety.md

@@ -0,0 +1,36 @@
+---
+type: auto
+source: package
+description: "When a skill uses external tools — enforce allowlist, deny-by-default, and no hidden credential patterns"
+---
+
+# Tool Safety
+
+Tools are permissions, not abilities. Every tool access must be declared and reviewable.
+
+## Constraints
+
+- **Deny by default** — no access unless in `allowed_tools`
+- **Allowlist only** — names must match tool registry
+- **Read-first** — write requires explicit approval
+- **No hidden credentials** — no API keys in skill files
+- **No arbitrary execution** — adapters have fixed interfaces
+- **Audit trail** — tool usage must be observable
+
+## When this applies
+
+- Skills declaring `allowed_tools`
+- Skills referencing external APIs (GitHub, Jira)
+- Runtime execution accessing external services
+
+## Escalation
+
+1. Do NOT use unregistered tools
+2. Flag as registry extension suggestion
+3. Tool must be added to registry before use
+
+## Not covered
+
+- Internal agent capabilities (not external tools)
+- MCP server configuration (`mcp` skill)
+- Credential management (environment config)

package/.agent-src/rules/upstream-proposal.md

@@ -0,0 +1,76 @@
+---
+type: "auto"
+description: "After creating or significantly improving a skill, rule, guideline, or command — ask if it should be contributed upstream to the shared package"
+alwaysApply: false
+source: package
+---
+
+# Upstream Proposal
+
+## When to activate
+
+After the agent **creates or significantly improves** any of these in a consumer project:
+
+- Skill (new or major update)
+- Rule (new or major update)
+- Guideline (new or major update)
+- Command (new or major update)
+
+**Also activate when:**
+
+- A project-specific skill/rule could be **generalized** to benefit all consumers
+- An override was created that improves on the shared version
+- A learning was captured that produced a high-quality new artifact
+
+**Do NOT activate when:**
+
+- Working inside the agent-config package itself (no self-referential proposals)
+- The change is a trivial fix (typo, formatting)
+- The user already declined upstream for this exact item in this conversation
+
+## Consent check
+
+**⛔ MANDATORY: Always ask the user. Never skip this step.**
+
+After completing the creation/improvement, evaluate:
+
+1. **Is this universal?** Could other projects benefit from this?
+2. **Is this generalizable?** Even if project-specific, can it be abstracted?
+3. **Is this high-quality?** Does it pass the promotion gate from `capture-learnings`?
+
+If ANY of these is YES → propose to the user:
+
+### For universal content (directly applicable):
+
+```
+> 🔄 The [skill/rule/guideline] `{name}` you just created could benefit all projects
+> using the shared agent-config package.
+>
+> 1. Yes — contribute upstream via PR
+> 2. No — keep project-local only
+```
+
+### For project-specific content (needs generalization):
+
+```
+> 🔄 The [skill/rule/guideline] `{name}` is project-specific, but I could generalize
+> it for the shared package. [Brief explanation of what would change]
+>
+> 1. Yes — generalize and contribute upstream
+> 2. No — keep project-local only
+```
+
+## After user response
+
+- **User picks 1** → invoke `upstream-contribute` skill (which has its own consent gate for repo access)
+- **User picks 2** → stop. Do NOT ask again for this item.
+- **Max 1 proposal per created artifact** — never nag.
+
+## Important
+
+- **Consent is non-negotiable** — the user decides, always.
+- **Do NOT batch proposals** — ask for each artifact separately.
+- **Do NOT interrupt flow** — only propose AFTER the creation/improvement is complete.
+- **Do NOT propose for trivial changes** — formatting, typos, comment updates.
+- **Respect "no"** — if the user declines, do not revisit unless they bring it up.
+- **Token efficiency** — this rule costs zero tokens when not triggered (auto type).

package/.agent-src/rules/user-interaction.md

@@ -0,0 +1,79 @@
+---
+type: "always"
+description: "User interaction — numbered options, progress indicators, summaries"
+alwaysApply: true
+source: package
+---
+
+# User Interaction
+
+## Numbered Options — Always
+
+When asking the user a question with predefined choices, **always present numbered options**.
+The user should be able to reply with just a number (e.g., `1`) instead of typing a sentence.
+
+### Format
+
+```
+> 1. First option — brief explanation
+> 2. Second option — brief explanation
+> 3. Third option — brief explanation
+```
+
+### Rules
+
+- **Every question with choices** must use numbered options — no exceptions.
+- **Keep options short** — one line each, with a brief explanation after the dash.
+- **Always include a "skip" or "no change" option** when applicable.
+- **Default/recommended option** can be marked: `1. Do X (recommended)`.
+- **Use the user's language** for the question and options.
+- **Accept both** the number and a natural language answer (e.g., "1" or "the first one").
+
+### Examples
+
+**Binary choice:**
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+**Multiple choice with skip:**
+```
+> 1. Fix the code
+> 2. Fix the test
+> 3. Skip
+```
+
+**Confirmation with context:**
+```
+> Found PR #1399 on branch `chore/refactor-agent-setup-2`.
+>
+> 1. Yes, that's the right PR
+> 2. No, different PR — I'll provide the URL
+```
+
+### When NOT to use numbered options
+
+- **Open-ended questions** where the answer is free text (e.g., "What should the class be named?").
+- **Simple yes/no** can use numbered options OR accept "ja"/"nein" directly.
+  Even for yes/no, prefer numbered options if there's additional context to show.
+
+## Progress Indicators
+
+When processing multiple items (e.g., review comments, test failures), show progress:
+
+```
+**Comment 3/7** — `filename.php:42`
+```
+
+## Summaries
+
+After completing a batch of actions, provide a summary table:
+
+```
+| # | File | Action |
+|---|---|---|
+| 1 | `file.php` | Fixed null check |
+| 2 | `test.php` | Updated assertion |
+| 3 | `config.php` | Skipped (intentional) |
+```

package/.agent-src/rules/verify-before-complete.md

@@ -0,0 +1,120 @@
+---
+type: "always"
+description: "Verify before completion — run tests and quality tools before claiming done"
+alwaysApply: true
+source: package
+---
+
+# Verify Before Completion
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command **in this message**, you cannot claim it passes.
+
+## When to run what — timing matters
+
+**Quality tools (PHPStan, Rector, ECS) run ONCE at the very end** — not after every edit.
+Do NOT run quality checks between tasks if you have more work to do.
+Only run the full quality pipeline when you are about to finish all work in the current conversation.
+
+**Tests: as targeted as possible, as little as necessary.**
+- During work: run ONLY the specific test class or test case affected by the change.
+  Use `--filter=ClassName` or `--filter=test_name` — NEVER the full suite mid-work.
+- Only run tests when you genuinely need to verify behavior (not "just to be safe").
+- Full test suite: ONCE at the very end, before quality tools.
+
+**The sequence at the end:**
+1. All code changes are done
+2. Run tests — targeted first (`--filter`), full suite only if targeted passes
+3. Run quality pipeline (PHPStan → Rector → ECS → PHPStan)
+4. Fix any issues from step 2-3
+5. ONLY THEN claim completion or suggest commit/push/PR
+
+## The Gate
+
+Before claiming ANY work is complete:
+
+1. **IDENTIFY** — What command proves this claim? (tests, PHPStan, build, etc.)
+2. **RUN** — Execute the full command (fresh, complete, not cached)
+3. **READ** — Full output, check exit code, count failures
+4. **VERIFY** — Does the output actually confirm the claim?
+5. **ONLY THEN** — Make the claim
+
+Skip any step = the claim is unverified.
+
+## When this applies
+
+- About to claim **all work is done** (not after individual edits)
+- About to say "done" or "complete"
+- Before suggesting to commit, push, or create a PR
+- Any statement implying all work is finished
+
+## Red flags — STOP immediately
+
+- Using "should pass", "probably works", "seems fine"
+- Expressing satisfaction before running verification
+- About to commit/push without running tests + quality
+- Trusting a previous run from earlier in the conversation
+- Relying on partial verification (ran tests but not PHPStan)
+- ANY wording implying success without fresh evidence
+
+## Verification commands
+
+For specific commands → see the `quality-tools` skill.
+
+For the detailed evidence-gate playbook (claim→command mapping, output
+inspection, end-of-work sequence) → see the `verify-before-complete`
+skill.
+
+## Minimum verification per task type
+
+| Task | Required evidence |
+|---|---|
+| Code change | Tests + PHPStan |
+| New feature | Tests + PHPStan + smoke test |
+| Bug fix | Regression test + full suite |
+| Refactoring | Full suite + PHPStan + Rector |
+| Config/migration | Relevant tests or command output |
+| API endpoint | curl/HTTP response output |
+| Documentation only | No verification needed |
+
+**Never accept** as proof: "should work", "looks correct", "logic is sound".
+No captured output = not verified.
+
+## Confidence gating
+
+State confidence explicitly before claiming completion on non-trivial work.
+
+- **High** — runtime path read end-to-end, relevant tests inspected or run,
+  no hidden side-effects (queues/events/observers) unaccounted for.
+- **Medium** — main path verified but one gap remains; list the gap in the
+  completion message.
+- **Low** — broad implementation NOT allowed; switch to analysis, narrow
+  the scope, or ask the user before proceeding.
+
+For high-risk areas (auth, tenancy, migrations, queues, dependencies,
+external APIs, data exposure), "high" requires tests AND a cross-layer
+read — not inference from a single file.
+
+## Break-glass reduction
+
+During a live production incident the verification gate is **narrowed**,
+never skipped. Break-glass requires explicit user invocation (e.g.
+`break-glass: true`, "this is a hotfix"). Never enter it unilaterally.
+
+Minimum evidence:
+
+- **Targeted test(s)** covering the exact regression — zero tests is not
+  acceptable.
+- **Smoke check** of the fixed path (curl, manual trigger, log tail) with
+  output captured in the message.
+- **Explicit list of skipped validations** and a **follow-up commitment**
+  (ticket or PR line) to run them within 24h.
+
+Completion wording: _"hotfix applied, full verification deferred per
+break-glass"_ — never _"done"_ or _"verified"_. The normal gate resumes
+on the follow-up PR.