@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/commands/optimize-augmentignore.md

@@ -3,8 +3,13 @@ skills: [agent-docs-writing]
 name: optimize-augmentignore
 description: Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules.
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Niche maintenance tool with no recurring NL trigger."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /optimize-augmentignore
 
 Scans the project to find files that waste tokens in Augment's retrieval index
@@ -260,3 +265,10 @@ echo "Rules ignored: $rules_count"
 - **Never ignore always-active rules** — only auto-loaded rules (those with `description` frontmatter) may be ignored.
 - **Never ignore meta/agent-system skills** — `agent-docs-writing-writing`, `commands`, `context-create`, `override-management`, `guidelines`, `project-docs`, `roadmap-management`, `naming`, `skill-reviewer`, `file-editor`, `copilot-config`, `copilot-agents-optimization`.
 - **Restore previously ignored skills** when the stack changes (e.g., Vue added to project → restore `vue` skill).
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+`.augmentignore` is an Augment-Code-specific retrieval-index config; it has
+no equivalent on the cloud surfaces and no file to write. Index pruning is
+a local-agent concern.

package/.agent-src/commands/optimize-rtk-filters.md

@@ -3,6 +3,9 @@ name: optimize-rtk-filters
 skills: [agent-docs-writing]
 description: Create or optimize project-local rtk filters based on the actual toolchain
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Niche maintenance tool with no recurring NL trigger."
 ---
 
 # optimize-rtk-filters

package/.agent-src/commands/optimize-skills.md

@@ -3,6 +3,10 @@ name: optimize-skills
 description: Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply.
 skills: [skill-reviewer]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "audit my skills, find duplicate skills"
+  trigger_context: "maintainer working on .augment/skills/ files"
 ---
 
 # /optimize-skills

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

@@ -3,6 +3,10 @@ name: override-create
 description: Creates a project-level override for a shared skill, rule, or command.
 skills: [override-management, agent-docs-writing]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "override this skill for the project, customize this rule locally"
+  trigger_context: "prompt names a shared skill/rule needing project-specific behavior"
 ---
 
 # /override-create

package/.agent-src/commands/override-manage.md

@@ -3,6 +3,10 @@ name: override-manage
 description: Reviews, updates, and refactors existing project-level overrides.
 skills: [override-management, agent-docs-writing]
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "review my overrides, update the project overrides"
+  trigger_context: "existing entries under agents/overrides/"
 ---
 
 # /override-manage

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

@@ -3,6 +3,9 @@ name: package-reset
 skills: [composer, npm]
 description: /package-reset
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Package-internal destructive reset."
 ---
 
 # package-reset

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

@@ -3,6 +3,9 @@ name: package-test
 skills: [composer, npm]
 description: /package-test
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Package-internal — only the event4u/agent-config repo runs this."
 ---
 
 # package-test

package/.agent-src/commands/prepare-for-review.md

@@ -3,6 +3,10 @@ name: prepare-for-review
 skills: [git-workflow, quality-tools]
 description: Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to date
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "get this branch ready for review, rebase and prep for PR"
+  trigger_context: "branch behind base or part of a PR chain"
 ---
 
 # prepare-for-review

package/.agent-src/commands/project-analyze.md

@@ -3,6 +3,10 @@ name: project-analyze
 skills: [project-analyzer]
 description: Full project analysis — detect stack, inventory modules, audit docs, create missing contexts
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "analyze the project structure, do a full project audit"
+  trigger_context: "new project or after a major refactor"
 ---
 
 # project-analyze

package/.agent-src/commands/project-health.md

@@ -3,6 +3,10 @@ name: project-health
 skills: [quality-tools]
 description: Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "check project health, what's the state of my docs and modules"
+  trigger_context: "routine health check, no destructive intent"
 ---
 
 # project-health

package/.agent-src/commands/propose-memory.md

@@ -3,14 +3,15 @@ name: propose-memory
 description: Append a provisional memory signal to the intake stream — the universal fallback for any producer (human or agent) to record a finding without committing to a curated entry.
 skills: [file-editor]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Programmatic intake fallback — overlaps /memory-add; keep explicit."
 ---
 
 # /propose-memory
 
 Drops a **signal** into `agents/memory/intake/signals-YYYY-MM.jsonl` via
