@event4u/agent-config 1.9.1

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

@@ -0,0 +1,121 @@
+---
+name: commit
+skills: [git-workflow]
+description: Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits
+disable-model-invocation: true
+---
+
+# commit
+
+## Instructions
+
+### 1. Detect uncommitted changes
+
+Run:
+```bash
+git status --short
+git diff --stat
+git diff --cached --stat
+```
+
+If there are no uncommitted changes (staged or unstaged), report "Nothing to commit." and stop.
+
+### 2. Determine the ticket number
+
+- Extract the ticket ID from the current branch name (e.g. `feat/DEV-1234/...` → `DEV-1234`).
+- If no ticket ID is found in the branch name, ask the user:
+  ```
+  > No Jira ticket found in branch name. Do you want to include one?
+  >
+  > 1. Yes — I'll provide the ticket number
+  > 2. No — skip ticket number
+  ```
+- If the user provides a ticket number, use it as the scope in all commit messages.
+- If skipped, omit the scope entirely — write `chore: ...` not `chore(): ...`.
+
+### 3. Analyze the changes
+
+- Run `git diff HEAD` (and `git diff --cached` for already staged changes) to understand the full diff.
+- Group changed files into **logical units** — files that belong together because they:
+  - Implement the same feature or fix
+  - Are a migration + its corresponding model/seeder
+  - Are a test file and the class it tests
+  - Are purely stylistic/formatting changes (separate from logic changes)
+  - Are unrelated to the main change (e.g. config fix, unrelated typo)
+
+### 4. Plan the commits
+
+For each logical group, determine the commit message following the commit conventions rule
+(see `.augment/rules/commit-conventions.md`).
+
+Rules for splitting:
+- **Do NOT split arbitrarily** — only split when the changes are logically independent.
+- **Prefer fewer, coherent commits** over many tiny ones.
+- **Tests always go with the code they test** unless there are many test-only changes.
+- **Style-only changes** (ECS/Rector formatting) may get their own `style:` or `chore:` commit
+  if they are large and mixed with logic changes.
+
+### 5. Present the commit plan
+
+Show the proposed commits as a numbered list, including which files go into each:
+
+```
+Proposed commits:
+
+1. feat(DEV-1234): add absence type filter to working time report
+   → app/Services/WorkingTimeService.php
+   → app/Http/Controllers/WorkingTimeController.php
+   → app/Http/Resources/WorkingTimeResource.php
+
+2. test(DEV-1234): add component test for working time controller
+   → tests/Component/WorkingTime/WorkingTimeControllerTest.php
+
+3. chore: apply Rector formatting
+   → app/Models/Absence.php
+```
+
+Then ask:
+```
+> 1. Looks good — commit
+> 2. Adjust — I'll tell you what to change
+> 3. Cancel
+```
+
+Wait for the user's response before doing anything.
+
+### 6. Commit
+
+Only after the user confirms (option 1):
+
+For each planned commit in order:
+1. Stage only the files for that commit: `git add {files...}`
+2. Commit: `git commit -m "{message}"`
+
+### 7. Report
+
+Show a summary:
+- Number of commits created
+- Commit messages (one per line)
+
+## Rules
+
+- **Never commit before the user confirms** the plan.
+- **Never push** — pushing is left to the user.
+- **Never modify files** — only stage and commit existing changes.
+- **Do NOT add untracked files** unless they are clearly part of the change (check with `git status`).
+- **Follow commit conventions** as defined in `.augment/rules/commit-conventions.md`.
+
+## Optional: wrap in `/do-and-judge`
+
+If the user invoked `/commit` under `/do-and-judge` (or explicitly asked
+for judged commits), treat the planned commit list from step 5 as the
+implementer artifact:
+
+- Hand the commit plan + diff to the judge before step 6.
+- Judge verdict `apply` → proceed with step 6 unchanged.
+- Judge verdict `revise` → adjust grouping or messages per the issue
+  list, re-present the updated plan to the user, then re-judge.
+- Judge verdict `reject` → stop, report, do not commit.
+
+Two-revision ceiling applies per [`/do-and-judge`](do-and-judge.md).
+Outside the wrapper this section is a no-op.

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

