# Validator Setup

> Scans the project and configures checks and reviews for Agent Validator for requests such as "set up validator", "configure checks and reviews", or "initialize validator for this repo".

- Skill: `codagent-ai/validator-setup` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add codagent-ai/validator-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codagent-ai/validator-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: codagent-ai (https://skillmd.com/u/codagent-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codagent-ai/validator-setup

---


# /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.

## Step 1: Check config exists

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.

## Step 2: Check existing config

Read the `entry_points` field from `.validator/config.yml`.

Before deciding whether this project is already configured, inspect the git state of `.validator/`:

- If this is a git repo, run `git status --porcelain -- .validator`.
- If `.validator/` or `.validator/config.yml` is untracked or newly added, treat this as a fresh install even though the directory exists. `agent-validate init` creates the scaffold first; `/validator-setup` still needs to configure checks and entry points.
- If git is unavailable, the project is not a git repo, or the status is ambiguous, do not claim Agent Validator was previously set up. Ask the user whether this is a new install or an existing configuration they want to modify.

Do not conclude "nothing to do" or "already set up" merely because `.validator/` exists. Only treat the project as an existing setup when the committed config already contains meaningful entry points/checks, or the user confirms it is existing.

**If `entry_points` is empty (`[]`) OR contains only the generated root entry point (`path: "."`) with no `checks`:** This is a fresh setup. Proceed to Step 3 (detect project structure). Preserve any existing `reviews` on that generated root entry point unless the user explicitly reconfigures reviews.

**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

## Step 3: Detect project structure

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

### 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`)

### 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/*`

### 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.

## Step 4: Determine entry point path

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.

## Step 5: Scan for tooling

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.

## Step 6: Present findings and confirm

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:
1. Which checks to enable (default: all)
2. 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).

## Step 7: Add custom

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.

## Step 8: Create files and update config

**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` in `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.

## Step 9: "Add something else?"

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

## Step 10: Validate

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

## Step 11: Commit configuration

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

1. Stage all new/modified files: `.validator/`, `.claude/skills/validator-*/`, `.claude/settings.local.json`, `.gitignore`
2. 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.

## Step 12: Advance validator baseline

Run `/validator-skip` to advance the execution state baseline to the current working tree, so the next run only diffs against future changes.

## Step 13: Suggest next steps

Tell the user: configuration is complete. Run `/validator-run` to execute, or `/validator-setup` again to add more.