@event4u/agent-config 1.14.0 → 1.16.0

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "turn this feature into a roadmap, generate the implementation roadmap"
   trigger_context: "existing feature plan without linked roadmap"
+superseded_by: feature roadmap
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-roadmap is deprecated; use /feature roadmap instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # feature-roadmap
 
 ## Instructions
@@ -176,8 +181,8 @@ What's next?
 ### Rules
 
 - **Do NOT commit or push.**
-- **Do NOT include commit steps** unless user explicitly requested them.
-  See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
+- **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).
 - **Do NOT modify the feature plan** beyond updating the Roadmaps section and status.
 - **Always link roadmaps back to the feature** and vice versa.
 - **Use the roadmap template** from `agents/roadmaps/template.md`.
@@ -187,4 +192,4 @@ What's next?
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#planner) — Planner mode output contract (Goal / Constraints / Option set / Recommendation / Dependencies / Rollback)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#planner) — Planner mode output contract (Goal / Constraints / Option set / Recommendation / Dependencies / Rollback)

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

@@ -0,0 +1,58 @@
+---
+name: feature
+description: Feature orchestrator — routes to explore, plan, refactor, roadmap, dev
+cluster: feature
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "explore feature idea, plan a feature, refactor feature plan, roadmap a feature, full feature dev"
+  trigger_context: "user starting or iterating on a feature workflow"
+---
+
+# /feature
+
+Top-level orchestrator for the `/feature` family. Replaces 5 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/feature explore` | `feature-explore.md` | Brainstorm an idea before committing to a plan |
+| `/feature plan` | `feature-plan.md` | Interactively plan a feature, produce a structured plan doc |
+| `/feature refactor` | `feature-refactor.md` | Refine and update an existing feature plan |
+| `/feature roadmap` | `feature-roadmap.md` | Generate implementation roadmap(s) from a plan |
+| `/feature dev` | `feature-dev.md` | Full 7-phase feature development workflow (heavyweight) |
+
+## Workflow ordering
+
+Typical sequence: `explore` → `plan` → `roadmap` → `dev` (or per-step
+implementation). Use `refactor` whenever an existing plan needs an update.
+
+## Dispatch
+
+1. Parse the user's argument: `/feature <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the corresponding `commands/feature-<sub>.md` file and
+   follow its `## Instructions` (or `## Steps`) section verbatim.
+4. If the sub-command is unknown or missing, print the menu and ask:
+
+   > 1. explore — brainstorm a feature idea
+   > 2. plan — produce a structured feature plan
+   > 3. refactor — update an existing feature plan
+   > 4. roadmap — generate roadmap(s) from a plan
+   > 5. dev — run the full 7-phase development workflow
+
+## Migration
+
+The 5 standalone `/feature-*` commands continue to work for one release
+cycle as deprecation shims. They emit a notice and route to the same
+content. New invocations should use `/feature <sub>`.
+
+## Rules
+
+- **Do NOT chain sub-commands.** One `/feature <sub>` per turn — except
+  the agent may suggest the next logical sub-command at the end of a step
+  (numbered options per `user-interaction`).
+- If the user invokes `/feature` with no argument, **show the menu** — do
+  not guess which sub-command they meant.

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "CI is failing, fix the GitHub Actions errors, the pipeline is red"
   trigger_context: "open PR with failing checks"
+superseded_by: fix ci
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-ci is deprecated; use /fix ci instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-ci
 
 ## Instructions

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

@@ -5,8 +5,13 @@ disable-model-invocation: true
 suggestion:
   eligible: false
   rationale: "Package-internal — only the event4u/agent-config repo runs this."
+superseded_by: fix portability
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-portability is deprecated; use /fix portability instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-portability
 
 ## Instructions
@@ -92,8 +97,8 @@ python3 scripts/compress.py --mark-done "{relative_path}"
 
 ## Rules
 
