@event4u/agent-config 8.13.0 → 9.1.0

package/dist/agent-src/commands/pr/create/description-only.md

@@ -9,6 +9,7 @@ cluster: git-pr-create
 sub: description-only
 skills: [git-workflow]
 description: Generate a PR description as a copyable markdown block — used standalone or by create-pr
+argument-hint: "[pr-url | branch]"
 suggestion:
   eligible: true
   trigger_description: "write a PR description, draft the PR text"
@@ -94,34 +95,164 @@ That's 6 round-trips for what should be 2.
 
 ### 4. Build the PR body
 
+#### 4.0 Resolve the detail level
+
+Read `commands.create_pr.detail_level` from `.agent-settings.yml` (default
+`min` when unset). This tier governs **only the explanatory depth of the
+Description section** — never which template sections exist, and never
+whether a critical callout appears (see 4.1 critical-info-always).
+
+| Tier | Description section content |
+|---|---|
+| `min` (default) | Title-level summary in 2-3 sentences: *what* changed, *why*, and the user/system impact. No per-file walk, no restating commit subjects, no "how to test". |
+| `med` | `min` + grouped logical changes as 3-5 bullets (by concern, not by file) + a one-line tests note (added / none / coverage). |
+| `max` | `med` + how-to-test steps + edge cases / trade-offs + one "reviewer guidance" line (what to focus on). ≈ the legacy output. |
+
+`min` is the default because this is a token-cost optimization: a shorter
+description costs fewer output tokens on every PR. Keep `min` genuinely
+minimal — but never at the expense of the critical-info block below.
+
+#### 4.1 Critical-info-always — tier-independent MUST
+
+```
+CRITICAL INFORMATION APPEARS AT EVERY TIER, INCLUDING min.
+THE TIER GOVERNS EXPLANATORY DEPTH, NEVER WHETHER A CRITICAL CALLOUT APPEARS.
+DROPPING A BREAKING-CHANGE / MIGRATION / SECURITY / ROLLBACK CALLOUT AT min
+IS A P0 DEFECT, NOT A TOKEN SAVING.
+```
+
+If the diff shows any of the following, a one-line callout for it is included
+in the Description **regardless of `detail_level`** (grounded in the diff, not
+guessed):
+
+- **Breaking change** — API contract change (new/removed/renamed field, changed
+  endpoint or response shape), CLI-arg change, changed env var, or a renamed
+  route the frontend depends on. Prefix `⚠️ Breaking:`.
+- **Migration required** — DB migration, config migration, or a deployment step.
+  Prefix `Migration:`.
+- **Security implication** — new permission/scope, auth change, or data-exposure
+  surface. Prefix `🔒 Security:`.
+- **Non-trivial rollback** — when reverting is not a plain `git revert`. Prefix
+  `Rollback:`.
+
+None present → omit the block entirely (do not emit empty "No breaking
+changes" filler at `min`).
+
+#### 4.2 Fill the template sections
+
 **ALWAYS** use the PR template (`.github/pull_request_template.md`). Fill in its sections:
 
 - **Jira badge**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Description**: Summarize the changes in 2-5 sentences. Explain *what* changed and *why*.
-  Use the Jira ticket description and commit messages as input.
+- **Description**: Write it to the resolved tier (4.0) with the critical-info
+  block (4.1) always present. Use the Jira ticket description + commit messages
+  as input.
 - **Type of change**: Check the appropriate checkbox(es) based on the changes.
 - **Checklist**: Leave as-is (the developer fills this in).
 - **Links**: Replace `{TICKET-NUMBER}` with the actual ticket ID.
-- **Screenshots**: Leave as `...` unless the user provides screenshots.
+- **Screenshots**: Handled by Step 4.4 (default: leave the placeholder / `...`).
 
-If no PR template exists, use this structure:
+If no PR template exists, use this structure — including only the sections the
+tier calls for (at `min`, the `## Changes` bullets collapse to the 2-3 sentence
+summary and `## How to test` is omitted):
 
 ```markdown
 ## Jira
 [{TICKET-ID}]({JIRA_BASE_URL}/browse/{TICKET-ID})
 
-## Changes
-- Bullet list of what was changed and why
+## Description
+- 2-3 sentence what/why/impact (min) — grouped bullets (med/max)
+- Critical-info callouts (any tier, only if present)
 
 ### Migrations
 - List new/changed migrations (if any)
 
 ### Tests
-- List new/changed tests (if any)
+- List new/changed tests (med/max)
 
 ## How to test
-- Steps to verify the changes
+- Steps to verify the changes (max)
+```
+
+#### 4.3 API response examples (evidence-grounded)
+
+Read `commands.create_pr.api_examples` (default `true`). When `true` **and**
+the diff touches an API endpoint, add a fenced request/response example under
+the Description.
+
+**Detect an API-endpoint change** (fail-open — no false enrichment when
+ambiguous): a changed file matches `commands.create_pr.api_paths` (if set), or
+the light heuristic — a route file (`routes/`, `**/api/**`, `*Controller*`,
+resource/serializer classes) whose diff adds or changes an endpoint or its
+request/response shape. No confident match → skip silently.
+
+**Ground the example in a real source — never invent one:**
+
+```
+NEVER FABRICATE A JSON EXAMPLE. AN INVENTED CONTRACT MISLEADS REVIEWERS
+AND IS WORSE THAN NONE. EMIT A JSON BLOCK ONLY FROM A REAL SOURCE.
+```
+
+Grounding sources, in priority order: the response DTO / API-resource /
+serializer class in the diff · an OpenAPI/JSON-schema in the repo · a test
+fixture or assertion exercising the endpoint · the actual output of a probe you
+ran this session (`curl` / test client). If **none** exists, emit a one-line
+pointer instead — `API contract changed — see \`<file>\`` — never a guessed
+example. This is [`senior-engineering-discipline`](../rules/senior-engineering-discipline.md)
+(never invent an API) applied to the description surface.
+
+Format when grounded:
+
+~~~markdown
+### API example (`POST /api/...`)
+Request:
+```json
+{ ...grounded... }
+```
+Response `201`:
+```json
+{ ...grounded... }
 ```
+~~~
+
+`api_examples: false` → skip this step entirely.
+
+#### 4.4 Screenshots for frontend changes (capability-gated)
+
+Read `commands.create_pr.screenshots` (default `false`). `false` → skip this
+step entirely; leave the template Screenshots placeholder as-is.
+
+When `true`, this is a **capability-gated contract, never a runtime
+orchestrator** — the package ships instructions, the host provides the tools:
+
+1. **Frontend-change gate.** Only proceed if the diff touches a frontend
+   surface — a changed file matches `commands.create_pr.ui_paths` (if set), or
+   the light heuristic (`.vue` / `.tsx` / `.jsx` / `.blade.php` / `.svelte`,
+   component/view/page/template dirs, CSS/Tailwind). No match → skip silently.
+2. **Capability gate — explicit, never silent.** Screenshots need host
+   browser/preview tooling (a Playwright/browser MCP **and** a reachable dev-server
+   or preview URL). There is no capability flag to read, so probe cheaply. If the
+   tooling or a running preview is **absent**:
+   - Leave the template Screenshots placeholder untouched, **and**
+   - Emit ONE line in the chat reply: `Screenshots requested (screenshots: true)
+     but no browser/preview tooling was reachable — skipped.`
+   - **Never** fail, block, or delay PR creation over this.
+3. **Capture (when capable).** Capture the current (head) state of each changed
+   surface. Before/after (base vs head) with changed-region highlighting is
+   **best-effort only** — a base checkout mid-PR is fragile and expensive;
+   attempt it only if cheap and safe, otherwise after-only. One screenshot per
+   changed surface, each with a one-line caption.
+4. **Embedding — honest limits.** The `github-api pulls` write path cannot
+   upload image bytes and GitHub markdown does not render `data:` URIs, so an
+   agent cannot inline captured bytes into the body via the API. Use, in order:
+   (a) a host image-upload capability if one exists (embed the returned URL);
+   (b) otherwise save the screenshots to a local path, reference them in the
+   Screenshots section, and tell the user to drag them into the PR in the
+   GitHub UI. **Never claim an embed that did not happen**
+   ([`direct-answers`](../rules/direct-answers.md) Iron Law 2).
+
+Limitations (state them so expectations are set): default off; depends on host
+browser tooling + a running preview; before/after + highlighting is best-effort;
+byte-embedding into the PR body is not possible via the API.
 
 ### 5. Present as copyable block
 

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: git-pr-create
 disable-model-invocation: true
+argument-hint: "[description-only] [:draft|:ready|:final]"
 pack: git
 intent: "Open a pull request with a generated description and stripped attribution footers"
 routes_to: [git-workflow]
@@ -86,28 +87,29 @@ improvise the base or silently proceed when behind **and** overlapping. The
 **On merge conflict: regenerate, don't abort.** Most conflicts on this class of
 branch are in **generated files** — the roadmap dashboard
 (`agents/roadmaps-progress.md`), `docs/proof.md`, condensation hashes, tool
-projections. Resolve **by regenerating from the merged sources**, never by
-hand-picking hunks:
+projections. Those are resolved **by regenerating from the merged sources**,
+never by hand-picking hunks:
 
-1. `./agent-config roadmap:progress` → dashboard.
-2. `./scripts-run src/scripts/build_proof` → `docs/proof.md`.
-3. `bash src/scripts/condense.sh --check` (re-`--mark-done` dependents on a
-   hash conflict) → condensation state.
-4. Stage regenerated files, complete the merge, re-run touched verification
-   before pushing.
+1. `./agent-config roadmap:progress` → resolves the dashboard.
+2. `./scripts-run src/scripts/build_proof` → resolves `docs/proof.md`.
+3. `bash src/scripts/condense.sh --check` (and re-`--mark-done` dependents on
+   a hash conflict) → resolves condensation state.
+4. Stage the regenerated files, complete the merge, and re-run the touched
+   verification before pushing.
 
-Only a conflict in **hand-authored** content is surfaced to the user; a
-generated-file conflict never is.
+Only a conflict in **hand-authored** content (source code, prose you or the
+other PR wrote) is surfaced to the user; a generated-file conflict never is.
 
 ### 1b-ii. Update freshness — MANDATORY on EVERY later push to an open PR
 
-The gate is not creation-only. **Every subsequent push** to a branch with an
-open PR (CI fix, review response, follow-up commit) re-runs the sequence first:
-`git fetch origin {target-base}` → behind-check → merge `origin/{target-base}`
-in (regenerating on conflict as above) → verify → push. A PR that sits open
-while its base advances goes stale silently; keeping the base merged at every
-touch keeps it `mergeStateStatus: CLEAN`. Behind-check `0` → the step costs one
-fetch and nothing else.
+The gate above is not creation-only. **Every subsequent push** to a branch with
+an open PR (a CI fix, a review response, a follow-up commit) re-runs the same
+sequence first: `git fetch origin {target-base}` → behind-check → merge
+`origin/{target-base}` in (regenerating on conflict as above) → verify → push.
+A PR that sits open while its base advances goes stale silently; keeping the
+base merged **at every touch** means it stays `mergeStateStatus: CLEAN` instead
+of accumulating conflicts for the moment the user wants to merge. If the
+behind-check shows `0`, the step costs one fetch and nothing else.
 
 ### 1c. PR-gate — archive completed roadmaps (MANDATORY)
 
@@ -138,6 +140,12 @@ completion is read from the checkbox counts.
 Run `/create-pr:description-only` Steps 1–4 to generate the PR title and body.
 This handles: Jira ticket extraction, diff analysis, commit messages, **PR template filling**.
 
+The generation honors the cached content flags from step 1 (§4e):
+`detail_level` sets the Description tier (default `min`), `api_examples`
+adds a grounded JSON block for API-endpoint changes, and `screenshots`
+(capability-gated) adds frontend screenshots. Critical-info callouts
+(breaking changes / migrations / security / rollback) appear at every tier.
+
 **CRITICAL**: The PR body MUST use the project's PR template (`.github/pull_request_template.md`).
 Read the template file and fill in its sections. If the template does not exist, use the
 fallback structure defined in `/create-pr:description-only`. NEVER invent a custom body structure.
@@ -314,11 +322,16 @@ an actual Jira API call succeeded** — never announce "skipped".
 
 #### 4e. Settings short-circuit — single read per run
 
-`verbosity.routine_confirmations`, `verbosity.post_action_reports`, and
-`commands.create_pr.preview_description` are read **once** at the top
-of the run and cached for the whole `/create-pr` invocation. Do **not**
-re-read `.agent-settings.yml` in 4b / 4d — both branches resolve from
-the cached values from step 1.
+`verbosity.routine_confirmations`, `verbosity.post_action_reports`,
+`commands.create_pr.preview_description`, `commands.create_pr.detail_level`,
+`commands.create_pr.api_examples`, `commands.create_pr.screenshots`,
+`commands.create_pr.ui_paths`, and `commands.create_pr.api_paths` are read
+**once** at the top of the run and cached for the whole `/create-pr`
+invocation. Do **not** re-read `.agent-settings.yml` in Step 2 or 4b / 4d —
+every branch resolves from the cached values from step 1. The content flags
+(`detail_level`, `api_examples`, `screenshots`, `ui_paths`, `api_paths`) are
+consumed by the `/create-pr:description-only` generation step (Step 2); the
+confirmation/report flags by steps 3–4.
 
 When all three resolve to their silent defaults (`false` / `minimal` /
 `false`), steps 4b + 4d collapse to the single `→ #N opened: <url>` line

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

@@ -5,6 +5,7 @@ pack: fun
 tier: 2
 visibility: internal
 description: "Fill a prediction pool (kicktipp, football/basketball WM): optimize expected points under the rules, enter tips via Playwright. Triggers 'Tippspiel', 'kicktipp', 'predict the pool'."
+argument-hint: "[event] [--pool-url <url>] [--council off|event|match] [--submit] [--fresh|--continue]"
 skills: [prediction-pool-optimizer]
 suggestion:
   eligible: true
@@ -109,12 +110,12 @@ Run [`prediction-pool-optimizer`](../skills/prediction-pool-optimizer/SKILL.md),
 adapted to the event's sport (football / basketball / …): a **de-vigged
 consensus across the 5–10 biggest publicly-viewable bookmakers**
 (sharp-weighted, never one portal) as the primary signal → expected value
-under the Step-3 rules → participant field → tip. **Answer every entry on the
-Step-3 checklist** — scores AND every bonus / award / special question (top
-scorer, "team of the top scorer", group winners, most cards …); none blank.
-Tournament/outright/award probabilities come from real markets **or** the
-skill's executed Poisson helper — **never** a hallucinated "I simulated
-10,000 runs".
+under the Step-3 rules → participant field → tip. **Answer every entry on
+the Step-3 checklist** — scores AND every bonus / award / special question
+(top scorer, "team of the top scorer", group winners, most cards …); none
+left blank. Tournament/outright/award probabilities come from real markets
+**or** the skill's executed Poisson helper — **never** a hallucinated
+"I simulated 10,000 runs".
 
 **Offer the AI-council pass (default off).** Unless `--council` is set,
 ask once:

package/dist/agent-src/commands/prepare-for-review.md

@@ -6,6 +6,7 @@ tier: 2
 visibility: internal
 skills: [git-workflow, quality-tools]
 description: Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to date
+argument-hint: "<pr-number | pr-url | ticket-key>"
 suggestion:
   eligible: true
   trigger_description: "get this branch ready for review, rebase and prep for PR"

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: profile
 sub: activate
 description: Activate a session profile — surface only the named profile/pack closure plus core artefacts, no persistence
+argument-hint: "<profile|pack> [names...]"
 suggestion:
   eligible: true
   trigger_description: "activate the laravel/po/finance profile for this session, switch my surface to X, only show me X commands"

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: profile
 sub: deactivate
 description: Deactivate the session profile — clear the overlay (or drop named packs) so the full surface returns
+argument-hint: "[names...]"
 suggestion:
   eligible: true
   trigger_description: "deactivate the profile, clear my session profile, show everything again, reset the surface"

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

@@ -5,6 +5,7 @@ pack: meta
 tier: 2
 visibility: internal
 description: Session-profile orchestrator — activate / deactivate / show the active packs for this session (recommendation-bias surface filter, no persistence)
+argument-hint: "[activate|deactivate|show] [args]"
 cluster: profile
 type: orchestrator
 suggestion:

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: project
 disable-model-invocation: true
+argument-hint: "[analyze|health]"
 pack: engineering-base
 intent: "Project dispatcher — full analysis or quick health check"
 routes_to: [project-analyze, project-health]
@@ -37,7 +38,7 @@ Top-level orchestrator for the `/project` family — project-wide inspection.
 | `/project health` | `commands/project/health.md` | Quick health check — status of docs, modules, contexts, roadmaps; creates nothing |
 
 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/refine-ticket.md

@@ -9,6 +9,7 @@ tier: 1
 visibility: advanced
 skills: [refine-ticket]
 description: Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates validate-feature-fit and threat-modeling, ends with a close-prompt
+argument-hint: "[ticket-key | url | text] [--personas=<list>] [--user-type=<id>] [--fresh-eyes]"
 suggestion:
   eligible: true
   trigger_description: "refine PROJ-123, tighten the acceptance criteria, is this ticket clear"
@@ -68,6 +69,12 @@ application, synthesis, and close-prompt.
 - `--personas=<list>` — comma-separated override of the Core-6 default
   (e.g. `--personas=developer,senior-engineer,critical-challenger`)
 - `--personas=+qa` — add the QA specialist to the Core-6
+- `--user-type=<id>` — load one user-type from `user-types/<id>.md` and
+  add an end-user simulation lens to the persona stack (e.g.
+  `--user-type=galabau-field-crew`). Composes orthogonally with
+  `--personas=`; persona = methodology lens, user-type = end-user lens.
+  v1 is CLI-only (no skill-level default). Contract:
+  [`docs/contracts/user-type-schema.md`](../docs/contracts/user-type-schema.md).
 - `--fresh-eyes` — reweight toward first-time-reader confusion signals
   (critical-challenger voice gets more lines; less assumed context)
 

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: research
 sub: deep
 description: "Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local research-schema. No Python runtime, no `~/.claude/` paths."
+argument-hint: "[--batch-confirm=each|once|auto]"
 skills: [deep-reading-analyst]
 suggestion:
   eligible: true

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

@@ -2,6 +2,7 @@
 model_tier: high
 name: research
 disable-model-invocation: true
+argument-hint: "[<topic>|deep|report] [args]"
 pack: product-discovery
 tier: 2
 visibility: internal

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

@@ -8,6 +8,7 @@ sub: routing
 cluster: review
 skills: [review-routing, reviewer-awareness]
 description: Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml
+argument-hint: "[base-ref head-ref]"
 suggestion:
   eligible: true
   trigger_description: "who should review this, suggest reviewers for this PR"

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: review
 disable-model-invocation: true
+argument-hint: "[changes|routing]"
 pack: engineering-base
 intent: "Review dispatcher — multi-judge self-review of the current diff, or reviewer routing"
 routes_to: [review-changes, review-routing]
@@ -38,7 +39,7 @@ reviewer selection.
 | `/review routing` | `commands/review/routing.md` | Compute reviewer roles + matched historical bug patterns for the current diff (ownership-map.yml, historical-bug-patterns.yml) |
 
 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/roadmap/ai-council.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: ai-council
 skills: [ai-council, agent-docs-writing, roadmap-management]
 description: Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council default` pinned to `--input-mode roadmap --depth deep`; patches surface as numbered options.
+argument-hint: "[roadmap-name | path]"
 council_depth: deep
 suggestion:
   eligible: true

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

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: materialize
 skills: [emit-tickets]
 description: Materialise a roadmap into a self-contained, importable ticket bundle under agents/tickets/
+argument-hint: "[roadmap-path]"
 suggestion:
   eligible: true
   trigger_description: "turn this roadmap into tickets, materialise the roadmap, mach Tickets aus der Roadmap"

package/dist/agent-src/commands/roadmap/process-full.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: process-full
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step across every phase of a roadmap until the file is fully closed. Largest execution scope of the /roadmap cluster — runs continuously across phase boundaries.
+argument-hint: "[roadmap]"
 suggestion:
   eligible: true
   trigger_description: "process the whole roadmap, finish the roadmap, komplette roadmap abarbeiten"

package/dist/agent-src/commands/roadmap/process-phase.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: process-phase
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process every open step in the next or current phase of a roadmap, then stop. Default execution scope of the /roadmap cluster.
+argument-hint: "[roadmap]"
 suggestion:
   eligible: true
   trigger_description: "process the next phase, finish this phase autonomously, eine phase abarbeiten"

package/dist/agent-src/commands/roadmap/process-step.md

@@ -8,6 +8,7 @@ cluster: roadmap
 sub: process-step
 skills: [agent-docs-writing, ai-council, roadmap-management]
 description: Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /roadmap cluster — one step in, one step out.
+argument-hint: "[roadmap]"
 suggestion:
   eligible: true
   trigger_description: "process the next step, do the next roadmap step, einen schritt abarbeiten"

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: roadmap
 disable-model-invocation: true
+argument-hint: "[create|ai-council|process-step|process-phase|process-full] [args]"
 pack: product-basic
 intent: "Roadmap dispatcher — create, process-step, process-phase, process-full, ai-council"
 routes_to: [roadmap-create, roadmap-process-step, roadmap-process-phase, roadmap-process-full]

package/dist/agent-src/commands/security-audit-config.md

@@ -6,6 +6,7 @@ tier: 2
 visibility: internal
 skills: [judge-security-auditor, threat-modeling, security-audit]
 description: Audit an assembled agent config (CLAUDE.md, .cursor/rules, settings, MCP, hooks, skills) for prompt-injection / supply-chain risk — A–F score per category, mapped to OWASP Agentic Top 10
+argument-hint: "[repo-root]"
 council_depth: deep
 suggestion:
   eligible: true
@@ -35,7 +36,7 @@ suite's own `lint_agent_security` self-audit gate.
 
 (omit `--root` to audit the current repo). The script reuses the Phase-1
 detection library under the false-positive containment convention
-([`security-lint-containment`](../../../docs/guidelines/agent-infra/security-lint-containment.md)),
+([`security-lint-containment`](../../docs/guidelines/agent-infra/security-lint-containment.md)),
 so doc/example files do not tank the score. It scans instruction files
 (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`,
 `.clinerules`, `.windsurfrules`), MCP configs (`.mcp.json`, `.cursor/mcp.json`,

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: skill
 sub: preview
 description: Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command targets — before you run it. Read-only, no execution.
+argument-hint: "<skill-name> [--technical]"
 skills: [file-editor]
 suggestion:
   eligible: true

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

@@ -5,6 +5,7 @@ pack: meta
 tier: 2
 visibility: internal
 description: Single-skill orchestrator — routes to preview. Non-destructive "what will this skill do?" before you run it.
+argument-hint: "[preview] <skill-name>"
 cluster: skill
 type: orchestrator
 suggestion:

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

@@ -7,6 +7,7 @@ visibility: internal
 cluster: skills
 sub: discover
 description: Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-task, recently-adopted, popular-in-role). Local-only; every result carries a why.
