@event4u/agent-config 1.16.0 → 1.17.0

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

@@ -16,57 +16,76 @@ execution:
 
 ## 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
+Use this skill when:
 
-NOT: body-only edits, frontmatter shape (use `lint-skills`), compressed pairs
-(use `bash scripts/compress.sh --check`).
+- A skill, rule, command, guideline, or context has been renamed or deleted
+- Linking a newly added artifact from elsewhere in `.agent-src.uncompressed/`
+- Preparing a PR that touches cross-references between agent artifacts
+- CI's `check-refs` job failed and the broken reference needs to be located
+
+Do NOT use when:
+
+- Only the body of a single file changed and no names or paths were touched
+- Checking frontmatter shape or required sections — use `lint-skills` instead
+- Verifying compressed vs uncompressed pairs — use `bash scripts/compress.sh --check` instead
 
 ## 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** —
+### 1. Inspect the scope of recent changes
 
-   ```bash
-   python3 scripts/runtime_dispatcher.py run --skill check-refs
-   ```
+Identify whether any artifact was renamed, moved, or removed since the last
+clean run. Cross-reference checks are relevant only when names or paths shift;
+pure body edits cannot break references.
 
-   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
+### 2. Dispatch via the runtime layer
 
-## Output
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
 
-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
+```bash
+python3 scripts/runtime_dispatcher.py run --skill check-refs
+```
 
-## Gotcha
+The dispatcher resolves the request, the shell handler runs
+`python3 scripts/check_references.py`, captures stdout/stderr, and returns a
+typed `ExecutionResult`.
 
-- 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
+### 3. Verify the result
 
-## Do NOT
+Check the returned `ExecutionResult`:
+
+- `exit_code: 0` → all cross-references resolve
+- `exit_code: 1` → at least one broken reference — read `stdout` for file,
+  line, and the offending ref, then fix the source or update the target
+- `status: timeout` → the checker exceeded `timeout_seconds` — investigate
+- `status: error` → interpreter or script missing — confirm `python3` and
+  `scripts/check_references.py` are available at the repository root
 
-- 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
+## Output format
 
-## References
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of broken references found, if any
+3. First 10 broken references with `file:line → missing-target`
+4. Next action: fix references, re-run the skill, or surface `stdout` for
+   review
+
+## Gotchas
+
+- The checker is read-only — it never rewrites references, so a clean run
+  after a fix must be produced by re-invoking the skill, not by assumption
+- Running outside the agent-config repo root makes the checker inspect zero
+  files and report a false pass
+- Relative links inside comments or fenced code blocks may still be parsed as
+  references depending on the checker's current rules; do not suppress a
+  broken ref without confirming it is a genuine false positive
+
+## Do NOT
 
