@event4u/agent-config 1.9.1

package/.agent-src/README.md

@@ -0,0 +1,64 @@
+# Agent Infrastructure
+
+> **⚠️ DO NOT edit files in `.agent-src/` or `.augment/` directly.**
+> The source of truth is `.agent-src.uncompressed/`. Edit there, then run `task sync`.
+> See `.agent-src.uncompressed/commands/compress.md` for the full workflow.
+
+This directory contains the shared agent infrastructure: skills, commands, rules, guidelines,
+templates, and contexts that power the AI coding assistant across all projects.
+
+In the package repo, this content lives in `.agent-src/` (shipped). Consumer projects install
+it as `.augment/` (local projection).
+
+## Directory Structure
+
+```
+├── commands/       # Slash commands — executable workflows (/fix-pr-comments, /agent-handoff, ...)
+├── contexts/       # Background context documents for the agent
+├── guidelines/     # Coding guidelines by language (reference material)
+├── rules/          # Always-active behavior rules (auto-loaded every conversation)
+├── skills/         # On-demand expertise (matched by topic)
+└── templates/      # File templates for roadmaps, features, skills, etc.
+```
+
+## How It Works
+
+| Layer | Always active? | Purpose |
+|---|---|---|
+| **Rules** | ✅ Yes | Behavior constraints — loaded every conversation |
+| **Skills** | 🔄 On demand | Expertise — matched when the topic is relevant |
+| **Commands** | ⚡ On trigger | Workflows — triggered by `/command-name` |
+| **Guidelines** | 📖 Reference | Coding conventions — read when writing code |
+| **Templates** | 📄 Blueprints | File structure templates for new documents |
+| **Contexts** | 🧠 Background | System-level context about the infrastructure |
+
+For full details see [augment-infrastructure.md](contexts/augment-infrastructure.md).
+
+## Quick Reference
+
+### Most-used commands
+
+| Command | Purpose |
+|---|---|
+| `/agent-handoff` | Generate context summary for a fresh chat |
+| `/fix-pr-comments` | Fix all open PR review comments |
+| `/quality-fix` | Run PHPStan + Rector and fix errors |
+| `/create-pr` | Create a GitHub PR with description |
+| `/bug-investigate` | Investigate a bug from Jira/Sentry |
+| `/tests-create` | Write tests for current changes |
+
+### Key rules
+
+| Rule | What it enforces |
+|---|---|
+| `verify-before-complete` | Must run tests/PHPStan before claiming "done" |
+| `scope-control` | Don't commit/push without permission, no unasked changes |
+| `token-efficiency` | Redirect output, don't narrate, trust ECS/Rector |
+| `downstream-changes` | After every edit, update ALL callers, tests, imports |
+| `php-coding` | Strict types, getters/setters, observers |
+
+## Project-Level Overrides
+
+Projects can override shared skills, rules, and commands via `agents/overrides/`.
+See [override-system.md](contexts/override-system.md) for details.
+

package/.agent-src/commands/agent-handoff.md

@@ -0,0 +1,64 @@
+---
+name: agent-handoff
+skills: [agent-docs-writing]
+description: Generate a context summary for continuing work in a fresh chat. Replaces the session system.
+disable-model-invocation: true
+---
+
+# /agent-handoff
+
+Generates a concise handoff prompt the user can paste into a new chat.
+This replaces the old session system — no files to save/load, just a copy-paste prompt.
+
+## Steps
+
+### 1. Gather context
+
+Collect the following from the current conversation:
+
+- **Branch**: `git branch --show-current`
+- **Uncommitted changes**: `git status --short`
+- **Recent commits**: `git log --oneline -5`
+- **Active roadmap**: Check `agents/roadmaps/` for any active roadmap
+- **Task list**: Only include if the user explicitly asks for it (e.g., "/agent-handoff with tasks")
+
+### 2. Generate handoff prompt
+
+Create a fenced code block the user can copy-paste into a new chat:
+
+```
+---
+Branch: {branch}
+Last commit: {hash} {message}
+Roadmap: {roadmap file if active, or "none"}
+---
+
+## Done
+- {1-2 sentences summarizing what was accomplished}
+
+## Open
+- {bullet list of remaining tasks or next steps}
+
+## Key decisions
+- {important decisions made during this conversation}
+
+## Relevant files
+- {list of files that were edited or are important for context}
+```
+
+### 3. Present to user
+
+Show the handoff prompt in a fenced code block and say:
+
+```
+> Copy this into a new chat to continue where we left off.
+```
+
+## Rules
+
+- **Keep it concise** — the prompt should be <30 lines. More context = more input tokens in the new chat.
+- **Only include actionable info** — skip history, reasoning, and failed attempts.
+- **Branch name is critical** — always include it.
+- **Open tasks are critical** — the new chat needs to know what's left.
+- **Decisions are important** — prevents the new chat from re-asking settled questions.
+- **File list is optional** — only include if the new chat will need to edit specific files.

