chore: import upstream snapshot with attribution

codex-skill/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: cli-anything
+description: Use when the user wants Codex to build, refine, test, validate, or list CLI-Anything harnesses for GUI applications or source repositories. Adapts the full CLI-Anything methodology to Codex without changing the generated Python harness format.
+---
+
+# CLI-Anything for Codex
+
+Use this skill when the user wants Codex to act like the `CLI-Anything` builder.
+
+## Read the Full Methodology First
+
+Before implementation, use the full methodology source of truth:
+
+1. Read `references/HARNESS.md` relative to this skill directory.
+2. Read the matching mode specification under `references/commands/`.
+3. Read referenced files under `references/guides/` only when they apply to the target.
+4. If the installed resources are unavailable and this skill is being used from a
+   `CLI-Anything` repository checkout, read `../cli-anything-plugin/HARNESS.md` and
+   the resources around it.
+5. If neither local source is available, clone or download
+   `https://github.com/HKUDS/CLI-Anything` and use `cli-anything-plugin/HARNESS.md`.
+6. Only if all full-methodology sources are unavailable, follow the condensed rules below.
+
+The installer vendors the canonical resources from `cli-anything-plugin/` into this
+skill so a normal Codex installation is self-contained.
+
+## Resource Map
+
+| Path | Purpose |
+|------|---------|
+| `references/HARNESS.md` | Complete methodology and quality rules |
+| `references/commands/cli-anything.md` | Build-mode specification |
+| `references/commands/refine.md` | Refine-mode specification |
+| `references/commands/test.md` | Test-mode specification |
+| `references/commands/validate.md` | Validation checklist |
+| `references/commands/list.md` | Installed/generated harness discovery |
+| `references/guides/` | On-demand implementation guidance |
+| `scripts/repl_skin.py` | Copy into generated harnesses as `utils/repl_skin.py` |
+| `scripts/preview_bundle.py` | Copy into preview-capable harnesses as `utils/preview_bundle.py` |
+| `scripts/skill_generator.py` | Generate canonical and packaged CLI skills |
+| `scripts/templates/SKILL.md.template` | Skill generation template used by `skill_generator.py` |
+| `references/docs/PREVIEW_PROTOCOL.md` | Shared preview bundle protocol |
+
+When reading vendored documents, apply these path remappings instead of resolving
+plugin paths against the current working directory:
+
+| Document reference | Installed skill path |
+|--------------------|----------------------|
+| `guides/...` | `references/guides/...` |
+| `cli-anything-plugin/repl_skin.py` | `scripts/repl_skin.py` |
+| `cli-anything-plugin/preview_bundle.py` | `scripts/preview_bundle.py` |
+| `cli-anything-plugin/skill_generator.py` | `scripts/skill_generator.py` |
+| `templates/SKILL.md.template` | `scripts/templates/SKILL.md.template` |
+| `docs/PREVIEW_PROTOCOL.md` | `references/docs/PREVIEW_PROTOCOL.md` |
+
+## Inputs
+
+Accept either:
+
+- A local source path such as `./gimp` or `/path/to/software`
+- A GitHub repository URL
+
+Derive the software name from the local directory name after cloning if needed.
+
+## Modes
+
+### Build
+
+Read `references/commands/cli-anything.md`. Build a complete harness through source
+analysis, architecture design, implementation, test planning, test implementation,
+test documentation, CLI-specific `SKILL.md` generation, and local installation.
+
+### Refine
+
+Read `references/commands/refine.md`. Inventory current commands and tests, compare
+them against the target software, then incrementally add high-impact capabilities
+without removing existing commands unless the user requests a breaking change.
+
+### Test
+
+Read `references/commands/test.md`. Run the harness tests against the real backend,
+verify installed-command subprocess coverage, and update `TEST.md` only with passing
+results.
+
+### Validate
+
+Read `references/commands/validate.md`. Validate the harness against the complete
+directory, implementation, test, documentation, packaging, and code-quality checklist.
+
+### List
+
+Read `references/commands/list.md`. Discover installed and generated CLI-Anything tools
+and support human-readable or JSON output as requested.
+
+## Condensed Fallback Rules
+
+Use these only when the full methodology cannot be retrieved.
+
+### Harness Structure
+
+Produce:
+
+```text
+<software>/
+└── agent-harness/
+    ├── <SOFTWARE>.md
+    ├── setup.py
+    └── cli_anything/
+        └── <software>/
+            ├── README.md
+            ├── __init__.py
+            ├── __main__.py
+            ├── <software>_cli.py
+            ├── core/
+            ├── utils/
+            └── tests/
+```
+
+### Required Behavior
+
+- Prefer the real software backend over reimplementation.
+- Provide one-shot Click subcommands and default REPL mode.
+- Support `--json` machine-readable output.
+- Add session state with undo/redo where the target supports it.
+- Auto-save one-shot session mutations and support `--dry-run`.
+- Use locked session-file writes to avoid concurrent JSON corruption.
+- Copy and use the unified `ReplSkin`.
+- Add truthful preview commands for software with meaningful visual or inspection state.
+- Generate both canonical and packaged CLI-specific `SKILL.md` files.
+
+### Testing
+
+- Write `TEST.md` before test code.
+- Keep `test_core.py` for unit coverage.
+- Keep `test_full_e2e.py` for real-file workflows and real backend validation.
+- Verify rendered/exported output programmatically, not only process exit codes.
+- Test the installed `cli-anything-<software>` command via `_resolve_cli()`.
+- Run release validation with `CLI_ANYTHING_FORCE_INSTALLED=1`.
+
+### Packaging
+
+- Use `find_namespace_packages(include=["cli_anything.*"])`.
+- Keep `cli_anything/` as a namespace package without a top-level `__init__.py`.
+- Expose `cli-anything-<software>` through `console_scripts`.
+- Include the packaged CLI-specific `skills/SKILL.md`.
+
+## Output Expectations
+
+When reporting progress or final results, include:
+
+- target software and source path
+- files added or changed
+- validation commands run
+- open risks or backend limitations

