@event4u/agent-config 1.9.1

package/.agent-src/rules/commit-conventions.md

@@ -0,0 +1,64 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests"
+source: package
+---
+
+# Commit Conventions
+
+All commit messages and squash/merge titles follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+## Format
+
+- With scope: `<type>(<scope>): <description>`
+- Without scope: `<type>: <description>`
+- Always English. Imperative mood. Max 72 chars first line.
+
+## Types
+
+| Type | When |
+|---|---|
+| `feat` | New user-facing functionality |
+| `fix` | Bug fix |
+| `refactor` | Structure change, no behavior change |
+| `docs` | Documentation only |
+| `test` | Tests only |
+| `chore` | Maintenance, deps, cleanup |
+| `ci` | CI/CD, workflows |
+| `style` | Formatting only |
+| `perf` | Performance improvement |
+| `build` | Build tooling, packaging |
+
+## Scope
+
+- Jira ticket ID when branch has one: `DEV-1234`
+- Otherwise short area name: `api`, `auth`, `skills`
+- Optional — only add when it improves clarity.
+
+## Breaking changes
+
+Mark with `!` or `BREAKING CHANGE:` footer:
+
+```
+feat(api)!: rename invoice status values
+refactor(auth)!: remove legacy session flow
+```
+
+## Commit splitting
+
+Mixed concerns → split into multiple commits. Don't hide unrelated changes in one.
+
+## Examples
+
+```
+feat(DEV-1234): add absence type filter to working time report
+fix(DEV-1234): handle null value in equipment import
+test(DEV-1234): add component test for working time controller
+refactor: extract user sync logic into dedicated service
+chore: update PHP quality package to 2.1.0
+ci(lint): add skill-lint workflow
+docs(roadmap): add phase 3 implementation plan
+```
+
+→ Type selection rules, anti-patterns, decision checklist: `guidelines/php/git.md`

package/.agent-src/rules/context-hygiene.md

@@ -0,0 +1,90 @@
+---
+type: "always"
+alwaysApply: true
+description: "3-failure rule for debugging and fixing errors — stop after 3 consecutive failed attempts, dump state, and recommend a fresh session"
+source: package
+---
+
+# Context Hygiene
+
+## Conversation Freshness
+
+Monitor for **context decay** — long conversations degrade quality and waste tokens.
+
+**Suggest a new chat when:**
+
+- Conversation exceeds **~20 user messages**
+- Topic **changes completely**
+- Re-reading files already in context
+- **15+ completed tasks** and new unrelated topic
+- Branch changed since start
+- ~24 hours passed
+
+**Repeat** at multiples: messages 20/40/60, tasks 15/30/45.
+**ONLY at exact thresholds.** Between: silence.
+
+**How to suggest:**
+
+Estimate token cost: responses × ~1,500 tokens.
+
+```
+> ⚡ This conversation has ~{N} messages (~{N×1500} tokens history cost — charged on EVERY request).
+> A fresh chat saves ~{N×1500} input tokens per request.
+>
+> 1. Start fresh — I'll initiate a session handoff
+> 2. Continue here
+```
+
+**If the user picks 1:** Initiate a session handoff or start fresh.
+
+## The 3-Failure Rule
+
+When **3 consecutive attempts** at the same task fail (code fix, test fix, config change, etc.):
+
+1. **STOP** — do not attempt a 4th fix.
+2. **State dump** — summarize what was tried, what failed, and what you know so far.
+3. **Recommend fresh start** — suggest a fresh session with the state dump as context, or ask for a different approach.
+
+**What counts as a failure:**
+
+- Code change that doesn't fix the problem
+- Test that still fails after the fix
+- Quality check (PHPStan, ECS) that still errors
+- Build/deploy that fails after config change
+
+**Does NOT reset the counter:** Unrelated tasks. User providing new information (course correction).
+
+## Tool Loop Detection
+
+Calling the **same tool** more than **2 times in a row** with similar parameters = loop.
+
+**Immediate action:**
+1. **STOP** all tool calls.
+2. **Do the task directly** — write the code, run the command, answer the question.
+3. If you can't proceed — ask the user for help.
+
+`sequentialthinking` is especially prone to loops. Use at most **once** per task,
+NEVER for simple file operations, command execution, or straightforward edits.
+
+## State dump format
+
+```
+## State Dump: [Task]
+### Tried: 1. [Approach] → [Why failed] 2. ... 3. ...
+### Known: [Key facts]
+### Hypothesis: [Best guess for root cause]
+### Recommendation: [Next approach for fresh session]
+```
+
+Use `/agent-handoff` to generate a context summary for a fresh conversation.
+
+## Augment-specific: Ignored Skills Recovery
+
+Skills excluded via `.augmentignore` don't appear in `<available_skills>`.
+If you need an ignored skill: read its SKILL.md directly, apply guidance, then ask:
+
+```
+> 💡 I loaded `{name}` manually — currently ignored in `.augmentignore`.
+> 1. Remove from ignore — relevant for this project
+> 2. Keep ignored — one-off
+```

