@event4u/agent-config 8.13.0 → 9.1.0

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

@@ -8,6 +8,7 @@ cluster: brand
 sub: tokens
 skills: [brand-to-tokens]
 description: Derive a DTCG .tokens.json source of truth from brand decisions, then emit CSS vars + Tailwind via the no-Node token generator.
+argument-hint: "<identity-ref>"
 suggestion:
   eligible: true
   trigger_description: "derive brand tokens, turn our brand into design tokens, generate a .tokens.json from the brand"
@@ -20,9 +21,9 @@ packs:
 
 # /brand:tokens
 
-Run the [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) skill — brand
-decisions → a DTCG `.tokens.json` source of truth → `design-tokens` emits CSS
-vars + Tailwind (no Node). The same `.tokens.json` is the export pack-ai-image's
-brand-asset generation and the greenfield scaffold seed consume; stays on
-`$value`/`$type` so Tokens Studio / Style Dictionary round-trip. Args:
-`"<identity ref>"`.
+Run the [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) skill —
+brand decisions → a DTCG `.tokens.json` source of truth → `design-tokens`
+emits CSS vars + Tailwind (no Node). The same `.tokens.json` is the export that
+`pack-ai-image`'s brand-asset generation and the greenfield scaffold seed
+consume; stays on `$value`/`$type` so Tokens Studio / Style Dictionary
+round-trip. Args: `"<identity ref>"`.

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

@@ -8,6 +8,7 @@ cluster: brand
 sub: voice
 skills: [voice-and-tone-design]
 description: Define the brand voice-and-tone profile — register, do/don't lexicon, and tone shifts by context — the profile the brand-consistency gate checks copy against.
+argument-hint: "<brand-ref | strategy-ref>"
 suggestion:
   eligible: true
   trigger_description: "define our brand voice, voice and tone guide, how should our copy sound, tone of voice profile"
@@ -21,7 +22,7 @@ packs:
 # /brand:voice
 
 Run the [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md)
-skill — register, do/don't lexicon, per-context tone shifts. The voice profile
-is what `/brand:review` and the `brand-consistency` gate check emitted copy
-against. Args: `"<brand/strategy ref>"`. Run `/brand:strategy` first when the
-archetype/positioning is not yet set.
+skill — register, do/don't lexicon, and per-context tone shifts. The resulting
+voice profile is what `/brand:review` and the `brand-consistency` gate check
+emitted copy against. Args: `"<brand/strategy ref>"`. Run `/brand:strategy`
+first when the archetype/positioning is not yet set.

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: brand
 type: orchestrator
 description: Brand-as-UX orchestrator — strategy, identity, tokens, review, voice. Routes to the brand-grounding skills that constrain the design layer.
+argument-hint: "[strategy|identity|tokens|review|voice] [args]"
 suggestion:
   eligible: true
   trigger_description: "work on our brand, define brand strategy/identity/voice, derive brand tokens, audit brand consistency"
@@ -20,11 +21,12 @@ packs:
 # /brand
 
 Top-level orchestrator for the `/brand:*` family — brand as a first-class UX
-layer that **constrains** the UI. Consulted **before**
+layer that **constrains** the UI. The brand layer is consulted **before**
 [`design-intelligence`](../../skills/design-intelligence/SKILL.md) so brand
-bounds style selection. Designer flow: discover → strategy → identity → tokens →
-application → governance. Derived brand tokens are the export pack-ai-image's
-brand-asset generation and the greenfield scaffold seed consume (B → A).
+decisions bound style selection. Walk the designer flow: discover → strategy →
+identity → tokens → application → governance. Brand tokens, once derived, are
+the export that pack-ai-image's brand-asset generation and the greenfield
+scaffold seed consume (B → A dependency).
 
 ## Sub-commands
 
@@ -47,9 +49,9 @@ brand-asset generation and the greenfield scaffold seed consume (B → A).
 
 - **Do NOT commit, push, or open a PR** — subcommands never do this.
 - **Do NOT chain subcommands.** One `/brand <sub>` per turn.