+argument-hint: "[role]"
 skills: [file-editor]
 suggestion:
   eligible: true

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

@@ -5,6 +5,7 @@ pack: meta
 tier: 2
 visibility: internal
 description: Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog + role shortlists + optional local analytics.
+argument-hint: "[discover] [role]"
 cluster: skills
 type: orchestrator
 suggestion:

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

@@ -8,6 +8,7 @@ sub: agent-settings
 cluster: sync
 skills: [sync-agent-settings]
 description: Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing
+argument-hint: "[--path <file>] [--profile minimal|balanced|full] [--check]"
 suggestion:
   eligible: false
   rationale: "Settings sync — must be deliberate."

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

@@ -2,6 +2,7 @@
 model_tier: medium
 name: sync
 disable-model-invocation: true
+argument-hint: "[agent-settings|gitignore|gitignore-fix]"
 pack: meta
 intent: "Sync dispatcher — agent settings or the managed .gitignore block"
 routes_to: [sync-agent-settings, sync-gitignore, sync-gitignore-fix]
@@ -34,7 +35,7 @@ managed files in step with the package templates.
 | `/sync gitignore-fix` | `commands/sync/gitignore/fix.md` | Scrub legacy pre-`/agents/` patterns anywhere in the `.gitignore`, then re-sync the canonical entries |
 
 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/team/adversarial.md

