@event4u/agent-config 1.16.0 → 1.18.0

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

@@ -3,6 +3,8 @@ type: "auto"
 description: "Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators"
 alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/user-interaction-mechanics.md
 ---
 
 # User Interaction
@@ -55,7 +57,7 @@ recommendation line is mandatory.
 - Hiding behind "you know the project better"
 - Inline `(recommended)` tag with no follow-up `Recommendation: N` line
 
-**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#when-the-user-calls-out-a-language-slip).**
+**Slip handling — same protocol as [`language-and-tone`](language-and-tone.md#slip-handling).**
 User calls out a missing or wrong recommendation → acknowledge once
 in the user's language, rewrite the reply with a recommendation,
 ship. No "from now on" promises — only the next reply proves
@@ -84,12 +86,11 @@ Mechanical backstop: `python3 scripts/check_reply_consistency.py --stdin < draft
 (non-zero exit on any rule above). Self-scan is the primary gate; the
 script is the deterministic safety net for ambiguous cases.
 
-### Common failure modes — known, named, no excuses
-
-- **End-of-turn menu skipped.** Reply answers the question fine, then ends with `> 1. Foo > 2. Bar > 3. Stop` and no `Empfehlung:`. Iron Law 1 was violated — these are numbered options, position is irrelevant.
-- **"Genuinely no preference" hedge.** Pick anyway. The agent has more context than the user on the trade-off; refusing to pick dumps the work back. Pick the safest option, name the flip-condition.
-- **"User knows the project better" hedge.** Same failure mode, different costume. The user asked for an opinion by virtue of accepting the options block; deliver it.
-- **Multi-block reply with one recommendation.** Two options blocks but only one `Empfehlung:` line — the second block is unguarded. Rule 5 above closes this.
+Common failure modes (end-of-turn menu skipped, "no preference"
+hedges, multi-block reply with one recommendation) and the named
+slip catalog live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md)
+§ Common failure modes.
 
 ## Numbered Options — Always
 
@@ -117,65 +118,9 @@ just a number (e.g., `1`) instead of typing a sentence.
 - **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
-
-**Recommendation: 1 — Interactive** — the comments touch security-sensitive code,
-so a wrong auto-fix is more expensive than approving each one. Caveat: flip to 2
-if the comments turn out to be pure formatting.
-```
-
-**Multiple choice with skip:**
-
-```
-> 1. Fix the code
-> 2. Fix the test
-> 3. Skip
-
-**Recommendation: 1 — Fix the code** — the test asserts the documented behaviour;
-the production code drifted from the contract. Caveat: pick 2 only if the contract
-itself is wrong.
-```
-
-**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
+### Examples and "when NOT to use" — see mechanics
 
-**Recommendation: 1 — Yes** — the branch name matches the PR title exactly.
-Caveat: flip to 2 if the PR was reopened from a different branch.
-```
-
-### 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) |
-```
+Worked examples (binary choice, multiple choice with skip,
+confirmation with context), the "when NOT to use numbered options"
+catalog, progress indicators, and summary-table patterns live in
+[`contexts/communication/rules-auto/user-interaction-mechanics.md`](../contexts/communication/rules-auto/user-interaction-mechanics.md).

package/.agent-src/skills/ai-council/SKILL.md

@@ -4,6 +4,8 @@ description: "Use when polling external AIs (OpenAI, Anthropic) outside the host
 source: package
 ---
 
+> **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
+
 # ai-council
 
 ## When to use

package/.agent-src/skills/api-testing/SKILL.md

@@ -13,7 +13,7 @@ contract validation, response structure checks, or external service mocking.
 
 ## Procedure: Write API tests
 
-1. **Understand the endpoint** — Read controller, form request, existing tests. Understand expected behavior and edge cases before writing anything.
+1. **Understand the endpoint** — Read the controller, form request, and existing tests. Understand expected behavior, edge cases, and auth requirements before writing anything.
 2. **Set up test data** — Use seeders (preferred) or factories. Mock external services with `Http::fake()`.
 3. **Write test cases** — Cover success, validation errors, authorization failures, edge cases.
 4. **Assert response** — Check status code, JSON structure, data values. Use `assertJsonStructure()`.

package/.agent-src/skills/check-refs/SKILL.md

@@ -16,57 +16,76 @@ execution:
 
 ## When to use
 
-- Skill/rule/command/guideline/context renamed, moved, or deleted
-- Linking newly added artifact from elsewhere in `.agent-src.uncompressed/`
-- Pre-PR when changes touch cross-references
-- CI `check-refs` job failed and target ref needs locating
+Use this skill when:
 
-NOT: body-only edits, frontmatter shape (use `lint-skills`), compressed pairs
-(use `bash scripts/compress.sh --check`).
+- A skill, rule, command, guideline, or context has been renamed or deleted
+- Linking a newly added artifact from elsewhere in `.agent-src.uncompressed/`
+- Preparing a PR that touches cross-references between agent artifacts
+- CI's `check-refs` job failed and the broken reference needs to be located
+
+Do NOT use when:
+
+- Only the body of a single file changed and no names or paths were touched
+- Checking frontmatter shape or required sections — use `lint-skills` instead
+- Verifying compressed vs uncompressed pairs — use `bash scripts/compress.sh --check` instead
 
 ## Procedure
 
-1. **Inspect scope** — confirm at least one rename/move/remove since last clean
-   run. Body-only edits cannot break refs.
-2. **Dispatch via runtime** —
+### 1. Inspect the scope of recent changes
 
-   ```bash
-   python3 scripts/runtime_dispatcher.py run --skill check-refs
-   ```
+Identify whether any artifact was renamed, moved, or removed since the last
+clean run. Cross-reference checks are relevant only when names or paths shift;
+pure body edits cannot break references.
 
-   Handler runs `python3 scripts/check_references.py`, captures stdout/stderr,
-   returns typed `ExecutionResult`.
-3. **Verify result** —
-   - `exit_code: 0` → all refs resolve
-   - `exit_code: 1` → broken refs — read stdout for `file:line → target`
-   - `status: timeout` → investigate, do not raise limit blindly
-   - `status: error` → interpreter or script missing, or wrong cwd
+### 2. Dispatch via the runtime layer
 
-## Output
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
 
-1. One-line summary: status, exit code, duration (ms)
-2. Count of broken refs if any
-3. First 10 broken refs: `file:line → missing-target`
-4. Next action: fix, re-run, or surface raw stdout
+```bash
+python3 scripts/runtime_dispatcher.py run --skill check-refs
+```
 
-## Gotcha
+The dispatcher resolves the request, the shell handler runs
+`python3 scripts/check_references.py`, captures stdout/stderr, and returns a
+typed `ExecutionResult`.
 
-- Checker is read-only — clean re-run must be produced by re-invoking, not
-  assumed
-- Running outside repo root → zero files inspected, false pass
-- Refs inside fenced code blocks may still be parsed — verify a "false
-  positive" before suppressing it
+### 3. Verify the result
 
-## Do NOT
+Check the returned `ExecutionResult`:
+
+- `exit_code: 0` → all cross-references resolve
+- `exit_code: 1` → at least one broken reference — read `stdout` for file,
+  line, and the offending ref, then fix the source or update the target
+- `status: timeout` → the checker exceeded `timeout_seconds` — investigate
+- `status: error` → interpreter or script missing — confirm `python3` and
+  `scripts/check_references.py` are available at the repository root
 
-- Do NOT call `check_references.py` directly when the intent is to exercise
-  the runtime path — go through the dispatcher
-- Do NOT raise `timeout_seconds` to mask a real slowdown
-- Do NOT add pipes/redirection — handler uses `shell=False`, argv form only
+## Output format
 
-## References
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of broken references found, if any
+3. First 10 broken references with `file:line → missing-target`
+4. Next action: fix references, re-run the skill, or surface `stdout` for
+   review
+
+## Gotchas
+
+- The checker is read-only — it never rewrites references, so a clean run
+  after a fix must be produced by re-invoking the skill, not by assumption
+- Running outside the agent-config repo root makes the checker inspect zero
+  files and report a false pass
+- Relative links inside comments or fenced code blocks may still be parsed as
+  references depending on the checker's current rules; do not suppress a
+  broken ref without confirming it is a genuine false positive
+
+## Do NOT
 
-- Skill: `lint-skills` — sibling pilot for skill/rule shape
-- Rule: `runtime-safety` — execution metadata constraints
-- Script: `scripts/check_references.py`, `scripts/runtime_dispatcher.py`,
-  `scripts/runtime_handler.py`
+- Do NOT invoke `scripts/check_references.py` directly when the intent is to
+  verify the runtime path — always go through the dispatcher so the
+  `ExecutionResult` is produced and inspectable
+- Do NOT raise `timeout_seconds` to mask a slowdown — investigate which part
+  of the tree grew large enough to push past 60 seconds
+- Do NOT add piping or redirection to `command` — the handler uses
+  `shell=False` and will refuse anything outside pure argv form

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -12,48 +12,106 @@ execution:
 
 ## When to use
 
-- Generating commit message from staged changes
-- Generating squash merge title from PR
-- Deciding correct type for a change
-- Reviewing/correcting commit messages
-- Splitting vague changes into multiple commits
+Use this skill when:
 
-NOT: explaining standard (reference rule), git workflow (use `git-workflow`)
+- Generating a commit message from staged changes
+- Generating a squash merge title from a PR
+- Deciding the correct Conventional Commit type for a change
+- Reviewing whether a commit message is correct
+- Splitting one vague change into multiple commit messages
 
-## Procedure: Generate
+Do NOT use when:
 
-1. **Intent** — feat/fix/refactor/docs/test/ci/chore/perf/build/style. Classify by intent, not file type.
-2. **Mixed concerns?** — split into multiple commits or choose dominant net effect for squash title.
-3. **Scope** — Jira ID or area name. Only if it adds clarity.
-4. **Description** — intent, not implementation. Imperative. Max 72 chars. No generic filler.
-5. **Breaking?** — add `!` or `BREAKING CHANGE:` footer:
+- Only explaining the Conventional Commits standard (just reference the rule)
+- The message is already correct and does not need review
+- Following the Git workflow (use `git-workflow` skill)
+
+## Procedure: Generate commit message
+
+### 1. Identify the actual intent
+
+Determine whether the change is:
+
+- New behavior → `feat`
+- Bug fix → `fix`
+- Structural cleanup → `refactor`
+- Docs only → `docs`
+- Tests only → `test`
+- CI/build/tooling → `ci` or `build`
+- Maintenance → `chore`
+- Performance → `perf`
+- Formatting only → `style`
+
+Classify by **user-visible or system-relevant intent**, not by file type alone.
+
+### 2. Detect mixed concerns
+
+Check whether the change includes more than one unrelated concern.
+
+If yes:
+
+- Suggest splitting into multiple commits
+- Or choose the dominant net effect for squash merge title
+
+### 3. Choose scope
+
+Add a scope only if it improves clarity:
+
+- Jira ticket ID: `DEV-1234`
+- Module/area: `api`, `auth`, `skills`, `rules`, `ci`
+
+### 4. Write the description
+
+- State the intent clearly
+- Avoid generic filler (`update stuff`, `fix things`)
+- Stay concise — max 72 chars total for first line
+- Imperative mood: "add", "fix", "remove" — not "added", "fixed", "removed"
+
+### 5. Check for breaking change
+
+If compatibility is broken, add `!` after type/scope:
 
 ```
 feat(api)!: rename invoice status values
 ```
 
-6. **Validate** — type matches intent? scope useful? not hiding multiple concerns?
+Or add `BREAKING CHANGE:` in the commit body/footer.
+
+### 6. Validate
+
+- Type matches intent?
+- Scope is useful (not noise)?
+- Description is specific (not generic)?
+- Not hiding multiple unrelated changes?
+- Breaking changes are marked?
 
-## Procedure: Review
+## Procedure: Review existing commit message
 
-Parse → check type vs diff → check scope → check description clarity → suggest corrections.
+1. Parse the message into type, scope, description
+2. Check type accuracy against the actual diff
+3. Check scope usefulness
+4. Check description clarity and specificity
+5. Suggest corrections if any check fails
 
-## Procedure: Squash merge title
+## Procedure: Generate squash merge title
 
-Read all PR commits → identify net effect → write single Conventional Commit summarizing it.
+1. Read all commits in the PR
+2. Identify the **net effect** — what does the PR accomplish overall?
+3. Write a single Conventional Commit message summarizing the net effect
+4. Do not list every internal commit — summarize
 
-## Output
+## Output format
 
-1. Recommended message(s)
-2. Brief type rationale
-3. Split suggestion if needed
+1. Recommended commit message(s)
+2. Brief rationale for type choice
+3. Split suggestion if the change should be multiple commits
 
 ## Gotcha
 
-- Model overuses `chore`/`refactor` — classify by intent, not effort
-- File type ≠ commit type (`.md` change can be `feat`)
-- `refactor` = NO behavior change — if behavior changes, use `feat`/`fix`
-- Squash title = net effect, not internal details
+- The model tends to overuse `chore` and `refactor` — classify by intent, not by effort
+- File type alone does not determine commit type (e.g. a `.md` change can be `feat` if it's a new feature doc)
+- Squash merge titles should describe the net effect, not every internal detail
+- `refactor` means NO behavior change — if behavior changes, use `feat` or `fix`
 
 ## Do NOT
 
@@ -65,6 +123,6 @@ Read all PR commits → identify net effect → write single Conventional Commit
 
 ## References
 
-- Rule: `commit-conventions` — format, types, scope
-- Guideline: `docs/guidelines/php/git.md` — selection rules, anti-patterns, checklist
-- Command: `/commit` — uses this skill
+- Rule: `commit-conventions` — base format, types, scope, examples
+- Guideline: `docs/guidelines/php/git.md` — type selection rules, anti-patterns, decision checklist
+- Command: `/commit` — uses this skill for message generation

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -27,12 +27,12 @@ Do NOT use when:
 
 ### 0. Analyze current state
 
-Before changing anything:
+Before changing anything, read and understand:
 
-1. Read `AGENTS.md` — content, line count, what's duplicated vs. unique
-2. Read `.github/copilot-instructions.md` — same analysis
-3. Scan `.augment/` — which skills/rules already cover topics from above
-4. Identify duplication — what exists in both AGENTS.md and `.augment/`?
+1. **Read `AGENTS.md`** — current content, line count, what's duplicated vs. unique.
+2. **Read `.github/copilot-instructions.md`** — same analysis.
+3. **Scan `.augment/`** — which skills, rules, and guidelines already cover topics from the files above.
+4. **Identify duplication** — what content exists in both AGENTS.md and `.augment/`?
 
 Only after this analysis, proceed with optimization.
 

package/.agent-src/skills/developer-like-execution/SKILL.md

@@ -129,10 +129,10 @@ If important information is missing:
 - **Consult memory — invariants and prior decisions.** Via
   [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md), call
   `retrieve(types=["domain-invariants", "architecture-decisions"], keys=<touched paths>, limit=3)`.
-  A matching `domain-invariant` is a hard constraint — violating it =
-  regression, surface the conflict before proceeding. A matching
-  `architecture-decision` explains *why* the current shape exists; plan
-  around it, do not silently overturn it. Cite matching `id`s in the plan.
+  A matching `domain-invariant` is a hard constraint — violating it = regression,
+  surface the conflict to the user before proceeding. A matching
+  `architecture-decision` explains *why* the current shape exists; plan around
+  it, do not silently overturn it. Cite matching `id`s in the plan.
   See [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
   for the schema.