package/.agent-src/commands/agent-status.md

@@ -0,0 +1,83 @@
+---
+name: agent-status
+skills: [agent-docs-writing]
+description: Show current conversation stats — message count, token costs, task progress, next freshness check.
+disable-model-invocation: true
+---
+
+# /agent-status
+
+Displays a dashboard of the current conversation's health and token costs.
+
+## Steps
+
+### 1. Count messages
+
+Count your own responses in this conversation (each response ≈ 1 user message).
+This is an estimate — you cannot access exact counts.
+
+### 2. Count tasks
+
+Run `view_tasklist` and count:
+- Total tasks
+- Completed tasks
+- In-progress tasks
+- Not started tasks
+
+### 3. Estimate token costs
+
+Calculate based on these estimates:
+
+| Component | How to estimate | Tokens |
+|---|---|---|
+| **Conversation history** | responses × ~1,500 | variable |
+| **AGENTS.md** | always loaded | ~1,800 |
+| **Skill descriptions** | always loaded | ~4,100 |
+| **Matched rules** | count rules triggered this request × ~800 avg | variable |
+| **Matched skills** | count skills triggered this request × ~1,500 avg | variable |
+| **Platform overhead** | system prompt, tool schemas | ~15,000 |
+
+### 4. Calculate freshness thresholds
+
+- **Message threshold**: Next multiple of 25 ≥ current count
+- **Task threshold**: Next multiple of 15 ≥ completed count
+- **Which comes first?**
+
+### 5. Display dashboard
+
+Use Markdown tables and headings — NOT ASCII box art (breaks in non-monospace chat UIs).
+
+**📊 Agent Status**
+
+| | |
+|---|---|
+| 💬 Messages | ~{N} responses |
+| 📋 Tasks | {done}/{total} done ({in_progress} in progress, {not_started} open) |
+| 🌿 Branch | `{branch}` |
+
+**💰 Estimated tokens PER REQUEST**
+
+| Component | Tokens |
+|---|---|
+| Platform overhead | ~15,000 |
+| AGENTS.md + Skills | ~5,900 |
+| **Conversation history** | **~{N×1500}** ← biggest cost |
+| Matched rules (~{n}) | ~{n×800} |
+| Matched skills (~{n}) | ~{n×1500} |
+| **Total input** | **~{sum}** |
+
+**⚡ Freshness**
+
+| | |
+|---|---|
+| Next check at | {next_msg} messages or {next_task} completed tasks |
+| Fresh chat saves | ~{N×1500} tokens/request |
+
+If history cost exceeds ~50,000: add a ⚠️ recommendation to start a fresh chat.
+
+## Rules
+
+- **Estimates only** — no access to real token counts, make that clear.
+- **Markdown tables** — never use ASCII box art, it breaks in chat UIs.
+- **History cost is the key insight** — bold it as the biggest variable cost.
+- **Always show the savings** — "Fresh chat saves X tokens/request" drives the point home.

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

