Code Review
Testing & QualityCode Review is an Agent Skill for testing & quality published in the vinilana/dotcontext repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Review code quality, patterns, and best practices
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/vinilana/dotcontext/blob/HEAD/.context/skills/code-review/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/code-review-7abada36, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Code Review
Guidelines for reviewing code changes in the @dotcontext/cli project.
When to Use
- Reviewing a pull request or diff
- Validating code during the Review (R) or Validation (V) phases of the PREVC workflow
- Checking a new service, generator, or utility for adherence to project patterns
- Evaluating MCP gateway handler implementations
Project Standards
TypeScript Configuration
- Target: ES2020, Module: CommonJS
- Strict mode enabled (
"strict": true) - Declarations and source maps generated
- Path alias:
@generators/agents/*maps tosrc/generators/agents/*
Code Organization Patterns
Service Layer (22 services in src/services/):
- Each service lives in its own directory under
src/services/ - Exports through
index.tsbarrel files - Constructor takes an options object or required config
- Methods are async where I/O is involved
- Example:
FillService,WorkflowService,AIContextMCPServer
Generators (src/generators/):
- Separate generators for docs, agents, plans, skills
- Accept options objects, return typed result objects (e.g.,
SkillGeneratorResult) - Use frontmatter serialization from
src/types/scaffoldFrontmatter.ts
Utilities (src/utils/):
- Pure functions or thin wrappers:
frontMatter.ts,contentSanitizer.ts,gitService.ts - CLI UI abstraction:
cliUI.tswithCLIInterfacetype - i18n:
i18n.tswithTranslateFntype anden/pt-BRlocale support
MCP Gateway Handlers (src/services/mcp/gateway/):
- One file per gateway:
explore.ts,context.ts,sync.ts, etc. - Exports: handler function, params type, options type, action type
- Uses
createJsonResponse/createErrorResponse/createTextResponsefromresponse.ts - Barrel re-export through
index.tsandgatewayTools.ts
Review Checklist
Architecture
- New code follows the service/generator/util separation
- No direct file I/O in generators -- delegate to services or
fs-extra - MCP handlers do not use
console.log(useprocess.stderr.writefor debug output) -
repoPathis never hardcoded; always resolved through options orgetRepoPath()
TypeScript Quality
- No
anytypes (useunknown+ type guards where needed) - Exported interfaces/types for all public APIs
- Async functions return typed Promises, not implicit
any - Optional dependencies (tree-sitter) have graceful fallbacks
Error Handling
- MCP gateway handlers return
createErrorResponse()rather than throwing - CLI commands catch errors and display via
chalk/orawith user-friendly messages - File operations use
fs-extramethods which handle missing directories
Naming Conventions
- Files: camelCase (
fillService.ts,codebaseAnalyzer.ts) - Classes: PascalCase (
SkillGenerator,SemanticContextBuilder) - Interfaces: PascalCase, often with
I-free naming (SkillMetadata, notISkillMetadata) - Constants: UPPER_SNAKE_CASE (
BUILT_IN_SKILLS,PREVC_PHASE_ORDER) - MCP tools: kebab-case (
workflow-init,workflow-status)
Testing
- New services have corresponding
.test.tsfiles - Tests use
jest.mock()for external dependencies (AI providers, file system) - Temp directories created with
fs.mkdtemp()and cleaned up inafterEach - Mock
CLIInterfaceandTranslateFnfor service tests (seefillService.test.ts)
Frontmatter
- New scaffold files use v2 format with
scaffoldVersion: "2.0.0" -
statusfield is set correctly (unfilledfor new,filledafter content generation) - Type-specific fields present (
skillSlugfor skills,agentTypefor agents, etc.)
i18n
- New user-facing strings added to both
enandpt-BRinsrc/utils/i18n.ts - Translation keys follow dot-notation:
'commands.fill.description' - CLI output uses
t()function, not hardcoded strings
Instructions
Reviewing a Service Change
- Check the service's public interface -- does it follow the options-object constructor pattern?
- Verify barrel exports in
index.tsare updated - Check for proper error handling (try/catch with typed errors)
- Ensure no side effects in constructors (async init should be a separate method)
- Look for dependency injection points (e.g.,
AIContextMCPServeracceptscontextBuilderfor testing)
Reviewing an MCP Tool Change
- Verify Zod schema has
.describe()on every param with action prefix - Check that the handler switch covers all actions in the enum
- Confirm responses use
createJsonResponse/createErrorResponseconsistently - Verify new types are re-exported through
gatewayTools.ts - Check that
repoPathuses the caching mechanism viagetRepoPath()
Reviewing a Generator Change
- Check output paths are constructed with
path.join(repoPath, outputDir, ...) - Verify
forceflag is respected (skip existing files whenfalse) - Ensure frontmatter is generated via
createSkillFrontmatter/serializeFrontmatterfromscaffoldFrontmatter.ts - Check that the result type includes all relevant counts (generated, skipped, etc.)
Reviewing a Workflow Change
- Verify phase transitions follow PREVC order (P -> R -> E -> V -> C)
- Check scale-dependent phase inclusion (QUICK: E+V only, SMALL: P+E+V, MEDIUM: P+R+E+V, LARGE: all)
- Ensure gate checks are enforced unless
autonomousorforceis true - Verify workflow status file is written to
.context/runtime/workflows/