-`scripts/memory_signal.py`. Signals are append-only JSONL and
-merge-safe (see
-[`road-to-memory-merge-safety`](../../../agents/roadmaps/road-to-memory-merge-safety.md)).
+`scripts/memory_signal.py`. Signals are append-only JSONL and merge-safe.
 
 Unlike [`/memory-add`](memory-add.md) — which writes a **curated**
 entry the reviewer has validated — `/propose-memory` is cheap and
@@ -30,8 +31,7 @@ Do NOT use when:
 - The entry is a **decision** — go to [`/memory-add`](memory-add.md)
   with `architecture-decisions` or `product-rules`.
 - The finding contradicts an existing curated entry — open a
-  supersede-chain discussion instead; route via
-  [`road-to-memory-self-consumption`](../../../agents/roadmaps/road-to-memory-self-consumption.md).
+  supersede-chain discussion instead.
 
 ## Steps
 
@@ -65,7 +65,7 @@ Ask once, numbered. If the user picks `skip`, proceed without them:
 ### 4. Emit via the shared helper
 
 ```bash
-python3 scripts/memory_signal.py \
+./agent-config memory:signal \
     --type <type> \
     --path "<path>" \
     --body "<body>" \
@@ -104,5 +104,3 @@ is intended (rarely).
 - [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
 - [`memory-access`](../guidelines/agent-infra/memory-access.md) — the
   read-side contract that consumes what this command writes.
-- [`road-to-agent-memory-integration`](../../../agents/roadmaps/road-to-agent-memory-integration.md)
-  — Phase 2 (write-side producers).

package/.agent-src/commands/quality-fix.md

@@ -3,6 +3,10 @@ name: quality-fix
 skills: [quality-tools]
 description: Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix the quality errors, run PHPStan and fix issues, fix code style"
+  trigger_context: "PHPStan/Rector/ECS output in recent tool results"
 ---
 
 # quality-fix

package/.agent-src/commands/refine-ticket.md

@@ -3,6 +3,10 @@ name: refine-ticket
 skills: [refine-ticket]
 description: Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates validate-feature-fit and threat-modeling, ends with a close-prompt
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "refine PROJ-123, tighten the acceptance criteria, is this ticket clear"
+  trigger_context: "ticket key in prompt with vague acceptance criteria"
 ---
 
 # refine-ticket
@@ -30,16 +34,18 @@ If no input resolves: ask **one** focused question:
 
 ### 2. Pick the output language
 
-Apply the skill's language-strategy block. First hit wins:
+Apply the skill's language-strategy block. Fallback order, first hit wins:
 
 1. **User-message language** — latest user message decides. Honours
    the global `language-and-tone` iron law.
-2. **Ticket body language** — minimal invocation (`/refine-ticket PROJ-123`
-   with no prose) mirrors the ticket's own language.
-3. **`.agent-settings.yml` default** — fallback when both silent; English
-   when absent.
+2. **Ticket body language** — when the invocation is minimal
+   (`/refine-ticket PROJ-123` with no prose), mirror the ticket's
+   own language (summary + description).
+3. **`.agent-settings.yml` default** — fallback when both are silent;
+   English when the setting is absent.
 
-Quoted identifiers stay native; only prose mirrors the picked language.
+Quoted identifiers (keys, paths, commands) stay native; only the
+prose mirrors the picked language.
 
 ### 3. Run the refine-ticket skill
 
@@ -78,4 +84,3 @@ persona voices) plus the close-prompt. Stop there. Do **not** chain into
 - [`jira-ticket`](jira-ticket.md) — ticket loader this command delegates to
 - [`estimate-ticket`](estimate-ticket.md) — sibling command — run after refining if you also need sizing
 - [`feature-plan`](feature-plan.md), [`feature-explore`](feature-explore.md) — downstream commands
-- [`road-to-ticket-refinement.md`](../../agents/roadmaps/road-to-ticket-refinement.md) — governing roadmap

package/.agent-src/commands/review-changes.md

@@ -1,8 +1,12 @@
 ---
 name: review-changes
-skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality]
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, git-workflow]
 description: Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "self-review my changes, judge this diff before PR"
+  trigger_context: "uncommitted or staged changes pre-PR"
 ---
 
 # review-changes
@@ -13,7 +17,29 @@ Review all uncommitted and committed-but-not-pushed changes against
 the default branch (`main`) by dispatching to four specialized judge
 sub-skills and consolidating their verdicts.
 
-### 1. Gather the diff
+### 1. Update the current branch
+
+Before gathering the diff, run [`/prepare-for-review`](prepare-for-review.md)
+to make sure the current branch is up to date with its base chain:
+
+- Detect the current branch with `git rev-parse --abbrev-ref HEAD`.
+- If the branch is `main` → skip this step (nothing to prepare).
+- Otherwise, search for an open GitHub PR whose head is the current
+  branch.
+  - If exactly one open PR is found → invoke `/prepare-for-review`
+    with that PR number. It will update `main`, fetch and merge the
+    full branch chain into the current branch, and leave the current
+    branch checked out.
+  - If no open PR is found → fall back to a minimal local update:
+    `git fetch origin main` and `git merge origin/main --no-edit` on
+    the current branch. Abort on conflict and report.
+  - If multiple PRs are found → ask the user which PR to use before
+    proceeding.
+- If `/prepare-for-review` aborts (merge conflict, network error,
+  etc.) → stop the review here and surface the error. Do **not**
+  continue with stale data.
+
+### 2. Gather the diff
 
 - `git diff origin/main..HEAD --stat` — overview of changed files
 - `git diff origin/main..HEAD` — full committed-but-not-pushed diff
@@ -21,7 +47,7 @@ sub-skills and consolidating their verdicts.
 
 If both diffs are empty, **stop** — nothing to review.
 
-### 2. Resolve the judge model
+### 3. Resolve the judge model
 
 Read `.agent-settings.yml`:
 
@@ -29,7 +55,7 @@ Read `.agent-settings.yml`:
 
 Unknown alias → stop. Never silently fall back.
 
-### 3. Dispatch to the four judges
+### 4. Dispatch to the four judges
 
 Each judge receives **the same diff plus the task context** (ticket,
 PR body, commit messages) and runs independently. The judges are:
@@ -55,7 +81,7 @@ Pick dispatch mode based on diff size and environment:
 Each judge returns its own `Judge / Model / Target / Verdict /
 Issues` block in the format defined by that skill.
 
-### 4. Consolidate
+### 5. Consolidate
 
 Produce one combined report:
 
@@ -65,7 +91,7 @@ Produce one combined report:
 - Highlight any finding that multiple judges flagged — those are the
   highest-confidence items
 
-### 5. Decide next steps
+### 6. Decide next steps
 
 - If **any** judge returned `reject` → stop; the approach must change
   before proceeding
@@ -73,7 +99,7 @@ Produce one combined report:
   ask before fixing 🟡 findings, report 🟢 as suggestions
 - If all four returned `apply` → the diff is ready; report and stop
 
-### 6. Quality tools (optional)
+### 7. Quality tools (optional)
 
 After the consolidated report, ask:
 
@@ -93,8 +119,12 @@ or the equivalent configured command).
   files still gets coverage feedback — `judge-test-coverage` treats
   "production changed, no test changed" as its primary finding
 - Project-specific syntax checks (e.g. `php -l`, linter pre-pass) are
-  out of scope for the judges and belong in the optional step 6
+  out of scope for the judges and belong in the optional step 7
   quality tools hand-off
+- The new step 1 (`/prepare-for-review`) is **best-effort**: if no
+  open PR exists for the current branch, it falls back to a plain
+  `git fetch && git merge origin/main`. Existing invocations that
+  ran on a fully detached or pre-PR branch keep working
 
 ## Use this command when
 
@@ -115,6 +145,7 @@ or the equivalent configured command).
 
 ## See also
 
+- [`/prepare-for-review`](prepare-for-review.md) — updates `main` and merges the full base-branch chain into the target branch (used by step 1)
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — dispatch and model-pairing rules
 - [`/do-and-judge`](do-and-judge.md) — implementer + judge loop for a single change
 - [`/judge`](judge.md) — standalone judge, no review-changes dispatch

package/.agent-src/commands/review-routing.md

@@ -3,6 +3,10 @@ name: review-routing
 skills: [review-routing, reviewer-awareness, review-routing-awareness]
 description: Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "who should review this, suggest reviewers for this PR"
+  trigger_context: "PR open without assigned reviewers"
 ---
 
 # review-routing

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

@@ -3,6 +3,10 @@ name: roadmap-create
 skills: [agent-docs-writing]
 description: Interactively create a new roadmap file in agents/roadmaps/
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create a roadmap for X, plan this work as a roadmap"
+  trigger_context: "multi-phase work without an existing agents/roadmaps/*.md"
 ---
 
 # roadmap-create
@@ -110,6 +114,20 @@ If yes → switch to the `roadmap-execute` command workflow with the newly creat
 
 - **Do NOT auto-generate content** — always ask the user for input.
 - **Do NOT commit or push.**
+- **Do NOT include commit steps in the roadmap** unless the user explicitly
+  requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
+  Roadmaps plan **work**; commits are a separate delivery decision.
+- **Every phase MUST contain at least one `- [ ]` checkbox.** A roadmap
+  without checkboxes is invisible to `agents/roadmaps-progress.md` and
+  violates [`roadmap-progress-sync`](../rules/roadmap-progress-sync.md)
+  Iron Law #2.
+- **Status is binary: `ready` (default) or `draft`.** Create new
+  roadmaps as **ready** — no `status:` field needed, ready is
+  implicit. Only mark `status: draft` (in YAML frontmatter) when the
+  user explicitly says it should be hidden from the dashboard (still
+  being authored, awaiting upstream decisions, capture-only synthesis
+  without executable phases). If the user wants draft, ask once at
+  step 3 — do not infer it.
 - **Write the roadmap in English** (per project convention for `.md` files).
 - Follow the roadmap template from `.augment/templates/roadmaps.md`.
 - Keep the file focused: 500–1000 lines max. If larger, suggest splitting.

package/.agent-src/commands/roadmap-execute.md

@@ -3,6 +3,10 @@ name: roadmap-execute
 skills: [agent-docs-writing]
 description: Read and interactively execute a roadmap from agents/roadmaps/
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "execute the roadmap, work through the roadmap step by step"
+  trigger_context: "existing agents/roadmaps/*.md referenced in the prompt"
 ---
 
 # roadmap-execute
@@ -61,7 +65,16 @@ For each open step:
 
 ### Rules
 
-- **Do NOT commit or push** — only apply local changes and update the roadmap file.
+- **Commits are governed by [`commit-policy`](../rules/commit-policy.md).**
+  By default: only apply local changes and update the roadmap file — no commits.
+  - If the roadmap **does not** contain explicit commit steps → never commit, never ask.
+  - If the roadmap **does** contain explicit commit steps:
+    - **Non-autonomous** (`personal.autonomy: off`, or `auto` before opt-in) →
+      ask before each commit step.
+    - **Autonomous** (`personal.autonomy: on`, or `auto` after opt-in) →
+      pre-scan the roadmap **before starting**, ask **once** upfront whether
+      to execute the listed commit steps, then proceed silently per the answer.
+- **Push, merge, branch, PR, tag** stay permission-gated by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
 - **Always ask before implementing** a step — never auto-execute.
 - **Run quality checks** after each code change.
 - If a step is unclear or too large, suggest breaking it down further.

package/.agent-src/commands/rule-compliance-audit.md

@@ -2,6 +2,10 @@
 name: rule-compliance-audit
 description: Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "audit my rules, check rule trigger quality"
+  trigger_context: "maintainer working on .augment/rules/ files"
 ---
 
 # rule-compliance-audit

package/.agent-src/commands/set-cost-profile.md

@@ -3,8 +3,13 @@ name: set-cost-profile
 description: Change the cost_profile in .agent-settings.yml — shows each profile's meaning and applies the selection
 skills: [file-editor]
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Settings mutation — must be deliberate."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /set-cost-profile
 
 Changes `cost_profile` in `.agent-settings.yml`. Four profiles are defined in
@@ -93,6 +98,12 @@ steps here, that's the docs' job.
 - `custom` ignores the profile matrix — every per-feature toggle must be
   set explicitly afterwards. Warn the user when switching to `custom`.
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` to write and no `cost_profile` toggle to
+flip. Cost behaviour on those surfaces is governed by the platform itself.
+
 ## See also
 
 - [`agent-settings`](../templates/agent-settings.md) — profile matrix and settings reference

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

