validator-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/validator-setup

Scan the project to discover tooling and configure checks and reviews for agent-validator.

Before starting, read

references/check-catalog.md

for check category details, YAML schemas, and example configurations.

扫描项目以发现工具链，并为agent-validator配置检查与评审。

开始操作前，请阅读

references/check-catalog.md

以了解检查类别详情、YAML schema及配置示例。

Step 1: Check config exists

步骤1：检查配置文件是否存在

Read

.validator/config.yml

. If the file does not exist, tell the user to run

agent-validate init

first and STOP — do not proceed with any further steps.

读取

.validator/config.yml

。若该文件不存在，请告知用户先运行

agent-validate init

并停止后续操作——请勿继续执行任何步骤。

Step 2: Check existing config

步骤2：检查现有配置

Read the

entry_points

field from

.validator/config.yml

If
entry_points
is empty (
[]
): This is a fresh setup. Proceed to Step 3 (detect project structure).

If
entry_points
is populated: Show the user a summary of the current configuration:

List each entry point with its
```
path
```
,
```
checks
```
, and
```
reviews
```
Then ask the user which action to take:
1. Add checks — Scan for tools not already configured. Proceed to Step 3, but filter out any checks that already appear in
```
entry_points
```
  .
2. Add custom — User describes what they want to add. Skip to Step 7.
3. Reconfigure — Start fresh. Back up existing config first:
  - Rename each
```
.validator/checks/*.yml
```
    file to
```
.yml.bak
```
    (overwrite any previous
```
.bak
```
    files) — these are legacy file-based checks
  - Rename each custom
```
.validator/reviews/*.md
```
    file to
```
.md.bak
```
    (overwrite any previous
```
.bak
```
    files)
  - Do NOT rename
```
.validator/reviews/*.yml
```
    files (these are built-in review configs)
  - Clear
```
entry_points
```
    to
```
[]
```
    in
```
config.yml
```
  - Proceed to Step 3

读取

.validator/config.yml

中的

entry_points

字段。

若
entry_points
为空（
[]
）：这是全新配置，继续执行步骤3（检测项目结构）。

若
entry_points
已填充内容：向用户展示当前配置的摘要：

列出每个入口点的
```
path
```
、
```
checks
```
和
```
reviews
```
然后询问用户要执行以下哪个操作：
1. 添加检查 —— 扫描未配置的工具。继续执行步骤3，但过滤掉
```
entry_points
```
  中已存在的检查项。
2. 添加自定义项 —— 用户描述需添加的内容。跳至步骤7。
3. 重新配置 —— 从头开始。先备份现有配置：
  - 将每个
```
.validator/checks/*.yml
```
    文件重命名为
```
.yml.bak
```
    （覆盖之前的
```
.bak
```
    文件）——这些是基于文件的旧版检查项
  - 将每个自定义
```
.validator/reviews/*.md
```
    文件重命名为
```
.md.bak
```
    （覆盖之前的
```
.bak
```
    文件）
  - 请勿重命名
```
.validator/reviews/*.yml
```
    文件（这些是内置评审配置）
  - 将
```
config.yml
```
    中的
```
entry_points
```
    清空为
```
[]
```
  - 继续执行步骤3

Step 3: Detect project structure

步骤3：检测项目结构

Scan for signals to classify the project as monorepo, split project, or single project.

扫描项目特征，将其归类为单体仓库（monorepo）、拆分项目或单一项目。

Monorepo signals

单体仓库特征

```
package.json
```
with a
```
workspaces
```
field
```
pnpm-workspace.yaml
```
```
lerna.json
```
,
```
nx.json
```
,
```
turbo.json
```
```
Cargo.toml
```
with a
```
[workspace]
```
section
Multiple subdirectories under
```
packages/
```
,
```
apps/
```
, or
```
services/
```
each containing their own project manifest (
```
package.json
```
,
```
go.mod
```
,
```
Cargo.toml
```
,
```
pyproject.toml
```
)

包含
```
workspaces
```
字段的
```
package.json
```
```
pnpm-workspace.yaml
```
```
lerna.json
```
、
```
nx.json
```
、
```
turbo.json
```
包含
```
[workspace]
```
章节的
```
Cargo.toml
```
```
packages/
```
、
```
apps/
```
或
```
services/
```
目录下存在多个子目录，每个子目录都有自己的项目清单（
```
package.json
```
、
```
go.mod
```
、
```
Cargo.toml
```
、
```
pyproject.toml
```
）

Split project signals

拆分项目特征

```
frontend/
```
+
```
backend/
```
(or
```
client/
```
+
```
server/
```
,
```
web/
```
+
```
api/
```
) directories each containing source code and/or their own project manifest
Multiple apps or libraries of the same language under a common parent directory (e.g.,
```
apps/web/
```
,
```
apps/api/
```
,
```
apps/worker/
```
each with their own source and config) — suggests a wildcard entry point like
```
apps/*
```

