@event4u/agent-config 1.15.0 → 1.16.0

package/.agent-src/commands/do-in-steps.md

@@ -1,6 +1,6 @@
 ---
 name: do-in-steps
-skills: [subagent-orchestration, verify-before-complete]
+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:
@@ -57,7 +57,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 +77,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/e2e-heal.md

@@ -21,7 +21,7 @@ suggestion:
 > 2. Fix a specific test file — which one?
 > 3. Fix tests that failed in CI — provide the CI run URL or error output
 
-- Read the Playwright guideline: `.augment/guidelines/e2e/playwright.md`
+- Read the Playwright guideline: `../../docs/guidelines/e2e/playwright.md`
 
 ### 2. Run failing tests
 

package/.agent-src/commands/e2e-plan.md

@@ -21,7 +21,7 @@ suggestion:
 > 2. Which feature area? (e.g., "checkout flow", "user settings", or "all visible flows")
 > 3. Is there an existing seed/setup file? (e.g., `tests/e2e/fixtures/auth.ts`)
 
-- Read the Playwright guideline: `.augment/guidelines/e2e/playwright.md`
+- Read the Playwright guideline: `../../docs/guidelines/e2e/playwright.md`
 - Check for existing test plans in `specs/` or `tests/e2e/specs/`.
 
 ### 2. Explore the application

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

@@ -8,6 +8,14 @@ suggestion:
   trigger_description: "build this feature end-to-end, run the full feature workflow"
   trigger_context: "long-form feature description spanning multiple components"
 ---
+
+<!-- F2-deprecation-banner -->
+> **Deprecated — use `/feature dev`.** This standalone command
+> is kept as a deprecation shim for one release cycle and routes to
+> the same instructions below. New invocations should go through the
+> `/feature` orchestrator (`commands/feature.md`).
+<!-- /F2-deprecation-banner -->
+
 # /feature-dev
 
 > Full 7-phase feature development workflow for complex features.

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "brainstorm this idea, explore this feature concept"
   trigger_context: "open-ended feature idea without acceptance criteria"
+superseded_by: feature explore
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-explore is deprecated; use /feature explore 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-explore
 
 ## Instructions
@@ -181,4 +186,4 @@ What's next?
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "plan this feature, create a feature spec for X"
   trigger_context: "feature idea referenced and no plan doc exists"
+superseded_by: feature plan
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-plan is deprecated; use /feature plan 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-plan
 
 ## Instructions
@@ -111,7 +116,7 @@ Before asking detailed questions, **proactively research**:
   `status: active` is a binding constraint — propose structure that
   respects it. If the feature needs to contradict an ADR, surface that
   as a decision for the user before drafting the plan. See
-  [`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).
 
 **Share key findings with the user** — this informs the discussion:
 
@@ -208,6 +213,32 @@ Mir sind noch ein paar offene Fragen aufgefallen:
 Hast du dazu schon eine Meinung?
 ```
 
+### 5d. Offer council idea-validation (B4 hook)
+
+Once the conversation has converged on a problem statement, proposal,
+and rough scope (rounds 1–4), but **before** step 6 writes the file,
+ask (in the user's language):
+
+> 1. Run the council on this idea before writing the plan? (billable)
+> 2. Skip — write the plan now
+
+Suppress when `personal.autonomy: on` (council is billable).
+
+If picked **1**:
+
+- Build a short prompt: the problem, the proposal, the scope, the
+  open questions from round 4. **Do not** include the agent's
+  framing or recommendations — neutrality preamble is mandatory.
+- Run `/council prompt:"<assembled prompt>"` with `original_ask` set
+  to the feature title from step 1.
+- Surface convergent + divergent points back to the user. **Do not**
+  rewrite the proposal autonomously; let the user decide which
+  council points to fold in.
+- After the user has reviewed, return to step 6 with the (possibly
+  updated) proposal.
+
+If picked **2** → continue.
+
 ### 6. Create the feature document
 
 - Read `.augment/templates/features.md` for the structure.
@@ -287,6 +318,6 @@ What's next?
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md#po) — PO mode output contract (Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder)
 - [`refine-ticket`](refine-ticket.md) — optional upstream step: run first when the input is a Jira/Linear ticket rather than a fresh idea
 - [`estimate-ticket`](estimate-ticket.md) — sibling of `refine-ticket`; size + risk + split recommendation for an already-refined ticket

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

@@ -7,8 +7,13 @@ suggestion:
   eligible: true
   trigger_description: "update the feature plan, refine the feature spec"
   trigger_context: "existing agents/features/*.md referenced in the prompt"
+superseded_by: feature refactor
+deprecated_in: "1.15.0"
 ---
 
+> ⚠️  /feature-refactor is deprecated; use /feature refactor 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-refactor
 
 ## Instructions

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
@@ -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

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

@@ -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

@@ -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,13 @@ 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

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