package/.agent-src/rules/docker-commands.md

@@ -0,0 +1,55 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution"
+source: package
+---
+
+# Docker Container Commands
+
+All PHP commands (PHPStan, Rector, Composer, PHPUnit, Artisan) must be executed **inside the Docker container**, not on the host.
+
+## Container Detection
+
+Detect the correct PHP container service name from `docker-compose.yml` / `compose.yaml`.
+Read the compose file to find the PHP service name — it varies per project.
+
+Use `docker compose exec -T <service> ...` for non-interactive commands (scripts, CI).
+Use `make console` to enter the container interactively (if available).
+
+## Tooling Detection
+
+Check if `artisan` exists in the project root:
+
+- **Laravel** (`artisan` exists): `php artisan test`, `vendor/bin/phpstan analyse`, `vendor/bin/rector process`
+- **Composer** (no `artisan`): `vendor/bin/phpunit`, `vendor/bin/phpstan analyse`, `vendor/bin/rector process`
+
+## Examples (Laravel project)
+
+```bash
+docker compose exec -T <php-service> vendor/bin/phpstan analyse
+docker compose exec -T <php-service> vendor/bin/rector process
+docker compose exec -T <php-service> vendor/bin/ecs check --fix
+docker compose exec -T <php-service> php artisan test
+```
+
+## Examples (Composer project)
+
+```bash
+docker compose exec -T <php-service> vendor/bin/phpstan analyse
+docker compose exec -T <php-service> vendor/bin/rector process
+docker compose exec -T <php-service> vendor/bin/ecs check --fix
+docker compose exec -T <php-service> vendor/bin/phpunit
+```
+
+## Build / Task Runner
+
+Before using raw `docker compose exec` commands, check if a `Makefile` or `Taskfile.yml` exists.
+These often provide convenient shortcuts for common operations:
+
+- `Makefile` → `make console`, `make test`, `make phpstan`, etc.
+- `Taskfile.yml` → `task console`, `task test`, `task phpstan`, etc.
+
+**Always read the Makefile/Taskfile first** to discover available targets.
+
+Frontend commands (npm, webpack) run on the host or in the node container.

package/.agent-src/rules/docs-sync.md

@@ -0,0 +1,79 @@
+---
+type: "auto"
+description: "Keeping .augment/ contexts, counts, and cross-references in sync when creating, renaming, or deleting skills, commands, rules, guidelines, templates, or any agent infrastructure files"
+source: package
+---
+
+# Docs Sync
+
+## Rule
+
+**CRITICAL — ZERO TOLERANCE:** When a file in `.augment/` is **created, renamed, or deleted**,
+or its **name, description, scope, or counts change**, all related files **must be updated
+in the same response** — not later, not in a follow-up, not when reminded.
+
+A new rule/skill/command without its index entry, count update, and context update is **incomplete work**.
+
+**Mandatory sequence when creating/deleting any `.augment/` file:**
+1. Create/delete the file
+2. **Immediately** update `contexts/augment-infrastructure.md` (counts + category tables)
+3. Check cross-references in contexts and routing hints (inline "see X skill" references)
+
+Steps 2–3 are NOT optional. Do NOT present the result to the user until all steps are done.
+
+**Two modes:**
+- **Reactive** (automatic): Triggered by add/remove/rename or scope/description/count changes → sync counts, contexts, cross-references.
+- **Proactive** (on demand): Full audit → find duplicates, thin skills, redundancy, stale content → fix or merge. Ask before destructive actions.
+
+## What to update
+
+When a file is **added, removed, or renamed**:
+
+| Change | Files to update |
+|---|---|
+| Skill/command/rule count changes | `contexts/augment-infrastructure.md` (count + category table) |
+| New skill category | `contexts/augment-infrastructure.md` + `contexts/skills-and-commands.md` |
+| New workflow chain | `contexts/skills-and-commands.md` (workflow chains section) |
+
+## Cross-reference updates
+
+When a skill is **added or its scope changes**, check and update:
+
+| What | Where to check |
+|---|---|
+| Inline routing hints | "see X skill" or "use X instead" references in other skills |
+| Guideline cross-references | Guidelines that reference the changed skill |
+| Command skill references | Commands that use the changed skill |
+
+## Settings template sync
+
+When skill/rule/command reads new setting from `.agent-settings.yml` not in `templates/agent-settings.md`:
+
+1. Add key with default to template
+2. Add row to Settings Reference table
+3. Add comment above key explaining it
+4. **Update local `.agent-settings.yml`** — add new key with default, preserve existing values,
+   apply template order and comments. Same behavior as `/config-agent-settings`, inline.
+
+**Mandatory** — without step 4, user can't discover new settings exist.
+
+## Content consistency
+
+**CRITICAL — MANDATORY CHECK:** When a rule, skill, or guideline's **content** is changed
+(not just metadata), you MUST search for **all other rules, skills, and guidelines that cover
+the same topic** and verify they are consistent.
+
+```bash
+grep -rl "TOPIC" .augment/rules/ .augment/skills/ .augment/guidelines/ --include="*.md"
+```
+
+If any file contradicts or is missing the updated information → **update it in the same response**.
+Inconsistent documentation is worse than no documentation.
+
+## Do NOT
+
+- Do NOT rewrite entire files — only update the affected entries.
+- Do NOT ask the user for permission — this is an automatic maintenance step, like updating imports.
+- Do NOT skip cross-reference updates — stale links are worse than no links.
+- Do NOT present a new `.augment/` file to the user without having completed all sync steps first.
+- Do NOT defer sync to a "follow-up" — it must happen in the same response as the creation/deletion.