codex-skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CLI-Anything"
+  short_description: "Build, refine, test, validate, or list harnesses."
+  default_prompt: "Use $cli-anything to build, refine, test, validate, or list harnesses for the user's target software or source repository."

codex-skill/scripts/install.ps1

@@ -0,0 +1,67 @@
+$ErrorActionPreference = "Stop"
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$skillDir = Split-Path -Parent $scriptDir
+$repoRoot = Split-Path -Parent $skillDir
+$pluginDir = Join-Path $repoRoot "cli-anything-plugin"
+$previewProtocol = Join-Path $repoRoot "docs/PREVIEW_PROTOCOL.md"
+
+$codexHome = if ($env:CODEX_HOME) {
+    $env:CODEX_HOME
+} elseif ($env:USERPROFILE) {
+    Join-Path $env:USERPROFILE ".codex"
+} else {
+    throw "CODEX_HOME is not set and USERPROFILE is unavailable."
+}
+
+$destRoot = Join-Path $codexHome "skills"
+$destDir = Join-Path $destRoot "cli-anything"
+$stagingDir = $null
+
+if (-not (Test-Path (Join-Path $pluginDir "HARNESS.md"))) {
+    throw "Cannot find canonical CLI-Anything resources at: $pluginDir`nRun this installer from a full CLI-Anything repository checkout."
+}
+
+if (-not (Test-Path $previewProtocol)) {
+    throw "Cannot find preview protocol at: $previewProtocol`nRun this installer from a full CLI-Anything repository checkout."
+}
+
+New-Item -ItemType Directory -Path $destRoot -Force | Out-Null
+
+if (Test-Path $destDir) {
+    throw "Refusing to overwrite existing skill: $destDir`nRemove it manually if you want to reinstall."
+}
+
+try {
+    $stagingDir = Join-Path $destRoot (".cli-anything.tmp." + [System.Guid]::NewGuid().ToString("N"))
+    New-Item -ItemType Directory -Path $stagingDir | Out-Null
+    Get-ChildItem -LiteralPath $skillDir -Force | Copy-Item -Destination $stagingDir -Recurse -Force
+
+    $referenceDir = Join-Path $stagingDir "references"
+    $referenceCommands = Join-Path $referenceDir "commands"
+    $referenceDocs = Join-Path $referenceDir "docs"
+    $referenceGuides = Join-Path $referenceDir "guides"
+    $resourceScripts = Join-Path $stagingDir "scripts"
+    $scriptTemplates = Join-Path $resourceScripts "templates"
+
+    New-Item -ItemType Directory -Path $referenceCommands, $referenceDocs, $referenceGuides, $scriptTemplates -Force | Out-Null
+
+    Copy-Item -Path (Join-Path $pluginDir "HARNESS.md") -Destination (Join-Path $referenceDir "HARNESS.md")
+    Copy-Item -Path (Join-Path $pluginDir "commands/*.md") -Destination $referenceCommands
+    Copy-Item -Path (Join-Path $pluginDir "guides/*.md") -Destination $referenceGuides
+    Copy-Item -Path (Join-Path $pluginDir "repl_skin.py") -Destination (Join-Path $resourceScripts "repl_skin.py")
+    Copy-Item -Path (Join-Path $pluginDir "preview_bundle.py") -Destination (Join-Path $resourceScripts "preview_bundle.py")
+    Copy-Item -Path (Join-Path $pluginDir "skill_generator.py") -Destination (Join-Path $resourceScripts "skill_generator.py")
+    Copy-Item -Path (Join-Path $pluginDir "templates/*") -Destination $scriptTemplates
+    Copy-Item -Path $previewProtocol -Destination (Join-Path $referenceDocs "PREVIEW_PROTOCOL.md")
+
+    Move-Item -Path $stagingDir -Destination $destDir
+} finally {
+    if ($stagingDir -and (Test-Path $stagingDir)) {
+        Remove-Item -Path $stagingDir -Recurse -Force
+    }
+}
+
+Write-Host "Installed Codex skill to: $destDir"
+Write-Host "Vendored CLI-Anything methodology resources into the installed skill."
+Write-Host "Restart Codex to pick up the new skill."

