@event4u/agent-config 1.9.1

package/.agent-src/commands/agents-prepare.md

@@ -0,0 +1,137 @@
+---
+name: agents-prepare
+skills: [agent-docs-writing]
+description: Scaffold the agents/ directory structure with all required subdirectories and .gitkeep files
+disable-model-invocation: true
+---
+
+# agents-prepare
+
+## Instructions
+
+### 1. Check project root
+
+Verify you're in the project root (look for `composer.json`, `artisan`, or `package.json`).
+
+### 2. Create directory structure
+
+Create the following directories if they don't exist, with a `.gitkeep` in each **empty** directory:
+
+```
+agents/
+├── roadmaps/
+│   └── .gitkeep
+├── features/
+│   └── .gitkeep
+└── contexts/
+    └── .gitkeep
+```
+
+Also create the guidelines directory in `.augment/` if it doesn't exist:
+
+```
+.augment/guidelines/
+└── php/
+    └── .gitkeep
+```
+
+**Rules:**
+- Only add `.gitkeep` to directories that have **no other files** in them.
+- Do NOT overwrite existing files.
+- Do NOT create directories that already exist with content.
+
+### 3. Check for module support
+
+Check if the project has a module system (`app/Modules/` directory):
+
+- If `app/Modules/` exists → list all modules.
+- For each module, create the agent directories if they don't exist:
+
+```
+app/Modules/{Module}/agents/
+├── roadmaps/
+│   └── .gitkeep
+├── features/
+│   └── .gitkeep
+├── contexts/
+│   └── .gitkeep
+```
+
+### 4. Verify templates exist
+
+Check that `.augment/templates/` contains the required templates:
+
+```
+.augment/templates/
+├── features.md    # Feature plan template
+├── roadmaps.md    # Roadmap template
+└── contexts.md    # Context document template
+```
+
+If any template is missing, warn:
+
+```
+⚠️  Missing templates in .augment/templates/:
+  - {missing-file}
+
+These templates are required by the Feature/Roadmap commands.
+```
+
+### 5. Clean up old templates
+
+Check for **old template files** in the agents directories and offer to remove them:
+
+```
+agents/features/template.md
+agents/roadmaps/template.md
+app/Modules/*/agents/roadmaps/template.md
+app/Modules/*/agents/features/template.md
+```
+
+If any are found:
+
+```
+ℹ️  Old template files found (now in .augment/templates/):
+
+  - agents/features/template.md
+  - agents/roadmaps/template.md
+
+Delete these? (y/n)
+```
+
+If yes → delete them.
+
+### 6. Show summary
+
+```
+═══════════════════════════════════════════════
+  ✅  AGENTS-VERZEICHNIS VORBEREITET
+═══════════════════════════════════════════════
+
+📁 Projekt-Root:
+  agents/roadmaps/     {✅ existiert | 🆕 erstellt}
+  agents/features/     {✅ existiert | 🆕 erstellt}
+  .augment/guidelines/ {✅ existiert | 🆕 erstellt}
+
+📁 Templates:
+  .augment/templates/features.md   {✅ | ⚠️ fehlt}
+  .augment/templates/roadmaps.md   {✅ | ⚠️ fehlt}
+
+{If modules exist:}
+📁 Module:
+  {Module}/agents/roadmaps/   {✅ | 🆕}
+  {Module}/agents/features/   {✅ | 🆕}
+  ...
+
+{If old templates were cleaned up:}
+🗑️  Old templates removed: {count}
+
+═══════════════════════════════════════════════
+```
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Do NOT overwrite existing files.**
+- **Do NOT create `.gitkeep` in directories that already have files.**
+- **Always ask before deleting** old template files.

package/.agent-src/commands/analyze-reference-repo.md

