@event4u/agent-config 1.9.1

package/.agent-src/skills/file-editor/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: file-editor
+description: "Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  allowed_tools: []
+---
+
+# file-editor
+
+## When to use
+
+This skill applies **automatically** whenever:
+- The agent creates or edits a file using `save-file` or `str-replace-editor`
+- The agent wants to show the user a file they should review
+
+Do NOT use when:
+- Only reading files (no edits)
+- Running commands or tests
+- The `personal.open_edited_files` setting is `false`
+
+## Procedure: Open files in IDE
+
+1. **Read settings** — Check `personal.open_edited_files` and `personal.ide` in `.agent-settings.yml`.
+2. **Skip if disabled** — If `personal.open_edited_files` is `false`, do nothing.
+3. **Open files** — Use the IDE CLI command to open each edited file.
+4. **Verify** — Confirm the command succeeded (exit code 0).
+
+## Settings file
+
+Settings are stored in `.agent-settings.yml` (project root, git-ignored).
+See `.augment/templates/agent-settings.md` for the full settings reference.
+
+Relevant settings for this skill:
+
+| Key | Values | Default | Description |
+|---|---|---|---|
+| `personal.ide` | `code`, `phpstorm` | _(empty)_ | CLI command to open files |
+| `personal.open_edited_files` | `true`, `false` | `false` | Whether to auto-open edited files |
+
+## Behavior
+
+### 1. Read settings
+
+At the start of a conversation (or on first file edit), read `.agent-settings.yml`:
+
+```bash
+cat .agent-settings.yml 2>/dev/null
+```
+
+- If the file doesn't exist → **do not open files**. Suggest running `/config-agent-settings`.
+- If `personal.open_edited_files: false` → do nothing.
+- If `personal.open_edited_files: true` and `personal.ide` is set → open files after edits.
+
+### 2. Open files after edits
+
+After editing one or more files, open them using the `ide` setting.
+**Always jump to the first edited line.** The syntax depends on the IDE:
+
+**PhpStorm** (`personal.ide: phpstorm`):
+```bash
+phpstorm --line {line} {file}
+```
+
+**VS Code** (`personal.ide: code`):
+```bash
+code -g {file}:{line}
+```
+
+For multiple files, run one command per file:
+```bash
+# PhpStorm
+phpstorm --line 42 app/Models/User.php
+phpstorm --line 15 app/Services/UserService.php
+
+# VS Code
+code -g app/Models/User.php:42
+code -g app/Services/UserService.php:15
+```
+
+If the line number is unknown (e.g. new file), omit the line parameter:
+```bash
+phpstorm app/Models/User.php
+code app/Models/User.php
+```
+
+### Rules
+
+- **Batch opens** — collect all files from a single logical edit operation and open them as one batch (one IDE command per file).
+- **No duplicates** — don't open the same file twice in one batch.
+- **Silent on failure** — if the IDE command fails, log it but don't interrupt the workflow.
+- **Never open test output** — don't open files just because they appeared in test results.
+- **Only edited files** — only open files the agent actively created or modified, not files that were only read.
+- **Respect the setting** — if `personal.open_edited_files: false` or `.agent-settings.yml` doesn't exist, never open files.
+
+## IDE CLI commands
+
+| IDE | Command | Install |
+|---|---|---|
+| VS Code | `code {file}` | Shell Command: Install 'code' in PATH |
+| PhpStorm | `phpstorm {file}` | JetBrains Toolbox CLI or `Create command-line launcher` in PhpStorm |
+
+## Output format
+
+1. Files opened in the configured IDE (if enabled)
+2. No output if `personal.open_edited_files` is disabled
+
+## Auto-trigger keywords
+
+- open file
+- open in editor
+- show in IDE
+- file editor settings
+- configure IDE
+
+## Gotcha
+
+- Check `.agent-settings.yml` for `personal.open_edited_files` before opening anything — the user may have disabled it.
+- Don't open files during batch operations (e.g., fixing 20 PHPStan errors) — only open when specifically relevant.
+- PHPStorm sometimes locks files when opening — wait briefly before editing the same file.
+
+## Do NOT
+
+- Do NOT open files without checking `.agent-settings.yml` first.
+- Do NOT prompt the user about IDE settings during normal work — suggest `/config-agent-settings` instead.
+- Do NOT open files that were only read, not edited.
+- Do NOT open more than 10 files at once — summarize instead.

