feat: Add agent-tui and tui-explorer skills with comprehensive documentation and scripts

.agents/skills/tui-explorer/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: tui-explorer
+description: >
+  Discover and replay terminal UI paths using agent-tui.
+  Use when you need to launch a TUI app, explore navigation with bounded BFS,
+  generate markdown acceptance tests, and verify those tests repeatedly.
+  Do not use for web or desktop GUI automation.
+---
+
+# tui-explorer
+
+## Purpose
+Generate replayable acceptance tests from discovered TUI navigation paths.
+
+## Commands
+- Discover:
+  - `skills/tui-explorer/scripts/tui_explorer discover --command "<app command>"`
+- Verify:
+  - `skills/tui-explorer/scripts/tui_explorer verify --spec "<path-to-acceptance.md>"`
+
+## Defaults
+- Exploration strategy: bounded BFS.
+- Safe action set: `Enter`, `Tab`, `ArrowDown`, `ArrowUp`, `ArrowRight`, `ArrowLeft`, `Esc`, `Space`.
+- Risky actions are disabled unless `--allow-risky` is set.
+- Output directory defaults to `.agent-tui/discover/<timestamp>/`.
+- Replay fails on scenario failure and exits non-zero.
+
+## Workflow
+1. Start live preview over the HTTP endpoint with `agent-tui live start --open` before discovery so the user can watch exploration in the built-in web UI.
+2. Run `discover` for the target command.
+3. Inspect generated artifacts:
+   - `acceptance.md` (human-readable OpenSpec-style expectations + machine-executable steps)
+   - `trace.jsonl`
+   - `discover-report.json`
+4. Run `verify` against the generated `acceptance.md`.
+5. Stop live preview with `agent-tui live stop` after verification.
+
+Session handling for live preview:
+- Treat browser session selection as preview-local context only.
+- Do not use browser interactions to switch the daemon active session.
+6. On failure, inspect `verify-report.json` and files under `failures/`.
+
+## References
+- Schema details: `references/schema-v1.md`
+- Discovery mechanics: `references/discovery.md`
+- Replay semantics: `references/replay.md`

.agents/skills/tui-explorer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TUI Explorer"
+  short_description: "Discover and replay TUI acceptance paths"
+  default_prompt: "Use tui-explorer to discover bounded TUI navigation paths, generate schema v1 markdown acceptance tests, and verify them with fail-fast replay and artifacts. Start live preview over the HTTP endpoint with `agent-tui live start --open` before discovery so the user can watch exploration in the built-in web UI, and stop it with `agent-tui live stop` after verification. Treat browser session selection as preview-local and do not switch the daemon active session from UI navigation."

.agents/skills/tui-explorer/references/discovery.md

@@ -0,0 +1,33 @@
+# Discovery
+
+Run:
+- `skills/tui-explorer/scripts/tui_explorer discover --command "<app command>"`
+- Before running discover, start live preview so users can observe exploration in the web UI:
+  - `agent-tui live start --open`
+- After verification, stop preview:
+  - `agent-tui live stop`
+
+## Strategy
+- Bounded BFS over action paths.
+- Rebuild each node from a fresh session for deterministic state evaluation.
+- Deduplicate with:
+  - `sha256(normalized_screenshot + cursor + cols + rows)`
+
+## Normalization
+- Strip ANSI sequences.
+- Collapse whitespace.
+
+## Stop rules
+- `max_depth`
+- `max_states`
+- `branch_limit`
+- `time_budget_sec`
+
+## Artifacts
+- `acceptance.md` (includes OpenSpec-style `WHEN/THEN/SHOULD` expectation narrative plus executable step lines)
+- `trace.jsonl`
+- `discover-report.json`
+
+## Session isolation
+- Session changes made in the web UI are preview-local.
+- Discovery/verify commands must not rely on browser-driven active session switching.

.agents/skills/tui-explorer/references/replay.md

@@ -0,0 +1,20 @@
+# Replay
+
+Run:
+- `skills/tui-explorer/scripts/tui_explorer verify --spec "<acceptance.md>"`
+
+## Execution model
+- Spawn a fresh session per scenario.
+- Execute each step in order.
+- Use `wait --assert` for `expect` steps.
+- Stop on first scenario failure (fail-fast).
+
+## Result contract
+- Exit `0`: all scenarios pass.
+- Exit `1`: scenario/assertion failure.
+- Exit `2`: spec validation error.
+- Exit `69`: agent-tui/daemon unavailable.
+
+## Failure artifacts
+- `verify-report.json`
+- `failures/<scenario>-step-<n>.txt`

.agents/skills/tui-explorer/references/schema-v1.md

@@ -0,0 +1,35 @@
+# Schema v1
+
+Acceptance files are markdown with YAML frontmatter.
+
+## Required frontmatter
+- `schema_version: "v1"`
+- `command`
+- `cols`
+- `rows`
+- `default_timeout_ms`
+- `generated_at`
+- `generator`
+
+Optional:
+- `cwd`
+
+## Scenario format
+Scenario header:
+- `## Scenario: <name>`
+
+Optional OpenSpec-style expectation narrative (human-readable):
+- `### Expectation` (or `### Expectations`)
+- `- **WHEN** ...`
+- `- **THEN** ...`
+- `- **AND** ...` (optional)
+- `- **SHOULD** ...`
+
+Supported steps:
+- `- expect: "<text>"`
+- `- press: "<key>"`
+- `- type: "<text>"`
+- `- wait_stable: true`
+
+OpenSpec narrative lines are ignored by the verifier parser; executable behavior is driven by the supported step lines.
+Any other non-empty line format is invalid.

.agents/skills/tui-explorer/scripts/tui_explorer

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+
+exec cargo run -q --manifest-path "$ROOT/cli/Cargo.toml" -p xtask -- tui-explorer "$@"