-- **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
-- **Run `bash scripts/compress.sh --sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Always fix in `.agent-src.uncompressed/`** — never edit `.augment/` directly.
+- **Copy to `.augment/`** after fixing.
 - **Do NOT commit or push.**
 - **`agents/` directory is allowed** to have project-specific references — skip it.
 - **Do NOT fix references in code blocks** unless the code block is clearly a template.

package/.agent-src/commands/fix-pr-bot-comments.md

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "address the Copilot/Greptile comments, fix the bot review feedback"
   trigger_context: "open PR with bot review comments unresolved"
+superseded_by: fix pr-bots
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-pr-bot-comments is deprecated; use /fix pr-bots instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-pr-bot-comments
 
 ## Input

package/.agent-src/commands/fix-pr-comments.md

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "fix all PR review comments, resolve the review feedback"
   trigger_context: "open PR with unresolved comments (bot + human)"
+superseded_by: fix pr
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-pr-comments is deprecated; use /fix pr instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-pr-comments
 
 This command runs `fix-pr-bot-comments` and `fix-pr-developer-comments` in sequence on the same PR.

package/.agent-src/commands/fix-pr-developer-comments.md

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "fix the human reviewer comments, address the developer feedback"
   trigger_context: "open PR with unresolved human-reviewer comments"
+superseded_by: fix pr-developers
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-pr-developer-comments is deprecated; use /fix pr-developers instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-pr-developer-comments
 
 ## Input

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

@@ -5,8 +5,13 @@ disable-model-invocation: true
 suggestion:
   eligible: false
   rationale: "Package-internal — only the event4u/agent-config repo runs this."
+superseded_by: fix refs
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-references is deprecated; use /fix refs instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-references
 
 ## Instructions

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "the seeder is broken, foreign key errors in seeders"
   trigger_context: "seeder error output or recent edits in database/seeders/"
+superseded_by: fix seeder
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /fix-seeder is deprecated; use /fix seeder instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # fix-seeder
 
 Scans all `PhpDataSeeder` data files for foreign key references that use raw seeder constants

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

@@ -0,0 +1,60 @@
+---
+name: fix
+description: Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-developer-comments
+cluster: fix
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix CI, fix references, fix the broken seeder, fix PR comments, address bot review"
+  trigger_context: "user wants to fix something that has a dedicated sub-command"
+---
+
+# /fix
+
+Top-level orchestrator for the `/fix` family. Replaces 7 standalone commands
+with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/fix ci` | `fix-ci.md` | Fetch CI errors from GitHub Actions and fix them |
+| `/fix refs` | `fix-references.md` | Find and fix broken cross-references in `.augment/` and `agents/` |
+| `/fix portability` | `fix-portability.md` | Find and fix project-specific references in shared `.augment/` files |
+| `/fix seeder` | `fix-seeder.md` | Scan seeder data files for broken FK references |
+| `/fix pr` | `fix-pr-comments.md` | Fix and reply to **all** open review comments (bots + humans) |
+| `/fix pr-bots` | `fix-pr-bot-comments.md` | Fix and reply to **bot** review comments only |
+| `/fix pr-developers` | `fix-pr-developer-comments.md` | Fix and reply to **human** reviewer comments only |
+
+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: `/fix <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. ci — fetch and fix GitHub Actions errors
+   > 2. refs — fix broken cross-refs in agent docs
+   > 3. portability — purge project-specific refs from shared package
+   > 4. seeder — scan seeders for broken FK references
+   > 5. pr — address all open review comments
+   > 6. pr-bots — address bot reviewer comments only
+   > 7. pr-developers — address human reviewer comments only
+
+## Migration
+
+The 7 standalone `/fix-*` commands continue to work for one release cycle as
+deprecation shims. They emit a notice and route to the same content. New
+invocations should use `/fix <sub>`.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it. Sub-command rules override these defaults only when stated.
+- **Do NOT chain sub-commands.** One `/fix <sub>` per turn.
+- If the user invokes `/fix` with no argument, **show the menu** — do not
+  guess which sub-command they meant.

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

@@ -72,4 +72,4 @@ suggestion:
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#developer) — Developer mode output contract (Goal / Plan / Changes / Tests / Open questions)

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

@@ -86,4 +86,4 @@ Next step: <what the user should do based on the verdict>
 - [`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)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)

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

@@ -14,7 +14,7 @@ suggestion:
 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 +58,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 +125,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

@@ -80,7 +80,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 +96,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

@@ -61,7 +61,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 +142,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/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/onboard.md

@@ -8,6 +8,8 @@ suggestion:
   rationale: "Gated by the onboarding-gate rule already; never inferred from prose."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /onboard
 
 Centralized first-run flow. Bundles what used to be scattered "ask once"
@@ -23,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
 
@@ -132,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
@@ -158,10 +160,10 @@ you ask it to change a value.
 
 ### 9. Maintainer-only feature pointer
 
-One-screen hint after the summary — no question, no prompt. Pointer for
-maintainers who want to opt into artefact-engagement telemetry. Consumers
-can ignore it; the feature is **default-off** and stays off unless
-explicitly enabled.
+Print a one-screen hint after the summary — no question, no prompt, just a
+pointer for maintainers who want to opt into the artefact-engagement
+telemetry layer. Consumers can ignore it; the feature is **default-off**
+and stays off unless explicitly enabled.
 
 ```
 ℹ️  Maintainer telemetry (opt-in)
@@ -172,7 +174,7 @@ explicitly enabled.
 
   The log is local-only JSONL — nothing uploaded, nothing shared across
   projects. Reports: ./agent-config telemetry:report
-  Contract + privacy floor: agents/contexts/artifact-engagement-flow.md
+  Contract + privacy floor: docs/contracts/artifact-engagement-flow.md
 ```
 
 Skip this block in cloud surfaces (no settings file, no log path).