@@ -2,8 +2,13 @@
 name: sync-agent-settings
 description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Settings sync — must be deliberate."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /sync-agent-settings
 
 Reconciles `.agent-settings.yml` with the shipped template
@@ -112,6 +117,13 @@ check-only workflows; report the drift and let the pipeline decide.
   presets require a package update in the consumer project before
   this command can apply them.
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` on disk, no `scripts/sync_agent_settings.py`
+to call, and no template/profile preset reachable. Settings reconciliation
+is a local-agent concern.
+
 ## See also
 
 - [`scripts/sync_agent_settings.py`](../../../scripts/sync_agent_settings.py) — the helper

package/.agent-src/commands/sync-gitignore.md

@@ -2,6 +2,9 @@
 name: sync-gitignore
 description: Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing
 disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Settings sync — must be deliberate."
 ---
 
 # /sync-gitignore

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

@@ -3,6 +3,10 @@ name: tests-create
 skills: [pest-testing]
 description: Write meaningful tests for the changes in the current branch
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "write tests for these changes, add tests for this branch"
+  trigger_context: "code changes on the branch without matching test changes"
 ---
 
 # tests-create

package/.agent-src/commands/tests-execute.md

@@ -3,6 +3,10 @@ name: tests-execute
 skills: [pest-testing]
 description: Run PHP tests inside the Docker container
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "run the tests, execute the test suite"
+  trigger_context: "code changes pending verification"
 ---
 
 # tests-execute
@@ -18,9 +22,8 @@ Check in this order — use the **first match**:
 3. **`vendor/bin/pest` exists** → Pest → `vendor/bin/pest`
 4. **Fallback** → PHPUnit → `vendor/bin/phpunit`
 
-**Prefer Makefile targets** over raw commands — they handle container access,
-environment variables, and parallel settings automatically. If the project
-uses a different task runner, inspect its config before falling back to raw.
+**Prefer Makefile targets** over raw commands when they exist — they handle container access,
+environment variables, and parallel settings automatically.
 
 ### 2. Run the tests
 

package/.agent-src/commands/threat-model.md

@@ -3,6 +3,10 @@ name: threat-model
 skills: [threat-modeling, authz-review, security-sensitive-stop]
 description: Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and authorization gaps before the first line of code is written
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "threat model this change, what could go wrong security-wise"
+  trigger_context: "changes touching auth, webhooks, uploads, secrets, or public endpoints"
 ---
 
 # threat-model

package/.agent-src/commands/update-form-request-messages.md

@@ -3,6 +3,10 @@ name: update-form-request-messages
 skills: [laravel-validation]
 description: Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and clean up stale ones
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "sync the form request messages, update the validation messages"
+  trigger_context: "edits to app/Http/Requests/*.php referencing rules without messages"
 ---
 
 # update-form-request-messages

package/.agent-src/commands/upstream-contribute.md

@@ -3,6 +3,10 @@ name: upstream-contribute
 skills: [upstream-contribute, skill-writing, learning-to-rule-or-skill]
 description: Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
 disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "contribute this back to agent-config, upstream this learning"
+  trigger_context: "project-local skill/rule that fits the shared package"
 ---
 
 # /upstream-contribute