@@ -0,0 +1,177 @@
+---
+name: compress
+skills: []
+description: Compress .md files from .agent-src.uncompressed/ into caveman format and write to .agent-src/
+disable-model-invocation: true
+---
+
+# compress
+
+Compress agent config `.md` files from `.agent-src.uncompressed/` into token-efficient caveman format
+and write the compressed output to `.agent-src/`.
+
+Uses SHA-256 hashes to track which source files changed since last compression.
+Only changed files need recompression — saving tokens and time.
+
+## Step 1: Sync non-.md files
+
+```bash
+task sync
+```
+
+This copies non-`.md` files (`.php`, etc.), deletes stale files, and shows the count of
+changed `.md` files that need compression.
+
+## Step 2: Get changed files
+
+```bash
+task sync-changed
+```
+
+This lists only `.md` files whose source has changed since the last compression (based on
+stored SHA-256 hashes). If no files changed → you're done.
+
+If you need to see ALL files regardless of change status: `task sync-list`.
+
+## Step 3: Compress each changed .md file
+
+**Core principle:** Compression must improve execution quality, not just reduce length.
+A compressed file should be easier to scan, easier to trigger, and easier to execute than the original.
+
+For each changed `.md` file:
+
+1. Read the source from `.agent-src.uncompressed/{path}`
+2. Compress the prose using these rules:
+   - **Remove:** articles (a, an, the), filler (just, really, basically, actually, simply, essentially),
+     pleasantries, hedging, connective fluff (however, furthermore, additionally),
+     redundant wording, obvious framework knowledge, repeated explanations, decorative prose
+   - **Shorten:** "in order to" → "to", "make sure to" → "ensure", use short synonyms
+   - **Fragments OK:** "Run tests before commit" not "You should always run tests before committing"
+   - **Drop:** "you should", "make sure to", "remember to" — state action directly
+   - **Merge** redundant bullets that say the same thing differently
+   - **Prefer** bullets over prose, direct instructions over explanatory paragraphs, one-line decisions over paragraphs
+3. **Copy-paste first, compress second:**
+   Before compressing ANY prose, extract and set aside these elements from the source.
+   They go into the compressed output **unchanged, byte-for-byte**:
+   - **All code blocks** (``` fenced or indented) — copy EVERY code block from source to output FIRST
+   - **YAML frontmatter** — copy verbatim
+   - **All inline code** (`backtick content`)
+   - **All URLs, links, file paths, commands**
+   - **All H1/H2 headings** — exact text preserved
+   - **Tables** (structure preserved, compress cell text only)
+   - **Technical terms, library names, API names**
+   - **Dates, version numbers, numeric values**
+   Then compress ONLY the prose around these preserved elements.
+4. **NEVER remove (even if verbose):**
+   - Trigger clarity (When to use / description)
+   - Decision hints that prevent mistakes
+   - Concrete validation checks
+   - Gotchas based on real failure patterns
+   - Anti-patterns that prevent recurring failures
+5. **Enrich (SKILL.md files only):** During compression, also improve agent-effectiveness:
+   - **Validation steps:** If a Procedure ends with a vague validation ("check if it works"),
+     replace with concrete checks (expected output, commands to verify, specific conditions)
+   - **Mini examples:** If no `Examples` section exists, add a short safe/unsafe or good/bad example
+     (2-4 lines max — not a tutorial)
+   - **Output format:** If the Output format section is vague ("explain everything"), sharpen it to
+     specific numbered expectations ("1. Code snippet 2. Where to register 3. Gotcha if relevant")
+   - **Anti-patterns:** If the same mistake keeps recurring, add a short anti-patterns section
+   - **Do NOT invent content.** Only concretize what the source implies. If the source says
+     "validate copy/paste safety", you can add "Check: no nested backticks, fully selectable".
+     But don't add unrelated sections.
+   - **Do NOT compress weak skills.** If the source has no procedure or no validation, fix structure first.
+   - **Reference skill:** See `.agent-src.uncompressed/skills/skill-writing/SKILL.md` for the gold standard
+6. Write the compressed output to `.agent-src/{path}`
+7. **MANDATORY: Run compression quality check on this file:**
+
+```bash
+python3 scripts/check_compression.py --format text 2>&1 | grep "{path}"
+```
+
+If the output contains 🔴 (error) for this file: **STOP. Fix the compressed file before continuing.**
+Common errors and how to fix them:
+- `lost_code_blocks` → You dropped a code block. Copy ALL code blocks from source.
+- `modified_code_block` → Code block content changed. Replace with exact source content.
+- `frontmatter_mismatch` → YAML frontmatter differs. Copy verbatim from source.
+
+**Do NOT call `mark-done` until this file has zero 🔴 errors.**
+
+8. Show word count: `{original} → {compressed} words ({saved}% saved)`
+9. **Mark as done:** `task sync-mark-done -- {path}`
+
+### Batch processing
+
+When compressing multiple files, process them in batches of ~10.
+Mark each file done after writing it. After each batch, show a progress summary:
+
+```
+Batch 1/5 complete: 10 files, avg 42% saved
+```
+
+## Step 4: Final verification gate
+
+Run BOTH checks. Both must pass before finishing.
+
+```bash
+task sync-check
+```
+
+Must show ✅ (hashes in sync).
+
+```bash
+python3 scripts/check_compression.py
+```
+
+Must show **zero 🔴 errors**. Warnings (🟡) are acceptable.
+If any 🔴 errors remain: go back and fix those files before finishing.
+
+## Step 5: Summary
+
+Show a summary table with per-category stats (files compressed, avg savings).
+
+## Hash management
+
+- Hashes are stored in `.augment/.compression-hashes.json` (committed to Git).
+- `task sync` automatically cleans up hashes for deleted source files.
+- `task sync-mark-all-done` marks ALL current `.md` files as compressed (useful after an
+  initial full compression or when bootstrapping the hash file).
+- A file with no stored hash is always treated as "changed".
+
+## Compression quality checklist
+
+**Also apply the `preservation-guard` rule** — strongest validation, example, anti-pattern, and decision hints must survive compression.
+
+After compressing each file, verify:
+
+- [ ] All code blocks preserved exactly (no content changes)
+- [ ] All inline code, URLs, file paths unchanged
+- [ ] YAML frontmatter identical to source
+- [ ] Headings match source exactly
+- [ ] Tables structure preserved (cell text may be shortened)
+- [ ] "NEVER", "MUST", "Do NOT" and other strong language preserved
+- [ ] Technical terms, library names, API names unchanged
+- [ ] No meaning lost — compressed version says the same thing, shorter
+- [ ] No sections accidentally removed
+- [ ] Word count reduction is 20-50% (typical range for prose-heavy files)
+
+### Safe vs unsafe compression
+
+Safe:
+- "You should always make sure to run the tests before committing" → "Run tests before commit"
+- "In order to ensure that the configuration is correct" → "To verify config"
+- "It is important to note that this feature requires" → "Requires"
+
+Unsafe (DO NOT do this):
+- Removing a bullet point that contains unique information
+- Changing `php artisan test --filter=MyTest` to `php artisan test`
+- Shortening "Do NOT use float for money" to "Avoid float"
+- Removing "NEVER" from "NEVER add to phpstan-baseline.neon"
+
+## Rules
+
+- **Do NOT commit or push.** Only write files.
+- **Do NOT modify `.agent-src.uncompressed/`** — it is the source of truth.
+- **Only write to `.augment/`** — the compressed output directory.
+- **Preserve ALL technical content** — only compress natural language prose.
+- **YAML frontmatter** in command/skill files must be preserved exactly.
+- **Always run `task sync-mark-done`** after writing each compressed file.

package/.agent-src/commands/config-agent-settings.md

@@ -0,0 +1,126 @@
+---
+name: config-agent-settings
+description: Create or update .agent-settings.yml — syncs with template, preserves existing values, adds new defaults
+skills: [file-editor]
+disable-model-invocation: true
+---
+
+# /config-agent-settings
+
+Creates or updates `.agent-settings.yml` in the project root by syncing with the
+template in `.augment/templates/agent-settings.md`. Both files are YAML with the
+same section layout (`personal`, `project`, `github`, `eloquent`, `pipelines`,
+`subagents`).
+
+If a **legacy** flat `.agent-settings` (key=value) is present, `scripts/install`
+migrates it to `.agent-settings.yml` automatically (with backup). This command
+assumes migration has already happened.
+
+## Steps
+
+### 1. Read the template
+
+Read `.augment/templates/agent-settings.md` and extract the YAML block (between
+the ` ```yaml ` markers). Parse it into a nested mapping preserving section
+order and comments.
+
+### 2. Read existing settings (if any)
+
+Read `.agent-settings.yml` from the project root. If a legacy `.agent-settings`
+(key=value, no `.yml`) is present, stop and tell the user to run
+`scripts/install` first — do not re-implement the migration here.
+
+### 3. Merge settings (section-aware)
+
+For each section in the template (in template order):
+
+- Keep the section header and its comments verbatim from the template.
+- For each key under the section:
+  - **Key exists in user's file** → use the user's current value.
+  - **Key missing** → use the template default.
+- **Unknown sections/keys** the user has added → preserve at the end of the
+  section (or in a trailing `_user:` block if no matching section exists).
+
+Invariants:
+- Template section **order** always wins.
+- Existing scalar values are **never overwritten**.
+- New keys added to the template land with their default value.
+- Comments from the template always replace user comments in the same position
+  (comments are documentation, not user data).
+
+### 4. Write the file
+
+Write the merged YAML to `.agent-settings.yml` with 2-space indentation and no
+trailing whitespace.
+
+### 5. Show diff
+
+If the file already existed, show what changed in YAML dotted-key notation:
+
+```
+✅  .agent-settings.yml updated!
+
+Added:
+  + project.pr_comment_bot_icon: true   (new setting, default applied)
+
+Unchanged:
+  personal.ide: phpstorm
+  personal.open_edited_files: true
+```
+
+If the file was created fresh:
+
+```
+✅  .agent-settings.yml created!
+
+Settings (all defaults applied):
+  personal.ide: ""
+  personal.open_edited_files: false
+  project.pr_comment_bot_icon: false
+
+Run /config-agent-settings again to change values, or edit .agent-settings.yml directly.
+```
+
+### 6. Interactive setup for empty values
+
+If any required setting has an empty value (e.g. `personal.ide: ""`), offer to
+configure it:
+
+```
+> `personal.ide` is empty. Which IDE do you use?
+>
+> 1. VS Code (code)
+> 2. PhpStorm (phpstorm)
+> 3. Cursor (cursor)
+> 4. Skip — I'll set it later
+```
+
+For `personal.ide`, also try auto-detection first:
+
+```bash
+ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v grep
+```
+
+- If detected → confirm with the user before setting.
+- If not detected → ask.
+
+### 7. Verify IDE command
+
+If `personal.ide` was set and `personal.open_edited_files: true`, verify the CLI
+command works:
+
+```bash
+{ide} --version 2>/dev/null
+```
+
+Warn if it fails and suggest how to install the CLI.
+
+## Rules
+
+- **Do NOT commit `.agent-settings.yml`** — it's in `.gitignore`.
+- **Never overwrite existing values** — only add missing keys with defaults.
+- **Always use template section order** — reorder keys to match the template.
+- **Template is the source of truth** for which keys exist and their defaults.
+- **Legacy migration is `scripts/install`'s job**, not this command's. If a flat
+  `.agent-settings` file is still present, ask the user to run `scripts/install`
+  and stop.

