Stack Audit

Scan a codebase to identify Outfitter Stack adoption candidates and generate an audit report.

Quick Start

Option 1: Run the scanner (recommended for large projects)

bun run plugins/outfitter-stack/skills/stack-audit/scripts/init-audit.ts [project-root]

Generates .outfitter/adopt/ with:

• audit-report.md – Scan results and scope
• plan/ – Stage-by-stage task files

Option 2: Manual scan (smaller projects)

Run the audit commands below to understand scope.

Audit Commands

Critical Issues – Exceptions

# Count throw statements
rg "throw (new |[a-zA-Z])" --type ts -c

# List throw locations
rg "throw (new |[a-zA-Z])" --type ts -n

# Count try-catch blocks
rg "(try \{|catch \()" --type ts -c

Console Usage

# Count console statements
rg "console\.(log|error|warn|debug|info)" --type ts -c

# List console locations
rg "console\.(log|error|warn|debug|info)" --type ts -n

Hardcoded Paths

# Homedir usage
rg "(homedir\(\)|os\.homedir)" --type ts -c

# Tilde paths
rg "~/\." --type ts -c

# Combined path issues
rg "(homedir|~\/\.)" --type ts -n

Custom Error Classes

# Find custom error classes
rg "class \w+Error extends Error" --type ts -n

# Count usage of custom errors
rg "new MyCustomError\(" --type ts -c

Generated Structure

.outfitter/adopt/
├── audit-report.md           # Scan results, scope, recommendations
└── plan/
    ├── 00-overview.md        # Status dashboard, dependencies
    ├── 01-foundation.md      # Dependencies, context, logger
    ├── 02-handlers.md        # Handler conversions
    ├── 03-errors.md          # Error taxonomy mappings
    ├── 04-paths.md           # XDG path migrations
    ├── 05-adapters.md        # CLI/MCP transport layers
    ├── 06-documents.md       # Documentation updates
    └── 99-unknowns.md        # Items requiring review

Migration Stages

Audit Report Fields

Error Taxonomy Reference

When mapping errors, use this reference:

Effort Estimation

Interpreting Results

High-Priority Items

• Functions with 3+ throw statements (complex error handling)
• Files with 3+ try-catch blocks (may need restructuring)
• Custom error classes with high usage counts

Medium-Priority Items

• Isolated throw statements (simple conversions)
• Console logging (straightforward migration)
• Hardcoded paths (mechanical replacement)

Low-Priority Items

• Documentation updates (can happen last)
• Test file updates (follow handler changes)

Next Steps After Audit

1. Review audit-report.md for accuracy
2. Adjust priorities in plan/00-overview.md
3. Begin with Stage 1 (Foundation)
4. Load outfitter-stack:stack-patterns for conversion guidance
5. Load outfitter-stack:stack-templates for scaffolding

Constraints

Always:

• Run audit before planning adoption
• Review unknowns for complex patterns
• Estimate effort before committing

Never:

• Skip the audit phase
• Underestimate try-catch complexity
• Ignore custom error classes

Related Skills

• outfitter-stack:stack-patterns – Target patterns reference
• outfitter-stack:stack-templates – Component templates
• outfitter-stack:stack-review – Verify compliance