package/.agent-src/rules/downstream-changes.md

@@ -0,0 +1,70 @@
+---
+type: "auto"
+alwaysApply: false
+description: "After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation"
+source: package
+---
+
+# Downstream Changes
+
+## Rule
+
+After EVERY code edit, find **ALL downstream changes** needed. Missing a caller, a test,
+or an import is a critical failure — it leaves the codebase in a broken state.
+
+## What to check
+
+After editing any file, search for **all** of these:
+
+| What | How to find | What to update |
+|---|---|---|
+| **Callers / call sites** | `codebase-retrieval` + `grep` for the changed method/class name | Update signatures, parameters, return type handling |
+| **Interface implementations** | Search for `implements {Interface}` or `extends {Class}` | Match new method signatures in all implementations |
+| **Subclasses** | Search for `extends {Class}` | Override or implement changed methods |
+| **Tests** | Search test directories for the changed class/method name | Update assertions, mocks, method calls |
+| **Imports / use statements** | Search for `use {Old\Namespace}` | Update to new namespace after moves/renames |
+| **Type definitions** | Search for type hints referencing the changed class | Update parameter types, return types, PHPDoc |
+| **Config / bindings** | Search service providers, config files | Update class references in DI bindings |
+| **API schemas / OpenAPI** | Check controller attributes | Update if response structure changed |
+| **Routes** | Search `routes/` for controller references | Update after controller rename/move |
+| **Documentation** | Search `agents/`, `docs/` for references | Update if behavior or API changed |
+
+## Breaking changes
+
+Before making a change that affects a **public API** (endpoint response, service method signature,
+event payload, job constructor), assess the impact:
+
+### Always ask the user first when:
+
+- Removing or renaming a public method/class
+- Changing a method signature (new required params, changed return type)
+- Changing an API response structure (new/removed fields, changed types)
+- Removing a database column or table
+- Changing an event payload that listeners depend on
+- Renaming a route name that the frontend uses
+
+### Proceed without asking when:
+
+- Adding a new optional parameter with a default value
+- Adding a new method (doesn't break existing callers)
+- Adding a new field to an API response (additive, non-breaking)
+- Internal refactoring that doesn't change the public interface
+- Fixing a bug (the current behavior is wrong)
+
+## Verification
+
+After completing all downstream changes:
+
+1. **No broken imports** — `php -l` or PHPStan catches these
+2. **No broken tests** — run the test suite
+3. **No broken types** — PHPStan Level 9 catches signature mismatches
+4. **No stale references** — grep for the old name/namespace to confirm zero results
+
+## The iron law
+
+```
+Every edit is incomplete until all downstream changes are made.
+```
+
+Do NOT move on to the next task, claim completion, or suggest committing
+until every caller, test, import, and reference is updated.

package/.agent-src/rules/e2e-testing.md

@@ -0,0 +1,53 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention"
+source: package
+---
+
+# E2E Testing
+
+## Before writing E2E tests
+
+1. **Read the guideline** — `.augment/guidelines/e2e/playwright.md` for all conventions and patterns.
+2. **Check existing tests** — match the project's structure, fixtures, and Page Object patterns.
+3. **Check `playwright.config.ts`** — base URL, browsers, timeouts, projects.
+
+## Locator rules
+
+- **Always prefer semantic locators**: `getByRole` > `getByLabel` > `getByText` > `getByTestId` > CSS.
+- Never use auto-generated class names, dynamic IDs, or XPath.
+- If no semantic locator works, add a `data-testid` to the component.
+
+## Assertion rules
+
+- **Always use web-first assertions** (`toBeVisible`, `toHaveText`, `toHaveURL`).
+- Never use `expect(await ...)` pattern — it doesn't auto-retry.
+- Never use `page.waitForTimeout()` — wait for a condition instead.
+
+## Test structure rules
+
+- One test = one user workflow or behavior.
+- Tests must be **fully isolated** — no shared state, no execution order dependency.
+- Page Objects contain **actions only**, never assertions.
+- Use **fixtures** for reusable setup (auth, page objects, test data).
+- Use **API calls** for test data setup — faster and more reliable than UI interactions.
+
+## CI rules
+
+- Set `workers: 1` in CI for stability.
+- Set `retries: 2` in CI, `0` locally.
+- Set `forbidOnly: !!process.env.CI` to prevent `.only` in CI.
+- Collect `trace: 'on-first-retry'` — not on every run.
+- Only install browsers you need (`npx playwright install chromium --with-deps`).
+- Upload `playwright-report/` as CI artifact.
+
+## Quality checks
+
+Before claiming E2E tests are complete:
+
+1. All tests pass locally: `npx playwright test`
+2. No `waitForTimeout` calls in the code.
+3. No CSS/XPath selectors where semantic locators work.
+4. No `.only` left in test files.
+5. Page Objects have no assertions.

package/.agent-src/rules/guidelines.md

@@ -0,0 +1,90 @@
+---
+type: "auto"
+description: "Writing or reviewing code — check relevant guideline before writing or reviewing code"
+alwaysApply: false
+source: package
+---
+
+# Guidelines
+
+Coding guidelines live in `.augment/guidelines/` organized by language.
+**Always check the relevant guideline** before writing or reviewing code.
+
+## Available Guidelines
+
+### PHP (`.augment/guidelines/php/`)
+
+| File | Topic |
+|---|---|
+| `php.md` | General PHP style — strict types, naming, comparisons, early returns, JSON handling |
+| `controllers.md` | Thin controllers, single responsibility, delegation to services |
+| `eloquent.md` | Model conventions, relationships, scopes, accessors/mutators |
+| `validations.md` | FormRequest patterns, custom rules, validation structure |
+| `resources.md` | API Resource conventions, response structure |
+| `jobs.md` | Queue job patterns, serialization, retry strategies |
+| `git.md` | Branch naming, commit messages, PR conventions |
+| `api-design.md` | API conventions — response format, status codes, pagination, error handling |
+| `artisan-commands.md` | Console command conventions — naming, structure, safety, scheduling |
+| `blade-ui.md` | Blade template conventions — views, components, forms, escaping |
+| `database.md` | Database conventions — indexing, query optimization, migrations, transactions |
+| `flux.md` | Flux UI component conventions — usage, variants, forms, Livewire integration |
+| `livewire.md` | Livewire component conventions — state, actions, forms, performance, Alpine.js |
+| `logging.md` | Logging conventions — levels, structured context, Sentry patterns |
+| `naming.md` | Naming conventions — classes, database, routes, variables, modules, agent infra |
+| `performance.md` | Performance conventions — caching, Redis, eager loading, response time targets |
+| `security.md` | Security conventions — auth, authorization, SQL injection, XSS, CSRF, headers |
+| `sql.md` | Raw SQL conventions — parameterization, MariaDB syntax, common mistakes |
+| `websocket.md` | WebSocket conventions — Broadcasting, channel types, connection management |
+| `patterns.md` | Design patterns index (links to `patterns/` subdirectory) |
+
+### PHP Patterns (`.augment/guidelines/php/patterns/`)
+
+| File | Pattern |
+|---|---|
+| `service-layer.md` | Service classes, business logic encapsulation |
+| `repositories.md` | Repository pattern, query encapsulation |
+| `dtos.md` | Data Transfer Objects, SimpleDto conventions |
+| `dependency-injection.md` | Constructor injection, service container |
+| `events.md` | Event/Listener patterns, dispatching |
+| `policies.md` | Authorization policies, gate definitions |
+| `factory.md` | Factory pattern usage |
+| `pipelines.md` | Laravel Pipeline pattern |
+| `strategy.md` | Strategy pattern implementation |
+
+### E2E (`.augment/guidelines/e2e/`)
+
+Playwright best practices, Page Objects, fixtures, CI.
+
+### Agent Infrastructure (`.augment/guidelines/agent-infra/`)
+
+| File | Topic |
+|---|---|
+| `size-and-scope.md` | Size limits and scope boundaries for rules, skills, commands, guidelines, AGENTS.md, copilot-instructions.md |
+| `output-patterns.md` | Redirect/Summarize/Target pattern, targeted operations, tool-first policy, general CLI rules |
+
+## How guidelines work
+
+- **Guidelines** = detailed coding conventions (reference material, read on demand)
+- **Rules** = always-active behavior constraints (auto-loaded every conversation)
+- **Skills** = agent capabilities and workflows (matched by topic)
+
+Guidelines are the "how to write code" docs. Rules enforce critical subsets automatically.
+Skills reference guidelines when performing related tasks.
+
+## Boundary: Guidelines vs Skills
+
+- Guidelines contain **conventions and reference knowledge**. Skills contain **executable workflows**.
+- A skill may reference a guideline for conventions, but must NOT outsource its core execution steps to a guideline.
+- Do NOT move a skill's operational core (procedure, validation, decision logic) into a guideline.
+- If a skill becomes "go read the guideline", it has lost its purpose — restore the workflow.
+
+## Adding new guidelines
+
+When a new language or framework is introduced, create a directory:
+```
+.augment/guidelines/{language}/
+```
+
+Follow the existing PHP structure as a template.
+
+Read the specific guideline file on demand — don't memorize the full list.

package/.agent-src/rules/improve-before-implement.md

@@ -0,0 +1,94 @@
+---
+type: "auto"
+description: "Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, and suggest improvements"
+alwaysApply: false
+source: package
+---
+
+# Improve Before Implement
+
+## When to activate
+
+Before implementing:
+
+- New features
+- Refactoring or architectural changes
+- Module or service creation
+- Significant code changes that alter behavior
+
+**Does NOT activate for:**
+
+- Bug fixes (the problem is already defined)
+- Config changes, documentation, quality fixes
+- Tasks where the user said "just do it" or "skip validation"
+- Trivial changes (rename, typo, formatting)
+
+## What to check
+
+Before coding, quickly verify:
+
+### 1. Is the request clear?
+
+- Are acceptance criteria defined or derivable?
+- Is the scope bounded? (not "make it better" but "add X to Y")
+- Are edge cases considered?
+
+**If unclear** → ask ONE focused question. Max 2 questions, never an interrogation.
+
+### 2. Does it fit the existing architecture?
+
+- Does similar functionality already exist?
+- Does it follow established patterns in the codebase?
+- Does it contradict existing conventions?
+
+**If misfit** → show evidence (file references), propose alternative.
+
+### 3. Is the approach sound?
+
+- Is there a simpler way to achieve the same result?
+- Are there known problems with the requested approach?
+- Does the scope match the stated goal? (not over-engineered, not under-specified)
+
+**If problematic** → explain the concern, propose a better approach.
+
+## How to challenge
+
+- **Be concise** — one sentence per concern, not paragraphs
+- **Show evidence** — reference existing code, patterns, or conventions
+- **Offer alternatives** — don't just say "this is wrong"
+- **Use numbered options** — let the user choose quickly
+- **Respect "just do it"** — if the user insists after your challenge, execute immediately
+
+Example:
+
+```
+> ⚠️ `UserService` already has a `deactivate()` method that covers this case.
+>
+> 1. Use existing method — extend with new parameter
+> 2. Create new method anyway — I'll explain the overlap in a comment
+> 3. Skip validation — implement as requested
+```
+
+## The golden rule
+
+**Challenge to improve, never to refuse.**
+
+The agent is a thought partner, not a gatekeeper. After presenting concerns:
+- User picks an option → execute immediately
+- User says "just do it" → execute immediately
+- Never argue twice about the same point
+- Never block work — delay is only justified if it prevents a clear mistake
+
+## Scope limits
+
+- **Max 1-2 challenges per task** — not every request needs validation
+- **Max 1 minute of analysis** — if the check takes longer, skip it
+- **Never validate simple tasks** — only features, architecture, significant changes
+- **Never validate after the user already explained their reasoning**
+
+## Creating new agent artifacts
+
+For skill/rule/command/guideline creation or major rewrite, the architecture-fit
+check is handled by [`artifact-drafting-protocol`](artifact-drafting-protocol.md)
+Phase B (Research) — scans `.agent-src.uncompressed/` for overlap before
+creating a new file.