Tool Updater

Tool Updater

Overview

Use this skill to refresh an existing CLI tool safely: research current best practices, compare against current implementation, generate a TDD patch backlog, apply updates, and verify CLI invocation.

When to Use

• Tool has broken require() paths or runtime errors
• Tool's CLI interface needs updating (new flags, changed behavior)
• Reflection flags stale or low-performing tool
• User asks to audit/refresh an existing tool

The Iron Law

Never update a tool blindly. Every refresh must be evidence-backed, TDD-gated, and integration-validated.

Workflow

Step 0: Evaluate Current State

1. Read the tool file and understand its purpose
2. Check if it's registered in package.json scripts
3. Test node <tool-path> --help for CLI interface
4. Identify issues: broken requires, missing error handling, stale logic

Step 1: Research Best Practices

1. Read .claude/tools/cli/CLAUDE.md for tool conventions
2. Review similar tools for patterns (especially cli-wrapper.cjs usage)
3. Check if tool uses wrapCLITool() from ../../lib/utils/cli-wrapper.cjs
4. Use Skill({ skill: 'research-synthesis' }) if external research needed

Step 2: Generate Patch Backlog

1. List specific changes needed
2. Prioritize: broken requires > CLI interface > error handling > logic
3. Estimate scope: <30 lines = auto-apply, >30 lines = plan mode

Step 3: Apply Updates

1. Write or update tests first (RED phase)
2. Apply tool changes (GREEN phase)
3. Refactor for clarity (REFACTOR phase)
4. Use Edit tool — never rewrite the entire file

Step 4: Verify Integration

1. Verify tool loads without MODULE_NOT_FOUND errors
2. Verify --help output is correct and complete
3. Verify tool handles missing args gracefully (exit 1 with usage)
4. If CLI tool, verify package.json script entry exists or add one
5. Run pnpm lint:fix && pnpm format
6. Run tool-specific tests

Step 5: Record

1. Log changes via MemoryRecord if significant
2. Update CHANGELOG.md entry

Domain-Specific Validation

• Tool MUST load without MODULE_NOT_FOUND errors
• Tool MUST handle --help flag and missing arguments gracefully
• Tool require() paths MUST be file-relative, not CWD-relative
• Tool MUST use shell: false for any child process spawning (SE security rule)
• Tool SHOULD use wrapCLITool() for consistent CLI behavior
• Tool SHOULD be registered in package.json if user-facing

Anti-Patterns

• Using CWD-relative requires (./.claude/lib/...) instead of file-relative (../../lib/...)
• Swallowing errors silently in catch blocks
• Hardcoding paths that should be computed from __dirname
• Using shell: true in spawn/exec calls