opt-shell Install
This is NOT the opt-shell you know. @reopt-ai/opt-shell (formerly @reopt-ai/opt-harness) is the runtime product-frame layer between opt-ui and product screens. It ships no dist/docs/ — read node_modules/@reopt-ai/opt-shell/shell-llms.txt (agent guide) and README.md before writing code.
What opt-shell provides
| Area |
Pattern |
| Workspace recipes |
DashboardWorkspace, ListWorkspace, DetailWorkspace, EditorWorkspace, landing — pick via the decision tree in shell-llms.txt |
| Non-recipe surface |
ShellFullscreenToolSurface (full-viewport tools — code editor, canvas) |
| Policy |
density, contentWidth, navigationMode, motionPolicy, textScale, sidebarMode, shortcutHints |
| Adapters |
data-engine wrappers supplying loading / empty / error chrome |
| State UX |
shared state boundaries; every recipe requires header + content slots |
| Authoring audit |
@reopt-ai/opt-cli/audit + opt harness commands; published opt-shell 1.1.0 has no ./audit export |
Invocation
/opt-shell-install # Auto-branch (missing → init, installed → upgrade)
/opt-shell-install --upgrade # Explicit upgrade
/opt-shell-install --check # Analyze only
Step 1 — Pin agent rules into AGENTS.md / CLAUDE.md
Source: the module's own agent-rules file once it ships one (@reopt-ai/opt-shell ships shell-llms.txt, an agent guide, but not a marker-block file as of 1.1.0). Fallback: agent-rules.md bundled with this skill. Wrap content between:
<!-- BEGIN:reopt/opt-shell-agent-rules -->
…content from source…
<!-- END:reopt/opt-shell-agent-rules -->
Idempotent: replace only between markers.
Step 2 — Consumer-side setup (this skill owns; docs cannot)
Public npm registry — no token or scoped .npmrc entry is required. Inspect the project .npmrc and npm config get @reopt-ai:registry; if the scope still resolves to GitHub Packages, remove only the legacy project entry @reopt-ai:registry=https://npm.pkg.github.com. Preserve unrelated registry/auth settings, and ask before changing user/global npm config.
Runtime / peers — Node 20+ is required. For opt-shell's peerDependencies, install / run their skills first if missing:
- Required:
@reopt-ai/opt-palette (theme engine), react / react-dom 19+
- Optional (only if you use that adapter):
@reopt-ai/opt-datagrid (/opt-datagrid-install), @reopt-ai/opt-editor (/opt-editor-install), @reopt-ai/opt-calendar
@reopt-ai/opt-ui is a direct dependency of opt-shell; run /opt-ui-install to wire its Tailwind/theme CSS rather than adding a second package copy or source alias.
App wiring — properties of the consumer app:
- A workspace recipe at the screen root (
header + content slots are mandatory).
- A shell manifest / policy config (density, contentWidth, navigationMode, motionPolicy, textScale, sidebarMode, shortcutHints).
@reopt-ai/opt-ui/app.css in global CSS when 1.1 document policies (motion, text scale, shortcut hints) should take effect.- Adapters wired to your data engines wherever loading / empty / error chrome is needed.
- Prefer
useShellPreferences() for localStorage/cross-tab policy persistence and the Shell shortcut registry for global shortcuts; do not duplicate either layer in app code.
Step 3 — Route to module docs
opt-shell ships no dist/docs/. Route to shell-llms.txt (agent guide) and README.md.
| Task signal |
Read |
| Recipe decision tree, slot rules, policy |
shell-llms.txt |
Component / prop API, exports (., ./core, ./meta) |
README.md §§ "Module map", "Which component do I need?", "Hooks" |
| Slot rules, z-index, theme wiring |
README.md §§ "Slot contract", "z-index scale", "Theme configuration" |
| Agent-facing protocol + lint rules |
README.md §§ "AI Agent Protocol", "ESLint Plugin" |
| Authoring audit / scoring |
@reopt-ai/opt-cli/audit; `npx @reopt-ai/opt-cli harness check |
| Breaking changes per version |
CHANGELOG.md |
Pipeline (auto-branch)
| # |
Step |
Init |
Upgrade |
| 1 |
Detect current state (incl. legacy opt-harness dep) |
✓ |
✓ |
| 2 |
Public-registry preflight + legacy override cleanup |
✓ |
✓ |
| 3 |
Install / update package |
✓ |
✓ |
| 4 |
Dependency/peer check (opt-ui direct; opt-palette required; adapters optional) |
✓ |
✓ |
| 5 |
Shell manifest / policy config |
✓ |
– |
| 6 |
First workspace recipe |
✓ |
– |
| 7 |
Breaking-change edits |
– |
✓ |
| 8 |
Verify + summary |
✓ |
✓ |
Safety
- Never upgrade without an impact scan.
- Confirm before overwriting existing files.
- Apply breaking-change edits in logical groups, never bulk.
- Do not finish until
tsc --noEmit passes.
- Never commit — do not commit or push without an explicit request.
Verify
npx tsc --noEmit passes.- App boots into the chosen workspace recipe (
header + content slots filled); policy applies, including expected <html> data-density / data-motion / data-text-scale / data-shortcut-hints attributes.
- (If an adapter is used) the data-grid or editor adapter renders the peer's content with shell chrome (loading / empty / error states).
1---2name: opt-shell-install3description: Install or upgrade @reopt-ai/opt-shell — the runtime product-frame layer for workspace recipes, document policy, persisted preferences, shortcuts, adapters, and state boundaries. Formerly @reopt-ai/opt-harness. Auto-branches by current install state. Triggers on "opt-shell install", "opt-shell init", "opt-shell setup", "shell install", "app shell setup", "workspace recipe", "opt-shell upgrade", "opt-shell update", "shell preferences", "shortcut registry", "document policy", plus legacy "opt-harness install", "harness install", "harness setup".4---56# opt-shell Install78> This is NOT the opt-shell you know. `@reopt-ai/opt-shell` (formerly `@reopt-ai/opt-harness`) is the runtime product-frame layer between opt-ui and product screens. It ships **no** `dist/docs/` — read `node_modules/@reopt-ai/opt-shell/shell-llms.txt` (agent guide) and `README.md` before writing code.910## What opt-shell provides1112| Area | Pattern |13|---|---|14| Workspace recipes | `DashboardWorkspace`, `ListWorkspace`, `DetailWorkspace`, `EditorWorkspace`, landing — pick via the decision tree in `shell-llms.txt` |15| Non-recipe surface | `ShellFullscreenToolSurface` (full-viewport tools — code editor, canvas) |16| Policy | density, contentWidth, navigationMode, motionPolicy, textScale, sidebarMode, shortcutHints |17| Adapters | data-engine wrappers supplying loading / empty / error chrome |18| State UX | shared state boundaries; every recipe requires `header` + `content` slots |19| Authoring audit | `@reopt-ai/opt-cli/audit` + `opt harness` commands; published opt-shell 1.1.0 has no `./audit` export |2021## Invocation2223```24/opt-shell-install # Auto-branch (missing → init, installed → upgrade)25/opt-shell-install --upgrade # Explicit upgrade26/opt-shell-install --check # Analyze only27```2829## Step 1 — Pin agent rules into AGENTS.md / CLAUDE.md3031Source: the module's own agent-rules file once it ships one (`@reopt-ai/opt-shell` ships `shell-llms.txt`, an agent guide, but not a marker-block file as of 1.1.0). Fallback: `agent-rules.md` bundled with this skill. Wrap content between:3233```34<!-- BEGIN:reopt/opt-shell-agent-rules -->35…content from source…36<!-- END:reopt/opt-shell-agent-rules -->37```3839**Idempotent:** replace only between markers.4041## Step 2 — Consumer-side setup (this skill owns; docs cannot)42431. **Public npm registry** — no token or scoped `.npmrc` entry is required. Inspect the project `.npmrc` and `npm config get @reopt-ai:registry`; if the scope still resolves to GitHub Packages, remove only the legacy project entry `@reopt-ai:registry=https://npm.pkg.github.com`. Preserve unrelated registry/auth settings, and ask before changing user/global npm config.44452. **Runtime / peers** — Node 20+ is required. For opt-shell's `peerDependencies`, install / run their skills first if missing:46 - **Required:** `@reopt-ai/opt-palette` (theme engine), `react` / `react-dom` 19+47 - **Optional** (only if you use that adapter): `@reopt-ai/opt-datagrid` (`/opt-datagrid-install`), `@reopt-ai/opt-editor` (`/opt-editor-install`), `@reopt-ai/opt-calendar`4849 `@reopt-ai/opt-ui` is a direct dependency of opt-shell; run `/opt-ui-install` to wire its Tailwind/theme CSS rather than adding a second package copy or source alias.50513. **App wiring** — properties of the consumer app:52 - A workspace recipe at the screen root (`header` + `content` slots are mandatory).53 - A shell manifest / policy config (density, contentWidth, navigationMode, motionPolicy, textScale, sidebarMode, shortcutHints).54 - `@reopt-ai/opt-ui/app.css` in global CSS when 1.1 document policies (motion, text scale, shortcut hints) should take effect.55 - Adapters wired to your data engines wherever loading / empty / error chrome is needed.56 - Prefer `useShellPreferences()` for localStorage/cross-tab policy persistence and the Shell shortcut registry for global shortcuts; do not duplicate either layer in app code.5758## Step 3 — Route to module docs5960opt-shell ships **no** `dist/docs/`. Route to `shell-llms.txt` (agent guide) and `README.md`.6162| Task signal | Read |63|---|---|64| Recipe decision tree, slot rules, policy | `shell-llms.txt` |65| Component / prop API, exports (`.`, `./core`, `./meta`) | `README.md` §§ "Module map", "Which component do I need?", "Hooks" |66| Slot rules, z-index, theme wiring | `README.md` §§ "Slot contract", "z-index scale", "Theme configuration" |67| Agent-facing protocol + lint rules | `README.md` §§ "AI Agent Protocol", "ESLint Plugin" |68| Authoring audit / scoring | `@reopt-ai/opt-cli/audit`; `npx @reopt-ai/opt-cli harness check|test|doctor` |69| Breaking changes per version | `CHANGELOG.md` |7071## Pipeline (auto-branch)7273| # | Step | Init | Upgrade |74|---|---|---|---|75| 1 | Detect current state (incl. legacy `opt-harness` dep) | ✓ | ✓ |76| 2 | Public-registry preflight + legacy override cleanup | ✓ | ✓ |77| 3 | Install / update package | ✓ | ✓ |78| 4 | Dependency/peer check (opt-ui direct; opt-palette required; adapters optional) | ✓ | ✓ |79| 5 | Shell manifest / policy config | ✓ | – |80| 6 | First workspace recipe | ✓ | – |81| 7 | Breaking-change edits | – | ✓ |82| 8 | Verify + summary | ✓ | ✓ |8384## Safety8586- Never upgrade without an impact scan.87- Confirm before overwriting existing files.88- Apply breaking-change edits in logical groups, never bulk.89- Do not finish until `tsc --noEmit` passes.90- **Never commit** — do not commit or push without an explicit request.9192## Verify93941. `npx tsc --noEmit` passes.952. App boots into the chosen workspace recipe (`header` + `content` slots filled); policy applies, including expected `<html>` `data-density` / `data-motion` / `data-text-scale` / `data-shortcut-hints` attributes.963. (If an adapter is used) the data-grid or editor adapter renders the peer's content with shell chrome (loading / empty / error states).
reopt-ai