validator-setup

Files (3)

• SKILL.md
• check-catalog.md · references/
• project-structure.md · references/

SKILL.md (first lines)

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

From Codagent-AI/agent-validator, MIT.

More from Codagent-AI/agent-validator