@@ -0,0 +1,191 @@
+---
+name: analyze-reference-repo
+skills: [project-analyzer, learning-to-rule-or-skill]
+description: Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project.
+disable-model-invocation: true
+---
+
+# analyze-reference-repo
+
+Analyze a **different** repository (a competitor, a reference implementation, or a
+project the user admires) and produce a structured document that:
+
+- maps what the reference does well,
+- compares it against **this** project,
+- classifies each finding (adopt / adapt / reject / already-have),
+- proposes concrete adoption items,
+- optionally generates a roadmap draft for the adopt items.
+
+**Not** for analyzing the current project — use `/project-analyze` for that.
+**Not** for importing external skills wholesale — out of scope for this
+package; fork the reference repo or maintain the content in your own.
+
+## Inputs
+
+The user provides a repository URL. Accept:
+
+- Full GitHub URL (`https://github.com/owner/repo`)
+- `owner/repo` shorthand
+- A raw archive URL (zip/tar) for private or mirrored repos
+
+Optional arguments:
+
+- `--focus=<area>` — restrict analysis to one axis (e.g. `installer`,
+  `skills`, `mcp`, `governance`, `ci`). Default: full-surface.
+- `--no-roadmap` — skip the roadmap-draft step.
+
+## Steps
+
+### 1. Confirm scope
+
+Before touching anything, ask:
+
+> Found reference: `<owner/repo>`.
+>
+> 1. Full comparison — all axes (default)
+> 2. Focused — one axis (I'll ask which)
+> 3. Quick scan — README + top-level layout only
+> 4. Cancel
+
+Wait for the user's choice.
+
+### 2. Fetch the reference surface
+
+Do **not** clone or execute the target repo. Fetch only:
+
+- `README.md`, `AGENTS.md`, `CHANGELOG.md`, `LICENSE`
+- `package.json` / `composer.json` / `pyproject.toml` / `Cargo.toml`
+- Top-level file listing (1 level deep)
+- One level of key directories: `docs/`, `scripts/`, `commands/`, `skills/`,
+  `rules/`, `.github/workflows/`
+- Any file the README explicitly points to
+
+Use `web-fetch` for rendered files, GitHub REST
+(`/repos/{o}/{r}/contents/{p}`) for listings. **Max 40 fetches** — if more is
+needed, ask which subtree to expand.
+
+### 3. Extract structured facts
+
+For each axis, record **one line** of verified fact or "not found":
+
+| Axis | What to capture |
+|---|---|
+| **Distribution** | How is it installed? (npm global / composer / pip / manual) |
+| **Scope** | User-scoped, project-scoped, both? |
+| **Skill model** | What is a "skill" here? Folder shape, frontmatter, size? |
+| **Rule model** | How are rules triggered? Auto / manual / always-on? |
+| **Installer** | One script or many? Idempotent? Uninstall? |
+| **Multi-tool** | Which AI tools are supported? How is the output generated? |
+| **MCP** | MCP server config generation? Secret handling? |
+| **Governance** | Linters? Size limits? Quality gates? |
+| **External sources** | Can users add third-party skills? |
+| **CI** | Auto-sync? Quality checks? Release automation? |
+| **Docs** | README structure, examples, architecture docs |
+| **Community** | Contribution docs, maintainers, license, activity |
+
+Reject anything you cannot verify from the fetched files — write "not found"
+rather than guess.
+
+### 4. Compare against this project
+
+Add a **this-repo** column per axis. Sources of truth:
+`.agent-src.uncompressed/` (skills/rules/commands), `docs/architecture.md`
+(stable/experimental), `scripts/` (installer), `.github/workflows/` (CI).
+Never invent capabilities — if we don't have it, say so.
+
+### 5. Classify every finding
+
+One label per row:
+
+| Label | Meaning |
+|---|---|
+| **ADOPT** | Clear win. Implement. |
+| **ADAPT** | Good idea, must fit our governance. |
+| **REJECT** | Conflicts with our principles. |
+| **ALREADY** | We already have it (possibly better). |
+| **UNCLEAR** | Needs human judgement — flag. |
+
+ADOPT/ADAPT rows must cite the reference source (file/line/URL).
+
+### 6. Write the analysis document
+
+Target: `agents/analysis/compare-<slug>.md`.
+Slug rule: `<owner>-<repo>` lowercased, non-alphanumeric → `-`, collapse runs.
+
+Document structure (copy into the file):
+
+```markdown
+# Reference analysis: {owner}/{repo}
+
+> One-sentence framing of why this reference matters.
+
+- **Source:** https://github.com/{owner}/{repo}
+- **Fetched commit:** {sha} ({date})
+- **Focus:** {full | area}
+- **Analyst:** agent via `/analyze-reference-repo`
+
+## TL;DR
+
+- Top 3 things to ADOPT
+- Top 3 things to REJECT (and why)
+- Top 3 things we ALREADY do better
+
+## Comparison matrix
+
+| Axis | Reference | This repo | Label | Notes |
+|---|---|---|---|---|
+
+## Findings
+
+### ADOPT
+### ADAPT
+### REJECT
+### ALREADY
+### UNCLEAR
+
+## Proposed roadmap items
+
+{Only if --no-roadmap was not set.}
+
+## Open questions for the maintainer
+```
+
+### 7. Offer next steps
+
+After writing the file, present:
+
+> Analysis written to `agents/analysis/compare-{slug}.md`.
+>
+> 1. Draft roadmap from ADOPT/ADAPT — `agents/roadmaps/adopt-{slug}.md`
+> 2. Merge findings into an existing roadmap — say which
+> 3. Stop here
+> 4. Deep-dive on one axis — say which
+
+Never create the roadmap without explicit confirmation.
+
+## Output location
+
+`agents/analysis/` (create if missing, with `.gitkeep`). Same convention as
+`project-analyzer`.
+
+## Safety
+
+- Read-only on the reference. Never clone, execute, or submit PRs to it.
+- No credentials in fetches. Public GitHub API is enough. For private mirrors,
+  take a PAT via env var and never echo it.
+- Max 40 fetches without explicit extension.
+- No auto-commits — the analysis is a draft until the user accepts.
+
+## When **not** to use
+
+- Analyzing the current repo → `/project-analyze`.
+- Importing external skills wholesale → out of scope; fork or maintain your own.
+- Security audit of a dependency → `security-audit` skill.
+- Framework migration → `project-analysis-*` skill family.
+
+## Related
+
+- Skill: `project-analyzer` — base analysis workflow.
+- Skill: `learning-to-rule-or-skill` — turn adopt items into content.
+- Skill: `upstream-contribute` — push learnings back to this package.
+- Roadmaps: `agents/roadmaps/` — consumers of findings (e.g. `archive/road-to-anthropic-alignment.md`).

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

@@ -0,0 +1,181 @@
+---
+name: bug-fix
+skills: [bug-analyzer, pest-testing]
+description: Plan and implement a bug fix — based on investigation, with quality checks and test verification
+disable-model-invocation: true
+---
+
+# bug-fix
+
+## Instructions
+
+### 1. Check for prior investigation
+
+- Check if `/bug-investigate` was run in this conversation (context should be loaded).
+- If not, ask:
+
+```
+⚠️  Has the bug already been analyzed?
+
+1. Yes — I have the context from the previous analysis
+2. No — run /bug-investigate first
+3. I already know the root cause — start fixing directly
+```
+
+If option 3, ask for a brief description of the root cause and affected files.
+
+### 2. Plan the fix
+
+Based on the root cause analysis, create a fix plan:
+
+```
+═══════════════════════════════════════════════
+  🔧 FIX-PLAN
+═══════════════════════════════════════════════
+
+🐛 Bug:    {brief description}
+📍 Ursache: {root cause}
+🎫 Ticket:  {ticket ID or "none"}
+
+───────────────────────────────────────────────
+CHANGES:
+───────────────────────────────────────────────
+
+1. 📁 {file1.php}
+   → {what to change and why}
+
+2. 📁 {file2.php}
+   → {what to change and why}
+
+3. 🧪 Tests
+   → {which tests to add/update}
+
+───────────────────────────────────────────────
+RISIKO-CHECK:
+───────────────────────────────────────────────
+
+  Side effects:     {potential side effects}
+  Similar spots:    {other code that might need the same fix}
+  Migration needed: {yes/no}
+  Breaking change:  {yes/no}
+
+═══════════════════════════════════════════════
+
+> 1. Yes — start implementing
+> 2. No — adjust the plan
+> 3. Cancel
+```
+
+### 3. Implement the fix
+
+For each change:
+
+1. **Read the file** before modifying.
+2. **Make the change** using `str-replace-editor`.
+3. **Check for downstream effects** — use `codebase-retrieval` to find callers.
+4. **Update related code** if signatures or behavior changed.
+
+### 4. Quality checks
+
+After all changes, run quality tools:
+
+```bash
+vendor/bin/phpstan analyse           # 1. Check for type errors
+vendor/bin/rector process            # 2. Auto-fix refactoring
+vendor/bin/ecs check --fix           # 3. Auto-fix code style
+vendor/bin/phpstan analyse           # 4. Re-check after Rector/ECS
+```
+
+Show results and fix any issues.
+
+### 5. Tests
+
+Check for existing tests that cover the affected code:
+
+```
+🧪 Existing tests:
+  • {TestFile}::{testMethod} — {what it tests}
+  • ...
+
+> 1. Run these tests
+> 2. Write new tests for the fix
+> 3. Both
+> 4. Skip tests for now
+```
+
+- **Run affected tests** to verify the fix doesn't break anything.
+- **Write new tests** if the bug scenario isn't covered.
+- **Run all tests** at the end.
+
+### 6. Show result
+
+```
+═══════════════════════════════════════════════
+  ✅  FIX IMPLEMENTED
+═══════════════════════════════════════════════
+
+🐛 Bug:        {description}
+🎫 Ticket:     {ticket ID}
+
+───────────────────────────────────────────────
+CHANGES:
+───────────────────────────────────────────────
+
+  ✏️  {file1.php} — {summary of change}
+  ✏️  {file2.php} — {summary of change}
+  🧪 {TestFile.php} — {new/updated test}
+
+───────────────────────────────────────────────
+QUALITY:
+───────────────────────────────────────────────
+
+  PHPStan:  {✅ passed | ❌ errors}
+  Rector:   {✅ no changes | ✏️ auto-fixed}
+  Tests:    {✅ all passed | ❌ failures}
+
+═══════════════════════════════════════════════
+```
+
+### 7. Emit a memory signal (post-resolution)
+
+If the root cause is a recognizable pattern (not a one-off typo),
+drop a `historical-patterns` signal so future work benefits:
+
+```bash
+python3 scripts/memory_signal.py \
+    --type historical-patterns \
+    --path "<primary affected file>" \
+    --body "<root cause → fix, one sentence>" \
+    --origin "bug-fix" \
+    --extra '{"symptom":"<observed symptom>","severity":"<low|medium|high>"}'
+```
+
+The helper deduplicates within a 7-day window, so repeated fixes of
+the same symptom only emit once. See
+[`/propose-memory`](propose-memory.md) for the universal write path.
+
+Skip this step for trivial fixes (typos, comment updates).
+
+### 8. Offer next steps
+
+```
+What next?
+
+1. 🧪 Write more tests
+2. 🔍 Check and fix similar spots in the code
+3. ✅ Done
+```
+
+### Rules
+
+- **Do NOT commit or push** without permission.
+- **Always run PHPStan** after changes.
+- **Always run affected tests** before declaring the fix done.
+- **Check for similar patterns** — if the bug exists in one place, it likely exists elsewhere.
+- **Present the fix plan** before implementing — let the user confirm.
+- **Update existing tests** that are affected by the change.
+- **Write new tests** for the specific bug scenario (regression test).
+
+## See also
+
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)

