HKUDS · mxyhi · Mar 11, 2026
diff --git a/.agents/skills/cli-anything/SKILL.md b/.agents/skills/cli-anything/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: cli-anything
+description: Build, refine, test, validate, or inventory agent-usable CLI harnesses for software codebases with the CLI-Anything methodology. Use this skill when a request involves turning a GUI app, desktop tool, web service SDK, or existing codebase into a stateful CLI under agent-harness/, or when extending an existing cli-anything-* harness.
+---
+
+# CLI-Anything
+
+## Overview
+
+Use this skill when your agent runtime supports local skills and you want to apply the CLI-Anything methodology without relying on slash-command plugins. It complements the existing plugin flow and uses the same source of truth: [`references/HARNESS.md`](references/HARNESS.md).
+
+## Core Workflow
+
+1. Choose the task mode first:
+   - Build a new harness from a source tree or repository: [`references/commands/cli-anything.md`](references/commands/cli-anything.md)
+   - Expand coverage of an existing harness: [`references/commands/refine.md`](references/commands/refine.md)
+   - Run or update tests for an existing harness: [`references/commands/test.md`](references/commands/test.md)
+   - Validate an implementation against the standard: [`references/commands/validate.md`](references/commands/validate.md)
+   - Inventory generated or installed harnesses: [`references/commands/list.md`](references/commands/list.md)
+2. Read [`references/HARNESS.md`](references/HARNESS.md) before changing code. It defines the architecture, testing, packaging, and backend integration rules.
+3. Preserve the generated layout `<software>/agent-harness/cli_anything/<software>/...` and package name `cli-anything-<software>`.
+4. Use the real software backend for rendering and export. Do not replace the target application with toy Python reimplementations.
+5. Reuse existing harnesses in this repository as examples before inventing a new structure.
+
+## Repository Examples
+
+- `anygen/agent-harness/` for cloud API backed workflows.
+- `gimp/agent-harness/`, `blender/agent-harness/`, and `inkscape/agent-harness/` for GUI-to-CLI mappings.
+- `libreoffice/agent-harness/` for document generation and real headless export.
+- `cli-anything-plugin/repl_skin.py` as the shared REPL presentation layer that generated harnesses can copy into `utils/repl_skin.py`.
+
+## Notes
+
+- The repository supports both the original plugin flow and the repo-local skill flow.
+- Do not assume slash commands such as `/cli-anything` exist in the current runtime. Translate the command references into normal agent execution steps.
+- If the request is only about using an already-generated CLI, prefer the installed `cli-anything-<software>` command instead of regenerating the harness.
diff --git a/.agents/skills/cli-anything/agents/openai.yaml b/.agents/skills/cli-anything/agents/openai.yaml
@@ -0,0 +1,3 @@
+interface:
+  display_name: "CLI Anything"
+  short_description: "Turn software codebases into agent-usable CLIs"
diff --git a/.agents/skills/cli-anything/references/HARNESS.md b/.agents/skills/cli-anything/references/HARNESS.md
diff --git a/.agents/skills/cli-anything/references/commands/cli-anything.md b/.agents/skills/cli-anything/references/commands/cli-anything.md
@@ -0,0 +1,126 @@
+# cli-anything Command
+
+> Historical slash-command spec. In skill mode, follow the same workflow without requiring `/cli-anything` command support.
+
+Build a complete, stateful CLI harness for any GUI application.
+
+## CRITICAL: Read HARNESS.md First
+
+**Before doing anything else, you MUST read `../HARNESS.md`.** It defines the complete methodology, architecture standards, and implementation patterns. Every phase below follows HARNESS.md. Do not improvise — follow the harness specification.
+
+## Usage
+
+```bash
+/cli-anything <software-path-or-repo>
+```
+
+## Arguments
+
+- `<software-path-or-repo>` - **Required.** Either:
+  - A **local path** to the software source code (e.g., `/home/user/gimp`, `./blender`)
+  - A **GitHub repository URL** (e.g., `https://github.com/GNOME/gimp`, `github.com/blender/blender`)
+
+  If a GitHub URL is provided, the agent clones the repo locally first, then works on the local copy.
+
+  **Note:** Software names alone (e.g., "gimp") are NOT accepted. You must provide the actual source code path or repository URL so the agent can analyze the codebase.
+
+## What This Command Does
+
+This command implements the complete cli-anything methodology to build a production-ready CLI harness for any GUI application. **All phases follow the standards defined in HARNESS.md.**
+
+### Phase 0: Source Acquisition
+- If `<software-path-or-repo>` is a GitHub URL, clone it to a local working directory
+- Verify the local path exists and contains source code
+- Derive the software name from the directory name (e.g., `/home/user/gimp` -> `gimp`)
+
+### Phase 1: Codebase Analysis
+- Analyzes the local source code
+- Analyzes the backend engine and data model
+- Maps GUI actions to API calls
+- Identifies existing CLI tools
+- Documents the architecture
+
+### Phase 2: CLI Architecture Design
+- Designs command groups matching the app's domains
+- Plans the state model and output formats
+- Creates the software-specific SOP document (e.g., GIMP.md)
+
+### Phase 3: Implementation
+- Creates the directory structure: `agent-harness/cli_anything/<software>/core`, `utils`, `tests`
+- Implements core modules (project, session, export, etc.)
+- Builds the Click-based CLI with REPL support
+- Implements `--json` output mode for agent consumption
+- All imports use `cli_anything.<software>.*` namespace
+
+### Phase 4: Test Planning
+- Creates `TEST.md` with comprehensive test plan
+- Plans unit tests for all core modules
+- Plans E2E tests with real files
+- Designs realistic workflow scenarios
+
+### Phase 5: Test Implementation
+- Writes unit tests (`test_core.py`) - synthetic data, no external deps
+- Writes E2E tests (`test_full_e2e.py`) - real files, full pipeline
+- Implements workflow tests simulating real-world usage
+- Adds output verification (pixel analysis, format validation, etc.)
+- Adds `TestCLISubprocess` class with `_resolve_cli("cli-anything-<software>")`
+  that tests the installed command via subprocess (no hardcoded paths or CWD)
+
+### Phase 6: Test Documentation
+- Runs all tests with `pytest -v --tb=no`
+- Appends full test results to `TEST.md`
+- Documents test coverage and any gaps
+
+### Phase 7: PyPI Publishing and Installation
+- Creates `setup.py` with `find_namespace_packages(include=["cli_anything.*"])`
+- Package name: `cli-anything-<software>`, namespace: `cli_anything.<software>`
+- `cli_anything/` has NO `__init__.py` (PEP 420 namespace package)
+- Configures console_scripts entry point for PATH installation
+- Tests local installation with `pip install -e .`
+- Verifies CLI is available in PATH: `which cli-anything-<software>`
+
+## Output Structure
+
+```
+<software-name>/
+└── agent-harness/
+    ├── <SOFTWARE>.md          # Software-specific SOP
+    ├── setup.py               # PyPI package config (find_namespace_packages)
+    └── cli_anything/          # Namespace package (NO __init__.py)
+        └── <software>/        # Sub-package (HAS __init__.py)
+            ├── README.md          # Installation and usage guide
+            ├── <software>_cli.py  # Main CLI entry point
+            ├── core/              # Core modules
+            │   ├── project.py
+            │   ├── session.py
+            │   ├── export.py
+            │   └── ...
+            ├── utils/             # Utilities
+            └── tests/
+                ├── TEST.md        # Test plan and results
+                ├── test_core.py   # Unit tests
+                └── test_full_e2e.py # E2E tests
+```
+
+## Example
+
+```bash
+# Build a CLI for GIMP from local source
+/cli-anything /home/user/gimp
+
+# Build from a GitHub repo
+/cli-anything https://github.com/blender/blender
+```
+
+## Success Criteria
+
+The command succeeds when:
+1. All core modules are implemented and functional
+2. CLI supports both one-shot commands and REPL mode
+3. `--json` output mode works for all commands
+4. All tests pass (100% pass rate)
+5. Subprocess tests use `_resolve_cli()` and pass with `CLI_ANYTHING_FORCE_INSTALLED=1`
+6. TEST.md contains both plan and results
+7. README.md documents installation and usage
+8. setup.py is created and local installation works
+9. CLI is available in PATH as `cli-anything-<software>`