codex-skill/scripts/install.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+REPO_ROOT="$(cd "${SKILL_DIR}/.." && pwd)"
+PLUGIN_DIR="${REPO_ROOT}/cli-anything-plugin"
+PREVIEW_PROTOCOL="${REPO_ROOT}/docs/PREVIEW_PROTOCOL.md"
+DEST_ROOT="${CODEX_HOME:-$HOME/.codex}/skills"
+DEST_DIR="${DEST_ROOT}/cli-anything"
+STAGING_DIR=""
+
+if [[ ! -f "${PLUGIN_DIR}/HARNESS.md" ]]; then
+  echo "Cannot find canonical CLI-Anything resources at: ${PLUGIN_DIR}" >&2
+  echo "Run this installer from a full CLI-Anything repository checkout." >&2
+  exit 1
+fi
+
+if [[ ! -f "${PREVIEW_PROTOCOL}" ]]; then
+  echo "Cannot find preview protocol at: ${PREVIEW_PROTOCOL}" >&2
+  echo "Run this installer from a full CLI-Anything repository checkout." >&2
+  exit 1
+fi
+
+mkdir -p "${DEST_ROOT}"
+
+if [[ -e "${DEST_DIR}" ]]; then
+  echo "Refusing to overwrite existing skill: ${DEST_DIR}" >&2
+  echo "Remove it manually if you want to reinstall." >&2
+  exit 1
+fi
+
+cleanup() {
+  if [[ -n "${STAGING_DIR}" && -d "${STAGING_DIR}" ]]; then
+    rm -rf "${STAGING_DIR}"
+  fi
+}
+trap cleanup EXIT
+
+STAGING_DIR="$(mktemp -d "${DEST_ROOT}/.cli-anything.tmp.XXXXXX")"
+cp -R "${SKILL_DIR}/." "${STAGING_DIR}/"
+mkdir -p \
+  "${STAGING_DIR}/references/commands" \
+  "${STAGING_DIR}/references/docs" \
+  "${STAGING_DIR}/references/guides" \
+  "${STAGING_DIR}/scripts/templates"
+
+cp "${PLUGIN_DIR}/HARNESS.md" "${STAGING_DIR}/references/HARNESS.md"
+cp "${PLUGIN_DIR}/commands/"*.md "${STAGING_DIR}/references/commands/"
+cp "${PLUGIN_DIR}/guides/"*.md "${STAGING_DIR}/references/guides/"
+cp "${PLUGIN_DIR}/repl_skin.py" "${STAGING_DIR}/scripts/repl_skin.py"
+cp "${PLUGIN_DIR}/preview_bundle.py" "${STAGING_DIR}/scripts/preview_bundle.py"
+cp "${PLUGIN_DIR}/skill_generator.py" "${STAGING_DIR}/scripts/skill_generator.py"
+cp "${PLUGIN_DIR}/templates/"* "${STAGING_DIR}/scripts/templates/"
+cp "${PREVIEW_PROTOCOL}" "${STAGING_DIR}/references/docs/PREVIEW_PROTOCOL.md"
+
+mv "${STAGING_DIR}" "${DEST_DIR}"
+
+echo "Installed Codex skill to: ${DEST_DIR}"
+echo "Vendored CLI-Anything methodology resources into the installed skill."
+echo "Restart Codex to pick up the new skill."

