@event4u/agent-config 1.9.1

package/.agent-src/skills/check-refs/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: check-refs
+description: "Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 60
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/check_references.py
+---
+
+# check-refs
+
+## When to use
+
+- Skill/rule/command/guideline/context renamed, moved, or deleted
+- Linking newly added artifact from elsewhere in `.agent-src.uncompressed/`
+- Pre-PR when changes touch cross-references
+- CI `check-refs` job failed and target ref needs locating
+
+NOT: body-only edits, frontmatter shape (use `lint-skills`), compressed pairs
+(use `task sync-check`).
+
+## Procedure
+
+1. **Inspect scope** — confirm at least one rename/move/remove since last clean
+   run. Body-only edits cannot break refs.
+2. **Dispatch via runtime** —
+
+   ```bash
+   python3 scripts/runtime_dispatcher.py run --skill check-refs
+   ```
+
+   Handler runs `python3 scripts/check_references.py`, captures stdout/stderr,
+   returns typed `ExecutionResult`.
+3. **Verify result** —
+   - `exit_code: 0` → all refs resolve
+   - `exit_code: 1` → broken refs — read stdout for `file:line → target`
+   - `status: timeout` → investigate, do not raise limit blindly
+   - `status: error` → interpreter or script missing, or wrong cwd
+
+## Output
+
+1. One-line summary: status, exit code, duration (ms)
+2. Count of broken refs if any
+3. First 10 broken refs: `file:line → missing-target`
+4. Next action: fix, re-run, or surface raw stdout
+
+## Gotcha
+
+- Checker is read-only — clean re-run must be produced by re-invoking, not
+  assumed
+- Running outside repo root → zero files inspected, false pass
+- Refs inside fenced code blocks may still be parsed — verify a "false
+  positive" before suppressing it
+
+## Do NOT
+
+- Do NOT call `check_references.py` directly when the intent is to exercise
+  the runtime path — go through the dispatcher
+- Do NOT raise `timeout_seconds` to mask a real slowdown
+- Do NOT add pipes/redirection — handler uses `shell=False`, argv form only
+
+## References
+
+- Skill: `lint-skills` — sibling pilot for skill/rule shape
+- Rule: `runtime-safety` — execution metadata constraints
+- Script: `scripts/check_references.py`, `scripts/runtime_dispatcher.py`,
+  `scripts/runtime_handler.py`

