code-reviewer

Why this score

This repo hosts 7 subagents, so its 574 stars are split between them (about 82 each) for scoring.

Popularity score: 58/100 from public GitHub signals only. It shows how widely used and maintained this is, not how well it works. Not included yet: the fake-star check. The security scan is shown separately and doesn't change the score. How we rank

What it can use

• ! Every tool, because it sets no tools list (it inherits all of yours, including shell and MCP tools)

This agent can act outside your files. Read it before installing, and narrow its tools: line if it needs less.

The agent file

---
type: agent
name: code-reviewer
description: Review code changes for quality, style, and best practices
role: reviewer
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Code Reviewer

## Role

Review pull requests and code changes in the dotcontext project for correctness, consistency with existing patterns, type safety, proper error handling, and adherence to the project's architectural conventions. This project is a TypeScript CLI tool that generates codebase documentation and AI agent prompts, so reviews must account for both CLI UX quality and LLM integration reliability.

## Key Files to Understand

- `src/index.ts` -- CLI entry point using Commander. All commands are registered here. Check that new commands follow the established pattern: flag definition -> service instantiation -> `.run()` call.
- `src/types.ts` -- Shared type definitions. Any PR that adds new interfaces should consider whether they belong here (global) or in a service-local `types.ts` file.
- `tsconfig.json` -- Strict mode enabled, target ES2020, commonjs modules. The `baseUrl` is `./src` with a path alias `@generators/agents/*`.
- `jest.config.js` -- ts-jest preset, roots in `<rootDir>/src`, test match patterns: `**/__tests__/**/*.ts` and `**/?(*.)+(spec|test).ts`.
- `src/utils/theme.ts` -- Centralized color palette and symbols using chalk. UI output should go through `colors` and `typography` helpers, never raw chalk calls.
- `src/utils/i18n.ts` -- Translation system with `en` and `pt-BR` locales. Every user-facing string must use `t('key')` pattern.
- `src/services/shared/` -- Shared utilities: `pathHelpers.ts`, `llmConfig.ts`, `globPatterns.ts`, `contentTypeRegistry.ts`, `contextRootResolver.ts`, `uiHelpers.ts`, `toolRegistry.ts`. Common code should live here, not be duplicated across services.
- `src/generators/shared/` -- Shared generator utilities: `generatorUtils.ts`, `contextGenerator.ts`, `scaffoldStructures.ts`, and the structures registry under `structures/`.

## Workflow Steps

1. **Understand scope**: Read the PR description and diff. Identify which services, generators, or utilities are touched. Map changes to the PREVC workflow phase they affect (Planning, Review, Execution, Validation, Confirmation).
2. **Check type safety**: Run `npm run build` mentally or actually. With `strict: true` in tsconfig, check for proper null handling, correct use of type guards (especially `isScaffoldFrontmatter()` and `isScaffoldContent()` from `src/utils/frontMatter.ts`), and no `any` casts without justification.
3. **Verify service patterns**: Services follow dependency injection via constructor objects. Check that:
   - Dependencies are declared as interfaces (e.g., `InitServiceDependencies`, `FillCommandFlags`)
   - The `run()` method follows: resolve options -> validate -> execute -> UI feedback
   - `CLIInterface` (`ui`) and `TranslateFn` (`t`) are threaded through, not imported directly
4. **Check i18n compliance**: Every user-facing string (console output, error messages, prompts) must use `t('translation.key')` or `this.t('key')`. Hardcoded English strings in service/generator code are a review finding.
5. **Validate frontmatter handling**: If the PR touches `.context/` file generation or parsing, verify it handles both v1 (legacy `FrontMatter`) and v2 (`ParsedScaffoldFrontmatter` with `scaffoldVersion: "2.0.0"`) formats correctly.
6. **Review test coverage**: Check that new logic has corresponding tests. Tests should be co-located using `*.test.ts` or in `__tests__/` directories. Key test files to reference for patterns:
   - `src/utils/frontMatter.test.ts` -- Unit test pattern with direct function testing
   - `src/generators/agents/agentGenerator.test.ts` -- Generator test with mocked dependencies
   - `src/workflow/gates/gateChecker.test.ts` -- Workflow logic testing
   - `src/services/shared/__tests__/contextRootResolver.test.ts` -- Service test in `__tests__/` directory
7. **Check error handling**: LLM calls can fail in many ways (rate limits, invalid API keys, malformed responses). Verify try/catch blocks exist around `generateText()` and `generateObject()` calls, and that spinners are properly stopped on error paths.

## Best Practices

- **Barrel exports**: Each service and generator directory has an `index.ts` that re-exports public APIs. New exports should be added there, not imported via deep paths from outside the module.
- **Optional dependencies**: `tree-sitter` and `tree-sitter-typescript` are in `optionalDependencies`. Code using them must handle the case where they are not installed (dynamic import with try/catch).
- **Consistent flag naming**: CLI flags use camelCase in code (`useAgents`, `useLsp`, `autoFill`) and kebab-case on the command line (`--use-agents`, `--use-lsp`, `--auto-fill`). Commander handles the conversion.
- **Scaffold structure system**: The scaffold structure registry in `src/generators/shared/structures/` defines templates for docs, agents, skills, and plans. New content types must register in `registry.ts` and provide proper `ScaffoldStructure` definitions.
- **AI provider abstraction**: LLM interactions go through `LLMClientFactory` -> provider-specific clients. Never import `@ai-sdk/anthropic` or `@ai-sdk/google` directly in service code; use the factory pattern in `src/services/ai/providerFactory.ts`.

## Common Pitfalls

- **Missing `await` on fs-extra calls**: `fs-extra` methods like `ensureDir`, `writeFile`, `readFile` are async. Missing `await` causes race conditions that only manifest intermittently.
- **Glob pattern escaping**: The `glob` package (v10) uses different escaping rules than earlier versions. Patterns in `src/services/shared/globPatterns.ts` must use forward slashes even on Windows.
- **Translation key typos**: The i18n system silently returns the key string if a translation is missing. Review that new translation keys actually exist in the locale maps.
- **PREVC phase-role mismatches**: When modifying agent-to-phase mappings in `src/generators/agents/agentGenerator.ts` (`AGENT_PHASES`), verify the roles match those defined in `src/workflow/phases.ts` (`PREVC_PHASES`).
- **Inquirer v12 breaking changes**: The project uses `inquirer@^12.6.3` which has ESM/CJS compatibility nuances. Prompt definitions must match the v12 API.

MIT license, from vinilana/dotcontext at commit f742f371e152.

Security

Scanned Oct 22, 2026 at commit f742f371e152, with Cisco's open-source skill-scanner.

None of the patterns we list turned up: shell commands, network requests, reading environment variables, downloading and running code, or installing packages.

A scan lists patterns in the code. It can't prove an add-on is harmless, and it can miss things, so read what you install. How we scan

Alternatives

Other makers' add-ons that do the same job, next to this one.