```
frontend/
```
+
```
backend/
```
（或
```
client/
```
+
```
server/
```
、
```
web/
```
+
```
api/
```
）目录，每个目录都包含源代码和/或自己的项目清单
同一语言的多个应用或库位于同一父目录下（例如
```
apps/web/
```
、
```
apps/api/
```
、
```
apps/worker/
```
，每个都有自己的源代码和配置）——建议使用通配符入口点如
```
apps/*
```

Single project signals

单一项目特征

```
src/
```
or
```
lib/
```
as sole source directory, or source files at project root
No monorepo or split project signals found

If monorepo or split project: Read

references/project-structure.md

for detailed multi-project entry point guidance, then follow it for Steps 4 through 8. The rest of this file covers the single-project flow.

If single project: Tell the user what you detected and continue below.

```
src/
```
或
```
lib/
```
作为唯一的源代码目录，或源代码文件位于项目根目录
未发现单体仓库或拆分项目的特征

若为单体仓库或拆分项目： 阅读

references/project-structure.md

获取多项目入口点的详细指南，然后按照该指南执行步骤4至8。本文档剩余部分介绍单一项目的流程。

若为单一项目： 告知用户检测结果，然后继续执行后续步骤。

Step 4: Determine entry point path

步骤4：确定入口点路径

Infer the source directory:

If
```
src/
```
exists and contains source code, suggest
```
src
```
If
```
lib/
```
exists and contains source code, suggest
```
lib
```
Otherwise suggest
```
.
```
(project root — safer default since it captures all changes)

Skip this step if adding checks to an existing entry point that already has a path.

推断源代码目录：

若
```
src/
```
存在且包含源代码，建议使用
```
src
```
若
```
lib/
```
存在且包含源代码，建议使用
```
lib
```
否则建议使用
```
.
```
（项目根目录——更安全的默认选项，因为它能捕获所有变更）

若为向现有入口点添加检查项，则跳过此步骤（该入口点已包含路径）。

Step 5: Scan for tooling

步骤5：扫描工具链

Scan the project for tooling signals across the 6 check categories listed in

references/check-catalog.md

For the "add checks" path: Filter out checks already configured in

entry_points

If no tools discovered: Offer the custom flow (skip to Step 7). Still include

code-quality

review.

扫描项目中属于

references/check-catalog.md

列出的6个检查类别的工具特征。

对于「添加检查」流程： 过滤掉

entry_points

中已配置的检查项。

若未发现任何工具： 提供自定义流程（跳至步骤7）。仍需包含

code-quality

评审。

Step 6: Present findings and confirm

步骤6：展示检测结果并确认

Show a table of discovered checks:

Category        | Tool            | Command                              | Confidence
----------------|-----------------|--------------------------------------|-----------
Build           | npm             | npm run build                        | High
Lint            | ESLint          | npx eslint .                         | High
Typecheck       | TypeScript      | npx tsc --noEmit                     | High
Test            | Jest            | npx jest                             | High
Security (deps) | npm audit       | npm audit --audit-level=moderate     | Medium
Security (code) | Semgrep         | semgrep scan --config auto --error . | Medium

Confidence levels:

High — Tool config file found AND/OR explicit script in package.json/Makefile
Medium — Tool found in devDependencies or inferred from CI workflow but no dedicated config
Low — Only indirect evidence (e.g., test directory exists but no runner config found)

If a category has no discovered tool, show

(not found)

with

—

for command and confidence.

Ask the user:

Which checks to enable (default: all)
Whether any commands need adjustment

If the user declines ALL checks, still include

code-quality

review and offer the custom flow (Step 7).

After confirmation, proceed to Step 8 (create files).

展示已发现检查项的表格：

Category        | Tool            | Command                              | Confidence
----------------|-----------------|--------------------------------------|-----------
Build           | npm             | npm run build                        | High
Lint            | ESLint          | npx eslint .                         | High
Typecheck       | TypeScript      | npx tsc --noEmit                     | High
Test            | Jest            | npx jest                             | High
Security (deps) | npm audit       | npm audit --audit-level=moderate     | Medium
Security (code) | Semgrep         | semgrep scan --config auto --error . | Medium

置信度等级：

高 —— 发现工具配置文件，且/或
```
package.json
```
/Makefile中有明确的脚本
中 —— 在devDependencies中发现工具，或从CI工作流推断出工具，但无专用配置文件
低 —— 仅存在间接证据（例如存在测试目录但未发现运行器配置）

若某类别未发现工具，显示

(未找到)

，命令和置信度栏显示

—

。

询问用户：

要启用哪些检查项（默认：全部）
是否需要调整任何命令

若用户拒绝所有检查项，仍需包含

code-quality

