outfitter-dev Outfitter Check
Verify Outfitter compliance and produce a structured report.
Goal
Scan a codebase and produce a Compliance Report at .agents/notes/YYYY-MM-DD-outfitter-check.md documenting:
- What violations were found (by severity)
- Where they are (file:line)
- How to fix them (with pattern references)
Constraints
DO:
- Load
outfitter-atlasfirst for pattern knowledge - Scan systematically using the diagnostic commands
- Rank findings by severity (Critical > High > Medium > Low)
- Reference fieldguide patterns for fixes
- Produce a Compliance Report at the end
DON'T:
- Skip categories during scanning
- Report issues without actionable guidance
- Mix severity levels (keep them separate)
- Forget to check the target scope (file, directory, or full codebase)
Steps
- Load
outfitter-atlasfor pattern expertise - Determine scope — what are we checking?
- Run diagnostics — systematic anti-pattern scan
- Categorize findings — rank by severity
- Produce report — using TEMPLATE.md
- Migration guidance — detect version gaps and compose upgrade instructions
Step 1: Determine Scope
Ask or infer the target:
| Scope | When | Command Modifier |
|---|---|---|
| Single file | "Check this file" | rg PATTERN path/to/file.ts |
| Directory | "Check src/handlers" | rg PATTERN path/to/dir/ |
| Full codebase | "Check compliance" | rg PATTERN --type ts |
Exclude test files unless specifically requested:
rg PATTERN --type ts -g "!*.test.ts" -g "!__tests__/*"
Step 2: Run Diagnostics
Run each scan and collect results.
Critical: Exception Control Flow
# Thrown exceptions (must convert to Result)
rg "throw new" --type ts -g "!*.test.ts" -n
# try/catch control flow (must convert to Result checking)
rg "try \{" --type ts -g "!*.test.ts" -n
Why critical: Breaks type safety, loses error context, makes control flow unpredictable.
High: Logging and Paths
# Console usage (must use ctx.logger)
rg "console\.(log|error|warn|info|debug)" --type ts -g "!*.test.ts" -n
# Hardcoded home paths (must use XDG via @outfitter/config)
rg "(homedir\(\)|~\/\.)" --type ts -g "!*.test.ts" -n
Why high: Console breaks structured logging; hardcoded paths break portability.
Medium: Type Safety
# Custom error classes (should use taxonomy)
rg "class \w+Error extends Error" --type ts -n
# Handlers without context parameter
rg "Handler<.*> = async \(input\)" --type ts -n
# Missing Result type returns
rg "async.*Handler.*\{" --type ts -A 10 | rg "return [^R]" -B 5
Why medium: Reduces type safety and pattern consistency.
Low: Style and Documentation
# process.exit without exitWithError
rg "process\.exit\(" --type ts -g "!*.test.ts" -n
# Missing .describe() on Zod schemas used with MCP
rg "z\.(string|number|boolean|object)\(\)(?!.*\.describe)" --type ts -n
Why low: Affects agent experience and exit code consistency.
Step 3: Categorize Findings
Count results and assign severity:
| Severity | Findings | Action |
|---|---|---|
| Critical | throw/try-catch in handlers | Must fix before merge |
| High | console.log, hardcoded paths | Should fix before merge |
| Medium | Custom errors, missing context | Fix when touching file |
| Low | Style issues, missing describe | Nice to have |
Severity Definitions
| Level | Impact | Examples |
|---|---|---|
| Critical | Breaks core patterns, causes runtime issues | Thrown exceptions, unvalidated paths |
| High | Breaks observability or portability | Console logging, hardcoded paths |
| Medium | Reduces type safety or consistency | Custom errors, missing context param |
| Low | Affects polish, not correctness | Style, documentation gaps |
Step 4: Produce Report
Write the Compliance Report to .agents/notes/YYYY-MM-DD-outfitter-check.md using TEMPLATE.md.
# Create directory if needed
mkdir -p .agents/notes
# Report path (replace YYYY-MM-DD with today's date)
# .agents/notes/2024-01-15-outfitter-check.md
Pass Criteria
| Status | Criteria |
|---|---|
| PASS | 0 critical, 0 high |
| WARNINGS | 0 critical, 1+ high or medium |
| FAIL | 1+ critical |
Quick Summary
## Compliance: [scope]
**Status**: PASS | WARNINGS | FAIL
**Issues**: X critical, Y high, Z medium, W low
{ details follow }
Fix References
Point to fieldguide patterns for each issue type:
| Issue | Fix Pattern |
|---|---|
throw new |
patterns/conversion.md |
try/catch |
patterns/results.md |
console.log |
patterns/logging.md |
| Hardcoded paths | patterns/file-ops.md |
| Custom errors | patterns/errors.md |
| Missing context | patterns/handler.md |
Quick Check
For a fast pass/fail without full report:
# Critical count (should be 0)
rg "throw new|try \{" --type ts -g "!*.test.ts" -c | wc -l
# High count (should be 0)
rg "console\.(log|error|warn)|homedir\(\)" --type ts -g "!*.test.ts" -c | wc -l
Step 5: Migration Guidance
After the compliance scan, detect installed @outfitter/* versions and check for available migrations using the outfitter upgrade command.
# Check for available updates (human-readable)
bunx outfitter upgrade --guide --cwd .
For JSON output (version data only, does not include migration docs):
bunx outfitter upgrade --json --cwd .
If updates are found, append a Migration Guidance section to the compliance report. If all packages are up to date, note that in the report.
The command:
- Reads
package.jsonfor@outfitter/*dependencies - Queries npm for latest versions
- When
--guideis used, composes migration docs from the kit plugin's shared migrations
Related Skills
outfitter-atlas— Patterns and fix guidance (load first)outfitter-start— Full adoption workflow with staged plandebug-outfitter— Deep investigation of specific issues