-- **Consumer brand tokens are the source of truth.** Corpus only fills gaps; a
-  value not traceable to a brand token or voice rule is off-brand (per
-  [`brand-consistency`](../rules/brand-consistency.md)).
+- **Consumer brand tokens are the source of truth.** The brand corpus only
+  fills gaps; a value not traceable to a brand token or voice rule is off-brand
+  (per [`brand-consistency`](../rules/brand-consistency.md)).
 - **Edit `src/` only.** Generated mirrors regenerate.
 
 ## See also

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

@@ -8,6 +8,7 @@ sub: fix
 cluster: bug
 skills: [bug-analyzer, pest-testing]
 description: Plan and implement a bug fix — based on investigation, with quality checks and test verification
+argument-hint: "[bug-description]"
 council_depth: deep
 suggestion:
   eligible: true

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

@@ -8,6 +8,7 @@ sub: investigate
 cluster: bug
 skills: [bug-analyzer, sentry-integration]
 description: Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause
+argument-hint: "[ticket-key | sentry-url | error-message | description]"
 council_depth: deep
 suggestion:
   eligible: true

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: bug
 disable-model-invocation: true
+argument-hint: "[investigate|fix] [args]"
 pack: engineering-base
 intent: "Bug dispatcher — investigate the root cause or implement the fix"
 routes_to: [bug-investigate, bug-fix]
@@ -34,7 +35,7 @@ user knows they have a defect but has not picked a workflow yet.
 | `/bug fix` | `commands/bug/fix.md` | Plan and implement a bug fix — based on investigation, with quality checks and test verification |
 
 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/challenge-me/vision.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: challenge-me
 sub: vision
 description: "Stress-test a plan or idea by one-question-at-a-time interview until 95% confidence — emits a copyable Markdown vision pitch for tickets, roadmaps, or fresh-chat handoff."
+argument-hint: "[--until=N] [--keep-going] [seed]"
 suggestion:
   eligible: true
   trigger_description: "challenge me on this plan, grill me, grill me on this, grill me on the vision, grill me on the idea, grill me until it's clear, grill me hard, frag mich durch, dreh mich durch die Mangel"

package/dist/agent-src/commands/challenge-me/with-docs.md

@@ -7,6 +7,7 @@ visibility: internal
 cluster: challenge-me
 sub: with-docs
 description: "Doc-aware /challenge-me — 95%-confidence interview with session glossary vs CONTEXT.md, load-bearing claim-vs-code verification, optional CONTEXT.md patch + ADR candidates in the pitch."
+argument-hint: "[--until=N] [--keep-going] [seed]"
 suggestion:
   eligible: true
   trigger_description: "challenge me against the docs, grill me with our context, grill me against the docs, grill me against CONTEXT.md, grill me with the project context, frag mich durch und prüf gegen CONTEXT.md, challenge plan with domain docs"

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

@@ -5,6 +5,7 @@ pack: product-reasoning
 tier: 2
 visibility: internal
 description: Challenge-me orchestrator — routes to vision, with-docs
+argument-hint: "[vision|with-docs] [flags] [seed]"
 cluster: challenge-me
 type: orchestrator
 suggestion:
@@ -55,15 +56,36 @@ enough to emit a copyable Markdown pitch.
    > 2. with-docs — same flow, but checks the seed against `CONTEXT.md` /
    >    ADRs and emits an optional doc patch in the pitch
 
+## In-interview triggers (both sub-commands)
+
+While inside `vision` or `with-docs`, the user can end or branch the
+interview at any turn by typing one of three triggers. Full syntax,
+match rules, and routing live in
+[`vision.md` § Triggers — strict matching](challenge-me/vision.md);
+`with-docs` inherits verbatim.
+
+| Trigger | Action |
+|---|---|
+| `!pitch` (and aliases) | Emit the pitch, hand back. |
+| `!roadmap` / `!roadmap:create` (and aliases) | Emit the pitch, then auto-route to [`/roadmap:create`](roadmap/create.md) with the pitch as seed. Routing is opt-in by the trigger, not silent. |
+| `!ai` / `!ai-council` / `!council` (and aliases) | Invoke [`/council default`](council/default.md) on the open question(s); cost gate **auto-accepted** by the trigger; council answers integrated, interview resumes. |
+
 ## Rules
 
 - **Do NOT chain sub-commands.** One `/challenge-me <sub>` per turn.
 - If the user invokes `/challenge-me` with no argument, **show the menu**
   — do not guess which sub-command they meant.
