@event4u/agent-config 8.13.0 → 9.1.0

package/dist/agent-src/commands/ghostwriter/write.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: ghostwriter
 sub: write
 description: Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory non-removable disclosure footer.
+argument-hint: "[slug | --as=<slug>] [--tone] [--length] [--channel] [--audience]"
 suggestion:
   eligible: true
   trigger_description: "draft post in style of public figure, write in someone's voice, ghostwriter draft, LinkedIn post in style of X"

package/dist/agent-src/commands/ghostwriter.md

@@ -5,6 +5,7 @@ pack: gtm-marketing
 tier: 2
 visibility: internal
 description: Ghostwriter cluster — fetch, write, list, show, and delete public-figure voice profiles (the third voice primitive alongside personas/ and .agent-user.md).
+argument-hint: "[fetch|write|list|show|delete] [args]"
 cluster: ghostwriter
 type: orchestrator
 suggestion:

package/dist/agent-src/commands/grill-me.md

@@ -5,6 +5,7 @@ pack: product-reasoning
 tier: 2
 visibility: internal
 description: Alias for /challenge-me — interactive grill-style interview that sharpens a fuzzy plan/idea into a copyable Markdown pitch
+argument-hint: "[vision|with-docs] [flags] [seed]"
 cluster: challenge-me
 type: orchestrator
 suggestion:
@@ -20,27 +21,31 @@ packs:
 # /grill-me
 
 Alias for [`/challenge-me`](challenge-me.md). Identical behaviour,
-sub-commands (`vision`, `with-docs`), and in-interview triggers
-(`!pitch`, `!roadmap`, `!ai`).
+identical sub-commands (`vision`, `with-docs`), identical in-interview
+triggers (`!pitch`, `!roadmap`, `!ai`). Provided so users who think of
+the workflow as "grill me" rather than "challenge me" land on the same
+dispatcher without a second hop.
 
 ## Sub-commands
 
 | Sub-command | Routes to | Purpose |
 |---|---|---|
-| `/grill-me vision` | `commands/challenge-me/vision.md` | 95%-confidence interview, emits a vision pitch |
-| `/grill-me with-docs` | `commands/challenge-me/with-docs.md` | Same flow plus glossary + claim-vs-code check vs `CONTEXT.md` / ADRs |
+| `/grill-me vision` | `commands/challenge-me/vision.md` | Standard variant — interrogate to 95 % confidence, emit a vision pitch |
+| `/grill-me with-docs` | `commands/challenge-me/with-docs.md` | Doc-aware variant — same flow plus glossary + claim-vs-code verification against `CONTEXT.md` / ADRs |
 
 ## Dispatch
 
-1. Parse: `/grill-me <sub-command> [flags] [seed]`.
+1. Parse the user's argument: `/grill-me <sub-command> [flags] [seed]`.
 2. Load [`commands/challenge-me.md`](challenge-me.md) and follow its
-   `## Dispatch` verbatim with the same sub-command + flags + seed.
-3. Unknown / missing sub-command → print menu from `challenge-me.md`.
+   `## Dispatch` section verbatim with the same sub-command + flags + seed.
+3. If the sub-command is unknown or missing, print the menu from
+   `challenge-me.md` (do not guess).
 
 ## Rules
 
-- Thin alias — all behaviour, triggers, cost-gate, file-write rules
-  live in [`challenge-me.md`](challenge-me.md) and the routed sub-commands.
-  Do not duplicate them here; edit them there.
-- Suggestion engine surfaces this for free-form "grill me" prompts;
-  `/grill-me` is the direct invocation path.
+- This file is a **thin alias** — all behaviour, in-interview triggers,
+  cost-gate semantics, and file-write rules live in
+  [`commands/challenge-me.md`](challenge-me.md) and the routed
+  sub-command files. Do not duplicate them here; edit them there.
+- The suggestion engine surfaces this command for free-form "grill me"
+  prompts; the slash form `/grill-me` is the direct invocation path.

package/dist/agent-src/commands/humanize.md

@@ -5,6 +5,7 @@ pack: gtm-marketing
 tier: 2
 visibility: internal
 description: Remove AI-writing tells from pasted text or a file — runs the humanizer skill's draft→audit→final loop and prints the rewrite plus a detector summary.
