# build-validator — CI Validation Subagent

> Open-source Claude Code subagent that validates the full build pipeline (typecheck, lint, test, build) and reports failures. Inspired by Boris Cherny.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# build-validator — CI Validation Subagent

## Quick Use

1. Save the file below to `.claude/agents/build-validator.md`.
2. Restart Claude Code (or `/agents reload`).
3. Before pushing, say:
   > "Run build-validator before I push."

You get the full local pipeline (typecheck + lint + unit tests + build) with errors grouped by stage and a clear pass/fail.

> Inspired by Boris Cherny's setup (howborisusesclaudecode.com). Community-written equivalent.

---

## Intro

build-validator is a Claude Code subagent that runs your full CI pipeline locally before you push. It is the "did I break the build" check — typecheck, lint, unit tests, build — staged so failures are isolated to a specific phase. The point is to catch CI failures 10 minutes earlier, with the failing diff still warm in your head.

Boris Cherny describes a build-check subagent as part of his pre-push routine on howborisusesclaudecode.com. This entry captures that pattern.

Works with: Claude Code 1.x. Auto-detects Node, Python, Go, Rust toolchains. Setup: under 1 minute.

---

## How build-validator Works

Save to `.claude/agents/build-validator.md`:

```markdown
---
name: build-validator
description: Run the full local build pipeline (typecheck, lint, unit tests, build) and report stage-by-stage. Use before pushing.
tools: Bash, Read, Grep, Glob
---

You are the build-validator subagent. You run a fixed pipeline against the current working tree and report whether it passes.

## Workflow

1. Detect toolchain by inspecting the repo:
   - Node: `package.json` → use `npm run` scripts
   - Python: `pyproject.toml`/`setup.cfg` → use `ruff` / `mypy` / `pytest`
   - Go: `go.mod` → `go vet`, `go build`, `go test`
   - Rust: `Cargo.toml` → `cargo check`, `cargo clippy`, `cargo test`, `cargo build`
2. Run stages in order. Stop at the first failure unless `--keep-going` is mentioned.
   1. typecheck (or equivalent: tsc --noEmit, mypy, go vet, cargo check)
   2. lint (eslint, ruff, golangci-lint, cargo clippy)
   3. unit tests (jest/vitest, pytest, go test, cargo test)
   4. build (next build, vite build, go build, cargo build)
3. For each failed stage, capture the first 20 lines of stderr.
4. Emit the structured report below.

## Output format

build-validator
===============
Toolchain: <Node | Python | Go | Rust | mixed>
Duration: <seconds>

Stage results:
✅ typecheck
✅ lint
❌ unit tests — 3 failures
   src/lib/billing.test.ts:42 — Expected 100, got 99
   ...
⏸️  build (skipped — earlier stage failed)

Verdict: FAIL at unit tests

Suggested fix: review the 3 test failures above; pricing math regression.

## Boundaries

- Do not auto-fix anything.
- Do not run E2E tests (use verify-app).
- Do not deploy.
- If the toolchain is unrecognized, escalate: "Add a `validate.sh` script and re-run."
```

### When to use

- Right before `git push`.
- After a `/loop` or `/ralph-loop` finishes — confirm the loop did not regress fundamentals.
- In CI substitution mode when CI is down.

### When not to use

- During active feature development — too noisy. Wait until you think you are done.
- Without a stable toolchain — fix the project setup first.

---

## Example session

```
You:    "Run build-validator before I push."
Claude: -> detects Node + TypeScript project
        -> tsc --noEmit ✅
        -> eslint ✅
        -> vitest ❌ 3 failures in src/lib/billing.test.ts
        -> stops, reports
You:    "Fix the failures."
Claude: ... (fixes, re-runs build-validator until ✅)
```

---

## FAQ

**Q: Does it run E2E tests?**
A: No — that is verify-app's job. build-validator covers typecheck/lint/unit/build only.

**Q: Will it fix failures itself?**
A: No — fail-and-report. Pair with a code-fixer subagent if you want auto-repair.

**Q: My project has multiple package manifests (monorepo). Does that work?**
A: Yes, but you may want to scope it. Edit the Workflow to pass `--filter <package>` to your monorepo tool.

**Q: Can I add custom stages?**
A: Yes — edit the Workflow. Common additions: `prisma generate`, `openapi-typescript`, security scanners.

**Q: Is this Boris Cherny's actual subagent?**
A: No — community-written equivalent based on his public setup description.

---

## Source & Thanks

> Inspired by Boris Cherny's pre-push validation routine on howborisusesclaudecode.com.

Citations:
- howborisusesclaudecode.com
- Pragmatic Engineer: https://newsletter.pragmaticengineer.com/p/building-claude-code-with-boris-cherny
- Get Push To Prod: https://getpushtoprod.substack.com/p/how-the-creator-of-claude-code-actually

<!-- ZH -->

## 快速使用

1. 落 `.claude/agents/build-validator.md`
2. `/agents reload`
3. push 前问："Run build-validator before I push."

按 typecheck / lint / unit test / build 顺序跑，遇到第一个失败停下报告，省得 CI 才发现。

## 边界

- 不跑 E2E（那是 verify-app 的事）
- 不自动修
- 不部署
- 工具链识别不出来直接喊你加 validate.sh


---
Source: https://tokrepo.com/en/workflows/build-validator-ci-validation-subagent-fded195c
Author: Skill Factory