cli-anything-harness-builder

Files (4)

• SKILL.md
• architecture-and-pitfalls.md · references/
• packaging.md · references/
• testing-and-verification.md · references/

SKILL.md (first lines)

# CLI-Anything Harness Builder

Turn a GUI application (or any software with no agent-friendly interface) into
a scriptable, JSON-capable CLI you can then drive with `terminal` — the same
methodology behind [CLI-Anything](https://github.com/HKUDS/CLI-Anything)'s
registry, condensed for Hermes tools (`terminal`, `read_file`/`write_file`,
`patch`, `delegate_task`) instead of the upstream doc's Claude-Code/Codex
framing. This is a bigger job than using an existing harness — expect several
turns of real engineering, not a one-shot script.

## When to Use

- The user wants Stardust to operate a specific piece of software and no
  harness for it exists yet. **Check first**: use the `cli-anything` skill's
  `cli-hub search <name>` — if a harness already exists, install and use it
  instead of rebuilding it.
- The user explicitly asks to "build a CLI for X" / "make X agent-usable."

Do not reach for this to wrap something that already has a decent CLI or a
Hermes-native tool — this is for GUI-only or no-interface software.

## The One Non-Negotiable Rule

**Call the real software. Never reimplement it.** The #1 failure mode is
building a look-alike (a Pillow-based image compositor standing in for GIMP, a
`bpy`-script generator that never actually invokes Blender) — it can't handle
real workloads and silently diverges from the real thing. The software is a
**hard runtime dependency** you shell out to via `terminal`, documented in the
harness's own README with install instructions per OS — never an optional
fallback, never a "gracefully degraded" pure-Python reimplementation.

The shape is always: **build valid project/intermediate data → hand it to the
real software via its CLI/scripting interface → verify the real output.**

| Software | Backend invocation | Native format |
|---|---|---|
| LibreOffice | `libreoffice --headless --convert-to <fmt>` | ODF (ZIP+XML) |
| Blender | `blender --background --python script.py` | `.blend` / bpy script |
| GIMP | `gimp -i -b '(script-fu-console-eval ...)'` | `.xcf` |
| Inkscape | `inkscape --actions="..." --export-filename=...` | SVG |
| Shotcut / Kdenlive | `melt project.mlt -consumer avformat:out.mp4` | MLT XML |
| Audacity | `sox` | `.aup3` |
| Browser (no CLI) | an MCP server, when one exists — see `references/architecture-and-pitfalls.md` | n/a |

## Workflow

### 1. Analyze

Find the backend engine (the library/CLI the GUI itself calls), the native
project-file format, and any command/undo system — those commands ARE your
future CLI operations. Use `terminal`/`read_file` to inspect the target
software's source (if available) or its CLI `--help`/scripting docs.

### 2. Design

- Interaction model: build **both** a stateful REPL (default, no args) and
  one-shot subcommands (scripting) — not just one.
- Command groups by domain: project (new/open/save), core operations
  (the app's actual purpose), import/export, config, session (undo/redo/status).
- Every command supports `--json` for machine output.
- Plan the state model: what persists between commands, and where.

### 3. Implement

Use `write_file`/`patch` to build, in this exact layout (PEP 420 namespace
package — `cli_anything/` itself has **no** `__init__.py`, so unrelated
harnesses can coexist in one Python environment):

```
<software>/agent-harness/
├── <SOFTWARE>.md              # your analysis notes (phase 1)
├── setup.py
└── cli_anything/
    └── <software>/
        ├── __init__.py
        ├── __main__.py
        ├── README.md           # install + run instructions — required
        ├── <software>_cli.py   # Click entry point; REPL when no subcommand
        ├── core/               # one module per domain, e.g. project.py, export.py, session.py
        ├── utils/
        │   └── <software>_backend.py   # the ONLY module that shells out to the real software
        └── tests/
            ├── TEST.md         # test plan, then results — required
            ├── test_core.py
            └── test_full_e2e.py
```

Read `references/architecture-and-pitfalls.md` before writing `export.py` or
any rendering path — the "rendering gap" (effects silently dropped because the
renderer you picked ignores project-level filters) is the #2 failure mode.

### 4–5. Test (plan first, then implement)

Write `tests/TEST.md` as a plan **before** any test code: which modules,
which edge cases, which realistic multi-step workflows (e.g. "podcast
production," "YouTube-style cut/trim") will be simulated, and what output
properties get verified. Then implement against that plan.

Read `references/testing-and-verification.md` before writing `test_full_e2e.py`
— this is the layer that actually invokes the real software and is the one
projects most often skip or fake. **No graceful degradation**: if the real
software isn't installed, tests fail, they don't skip.

Append real `pytest -v` results to `TEST.md` once everything passes.

### 6. Give the harness its own skill

Generate a `SKILL.md` for the finished harness (frontmatter `name`/
`description`, then install prerequisites, command groups, `--json` usage,
realistic examples) so Stardust — or any other agent — can discover and drive
it later without re-reading your source. This is a skill for the *harness*,
separate from this builder skill.

### 7. Package it

Read `references/packaging.md` for the exact `setup.py` namespace-package
template and verification steps (`pip install -e .`, then run the test suite
against the **installed** command, not a module fallback).

From 9529360-cpu/stardust-hermes, MIT.

More from 9529360-cpu/stardust-hermes