package/.agent-src/skills/code-refactoring/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: code-refactoring
+description: "Use when the user says "refactor this", "rename class", or "move method". Safely refactors PHP code — finds all callers, updates downstream dependencies, and verifies with quality tools."
+source: package
+---
+
+# refactorer
+
+## When to use
+
+Use this skill when renaming, moving, extracting, or restructuring code — any change that
+may have downstream effects on callers, interfaces, tests, documentation, or API contracts.
+
+
+Do NOT use when:
+- New feature development (use `feature-planning` skill)
+- Bug fixes that don't involve restructuring (use `bug-analyzer` skill)
+
+## Before refactoring
+
+1. **Read the agent docs** — check `agents/docs/` and `agents/contexts/` for the area you're refactoring.
+   For modules, also read `app/Modules/{Module}/agents/`. See the `project-docs` skill for the mapping.
+2. **Understand the scope** — what exactly needs to change and why?
+3. **Find ALL references** — use `codebase-retrieval` and `view` with `search_query_regex` to find every
+   caller, implementation, test, and configuration that references the code being changed.
+4. **Map the impact** — create a list of all files that will need changes.
+5. **Present the plan** — show the user what will be affected before starting.
+
+## Procedure: Refactor code
+
+### Step 1: Make the core change
+
+- Rename, extract, move, or restructure the target code.
+- Keep the change minimal and focused.
+
+### Step 2: Update all downstream dependencies
+
+For each affected file (from the impact analysis):
+
+- **Callers**: Update method calls, constructor arguments, imports.
+- **Interfaces / abstract methods**: Update all implementations to match new signatures.
+- **Subclasses**: Update overridden methods.
+- **Type hints / PHPDoc**: Update type references.
+- **Config / bindings**: Update service container bindings, route references, etc.
+- **Imports**: Add or update `use` statements.
+
+### Step 3: Update API layer (if controllers/endpoints are affected)
+
+When refactoring touches controllers, requests, resources, or routes:
+
+| Component | What to check and update |
+|---|---|
+| **Controller** | `__invoke()` signature, injected services, return type |
+| **FormRequest** | `authorize()`, `rules()`, validated field names |
+| **Resource** | `toArray()` field mapping, conditional fields, nested resources |
+| **OpenAPI Schema Attributes** | Request schemas (`ShowResourceRequestSchema`, `CreateResourceRequestSchema`, etc.) |
+| **OpenAPI Response Attributes** | Response schemas (`ShowResourceResponseSchema`, `CreateResourceResponseSchema`, etc.) |
+| **OpenAPI Error Attributes** | `ResourceNotFoundResponse`, `ValidationErrorResponse` |
+| **Custom Request Schemas** | Extended schema classes in `app/OpenApi/Schema/Request/v{N}/` |
+| **Route definition** | Route file in `routes/api/v{N}/`, route name, URL path, HTTP method |
+| **Route model binding** | Parameter name in route must match variable name in controller |
+| **Version inheritance** | If v1 extends v2 (or vice versa), check both versions |
+| **Module routes** | Module routes in `app/Modules/*/Routes/api.php` with version prefix |
+
+### Step 4: Update tests — with user approval
+
+**Before changing any test**, present a summary to the user:
+
+1. **List all affected tests** — which test files and which test cases need changes.
+2. **Describe what changes** — for each test, explain what assertion/setup changes and why.
+3. **Classify the change**:
+   - ✅ **Non-breaking**: Test adapts to internal refactoring (renamed class, moved method) —
+     same behavior, different code path. No API contract change.
+   - ⚠️ **Potentially breaking**: Test expectations change (new field in response, changed
+     validation rule, different error code) — this MAY affect API consumers.
+   - 🔴 **Breaking**: Test removes or changes existing API behavior (removed field, changed
+     endpoint URL, different response structure) — this WILL affect API consumers.
+4. **Ask for confirmation** (numbered options):
+   ```
+   > 1. Yes — apply test changes
+   > 2. No — I'll adjust the tests myself
+   ```
+5. Only proceed after the user confirms.
+
+**Rules for test changes:**
+- Do NOT change test expectations to make failing tests pass unless the refactoring intentionally
+  changes behavior. A failing test after refactoring usually means the refactoring has a bug.
+- Do NOT delete tests — adapt them to the new code structure.
+- Do NOT reduce test coverage — if you split a class, split the test too.
+
+### Step 5: Verify with quality tools
+
+Run quality tools after each significant step — do NOT batch everything to the end:
+
+- Run PHPStan: `vendor/bin/phpstan analyse` (see `quality-tools` skill for detection).
+- If PHPStan finds new errors from the refactoring → fix immediately before continuing.
+- Run Rector + ECS: `vendor/bin/rector process && vendor/bin/ecs check --fix`.
+- Run PHPStan again after Rector (Rector can introduce issues).
+
+### Step 6: Run tests
+
+- Run tests related to the changed code first (`php artisan test --filter=...`).
+- Then run the full test suite (`php artisan test`).
+- All tests must pass before the refactoring is considered complete.
+
+### Step 7: Update documentation
+
+After the code changes are verified, update all affected documentation:
+
+| Documentation layer | When to update | Location |
+|---|---|---|
+| **Project docs** | When conventions, patterns, or key files change | `agents/docs/*.md` |
+| **Project contexts** | When architecture or high-level flow changes | `agents/contexts/*.md` |
+| **Module agent docs** | When module-specific behavior changes | `app/Modules/*/agents/` |
+| **Module Docs/** | When module internals change | `app/Modules/*/Docs/` |
+| **AGENTS.md** | When project-wide conventions change | `AGENTS.md` |
+| **Roadmaps** | When a roadmap step is completed | `agents/roadmaps/*.md` |
+
+**Rules for doc updates:**
+- If you rename a class/method referenced in docs → update the reference.
+- If you move files → update all path references.
+- If you change a pattern → update the pattern description.
+- If you add a new convention → document it.
+- Do NOT create new docs unless the refactoring introduces a genuinely new concept.
+
+## Common refactoring patterns
+
+### Rename (method, class, property)
+1. Find all usages → update all usages → update docs → run PHPStan → run tests.
+
+### Extract method / class
+1. Create the new method/class → move logic → update caller → update docs → run PHPStan → run tests.
+
+### Move class to different namespace
+1. Move file → update namespace → find all `use` statements → update imports → update docs → run PHPStan.
+
+### Change method signature
+1. Update the method → find all callers → update each caller → present test changes → update docs → run PHPStan.
+
+### Change API endpoint
+1. Update controller + request + resource + OpenAPI schemas + route → present test changes →
+   update docs (`agents/docs/controller.md`, `agents/docs/api-resources.md`) → run PHPStan → run tests.
+
+### Replace implementation (e.g. switch service)
+1. Create new implementation → update binding → find all direct references → update → present test
+   changes → update docs → run PHPStan → run tests → remove old implementation.
+
+### Move/restructure module
+1. Move files → update namespaces → update `ModuleServiceProvider` if needed → update module routes →
+   update module agent docs → update project contexts → run PHPStan → run tests.
+
+## Safety rules
+
+- **Never skip the caller search** — missing a caller is the #1 cause of broken refactorings.
+- **Never remove old code before verifying** the new code works everywhere.
+- **Never change test expectations without user approval** — explain what changes and why first.
+- **Run PHPStan after every step**, not just at the end.
+- **Run tests after every step**, not just at the end.
+- **Update docs after code changes** — stale docs are worse than no docs.
+- **Do NOT commit or push** — only apply local changes.
+- **Do NOT refactor code outside the requested scope** — no drive-by cleanups.
+- If the refactoring reveals more work than expected, **stop and discuss with the user**.
+
+## Cross-References
+
+| Skill | Relationship |
+|---|---|
+| `project-docs` | Which docs to read before refactoring a specific area |
+| `agent-docs-writing` | When to create/update agent documentation |
+| `api-endpoint` | Full API endpoint structure (controller + request + resource + schema) |
+| `php-coder` | PHP coding conventions to follow in refactored code |
+| `pest-testing` | Test conventions when adapting tests |
+| `openapi` | OpenAPI schema attribute patterns |
+
+
+## Output format
+
+1. Refactored code with clear separation of changes
+2. Before/after comparison for key changes
+3. Test verification confirming no behavior change
+
+## Gotcha
+
+- Always find ALL callers before renaming — the model frequently misses usages in tests and config files.
+- Don't refactor and add features in the same commit — separate concerns for reviewability.
+- The model tends to "improve" code it's refactoring — stay scope-focused, refactor means same behavior.
+- Run the full test suite after every refactoring step — don't batch multiple refactors.
+
+## Do NOT
+
+- Do NOT refactor without running tests before and after.
+- Do NOT change test expectations without explicit user approval.
+- Do NOT refactor across module boundaries without checking downstream.
+
+## Auto-trigger keywords
+
+- refactoring
+- rename
+- move class
+- change signature

package/.agent-src/skills/code-review/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: code-review
+description: "Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards."
+source: package
+---
+
+# code-review
+
+## When to use
+
+Use this skill when:
+- Reviewing a PR (own or someone else's)
+- Self-reviewing local changes before creating a PR
+- Responding to review feedback on your PR
+- The user asks to "review", "check", or "look at" code changes
+
+## Procedure: Review code
+
+### Mindset
+
+- **Be thorough but pragmatic** — catch real bugs, not style nitpicks that tools handle.
+- **Understand intent first** — read the PR description, linked ticket, and commit messages before looking at code.
+- **Check the full picture** — a change in a service may require changes in tests, migrations, docs.
+- **Assume good intent** — suggest improvements, don't criticize.
+
+### Review order
+
+1. **Understand the goal** — what is this change trying to achieve?
+2. **Architecture** — does the approach make sense? Right layer? Right pattern?
+3. **Correctness** — does it actually work? Edge cases? Error handling?
+4. **Quality** — types, naming, readability, DRY, SOLID?
+5. **Security** — input validation, authorization, injection?
+6. **Performance** — N+1 queries, missing indexes, unbounded queries?
+7. **Tests** — are new paths covered? Are existing tests still valid?
+8. **Conventions** — does it follow project standards?
+
+## Review checklist
+
+### Code quality
+
+| Check | What to look for |
+|---|---|
+| **Strict types** | `declare(strict_types=1)` in new files, typed properties/params/returns |
+| **PSR-12** | Coding style, line length ≤120, trailing commas, Yoda comparisons |
+| **Naming** | Clear, descriptive names. `camelCase` vars, `snake_case` array keys, `UPPER_SNAKE` constants |
+| **Early returns** | No deep nesting. Guard clauses at the top. |
+| **Single responsibility** | Each class/method does one thing. Controllers are thin. |
+| **No magic** | No magic properties on models (use getters/setters). No `$request->input()` without FormRequest. |
+| **PHPDoc** | Only where type hints are insufficient (generics, complex arrays). No redundant docblocks. |
+
+### Architecture
+
+| Check | What to look for |
+|---|---|
+| **Layer separation** | Business logic in services, not controllers. Models have no business logic. |
+| **Single-action controllers** | New controllers use `__invoke()`. No multi-action controllers. |
+| **FormRequest** | Every controller has a dedicated FormRequest. No inline `$request->validate()`. |
+| **API Resources** | Controllers return Resources, never raw models or `response()->json()`. |
+| **DTOs** | Structured data transfer between layers, not raw arrays. |
+| **Dependency injection** | Constructor injection, no `new Service()` or `app()` calls in business logic. |
+
+### Database & Performance
+
+| Check | What to look for |
+|---|---|
+| **N+1 queries** | Relationship access in loops without eager loading |
+| **Missing indexes** | New columns used in WHERE/JOIN without index |
+| **Unbounded queries** | `Model::all()` or queries without pagination/limit |
+| **Raw SQL** | Parameterized queries only. No string concatenation with user input. |
+| **Migrations** | Reversible (has `down()`). Correct connection. Correct table prefix. |
+| **Money** | Uses `decimal` or `Math` helper, never `float` |
+
+### Security
+
+| Check | What to look for |
+|---|---|
+| **Authorization** | Policy check in FormRequest or middleware. No unprotected endpoints. |
+| **Input validation** | All user input validated via FormRequest rules. |
+| **Mass assignment** | No `$model->fill($request->all())` without `$fillable`/`$guarded`. |
+| **SQL injection** | No raw queries with unescaped user input. |
+| **XSS** | Blade output escaped (`{{ }}` not `{!! !!}`) unless intentional. |
+| **Sensitive data** | No secrets, tokens, or passwords in code or logs. |
+
+### Tests
+
+| Check | What to look for |
+|---|---|
+| **Coverage** | New code paths have tests. Bug fixes have regression tests. |
+| **Test quality** | Tests verify behavior, not implementation details. |
+| **Pest syntax** | Correct Pest conventions. No `readonly`/`final` on test classes. |
+| **Seeders** | Test data via seeders (or factories where allowed). |
+| **Assertions** | Meaningful assertions. Not just "no exception thrown". |
+| **Flaky risks** | Time-dependent tests use `travel()`. No reliance on execution speed. |
+
+## Before creating a PR
+
+1. Run quality pipeline: PHPStan → Rector → ECS → PHPStan (see `quality-tools` skill for commands)
+2. Run tests: `make test` (or project equivalent)
+3. Ensure CI passes on the branch.
+4. Self-review the diff: `git diff origin/main..HEAD`
+
+## Receiving feedback
+
+### The response pattern
+
+When receiving code review feedback, follow this sequence:
+
+1. **READ** — Complete feedback without reacting.
+2. **UNDERSTAND** — Restate the requirement in your own words (or ask if unclear).
+3. **VERIFY** — Check the suggestion against codebase reality.
+4. **EVALUATE** — Is it technically sound for THIS codebase?
+5. **RESPOND** — Technical acknowledgment or reasoned pushback.
+6. **IMPLEMENT** — One item at a time, test each.
+
+If **any item is unclear**, STOP — do not implement anything yet. Items may be related;
+partial understanding leads to wrong implementation.
+
+### No performative agreement
+
+- **Do NOT** reply with "Great point!", "You're absolutely right!", "Excellent catch!" or similar.
+- **Instead:** Just fix it. "Fixed." or "Updated — [brief description of what changed]."
+- Actions speak louder than words — the code itself shows you heard the feedback.
+
+### Source-specific handling
+
+**Internal team feedback** (trusted colleagues):
+- Implement after understanding — no need for deep skepticism.
+- Still ask if scope is unclear.
+- Skip to action or technical acknowledgment.
+
+**External / Copilot / bot feedback** (less context):
+- Check: Technically correct for THIS codebase?
+- Check: Does it break existing functionality?
+- Check: Is there a reason for the current implementation?
+- Check: Does the reviewer understand the full context?
+- **YAGNI check:** If the reviewer suggests "implementing properly", grep the codebase
+  for actual usage. If unused → suggest removing (YAGNI).
+- If it conflicts with existing architectural decisions → discuss with the team first.
+
+### When to push back
+
+Push back when:
+- Suggestion breaks existing functionality.
+- Reviewer lacks full context.
+- Violates YAGNI (unused feature).
+- Technically incorrect for this stack.
+- Legacy/compatibility reasons exist.
+- Conflicts with architectural decisions.
+
+How: Use technical reasoning, not defensiveness. Reference working tests/code.
+
+### Addressing PR comments systematically
+
+When working through review comments on a PR:
+
+1. **List** all comments and review threads (`gh pr view --comments`).
+2. **Categorize**: blocking → simple fixes → complex fixes.
+3. **Clarify** anything unclear BEFORE implementing.
+4. **Fix** one at a time, test each.
+5. **Reply in the thread** — not as a top-level PR comment.
+
+```bash
+# Reply to a specific review comment thread
+gh api repos/{owner}/{repo}/pulls/comments/{comment_id}/replies \
+  -f body="Fixed in latest commit."
+```
+
+## Output format
+
+When reviewing code, structure feedback by severity:
+
+```
+🔴 **Blocker** — must fix before merge
+Description of the issue and why it's critical.
+
+🟡 **Suggestion** — should fix, improves quality
+Description and suggested improvement.
+
+🟢 **Nit** — optional, minor improvement
+Description.
+```
+
+Group related findings. Don't repeat what linters/PHPStan already catch — focus on
+logic, architecture, and things tools can't detect.
+
+## Adversarial review
+
+Before creating a PR or presenting code changes, run the **`adversarial-review`** skill.
+Focus on the "Code changes / Refactoring" attack questions.
+
+## Auto-trigger keywords
+
+- code review
+- PR review
+- pull request
+- review checklist
+- review feedback
+- review changes
+- check my code
+
+## Gotcha
+
+- Don't rewrite code that works and is tested just because you'd write it differently.
+- The model tends to suggest changes that are out of scope — stay focused on the PR's intent.
+- "I would prefer X" is not a valid review comment unless X prevents a bug or violates a rule.
+- Always check if the PR has tests — missing tests is always worth flagging.
+
+## Do NOT
+
+- Do NOT approve without actually reading the code.
+- Do NOT agree with review comments without verifying them against the codebase.
+- Do NOT use performative language when responding to feedback ("Great point!", "Excellent catch!").
+- Do NOT nitpick style issues that ECS/Rector handle automatically.
+- Do NOT merge without CI passing and quality checks green.

package/.agent-src/skills/command-routing/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: command-routing
+description: "Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+---
+
+# commands
+
+## When to use
+
+Triggered when user invokes a slash command. The `slash-commands` rule (always loaded) handles core behavior — this skill adds context inference and GitHub API patterns.
+
+## Procedure: Execute a command
+
+1. **Match command** — Find the command file in `.augment/commands/` or `agents/overrides/commands/`.
+2. **Infer inputs** — Before asking the user, try to infer values (see table below).
+3. **Execute steps** — Follow the command steps in exact order.
+4. **Verify output** — Confirm expected result was produced (commit, PR, file change, etc.).
+
+Before asking the user for input, try to infer it:
+
+| Input needed | How to infer |
+|---|---|
+| Jira ticket | Extract from branch name (`fix/DEV-1234-...` → `DEV-1234`) |
+| Default branch | `git symbolic-ref refs/remotes/origin/HEAD` or assume `main` |
+| Project type | Check for `artisan` (Laravel) or `composer.json` (Composer) |
+| Module name | Extract from current working directory or file path |
+| Current branch | `git branch --show-current` |
+
+Only ask the user if inference fails and the command cannot proceed without the value.
+
+## Command locations
+
+| Location | Scope |
+|---|---|
+| `.augment/commands/` | Shared commands (work across projects) |
+| `agents/overrides/commands/` | Project-specific overrides (used instead of original) |
+
+## GitHub API: Replying to PR review comments
+
+When commands reply to PR review comments (e.g. `/fix-pr-bot-comments`):
+
+### 1. Read the setting
+
+Read `github.pr_reply_method` from `.agent-settings.yml`:
+
+| Value | API call |
+|---|---|
+| `replies_endpoint` | `POST /repos/{owner}/{repo}/pulls/comments/{comment_id}/replies` with `{"body": "..."}` |
+| `create_review_comment` | `POST /repos/{owner}/{repo}/pulls/{number}/comments` with `{"body": "...", "in_reply_to": comment_id}` |
+| `auto` | Try `replies_endpoint` first. If it works → update setting. If 404/error → try `create_review_comment`. |
+
+### 2. Bot icon prefix
+
+Read `project.pr_comment_bot_icon` from `.agent-settings.yml`:
+- `true` → prefix reply body with `🤖 `.
+- `false` or not set → no prefix.
+
+### 3. API call rules
+
+- `data` must be clean JSON with ONLY required API fields — no `summary` or extra params.
+- Each reply is a separate API call — do NOT batch.
+- On first success with `auto` → update `github.pr_reply_method` in `.agent-settings.yml` to the method that worked.
+
+### Validate
+
+1. Verify all command steps were executed in order.
+2. Confirm expected output was produced (commit, PR, file change, etc.).
+3. Check that no step was skipped or improvised.
+
+## Output format
+
+1. Command executed — all steps completed in order
+2. Final result or summary as defined by the command
+
+## Gotcha
+
+- Don't ask questions when executing a command unless the command says "ask the user".
+- Don't add opinions during execution — follow steps exactly.
+- If a step fails, stop and report — don't improvise.
+
+## Do NOT
+
+- Do NOT ask questions during command execution unless the command says "ask the user".
+- Do NOT add opinions or summaries — execute steps exactly as written.
+- Do NOT improvise when a step fails — stop and report.
+
+## Auto-trigger keywords
+
+- slash command
+- command execution
+- agent command