@event4u/agent-config 1.9.1

package/.agent-src/commands/feature-roadmap.md

@@ -0,0 +1,184 @@
+---
+name: feature-roadmap
+skills: [agent-docs-writing]
+description: Generate implementation roadmap(s) from a feature plan and link them
+disable-model-invocation: true
+---
+
+# feature-roadmap
+
+## Instructions
+
+### 1. Find the feature
+
+- List feature plans in `agents/features/`.
+- Also check module-level `app/Modules/*/agents/features/`.
+
+If the user specified a feature name, load it directly.
+Otherwise show a list and ask:
+
+```
+📂 Feature plans:
+
+  #  Name                              Status
+  ─  ──────────────────────────────    ──────
+  1  import-csv-validation.md          📋 Planned
+  2  webhook-retry-logic.md            📋 Planned
+
+Which feature should get a roadmap?
+```
+
+If no features exist or all are `💡 Idea`:
+```
+⚠️  No feature ready for a roadmap.
+Create a plan first with /feature-plan or refine with /feature-refactor.
+```
+Stop.
+
+### 2. Analyze the feature
+
+- Read the feature file completely.
+- Read `agents/roadmaps/template.md` for the roadmap structure.
+- Research the codebase for affected areas mentioned in the feature.
+
+Determine how many roadmaps are needed:
+
+- **Single roadmap:** Small/medium features that fit in one document.
+- **Multiple roadmaps:** Large features that span multiple phases or modules.
+
+```
+I've analyzed the feature:
+
+📄 {feature title}
+📐 Scope: {scope summary}
+🔧 Affected areas: {modules, models, services}
+
+───────────────────────────────────────────────
+ROADMAP PROPOSAL:
+───────────────────────────────────────────────
+
+{Option A: Single roadmap}
+  📄 agents/roadmaps/{feature-name}.md
+  Phasen: {phase count}
+  Estimated effort: {rough estimate}
+
+{Option B: Multiple roadmaps — only if feature is large}
+  📄 agents/roadmaps/{feature-name}-database.md (Schema & Migrations)
+  📄 agents/roadmaps/{feature-name}-backend.md (Services, API)
+  📄 agents/roadmaps/{feature-name}-frontend.md (UI, if applicable)
+
+Which fits better? Or do you have a different breakdown in mind?
+```
+
+### 3. Plan the phases
+
+For each roadmap, work through the phases interactively:
+
+**Phase planning questions:**
+- "What order makes sense? I suggest: {order}"
+- "Soll {X} ein eigener Schritt sein oder Teil von {Y}?"
+- "Are there dependencies between the steps?"
+
+**Use codebase knowledge:**
+- Reference specific files that need changes.
+- Identify existing patterns to follow.
+- Flag potential conflicts with other work.
+
+**Phase structure per roadmap step:**
+```markdown
+### Phase {N}: {title}
+
+- [ ] {concrete task with file reference}
+- [ ] {concrete task}
+- [ ] Tests: {what to test}
+- [ ] Quality: PHPStan + Rector
+```
+
+### 4. Generate the roadmap(s)
+
+- Read `.augment/templates/roadmaps.md` for the format.
+- Determine the target directory from the feature's location:
+  - Feature in `agents/features/` → roadmap in `agents/roadmaps/`
+  - Feature in `app/Modules/{Module}/agents/features/` → roadmap in `app/Modules/{Module}/agents/roadmaps/`
+- Create the target directory if it doesn't exist.
+
+**Naming convention:**
+- Single: `agents/roadmaps/{feature-name}.md`
+- Multiple: `agents/roadmaps/{feature-name}-{aspect}.md`
+
+### 5. Link roadmaps in the feature plan
+
+Update the feature file's `## Roadmaps` section:
+
+```markdown
+## Roadmaps
+
+- [`agents/roadmaps/{feature-name}.md`](../roadmaps/{feature-name}.md) — Main implementation roadmap
+```
+
+Or for multiple:
+```markdown
+## Roadmaps
+
+- [`agents/roadmaps/{name}-database.md`](../roadmaps/{name}-database.md) — Schema & Migrations
+- [`agents/roadmaps/{name}-backend.md`](../roadmaps/{name}-backend.md) — Services & API
+- [`agents/roadmaps/{name}-frontend.md`](../roadmaps/{name}-frontend.md) — UI Components
+```
+
+Update the feature status to `🗺️ Roadmapped`.
+
+### 6. Show the result
+
+```
+═══════════════════════════════════════════════
+  🗺️ ROADMAP(S) CREATED
+═══════════════════════════════════════════════
+
+Feature: {title}
+Status:  🗺️ Roadmapped
+
+───────────────────────────────────────────────
+DATEIEN:
+───────────────────────────────────────────────
+
+  📄 agents/roadmaps/{name}.md ({phase count} Phasen)
+  📄 agents/features/{name}.md (status updated, roadmaps linked)
+
+───────────────────────────────────────────────
+PHASE OVERVIEW:
+───────────────────────────────────────────────
+
+  Phase 1: {title} — {summary}
+  Phase 2: {title} — {summary}
+  Phase 3: {title} — {summary}
+
+═══════════════════════════════════════════════
+```
+
+### 7. Next steps
+
+```
+What's next?
+
+1. 🚀 Start with Phase 1
+2. ✏️ Adjust roadmap
+3. ✅ Done for now
+```
+
+- **Option 1:** Start Phase 1 using the roadmap context.
+- **Option 2:** Discuss changes and update the roadmap.
+- **Option 3:** Done.
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Do NOT modify the feature plan** beyond updating the Roadmaps section and status.
+- **Always link roadmaps back to the feature** and vice versa.
+- **Use the roadmap template** from `agents/roadmaps/template.md`.
+- **Reference specific files** in roadmap tasks — not vague descriptions.
+- **Include quality gates** (PHPStan, Rector, tests) in every phase.
+- **Research the codebase** to make tasks concrete and realistic.
+
+## See also
+
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#planner) — Planner mode output contract (Goal / Constraints / Option set / Recommendation / Dependencies / Rollback)

