prototype-openclaw-tui

Files (3)

• SKILL.md
• openai.yaml · agents/
• launch-tmux-grid.sh · scripts/

SKILL.md (first lines)

# Prototype OpenClaw TUI

Use this skill to isolate one OpenClaw terminal surface, render it with the
real OpenClaw TUI stack, and compare two to six design variants in tmux.

## Rules

- Read the root and scoped `AGENTS.md` files before editing.
- Keep the prototype beside the target and name it `*.prototype.ts`.
- When iterating on an existing surface, include its current implementation as
  the first `baseline` variant with the same fixture data. Only omit the
  baseline when the user explicitly asks for a greenfield comparison.
- Use the real OpenClaw renderer, theme, copy, and component where practical.
- Replace scanning, models, network calls, installs, config writes, SQLite, and
  other durable effects with deterministic in-memory fixtures.
- Do not run the full OpenClaw application when the isolated surface is enough.
- Treat prototype code as throwaway. Do not promote it directly to production.
- Preserve unrelated and pre-existing worktree changes.

## Choose the renderer

- Wizard, onboarding, configuration, doctor, selection, or progress surface:
  use `createClackPrompter()` from `src/wizard/clack-prompter.ts`.
- Agent shell, chat, overlay, editor, selector, or `src/tui/**` component:
  use `@earendil-works/pi-tui` and the existing OpenClaw component.

Do not invent a shared Clack/Pi abstraction. They are separate prototype
recipes joined only by the tmux comparison loop.

## Workflow

1. Read the target module, its renderer adapter, callers, and adjacent tests.
2. Create the smallest executable harness that reaches the target surface.
3. If the surface already exists, make the no-argument invocation render its
   current implementation unchanged as `--variant=baseline`.
4. Add structurally different alternatives behind `--variant=<id>`, for two
   to six total variants including the baseline.
5. Give every variant the same fixture data and terminal dimensions.
6. Run each variant directly in its own tmux pane. Do not pipe interactive TUI
   output; tmux must provide the PTY.
7. Iterate on the harness with the launcher's `--refresh` mode. Respawn the
   panes in the existing session; do not kill the session or reopen the user's
   terminal.
8. After the user chooses a direction, carry the decision into production code
   with normal tests and validation. Remove or separately capture the prototype.

## Launch the comparison grid

Run the bundled launcher with a session name, repository path, then title and
command pairs:

```bash
.agents/skills/prototype-openclaw-tui/scripts/launch-tmux-grid.sh \
  --open \
  app-recommendations-prototype "$PWD" \
  "A - Baseline" "node --import tsx src/wizard/setup.app-recommendations.prototype.ts --variant=baseline" \
  "B - Grouped" "node --import tsx src/wizard/setup.app-recommendations.prototype.ts --variant=grouped" \
  "C - Focused" "node --import tsx src/wizard/setup.app-recommendations.prototype.ts --variant=focused"
```

After editing the prototype, run the same command with `--refresh` instead of
`--open`. This preserves the tmux session, attached external terminal, window,
and first pane while restarting all pane commands and reapplying the grid:

```bash
.agents/skills/prototype-openclaw-tui/scripts/launch-tmux-grid.sh \
  --refresh \
  app-recommendations-prototype "$PWD" \
  "A - Baseline" "node --import tsx src/wizard/setup.app-recommendations.prototype.ts --variant=baseline" \
  "B - Grouped" "node --import tsx src/wizard/setup.app-recommendations.prototype.ts --variant=grouped" \
  "C - Focused" "node --import tsx src/wizard/setup.app-recommendations.prototype.ts --variant=focused"
```

The launcher refuses to replace an existing session unless `--refresh` is
explicitly provided. `--open` uses the user's
`.command`-associated terminal app on macOS, Windows Terminal from WSL, or the
first available Linux launcher from `xdg-terminal-exec`, `$TERMINAL`, and
`x-terminal-emulator`. If no supported launcher is available, the tmux session
remains ready at equal detached dimensions and the script exits successfully
after printing the manual attach command. Attach, then run `--refresh` once to
adopt the terminal's larger dimensions. The same guidance applies if an
external terminal opens but does not attach within ten seconds. When invoked
from a non-interactive `TERM=dumb` environment, the launcher removes its
inherited `NO_COLOR` only from prototype pane processes so the external
terminal can detect and render its normal colors. Prefer the external terminal
over the Codex in-app terminal unless the user asks for the in-app surface.
Leave the session running for user review unless asked to stop it.

## Handoff

Report:

- the prototype path and exact run command;
- the tmux session name and attach command;
- which effects were replaced with fixtures;
- available variant ids;
- whether the prototype changed production code (normally no).

From openclaw/openclaw, MIT.

More from openclaw/openclaw