-- 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`
+- Do NOT invoke `scripts/check_references.py` directly when the intent is to
+  verify the runtime path — always go through the dispatcher so the
+  `ExecutionResult` is produced and inspectable
+- Do NOT raise `timeout_seconds` to mask a slowdown — investigate which part
+  of the tree grew large enough to push past 60 seconds
+- Do NOT add piping or redirection to `command` — the handler uses
+  `shell=False` and will refuse anything outside pure argv form

package/.agent-src/skills/conventional-commits-writing/SKILL.md

@@ -12,48 +12,106 @@ execution:
 
 ## When to use
 
-- Generating commit message from staged changes
-- Generating squash merge title from PR
-- Deciding correct type for a change
-- Reviewing/correcting commit messages
-- Splitting vague changes into multiple commits
+Use this skill when:
 
-NOT: explaining standard (reference rule), git workflow (use `git-workflow`)
+- Generating a commit message from staged changes
+- Generating a squash merge title from a PR
+- Deciding the correct Conventional Commit type for a change
+- Reviewing whether a commit message is correct
+- Splitting one vague change into multiple commit messages
 
-## Procedure: Generate
+Do NOT use when:
 
-1. **Intent** — feat/fix/refactor/docs/test/ci/chore/perf/build/style. Classify by intent, not file type.
-2. **Mixed concerns?** — split into multiple commits or choose dominant net effect for squash title.
-3. **Scope** — Jira ID or area name. Only if it adds clarity.
-4. **Description** — intent, not implementation. Imperative. Max 72 chars. No generic filler.
-5. **Breaking?** — add `!` or `BREAKING CHANGE:` footer:
+- Only explaining the Conventional Commits standard (just reference the rule)
+- The message is already correct and does not need review
+- Following the Git workflow (use `git-workflow` skill)
+
+## Procedure: Generate commit message
+
+### 1. Identify the actual intent
+
+Determine whether the change is:
+
+- New behavior → `feat`
+- Bug fix → `fix`
+- Structural cleanup → `refactor`
+- Docs only → `docs`
+- Tests only → `test`
+- CI/build/tooling → `ci` or `build`
+- Maintenance → `chore`
+- Performance → `perf`
+- Formatting only → `style`
+
+Classify by **user-visible or system-relevant intent**, not by file type alone.
+
+### 2. Detect mixed concerns
+
+Check whether the change includes more than one unrelated concern.
+
+If yes:
+
+- Suggest splitting into multiple commits
+- Or choose the dominant net effect for squash merge title
+
+### 3. Choose scope
+
+Add a scope only if it improves clarity:
+
+- Jira ticket ID: `DEV-1234`
+- Module/area: `api`, `auth`, `skills`, `rules`, `ci`
+
+### 4. Write the description
+
+- State the intent clearly
+- Avoid generic filler (`update stuff`, `fix things`)
+- Stay concise — max 72 chars total for first line
+- Imperative mood: "add", "fix", "remove" — not "added", "fixed", "removed"
+
+### 5. Check for breaking change
+
+If compatibility is broken, add `!` after type/scope:
 
 ```
 feat(api)!: rename invoice status values
 ```
 
-6. **Validate** — type matches intent? scope useful? not hiding multiple concerns?
+Or add `BREAKING CHANGE:` in the commit body/footer.
+
+### 6. Validate
+
+- Type matches intent?
+- Scope is useful (not noise)?
+- Description is specific (not generic)?
+- Not hiding multiple unrelated changes?
+- Breaking changes are marked?
 
-## Procedure: Review
+## Procedure: Review existing commit message
 
-Parse → check type vs diff → check scope → check description clarity → suggest corrections.
+1. Parse the message into type, scope, description
+2. Check type accuracy against the actual diff
+3. Check scope usefulness
+4. Check description clarity and specificity
+5. Suggest corrections if any check fails
 
-## Procedure: Squash merge title
+## Procedure: Generate squash merge title
 
-Read all PR commits → identify net effect → write single Conventional Commit summarizing it.
+1. Read all commits in the PR
+2. Identify the **net effect** — what does the PR accomplish overall?
+3. Write a single Conventional Commit message summarizing the net effect
+4. Do not list every internal commit — summarize
 
-## Output
+## Output format
 
-1. Recommended message(s)
-2. Brief type rationale
-3. Split suggestion if needed
+1. Recommended commit message(s)
+2. Brief rationale for type choice
+3. Split suggestion if the change should be multiple commits
 
 ## Gotcha
 
-- Model overuses `chore`/`refactor` — classify by intent, not effort
-- File type ≠ commit type (`.md` change can be `feat`)
-- `refactor` = NO behavior change — if behavior changes, use `feat`/`fix`
-- Squash title = net effect, not internal details
+- The model tends to overuse `chore` and `refactor` — classify by intent, not by effort
+- File type alone does not determine commit type (e.g. a `.md` change can be `feat` if it's a new feature doc)
+- Squash merge titles should describe the net effect, not every internal detail
+- `refactor` means NO behavior change — if behavior changes, use `feat` or `fix`
 
 ## Do NOT
 
@@ -65,6 +123,6 @@ Read all PR commits → identify net effect → write single Conventional Commit
 
 ## References
 
-- Rule: `commit-conventions` — format, types, scope
-- Guideline: `docs/guidelines/php/git.md` — selection rules, anti-patterns, checklist
-- Command: `/commit` — uses this skill
+- Rule: `commit-conventions` — base format, types, scope, examples
+- Guideline: `docs/guidelines/php/git.md` — type selection rules, anti-patterns, decision checklist
+- Command: `/commit` — uses this skill for message generation

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -27,12 +27,12 @@ Do NOT use when:
 
 ### 0. Analyze current state
 
-Before changing anything:
+Before changing anything, read and understand:
 
-1. Read `AGENTS.md` — content, line count, what's duplicated vs. unique
-2. Read `.github/copilot-instructions.md` — same analysis
-3. Scan `.augment/` — which skills/rules already cover topics from above
-4. Identify duplication — what exists in both AGENTS.md and `.augment/`?
+1. **Read `AGENTS.md`** — current content, line count, what's duplicated vs. unique.
+2. **Read `.github/copilot-instructions.md`** — same analysis.
+3. **Scan `.augment/`** — which skills, rules, and guidelines already cover topics from the files above.
+4. **Identify duplication** — what content exists in both AGENTS.md and `.augment/`?
 
 Only after this analysis, proceed with optimization.
 

package/.agent-src/skills/developer-like-execution/SKILL.md

@@ -129,10 +129,10 @@ If important information is missing:
 - **Consult memory — invariants and prior decisions.** Via
   [`memory-access`](../../../docs/guidelines/agent-infra/memory-access.md), call
   `retrieve(types=["domain-invariants", "architecture-decisions"], keys=<touched paths>, limit=3)`.
-  A matching `domain-invariant` is a hard constraint — violating it =
-  regression, surface the conflict before proceeding. A matching
-  `architecture-decision` explains *why* the current shape exists; plan
-  around it, do not silently overturn it. Cite matching `id`s in the plan.
+  A matching `domain-invariant` is a hard constraint — violating it = regression,
+  surface the conflict to the user before proceeding. A matching
+  `architecture-decision` explains *why* the current shape exists; plan around
+  it, do not silently overturn it. Cite matching `id`s in the plan.
   See [`engineering-memory-data-format`](../../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
   for the schema.
 

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

@@ -9,15 +9,17 @@ source: package
 ## 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
+* All planned commits are in, the 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
+* The 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
+* A PR already exists and is mid-review — use
+  [`receiving-code-review`](../receiving-code-review/SKILL.md)
+* Only documentation changed and no tests apply — simplify to
+  commit + PR without the full gate
 
 ## Goal
 
@@ -37,29 +39,33 @@ how work gets lost.
 
 ## Procedure
 
-### 1. Inspect branch state
+### 1. Inspect the current branch state
 
-Before presenting options, check:
+Before presenting any options, gather context. Do not assume — 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
+* `git status` — clean, or still dirty?
+* `git log --oneline <base>..HEAD` — what commits are actually on this
+  branch?
+* `git branch --show-current` — the branch name you will be operating 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).
+If a PR already exists for this branch, **stop** — this is not a
+finishing step, route to [`receiving-code-review`](../receiving-code-review/SKILL.md)
+or [`fix-pr-comments`](../../commands/fix-pr-comments.md) instead.
 
 ### 2. Verify readiness
 
-Run the full end-of-work gate — see [`verify-before-complete`](../verify-before-complete/SKILL.md):
+Run the full end-of-work gate before presenting any options — 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
+4. `git status` clean — nothing unstaged, no stray files
+5. Branch is pushed or explicitly marked local-only
 
-Any step fails → **stop**. Report failure, do not present ship options.
+If any step fails → **stop**. Report the failure, do not present ship
+options. Fixing the failure comes first.
 
 ### 3. Determine the base branch
 
@@ -71,9 +77,12 @@ BASE=main
 BASE=$(git config branch.$(git branch --show-current).merge | sed 's|refs/heads/||')
 ```
 