package/.agent-src/commands/bug-investigate.md

@@ -0,0 +1,175 @@
+---
+name: bug-investigate
+skills: [bug-analyzer, sentry-integration]
+description: Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause
+disable-model-invocation: true
+---
+
+# bug-investigate
+
+## Instructions
+
+### 1. Auto-detect ticket from branch
+
+Run `git branch --show-current` and extract ticket IDs:
+
+- Match pattern: `[A-Z]+-[0-9]+` (e.g., `DEV-1234`, `PROJ-567`)
+- Common branch formats: `fix/DEV-1234/description`, `hotfix/DEV-999`, `fix/bug-description`
+
+If a ticket ID is found:
+
+```
+🔀 Branch: {branch-name}
+🎫 Ticket detected: {TICKET-ID}
+
+> 1. Yes — load ticket
+> 2. No — skip
+```
+
+If yes → fetch via Jira API and show summary (see step 2).
+If no ticket found → continue to step 2.
+
+### 2. Ask for bug sources
+
+```
+🐛 Bug Investigation
+
+What information do you have? (multiple allowed)
+
+1. 🎫 Jira ticket(s) — provide key(s) (e.g. DEV-1234)
+2. 🔴 Sentry issue — provide URL or issue ID
+3. 💬 Bug description — describe the bug manually
+4. 📋 Error message — paste error message or stacktrace
+```
+
+Accept **multiple sources** — the more context, the better.
+
+### 3. Gather context from each source
+
+**Jira ticket (if provided):**
+- Fetch via Jira API (`/issue/{key}`).
+- Extract: title, description, priority, status, comments, linked issues.
+- Check for linked Sentry issues in comments or description.
+
+```
+🎫 Jira: {KEY} — {title}
+
+  Status:       {status} | Priority: {priority}
+  Description:  {summary}
+  Comments:     {count} ({key points})
+  Sentry links: {extracted URLs or "none found"}
+```
+
+**Sentry issue (if provided):**
+- Use `get_issue_details` with the URL or issue ID.
+- Use `get_issue_tag_values` for environment, browser, URL distribution.
+
+```
+🔴 Sentry: {issue-title}
+
+  Events:      {count} | Users: {count}
+  Erste:       {first seen} | Letzte: {last seen}
+  Environment: {distribution}
+  Stacktrace:  {top 3-5 frames}
+```
+
+**Error message (if provided):**
+- Search codebase for the exact message string.
+- Show matching files and line numbers.
+
+**User description (if provided):**
+- Note reproduction steps and expected vs. actual behavior.
+
+### 4. Analyze the code
+
+Based on gathered context:
+
+1. **Read the stacktrace** (if available) — trace from top frame down.
+2. **Use `codebase-retrieval`** to find related code.
+3. **Read each file** in the call chain.
+4. **Check for context docs** — `agents/contexts/` or module `agents/contexts/`.
+5. **Read `agents/memory/incident-learnings.yml`** (if it exists) for
+   entries whose `scope:` overlaps with the touched files or the error
+   signature. A prior incident may already describe the root cause,
+   the fix, and the regression test that should have caught it. Cite
+   the matching `id:` in the root-cause report.
+6. **Identify the data flow** — where does the bad data/state come from?
+
+**Share findings as you go:**
+
+```
+🔍 Code-Analyse:
+
+  Einstiegspunkt: {controller/command/job}
+  → {ServiceClass}::{method}() (Zeile {n})
+  → {RepositoryClass}::{method}() (Zeile {n})
+  → ❌ Hier passiert der Fehler: {description}
+
+  Affected files:
+    • {file1.php} — {role in the bug}
+    • {file2.php} — {role in the bug}
+```
+
+### 5. Present root cause
+
+```
+═══════════════════════════════════════════════
+  🐛 ROOT CAUSE ANALYSE
+═══════════════════════════════════════════════
+
+📍 Fehler:     {what happens}
+🔍 Ursache:    {why it happens — the root cause}
+📁 Betroffen:  {files and lines}
+🌍 Impact:     {how many users/events, which environments}
+
+───────────────────────────────────────────────
+EXPLANATION:
+───────────────────────────────────────────────
+
+{2-5 sentences explaining the root cause in plain language.
+Trace the data flow that leads to the error.}
+
+───────────────────────────────────────────────
+SUGGESTED FIX:
+───────────────────────────────────────────────
+
+{High-level description of the fix. Which files to change, what to add/remove.}
+
+1. {concrete step}
+2. {concrete step}
+3. Tests: {what to test}
+
+───────────────────────────────────────────────
+SIMILAR SPOTS:
+───────────────────────────────────────────────
+
+{Other code locations with the same pattern that might have the same bug.}
+
+═══════════════════════════════════════════════
+```
+
+### 6. Offer next steps
+
+```
+What's next?
+
+1. 🔧 Fix implementieren → /bug-fix
+2. 🔍 Tiefer analysieren (bestimmte Stelle genauer untersuchen)
+3. 📋 Als Feature/Refactoring planen → /feature-plan
+4. ✅ Done — only the analysis was needed
+```
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Do NOT start fixing before presenting the root cause.**
+- **Always check the branch** for ticket IDs first.
+- **Combine all sources** — Jira + Sentry + description give the best picture.
+- **Trace to the root cause** — don't just describe the symptom.
+- **Check for similar patterns** elsewhere in the codebase.
+- **Use Sentry tools** (`get_issue_details`, `get_issue_tag_values`) when URLs are available.
+
+## See also
+
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#incident) — Incident mode output contract (Symptom / Reproduction / Minimal reversible change / Deferred verification / Follow-up commitment) — use when the bug is a live production issue with `break-glass: true`
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract for non-incident bugs