Categorize skills and add Ghostex orchestration surface

.gitignore

@@ -31,3 +31,6 @@ skills/remote-access/tools/remote-access-bridge/remote-access-bridge
 skills/handoff/bin/
 research/
 skills/cua-driver
+
+# Local DX/test reports - keep out of the repo
+docs/reports/*-dx.md

README.md

@@ -86,22 +86,40 @@ Reference these from TeamCreate teammates, Claude Code subagent types, or Codex
 
 ## Skills
 
-- `cmux` - control cmux workspaces, panes, terminal/browser surfaces, markdown viewers, and visible agent workspaces.
-- `tmux` - generic tmux reference for sessions, windows, panes, screen capture, and input.
-- `dotagents` - inspect and sync the repo-owned skill links across supported coding agents.
+Grouped by category, with the execution surface each skill drives. See `docs/reports/skill-categorization.md` for the full analysis.
+
+Orchestration and delegation:
+
+- `spawn` - decide how to delegate work to subagents or teams across Droid, Claude Code, Hermes, Codex, and multiplexer surfaces (tmux/cmux/Ghostex).
+- `cmux` - control cmux workspaces, panes, terminal/browser surfaces, markdown viewers, and visible agent workspaces. Surface: `cmux` CLI. Under replacement trial by Ghostex; kept until the trial concludes.
+- `tmux` - generic tmux reference for sessions, windows, panes, screen capture, and input. Surface: `tmux` CLI; fallback when neither cmux nor Ghostex manages the terminal.
+- `remote-access` - search local Droid/Codex sessions and send scoped continuation instructions through the Mac bridge from mobile. Surface: ssh/Tailscale + takopi.
+
+Ghostex ships its own bundled skills (`ghostex-agent-orchestration`, `ghostex-browser-use`, etc.); dotagents does not duplicate them - skills detect the surface and defer to the bundled reference when running inside Ghostex.
+
+Research:
+
+- `repo-eval` - find, triage, and deep-evaluate GitHub repos for a given need.
+- `tech-search` - gather high-signal opinions from tech communities and blogs on a topic.
+- `x-sim` - offline X audience simulation for draft tweets and handle positioning.
+
+Writing and process:
+
 - `grill-me` - pressure-test a plan one question at a time until scope and decisions are concrete.
-- `gws` - Google Workspace workflows. On Hermes, prefer the bundled native `google-workspace` skill; this repo's `skills/gws` remains the shared source for Claude Code/Codex and CLI helpers.
 - `humanizer` - final-pass rewriting for concise writing that keeps the user's voice.
+- `spec` - produce a small `SPEC.md` for complex or ambiguous work before implementation.
 - `jobs` - track job search pipeline, analyze fit for postings, generate interview quizzes, grade answers.
-- `remote-access` - search local Droid/Codex sessions and send scoped continuation instructions through the Mac bridge from mobile.
 - `pr-triage` - inspect PR failures and unresolved review threads, then drive a single fix-commit-push loop.
-- `repo-eval` - find, triage, and deep-evaluate GitHub repos for a given need.
-- `spec` - produce a small `SPEC.md` for complex or ambiguous work before implementation.
-- `spawn` - spawn and manage Claude Code agent teams with model routing and cmux integration.
+
+Integrations (CLI wrappers):
+
+- `gws` - Google Workspace workflows. On Hermes, prefer the bundled native `google-workspace` skill; this repo's `skills/gws` remains the shared source for Claude Code/Codex and CLI helpers.
 - `tg` - read Telegram chats, search messages, and list dialogs through the read-only `tg` CLI.
-- `tech-search` - gather high-signal opinions from tech communities and blogs on a topic.
 - `x-cli` - unofficial CLI for `x` tooling.
-- `x-sim` - offline X audience simulation for draft tweets and handle positioning.
+
+Infrastructure:
+
+- `dotagents` - inspect and sync the repo-owned skill links across supported coding agents.
 
 ## Installing these skills without dotagents
 

docs/reports/skill-categorization.md

@@ -0,0 +1,129 @@
+# Skill Categorization Report
+
+Date: 2026-06-12  
+Branch: ghostex-skill-categorization  
+Scope: dotagents skills (16) + Ghostex bundled skills (5)
+
+---
+
+## Summary Table
+
+| Skill | Category | Implementation Surface | Ghostex Overlap | Recommendation |
+|---|---|---|---|---|
+| **cmux** | Orchestration / multiplexer | cmux CLI | High: ghostex-agent-orchestration (pane mgmt), ghostex-browser-use (browser panes) | deprecate-behind-trial |
+| **tmux** | Orchestration / multiplexer | tmux CLI | Partial: ghostex-agent-orchestration wraps zmx (tmux-compatible); overlap via agent workflow pattern | deprecate-behind-trial |
+| **spawn** | Delegation / meta-orchestration | agent-agnostic (Claude Code teams section references cmux) | Partial: ghostex-agent-orchestration covers team creation; spawn is broader (Hermes, Codex, Droid) | parameterize for Ghostex (add gx section) |
+| **remote-access** | Remote access / mobile bridge | REST bridge + takopi (Telegram) | Partial: Ghostex has no takopi or mobile bridge; computer-use for macOS is different | keep as-is (complementary) |
+| **dotagents** | Infra / config management | Go CLI (plain CLI) | None | keep as-is |
+| **grill-me** | Writing / process | none (prompt-only) | None | keep as-is |
+| **gws** | Integration / CLI wrapper | gws CLI | None | keep as-is |
+| **humanizer** | Writing / voice | none (prompt-only) | None | keep as-is |
+| **jobs** | Workflow / process | gws CLI + LinkedIn MCP + WebSearch | None | keep as-is |
+| **pr-triage** | Workflow / process | gh CLI + Go tool + GitHub MCP | ghostex-manage-beads covers bead-based review tracking (no overlap on PRs proper) | keep as-is |
+| **repo-eval** | Research | gh CLI + WebSearch + x-cli | None | keep as-is |
+| **spec** | Writing / process | none (prompt-only) | None | keep as-is |
+| **tech-search** | Research | WebSearch + x-cli + rdt + discord-cli | None | keep as-is |
+| **tg** | Integration / CLI wrapper | tg CLI (Telethon daemon) | None | keep as-is |
+| **x-cli** | Integration / CLI wrapper | x-cli binary | None | keep as-is |
+| **x-sim** | Research / writing | x-cli + Go tool | None | keep as-is |
+
+---
+
+## Ghostex Bundled Skills
+
+| Skill | Category | Surface | Relation to dotagents skills |
+|---|---|---|---|
+| ghostex-agent-orchestration | Orchestration / multiplexer | ghostex / zmx CLI | Replaces cmux and tmux for Ghostex-managed panes |
+| ghostex-browser-use | Integration / browser | CEF DevTools MCP | Replaces cmux browser surfaces |
+| ghostex-computer-use | Integration / native macOS | cua-driver CLI | No direct dotagents equivalent |
+| ghostex-generate-title | Utility | ghostex CLI | No dotagents equivalent |
+| ghostex-manage-beads | Workflow / process | gx bd CLI | Parallel to pr-triage (different object: beads vs PRs) |
+
+---
+
+## Orchestration Cluster: Detailed Analysis
+
+### Skills in the cluster
+
+- **tmux**: Generic pane management reference. Detects CMUX env vars and routes to cmux if present. Pure tmux when no cmux.
+- **cmux**: Full cmux pane + browser surface management. cmux-specific launchers. Hooks routed through dotagents.
+- **spawn**: Agent delegation meta-skill. Surface-agnostic in framework; Claude Code teams section explicitly depends on cmux (`cmux claude-teams`).
+- **remote-access**: Two modes: takopi (Telegram -> Pi) and Mac bridge (REST). Not a multiplexer itself; uses no tmux or cmux directly.
+
+### Ghostex overlap
+
+`ghostex-agent-orchestration` covers the same conceptual surface as cmux + tmux for Ghostex-managed terminals:
+
+| cmux capability | tmux capability | ghostex-agent-orchestration equivalent |
+|---|---|---|
+| `cmux new-workspace`, `cmux new-pane` | `tmux new-session`, `tmux new-window` | `ghostex create-session`, `ghostex create-agent` |
+| `cmux send`, `cmux send-key` | `tmux send-keys` | `ghostex send-message`, `ghostex send-text`, `ghostex send-key` |
+| `cmux read-screen` | `tmux capture-pane` | `ghostex read-text` |
+| `cmux browser ...` | (none) | `$ghostex-browser-use` |
+| `cmux list-panes`, `cmux tree` | `tmux list-panes` | `ghostex sessions --json`, `ghostex state` |
+| `cmux focus-pane` | `tmux select-pane` | `ghostex focus` |
+| `cmux close-surface` | `tmux kill-pane` | `ghostex kill` |
+
+spawn's Claude Code teams section (`TeamCreate + cmux claude-teams`) does not have a direct Ghostex equivalent yet: `ghostex create-agent` launches configured agent panes but the Claude Code multi-agent team protocol (`TeamCreate`, `TaskCreate`, `SendMessage`) is harness-specific and lives at a layer above the multiplexer.
+
+remote-access is complementary: it covers Telegram-based mobile access to Pi and a REST bridge for Hermes-to-Mac communication. Ghostex has no takopi or bridge equivalent.
+
+### Options evaluated
+
+**Option A: Keep separate per-surface skills**
+
+Pros: clean separation, no conditional logic inside a skill, easy to deprecate one surface.  
+Cons: agents currently must detect the surface and pick between tmux and cmux manually (tmux.md delegates this with env-var detection), and adding a third surface (ghostex) means a third parallel skill that agents must choose between.
+
+**Option B: Merge into one "mux" skill with per-surface sections**
+
+Pros: single lookup for agents, env-var routing logic centralized, detection logic is the same in all three skills.  
+Cons: the merged skill grows large; detection-routing becomes critical to get right; harder to deprecate one surface cleanly; Ghostex bundled skills already cover ghostex-agent-orchestration independently, so merging would duplicate or conflict with the bundled skill.
+
+**Option C: spawn delegates to surface skills**
+
+Pros: spawn already decides delegation mode; surface detection fits its pattern.  
+Cons: spawn is about agent delegation (what work to hand off and to whom), not multiplexer command syntax. Mixing those concerns into spawn bloats it. Surface-selection is a pre-condition for spawn, not spawn's job.
+
+---
+
+## Recommendation
+
+### For the trial period (cmux and tmux)
+
+Keep cmux and tmux as separate skills, both marked as **deprecate-behind-trial**. The tmux skill already has the right routing logic (checks for CMUX env vars first). When the Ghostex trial concludes:
+
+- If Ghostex replaces cmux: remove cmux, update tmux detection to add a ghostex env-var check above the CMUX check, and note that ghostex-agent-orchestration is the authoritative reference.
+- If cmux stays: no change needed.
+
+Do not merge cmux and tmux now. The trial outcome should drive which surface becomes primary.
+
+### For spawn
+
+Add a **Ghostex execution section** to spawn alongside the existing Claude Code, Hermes, Codex, and Droid sections. The teams subsection currently says "Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set by cmux claude-teams)". When running under Ghostex, `ghostex create-agent` is the equivalent pane launcher. The TeamCreate protocol itself is Claude Code-level and does not change.
+
+This is a targeted addition, not a merge. spawn stays the decision layer; the new Ghostex section gives the execution syntax for agents running inside Ghostex.
+
+### For remote-access
+
+Keep as-is. It covers a different dimension (mobile/remote reach) that Ghostex does not address. takopi and the Mac bridge are complementary to any multiplexer surface.
+
+### Summary
+
+- **cmux**: deprecate-behind-trial (overlap with ghostex-agent-orchestration + ghostex-browser-use is high)
+- **tmux**: deprecate-behind-trial (overlap with ghostex-agent-orchestration via zmx is partial but covers the core use case)
+- **spawn**: parameterize for Ghostex -- add a `## Ghostex execution` section mirroring the cmux teams launch pattern
+- **remote-access**: keep as-is -- no Ghostex overlap on mobile/bridge surface
+
+---
+
+## Evidence Notes
+
+All findings are based on direct reading of SKILL.md files. No speculation about undocumented Ghostex CLI behavior.
+
+- dotagents skills: `~/.agents/skills/*/SKILL.md`
+- Ghostex bundled skills: `/Applications/Ghostex.app/Contents/Resources/CLI/skills/*/SKILL.md`
+- ghostex-agent-orchestration explicitly states it wraps zmx ("Ghostex uses zmx under the hood for this") confirming the tmux-layer overlap
+- ghostex-browser-use is a CEF DevTools MCP bridge, a direct replacement for cmux browser surfaces
+- ghostex-computer-use delegates to cua-driver; no dotagents equivalent exists
+- ghostex-generate-title and ghostex-manage-beads have no dotagents equivalents

skills/cmux/SKILL.md

@@ -7,6 +7,8 @@ description: Control cmux workspaces, panes, terminal and browser surfaces, mark
 
 Use this skill when the current terminal is managed by cmux, or when the task needs cmux browser surfaces, workspace layout, markdown viewing, or cmux-specific agent launchers.
 
+Status: under replacement trial by Ghostex (since 2026-06-12). If the terminal is managed by Ghostex instead (`GHOSTEX_*` env vars set, no `CMUX_*` env), use Ghostex's bundled `ghostex-agent-orchestration` and `ghostex-browser-use` skills. This skill stays until the trial concludes.
+
 ## Detection
 
 ```bash

skills/spawn/SKILL.md

@@ -218,3 +218,30 @@ Enable `multi_agent = true` in `~/.codex/config.toml`. Codex spawns child agents
 - No shared task list across sessions
 - No bi-directional messaging between independent sessions
 - Coordination is single-session only
+
+---
+
+## Ghostex execution
+
+Use when the terminal is managed by Ghostex (detect: `GHOSTEX_*` env vars set, e.g. `GHOSTEX_ZMX_BIN`; `gx state` succeeding alone only proves the server is running somewhere). The bundled `ghostex-agent-orchestration` skill in the app is the authoritative command reference; this section only covers the spawn loop.
+
+```bash
+gx sessions --json                                  # inspect projects/sessions
+gx create-session "task title" --project-id <id>    # registers the session
+gx send-message <selector> "self-contained prompt"  # send prompt + Enter
+gx read-text <selector> --lines 80 --json           # read output
+gx kill <selector> --json                           # clean up
+```
+
+Known gaps (gxserver 0.1.0):
+
+- CLI-created sessions lazy-start: the PTY does not exist until a client attaches. Headless workaround: pre-start the daemon with the bundled zmx (not on PATH) before sending input:
+
+  ```bash
+  zmx="/Applications/Ghostex.app/Contents/Resources/Web/bin/zmx"
+  "$zmx" run "<zmxName from sessions --json>" -d --initial-command /bin/zsh -lic 'exec /bin/zsh -li'
+  ```
+
+- `gx send-key ctrl-c`, `gx wait-for`, `gx focus` are broken headlessly; interrupt via `printf '\x03' | "$zmx" send <zmxName>` and wait by polling `read-text`.
+- Agent buttons (`create-agent`/`run-agent`) do not auto-dispatch their startup command without the UI; send it manually after the zmx pre-start.
+- No cmux-style markdown viewer: show reports by opening the .md in the embedded Code editor. `gx edit <file>` is the intended path but currently fails (missing `openPaths` gxserver endpoint); until it lands, ask the user to open the file in the Ghostex editor, or print the path. Upstream CLI TDZ-crash fix: maddada/Ghostex#21.

skills/tmux/SKILL.md

@@ -5,18 +5,20 @@ description: Generic tmux reference for sessions, windows, panes, screen capture
 
 # tmux
 
-Use this skill for terminal multiplexing when the current terminal is not managed by cmux.
+Use this skill for terminal multiplexing when the current terminal is not managed by cmux or Ghostex.
 
 ## Detection
 
 ```bash
 env | grep '^CMUX_'         # if present, switch to the cmux skill
+env | grep '^GHOSTEX_'      # if present, the terminal is Ghostex-managed: use its bundled ghostex-agent-orchestration skill
 test -n "$TMUX" && echo tmux
 command -v tmux
 ```
 
 Routing:
 - If `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID` are set, use the `cmux` skill.
+- Else if `GHOSTEX_*` env vars are set (e.g. `GHOSTEX_ZMX_BIN`), the terminal is Ghostex-managed: use the bundled `ghostex-agent-orchestration` skill (zmx underneath). A merely-running Ghostex app elsewhere does not count - `gx state` succeeding is server state, not terminal ownership.
 - Else if `TMUX` is set, target the current tmux server/session.
 - Else if `tmux` exists, create or attach a tmux session before relying on pane operations.
 - Else, no supported queryable pane manager is active.