feat: support additional agent harnesses

ARCHITECTURE.md

@@ -26,7 +26,7 @@ Current capabilities:
 * Local and cached `origin` branch inventory with explicit refresh, tracking, divergence, and provider-enriched single-branch safety inspection
 * Guarded branch publication and local/origin creation, renaming, and deletion, including safe checkout transitions for checked-out branch deletion
 * Read-only, bounded branch cleanup candidates with documented reachability rules
-* Agent guidance installation and removal for Codex, Claude Code, Pi, OpenCode, GitHub Copilot, and Gemini CLI; installation detects configured harnesses and preserves managed-content ownership
+* Agent skill installation and removal for Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw; installation detects configured harnesses and tracks skill-content ownership to preserve user changes
 * Build identity reporting
 * Versioned command capability inventory, including explicit unavailable features
 

DESIGN.md

@@ -579,9 +579,15 @@ Uninstall uses those recorded paths and retains destinations still shared by
 another configured harness. `gha agent list` reports the recorded harnesses,
 destinations, and current file presence without claiming to detect agents GHA
 has not configured. Codex, Claude Code, Pi, OpenCode, GitHub Copilot, and Gemini
-CLI are supported; the latter four share a globally discoverable skills path.
-Cursor remains deferred until a safe global discovery path exists. Installation
-detects configured supported harnesses from their setup directories, offers
+CLI, Cursor, Hermes Agent, and OpenClaw are supported. Pi, OpenCode, Copilot,
+and Gemini share a globally discoverable skills path. Cursor, Hermes, and
+OpenClaw use their documented global roots; Hermes honors `HERMES_HOME` and
+OpenClaw honors `OPENCLAW_STATE_DIR`. Skill ownership digests prevent GHA from
+overwriting unowned skills and let update and uninstall preserve user-modified
+content. See the [harness documentation](docs/command-guide.md#agent-guidance-installation)
+and [roadmap](docs/roadmap.md).
+Installation detects configured supported harnesses from their setup
+directories, offers
 `--binary-only`, and reports when none are found; detection does not depend on
 harness executables. Skill discovery paths have been checked against current
 harness documentation. `gha update` now

PROJECT_SUMMARY.md

@@ -19,7 +19,7 @@ context, safety, or workflow value beyond a raw provider invocation.
 - Guarded release-tag publication with commit, origin, CI, and workflow preflight
 - Offline local repository analysis
 - Guarded local and origin branch lifecycle operations, including publication and safe checked-out-branch deletion
-- Agent guidance installation and removal for Codex, Claude Code, Pi, OpenCode, GitHub Copilot, and Gemini CLI; setup detects configured harnesses and supports binary-only installation
+- Agent skill installation and removal for Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw; setup detects configured harnesses, preserves modified skills, and supports binary-only installation
 - Installed build identity reporting
 - Versioned capability inventory and structured diagnostics for automation
 
@@ -64,7 +64,7 @@ context, safety, or workflow value beyond a raw provider invocation.
 10. **Human-readable parity** - Render the same domain result clearly for terminal users
 
 ## Current Commands
-- `gha agent install|uninstall` - Safely manage bundled GHA skills and guidance for six supported harnesses; install detects configured harnesses by default
+- `gha agent install|uninstall` - Safely manage bundled GHA skills and guidance for nine supported harnesses; install detects configured harnesses by default
 - `gha version` and `gha capabilities` - Identify the installed build and enumerate its versioned command surface
 - `gha pr prepare|create` - Preflight and create a pull request unless `--dry-run` is set
 - `gha prs` and `gha review <number>` - Bounded PR discovery and decision-ready single-PR inspection

README.md

@@ -31,14 +31,14 @@ GHA bundles a portable `gha` skill that helps coding agents use its structured G
 gha agent install
 ```
 
-The command detects configured Codex, Claude Code, Pi, OpenCode, GitHub Copilot, and Gemini CLI setup directories and configures those harnesses without requiring their executables. Use `--agent` with comma-separated names to choose explicitly, or `--binary-only` to skip harness setup. If none are detected, GHA reports how to configure one later. It copies the bundled skill into a discoverable global skill directory and idempotently adds a marked GHA guidance block where a documented global instruction file exists. `gha agent list` shows recorded harnesses and current file presence.
+The command detects configured Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw setup directories and configures those harnesses without requiring their executables. Use `--agent` with comma-separated names to choose explicitly, or `--binary-only` to skip harness setup. If none are detected, GHA reports how to configure one later. It copies the bundled skill into a discoverable global skill directory and idempotently adds a marked GHA guidance block where a documented global instruction file exists. Existing skills are not overwritten, and modified GHA skills are preserved by update and uninstall. `gha agent list` shows recorded harnesses and current file presence.
 
 ```bash
 # Preview paths without writing files.
 gha agent install --agent codex,claude --dry-run
 
-# Preview setup for Pi, OpenCode, Copilot, and Gemini CLI.
-gha agent install --agent pi,opencode,copilot,gemini --dry-run
+# Preview setup for Pi, OpenCode, Copilot, Gemini CLI, Cursor, Hermes, and OpenClaw.
+gha agent install --agent pi,opencode,copilot,gemini,cursor,hermes,openclaw --dry-run
 
 # Remove GHA's managed guidance block and its installed skill.
 gha agent uninstall --agent codex --dry-run

docs/command-guide.md

@@ -56,7 +56,7 @@ gha version --format json
 
 `gha agent list` reports harnesses recorded by `gha agent install`, the exact
 instruction and skill destinations GHA manages, and whether each file is
-present, missing, or unavailable. An empty list means no harnesses are recorded by GHA; it
+present, modified, missing, or unavailable. An empty list means no harnesses are recorded by GHA; it
 does not search the machine for manually configured or installed agents.
 Structured output is available with `--format json` or `--format yaml`.
 
@@ -66,25 +66,32 @@ gha agent list --format json
 ```
 
 `gha agent install` detects configured supported harnesses and copies the skill bundled with the installed GHA binary to
-Codex, Claude Code, Pi, OpenCode, GitHub Copilot, or Gemini CLI. It adds a
+Codex, Claude Code, Pi, OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes
+Agent, or OpenClaw. It adds a
 clearly marked GHA section to the selected global instruction file where the
 harness supports a documented global file. Copilot uses its shared skill
 directory without a separate global instructions file. Existing instruction
 content is preserved; rerunning the command refreshes the skill without
 duplicating the managed section. Installation records configured harnesses and their exact
 destinations in the user's GHA config directory (`agent-installations.json`).
 Uninstall uses those recorded destinations, removes only managed guidance and
-the bundled GHA skill, and retains paths still shared by another configured
-harness. The ownership record is removed after the last configured harness is
-uninstalled.
+an unchanged GHA skill, and retains paths still shared by another configured
+harness. Existing unowned skills are never overwritten; a skill changed after
+installation is preserved during update and uninstall. The ownership record is
+removed after the last configured harness is uninstalled.
 
 When `--agent` is omitted, the command configures detected harnesses based on
 their setup directories; it does not require harness executables. If none are
 found, it explains how to select one later. Use `--binary-only` to skip harness
 setup, or comma-separated names such as `--agent pi,gemini,copilot` to select
 explicitly. Pi, OpenCode, Copilot, and Gemini
 share `~/.agents/skills/gha/SKILL.md` where their documented discovery supports
-it. Inspect destinations with `--dry-run`; otherwise the selected operation runs.
+it. Cursor uses `~/.cursor/skills/gha/SKILL.md`, Hermes Agent uses
+`$HERMES_HOME/skills/gha/SKILL.md` (default `~/.hermes/skills/gha/SKILL.md`),
+and OpenClaw uses `$OPENCLAW_STATE_DIR/skills/gha/SKILL.md` (default
+`~/.openclaw/skills/gha/SKILL.md`). Harness setup directories are detected
+without requiring executables. Inspect destinations with `--dry-run`; otherwise
+the selected operation runs.
 
 ```bash
 # Preview a Codex installation without changing files.
@@ -111,8 +118,13 @@ gha update --dry-run --format json
 `gha update` discovers the latest published GitHub release, then fetches that
 release's bundled skill and managed instruction block. It updates only the
 destinations recorded by `gha agent install`, preserving content outside the
-managed block. Writing runs by default; use `--dry-run` to preview. This command
-does not update the GHA executable.
+managed block. Before writing, it checks the skill's declared GHA command
+requirements against this executable's available capability inventory. If any
+required command is unavailable or the skill has no compatibility manifest,
+the update is rejected and existing files are preserved. Writing runs by
+default; use `--dry-run` to preview. This command does not update the GHA
+executable; update that through its installation method first. Structured
+results report `compatibility_state` and any `missing_capabilities`.
 
 ## Pull-request review
 

docs/roadmap.md

@@ -24,7 +24,8 @@ confirmation boundaries, and report what actually happened.
 - **Repository analysis:** offline worktree, history, storage, and large-file
   analysis.
 - **Agent guidance:** install, list, and uninstall for Codex, Claude Code, Pi,
-  OpenCode, GitHub Copilot, and Gemini CLI, with recorded destination ownership.
+  OpenCode, GitHub Copilot, Gemini CLI, Cursor, Hermes Agent, and OpenClaw, with
+  recorded destination ownership and modified-skill preservation.
 - **Guidance updates:** `gha update` discovers the latest published release and
   refreshes skills and managed instructions at recorded destinations; the GHA
   executable is not updated.
@@ -39,12 +40,15 @@ confirmation boundaries, and report what actually happened.
 
 Priorities are ordered by expected user value and prerequisite:
 
-1. **Assess additional harnesses.** Assess Cursor, Hermes Agent, and OpenClaw only after confirming
-   their current loading and safe-removal contracts.
-2. **Show coverage and project status.** Publish the CI coverage result and its
+1. **Show coverage and project status.** Publish the CI coverage result and its
    95% pass/fail status in pull requests. Add README badges for coverage, CI,
    and the latest release; include prereleases during the alpha phase. Keep the
    existing license badge and avoid manually maintained values.
+2. **Package-manager distribution.** Add maintained package-manager paths for
+   released GHA binaries, starting with a Homebrew tap and assessing Linux
+   options. Keep executable upgrades owned by the selected package manager and
+   refresh agent skills only when their declared GHA capabilities are
+   supported by the installed binary.
 3. **Design cleanup actions.** Before adding writes to `branches cleanup`,
    define candidate selection, per-target confirmation, provider safety, and
    checked-out-branch transitions. The current command stays read-only.