cli-anything:refine Command

Refine an existing CLI harness to improve coverage of the software's functions and usage patterns.

CRITICAL: Read HARNESS.md First

Before refining, read ./HARNESS.md. All new commands and tests must follow the same standards as the original build. HARNESS.md is the single source of truth for architecture, patterns, and quality requirements.

Usage

/cli-anything:refine <software-path> [focus]

Arguments

• <software-path> - Required. Local path to the software source code (e.g., /home/user/gimp, ./blender). Must be the same source tree used during the original build.

  Note: Only local paths are accepted. If you need to work from a GitHub repo, clone it first with /cli-anything, then refine.

• [focus] - Optional. A natural-language description of the functionality area to focus on. When provided, the agent skips broad gap analysis and instead targets the specified capability area.

  Examples:

  • /cli-anything:refine /home/user/shotcut "vid-in-vid and picture-in-picture features"
  • /cli-anything:refine /home/user/gimp "all batch processing and scripting filters"
  • /cli-anything:refine /home/user/blender "particle systems and physics simulation"
  • /cli-anything:refine /home/user/inkscape "path boolean operations and clipping"

  When [focus] is provided:

  • Step 2 (Analyze Software Capabilities) narrows to only the specified area
  • Step 3 (Gap Analysis) compares only the focused capabilities against current coverage
  • The agent should still present findings before implementing, but scoped to the focus area

What This Command Does

This command is used after a CLI harness has already been built with /cli-anything. It analyzes gaps between the software's full capabilities and what the current CLI covers, then iteratively expands coverage. If a [focus] is given, the agent narrows its analysis and implementation to that specific functionality area.

Step 1: Inventory Current Coverage

• Read the existing CLI entry point (<software>_cli.py) and all core modules
• List every command, subcommand, and option currently implemented
• Read the existing test suite to understand what's tested
• Build a coverage map: { function_name: covered | not_covered }

Step 2: Analyze Software Capabilities

• Re-scan the software source at <software-path>
• Identify all public APIs, CLI tools, scripting interfaces, and batch-mode operations
• Focus on functions that produce observable output (renders, exports, transforms, conversions)
• Categorize by domain (e.g., for GIMP: filters, color adjustments, layer ops, selection tools)

Step 3: Gap Analysis

• Compare current CLI coverage against the software's full capability set
• Prioritize gaps by:
  1. High impact — commonly used functions missing from the CLI
  2. Easy wins — functions with simple APIs that can be wrapped quickly
  3. Composability — functions that unlock new workflows when combined with existing commands
• Present the gap report to the user and confirm which gaps to address

Step 4: Implement New Commands

• Add new commands/subcommands to the CLI for the selected gaps
• Follow the same patterns as existing commands (as defined in HARNESS.md):
  • Click command groups
  • --json output support
  • Session state integration
  • Error handling with handle_error
• Add corresponding core module functions in core/ or utils/

Step 5: Expand Tests

• Add unit tests for every new function in test_core.py
• Add E2E tests for new commands in test_full_e2e.py
• Add workflow tests that combine new commands with existing ones
• Run all tests (old + new) to ensure no regressions

Step 6: Update Documentation

• Update README.md with new commands and usage examples
• Update TEST.md with new test results
• Update the SOP document (<SOFTWARE>.md) with new coverage notes

Example

# Broad refinement — agent finds gaps across all capabilities
/cli-anything:refine /home/user/gimp

# Focused refinement — agent targets a specific functionality area
/cli-anything:refine /home/user/shotcut "vid-in-vid and picture-in-picture compositing"
/cli-anything:refine /home/user/gimp "batch processing and Script-Fu filters"
/cli-anything:refine /home/user/blender "particle systems and physics simulation"
/cli-anything:refine /home/user/inkscape "path boolean operations and clipping masks"

Success Criteria

• All existing tests still pass (no regressions)
• New commands follow the same architectural patterns (per HARNESS.md)
• New tests achieve 100% pass rate
• Coverage meaningfully improved (new functions exposed via CLI)
• Documentation updated to reflect changes

Notes

• Refine is incremental — run it multiple times to steadily expand coverage
• Each run should focus on a coherent set of related functions rather than trying to cover everything at once
• The agent should present the gap analysis before implementing, so the user can steer priorities
• Refine never removes existing commands — it only adds or enhances