package/.agent-src/commands/fix-ci.md

@@ -0,0 +1,48 @@
+---
+name: fix-ci
+skills: [github-ci, quality-tools]
+description: Fetch CI errors from GitHub Actions and fix them
+disable-model-invocation: true
+---
+
+# fix-ci
+
+## Instructions
+
+### 1. Identify the failing CI run
+
+- Get the current branch name from `git branch --show-current`.
+- Fetch the latest CI run for this branch via GitHub API:
+  - `GET /repos/{owner}/{repo}/actions/runs?branch={branch}&per_page=5`
+- Find the most recent failed run.
+
+### 2. Get the failure details
+
+- Fetch the jobs for the failed run: `GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs`
+- For each failed job, fetch the logs: `GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs`
+- If logs are not available via API, check the check-runs and status endpoints:
+  - `GET /repos/{owner}/{repo}/commits/{sha}/check-runs`
+  - `GET /repos/{owner}/{repo}/commits/{sha}/status`
+
+### 3. Analyze and fix
+
+- Parse the error output to identify the root cause.
+- Detect the project type: if `artisan` exists → Laravel, otherwise → Composer (see `rules/docker-commands.md`).
+- Common CI failures:
+  - **PHPStan errors** — fix the code, do NOT add to baseline or ignoreErrors.
+  - **ECS (coding standard) errors** — run `vendor/bin/ecs check --fix` (auto-fix).
+  - **Rector changes** — run `vendor/bin/rector process` (auto-fix).
+  - **Test failures** — read the failing test, understand the assertion, fix the code or test.
+  - **Biome / TypeScript errors** — run `npm run biome:fix` or `npm run tscheck` and fix.
+- Fix errors in the local codebase.
+
+### 4. Verify
+
+- Re-run the failing tool locally (inside the PHP container) to confirm the fix.
+- If multiple tools failed, fix and verify each one.
+
+### Rules
+
+- **Do NOT commit or push.** Only apply local fixes.
+- **Do NOT skip or ignore errors** — fix the root cause.
+- If a fix is unclear, explain the error and ask the user for guidance.