-Ambiguous → ask: *"This branch splits from `<guess>` — correct?"*.
+If ambiguous, ask: *"This branch splits from `<guess>` — correct?"*
+before presenting options.
 
-### 4. Present four options — numbered, no narration
+### 4. Present the four options — numbered, no narration
+
+Ask the user exactly one question:
 
 ```
 Implementation is verified. What now?
@@ -84,21 +93,25 @@ Implementation is verified. What now?
 4. Discard all work on this branch
 ```
 
-No recommendations unless the user asks.
+Do not add recommendations unless the user asks. Each option leads to
+a different sub-procedure (steps 5a–5d).
 
 ### 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
+1. Ensure the branch is up to date with the base →
+   [`prepare-for-review`](../../commands/prepare-for-review.md)
+2. Self-review the full diff → [`review-changes`](../../commands/review-changes.md)
+3. Write the PR description → [`create-pr-description`](../../commands/create-pr-description.md)
+4. Open the PR → [`create-pr`](../../commands/create-pr.md)
+5. Confirm the PR opened green, not red
 
-Surrounding discipline → [`requesting-code-review`](../requesting-code-review/SKILL.md).
+See [`requesting-code-review`](../requesting-code-review/SKILL.md) for
+the surrounding discipline.
 
 ### 5b. Option 2 — Merge locally
 
