@event4u/agent-config 1.15.0 → 1.17.0

package/.agent-src/commands/judge/solo.md

@@ -0,0 +1,90 @@
+---
+name: judge:solo
+cluster: judge
+sub: solo
+skills: [subagent-orchestration]
+description: Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
+disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Sibling of /review-changes — eligibility routed there; keep this explicit."
+---
+
+# /judge solo
+## Instructions
+
+### 1. Identify the target
+
+The user invoked `/judge solo` on one of:
+
+- The current working-tree diff (`git diff`)
+- A specific commit range (`git diff A..B`)
+- A PR by number or URL
+- A single file or set of files
+
+Confirm the target in one sentence before proceeding. Do not silently
+assume the working tree.
+
+### 2. Gather the context
+
+Collect what the judge needs:
+
+- The diff in full
+- The original task, ticket, or PR description
+- Relevant acceptance criteria (tests, linter config, design doc)
+
+If any of these is missing and the judgment would be shallow without
+it, **stop** and ask.
+
+### 3. Resolve the judge model
+
+Read `.agent-settings.yml`:
+
+- `subagents.judge_model` → empty = one tier above session model
+
+Unknown alias → stop. Silence is not a fallback.
+
+### 4. Invoke the judge
+
+The judge reviews the diff against the task. Return one of:
+
+| Verdict  | Meaning                                      |
+|----------|----------------------------------------------|
+| `apply`  | Correct, complete, ready to land             |
+| `revise` | Specific issues listed — user decides next   |
+| `reject` | Fundamentally wrong approach                 |
+
+Unlike `/judge on-diff`, this command does **not** loop — no revision
+cycles. The verdict is the deliverable.
+
+### 5. Report
+
+```
+Mode:    judge (standalone)
+Target:  <diff | commit range | PR #N | files>
+Judge:   <resolved model>
+Verdict: apply | revise | reject
+Issues:  <numbered list if revise/reject>
+Next step: <what the user should do based on the verdict>
+```
+
+## Use this command when
+
+- A diff already exists and the user wants a second opinion
+- Reviewing someone else's PR before approving it
+- Double-checking a change before opening a PR
+- Stress-testing a refactor without committing to revisions
+
+## Do NOT
+
+- NEVER apply the diff — this command judges only
+- NEVER loop into a revision cycle — use `/judge on-diff` for that
+- NEVER run the judge on an empty diff — fail fast
+- NEVER silently fall back to the session model for the judge
+
+## See also
+
+- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
+- [`/judge on-diff`](do-and-judge.md) — if a revision loop is wanted
+- [`/review-changes`](review-changes.md) — human-oriented self-review
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)

package/.agent-src/commands/{do-in-steps.md → judge/steps.md}

@@ -1,6 +1,8 @@
 ---
-name: do-in-steps
-skills: [subagent-orchestration, verify-before-complete]
+name: judge:steps
+cluster: judge
+sub: steps
+skills: [subagent-orchestration, verify-completion-evidence]
 description: Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict
 disable-model-invocation: true
 suggestion:
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Subagent orchestration — overlaps /work and /roadmap-execute; keep explicit."
 ---
 
-# do-in-steps
-
+# /judge steps
 ## Instructions
 
 ### 1. Confirm the plan
@@ -57,7 +58,7 @@ On stop, report the last verified state so the user can resume.
 
 ### 5. Final verification
 
-After step N passes judgment, run `verify-before-complete` across the
+After step N passes judgment, run `verify-completion-evidence` across the
 whole changeset — targeted tests + full suite + quality pipeline.
 Never declare the plan "done" without this gate.
 
@@ -77,11 +78,11 @@ Next step:  <commit / open PR / resume from step K>
 
 - Never skip a step because the next one looks easier
 - Never apply a revised step without the judge re-verdicting
-- Never declare complete without final `verify-before-complete`
+- Never declare complete without final `verify-completion-evidence`
 - A failing step never cascades silently — stop, report, hand back
 
 ## See also
 
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
-- [`verify-before-complete`](../skills/verify-before-complete/SKILL.md)
+- [`verify-completion-evidence`](../skills/verify-completion-evidence/SKILL.md)
 - [`/do-and-judge`](do-and-judge.md) — single-change variant

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

@@ -1,89 +1,54 @@
 ---
 name: judge
