/refine

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