@@ -187,9 +189,16 @@ Skip this block in cloud surfaces (no settings file, no log path).
 - Never overwrite a non-empty value without asking (applies to `user_name`
   and `ide`).
 
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+there is no `.agent-settings.yml` to write, no `onboarding.onboarded` key to
+flip, and no local IDE/rtk environment to capture. First-run setup is a
+local-agent concern; the cloud agent should proceed without invoking it.
+
 ## See also
 
 - [`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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "audit agent infrastructure, tune the agent setup"
   trigger_context: "maintainer working on .augment/ files"
+superseded_by: optimize agents
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /optimize-agents is deprecated; use /optimize agents instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # /optimize-agents
 
 Agent infrastructure audit: measure token overhead, check rule triggers, verify AGENTS.md, find stale references. **Suggest only — never auto-apply.**
@@ -89,7 +94,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

@@ -6,8 +6,15 @@ disable-model-invocation: true
 suggestion:
   eligible: false
   rationale: "Niche maintenance tool with no recurring NL trigger."
+superseded_by: optimize augmentignore
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /optimize-augmentignore is deprecated; use /optimize augmentignore instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+<!-- cloud_safe: noop -->
+
 # /optimize-augmentignore
 
 Scans the project to find files that waste tokens in Augment's retrieval index
@@ -263,3 +270,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

@@ -6,8 +6,13 @@ disable-model-invocation: true
 suggestion:
   eligible: false
   rationale: "Niche maintenance tool with no recurring NL trigger."
+superseded_by: optimize rtk
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /optimize-rtk-filters is deprecated; use /optimize rtk instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # optimize-rtk-filters
 
 ## Instructions

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "audit my skills, find duplicate skills"
   trigger_context: "maintainer working on .augment/skills/ files"
+superseded_by: optimize skills
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /optimize-skills is deprecated; use /optimize skills instead.
+> This shim is retained for one release cycle (1.15.0 → next minor) and forwards to the same instructions below. See [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
 # /optimize-skills
 
 Skill audit: measure, find duplicates/merge candidates, run linter, present findings. **Suggest only — never auto-apply.**
@@ -78,7 +83,7 @@ done
 ```
 
 Oversized → suggest splitting by responsibility or extracting reference material.
-Size limits: see `guidelines/agent-infra/size-and-scope.md`.
+Size limits: see `docs/guidelines/agent-infra/size-and-scope.md`.
 
 ### 6. Present findings
 

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

@@ -0,0 +1,54 @@
+---
+name: optimize
+description: Optimize orchestrator — routes to skills, agents, augmentignore, rtk-filters
+cluster: optimize
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "optimize my skills, audit agents, tune augmentignore, optimize rtk filters"
+  trigger_context: "maintainer auditing or trimming agent infrastructure"
+---
+
+# /optimize
+
+Top-level orchestrator for the `/optimize` family. Replaces 4 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/optimize skills` | `optimize-skills.md` | Audit skills — measure baseline, find duplicates, run linter |
+| `/optimize agents` | `optimize-agents.md` | Audit agent infrastructure — token overhead, rule triggers, AGENTS.md |
+| `/optimize augmentignore` | `optimize-augmentignore.md` | Create or refine `.augmentignore` based on actual stack |
+| `/optimize rtk` | `optimize-rtk-filters.md` | Create or refine project-local rtk filters |
+
+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: `/optimize <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the corresponding `commands/optimize-<sub>.md` file and
+   follow its `## Steps` (or `## Instructions`) section verbatim.
+4. If the sub-command is unknown or missing, print the menu and ask:
+
+   > 1. skills — audit skills (find duplicates, run linter)
+   > 2. agents — audit agent infrastructure (token overhead, rule triggers)
+   > 3. augmentignore — create or refine `.augmentignore`
+   > 4. rtk — create or refine project-local rtk filters
+
+## Migration
+
+The 4 standalone `/optimize-*` commands continue to work for one release
+cycle as deprecation shims. They emit a notice and route to the same
+content. New invocations should use `/optimize <sub>`.
+
+## Rules
+
+- **Suggest only — never auto-apply.** All `/optimize` sub-commands are
+  audit-grade: they report and propose, but the user approves every change.
+- **Do NOT chain sub-commands.** One `/optimize <sub>` per turn.
+- If the user invokes `/optimize` with no argument, **show the menu** — do
+  not guess which sub-command they meant.

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

@@ -101,6 +101,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/refine-ticket.md

@@ -34,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.
-
-Quoted identifiers stay native; only prose mirrors the picked language.
+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 (keys, paths, commands) stay native; only the
+prose mirrors the picked language.
 
 ### 3. Run the refine-ticket skill