| name | repo-eval |
| description | Multi-dimensional codebase evaluation with verified scoring that writes a markdown scorecard only. Use when the user asks to evaluate, audit, score, grade, or review a repository holistically without adopting agile-workflow. Launches parallel exploratory sub-agents, cross-checks claims with direct verification, and produces calibrated 1-10 scores across architecture, code quality, error handling, testing, documentation, CI/CD, security, developer experience, and maintainability.
|
Repo Eval
Perform a structured, evidence-backed evaluation of a codebase and write a markdown report. This
standalone variant never files .work/ items and never commits. It produces REPO-EVAL.md by
default, or a user-specified output path.
Arguments
- No arguments: evaluate the entire repository.
- Path argument such as
src/: scope evaluation to that subtree.
- Dimension list such as
testing,architecture: evaluate only named dimensions.
--output <path>: write somewhere other than REPO-EVAL.md.
Dimensions
Score all 9 by default.
| # | Dimension | What it covers |
|---|
| 1 | Architecture & Design | Dependency graph, separation of concerns, layering, abstraction quality |
| 2 | Code Quality | Idiomatics, type safety, unsafe usage, anti-patterns, consistency |
| 3 | Error Handling | Error types, propagation, panics in library code, edge case coverage |
| 4 | Testing | Test layers, coverage strategy, fixture quality, edge case tests, E2E |
| 5 | Documentation | README, design docs, API docs, inline docs, doc freshness |
| 6 | CI/CD & Automation | Pipelines, linting, formatting, release process, dependency auditing |
| 7 | Security Posture | Unsafe code, validation, secrets, dependency hygiene |
| 8 | Developer Experience | Build ergonomics, onboarding, error messages, tooling |
| 9 | Maintainability | Module boundaries, coupling, file sizes, naming, upgrade path |
Phase 1: Parallel Exploration
Launch four read-only exploratory sub-agents in parallel. Use the strongest reviewer/explorer setting
the host exposes; use extra-high reasoning for large, polyglot, or architecture-heavy repos.
Each agent receives the repo path and scope restrictions.
Agent A: Structure & Infrastructure
Investigate repository layout, build system, dependency hygiene, CI/CD, formatter/linter configs,
LOC by language, scripts, and automation.
Agent B: Code Quality & Error Handling
Investigate error handling, panic safety, unsafe code, type safety, module organization,
logging/tracing, and code smells. Read representative source files and cite examples.
Agent C: Testing & Quality Assurance
Investigate test layers, test count, distribution, fixture quality, assertions, mocks, E2E, and test
configuration. Count tests and read actual test files.
Agent D: Documentation & API Design
Investigate README quality, inline docs, design docs, public API consistency, naming, examples, and
doc freshness against code.
Phase 2: Direct Verification
After agents return, verify key claims yourself. Do not blindly trust summaries. Adapt commands to
the detected language and scope. Use references/verification-checks.md.
Run at least 10 verification checks when the repo is large enough:
- CI exists.
- Linter and formatter are configured.
- Panic/unwrap/expect or equivalent risky shortcuts are counted outside tests.
- Unsafe code or equivalent escape hatches are located.
- Logging/println/console usage is checked in source.
- Error type strategy is checked.
- Test count and test layers are verified.
- README and design docs are checked.
- Security secret patterns are searched.
- Dependency auditing is checked.
Cross-reference every important agent claim. Discrepancies must affect scoring and appear in the
report.
Phase 3: Scoring
Use references/scoring-rubric.md.
Rules:
- Every score >= 7 cites verified positive evidence.
- Every score <= 5 cites verified deficiency.
- Scores of 9-10 require exceptional evidence.
- A normal competent codebase scores 5-6. Do not inflate.
- Overall score uses the rubric's weighting: architecture and code quality count 1.5x.
Phase 4: Write The Report
Use references/report-template.md. Write to REPO-EVAL.md unless
the user supplied --output.
The report must include:
- Summary.
- Scorecard table.
- Overall score.
- Dimension details with verified positives, concerns, and discrepancies.
- Verification summary.
- Top 5 recommendations.
In the final message, summarize the overall score, the weakest dimensions, top recommendations, and
the report path.
Language Detection
Detect primary languages before launching agents:
| Signal | Language |
|---|
Cargo.toml, *.rs | Rust |
package.json, *.ts, *.js | JavaScript/TypeScript |
go.mod, *.go | Go |
pyproject.toml, *.py | Python |
*.csproj, *.cs | C# |
Pass the detected language to sub-agents so their checks use the right terminology.
Guardrails
- Verify before scoring.
- Treat unverified claims as unverified, not evidence.
- Do not write
.work/, backlog, release, or tracking artifacts.
- Do not implement recommendations.