-Use only for no-PR projects (solo, spike, private tooling).
+Use only when the project policy is "no PR required" (solo repos,
+spike branches, private tooling). For team repos, default to Option 1.
 
 ```bash
 git checkout <base-branch>
@@ -110,17 +123,18 @@ git merge --no-ff <feature-branch>
 git branch -d <feature-branch>
 ```
 
-Post-merge test fails → `git reset --hard ORIG_HEAD`, fix on feature branch, restart.
+If the post-merge test run fails → `git reset --hard ORIG_HEAD`, fix
+on the feature branch, restart from Option 1/2.
 
 ### 5c. Option 3 — Keep as-is
 
-* Push to origin if not already pushed
-* Report branch name and last commit SHA
+* Push the branch to origin if not already pushed (safeguards the work)
+* Report the branch name and the last commit SHA back to the user
 * Do not delete the worktree, do not force-push
 
 ### 5d. Option 4 — Discard
 
-**Confirmation gate** — typed answer, not "y":
+**Confirmation gate** — require a typed answer, not "y":
 
 ```
 This will permanently remove:
@@ -140,65 +154,87 @@ git branch -D <feature-branch>
 git push origin --delete <feature-branch>
 ```
 
-Log discarded SHAs so work can be recovered via `git reflog`.
+Log the discarded SHAs so the work can be recovered via `git reflog`
+within the reflog TTL if needed.
 
 ### 6. Clean up worktrees
 
-Branch in a `git worktree`:
+If the branch lives in a `git worktree`:
 
-* Options 1, 2, 4 → `git worktree remove <path>` after terminal state
+* Options 1, 2, 4 → `git worktree remove <path>` after the branch
+  terminal state
 * Option 3 → keep the worktree
 
 ## Output format
 
-After chosen option completes:
+After the chosen option completes, report:
 
