tool-updater

name	tool-updater
description	Research-backed CLI tool refresh workflow for updating existing tools with TDD checkpoints and CLI invocation validation.
version	1.0.0
model	sonnet
invoked_by	both
user_invocable	true
tools	["Read","Write","Edit","Glob","Grep","Bash","Skill","MemoryRecord"]
args	--tool <name-or-path> [--trigger reflection|evolve|manual|stale] [--mode plan|execute]
error_handling	graceful
streaming	supported
verified	true
lastVerifiedAt	2026-04-07
dependencies	["research-synthesis"]
category	framework-management
tags	["tools","cli","updater","maintenance","framework"]
aliases	["update-tool","refresh-tool"]
source	builtin
trust_score	100
provenance_sha	414c640407561b93

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