-- **No file writes from either sub-command.** Both variants are
-  conversational; the pitch is the only artefact, and it is copyable
-  Markdown the user pastes elsewhere. `with-docs` emits its `CONTEXT.md`
-  patch and ADR candidates inside the same pitch block — agent does not
-  apply them itself.
+- **No file writes from /challenge-me itself.** Both variants are
+  conversational; the pitch is the only artefact `/challenge-me` produces,
+  and it is copyable Markdown the user pastes elsewhere. `with-docs`
+  emits its `CONTEXT.md` patch and ADR candidates inside the same pitch
+  block — `/challenge-me` does not apply them itself. The `!roadmap`
+  trigger routes to `/roadmap:create`, which then writes under its own
+  contract (with its own user confirmation in its Step 6); the file
+  write happens there, not here.
+- **Council cost gate is auto-accepted under `!ai`** — typing the
+  trigger is the consent. Sub-commands do not surface a second
+  confirmation, even under `personal.autonomy: auto`.
 - **Mirror the user's language** — sub-commands inherit the
-  `language-and-tone` Iron Law for question blocks and pitch.
+  `language-and-tone` Iron Law for question blocks and pitch. All
+  trigger syntax stays literal in any language.

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: chat-history
 disable-model-invocation: true
+argument-hint: "[import]"
 pack: memory
 tier: 2
 visibility: internal

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

@@ -5,6 +5,7 @@ pack: meta
 tier: 2
 visibility: internal
 description: "Check the open .md file (or a passed path) for German outside DE:/EN: anchor blocks — umlauts, function words, untranslated quotes. Reports and offers fixes."
+argument-hint: "[path...]"
 suggestion:
   eligible: false
   rationale: "Package-internal — only the event4u/agent-config repo runs this."

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: git-commit
 disable-model-invocation: true
+argument-hint: "[in-chunks] [args]"
 pack: git
 intent: "Stage and commit changes in logical chunks with a Conventional Commits message"
 routes_to: [git-workflow, conventional-commits-writing]

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

@@ -8,6 +8,7 @@ cluster: context
 sub: create
 skills: [agent-docs-writing]
 description: Analyze a codebase area and create a structured context document
+argument-hint: "[topic]"
 suggestion:
   eligible: true
   trigger_description: "document this part of the codebase, create a context doc for X"
@@ -86,9 +87,9 @@ Based on the type, analyze the relevant code area:
 - Identify all models and tables involved
 
 **Service context:**
-- Read the service class and its deps
+- Read the service class and its dependencies
 - Trace call chain (who calls it, what it calls)
-- Identify configuration and env deps
+- Identify configuration and env dependencies
 
 **Integration context:**
 - Find API client classes, HTTP calls

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

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

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

@@ -8,6 +8,7 @@ replaces: [set-cost-profile]
 sub: profile
 cluster: cost
 description: Change the rule_loading_tier in .agent-settings.yml — shows each profile's meaning and applies the selection
+argument-hint: "[minimal|balanced|full|custom]"
 skills: [file-editor]
 suggestion:
   eligible: false

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: cost
 disable-model-invocation: true
+argument-hint: "[report|profile] [args]"
 pack: meta
 intent: "Cost dispatcher — session cost report or rule-loading cost profile"
 routes_to: [cost-report, cost-profile]
@@ -34,7 +35,7 @@ and configuration.
 | `/cost profile` | `commands/cost/profile.md` | Change the `rule_loading_tier` in `.agent-settings.yml` — shows each profile's meaning, applies the selection |
 
 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/council/analysis.md