package/.agent-src/commands/context-create.md

@@ -0,0 +1,167 @@
+---
+name: context-create
+skills: [agent-docs-writing]
+description: Analyze a codebase area and create a structured context document
+disable-model-invocation: true
+---
+
+# context-create
+
+## Instructions
+
+### 1. Ask what to document
+
+If the user provided a topic, use it. Otherwise ask:
+
+```
+📄 What area do you want to document?
+
+Examples:
+- A module (e.g. "ClientSoftware Module")
+- A service (e.g. "CustomerService and Tenant-Switching")
+- An integration (e.g. "ProBauS API Integration")
+- A domain area (e.g. "Import pipeline from upload to processing")
+- Infrastructure (e.g. "Queue system with Horizon")
+```
+
+### 2. Determine scope (module vs. project-wide)
+
+Check if `app/Modules/` exists. If yes, ask:
+
+```
+Should the context be created in a module or in the project root?
+
+1. 📦 In a module → app/Modules/{Module}/agents/contexts/
+2. 🌐 Project root → agents/contexts/
+```
+
+If module:
+- List available modules and ask which one.
+- Target: `app/Modules/{Module}/agents/contexts/`
+- Create directory if it doesn't exist.
+
+If project-wide:
+- Target: `agents/contexts/`
+
+### 3. Determine context type
+
+```
+What type of context is this?
+
+1. 📦 Module — structure and purpose of a module
+2. 🏢 Domain — business logic across multiple modules
+3. ⚙️ Service — complex service with dependencies
+4. 🔗 Integration — external API/system integration
+5. 🏗️ Infrastructure — DevOps, infrastructure
+```
+
+### 4. Analyze the code
+
+Based on the type, analyze the relevant code area:
+
+**Module context:**
+- List all directories and file counts
+- Read key services, controllers, models
+- Analyze route files
+- Check for tests, agent docs
+
+**Domain context:**
+- Search across modules for related code
+- Trace data flow through services
+- Identify all models and tables involved
+
+**Service context:**
+- Read the service class and its dependencies
+- Trace call chain (who calls it, what it calls)
+- Identify configuration and env dependencies
+
+**Integration context:**
+- Find API client classes, HTTP calls
+- Read config for credentials/URLs
+- Identify error handling and retry logic
+
+**Infrastructure context:**
+- Read config files, Docker setup
+- Identify services and their connections
+- Check monitoring/logging setup
+
+**Share findings as you go:**
+```
+🔍 Ich analysiere den Code...
+
+Gefunden:
+  • 5 Services in App/Services/
+  • 3 Controllers mit 12 API Endpoints
+  • 8 Models mit Beziehungen zu customer_database
+  • 42 Tests (15 Unit, 20 Component, 7 Integration)
+
+Should I investigate any specific areas in more detail?
+```
+
+### 5. Interactive refinement
+
+After analysis, discuss findings:
+
+- "I noticed {Service} depends on {Dependency}. Is that correct?"
+- "There are {count} endpoints — should all be documented?"
+- "Are there known issues or technical debt in this area?"
+- "Anything I missed?"
+
+### 6. Create the context document
+
+- Read `.augment/templates/contexts.md` for the structure.
+- Create the context file in the target directory.
+- Fill in all applicable sections from the analysis.
+- Set `Last Updated` to today's date.
+
+**Ask for the filename:**
+```
+Context name?
+
+> 1. {suggested-kebab-case-name} (suggested)
+> 2. Enter a custom name
+
+Target: {target-directory}/{name}.md
+```
+
+### 7. Show result
+
+```
+═══════════════════════════════════════════════
+  ✅  CONTEXT CREATED
+═══════════════════════════════════════════════
+
+📄 {path/to/context.md}
+📊 Typ: {type}
+📦 Module: {module or "project-wide"}
+
+───────────────────────────────────────────────
+INHALT:
+───────────────────────────────────────────────
+
+  Key Files:       {count}
+  Key Classes:     {count}
+  DB Tables:       {count}
+  API Endpoints:   {count}
+  Known Issues:    {count}
+
+═══════════════════════════════════════════════
+```
+
+### 8. Offer next steps
+
+```
+What's next?
+
+1. ✏️ Adjust context → /context-refactor
+2. 📋 Plan a feature based on this context → /feature-plan
+3. ✅ Done
+```
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Always analyze the code first** — never guess or assume.
+- **Be factual** — document what IS, not what SHOULD be.
+- **Ask the user** about unclear areas or business context.
+- **Link to specific files** — not vague descriptions.