opt-shell

1. 북극성

opt-ui가 무엇으로 화면을 만들지 제공한다면, 루트 `DESIGN.md`는 어떻게 보여야 하는지 정하고, opt-shell는 제품급 화면을 어떤 규율로 만들지 제공합니다. 그래서 이 문서 묶음도 단순 API 안내가 아니라 visual contract, mission, recipe, agent contract, rollout evidence 순으로 읽히게 구성합니다.

최근에는 여기에 운영 관점이 추가됐습니다. 이제 opt-shell는 code layer만이 아니라, managed harness draft를 preview, review, approval, activation으로 다루는 사용자-facing workflow까지 포함합니다. 즉, 제품 품질 규약과 그 규약을 적용하는 거버넌스 surface를 함께 봐야 전체 그림이 맞습니다.

2. 왜 opt-shell인가

opt-ui는 토큰과 컴포넌트의 일관성을 잘 해결하지만, 실제 제품 화면에서 반복되는 문제는 별도였습니다. 페이지 폭이 흔들리고, loading/empty/error 상태 copy가 화면마다 달라지고, DataGrid와 Editor 주변의 toolbar, inspector, footer chrome이 제각각 생기기 시작했습니다. opt-shell는 그 문제를 "새 컴포넌트를 더 만드는 것"이 아니라 "제품 화면의 틀을 고정하는 것"으로 해결합니다.

여기서 끝나지 않습니다. 실제 팀은 후보 harness가 active baseline과 어떻게 다른지 즉시 이해해야 하고, review note와 actor evidence를 남긴 뒤, 승인된 후보만 runtime으로 올려야 합니다. 그래서 Builder Harness Manager는 부가 기능이 아니라 opt-shell의 운영 면을 증명하는 핵심 surface입니다.

import {
  DashboardWorkspace,
  ShellAppShell,
  ShellCollapsibleNav,
  ShellProvider,
  ShellSection,
  ShellStateBoundary,
} from "@reopt-ai/opt-shell";
import { builderHarness } from "@/lib/harness";
import type { ReactNode } from "react";

export function BuilderFrame({
  nav,
  children,
}: {
  nav: ReactNode;
  children: ReactNode;
}) {
  return (
    <ShellProvider manifest={builderHarness}>
      <ShellAppShell nav={<ShellCollapsibleNav>{nav}</ShellCollapsibleNav>}>
        <DashboardWorkspace
          header={<div>Builder Header</div>}
          toolbar={<div>Primary Actions</div>}
          aside={<div>Inspector</div>}
        >
          <ShellStateBoundary loading={false}>
            <ShellSection
              title="Overview"
              description="핵심 지표와 작업 상태를 한 리듬으로 묶습니다."
              frame="card"
            >
              {children}
            </ShellSection>
          </ShellStateBoundary>
        </DashboardWorkspace>
      </ShellAppShell>
    </ShellProvider>
  );
}

3. 동작 원리

opt-shell는 "선언 → 해석 → 주입 → 레이아웃 → 상태 정규화 → 관찰" 순서로 동작합니다. 아래 다이어그램은 이 파이프라인의 전체 흐름입니다.

// layout.tsx — 앱 프레임
<ShellProvider manifest={builderManifest}>
  <ShellAppShell nav={<Nav />} header={<Header />}>
    {children}
  </ShellAppShell>
</ShellProvider>

// page.tsx — 목록 화면 예시
<ListWorkspace
  header={<PageHeader title="프로젝트" />}
  toolbar={<FilterBar />}
  aside={<PreviewPanel />}
>
  <ShellStateBoundary loading={isLoading} error={error}>
    <ShellDataGridAdapter
      columns={cols} rows={rows}
      getRowId={(row) => row.id}
    />
  </ShellStateBoundary>
</ListWorkspace>

4. 책임 경계

5. 문서에서 코드까지

opt-shell는 설명과 구현이 분리되면 금방 흐려집니다. visual intent는 루트 `DESIGN.md`에, 역할 정의는 mission 문서에, 화면 유형은 recipes 문서에, 실행 규칙은 agent contract 문서에 둡니다. 실제 구현과 검사 도구는 그 언어를 그대로 사용해야 합니다. 현재 runtime은 workspace component를 primary API로 사용하고, `ShellPage recipe="..."`는 low-level escape hatch로 남습니다.

6. 핵심 런타임 블록

지금 구현은 recipe-aware runtime을 넘어 workspace-first API, fresh design proof gate, generated docs, `opt harness check/doctor`, searchable activity intelligence까지 함께 닫혀 있습니다. fullscreen tool 예외도 이제 `ShellFullscreenToolSurface`로 공통 shell을 공유합니다. 현재의 초점은 기반 guard를 만드는 일이 아니라, 이 운영 기준선을 더 많은 rollout 대상과 scaffold 산출물에 반복 적용하는 것입니다.

7. Adapter Demo 경로

opt-shell의 adapter 개념은 설명보다 실제 화면에서 더 명확합니다. 아래 경로에서 엔진은 그대로 두고 harness가 주변 chrome만 가져가는 현재 데모를 확인할 수 있습니다.

8. 권장 읽기 순서

1. Mission전에 루트 `DESIGN.md`로 visual intent를 먼저 읽고, 그다음 역할과 비목표를 고정합니다.
2. 시작하기와 provider 예제로 앱 수준 정책을 연결합니다.
3. Recipes와 핵심 개념으로 화면 유형과 state boundary를 맞추고, 현재는 workspace-first abstraction을 기준으로 삼습니다.
4. Adapters와 Agent Contract로 engine 경계와 실행 규칙을 확정합니다.
5. Builder Rollout과 Rollout Playbook으로 실제 적용 증거, project screen rollout, fullscreen tool 예외, smoke proof 순서를 확인합니다.