@@ -8,6 +8,7 @@ cluster: council
 sub: analysis
 skills: [ai-council]
 description: Run the council on a local analysis output (project-analyze, audit script, codebase scan) — critiques the analysis itself for dedup, evidence quality, and roadmap-readiness.
+argument-hint: "[path] [question]"
 suggestion:
   eligible: true
   trigger_description: "council on this analysis, critique the project-analyze output, second opinion on the audit findings, turn analysis into roadmap"

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

@@ -8,6 +8,7 @@ cluster: council
 sub: debate
 skills: [ai-council]
 description: Multi-round council debate with progressive cost disclosure — each member produces a position, then rebuts the strongest opposing position in subsequent rounds. User confirms spend between rounds.
+argument-hint: "[topic | path] [--rounds N] [--auto-continue]"
 suggestion:
   eligible: true
   trigger_description: "council debate on X, multi-round rebuttal, escalate council to debate mode, push the council to argue not synthesize"

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

@@ -8,6 +8,7 @@ cluster: council
 sub: default
 skills: [ai-council]
 description: Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <input>` for prompt/roadmap/diff/files; the cluster shows a menu when invoked bare.
+argument-hint: "[prompt:\"…\" | roadmap:<path> | diff:<a>..<b> | files:<paths>] [rounds:N] [depth:deep]"
 suggestion:
   eligible: false
   rationale: "Default lens — invoked via /council dispatcher; no direct trigger."
@@ -93,19 +94,19 @@ NOT in `.agent-settings.yml`, NOT in the project tree. The CLI
 (`scripts/ai_council/config.ts:resolve_config_path`, per
 [ADR-104](../../../docs/decisions/ADR-104-ai-council-config-global-only.md),
 superseding [ADR-093](../../../docs/decisions/ADR-093-ai-council-config-user-global.md))
-resolves it — first hit wins:
+resolves it in this order — first hit wins:
 
 1. `$AI_COUNCIL_CONFIG` — explicit absolute path (tests / power users),
-   honoured even when absent. Explicit path, never a project search.
-2. User-global `~/.event4u/agent-config/settings/.ai-council.yml` — the one
-   and only home; this single global config serves every project.
+   honoured even when absent. An explicit path, never a project search.
+2. User-global `~/.event4u/agent-config/settings/.ai-council.yml` — the
+   one and only home; this single global config serves every project.
 
-No project-local lookup. The council never reads
-`<project_root>/agents/settings/.ai-council.yml`, `scripts/ai_council`, or any
-project file. Keys are **top-level** (`enabled`, `defaults:`, `members:`). No
-`ai_council:` parent block; the legacy `ai_council.*` block under
-`.agent-settings.yml` was removed in ADR-093 — never read or recommend that
-path for council config.
+There is **no project-local lookup.** The council never reads
+`<project_root>/agents/settings/.ai-council.yml`, `scripts/ai_council`, or
+any project file. Keys are **top-level** in the global file (`enabled`,
+`defaults:`, `members:`). There is no `ai_council:` parent block, and the
+legacy `ai_council.*` block under `.agent-settings.yml` was removed in
+ADR-093 — never read or recommend that path for council config.
 
 ```
 THE COUNCIL CONFIG IS ALWAYS GLOBAL. NEVER SEARCH THE PROJECT FOR IT.