@@ -0,0 +1,243 @@
+---
+name: agents-audit
+description: Audits agents/ and module agents/ directories — finds outdated docs, structural issues, duplicates, orphaned overrides, and creates an improvement roadmap.
+skills: [agents-audit, agent-docs-writing, override-management, module-management]
+disable-model-invocation: true
+---
+
+# /agents-audit
+
+Audits all agent documentation across the project — root `agents/`, module `app/Modules/*/agents/`,
+and `agents/overrides/`.
+
+## Steps
+
+### 1. Inventory all agent docs
+
+Scan all directories:
+
+```bash
+# Root-level docs
+find agents/ -maxdepth 1 -name '*.md' | sort
+
+# Subdirectories
+find agents/features/ agents/contexts/ -name '*.md' 2>/dev/null | sort
+
+# Overrides
+find agents/overrides/ -name '*.md' -not -name '.gitkeep' 2>/dev/null | sort
+
+# Guidelines
+find .augment/guidelines/ -name '*.md' | sort
+
+# Module-level docs (excluding roadmaps)
+find app/Modules/*/agents/ -name '*.md' -not -path '*/roadmaps/*' 2>/dev/null | sort
+```
+
+For each file, extract:
+- Filename and path
+- First heading (title)
+- File size and last git modification date (`git log -1 --format='%ai' -- {file}`)
+
+### 2. Scan module agents coverage
+
+Check every module for agent docs:
+
+```bash
+for dir in app/Modules/*/; do
+  name=$(basename "$dir")
+  if [ -d "$dir/agents" ]; then
+    count=$(find "$dir/agents" -name '*.md' | wc -l | tr -d ' ')
+    echo "✅  $name — $count docs"
+  else
+    echo "❌  $name — no agents/ dir"
+  fi
+done
+```
+
+For each module WITH agents, check structure:
+
+| Check | Expected | Severity |
+|---|---|---|
+| Module description file exists | `agents/{name}.md` or `agents/README.md` | 🟡 Warning |
+
+| Features dir (if planned work) | `agents/features/` | 🔵 Info |
+| Contexts dir (if complex domain) | `agents/contexts/` | 🔵 Info |
+| Consistent format across modules | Same heading structure, same sections | 🔵 Info |
+
+### 3. Scan overrides
+
+For each override in `agents/overrides/`:
+
+```bash
+find agents/overrides/ -name '*.md' -not -name '.gitkeep' | while read f; do
+  # Extract Mode and Original path from header
+  mode=$(grep -m1 'Mode:' "$f" | sed 's/.*`\(.*\)`.*/\1/')
+  original=$(grep -m1 'Original:' "$f" | sed 's/.*`\(.*\)`.*/\1/')
+  # Check if original exists
+  if [ -f "$original" ]; then
+    echo "✅  $f → $original ($mode)"
+  else
+    echo "❌  $f → $original (ORPHANED — original missing)"
+  fi
+done
+```
+
+| Check | Severity |
+|---|---|
+| Override has valid `Mode` header (`extend` or `replace`) | 🔴 Critical if missing |
+| Override has valid `Original` path | 🔴 Critical if missing |
+| Original file exists | 🟡 Warning if orphaned |
+| Override content is not empty (beyond template) | 🟡 Warning if empty |
+
+### 4. Classify each document
+
+For each doc, determine its category:
+
+- **Architecture** — project-level architecture docs (DB, auth, tenancy)
+- **Convention** — coding guidelines and standards
+- **Pattern** — design pattern documentation
+- **Feature plan** — planned features
+- **Context** — codebase area snapshots
+- **Module doc** — module-specific documentation
+- **Override** — project-level override of shared resource
+- **Unclear** — doesn't fit a clear category
+
+### 5. Check for issues
+
+**Structural issues:**
+- Files in wrong directories (e.g., a guideline in `agents/` root)
+- Missing expected directories
+- Naming inconsistencies (not kebab-case)
+- Module docs that should be root-level (cross-module concern)
+- Root docs that should be module-level (single-module concern)
+
+**Content issues (for each doc):**
+- Read the file and extract referenced file paths, class names, method names
+- Use `codebase-retrieval` or file checks to verify references still exist
+- Flag references to deleted/renamed code
+
+**Duplication:**
+- Compare doc topics — are two docs covering the same thing?
+- Check overlap between `agents/` docs and `.augment/skills/` content
+- Check overlap between root docs and `.augment/guidelines/` docs
+- Check overlap between module docs and root docs
+
+**Coverage gaps:**
+- Active modules without any agent docs
+- Complex areas (many files, many services) without documentation
+- Overrides that reference sections no longer in the original
+
+### 6. Display audit report
+
+```
+═══════════════════════════════════════════════
+  🔍  AGENTS AUDIT
+═══════════════════════════════════════════════
+
+📁  Scanned: {total} files in {dirs} directories
+
+───────────────────────────────────────────────
+INVENTAR
+───────────────────────────────────────────────
+
+  Category         Count   Files
+  ───────────────  ──────  ────────────────────────────
+  Architecture     {n}     database-setup.md, ...
+  Convention       {n}     guidelines/controllers.md, ...
+  Pattern          {n}     guidelines/patterns/service-layer.md, ...
+  Feature          {n}     {or "keine"}
+  Context          {n}     {or "keine"}
+  Module Doc       {n}     Import/agents/import.md, ...
+  Override         {n}     overrides/skills/eloquent.md, ...
+  Unklar           {n}     {files that don't fit}
+
+───────────────────────────────────────────────
+MODULE AGENTS
+───────────────────────────────────────────────
+
+  Module             Status  Docs  Description   Features  Contexts
+  ─────────────────  ──────  ────  ────────────  ────────  ────────
+  Import             ✅      3     ✅            ✅        ❌
+  Backoff            ✅      1     ✅            ❌        ❌
+  Grafana            ✅      2     ✅            ❌        ❌
+  ClientSoftware     ❌      0     ❌            ❌        ❌
+  ...
+
+───────────────────────────────────────────────
+OVERRIDES
+───────────────────────────────────────────────
+
+  Override                          Mode     Original  Status
+  ────────────────────────────────  ───────  ────────  ──────
+  {or "No overrides found"}
+
+───────────────────────────────────────────────
+ISSUES
+───────────────────────────────────────────────
+
+🔴  Kritisch ({count}):
+  •  {file} — {issue description}
+
+🟡  Warnung ({count}):
+  •  {file} — {issue description}
+
+🔵  Info ({count}):
+  •  {file} — {improvement suggestion}
+
+⚪  Clean ({count} files without issues)
+
+───────────────────────────────────────────────
+DUPLICATES / OVERLAPS
+───────────────────────────────────────────────
+
+  •  {file1} ↔ {file2} — {what overlaps}
+
+───────────────────────────────────────────────
+GAPS
+───────────────────────────────────────────────
+
+  ⚠️  Modules without docs: {list}
+  ⚠️  Missing contexts: {list}
+  ⚠️  Orphaned overrides: {list}
+
+═══════════════════════════════════════════════
+```
+
+### 7. Create improvement roadmap
+
+```
+Create an improvement roadmap?
+
+1. ✅  Yes — create roadmap in agents/roadmaps/agents-cleanup.md
+2. 📋  Show recommendations only (no file creation)
+3. ❌  No — the audit was all that was needed
+```
+
+**Option 1:** Create a roadmap using `.augment/templates/roadmaps.md` with phases:
+
+- **Phase 1: Critical fixes** — orphaned overrides, broken references, broken structure
+- **Phase 2: Structural cleanup** — move misplaced files, merge duplicates
+- **Phase 3: Module docs** — create missing module descriptions and contexts
+- **Phase 4: Cleanup** — delete obsolete docs, clean up naming, align formats
+
+**Option 2:** Show recommendations inline without creating a file.
+
+### 8. Offer next steps
+
+```
+What next?
+
+1. 🧹  Start cleanup → /agents-cleanup
+2. 📄  Update a specific doc → /context-refactor
+3. ✅  Done
+```
+
+## Rules
+
+- **Do NOT modify or delete any files** — this command is analysis only.
+- **Do NOT commit or push.**
+- **Do NOT audit `agents/roadmaps/` or `app/Modules/*/agents/roadmaps/`** — roadmaps have their own lifecycle.
+- **Do NOT audit `.augment/`** — skills and rules are managed separately.
+- **Verify references against the actual codebase** — don't guess.
+- **Be specific about issues** — name the file, the reference, and what's wrong.
+- **Don't flag missing module docs for tiny/inactive modules** — only for active modules with significant code.

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