package/.agent-src/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: finishing-a-development-branch
+description: "Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'."
+source: package
+---
+
+# finishing-a-development-branch
+
+## When to use
+
+* Implementation of a feature or bug fix is complete on a development branch
+* All planned commits are in, user is ready to hand off
+* You are about to say "done" and suggest the next action
+* Branch has been idle and the user wants to decide its fate
+
+Do NOT use when:
+
+* Still implementing — use targeted verification, not the ship gate
+* A PR already exists and is mid-review — use [`receiving-code-review`](../receiving-code-review/SKILL.md)
+* Only documentation changed — simplify to commit + PR without full gate
+
+## Goal
+
+Route a finished branch to its next state **with evidence** — merged,
+pushed for PR, parked, or discarded. Never let a half-verified branch
+become a PR. Never destroy work without explicit confirmation.
+
+## The Iron Law
+
+```
+NO MERGE, NO PR, NO DISCARD WITHOUT VERIFIED TESTS + EXPLICIT CHOICE.
+```
+
+## Procedure
+
+### 1. Inspect branch state
+
+Before presenting options, check:
+
+* `git status` — clean or dirty?
+* `git log --oneline <base>..HEAD` — what commits are actually on this branch
+* `git branch --show-current` — branch name to operate on
+* Remote state — is the branch pushed? Is there an open PR already?
+
+PR already exists → **stop**, route to [`receiving-code-review`](../receiving-code-review/SKILL.md)
+or [`fix-pr-comments`](../../commands/fix-pr-comments.md).
+
+### 2. Verify readiness
+
+Run the full end-of-work gate — see [`verify-before-complete`](../verify-before-complete/SKILL.md):
+
+1. Targeted tests green
+2. Full test suite green
+3. Quality pipeline (PHPStan → Rector dry-run → ECS → PHPStan) green
+4. `git status` clean — no unstaged files, no stray files
+5. Branch pushed or explicitly marked local-only
+
+Any step fails → **stop**. Report failure, do not present ship options.
+
+### 3. Determine the base branch
+
+```bash
+# Default: main
+BASE=main
+
+# Stacked PR: parent branch
+BASE=$(git config branch.$(git branch --show-current).merge | sed 's|refs/heads/||')
+```
+
+Ambiguous → ask: *"This branch splits from `<guess>` — correct?"*.
+
+### 4. Present four options — numbered, no narration
+
+```
+Implementation is verified. What now?
+
+1. Open a Pull Request on <base-branch>
+2. Merge locally into <base-branch> (for projects without a PR flow)
+3. Keep the branch as-is — I'll handle it later
+4. Discard all work on this branch
+```
+
+No recommendations unless the user asks.
+
+### 5a. Option 1 — Open a PR
+
+1. Update branch → [`prepare-for-review`](../../commands/prepare-for-review.md)
+2. Self-review → [`review-changes`](../../commands/review-changes.md)
+3. Write description → [`create-pr-description`](../../commands/create-pr-description.md)
+4. Open PR → [`create-pr`](../../commands/create-pr.md)
+5. Confirm PR opened green, not red
+
+Surrounding discipline → [`requesting-code-review`](../requesting-code-review/SKILL.md).
+
+### 5b. Option 2 — Merge locally
+
+Use only for no-PR projects (solo, spike, private tooling).
+
+```bash
+git checkout <base-branch>
+git pull --ff-only
+git merge --no-ff <feature-branch>
+# Re-run the full test suite on the merged tree
+<test command>
+# Only if green:
+git branch -d <feature-branch>
+```
+
+Post-merge test fails → `git reset --hard ORIG_HEAD`, fix on feature branch, restart.
+
+### 5c. Option 3 — Keep as-is
+
+* Push to origin if not already pushed
+* Report branch name and last commit SHA
+* Do not delete the worktree, do not force-push
+
+### 5d. Option 4 — Discard
+
+**Confirmation gate** — typed answer, not "y":
+
+```
+This will permanently remove:
+- Local branch <name>
+- Remote branch <name> (if pushed)
+- Commits: <list of SHAs + subjects>
+
+Type "discard <name>" to confirm.
+```
+
+Only on exact match:
+
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+# Remove remote only if the user confirms a second time
+git push origin --delete <feature-branch>
+```
+
+Log discarded SHAs so work can be recovered via `git reflog`.
+
+### 6. Clean up worktrees
+
+Branch in a `git worktree`:
+
+* Options 1, 2, 4 → `git worktree remove <path>` after terminal state
+* Option 3 → keep the worktree
+
+## Output format
+
+After chosen option completes:
+
+1. **What happened** — one sentence ("PR #123 opened", "Merged as `abcdef`", "Discarded")
+2. **Evidence** — exit codes / PR URL / commit SHA
+3. **Cleanup state** — worktree removed/kept, branch deleted/retained
+4. **Next step** — "Awaiting review", "Main is one commit ahead", etc.
+
+## Gotchas
+
+* Option 1 on red CI — PR opens but not reviewable; check CI status
+* Option 2 with ff-only on diverged base silently aborts — check exit code
+* Option 4 on a branch that is upstream of another local branch — orphans the dependent
+* Force-push after PR open can lose reviewer line-comments
+* `-d` refuses unmerged; `-D` forces — only use `-D` inside confirmed discard
+* Stacked PRs base ≠ `main` — opening PR to `main` invalidates the stack
+
+## Do NOT
+
+* Do NOT present ship options while tests or quality are red
+* Do NOT add rationale to the four options — user decides
+* Do NOT discard without typed confirmation including branch name
+* Do NOT force-delete remote without user confirmation
+* Do NOT silently change the base between verification and ship
+* Do NOT mix other cleanup into the discard step
+
+## Anti-patterns
+
+* Three options + "or discard" — buries destructive option
+* Running the full gate here *and* at start of `create-pr` — duplicate
+* Merge local + open PR at the same time
+* Asking "ready to ship?" without the four numbered options
+
+## When to hand over to another skill / command
+
+* Pre-merge verification → [`verify-before-complete`](../verify-before-complete/SKILL.md)
+* Rebasing stack → [`prepare-for-review`](../../commands/prepare-for-review.md)
+* Last-minute commits → [`commit`](../../commands/commit.md), [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
+* Self-review → [`review-changes`](../../commands/review-changes.md)
+* Creating PR → [`create-pr`](../../commands/create-pr.md)
+* Review comments → [`receiving-code-review`](../receiving-code-review/SKILL.md)
+
+## Validation checklist
+
+* [ ] Full gate verified green in this turn
+* [ ] Base branch determined and confirmed when ambiguous
+* [ ] Exactly four numbered options presented, no narration
+* [ ] User's choice recorded literally, not reinterpreted
+* [ ] Sub-procedure for chosen option completed end-to-end
+* [ ] Worktree handled per option
+* [ ] Destructive actions had typed confirmation with branch name
+* [ ] Final report includes evidence (PR URL, SHA, exit code)

package/.agent-src/skills/flux/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: flux
+description: "Use when writing Laravel Flux UI components — the official Livewire component library by the Laravel team. Covers components, slots, and variants."
+source: package
+---
+
+# flux
+
+## When to use
+
+Use when building UI with Flux components in a project that uses `livewire/flux`.
+
+Do NOT use when:
+- Raw Blade templates without Flux (use `blade-ui` skill)
+- Livewire component logic (use `livewire` skill)
+
+## Procedure: Create a Flux view
+
+### Step 0: Inspect
+
+1. Confirm Flux is installed — check `composer.json` for `livewire/flux`.
+2. Check existing views — match Flux component usage patterns.
+3. Check Flux docs — https://fluxui.dev/docs for latest API.
+
+### Step 1: Build the view
+
+1. Use `<flux:*>` components instead of raw HTML.
+2. Use `variant` prop for styling (not custom Tailwind for standard styles).
+3. Use `wire:model` for Livewire binding.
+4. Use `label` prop on form fields (accessibility).
+
+### Step 2: Validate
+
+1. No raw HTML form elements where Flux equivalents exist.
+2. No manual error rendering (Flux has built-in validation display).
+3. No conflicting Tailwind classes overriding Flux styles.
+
+## Conventions
+
+→ See guideline `php/flux.md` for component reference, variants, forms, icons.
+
+## Output format
+
+1. Blade view using Flux components with correct props and slots
+2. Livewire component class if interactive behavior is needed
+
+## Gotcha
+
+- The model tends to use old Flux API syntax — always check latest docs.
+- Flux has built-in validation display — don't add manual error rendering alongside it.
+- Don't mix Flux with raw HTML form elements in the same form.
+
+## Do NOT
+
+- Do NOT use raw `<input>`, `<select>`, `<button>` when Flux equivalents exist.
+- Do NOT override Flux styles with conflicting Tailwind — use variants or slots.
+- Do NOT skip the `label` prop on form fields — accessibility.
+
+## Auto-trigger keywords
+
+- Flux UI
+- Livewire components
+- Flux component
+- Laravel Flux

package/.agent-src/skills/git-workflow/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: git-workflow
+description: "Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git."
+source: package
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: ["github"]
+---
+
+# git-workflow
+
+## When to use
+
+Use when preparing PRs, finishing branches, or following the team's Git workflow.
+
+Do NOT use when:
+- Code writing or review (use `php-coder` or `code-review` skill)
+- CI/CD pipeline changes (use `github-ci` skill)
+
+## Conventions
+
+→ See guideline `guidelines/php/git.md` for branch naming, commit messages, PR conventions.
+→ See `commit-conventions` rule for commit format, types, and scope rules.
+→ Use `conventional-commits-writing` skill for generating/reviewing commit messages.
+
+## Procedure: Before opening a PR
+
+1. Run quality pipeline: PHPStan → Rector → ECS → PHPStan (see `quality-tools` skill).
+2. Run tests: `php artisan test`.
+3. Rebase onto `main`.
+4. Fill in PR template completely.
+
+## Procedure: Finish a branch
+
+When implementation is complete and all tests pass:
+
+```
+Work complete. What would you like to do?
+
+1. Push and create a Pull Request
+2. Keep the branch as-is (I'll handle it later)
+3. Discard this work
+```
+
+### Option 1: Push and create PR
+
+1. Run quality pipeline + tests.
+2. `git push -u origin <branch>`.
+3. `gh pr create` using PR template.
+
+### Option 2: Keep as-is
+
+Report: "Branch `<name>` preserved locally." — do nothing.
+
+### Option 3: Discard
+
+**Confirm first** — list branch name and commit count.
+Wait for explicit confirmation. Then:
+```bash
+git checkout main
+git branch -D <feature-branch>
+```
+
+## PR template
+
+The project uses `.github/pull_request_template.md`:
+1. Jira ticket link (badge)
+2. Description — what and why
+3. Type of change
+4. Checklist (docs, rebase, quality, review, tests, QA)
+5. Links + screenshots
+
+## Default branch
+
+- `main` is default/production branch.
+- Merge strategy: merge commits (not squash).
+
+## Output format
+
+1. Commits following conventional commit format
+2. PR description with structured sections (if creating PR)
+
+## Gotcha
+
+- Never commit/push/merge without explicit user permission.
+- Keep subject line under 72 chars.
+- Don't rebase shared branches.
+- `git stash` can lose work — prefer WIP commits.
+
+## Do NOT
+
+- Do NOT commit directly to `main`.
+- Do NOT push without running quality tools first.
+- Do NOT force-push to shared branches.
+
+## Auto-trigger keywords
+
+- Git workflow
+- branch naming
+- commit message
+- PR convention

package/.agent-src/skills/github-ci/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: github-ci
+description: "Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'."
+source: package
+---
+
+# github-ci
+
+## When to use
+
+Use this skill when working with GitHub Actions workflows, CI pipeline configuration, or understanding the automated quality and deployment process.
+
+## Procedure: Modify CI workflows
+
+1. Read `.github/workflows/` to understand the full pipeline.
+2. Check `AGENTS.md` for quality tool commands and testing setup.
+3. Read `.augment/commands/fix-ci.md` for CI failure debugging workflow.
+
+## Workflow overview
+
+### Quality pipeline (`quality-tests.yml`)
+
+Triggered on: `pull_request` to `main`, `workflow_dispatch`
+
+Read `.github/workflows/` to discover the actual job matrix. Common patterns:
+
+- PHP version is **extracted from Dockerfile** (`ARG PHP_VERSION`), not hardcoded.
+- Static analysis may run on larger runners for memory.
+- Tests run in **parallel** with a matrix strategy per test suite.
+- Branch comparison for dead code and API docs.
+
+### Deployment workflows
+
+| Workflow | Trigger | Environment |
+|---|---|---|
+| `deploy-review.yaml` | PR with `review-env` label | Review (ephemeral) |
+| `deploy-sta.yaml` | Push to `main` | Stage |
+| `deploy-pro.yaml` | Tag `release-X.Y.Z` or schedule (Mon 8AM) | Production |
+| `deploy.yml` | After "Static Code Analysis" succeeds on `main` | Envoyer trigger |
+| `module-deploy.yaml` | Reusable workflow (called by others) | Parameterized |
+
+### Other workflows
+
+| Workflow | Purpose |
+|---|---|
+| `pr-review-gate.yaml` | Points-based review system (see `code-review` skill) |
+| `destroy-review.yaml` | Cleanup ephemeral review environments |
+| `add-labels.yml` | Auto-label PRs |
+| `apply-pr-template.yaml` | Apply PR description template |
+| `validate-deployment-files.yaml` | Validate AWS deployment configs |
+| `template-db-dump.yaml` | Database dump utility |
+
+## Conventions
+
+### Workflow structure
+
+- Use **pinned action versions** with SHA hashes (not tags): `actions/checkout@<sha> # v6.0.2`
+- Use **concurrency groups** to prevent duplicate runs: `group: ${{ github.workflow }}-${{ github.ref }}`
+- Use **`fail-fast: false`** in matrix strategies for independent job execution.
+- Extract shared logic into **reusable workflows** (`module-deploy.yaml` pattern).
+
+### Composer auth
+
+Every workflow that installs dependencies needs:
+1. `COMPOSER_AUTH` secret validation (check if set, validate JSON).
+2. Fallback handling if auth is missing or masked.
+
+### PHP version
+
+- **Never hardcode** the PHP version in workflows.
+- Always extract from Dockerfile: `awk -F= '/^ARG PHP_VERSION/ {print $2}' .docker/Dockerfile`
+- Pass via job outputs to dependent jobs.
+
+### Runners
+
+Check `.github/workflows/` for the runner types used. Common patterns:
+- Standard runners (`ubuntu-latest`) for light jobs.
+- Larger or custom runners for heavy jobs (static analysis, tests).
+- ARM runners if the project deploys to ARM-based infrastructure.
+
+### Environment variables
+
+- Use `env:` at job level for shared secrets.
+- Use `$GITHUB_OUTPUT` for passing data between steps.
+- Use `$GITHUB_ENV` for variables needed across multiple steps.
+
+## Debugging CI failures
+
+1. Get the failing run: `GET /repos/{owner}/{repo}/actions/runs?branch={branch}`
+2. Get failed jobs: `GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs`
+3. Get logs: `GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs`
+4. Fix locally, verify in container, then push.
+
+See `.augment/commands/fix-ci.md` for the full debugging workflow.
+
+
+## Output format
+
+1. Modified workflow YAML file(s) in `.github/workflows/`
+2. Summary of pipeline changes and affected triggers
+
+## Auto-trigger keywords
+
+- GitHub Actions
+- CI/CD
+- workflow
+- pipeline
+- quality checks
+
+## Gotcha
+
+- CI workflows run on Ubuntu, not macOS — don't assume macOS-specific tools are available.
+- The model forgets to add `--env=testing` to artisan commands in CI — tests will hit the wrong database.
+- Secret names are case-sensitive in GitHub Actions — double-check the casing.
+- Don't add `continue-on-error: true` to hide failures — fix the actual error.
+
+## Do NOT
+
+- Do NOT use unpinned action versions (e.g., `actions/checkout@v4`).
+- Do NOT hardcode PHP versions — always extract from Dockerfile.
+- Do NOT add new secrets without documenting them.
+- Do NOT change runner types without considering cost and architecture (ARM vs x86).