-1. **What happened** — one sentence ("PR #123 opened", "Merged as `abcdef`", "Discarded")
+1. **What happened** — single sentence ("PR #123 opened", "Merged
+   into main as `abcdef`", "Branch 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.
+3. **Cleanup state** — worktree removed / kept, branch deleted /
+   retained
+4. **Next step** — e.g. "Awaiting review" / "Main is one commit ahead"
 
 ## 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
+* Option 1 (PR) on a red CI — the PR opens but is not actually
+  reviewable; check the CI status before reporting success
+* Option 2 (local merge) with fast-forward only on a diverged base
+  silently fails — the merge command aborts but the report can look
+  successful if the exit code is not checked
+* Option 4 (discard) on a branch that is already the upstream of
+  another local branch — the dependent branch is orphaned
+* Force-pushing after a PR is opened can lose the reviewer's
+  line-comments — prefer additional commits during review
+* `git branch -d` vs `-D` — lowercase `-d` refuses unmerged branches,
+  uppercase `-D` forces; only use `-D` inside the confirmed discard
+  flow
+* On stacked PRs, the base is **not** `main` — opening a 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
+* Do NOT present ship options while tests or quality checks are red
+* Do NOT add rationale or recommendations to the four numbered options
+  — the user decides
+* Do NOT discard a branch without a typed confirmation including the
+  branch name
+* Do NOT force-delete a remote branch without user confirmation
+* Do NOT silently change the base branch between verification and ship
+* Do NOT mix any 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
+* Presenting three options and phrasing the fourth as "or we can
+  discard if you want" — buries the destructive option
+* Running the full gate inside this skill *and* at the start of
+  `create-pr` — duplicates work. Trust the gate result if nothing
+  changed in between
+* Merging local + opening PR at the same time — pick one
+* Asking "ready to ship?" without listing the four concrete 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)
+* Final pre-merge verification → [`verify-before-complete`](../verify-before-complete/SKILL.md)
+* Rebasing the stack before PR → [`prepare-for-review`](../../commands/prepare-for-review.md)
+* Writing the commit for any last-minute tweaks →
+  [`commit`](../../commands/commit.md),
+  [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md)
+* Self-review walkthrough → [`review-changes`](../../commands/review-changes.md)
+* Creating the PR → [`create-pr`](../../commands/create-pr.md)
+* Processing review comments after the PR is open →
+  [`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
+Before reporting "done" after this skill runs:
+
+* [ ] Full gate (tests + quality pipeline) verified green in this turn
+* [ ] Base branch determined and confirmed with the user when ambiguous
+* [ ] Exactly four numbered options were presented, no narration added
 * [ ] 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)
+* [ ] Sub-procedure for the chosen option completed end-to-end
+* [ ] Worktree state handled per option (remove for 1/2/4, keep for 3)
+* [ ] Destructive actions had typed confirmation including branch name
+* [ ] Final report includes evidence (PR URL, SHA, or exit code)

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

@@ -8,7 +8,12 @@ source: package
 
 ## Positioning — dispatched, not standalone
 
-`flux` is the **primitive-library executor** for projects on the Livewire + Flux stack. Invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py) once the design brief is locked, and revisited by `review.py` / `polish.py` during the design-review loop. Does **not** own the flow, drive the audit, or lock the design.
+`flux` is the **primitive-library executor** for projects on the
+Livewire + Flux stack. It is invoked by
+[`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
 
 | Concern | Owner |
 |---|---|
@@ -22,8 +27,8 @@ source: package
 
 Cite this skill when:
 
-- Project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
-- Building forms, modals, dropdowns, toasts, or other standard UI elements Flux already provides
+- The project depends on `livewire/flux` and `directives/ui/apply.py` dispatches Flux primitives
+- Building forms, modals, dropdowns, toasts, or other standard UI elements that Flux already provides
 
 Do NOT use when:
 
@@ -64,16 +69,31 @@ Do NOT use when:
 
 ### Review pass — a11y findings + preview envelope
 
-When dispatched by `directives/ui/review.py` (test slot) or `directives/ui/polish.py` (verify slot) — review/polish run, not initial apply — also emits:
-
-- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...], severity_floor?, accepted_violations?}`. Use same `(rule, selector)` shape as `state.ui_audit.a11y_baseline` so engine's de-dup matches pre-existing entries on replay. Omit envelope on apply passes; engine's `_apply_a11y_gate` only fires when baseline present.
-- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?, dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error` populated triggers `preview_render_failed` halt; `render_ok: true` with `screenshot_path` threads screenshot into delivery report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is consumer-project dependency — package does not ship one.
-
-Polish dispatch: when dispatcher skips `review` because previous review pass returned `SUCCESS`, this skill MUST itself synthesise updated `state.ui_review.findings` (including remaining `a11y_violation` entries) so engine's gate sees current state on next polish round.
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
 
 ## Gotcha
 
-- Model tends to use old Flux API syntax — always check latest docs.
+- 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.
 

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

@@ -14,7 +14,7 @@ Use this skill when working with GitHub Actions workflows, CI pipeline configura
 
 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.
+3. Read `commands/fix/ci.md` for CI failure debugging workflow.
 
 ## Workflow overview
 
@@ -91,7 +91,7 @@ Check `.github/workflows/` for the runner types used. Common patterns:
 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.
+See `commands/fix/ci.md` for the full debugging workflow.
 
 
 ## Output format