评审，并提供自定义流程（步骤7）。

确认后，继续执行步骤8（创建文件）。

Step 7: Add custom

步骤7：添加自定义项

Ask the user: check (shell command) or review (AI code review)?

For checks: Ask for command, name, and optional settings (run_in_ci, run_locally).

For reviews: Built-in (

code-quality

) or custom prompt? Ask for name and write the review content.

询问用户：添加check（Shell命令）还是review（AI代码评审）？

对于check： 询问命令、名称及可选设置（

run_in_ci

、

run_locally

）。

对于review： 使用内置（

code-quality

）还是自定义提示？询问名称并编写评审内容。

Step 8: Create files and update config

步骤8：创建文件并更新配置

Checks — Add checks inline in the entry point's

checks

array. Each inline check is a single-key object (check name → config object). Include

command

. Add optional fields (

run_in_ci

run_locally

) only when they differ from defaults. See

references/check-catalog.md

for schema. Do NOT add a top-level

checks

map — inline checks belong under entry_points.

Custom reviews — Create

.validator/reviews/<name>.md

with YAML frontmatter (

num_reviews: 1

) and review prompt.

Built-in reviews — Add built-in reviews inline in the entry point's

reviews

array (e.g.

- code-quality: { builtin: code-quality }

). Do not create a separate file for built-in reviews.

Update entry_points in

.validator/config.yml

yaml

entry_points:
  - path: "<source_dir>"
    checks:
      - build:
          command: npm run build
      - lint:
          command: npx eslint .
    reviews:
      - code-quality:
          builtin: code-quality

Always include

code-quality

reviews

for fresh setups. For "add checks" / "add custom": append to the appropriate entry point's lists, or add a new entry point if needed. A check or review defined inline in one entry point can be referenced by name (as a string) in other entry points.

Checks —— 在入口点的

checks

数组中内联添加检查项。每个内联检查项是一个单键对象（检查名称 → 配置对象）。需包含

command

。仅当与默认值不同时，才添加可选字段（

run_in_ci

、

run_locally

）。请参考

references/check-catalog.md

中的schema。请勿添加顶层

checks

映射——内联检查项应放在

entry_points

下。

自定义reviews —— 创建

.validator/reviews/<name>.md

文件，包含YAML前置元数据（

num_reviews: 1

）和评审提示。

内置reviews —— 在入口点的

reviews

数组中内联添加内置评审（例如

- code-quality: { builtin: code-quality }

）。无需为内置评审创建单独文件。

更新
.validator/config.yml
中的
entry_points
：

yaml

entry_points:
  - path: "<source_dir>"
    checks:
      - build:
          command: npm run build
      - lint:
          command: npx eslint .
    reviews:
      - code-quality:
          builtin: code-quality

全新配置时，务必在

reviews

中包含

code-quality

。对于「添加检查」/「添加自定义项」：将内容追加到对应入口点的列表中，或根据需要添加新的入口点。在一个入口点中内联定义的check或review，可以通过名称（字符串形式）在其他入口点中引用。

Step 9: "Add something else?"

步骤9：“是否需要添加其他内容？”

Ask the user. If yes, loop to Step 7. If no, proceed.

询问用户。若需要，循环至步骤7。若不需要，继续执行后续步骤。

Step 10: Validate

步骤10：验证配置

Run

agent-validate validate

. If it fails, apply one corrective attempt and re-validate. If it still fails, STOP and ask the user.

运行

agent-validate validate

。若验证失败，尝试一次修正后重新验证。若仍失败，停止操作并询问用户。

Step 11: Commit configuration

步骤11：提交配置

Commit all validator configuration and skills so the setup is preserved in version control:

Stage all new/modified files:

.validator/

.claude/skills/validator-*/

.claude/settings.local.json

.gitignore

Create a commit:

git commit -m "chore: configure agent-validator checks and reviews"

If there are no changes to commit (everything already committed), skip this step silently.

提交所有验证器配置及技能，确保设置被保存到版本控制中：

暂存所有新增/修改的文件：

.validator/

、

.claude/skills/validator-*/

、

.claude/settings.local.json

、

.gitignore

创建提交：

git commit -m "chore: configure agent-validator checks and reviews"

若无需要提交的变更（所有内容已提交），则静默跳过此步骤。

Step 12: Advance validator baseline

步骤12：更新验证器基线

Run

/validator-skip

to advance the execution state baseline to the current working tree, so the next run only diffs against future changes.

运行

/validator-skip

将执行状态基线更新至当前工作树，以便下次运行仅对比未来的变更。

Step 13: Suggest next steps

步骤13：建议下一步操作

Tell the user: configuration is complete. Run

/validator-run

to execute, or

/validator-setup

again to add more.

告知用户：配置已完成。运行

/validator-run

执行检查，或再次运行

/validator-setup

添加更多配置。",