codex-skill/tests/test_install.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+REPO_ROOT="$(cd "${SKILL_DIR}/.." && pwd)"
+PLUGIN_DIR="${REPO_ROOT}/cli-anything-plugin"
+TMP_DIR="$(mktemp -d)"
+CODEX_HOME="${TMP_DIR}/codex-home"
+INSTALLED_DIR="${CODEX_HOME}/skills/cli-anything"
+STALE_STAGING_DIR="${CODEX_HOME}/skills/.cli-anything.tmp.stale"
+
+cleanup() {
+  rm -rf "${TMP_DIR}"
+}
+trap cleanup EXIT
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+assert_file() {
+  [[ -f "$1" ]] || fail "expected file: $1"
+}
+
+assert_same() {
+  cmp -s "$1" "$2" || fail "files differ: $1 $2"
+}
+
+assert_tree_same() {
+  diff -qr "$1" "$2" >/dev/null || fail "directories differ: $1 $2"
+}
+
+mkdir -p "${STALE_STAGING_DIR}/codex-skill"
+echo "left over from an interrupted install" > "${STALE_STAGING_DIR}/codex-skill/stale.txt"
+
+CODEX_HOME="${CODEX_HOME}" bash "${SKILL_DIR}/scripts/install.sh"
+
+assert_file "${INSTALLED_DIR}/SKILL.md"
+[[ -d "${STALE_STAGING_DIR}" ]] ||
+  fail "installer reused or removed the stale staging directory"
+[[ ! -d "${INSTALLED_DIR}/codex-skill" ]] ||
+  fail "installer created a nested codex-skill directory"
+assert_file "${INSTALLED_DIR}/references/HARNESS.md"
+assert_file "${INSTALLED_DIR}/references/commands/cli-anything.md"
+assert_file "${INSTALLED_DIR}/references/commands/refine.md"
+assert_file "${INSTALLED_DIR}/references/commands/test.md"
+assert_file "${INSTALLED_DIR}/references/commands/validate.md"
+assert_file "${INSTALLED_DIR}/references/commands/list.md"
+assert_file "${INSTALLED_DIR}/references/guides/auto-save-dry-run.md"
+assert_file "${INSTALLED_DIR}/references/guides/session-locking.md"
+assert_file "${INSTALLED_DIR}/references/guides/preview-methodology.md"
+assert_file "${INSTALLED_DIR}/scripts/repl_skin.py"
+assert_file "${INSTALLED_DIR}/scripts/preview_bundle.py"
+assert_file "${INSTALLED_DIR}/scripts/skill_generator.py"
+assert_file "${INSTALLED_DIR}/scripts/templates/SKILL.md.template"
+assert_file "${INSTALLED_DIR}/references/docs/PREVIEW_PROTOCOL.md"
+
+assert_same "${PLUGIN_DIR}/HARNESS.md" "${INSTALLED_DIR}/references/HARNESS.md"
+assert_same "${PLUGIN_DIR}/repl_skin.py" "${INSTALLED_DIR}/scripts/repl_skin.py"
+assert_same "${PLUGIN_DIR}/preview_bundle.py" "${INSTALLED_DIR}/scripts/preview_bundle.py"
+assert_same "${PLUGIN_DIR}/skill_generator.py" "${INSTALLED_DIR}/scripts/skill_generator.py"
+assert_same "${REPO_ROOT}/docs/PREVIEW_PROTOCOL.md" "${INSTALLED_DIR}/references/docs/PREVIEW_PROTOCOL.md"
+assert_tree_same "${PLUGIN_DIR}/commands" "${INSTALLED_DIR}/references/commands"
+assert_tree_same "${PLUGIN_DIR}/guides" "${INSTALLED_DIR}/references/guides"
+assert_tree_same "${PLUGIN_DIR}/templates" "${INSTALLED_DIR}/scripts/templates"
+
+python3 -m py_compile \
+  "${INSTALLED_DIR}/scripts/repl_skin.py" \
+  "${INSTALLED_DIR}/scripts/preview_bundle.py" \
+  "${INSTALLED_DIR}/scripts/skill_generator.py"
+
+if CODEX_HOME="${CODEX_HOME}" bash "${SKILL_DIR}/scripts/install.sh" >/dev/null 2>&1; then
+  fail "installer overwrote an existing skill"
+fi
+
+grep -q 'references/HARNESS.md' "${INSTALLED_DIR}/SKILL.md" ||
+  fail "installed SKILL.md does not point to vendored HARNESS.md"
+
+DETACHED_ROOT="${TMP_DIR}/detached"
+DETACHED_LOG="${TMP_DIR}/detached-install.log"
+mkdir -p "${DETACHED_ROOT}"
+cp -R "${SKILL_DIR}" "${DETACHED_ROOT}/codex-skill"
+if CODEX_HOME="${TMP_DIR}/detached-home" bash "${DETACHED_ROOT}/codex-skill/scripts/install.sh" >"${DETACHED_LOG}" 2>&1; then
+  fail "installer accepted a detached skill without canonical resources"
+fi
+grep -q 'Cannot find canonical CLI-Anything resources' "${DETACHED_LOG}" ||
+  fail "detached install did not explain the missing canonical resources"
+
+echo "PASS: Codex skill installer vendors the complete CLI-Anything resource set."