-skills: [subagent-orchestration]
-description: Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
+description: Judge orchestrator — routes to solo, steps, on-diff
+cluster: judge
 disable-model-invocation: true
 suggestion:
-  eligible: false
-  rationale: "Sibling of /review-changes — eligibility routed there; keep this explicit."
+  eligible: true
+  trigger_description: "judge this diff, review with verdict, run an implementer→judge loop, step-by-step judged execution"
+  trigger_context: "user wants a verdict on a diff, a do-and-judge loop, or a step-gated execution"
 ---
 
-# judge
+# /judge
 
-## Instructions
+Top-level orchestrator for the `/judge` family. Replaces 3 standalone
+commands with a single entry point + sub-command dispatch.
 
-### 1. Identify the target
+## Sub-commands
 
-The user invoked `/judge` on one of:
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/judge solo` | `commands/judge/solo.md` | Standalone verdict on an existing diff — no implementer, no revision loop |
+| `/judge on-diff` | `commands/judge/on-diff.md` | Implementer→judge loop on a single change with a two-revision ceiling |
+| `/judge steps` | `commands/judge/steps.md` | Execute an ordered plan step by step, judge gate between steps |
 
-- The current working-tree diff (`git diff`)
-- A specific commit range (`git diff A..B`)
-- A PR by number or URL
-- A single file or set of files
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+The standalone reviewer surface lives at [`/review`](review-changes.md).
 
-Confirm the target in one sentence before proceeding. Do not silently
-assume the working tree.
+## Dispatch
 
-### 2. Gather the context
+1. Parse the user's argument: `/judge <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions`
+   section verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and
+   ask:
 
-Collect what the judge needs:
+   > 1. solo — verdict only, no loop
+   > 2. on-diff — implementer→judge revision loop
+   > 3. steps — judge gate between ordered steps
 
-- The diff in full
-- The original task, ticket, or PR description
-- Relevant acceptance criteria (tests, linter config, design doc)
+## Rules
 
-If any of these is missing and the judgment would be shallow without
-it, **stop** and ask.
-
-### 3. Resolve the judge model
-
-Read `.agent-settings.yml`:
-
-- `subagents.judge_model` → empty = one tier above session model
-
-Unknown alias → stop. Silence is not a fallback.
-
-### 4. Invoke the judge
-
-The judge reviews the diff against the task. Return one of:
-
-| Verdict  | Meaning                                      |
-|----------|----------------------------------------------|
-| `apply`  | Correct, complete, ready to land             |
-| `revise` | Specific issues listed — user decides next   |
-| `reject` | Fundamentally wrong approach                 |
-
-Unlike `/do-and-judge`, this command does **not** loop — no revision
-cycles. The verdict is the deliverable.
-
-### 5. Report
-
-```
-Mode:    judge (standalone)
-Target:  <diff | commit range | PR #N | files>
-Judge:   <resolved model>
-Verdict: apply | revise | reject
-Issues:  <numbered list if revise/reject>
-Next step: <what the user should do based on the verdict>
-```
-
-## Use this command when
-
-- A diff already exists and the user wants a second opinion
-- Reviewing someone else's PR before approving it
-- Double-checking a change before opening a PR
-- Stress-testing a refactor without committing to revisions
-
-## Do NOT
-
-- NEVER apply the diff — this command judges only
-- NEVER loop into a revision cycle — use `/do-and-judge` for that
-- NEVER run the judge on an empty diff — fail fast
-- NEVER silently fall back to the session model for the judge
+- **Do NOT commit, push, or open a PR** unless the sub-command
+  explicitly authorizes it.
+- **Do NOT chain sub-commands.** One `/judge <sub>` per turn.
+- If the user invokes `/judge` with no argument, **show the menu** —
+  do not guess which sub-command they meant.
 
 ## See also
 
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
-- [`/do-and-judge`](do-and-judge.md) — if a revision loop is wanted
-- [`/review-changes`](review-changes.md) — human-oriented self-review
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
+- [`/review`](review-changes.md) — human-oriented self-review (Reviewer-mode contract)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#reviewer)

package/.agent-src/commands/{memory-add.md → memory/add.md}

@@ -1,5 +1,7 @@
 ---
-name: memory-add
+name: memory:add
+cluster: memory
+sub: add
 description: Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decisions, incident-learnings, product-rules)
 skills: [file-editor]
 disable-model-invocation: true
@@ -9,12 +11,11 @@ suggestion:
   trigger_context: "post-incident or post-decision conversation"
 ---
 
-# /memory-add
-
+# /memory add
 Creates or updates a single entry in one of the four engineering-memory
 YAML files under `agents/memory/` in the consumer project. The entry
 is validated against the schema in
-[`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
+[`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
 before the file is written.
 
 Absence of these files is legal — this command is the entry point for
@@ -58,7 +59,7 @@ sharded layout: `agents/memory/<type>/*.yml`). For each existing
 ### 3. Collect the required fields
 
 All four types share the frontmatter in
-[`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md#shared-frontmatter-fields).
+[`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md#shared-frontmatter-fields).
 Collect in this order, one numbered question at a time:
 
 1. `id` — kebab-case slug, unique within the type.
@@ -125,7 +126,7 @@ link resolves. Broken link → block and ask the user to fix.
 
 ## See also
 
-- [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
+- [`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
   — full schema
 - [`capture-learnings`](../rules/capture-learnings.md) — when a
   learning is better captured as an `incident-learnings` entry vs a

package/.agent-src/commands/{memory-full.md → memory/load.md}

@@ -1,5 +1,7 @@
 ---
-name: memory-full
+name: memory:load
+cluster: memory
+sub: load
 description: Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analysis, never auto-triggered
 skills: []
 disable-model-invocation: true
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Description states 'never auto-triggered' — opt-in deep-load only."
 ---
 
-# /memory-full
-
+# /memory load
 Loads every entry of a single memory type into the current conversation
 as a formatted block. Use when the normal `memory_lookup` filter is too
 narrow and you need the full type for an architecture decision, audit,
@@ -80,7 +81,7 @@ opts in.
 
 The agent should now treat every loaded entry as an authority signal
 with its declared `confidence` — see
-[`memory-access`](../guidelines/agent-infra/memory-access.md) for
+[`memory-access`](../../docs/guidelines/agent-infra/memory-access.md) for
 how entries modulate edits.
 
 ## When to reject
@@ -96,5 +97,5 @@ how entries modulate edits.
 - [`memory-add`](memory-add.md) — add a single entry
 - [`memory-promote`](memory-promote.md) — promote an intake signal to
   a curated entry
-- [`memory-access`](../guidelines/agent-infra/memory-access.md) —
+- [`memory-access`](../../docs/guidelines/agent-infra/memory-access.md) —
   how entries flow into agent decisions

package/.agent-src/commands/{memory-promote.md → memory/promote.md}

@@ -1,5 +1,7 @@
 ---
-name: memory-promote
+name: memory:promote
+cluster: memory
+sub: promote
 description: Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the admission gate.
 skills: [file-editor]
 disable-model-invocation: true
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Curation pipeline — overlaps /memory-add; keep explicit."
 ---
 
-# /memory-promote
-
+# /memory promote
 Moves an entry from the provisional layer (intake JSONL) into the
 curated layer (`agents/memory/<type>.yml` or sharded). Promotion is
 gated by
@@ -61,7 +62,7 @@ gate script to lower the bar.
 ### 3. Draft the curated entry
 
 Using the schema in
-[`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md),
+[`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md),
 hydrate the full frontmatter:
 
 - `id` — kebab-case slug (not the `sig-*` id — that is an intake marker).
@@ -142,4 +143,4 @@ git push -u origin memory/promote-<curated-id>
 
 - [`/propose-memory`](propose-memory.md) — write-side entry point.
 - [`/memory-add`](memory-add.md) — direct curated write (skips intake).
-- [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
+- [`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md)

package/.agent-src/commands/{propose-memory.md → memory/propose.md}

@@ -1,5 +1,7 @@
 ---
-name: propose-memory
+name: memory:propose
+cluster: memory
+sub: propose
 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
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Programmatic intake fallback — overlaps /memory-add; keep explicit."
 ---
 
-# /propose-memory
-
+# /memory propose
 Drops a **signal** into `agents/memory/intake/signals-YYYY-MM.jsonl` via
 `scripts/memory_signal.py`. Signals are append-only JSONL and merge-safe.
 
@@ -101,6 +102,6 @@ is intended (rarely).
 ## See also
 
 - [`/memory-add`](memory-add.md) — curated (reviewer-validated) entries.
-- [`engineering-memory-data-format`](../guidelines/agent-infra/engineering-memory-data-format.md)
-- [`memory-access`](../guidelines/agent-infra/memory-access.md) — the
+- [`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
+- [`memory-access`](../../docs/guidelines/agent-infra/memory-access.md) — the
   read-side contract that consumes what this command writes.

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

@@ -0,0 +1,48 @@
+---
+name: memory
+description: Memory orchestrator — routes to add, load, promote, propose
+cluster: memory
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "add a memory entry, load all memories, promote a signal, propose a finding"
+  trigger_context: "user wants to write to or curate engineering memory"
+---
+
+# /memory
+
+Top-level orchestrator for the `/memory` family. Replaces 4 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/memory add` | `commands/memory/add.md` | Interactively add a validated entry to a memory file |
+| `/memory load` | `commands/memory/load.md` | Load ALL curated entries of a given memory type into context |
+| `/memory promote` | `commands/memory/promote.md` | Promote an intake signal to a curated memory entry |
+| `/memory propose` | `commands/memory/propose.md` | Append a provisional signal to the intake stream |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/memory <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+
+   > 1. add — write a curated entry interactively
+   > 2. load — load ALL entries of a type for deep analysis
+   > 3. promote — promote an intake signal to a curated entry
+   > 4. propose — drop a provisional signal into the intake stream
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/memory <sub>` per turn.
+- If the user invokes `/memory` with no argument, **show the menu** — do
+  not guess which sub-command they meant.

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

@@ -11,7 +11,7 @@ suggestion:
 
 Sets `roles.active_role` in `.agent-settings.yml` and surfaces the active
 contract before any work. Six modes are defined in
-[`role-contracts`](../guidelines/agent-infra/role-contracts.md):
+[`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md):
 
 - `developer` · `reviewer` · `tester` · `po` · `incident` · `planner`
 
@@ -37,7 +37,7 @@ Anything else: refuse. List the valid values and stop.
 
 ### 2. Validate the mode name
 
-Read [`role-contracts.md`](../guidelines/agent-infra/role-contracts.md).
+Read [`role-contracts.md`](../../docs/guidelines/agent-infra/role-contracts.md).
 Extract H3 headings under `## Contract skeletons` and lowercase them.
 If `<name>` is not in that set, refuse and print the valid list.
 
@@ -62,7 +62,7 @@ exactly what the contract demands.
 ### 5. Write the active role
 
 Update `roles.active_role` in `.agent-settings.yml` using the
-[section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 (preserve comments, preserve key order, touch only the changed field).
 
 For `/mode none`: set `active_role: ""`.
@@ -118,7 +118,7 @@ For `/mode` (status only):
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md) — the six modes
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md) — the six modes
 - [`role-mode-adherence`](../rules/role-mode-adherence.md) — closing-output gate
-- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
+- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for settings edits
 - [`ask-when-uncertain`](../rules/ask-when-uncertain.md) — never invent modes

package/.agent-src/commands/{module-create.md → module/create.md}

@@ -1,5 +1,7 @@
 ---
-name: module-create
+name: module:create
+cluster: module
+sub: create
 skills: [laravel]
 description: Create a new module from .module-template with interactive setup
 disable-model-invocation: true
@@ -9,8 +11,7 @@ suggestion:
   trigger_context: "prompt mentions a new domain area without an existing module"
 ---
 
-# module-create
-
+# /module create
 ## Instructions
 
 ### 1. Check for module support

package/.agent-src/commands/{module-explore.md → module/explore.md}

@@ -1,5 +1,7 @@
 ---
-name: module-explore
+name: module:explore
+cluster: module
+sub: explore
 skills: [laravel]
 description: Explore a module — load its structure, docs, and context into the current conversation
 disable-model-invocation: true
@@ -9,8 +11,7 @@ suggestion:
   trigger_context: "existing Modules/<Name>/ referenced in the prompt"
 ---
 
-# module-explore
-
+# /module explore
 ## Instructions
 
 ### 1. Check for modules

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

@@ -0,0 +1,44 @@
+---
+name: module
+description: Module orchestrator — routes to create, explore
+cluster: module
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create a new module, explore an existing module"
+  trigger_context: "user wants to scaffold or load a module's docs and structure"
+---
+
+# /module
+
+Top-level orchestrator for the `/module` family. Replaces 2 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/module create` | `commands/module/create.md` | Create a new module from `.module-template` |
+| `/module explore` | `commands/module/explore.md` | Load a module's structure, docs, and context into the conversation |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/module <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+
+   > 1. create — scaffold a new module from the template
+   > 2. explore — load a module's docs and structure
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/module <sub>` per turn.
+- If the user invokes `/module` with no argument, **show the menu** — do
+  not guess which sub-command they meant.

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

@@ -25,7 +25,7 @@ Triggered by the [`onboarding-gate`](../rules/onboarding-gate.md) rule when
 - Change cost profile only → [`/set-cost-profile`](set-cost-profile.md).
 - Single-value edit → ask the agent to change it, or edit
   `.agent-settings.yml` directly. The agent follows the merge rules in
-  [`layered-settings`](../guidelines/agent-infra/layered-settings.md).
+  [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md).
 
 ## Preconditions
 
@@ -134,7 +134,7 @@ template — `minimal` + `skill_improvement: true`):
 
 Write `onboarding.onboarded: true` to `.agent-settings.yml` using the
 section-aware merge rules from
-[`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 (preserve comments, key order, touch only the changed fields).
 
 ### 8. Summary
@@ -200,5 +200,5 @@ local-agent concern; the cloud agent should proceed without invoking it.
 
 - [`onboarding-gate`](../rules/onboarding-gate.md) — rule that triggers this command
 - [`set-cost-profile`](set-cost-profile.md) — isolated profile change
-- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
+- [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — settings reference

package/.agent-src/commands/{optimize-agents.md → optimize/agents.md}

@@ -1,5 +1,7 @@
 ---
-name: optimize-agents
+name: optimize:agents
+cluster: optimize
+sub: agents
 description: Audits agent infrastructure — measures token overhead, checks rule triggers, verifies AGENTS.md. Suggest only, never auto-apply.
 skills: [copilot-agents-optimization, agents-audit, agent-docs-writing, quality-tools]
 disable-model-invocation: true
@@ -9,8 +11,7 @@ suggestion:
   trigger_context: "maintainer working on .augment/ files"
 ---
 
-# /optimize-agents
-
+# /optimize agents
 Agent infrastructure audit: measure token overhead, check rule triggers, verify AGENTS.md, find stale references. **Suggest only — never auto-apply.**
 
 **Source of truth:** `.agent-src.uncompressed/` — never read or edit `.agent-src/` or `.augment/` directly.
@@ -89,7 +90,7 @@ Present candidates with explicit justification. **Never auto-apply.**
 ### 4. Check AGENTS.md + copilot-instructions.md
 
 - **Budget**: AGENTS.md target ≤800 words (max ~1200). copilot-instructions.md < 60 lines (max ~150).
-  See `guidelines/agent-infra/size-and-scope.md` for all limits.
+  See `docs/guidelines/agent-infra/size-and-scope.md` for all limits.
 - **Quality**: Dev Setup, Testing, Quality Tools need full detail — don't compress to one-liners
 - **Duplication**: only word-for-word identical. Summary + detail = layered context, NOT duplication
 - **Freshness**: paths, commands, references match reality?

package/.agent-src/commands/{optimize-augmentignore.md → optimize/augmentignore.md}

@@ -1,17 +1,17 @@
 ---
 skills: [agent-docs-writing]
-name: optimize-augmentignore
+name: optimize:augmentignore
+cluster: optimize
+sub: 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
-
+# /optimize augmentignore
 Scans the project to find files that waste tokens in Augment's retrieval index
 and creates/updates `.augmentignore` accordingly. Also identifies irrelevant
 `.augment/skills/` and `.augment/rules/` to exclude them from the system prompt.

package/.agent-src/commands/{optimize-rtk-filters.md → optimize/rtk.md}

@@ -1,5 +1,7 @@
 ---
-name: optimize-rtk-filters
+name: optimize:rtk
+cluster: optimize
+sub: rtk
 skills: [agent-docs-writing]
 description: Create or optimize project-local rtk filters based on the actual toolchain
 disable-model-invocation: true
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Niche maintenance tool with no recurring NL trigger."
 ---
 
-# optimize-rtk-filters
-
+# /optimize rtk
 ## Instructions
 
 ### 1. Check rtk is installed