@@ -119,18 +120,18 @@ is authoritative: run `council:estimate` (Step 3) and read its exit code
 consumer repos, fresh worktrees, any CWD — with zero per-project setup.
 ```
 
-CLI is the single source of truth for the configured-check — do not hand-parse
-the YAML, and never eyeball the project tree, to second-guess it. Map its outcomes (Step 4 exit codes + the
-**CLI exits 2** cases below):
+The CLI is the single source of truth for the configured-check — do not
+hand-parse the YAML, and never eyeball the project tree, to second-guess it. Map its outcomes (Step 4 exit
+codes, plus the **CLI exits 2** cases below):
 
-- `enabled: false` (top-level in resolved `.ai-council.yml`) → CLI exits 2 with
-  `ai_council.enabled is false`. State that, offer to flip it on. Do not flip
-  it autonomously.
-- No member has `enabled: true` (under top-level `members:`) → list install
-  commands (`./agent-config keys:install-anthropic`,
+- `enabled: false` (top-level in the resolved `.ai-council.yml`) → CLI exits 2
+  with `ai_council.enabled is false`. State that and offer to flip it on. Do
+  not flip it autonomously.
+- No member has `enabled: true` (under top-level `members:`) → list the
+  install commands (`./agent-config keys:install-anthropic`,
   `./agent-config keys:install-openai`) and stop.
-- A member is enabled but its `*.key` file is missing or wrong-mode → tell the
-  user which key to install. Do not fall back to env vars. Ever.
+- A member is enabled but its `*.key` file is missing or has the wrong mode
+  → tell the user which key to install. Do not fall back to env vars. Ever.
 
 Load the price table via `scripts.ai_council.pricing.load_prices()`
 (auto-bootstraps `agents/runtime/.agent-prices.md` from defaults if missing). Run

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

@@ -8,6 +8,7 @@ cluster: council
 sub: design
 skills: [ai-council]
 description: Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment.
+argument-hint: "[path]"
 suggestion:
   eligible: true
   trigger_description: "council on this design, second opinion on the ADR, external review of architecture proposal"

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

@@ -8,6 +8,7 @@ cluster: council
 sub: optimize
 skills: [ai-council]
 description: Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output — for ranked, evidence-based suggestions instead of generic advice.
+argument-hint: "[target]"
 suggestion:
   eligible: true
   trigger_description: "council on this perf hot path, second opinion on this optimization, external review of /optimize output"

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

@@ -8,6 +8,7 @@ cluster: council
 sub: pr
 skills: [ai-council]
 description: Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-only by default; comment posting is opt-in.
+argument-hint: "[pr-number | url]"
 suggestion:
   eligible: true
   trigger_description: "council on PR #N, external review of pull request, second opinion on a PR"

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: council
 disable-model-invocation: true
+argument-hint: "[default|pr|design|optimize|analysis|debate] [args]"
 pack: product-reasoning
 intent: "Poll external AIs for a neutral second opinion (pr/design/optimize/analysis lenses)"
 routes_to: [council-default, council-pr, council-design, council-analysis]

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

@@ -9,6 +9,7 @@ tier: 1
 visibility: advanced
 skills: [estimate-ticket]
 description: Estimate a Jira/Linear ticket before sprint planning — size + risk + split recommendation + uncertainty, sibling to /refine-ticket, ends with a close-prompt
+argument-hint: "[ticket-key | url | text] [--personas=<list>] [--scale=<map>]"
 suggestion:
   eligible: true
   trigger_description: "how big is this ticket, estimate PROJ-123, should we split this"

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

@@ -0,0 +1,88 @@
+---
+model_tier: inherit
+name: explain-run
+pack: meta
+tier: 2
+visibility: internal
+description: "Read-only 'why did that happen' run report — resolved rule set, rules fired, artefact engagement, subagent dispatches, hook/loop/freshness state — even when the user just says 'explain the last run'."
+argument-hint: "[--task <id>] [--since <ref>]"
+skills: [agent-docs-writing]
+suggestion:
+  eligible: false
+  rationale: "Package-internal maintainer diagnostic — only the event4u/agent-config repo runs this."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# explain-run
+
+Thin runner for the read-only explainability engine `explain_run`
+(`src/scripts/explain_run.ts`). Renders one Markdown
+report answering **"why did the agent do that this run?"** entirely from
+artefacts other parts of the suite already write — no new state, no capture,
+no daemon.
+
+The report covers: the resolved rule set (kernel vs trigger-routed, from
+`dist/router.json`), rules the audit log actually observed firing, artefact
+engagement (consulted vs applied), subagent dispatches (mode / tiers / token
+deltas), a hook / loop / freshness state snapshot, and a parked list of
+"why" questions this v0 cannot answer yet (surfaced, never silently omitted).
+
+## Instructions
+
+### 1. Resolve the window
+
+Both arguments are optional and narrow the report:
+
+- `--task <id>` — restrict to one task id seen in the audit log.
+- `--since <ref>` — an ISO-8601 timestamp / date cutoff (e.g. `2026-07-01`).
+
+With neither, the engine reports over all available artefacts. Pass through
+exactly what the user gave — do not invent a task id or a date.
+
+### 2. Run the engine
+
+```bash
+./scripts-run src/scripts/explain_run [--task <id>] [--since <ISO-8601>]
+```
+
+Exit codes:
+
+- `0` → report rendered to stdout; continue to step 3.
+- `2` → bad argument (unknown flag or unparsable `--since`); surface stderr
+  and stop.
+
+The engine prints an honest `no data — <source> absent or empty` for any
+section whose source file is missing — that is expected output, not an error.
+
+### 3. Surface the report
+
+Show the engine's Markdown output. Do not re-summarize or re-order it — the
+report already opens with a plain-language `## Summary`. If the user wants the
+report written to a file, add `--output <path>` and confirm the write.
+
+## Rules
+
+- **Read-only** — this command only reads on-disk artefacts. It never edits,
+  captures, or writes state (aside from an explicit `--output` file).
+- **Do NOT commit or push** — the working tree is left to the user.
+- **Never edit generated trees** — per [`source-of-truth`](../rules/source-of-truth.md),
+  the engine lives in `src/scripts/`; never hand-edit `dist/agent-src/` or any
+  tool projection.
+- **Honest nulls, not invented rows** — the engine's `no data` lines are
+  correct output; do not fabricate rule firings or dispatches to fill them.
+
+## When NOT to use
+
+- To *change* behaviour — this only explains it. Rule / routing edits go
+  through the normal source-of-truth flow.
+- Kill criterion: the engine self-documents a delete-if-unused-after-3-releases
+  criterion; if this command sees zero use, retire it with the engine.
+
+## See also
+
+- `explain_run` (`src/scripts/explain_run.ts`) — the read-only engine this wraps.
+- `/agent-status` — live session snapshot (this is the retrospective, artefact-sourced view).
+- [`source-of-truth`](../rules/source-of-truth.md) — edit `src/`, never generated trees.

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: feature
 sub: dev
 description: Full 7-phase feature development workflow for complex features.