@@ -2,7 +2,8 @@
 model_tier: inherit
 name: team-adversarial
 disable-model-invocation: true
-pack: product-reasoning
+argument-hint: "<focus>"
+pack: meta
 tier: 2
 visibility: internal
 skills: [adversarial-review]
@@ -16,7 +17,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - product-reasoning
+  - meta
 ---
 
 # /team adversarial

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

@@ -2,7 +2,8 @@
 model_tier: inherit
 name: team-delegate
 disable-model-invocation: true
-pack: product-reasoning
+argument-hint: "<task>"
+pack: meta
 tier: 2
 visibility: internal
 description: Thin wrapper — hand a task to the second model as a native worker via the official plugin (/codex:rescue). The only write-access wrapper; double-gated behind ai_team.allow_delegate.
@@ -14,7 +15,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - product-reasoning
+  - meta
 ---
 
 # /team delegate

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

@@ -2,7 +2,8 @@
 model_tier: inherit
 name: team-review
 disable-model-invocation: true
-pack: product-reasoning
+argument-hint: "[--background]"
+pack: meta
 tier: 2
 visibility: internal
 description: Thin wrapper — cross-model review of the current diff via the official plugin (/codex:review). Gated on ai_team.enabled; fails closed when the plugin is absent.
@@ -15,7 +16,7 @@ suggestion:
 workspaces:
   - agent-config-maintainer
 packs:
-  - product-reasoning
+  - meta
 ---
 
 # /team review