@@ -0,0 +1,169 @@
+---
+name: agents-cleanup
+skills: [agent-docs-writing]
+description: Execute cleanup actions from an agents-audit — move, merge, delete, and update agent docs
+disable-model-invocation: true
+---
+
+# agents-cleanup
+
+## Instructions
+
+### 1. Check for audit roadmap
+
+- Check if `agents/roadmaps/agents-cleanup.md` exists (created by `/agents-audit`).
+- If yes → load it and show the phases.
+- If no → ask:
+
+```
+⚠️  No audit roadmap found.
+
+1. 🔍 Run /agents-audit first (recommended)
+2. 💬 I know what to do — start directly
+```
+
+If option 2, ask what to clean up.
+
+### 2. Show action plan
+
+If a roadmap exists, display the phases:
+
+```
+═══════════════════════════════════════════════
+  🧹 AGENTS CLEANUP
+═══════════════════════════════════════════════
+
+Phase 1: Critical fixes ({count} actions)
+  - [ ] {action}
+  - [ ] {action}
+
+Phase 2: Structural cleanup ({count} actions)
+  - [ ] {action}
+  - [ ] {action}
+
+Phase 3: Fill gaps ({count} actions)
+  - [ ] {action}
+
+Phase 4: Cleanup ({count} actions)
+  - [ ] {action}
+
+═══════════════════════════════════════════════
+
+Which phase to work on?
+
+1. Start Phase 1 (recommended — top to bottom)
+2. Choose a specific phase
+3. Choose a specific action
+```
+
+### 3. Execute actions
+
+For each action, follow the appropriate workflow:
+
+**Move file:**
+```
+📁 Move: {source} → {target}
+Reason: {why}
+
+Confirm? (y/n)
+```
+- Move the file.
+- Update all references in other docs that link to the old path.
+- Check `.augment/skills/` and `.augment/commands/` for references.
+
+**Merge files:**
+```
+🔗 Merge:
+  {file1} + {file2} → {target}
+Reason: {why — what overlaps}
+
+Confirm? (y/n)
+```
+- Read both files.
+- Show the proposed merged content.
+- Create the merged file, delete the originals.
+- Update references.
+
+**Delete file:**
+```
+🗑️  Delete: {file}
+Reason: {why — what's obsolete}
+
+Content (preview):
+  {first 5 lines}
+
+Confirm? (y/n)
+```
+- Delete the file.
+- Check for and remove references in other docs.
+
+**Update file:**
+```
+✏️  Update: {file}
+Reason: {what's outdated}
+
+Changes:
+  - {reference to deleted class} → remove
+  - {outdated section} → update
+  - {missing info} → add
+
+Confirm? (y/n)
+```
+- Read the file.
+- Make the changes.
+- Show a summary of what changed.
+
+**Create context:**
+```
+📄 Create context: {area}
+Reason: {why it's needed}
+
+> 1. Yes — start /context-create
+> 2. Skip
+```
+- Transition to `/context-create` with the area pre-selected.
+
+### 4. Update roadmap progress
+
+After each action:
+- Mark the step as `[x]` in the roadmap file.
+- Show progress:
+
+```
+✅  Action complete: {description}
+
+Progress Phase {n}: [{completed}/{total}]
+██████████░░░░░░ 60%
+
+> 1. Continue with next action
+> 2. Stop here
+```
+
+### 5. Summary
+
+After completing a phase or all actions:
+
+```
+═══════════════════════════════════════════════
+  ✅  CLEANUP SUMMARY
+═══════════════════════════════════════════════
+
+  📁 Moved:     {count} files
+  🔗 Merged:    {count} files
+  🗑️  Deleted:   {count} files
+  ✏️  Updated:   {count} files
+  📄 Created:   {count} contexts
+
+  Remaining:        {count} actions in {phases} phases
+
+═══════════════════════════════════════════════
+```
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Always confirm before each destructive action** (delete, merge, move).
+- **Always update references** when moving or renaming files.
+- **Update the roadmap** after each completed action.
+- **Show file content** before deleting — the user should see what's being removed.
+- **Check `.augment/` references too** — skills and commands may link to agents docs.