+argument-hint: "[description]"
 skills: [laravel, php-coder]
 suggestion:
   eligible: true

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

@@ -8,6 +8,7 @@ cluster: feature
 sub: explore
 skills: [laravel]
 description: Brainstorm and explore a feature idea before committing to a full plan
+argument-hint: "[idea]"
 suggestion:
   eligible: true
   trigger_description: "brainstorm this idea, explore this feature concept"

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

@@ -8,6 +8,7 @@ cluster: feature
 sub: plan
 skills: [feature-planning]
 description: Interactively plan a feature — research, discuss, and create a structured feature document
+argument-hint: "[description]"
 suggestion:
   eligible: true
   trigger_description: "plan this feature, create a feature spec for X"

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

@@ -8,6 +8,7 @@ cluster: feature
 sub: refactor
 skills: [laravel, php-coder]
 description: Refine and update an existing feature plan through interactive discussion
+argument-hint: "[feature-name]"
 suggestion:
   eligible: true
   trigger_description: "update the feature plan, refine the feature spec"

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

@@ -8,6 +8,7 @@ cluster: feature
 sub: roadmap
 skills: [agent-docs-writing]
 description: Generate implementation roadmap(s) from a feature plan and link them
+argument-hint: "[feature-name]"
 suggestion:
   eligible: true
   trigger_description: "turn this feature into a roadmap, generate the implementation roadmap"

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: feature
 disable-model-invocation: true
+argument-hint: "[explore|plan|refactor|roadmap|dev] [args]"
 pack: engineering-base
 intent: "Feature-workflow dispatcher — explore, plan, refactor, roadmap, dev"
 routes_to: [feature-explore, feature-plan, feature-refactor, feature-roadmap, feature-dev]
@@ -39,7 +40,7 @@ commands with a single entry point + sub-command dispatch.
 ## Workflow ordering
 
 Typical sequence: `explore` → `plan` → `roadmap` → `dev` (or per-step
-impl). Use `refactor` whenever an existing plan needs an update.
+implementation). Use `refactor` whenever an existing plan needs an update.
 
 ## Dispatch
 

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

@@ -8,6 +8,7 @@ cluster: fix
 sub: pr-comments
 skills: [php-coder, quality-tools]
 description: Fix, commit+push, reply to, then resolve all open review comments (bots + human reviewers) on a GitHub PR
+argument-hint: "[pr-url]"
 suggestion:
   eligible: true
   trigger_description: "fix all PR review comments, resolve the review feedback"
@@ -194,6 +195,24 @@ Example: `🤖 Good catch, fixed.`
 
 If `false` or `.agent-settings.yml` doesn't exist, do NOT add the prefix.
 
+## Dedup + re-review scoping — before posting anything
+
+Two guards run before any reply/comment is posted:
+
+1. **Dedup against existing comments (fuzzy, not just id).** Fetch **all**
+   existing PR comments paginated (`per_page: 100`, follow `Link` headers).
+   Beyond the exact comment-id + reply-marker check, suppress a would-be new
+   comment when it **matches an existing one** on: same file **and** within
+   **±3 lines** **and** overlapping title keywords. Log every suppressed item
+   ("suppressed: <file>:<line> — already raised by @<login> in #<id>") so the
+   suppression is auditable — never silently drop. This stops the bot from
+   re-raising a point a human reviewer already made three lines away.
+2. **Re-review scoping on reply rounds.** A reply round scopes to the
+   **changed lines** of the push it responds to; never raise **new** issues in
+   code the round did not touch (mirrors the `code-review` re-review-scoping
+   rule). A pre-existing issue you notice in untouched code is noted to the
+   user, not posted as a fresh blocking comment on someone else's PR.
+
 ## Replying via GitHub API
 
 Read `github.pr_reply_method` from `.agent-settings.yml` to determine the correct endpoint.

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: fix
 disable-model-invocation: true
+argument-hint: "[ci|refs|portability|seeder|pr-comments|comments|quality] [args]"
 pack: engineering-base
 intent: "Fix-workflow dispatcher — ci, pr-comments, refs, seeder, portability, comments, quality"
 routes_to: [fix-ci, fix-pr-comments, fix-refs, fix-seeder, fix-portability, fix-comments, fix-quality]
@@ -40,7 +41,7 @@ with a single entry point + sub-command dispatch.
 | `/fix quality` | `commands/fix/quality.md` | Run the quality pipeline (type-checker / linter / formatter, PHP and/or JS/TS) and fix every error — auto-detects language from changed files |
 
 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).
 
 ## Non-interactive & auto-detection
 

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

@@ -8,6 +8,7 @@ cluster: ghostwriter
 sub: delete
 skills: [ghostwriter]
 description: Hard-delete a ghostwriter profile at agents/reference/ghostwriter/<slug>.md after a two-step confirmation. No backup, no soft delete — the file is gone after acceptance.
+argument-hint: "[slug]"
 suggestion:
   eligible: true
   trigger_description: "delete ghostwriter profile, remove public-figure voice, drop ghostwriter, retire captured profile"

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: ghostwriter
 sub: fetch
 description: Build or refresh a public-figure voice profile under agents/reference/ghostwriter/ from a URL or bare name; runs the public-figure attestation gate; delegates web-fetch/web-search to host.
+argument-hint: "<url | name> [--force-refresh]"
 suggestion:
   eligible: true
   trigger_description: "fetch public figure writing voice, capture LinkedIn / blog / Substack style, build ghostwriter profile from name, refresh stale profile"

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

@@ -8,6 +8,7 @@ cluster: ghostwriter
 sub: show
 skills: [ghostwriter]
 description: Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source URLs. Read-only.
+argument-hint: "[slug | index]"
 suggestion:
   eligible: true
   trigger_description: "show ghostwriter profile, inspect public-figure voice, view ghostwriter details, what does this profile contain"