@event4u/agent-config 5.10.1 → 6.0.0

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

@@ -0,0 +1,155 @@
+---
+model_tier: high
+name: research-deep
+pack: product-discovery
+tier: 2
+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."
+skills: [deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "deep research, populate the research scaffold, fill outline.yaml items"
+  trigger_context: "user has run `/research <topic>` and now wants per-item depth"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /research:deep
+
+Reads the `outline.yaml` produced by [`/research`](../research.md), launches
+batched per-item research, and writes one JSON per item under
+`{output_dir}/`. Each JSON is self-validated against the
+[`research-schema`](../../contexts/contracts/research-schema.md)
+contract before write — **no `validate_json.py` script, no Python
+runtime, no `~/.claude/` paths**.
+
+## Trigger
+
+`/research:deep [--batch-confirm=each|once|auto]`
+
+`--batch-confirm` controls user gating between batches:
+
+- `each` (default) — confirm before every batch.
+- `once` — confirm only the first batch, then run the rest.
+- `auto` — no confirmation, run all batches (only honoured under
+  explicit `/roadmap process-full` autonomy).
+
+## Workflow
+
+### Step 1 — Auto-locate outline
+
+Search `$PROJECT_ROOT/agents/research/*/outline.yaml` (single match) or
+ask via numbered options if multiple `outline.yaml` files exist. Read:
+
+- `topic`, `topic_slug`, `items[]`, `execution.batch_size`,
+  `execution.items_per_agent`, `execution.output_dir` (default
+  `./results` relative to the topic dir).
+
+### Step 2 — Resume check
+
+Scan `{output_dir}/` for `*.json` files; mark items whose
+`{slug(item.name)}.json` exists as **complete**. Slugify by lowercasing,
+replacing whitespace with `_`, and stripping characters outside
+`[a-z0-9_-]`.
+
+### Step 3 — Batch execution
+
+Group remaining items by `batch_size` (each batch holds
+`batch_size × items_per_agent` items at most). For each batch:
+
+1. Show the batch summary: `[N/M] items: a, b, c …`.
+2. Apply the `--batch-confirm` policy (default `each` — wait for the
+   user; `once` after the first; `auto` skips).
+3. For every item in the batch, run the per-item research using the
+   agent's **native web-search** (no `web-search-agent` persona).
+
+#### Per-item prompt template
+
+Variables in `{xxx}` only — **do not modify structure or wording**.
+
+```text
+## Task
+Research {item_related_info}, output structured JSON to {output_path}.
+
+## Field definitions
+Read {fields_path} to get all field definitions.
+
+## Output requirements
+1. Output JSON whose top-level keys map to the categories in
+   `fields.yaml` (or to the `{slug(category)}` form — both are
+   accepted by `/research:report`).
+2. Mark uncertain field values with the literal string `[uncertain]`.
+3. Append an `uncertain` array at the end of the JSON listing all
+   field names whose value contains `[uncertain]` or could not be
+   sourced.
+4. All field values in English.
+
+## Output path
+{output_path}
+
+## Validation (no Python, no host paths)
+Self-validate the JSON against
+`<package>/.agent-src.uncondensed/contexts/contracts/research-schema.md`
+in memory before writing. The well-formedness escape hatch is
+`jq -e '.[]' {output_path}` — agent runs it after write and re-tries
+once on failure. Task is complete only after both checks pass.
+```
+
+#### Variable bindings
+
+| Variable | Source |
+|---|---|
+| `{topic}` | `outline.yaml#/topic` |
+| `{item_related_info}` | the item's full YAML block (`name`, `category`, `description`, etc.) |
+| `{output_dir}` | `outline.yaml#/execution/output_dir` (default `./results`) |
+| `{fields_path}` | `$PROJECT_ROOT/agents/research/{topic_slug}/fields.yaml` |
+| `{output_path}` | `{output_dir}/{slug(item.name)}.json` |
+
+### Step 4 — Wait and monitor
+
+Wait for the current batch to finish (all per-item JSON files written
++ validated). Display per-item status (`✅ done`, `⚠️ uncertain`,
+`❌ failed`) before moving on.
+
+### Step 5 — Summary report
+
+After all batches complete, print:
+
+- Total items · completed · uncertain · failed.
+- Output directory.
+- Pointer to `/research:report` for the next phase.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── outline.yaml
+  ├── fields.yaml
+  └── {output_dir}/
+        ├── {slug(item_a)}.json
+        ├── {slug(item_b)}.json
+        └── …
+```
+
+## Portability notes
+
+- **No Python runtime** — validator dropped at adoption, replaced by
+  the in-memory JSON-Schema check + `jq -e` escape hatch (`jq` is
+  optional; agents skip it gracefully if not installed and report
+  `⚠️ jq missing — well-formedness not verified`).
+- **No `~/.claude/` paths** — every reference is rooted at
+  `$PROJECT_ROOT/agents/research/`.
+- **No `web-search-agent` persona** — uses the host agent's native
+  web-search tool.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research-deep/SKILL.md` · MIT License.
+Refactored:
+dropped Pydantic validator + `~/.claude/` paths + `web-search-agent`
+persona, added `--batch-confirm` flag, kept the per-item prompt
+structure verbatim except for the validation block.

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

@@ -0,0 +1,140 @@
+---
+model_tier: high
+name: research-report
+pack: product-discovery
+tier: 2
+cluster: research
+sub: report
+description: "Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an optional `jq` template for deterministic regeneration. No Python runtime."
+skills: [deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "summarise research results, build research report, render outline.yaml results"
+  trigger_context: "user has finished `/research:deep` and wants a single markdown summary"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /research:report
+
+Reads the per-item JSON files emitted by
+[`/research:deep`](deep.md), asks the user which fields to surface in
+the table of contents, then writes `{topic_slug}/report.md` directly.
+Optionally emits `{topic_slug}/report-template.jq` so the same report
+can be regenerated deterministically without re-invoking the agent.
+
+## Trigger
+
+`/research:report`
+
+## Workflow
+
+### Step 1 — Locate results
+
+Find `$PROJECT_ROOT/agents/research/*/outline.yaml` (single match) or
+ask via numbered options. Read `topic`, `topic_slug`, and
+`execution.output_dir`.
+
+### Step 2 — Scan summary-field candidates
+
+Read every `*.json` in `{output_dir}/`. Collect field names whose
+values are short / numeric (e.g. `github_stars`,
+`google_scholar_cites`, `swe_bench_score`, `user_scale`, `valuation`,
+`release_date`). Filter:
+
+- numeric scalars (int / float),
+- short strings (≤ 40 chars), or
+- ISO-8601 dates.
+
+### Step 3 — Ask user (numbered options)
+
+Per [`user-interaction`](../../rules/user-interaction.md) Iron Law,
+offer numbered options for **TOC summary fields** drawn from the
+candidate list. Allow multi-select (e.g., *"1, 3, 5"*) plus *"none"*.
+
+### Step 4 — Render `report.md` directly
+
+The agent itself reads each JSON + `fields.yaml` + the user's TOC
+choices, then writes `{topic_slug}/report.md`. **No `generate_report.py`
+script, no Python runtime.**
+
+#### Required structure
+
+1. **Title** — `# {topic} — Research Report`.
+2. **TOC** — every item, anchor-linked, with the chosen summary fields
+   inline. Example:
+   `1. [GitHub Copilot](#github-copilot) — Stars: 10k · Score: 85%`.
+3. **Detailed sections** — one `## {item.name}` per item, then
+   `### {category}` per category from `fields.yaml`, then field
+   key/value rows.
+
+#### Rendering rules
+
+| Rule | Behaviour |
+|---|---|
+| **JSON shape** | Support flat (`{"name": "…"}`) and nested (`{"basic_info": {"name": "…"}}`) layouts. Lookup order: top-level → category mapping → recursive walk. |
+| **Category mapping** | Maintain a bidirectional alias map between `fields.yaml` category labels and JSON keys (e.g. `"Basic info" ↔ "basic_info"`). Use language-neutral keys, no hard-coded English/Chinese. |
+| **List of dicts** | One row per dict, `key:value` pairs joined with ` \| `. |
+| **Plain list** | Short → comma-joined; long (> 5 items) → bullet list. |
+| **Nested dict** | Recurse; render with `;` between sibling keys or hard-break on long values. |
+| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. |
+| **Extra fields** | JSON keys not declared in `fields.yaml` → group under `### Other info`. Filter `_source_file`, `uncertain`, and category-container keys. |
+| **`uncertain` array** | Render each entry on its own line under `### Uncertain fields`; never condense to a one-liner. |
+| **Skip conditions** | Field value contains `[uncertain]` · field name in `uncertain` · value is `null` / empty string. |
+
+### Step 5 — Optional `jq` template (deterministic regenerate)
+
+Also emit `{topic_slug}/report-template.jq` capturing the user's TOC
+choices + rendering rules as a `jq` program. Document the regenerate
+command in the file's leading comment:
+
+```text
+# Regenerate report.md without re-invoking the agent:
+#   jq -rsf report-template.jq results/*.json > report.md
+# Requires: jq ≥ 1.6. Skip this file if jq is unavailable —
+# `report.md` from step 4 is the canonical artefact.
+```
+
+The template is **best-effort**. Agents that cannot fully express
+the rendering rules in `jq` may emit a stub with a `# TODO` comment
+and a pointer back to step 4. The primary deliverable is `report.md`;
+the `jq` template is a power-user convenience.
+
+### Step 6 — Confirm
+
+Print:
+
+- Path to `report.md`.
+- Whether `report-template.jq` was emitted.
+- Item count · category count · skipped-uncertain count.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── report.md             # primary artefact (agent-rendered)
+  └── report-template.jq    # optional, deterministic regen
+```
+
+## Portability notes
+
+- **No Python runtime** — upstream's `generate_report.py` was a
+  Python conversion script; this port shifts the transformation to
+  the agent (primary) + a `jq` template (optional). `augment-portability`
+  Iron Law upheld.
+- **No `~/.claude/` paths** — every reference is rooted at
+  `$PROJECT_ROOT/agents/research/`.
+- **`jq` is optional** — agents skip the template gracefully and
+  surface `⚠️ jq template not emitted` in the summary if generation
+  fails or the dependency is missing.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research-report/SKILL.md` · MIT License.
+Refactored: dropped the `generate_report.py` Python script (replaced
+with agent-side rendering + optional `jq` template), kept the
+multilingual category mapping + complex-value formatting rules,
+re-anchored every path under `$PROJECT_ROOT/agents/research/`.

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

@@ -0,0 +1,179 @@
+---
+model_tier: high
+name: research
+disable-model-invocation: true
+pack: product-discovery
+tier: 2
+cluster: research
+description: "Preliminary research scaffolder — pick objects, define fields, emit `outline.yaml` + `fields.yaml` for downstream deep research. Use for surveys, benchmarks, tech selection, competitive scans."
+skills: [project-analyzer, deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "research a topic, scan competitors, benchmark X, do a tech-selection survey"
+  trigger_context: "user names a research topic and wants a structured scaffold (objects + fields), not an immediate answer"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /research
+
+Top-level entry point for the `/research` family. Bare `/research <topic>`
+runs the preliminary scaffolder described under `## Default flow`. Sub-commands
+drive the downstream phases (`:deep` populates the scaffold, `:report`
+summarises the results).
+
+Routes thinking-framework support to
+[`deep-reading-analyst`](../skills/deep-reading-analyst/SKILL.md) (SCQA
+for narrative structure, mental-models lens for object selection).
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/research <topic>` (bare) | this file (`## Default flow`) | Pick objects, define fields, emit `outline.yaml` + `fields.yaml` |
+| `/research:deep` | `commands/research/deep.md` | Read scaffold, research each item in batches, write per-item JSON |
+| `/research:report` | `commands/research/report.md` | Summarise per-item JSON into a markdown report (+ optional `jq` template) |
+
+## Dispatch
+
+1. Parse the user's argument: `/research[:<sub>] [args]`.
+2. Bare `/research <topic>` → run the `## Workflow` below verbatim.
+3. `/research:deep` → load `commands/research/deep.md` and follow its
+   `## Workflow` section verbatim.
+4. `/research:report` → load `commands/research/report.md` and follow its
+   `## Workflow` section verbatim.
+5. Unknown sub-command → print the table above and ask which one.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/research[:<sub>]` per turn.
+- If the user invokes `/research` with no argument, **show the menu** —
+  do not guess whether they meant the bare workflow or a sub-command.
+- **Edit `.agent-src.uncondensed/` only.** `dist/agent-src/` and `.augment/`
+  regenerate from source.
+
+## Trigger
+
+`/research <topic>`
+
+## Workflow
+
+### Step 1 — Initial framework from model knowledge
+
+Generate, from the model's existing knowledge, the candidate object list
+and field framework for the topic:
+
+- **Objects / items** — entities, products, methods, datasets to compare.
+- **Field framework** — dimensions to fill per item (basic info, technical
+  features, evidence, etc.).
+
+Output `{step1_output}` and confirm with the user via numbered options
+(per [`user-interaction`](../rules/user-interaction.md) Iron Law):
+
+1. Add or remove items?
+2. Field framework adequate?
+
+### Step 2 — Web-search supplement
+
+Ask one numbered question for the time range (e.g., last 6 months,
+since 2024, unlimited). Use the agent's native web-search tool — do
+**not** spawn a separate `web-search-agent` persona.
+
+Search prompt template (variables in `{xxx}` only — do not modify
+structure):
+
+```text
+Research topic: {topic}
+Current date: {YYYY-MM-DD}
+Time range: {time_range}
+
+Existing framework:
+{step1_output}
+
+Goals:
+1. Verify existing items are not missing important objects.
+2. Supplement items based on missing objects.
+3. Continue searching for {topic}-related items within {time_range}.
+4. Supplement new fields where helpful.
+
+Output (return inline, do not write files):
+
+### Supplementary items
+- item_name: brief explanation (why it should be added)
+
+### Recommended supplementary fields
+- field_name: field description (why this dimension is needed)
+
+### Sources
+- [Source 1](url)
+- [Source 2](url)
+```
+
+### Step 3 — Existing fields merge
+
+Ask via numbered options whether the user has an existing field-definition
+file. If yes, read the file and merge into the framework before Step 4.
+
+### Step 4 — Generate outline (two files)
+
+Merge `{step1_output}`, `{step2_output}`, and any user-provided fields,
+then write two files into `$PROJECT_ROOT/agents/research/{topic_slug}/`:
+
+**`outline.yaml`** (items + execution config):
+
+- `topic`: research topic
+- `items`: research-objects list
+- `execution`: `batch_size`, `items_per_agent`, `output_dir`
+  (defaults: `./results`; confirm with the user via numbered options)
+
+**`fields.yaml`** (field definitions):
+
+- field categories + definitions
+- per field: `name`, `description`, `detail_level`
+  (`brief` → `moderate` → `detailed`)
+- `uncertain`: list reserved for the deep-research phase
+
+YAML structure validation: see
+[`research-schema`](../contexts/contracts/research-schema.md) for the
+project-local JSON-Schema reference (no runtime Python validator; the
+agent reads the schema and self-validates).
+
+### Step 5 — Output + confirm
+
+Create `agents/research/{topic_slug}/` if absent, write both YAML files,
+and present a summary block to the user:
+
+- Topic + slug.
+- Item count + field count.
+- Path to the two files.
+- Next-step pointer: deep-research orchestration is a follow-up port;
+  use the YAML scaffold as input when that lands.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── outline.yaml    # items list + execution config
+  └── fields.yaml     # field definitions
+```
+
+## Out of scope
+
+`/research:add-items` and `/research:add-fields` are **not** ported —
+the existing scaffolder + sub-commands cover the round-trip; the
+upstream incremental-edit commands are too thin to justify their own
+sub-command. Re-run `/research <topic>` and merge by hand if the
+field framework needs a follow-up adjustment.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research/SKILL.md` · MIT License.
+Refactored: dropped `web-search-agent` persona
+(portability), dropped Pydantic validator (replaced with JSON-Schema
+reference), repathed `./` → `$PROJECT_ROOT/agents/research/`. Phase 2
+ported `/research:deep` and `/research:report` as cluster sub-commands.

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

@@ -0,0 +1,213 @@
+---
+model_tier: high
+name: review-changes
+pack: engineering-base
+intent: "Multi-judge review of the current diff — bugs, security, tests, quality, architecture"
+routes_to: [code-review, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens]
+replaces: []
+tier: 1
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, architecture-review-lens, git-workflow]
+description: Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, tests, quality, architecture) and consolidates verdicts
+suggestion:
+  eligible: true
+  trigger_description: "self-review my changes, judge this diff before PR"
+  trigger_context: "uncommitted or staged changes pre-PR"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# review-changes
+
+## Instructions
+
+Review all uncommitted and committed-but-not-pushed changes against
+the default branch (`main`) by dispatching to four specialized judge
+sub-skills and consolidating their verdicts.
+
+### 1. Update the current branch
+
+Before gathering the diff, run [`/prepare-for-review`](prepare-for-review.md)
+to make sure the current branch is up to date with its base chain:
+
+- Detect the current branch with `git rev-parse --abbrev-ref HEAD`.
+- If the branch is `main` → skip this step (nothing to prepare).
+- Otherwise, search for an open GitHub PR whose head is the current
+  branch.
+  - If exactly one open PR is found → invoke `/prepare-for-review`
+    with that PR number. It will update `main`, fetch and merge the
+    full branch chain into the current branch, and leave the current
+    branch checked out.
+  - If no open PR is found → fall back to a minimal local update:
+    `git fetch origin main` and `git merge origin/main --no-edit` on
+    the current branch. Abort on conflict and report.
+  - If multiple PRs are found → ask the user which PR to use before
+    proceeding.
+- If `/prepare-for-review` aborts (merge conflict, network error,
+  etc.) → stop the review here and surface the error. Do **not**
+  continue with stale data.
+
+### 2. Gather the diff
+
+- `git diff origin/main..HEAD --stat` — overview of changed files
+- `git diff origin/main..HEAD` — full committed-but-not-pushed diff
+- `git diff --stat` + `git diff` — unstaged changes on top
+
+If both diffs are empty, **stop** — nothing to review.
+
+### 3. Resolve the judge model
+
+Read `.agent-settings.yml`:
+
+- `subagents.judge_model` → empty = one tier above the session model
+
+Unknown alias → stop. Never silently fall back.
+
+### 4. Dispatch to the five judges
+
+Each judge receives **the same diff plus the task context** (ticket,
+PR body, commit messages) and runs independently. The judges are:
+
+| Sub-skill | Focus |
+|---|---|
+| [`judge-bug-hunter`](../skills/judge-bug-hunter/SKILL.md) | Correctness, null-safety, edge cases, races, error handling |
+| [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md) | AuthZ/AuthN, injection, secrets, unsafe deserialization, SSRF, XSS |
+| [`judge-test-coverage`](../skills/judge-test-coverage/SKILL.md) | Missing assertions, uncovered branches, over-mocking, regression-test gaps |
+| [`judge-code-quality`](../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
+| [`architecture-review-lens`](../skills/architecture-review-lens/SKILL.md) | Layer violations, dependency direction, leaky abstractions, cross-service contract drift |
+
+The five judges weight equally in the consolidated verdict — none
+overrides another.
+
+Pick dispatch mode based on diff size and environment:
+
+- **Sequential** (default, simplest) — run bug-hunter → security-auditor
+  → test-coverage → code-quality → architecture-review-lens, collect
+  each verdict
+- **Parallel** — if `subagents.max_parallel` in `.agent-settings.yml` is
+  ≥ 5 and subagent dispatch is available, run all five concurrently
+  following the `do-in-parallel` pattern in
+  [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md);
+  the five judges operate on the same diff but produce independent
+  reports, so no shared-state risk
+
+Each judge returns its own `Judge / Model / Target / Verdict /
+Issues` block in the format defined by that skill.
+
+### 4b. Optional external council (B3 hook, verbosity-gated)
+
+Read `verbosity.offer_council_in_delivery` from `.agent-settings.yml`
+(default `false`):
+
+- `false` (default): skip the prompt silently. When `ai_council.enabled:
+  true` AND at least one member enabled, emit one line: `→ council
+  skipped (set verbosity.offer_council_in_delivery: true to enable, or
+  run /council diff:<base>..<head> directly)`. Otherwise emit nothing.
+- `true`: when `ai_council.enabled: true` **and** at least one member
+  enabled, ask (in the user's language):
+
+  > 1. Add an external council review alongside the four internal judges? (billable)
+  > 2. Skip — internal judges only
+
+  Also suppress when `personal.autonomy: on` (council is billable).
+
+If picked **1**:
+
+- Run `/council diff:<base>..<head>` in parallel with the four
+  internal judges (or sequentially after them — whichever the
+  dispatch mode picked in step 4 supports).
+- Treat each council member as one extra "judge" in the consolidated
+  report (step 5), but **mark them clearly as external** so the user
+  can weight them differently. Council verdicts are **advisory** —
+  they never block on their own; they augment the internal verdicts.
+- The council's neutrality preamble already strips host-agent
+  identity; do **not** add the internal judges' verdicts to the
+  council prompt (would defeat the Iron Law of Neutrality).
+
+If picked **2** → continue with internal judges only.
+
+### 5. Consolidate
+
+Produce one combined report:
+
+- List each judge's verdict side by side
+- Merge issues into a single severity-sorted table (🔴 → 🟡 → 🟢),
+  tagged with the judge that raised each one
+- Highlight any finding that multiple judges flagged — those are the
+  highest-confidence items
+
+### 6. Decide next steps
+
+- If **any** judge returned `reject` → stop; the approach must change
+  before proceeding
+- If **any** judge returned `revise` → fix 🔴 findings automatically,
+  ask before fixing 🟡 findings, report 🟢 as suggestions
+- If all five returned `apply` → the diff is ready; report and stop
+
+### 7. Quality tools (verbosity-gated)
+
+Per `verbosity.routine_confirmations` (default `false`):
+
+- `false` (default) → emit `→ run /quality-fix to format + lint` as a
+  single follow-up line; do not auto-invoke. User runs explicitly.
+- `true` → ask:
+  ```
+  > 1. Yes — run quality tools (formatter, static analyzer, linters)
+  > 2. No — review done
+  ```
+  If yes, hand off to the project's quality workflow (e.g.
+  `/quality-fix` or the equivalent configured command). The quality and
+  test runners are resolved per-stack via the
+  [`toolchain-resolver`](../contexts/execution/toolchain-resolver.md), so
+  the hand-off adapts to PHP / JS-TS / Python / Go / Rust rather than
+  assuming one stack.
+
+## Backward compatibility
+
+- Invocation is unchanged: `/review-changes` with no arguments still
+  reviews the full uncommitted-plus-committed-not-pushed diff
+- A user who invokes `/review-changes` on a diff that has no test
+  files still gets coverage feedback — `judge-test-coverage` treats
+  "production changed, no test changed" as its primary finding
+- Project-specific syntax checks (e.g. `php -l`, linter pre-pass) are
+  out of scope for the judges and belong in the optional step 7
+  quality tools hand-off
+- The new step 1 (`/prepare-for-review`) is **best-effort**: if no
+  open PR exists for the current branch, it falls back to a plain
+  `git fetch && git merge origin/main`. Existing invocations that
+  ran on a fully detached or pre-PR branch keep working
+
+## Use this command when
+
+- Preparing a self-review before opening a PR
+- Stress-testing a local branch with the same five lenses a reviewer
+  would apply
+- Sanity-checking a diff before handing it to `/create-pr`
+
+## Do NOT
+
+- NEVER apply fixes without showing the consolidated report first
+- NEVER skip a judge because the diff "looks fine" — each judge must
+  produce its own verdict
+- NEVER merge two judges' outputs into a single block — the user
+  needs to see which lens raised each finding
+- NEVER commit or push from this command — review only
+- NEVER run on an empty diff; fail fast
+
+## See also
+
+- [`/prepare-for-review`](prepare-for-review.md) — updates `main` and merges the full base-branch chain into the target branch (used by step 1)
+- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — dispatch and model-pairing rules
+- [`/do-and-judge`](do-and-judge.md) — implementer + judge loop for a single change
+- [`/judge`](judge.md) — standalone judge, no review-changes dispatch
+- [`code-review`](../skills/code-review/SKILL.md) — human-oriented review patterns (tone, feedback handling)
+- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
+
+## References
+
+- **LLM-as-a-Judge** — [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685)
+  MT-Bench and Chatbot Arena — judging LLM outputs with LLM judges.
+  This command adapts the pattern by dispatching to four specialized
+  judges (bug, security, tests, quality) instead of a single generic
+  judge, and consolidating their verdicts.