package/.agent-src/commands/fix-portability.md

@@ -0,0 +1,97 @@
+---
+name: fix-portability
+description: Find and fix project-specific references in shared .augment/ package files
+disable-model-invocation: true
+---
+
+# fix-portability
+
+## Instructions
+
+### 1. Run the portability checker
+
+```bash
+python3 scripts/check_portability.py --format json
+```
+
+### 2. Parse findings
+
+If output is `[]` or "No portability violations found":
+
+```
+✅  No portability violations found. Package is project-agnostic.
+```
+
+Stop here.
+
+### 3. Display findings
+
+```
+═══════════════════════════════════════════════
+  📦 PORTABILITY VIOLATION REPORT
+═══════════════════════════════════════════════
+
+  Found: {count} violation(s)
+```
+
+Group by severity:
+
+```
+  🔴 ERRORS (must fix):
+    {file}:{line} — pattern: `{pattern}` — match: `{matched_text}`
+
+  🟡 WARNINGS (should fix):
+    {file}:{line} — pattern: `{pattern}` — match: `{matched_text}`
+```
+
+### 4. Classify and fix
+
+For each violation:
+
+| Pattern Type | Fix Strategy |
+|---|---|
+| Project name (e.g., "MyApp", "acme-corp") | Replace with generic placeholder: `{project}`, `{app}` |
+| Project-specific URL/domain | Replace with `https://example.com` or `{domain}` |
+| Database name | Replace with `{database}` |
+| Project-specific env var | Replace with generic `APP_*` equivalent |
+| Project-specific path | Replace with relative or generic path |
+| Docker container name | Replace with `{container}` |
+
+Present a summary:
+
+```
+  Proposed fixes:
+  1. {file}:{line} — `{old}` → `{new}`
+  2. {file}:{line} — `{old}` → `{new}`
+
+> 1. Apply all fixes
+> 2. Apply interactively
+> 3. Skip — report only
+```
+
+### 5. Apply fixes
+
+Edit files in `.agent-src.uncompressed/`, then run `task sync` to regenerate `.agent-src/` and `.augment/`.
+
+After all fixes, re-run:
+
+```bash
+python3 scripts/check_portability.py
+```
+
+### 6. Mark hashes
+
+For each modified file:
+
+```bash
+python3 scripts/compress.py --mark-done "{relative_path}"
+```
+
+## Rules
+
+- **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
+- **Run `task sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Do NOT commit or push.**
+- **`agents/` directory is allowed** to have project-specific references — skip it.
+- **Do NOT fix references in code blocks** unless the code block is clearly a template.
+- **Run the checker again after fixing** to verify 0 remaining issues.

package/.agent-src/commands/fix-pr-bot-comments.md

@@ -0,0 +1,146 @@
+---
+name: fix-pr-bot-comments
+skills: [php-coder, quality-tools]
+description: Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR
+disable-model-invocation: true
+---
+
+# fix-pr-bot-comments
+
+## Input
+
+The user may or may not provide a PR URL.
+
+### PR detection
+
+1. If the user provides a GitHub PR URL → use that PR.
+2. If no URL is provided → **try to detect the PR automatically:**
+   - Determine the current Git branch (`git branch --show-current`).
+   - Search for an open PR on that branch via the GitHub API
+     (`GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&state=open`).
+   - If exactly one PR is found → tell the user: "I found PR #{number} ({title}) on branch `{branch}`. Is that the one?"
+   - Wait for confirmation before proceeding.
+   - If no PR or multiple PRs are found → ask the user for the PR URL.
+3. **Never** reuse a PR number from earlier in the conversation.
+
+## Mode selection
+
+After the PR is confirmed, ask the user (use numbered options per `user-interaction` rule):
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+- **Option 1** → follow the "Interactive flow" below.
+- **Option 2** → follow the "Auto flow" below.
+
+## Bot detection
+
+A comment is from a **bot** if the GitHub user has `type: "Bot"` or the login matches
+known bot accounts: `Copilot`, `github-actions[bot]`, `greptile[bot]`, `augment[bot]`,
+or any login ending in `[bot]`.
+
+## Instructions (shared)
+
+1. **Fetch all review comments** from the PR using the GitHub API (`/pulls/{number}/comments`).
+   Use `per_page: 100`. Filter for **bot comments** that have **no reply yet** from a human user.
+
+2. **For each unresolved bot comment**, read the affected file and surrounding context
+   to understand the code and the suggestion.
+
+3. **Report the total count** to the user: "Found X unresolved bot comments."
+
+---
+
+## Interactive flow
+
+For each comment, present it to the user **before** taking action:
+
+### 1. Summarize the comment
+
+In the **user's language**, briefly explain:
+- Which file/line is affected
+- What the bot is suggesting
+- Your assessment: is it valid, partially valid, or not applicable?
+
+### 2. Offer options
+
+Present numbered options. Always include a "leave as-is" option. Examples:
+
+**If there's one clear fix:**
+> **Comment 1/3** — `WorkingTimeService.php:108`
+> Bot says: The guard condition only checks `job_start`, but the comment also mentions `job_stop`.
+>
+> 1. Fix the comment (only mention `job_start`)
+> 2. Extend the guard condition (also check `job_stop`)
+> 3. Leave as-is, dismiss comment
+
+**If there are multiple valid approaches:**
+> **Comment 2/3** — `AbsencePlannerService.php:520`
+> Bot says: When an exception occurs mid-loop, log entries are missing.
+>
+> 1. `writeLogBulk()` in einen `finally`-Block verschieben
+> 2. Die gesamte Schleife in eine DB-Transaction wrappen
+> 3. Leave as-is, dismiss comment
+
+### 3. Wait for the user's choice
+
+- Do NOT proceed until the user picks an option.
+- If the user asks a follow-up question, answer it before proceeding.
+- After the user chooses, apply the fix (or skip) and reply on GitHub.
+
+### 4. Move to the next comment
+
+Repeat until all comments are handled.
+
+---
+
+## Auto flow
+
+Process all comments without asking. For each comment:
+
+1. Analyze whether the suggestion is valid.
+2. **If valid** — fix it and reply on GitHub.
+3. **If not valid** — reply on GitHub explaining why, do NOT change the code.
+
+---
+
+## Common patterns to watch for
+
+- **Duplicate PHPDoc tags** → fix by keeping the more specific/typed version.
+- **Split PHPDoc blocks** → merge into a single docblock.
+- **Wrong PHPDoc tag order** → `@param` before `@return` before `@throws`.
+- **Conflicting PHPDoc types** → remove incorrect PHPDoc, trust the method signature.
+- **Broad ignore patterns / intentional config** → reply explaining rationale, don't change.
+- **Validation/logic bugs** → fix the code.
+
+## Reply style — write like a human developer, not an AI
+
+- The GitHub API token authenticates as the PR author. Write replies as if you ARE the developer.
+- Keep it casual, short, and natural. Like a real dev replying to a code review.
+- Vary your wording — never use the same opening phrase twice in a row.
+- Don't over-explain. A dev who fixed something doesn't write a paragraph about it.
+- Good examples: `"Good catch, fixed."`, `"Yep, consolidated into one docblock now."`,
+  `"Removed the duplicate 👍"`, `"That's intentional — [reason]"`
+- Never start multiple replies with "Fixed". Mix it up: "Done", "Good catch", "Yep", etc.
+
+### Bot icon prefix
+
+Read `project.pr_comment_bot_icon` from `.agent-settings.yml`. If `true` (default),
+prefix every reply with `🤖 ` so reviewers can see at a glance that the reply was
+bot-authored.
+
+Example: `🤖 Good catch, fixed.`
+
+If `false` or `.agent-settings.yml` doesn't exist, do NOT add the prefix.
+
+## Replying via GitHub API
+
+Read `github.pr_reply_method` from `.agent-settings.yml` to determine the correct endpoint.
+See the `command-routing` skill → "GitHub API: Replying to PR review comments" for full details.
+
+## After all comments
+
+1. Run a PHP syntax check (`php -l`) on all modified files to verify nothing is broken.
+2. **Do NOT commit or push.** Just apply the fixes locally and reply to all comments on GitHub.

package/.agent-src/commands/fix-pr-comments.md

@@ -0,0 +1,58 @@
+---
+name: fix-pr-comments
+skills: [php-coder]
+description: Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
+disable-model-invocation: true
+---
+
+# fix-pr-comments
+
+This command runs `fix-pr-bot-comments` and `fix-pr-developer-comments` in sequence on the same PR.
+
+## Input
+
+The user may or may not provide a PR URL.
+
+### PR detection
+
+1. If the user provides a GitHub PR URL → use that PR.
+2. If no URL is provided → **try to detect the PR automatically:**
+   - Determine the current Git branch (`git branch --show-current`).
+   - Search for an open PR on that branch via the GitHub API
+     (`GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&state=open`).
+   - If exactly one PR is found → tell the user: "I found PR #{number} ({title}) on branch `{branch}`. Is that the one?"
+   - Wait for confirmation before proceeding.
+   - If no PR or multiple PRs are found → ask the user for the PR URL.
+3. **Never** reuse a PR number from earlier in the conversation.
+
+## Mode selection
+
+After the PR is confirmed, ask the user:
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+The chosen mode applies to **both** phases.
+
+## Execution
+
+### Phase 1: Bot comments
+
+Follow the full `fix-pr-bot-comments` instructions (see `.augment/commands/fix-pr-bot-comments.md`).
+Use the already-confirmed PR and mode — do not ask again.
+
+Report when done: "Bot comments done. Continuing with reviewer comments..."
+
+### Phase 2: Developer comments
+
+Follow the full `fix-pr-developer-comments` instructions (see `.augment/commands/fix-pr-developer-comments.md`).
+Use the same PR and mode.
+
+### After both phases
+
+1. Run a PHP syntax check (`php -l`) on all modified files to verify nothing is broken.
+2. Report a final summary: how many bot comments handled, how many developer comments handled,
+   how many files modified.
+3. **Do NOT commit or push.** Just apply the fixes locally and reply to all comments on GitHub.

package/.agent-src/commands/fix-pr-developer-comments.md

@@ -0,0 +1,152 @@
+---
+name: fix-pr-developer-comments
+skills: [php-coder]
+description: Fix and reply to human reviewer comments on a GitHub PR
+disable-model-invocation: true
+---
+
+# fix-pr-developer-comments
+
+## Input
+
+The user may or may not provide a PR URL.
+
+### PR detection
+
+1. If the user provides a GitHub PR URL → use that PR.
+2. If no URL is provided → **try to detect the PR automatically:**
+   - Determine the current Git branch (`git branch --show-current`).
+   - Search for an open PR on that branch via the GitHub API
+     (`GET /repos/{owner}/{repo}/pulls?head={owner}:{branch}&state=open`).
+   - If exactly one PR is found → tell the user: "I found PR #{number} ({title}) on branch `{branch}`. Is that the one?"
+   - Wait for confirmation before proceeding.
+   - If no PR or multiple PRs are found → ask the user for the PR URL.
+3. **Never** reuse a PR number from earlier in the conversation.
+
+## Mode selection
+
+After the PR is confirmed, ask the user (use numbered options per `user-interaction` rule):
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+- **Option 1** → follow the "Interactive flow" below.
+- **Option 2** → follow the "Auto flow" below.
+
+## Human reviewer detection
+
+A comment is from a **human reviewer** if:
+- The GitHub user `type` is `"User"` (not `"Bot"`).
+- The login does NOT end in `[bot]`.
+- The user is NOT the PR author (don't process your own comments).
+
+## Instructions (shared)
+
+1. **Fetch all review comments** from the PR using the GitHub API (`/pulls/{number}/comments`).
+   Use `per_page: 100`. Also fetch **PR reviews** (`/pulls/{number}/reviews`) for top-level
+   review comments. Filter for **human reviewer comments** that have **no reply yet** from the PR author.
+
+2. **For each unresolved reviewer comment**, read the affected file and surrounding context
+   to understand the code and what the reviewer is asking for.
+
+3. **Report the total count** to the user: "Found X unresolved reviewer comments."
+
+---
+
+## Interactive flow
+
+For each comment, present it to the user **before** taking action:
+
+### 1. Summarize the comment
+
+In the **user's language**, briefly explain:
+- Who wrote the comment (reviewer name/login)
+- Which file/line is affected
+- What the reviewer is requesting or asking
+- Your assessment: is it a valid concern, a question, a style preference, or a misunderstanding?
+
+### 2. Offer options
+
+Present numbered options. Always include a "skip" option. Adapt options to the comment type:
+
+**For a change request:**
+> **Comment 1/3** — @cjost1988 in `WorkingTimeService.php:108`
+> Reviewer asks: Why is the fallback `float`? `$time` is `$hours * 60`.
+>
+> 1. Reply and explain why (no code change needed)
+> 2. Adjust type annotation to `float|int|string`
+> 3. Skip
+
+**For a bug report:**
+> **Comment 2/3** — @cjost1988 in `AbsencePlannerService.php:520`
+> Reviewer says: Race condition when two requests book simultaneously.
+>
+> 1. Add locking mechanism (DB lock or cache lock)
+> 2. Reply: not relevant in current scope, create a ticket
+> 3. Skip
+
+**For a question (no code change needed):**
+> **Comment 3/3** — @cjost1988 in `KS21Client.php:42`
+> Reviewer asks: Is this fallback ever reached?
+>
+> 1. Reply with explanation
+> 2. Skip
+
+### 3. Wait for the user's choice
+
+- Do NOT proceed until the user picks an option.
+- If the user wants to write a custom reply, let them dictate the text.
+- If the user asks a follow-up question, answer it before proceeding.
+- After the user chooses, apply the fix (or reply) and post on GitHub.
+
+### 4. Move to the next comment
+
+Repeat until all comments are handled.
+
+---
+
+## Auto flow
+
+Process all comments without asking. For each comment:
+
+1. Analyze what the reviewer is requesting.
+2. **If it's a clear code fix** — fix it and reply on GitHub.
+3. **If it's a question** — reply with a concise explanation on GitHub.
+4. **If it's ambiguous or a design decision** — flag it to the user instead of guessing.
+   In auto mode, collect these and present them at the end: "These comments need your decision: ..."
+
+---
+
+## Reply style — write like a human developer, not an AI
+
+- The GitHub API token authenticates as the PR author. Write replies as if you ARE the developer.
+- Keep it casual, short, and natural. Like a real dev replying to a code review.
+- Vary your wording — never use the same opening phrase twice in a row.
+- For reviewer questions: answer directly and concisely. Don't over-explain.
+- For fixes: confirm briefly what was changed.
+- Be respectful — these are colleagues, not bots. Don't dismiss feedback.
+- Good examples: `"Good point, fixed."`, `"Yep, that was a leftover — removed."`,
+  `"The fallback covers legacy data where getTime() returns a string."`
+- Never start multiple replies with the same phrase. Mix it up naturally.
+
+### Bot icon prefix
+
+Read `project.pr_comment_bot_icon` from `.agent-settings.yml`. If `true` (default),
+prefix every reply with `🤖 ` so reviewers can see at a glance that the reply was
+bot-authored.
+
+Example: `🤖 Good point, fixed.`
+
+If `false` or `.agent-settings.yml` doesn't exist, do NOT add the prefix.
+
+## Replying via GitHub API
+
+Read `github.pr_reply_method` from `.agent-settings.yml` to determine the correct endpoint.
+See the `command-routing` skill → "GitHub API: Replying to PR review comments" for full details.
+
+## After all comments
+
+1. Run a PHP syntax check (`php -l`) on all modified files to verify nothing is broken.
+2. **Do NOT commit or push.** Just apply the fixes locally and reply to all comments on GitHub.