+argument-hint: "[path] [--voice=<slug|me>] [--language=en|de|auto]"
 cluster: humanize
 skills: [humanizer]
 suggestion:

package/dist/agent-src/commands/image/analyse.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: image
 sub: analyse
 description: Analyse a character image down to the smallest mole and diff it against a canon — per-feature spec, OCR tattoo text, severity-ranked drift report.
+argument-hint: "<path-or-url> [character-id]"
 personas: [hollywood-director]
 skills: [image-analyser]
 suggestion:
@@ -29,7 +30,7 @@ to diff against, e.g. `veikko`).
 
 1. **Resolve the image** — accept a path or public URL. Apply the input gate
    (refuse blurry / sub-resolution / unreadable; per the `image-ocr` contract).
-2. **Governance check** — real-person likeness → route through
+2. **Governance check** — if the image is a real-person likeness, route through
    [`media-governance-routing`](../rules/media-governance-routing.md) first.
 3. **Run `image-analyser`** — section-by-section extraction (the "down to the
    smallest mole" pass), OCR sub-pass for lettered tattoos, hard-feature

package/dist/agent-src/commands/image/create.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: image
 sub: create
 description: Generate a character image to spec — assemble a max-fidelity, anchors-first prompt from a Canon Spec; governance- and provider-gated, dry-run by default.
+argument-hint: "<character-id> <scene> [analyse-diff]"
 personas: [hollywood-director]
 skills: [image-creator, character-consistency]
 suggestion:

package/dist/agent-src/commands/image/verify.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: image
 sub: verify
 description: Verify a candidate render against its canon — run the analyser in loop mode, emit the gate verdict + remaining diff, halt-and-surface on non-pass.
+argument-hint: "<path-or-url> <character-id>"
 personas: [hollywood-director]
 skills: [image-analyser]
 suggestion:

package/dist/agent-src/commands/image.md

@@ -6,6 +6,7 @@ tier: 2
 visibility: internal
 cluster: image
 description: Character-image fidelity orchestrator — analyse, create, and verify a character image against its canon. Routes to analyse, create, verify.
+argument-hint: "[analyse|create|verify] [args]"
 type: orchestrator
 suggestion:
   eligible: true
@@ -21,10 +22,11 @@ packs:
 
 Top-level orchestrator for the `/image:*` family — character-image
 **fidelity** work: analyse an image down to the smallest mole, generate one
-to spec, verify a candidate against its **Canon Spec**. Schema, rubric, and
-the create→analyse→regenerate loop: [`canon-spec.md`](../../skills/image-analyser/canon-spec.md).
-Generation is a paid surface: every live provider call is **dry-run /
-refuse-and-surface by default** and needs explicit per-turn confirmation per
+to spec, and verify a candidate against its **Canon Spec**. Schema, rubric,
+and the create→analyse→regenerate loop are defined in
+[`canon-spec.md`](../../skills/image-analyser/canon-spec.md). Generation is a
+paid surface: every live provider call is **dry-run / refuse-and-surface by
+default** and requires explicit per-turn confirmation per
 [`provider-lifecycle-discipline`](../rules/provider-lifecycle-discipline.md).
 
 ## Sub-commands
@@ -37,13 +39,15 @@ refuse-and-surface by default** and needs explicit per-turn confirmation per
 
 ## Dispatch
 
-1. Parse `/image <sub-command> [args]`. Sub-command = first token; match
-   against the table's exact names only. A token that is a **file path or
-   URL** (contains `/`, `.`, or a known image extension — e.g. `img_2.png`,
-   `shots/veikko.jpg`) is NOT a sub-command: it is the image argument for
-   `analyse` / `verify`. Never treat `img_2.png` as the `analyse`
-   sub-command. On this ambiguity → ask rather than best-guess.
-2. Look up the sub-command and execute its file verbatim with the remaining args.
+1. Parse `/image <sub-command> [args]`. The sub-command is the first
+   token; match it against the table's exact sub-command names only. A
+   token that is a **file path or URL** (contains `/`, `.`, or a known
+   image extension — e.g. `img_2.png`, `shots/veikko.jpg`) is NOT a
+   sub-command: it belongs to `analyse` / `verify` as the image argument.
+   Never treat `img_2.png` as the `analyse` sub-command. On this
+   ambiguity → ask rather than best-guess.
+2. Look up the sub-command in the table above and execute its file
+   verbatim with the remaining args.
 3. Unknown / missing sub-command → print the table and ask:
 
    > 1. analyse — extract + diff an image against a canon
@@ -68,4 +72,4 @@ refuse-and-surface by default** and needs explicit per-turn confirmation per
 
 - [`image-analyser`](../../skills/image-analyser/SKILL.md) · [`image-creator`](../../skills/image-creator/SKILL.md) — the skills these commands invoke.
 - [`canon-spec.md`](../../skills/image-analyser/canon-spec.md) — schema, fidelity rubric, fidelity loop.
-- [`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md) — `image` cluster registration.
+- [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md) — `image` cluster registration.

package/dist/agent-src/commands/implement-ticket.md

@@ -9,6 +9,7 @@ tier: 0
 visibility: visible
 skills: [refine-ticket, feature-planning]
 description: Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `work_engine` engine, block-on-ambiguity, no auto-git.
+argument-hint: "[ticket-key | url | bundle-path | pasted-text]"
 suggestion:
   eligible: true
   trigger_description: "implement this ticket, setze ticket X um, build PROJ-123"

package/dist/agent-src/commands/judge/on-diff.md

@@ -8,6 +8,7 @@ cluster: judge
 sub: on-diff
 skills: [subagent-orchestration, verify-completion-evidence]
 description: Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user
+argument-hint: "<task-description | draft-pointer>"
 suggestion:
   eligible: false
   rationale: "Subagent orchestration — overlaps /work and judge skills; keep explicit."

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

@@ -8,6 +8,7 @@ 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
+argument-hint: "[diff | commit-range | pr | files]"
 suggestion:
   eligible: false
   rationale: "Sibling of /review-changes — eligibility routed there; keep this explicit."

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

@@ -8,6 +8,7 @@ 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
+argument-hint: "<plan-file | roadmap-phase | inline-step-list>"
 suggestion:
   eligible: false
   rationale: "Subagent orchestration — overlaps /work and /roadmap:process-*; keep explicit."

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: judge
 disable-model-invocation: true
+argument-hint: "[solo|on-diff|steps] [args]"
 pack: engineering-base
 intent: "Adversarial-judging dispatcher — solo, on-diff, steps"
 routes_to: [judge-solo, judge-on-diff, judge-steps]

package/dist/agent-src/commands/knowledge/cross-repo.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: knowledge
 sub: cross-repo
 description: Targeted, read-only retrieval over opted-in linked-project siblings (ADR-032 Option A). Pulls a shared type / API contract / config without bulk-including sibling files.
+argument-hint: "<query> [--path-scope <glob>]"
 skills: [file-editor]
 suggestion:
   eligible: true

package/dist/agent-src/commands/knowledge/forget.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: knowledge
 sub: forget
 description: Drop a knowledge ingest from `agents/memory/knowledge/` by id prefix. Atomic, no partial state. Pinning protects from LRU eviction, not from explicit forget — pinned ingests are dropped the same.
+argument-hint: "<ingest-id-prefix>"
 skills: [file-editor]
 suggestion:
   eligible: true

package/dist/agent-src/commands/knowledge/ingest.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: knowledge
 sub: ingest
 description: Walk a local path (folder, .zip, single file), redact PII + secrets, chunk to 2 KB markdown, and persist into the agent memory namespace under `knowledge/<ingest-id>/`.
+argument-hint: "<path> [--no-redact] [--markitdown=<bin>]"
 skills: [file-editor]
 suggestion:
   eligible: true

package/dist/agent-src/commands/knowledge/list.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: knowledge
 sub: list
 description: List existing knowledge ingests in `agents/memory/knowledge/` (table or JSON); pin / unpin by id prefix to control LRU eviction.
+argument-hint: "[--format=table|json] [--pin <id-prefix>] [--unpin <id-prefix>]"
 skills: [file-editor]
 suggestion:
   eligible: true
@@ -88,6 +89,15 @@ Print `(no ingests)` and offer the next step:
   ingest, the command rejects with a structured error and asks for a
   longer prefix.
 
+## Retrieval-trigger signals
+
+Possessives ("my/our X"), definite references to unnamed prior work
+("that document", "the spec"), and past-time cues ("you ingested this
+last week") are signals the user expects knowledge to be available. Check
+`/knowledge list` before declaring the agent unaware of material the
+user has already provided. See also
+[`memory-consolidation § Retrieval-trigger linguistics`](../../../../skills/memory-consolidation/SKILL.md#retrieval-trigger-linguistics).
+
 ## See also
 
 - [`/knowledge ingest`](ingest.md) — add a new ingest.

package/dist/agent-src/commands/knowledge.md

@@ -5,6 +5,7 @@ pack: product-discovery
 tier: 2
 visibility: internal
 description: Knowledge orchestrator — routes to ingest, list, forget. Local-only file ingestion into the agent memory namespace.
+argument-hint: "[ingest|list|forget|cross-repo] [args]"
 cluster: knowledge
 type: orchestrator
 suggestion:

package/dist/agent-src/commands/memory/learn-low-impact.md

@@ -8,6 +8,7 @@ cluster: memory
 sub: learn-low-impact
 skills: [ai-council, upstream-contribute]
 description: Preview validated low-impact entries that would be upstreamed to the package seed (default `--preview`); `--apply` opens a draft PR via `upstream-contribute` after re-redaction.
+argument-hint: "[--preview|--apply]"
 suggestion:
   eligible: true
   trigger_description: "upstream low-impact decisions, share validated council questions, contribute the learning corpus"

package/dist/agent-src/commands/memory/mine-session.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: memory
 sub: mine-session
 description: Mine a session (cross-host chat-history log) for memory signals and/or rule/skill proposal seeds via --mode=[signals|proposals|both]. Preview-default, opt-in. Folds in /chat-history learn.
+argument-hint: "[--mode signals|proposals|both] [--since <date>] [--confirm-transcript-access] [--commit-intake]"
 skills: [memory-consolidation, file-editor]
 suggestion:
   eligible: false

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

@@ -7,6 +7,7 @@ visibility: internal
 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.
+argument-hint: "[sig-id]"
 skills: [file-editor]
 suggestion:
   eligible: false
@@ -141,8 +142,8 @@ detector before writing (same primary key + Jaccard body similarity
   > 3. Both are valid in different scopes — narrow the new entry's key and re-check
   ```
 
-Warning surface, not a gate — the human's pick resolves it; the
-detector never blocks a promote on its own. Non-durable types
+This is a warning surface, not a gate — the human's pick resolves it;
+the detector never blocks a promote on its own. Non-durable types
 (`sessions`-style exploratory content, `recurring-patterns`, …) are
 deliberately not checked — they evolve legitimately.
 

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: memory
 disable-model-invocation: true
+argument-hint: "[add|load|mine-session|promote|propose] [args]"
 pack: memory
 intent: "Manage the agent memory layer — add, load, promote, propose"
 routes_to: [memory-add, memory-load, memory-promote, memory-propose]

package/dist/agent-src/commands/mission/upgrade.md

@@ -10,6 +10,7 @@ visibility: advanced
 skills: [dependency-upgrade]
 framework: laravel
 description: Gated Laravel major-version upgrade mission — provisional branch, breaking-change catalog, size-tier surfaced, git-as-rollback. Never auto-commits or auto-PRs.
+argument-hint: "<target-version> [framework=<slug>]"
 suggestion:
   eligible: true
   trigger_description: "upgrade Laravel to version X, Laravel 10 to 11 upgrade, bump framework major version"
@@ -25,21 +26,24 @@ disable-model-invocation: true
 
 ## Overview
 
-Structured, catalog-driven Laravel major-version upgrade through the existing gated `/work` engine. **Not** a new autonomous runtime:
+`/mission:upgrade` runs a structured, catalog-driven Laravel major-version upgrade
+through the existing gated `/work` engine. It is **not** a new autonomous runtime:
 
-- Every phase uses `/work`'s confidence-band gating, N=3 retry budget, persisted `.work-state.json`.
-- Rollback = git. Changes land on a provisional branch (`mission/upgrade-…`); revert is `git reset` or `git revert`, never a daemon.
-- No auto-commit, no auto-PR. User reviews before anything is staged.
+- Every phase uses the `/work` engine's confidence-band gating, N=3 retry budget,
+  and persisted `.work-state.json`.
+- Rollback = git. Changes land on a provisional branch (`mission/upgrade-…`);
+  revert is `git reset` or `git revert`, never a daemon.
+- No auto-commit, no auto-PR. The user reviews before anything is staged.
 
 ## Single-mission-per-branch guard
 
 Before starting, confirm:
 
-1. Working tree clean (`git status --porcelain` empty).
-2. No other `mission/*` branch checked out.
-3. No `.work-state.json` with a mission envelope present.
+1. The working tree is clean (`git status --porcelain` returns empty).
+2. No other `mission/*` branch is already checked out.
+3. No `.work-state.json` with a mission envelope is present.
 
-Any fail → surface the conflict and stop. Run:
+If any of these fail, surface the conflict and stop. Run:
 
 ```bash
 ./scripts-run src/scripts/lint_missions --check-precondition upgrade .
@@ -65,11 +69,13 @@ Accept inline arguments:
 /mission:upgrade target_version=11 framework=laravel
 ```
 
-`target_version` missing → ask once (numbered options per [`user-interaction`](../../rules/user-interaction.md)).
+If `target_version` is missing, ask once (numbered options per
+[`user-interaction`](../../rules/user-interaction.md)).
 
 ### 2. Surface the size tier
 
-Read `size_tier` from `src/missions/upgrade/mission.yaml`; display before starting:
+Read `size_tier` from `src/missions/upgrade/mission.yaml` and display it before
+starting:
 
 ```
 > Mission: upgrade Laravel {from} → {target_version}
@@ -89,11 +95,15 @@ Read `size_tier` from `src/missions/upgrade/mission.yaml`; display before starti
 git checkout -b mission/upgrade-laravel-{from}-to-{target_version}
 ```
 
-Per [`scope-control`](../../rules/scope-control.md), requires explicit user confirmation (step 2 provides it).
+Per [`scope-control`](../../rules/scope-control.md), this requires explicit user
+confirmation (step 2 above provides it).
 
 ### 4. Load the breaking-change catalog
 
-Read `src/missions/upgrade/laravel-10-to-11.yaml` (or the matching version). Lists breaking changes with `detection`, `fix`, `verification` command blocks restricted to safe prefixes (`composer`, `php`, `php artisan`, `git`, `sed`, `rector`, `vendor/bin/*`).
+Read `src/missions/upgrade/laravel-10-to-11.yaml` (or the matching version).
+The catalog lists breaking changes with `detection`, `fix`, and `verification`
+command blocks restricted to safe prefixes
+(`composer`, `php`, `php artisan`, `git`, `sed`, `rector`, `vendor/bin/*`).
 
 ### 5. Drive the /work engine
 
@@ -103,16 +113,18 @@ Read `src/missions/upgrade/laravel-10-to-11.yaml` (or the matching version). Lis
     --prompt-file prompt.txt
 ```
 
-Write a structured prompt to `prompt.txt` describing the mission phases (`analyze` → `plan` → `implement` → `test` → `verify` → `report`) referencing the catalog entries the engine should address.
+Write a structured prompt to `prompt.txt` that describes the mission phases
+(`analyze` → `plan` → `implement` → `test` → `verify` → `report`) and references
+the catalog entries the engine should address.
 
 **Candidate phase (opt-in, never auto-on):** the `test` → `verify` step MAY use
 [`verify-repair-loop`](../../skills/verify-repair-loop/SKILL.md) when the upgrade's
 catalog fixes are test-driven — a bounded generate→run→revise→re-run loop gated by
 a numeric threshold (then a judge confirms), reusing the same N=3 cap. Use
 test/quality verdicts only; the live-app Playwright verdict stays deferred. The
-loop is multi-turn reasoning, not a runtime — honors
-[`no-runtime-boundary`](../../docs/contracts/no-runtime-boundary.md) exactly as the
-mission does.
+loop is multi-turn reasoning, not a runtime — it honors
+[`no-runtime-boundary`](../../docs/contracts/no-runtime-boundary.md) exactly as
+the mission does.
 
 Handle exit codes per the `/work` contract:
 
@@ -124,7 +136,7 @@ Handle exit codes per the `/work` contract:
 
 ### 6. Rollback path
 
-Fix step fails beyond the N=3 budget:
+If a fix step fails beyond the N=3 budget:
 
 ```bash
 git revert HEAD        # revert the last mission commit
@@ -132,7 +144,7 @@ git revert HEAD        # revert the last mission commit
 git reset --hard HEAD~1  # if no remote tracking the branch yet
 ```
 
-Rollback is always manual — the mission surfaces the command, never auto-runs it.
+The rollback is always manual — the mission surfaces the command, never auto-runs it.
 
 ### 7. Final report and close-prompt
 
@@ -147,18 +159,27 @@ On `/work` exit `0`, surface the delivery report unchanged, then append:
 > 4. Discard — delete .work-state.json and reset the branch
 ```
 
-Per [`scope-control`](../../rules/scope-control.md), git operations are permission-gated. Never run `/commit` or `/create-pr` without the user choosing them.
+Per [`scope-control`](../../rules/scope-control.md), git operations are
+permission-gated. Never run `/commit` or `/create-pr` without the user choosing
+them.
 
 ## Rules
 
-- Honour [`scope-control`](../../rules/scope-control.md), [`non-destructive-by-default`](../../rules/non-destructive-by-default.md), [`minimal-safe-diff`](../../rules/minimal-safe-diff.md), [`verify-before-complete`](../../rules/verify-before-complete.md).
-- Every catalog `command:` field is restricted to the safe-prefix allowlist. Never run arbitrary shell from the catalog.
-- The N=3 retry budget from [`autonomous-execution`](../../rules/autonomous-execution.md) applies per breaking-change fix step, not per mission.
-- Never skip the size-tier surface step — user must see scope before the provisional branch is created.
+- Honour [`scope-control`](../../rules/scope-control.md),
+  [`non-destructive-by-default`](../../rules/non-destructive-by-default.md),
+  [`minimal-safe-diff`](../../rules/minimal-safe-diff.md), and
+  [`verify-before-complete`](../../rules/verify-before-complete.md).
+- Every catalog `command:` field is restricted to the safe-prefix allowlist.
+  Never run arbitrary shell commands from the catalog.
+- The N=3 retry budget from [`autonomous-execution`](../../rules/autonomous-execution.md)
+  applies per breaking-change fix step, not per mission.
+- Never skip the size-tier surface step — the user must see the scope before the
+  provisional branch is created.
 
 ## Breaking-change catalog
 
-Knowledge source: `src/missions/upgrade/laravel-10-to-11.yaml`. Versionable, diffable, CI-tested via `lint_missions.ts`. Each entry carries:
+The knowledge source is `src/missions/upgrade/laravel-10-to-11.yaml`. It is
+versionable, diffable, and CI-tested via `lint_missions.ts`. Each entry carries:
 
 - `id` — unique checkpoint key (used in `.work-state.json`)
 - `severity` — `critical` / `high` / `medium` / `low`

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

@@ -8,6 +8,7 @@ replaces: []
 tier: 1
 visibility: advanced
 description: Set the active role mode — prints the contract, lists default skills, and refuses work outside the contract (see role-contracts)
+argument-hint: "[developer|reviewer|tester|po|incident|planner|none]"
 suggestion:
   eligible: false
   rationale: "Role-mode switch is a deliberate context change."

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

@@ -8,6 +8,7 @@ cluster: module
 sub: create
 skills: [laravel]
 description: Create a new module from .module-template with interactive setup
+argument-hint: "[module-name]"
 suggestion:
   eligible: true
   trigger_description: "create a new module, scaffold a module for X"

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

@@ -8,6 +8,7 @@ cluster: module
 sub: explore
 skills: [laravel, symfony-workflow, php-coder]
 description: Explore a module — load its structure, docs, and context into the current conversation
+argument-hint: "[module-name]"
 suggestion:
   eligible: true
   trigger_description: "show me the X module, load the module context"

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: module
 disable-model-invocation: true
+argument-hint: "[create|explore] [args]"
 pack: engineering-base
 tier: 2
 visibility: internal

package/dist/agent-src/commands/optimize/agents-dir.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: optimize
 sub: agents-dir
 description: Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / --audit / --fix); default = interactive wizard.
+argument-hint: "[--scaffold|--audit|--fix]"
 skills: [agents-audit, agent-docs-writing, override-management, module-management]
 suggestion:
   eligible: true

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

@@ -8,6 +8,7 @@ sub: project
 cluster: optimize
 skills: [project-analyzer, decision-review, roadmap-writing]
 description: "Project-wide optimization sweep — inventory roadmaps, ADRs, agent folders (incl. modules), challenge stale decisions with the user in the loop, emit new roadmap(s). E.g. 'optimize this project'."
+argument-hint: "[--max-questions=N]"
 suggestion:
   eligible: true
   trigger_description: "optimize this project, optimize the project, what should we improve based on current state, challenge our old decisions, are our roadmaps and ADRs still right, optimiere das Projekt, hinterfrag unsere alten Entscheidungen"

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

@@ -7,6 +7,7 @@ visibility: internal
 sub: prompt
 cluster: optimize
 description: "Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt."
+argument-hint: "[DETAIL|BASIC] [using <ai>] [prompt]"
 skills: [prompt-optimizer]
 suggestion:
   eligible: true

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: optimize
 disable-model-invocation: true
+argument-hint: "[skills|agents-dir|augmentignore|rtk|project|prompt] [args]"
 pack: meta
 intent: "Optimization dispatcher — skills, rtk, augmentignore, agents-dir, project sweep, prompt"
 routes_to: [optimize-skills, optimize-rtk, optimize-augmentignore, optimize-agents-dir, optimize-project, optimize-prompt]
@@ -43,7 +44,7 @@ the **agent layer** (skills, agents-dir, augmentignore, rtk), the **project**
 | `/optimize prompt` | `commands/optimize/prompt.md` | Optimize a raw prompt for ChatGPT/Claude/Gemini via the 4-D methodology |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/dist/agent-src/commands/orchestrate.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: orchestrate
 skills: [subagent-orchestration]
 description: Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / sub-agents per the orchestration-dsl-v1 contract
+argument-hint: "<pipeline-name | path> [key=value ...]"
 suggestion:
   eligible: true
   trigger_description: "run a saved orchestration / pipeline / chain"

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: override
 disable-model-invocation: true
+argument-hint: "[create|manage] [args]"
 pack: meta
 tier: 2
 visibility: internal

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: package
 disable-model-invocation: true
+argument-hint: "[test|reset]"
 pack: meta
 intent: "Package dispatcher — test the package install or reset the installed state"
 routes_to: [package-test, package-reset]
@@ -33,7 +34,7 @@ agent-config package installation itself.
 | `/package reset` | `commands/package/reset.md` | Reset the installed package state (destructive — confirmation-gated) |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/dist/agent-src/commands/post-as/ghostwriter.md

@@ -8,6 +8,7 @@ cluster: post-as
 sub: ghostwriter
 skills: [post-as, ghostwriter]
 description: Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with the mandatory non-removable disclosure footer.
+argument-hint: "[slug | --as=<slug>] [--tone] [--length] [--channel] [--audience]"
 suggestion:
   eligible: true
   trigger_description: "post as ghostwriter, draft as a public figure, write in style of X, post-as alias for ghostwriter:write"

package/dist/agent-src/commands/post-as/me.md

@@ -8,6 +8,7 @@ cluster: post-as
 sub: me
 skills: [post-as]
 description: Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample). No disclosure footer — the user is the author.
+argument-hint: "[topic] [--tone] [--length] [--channel] [--audience]"
 suggestion:
   eligible: true
   trigger_description: "write as me, draft in my own voice, post as myself, draft from .agent-user.md"

package/dist/agent-src/commands/post-as.md

@@ -5,6 +5,7 @@ pack: gtm-marketing
 tier: 2
 visibility: internal
 description: Consumer-facing write entry points — :me drafts in the maintainer's own voice from .agent-user.md (no disclosure); :ghostwriter is a thin alias for /ghostwriter:write (mandatory disclosure footer).
+argument-hint: "[me|ghostwriter] [args]"
 cluster: post-as
 type: orchestrator
 suggestion: