/omd-harness

name: omd-harness
description: "사용자와 단계별로 검토하는 guided design harness. Discovery→Wireframe→Components→Microcopy→Validation을 omd-master가 실행하고 journey/system/validation의 필수 체크포인트에서 멈춘다. '/omd-harness', '체크포인트마다 검토', '나와 단계별로 디자인', 'guided design' 요청에 사용. 질문 없이 원샷으로 새 제품을 자율 구축하는 요청은 omd:autopilot, 단일 컴포넌트 수정은 omd:apply."

omd:harness — Design Harness Entry

이 스킬은 **omd-master 오케스트레이터**를 호출하는 단일 진입점이다. 본 스킬은 launcher + 사전체크 + run 디렉토리 부트스트랩 책임만 가지고, phase 로직은 `agents/omd-master.md`에 있다.

Run 디렉토리 부트스트랩에는 CLI 의존이 없다. Core v2 review/compile/adoption은 설치된 provider-free `design-md` 명령 또는 byte-equivalent helper만 사용한다.

트리거

• `/omd-harness <task>` 명시 호출
• 사용자가 자연어로 "디자인 하네스 / 체크포인트마다 검토 / 나와 단계별로 디자인" 요청

Step 0 — task 추출

슬래시에 task 같이 적었으면 (`/omd-harness 물 음용 유도 메인 화면`) 그 자연어 부분이 task. 빈 슬래시면 한 번 묻기:

어떤 디자인 작업을 진행할까요?
shape: "[도메인] + [톤/스타일] + [핵심 화면]" — 예: "토스 스타일 가족용 식단 앱 메인 화면"

task에서 delivery intent도 함께 고정한다.

• `디자인/와이어프레임/기획/시안`만 요청 → `delivery_intent: design-only`
• `구현/만들어/적용/build/implement/production-ready` 포함 → `delivery_intent: implement`

`implement`여도 mandatory checkpoint를 건너뛰지 않는다. 차이는 승인된 handoff 뒤 실제 제품 코드 통합까지 이어지는지다.

Step 1 — Channel-safe role activation + inline recovery (v1.9.0+)

먼저 Agent 도구의 사용 가능 role 목록에서 `omd-master`를 확인한다. 있으면 Step 2로 간다. 없을 때는 Markdown을 임의 폴더에 복사하지 않는다. Claude와 Codex의 role schema가 다르고, `.agents/`는 Codex에서 skill 경로이지 role 경로가 아니다.

1.1 — 현재 채널과 설치물 검증

• 이 스킬이 `.agents/skills/omd-harness/`에서 로드됐거나 `.codex/agents/omd-master.toml`이 있으면 **Codex**다. role 파일은 `.codex/agents/omd-master.toml`이어야 하며 top-level `name`, `description`, `developer_instructions`가 모두 있어야 한다.
• 이 스킬이 `.claude/skills/omd-harness/`에서 로드됐거나 `.claude/agents/omd-master.md`가 있으면 **Claude Code**다. role 파일은 첫 줄이 `---`인 `.claude/agents/omd-master.md`여야 한다.
• 이 스킬이 `.opencode/skills/omd-harness/`에서 로드됐거나 `.opencode/agents/omd-master.md`가 있으면 **OpenCode**다. project role은 `.opencode/agents/omd-master.md`, global role은 `~/.config/opencode/agents/omd-master.md`이며 `mode: subagent`여야 한다.
• 폴더가 존재한다는 이유만으로 채널을 추측하지 않는다. 둘 다 없거나 모호하면 사용자에게 현재 coding-agent 채널 하나만 확인한다.

role 파일이 없거나 schema가 틀렸으면 해당 채널만 최신 설치기로 복구한다:

# <channel> = claude-code, codex 또는 opencode
npx oh-my-design-cli@latest install-skills --agent <channel> --all
npx oh-my-design-cli@latest doctor

Codex의 legacy `.codex/skills` OmD entrypoint는 최신 설치기가 안전하게 제거하고 공식 `.agents/skills` 경로로 옮긴다. 사용자 소유 파일은 삭제하지 않는다.

1.2 — 현재 세션에서 role 목록이 stale인 경우

설치 파일이 유효해도 이미 실행 중인 세션의 Agent 목록은 즉시 갱신되지 않을 수 있다. 이 경우 작업을 중단하거나 잘못된 형식으로 복사하지 말고:

1. 유효한 role 파일을 Read한다. Codex는 `developer_instructions`, Claude Code는 frontmatter 뒤 body를 읽는다. 2. 현재 main agent가 그 지침을 **inline omd-master persona**로 채택해 이번 run을 계속한다. 3. 사용자에게는 한 줄만 알린다: `역할 파일은 복구됐고, 이번 작업은 inline으로 계속해요. 다음 세션부터 전용 role이 자동 로드됩니다.` 4. 다음 새 세션을 위해 Codex는 project trust가 필요하고, 두 채널 모두 설치/업그레이드 후 재시작이 필요하다는 점을 마지막 handoff에 남긴다.

Step 4에서 전용 role spawn이 여전히 불가능하면 inline persona가 같은 phase/state/checkpoint 계약을 직접 실행한다. 산출물이나 사용자 checkpoint를 생략하지 않는다.

Step 2 — Run 디렉토리 부트스트랩 (인라인 Bash)

이전엔 `omd harness "<task>" --internal` CLI를 호출했지만 1.0.0부터는 스킬이 직접 한다. 결정론적 hard verify gate:

2.1 기존 run 재사용 체크

ls -t .omd/runs 2>/dev/null | head -1

출력 있으면 그 디렉토리의 `task.md`를 Read해서 사용자 task와 의미적으로 일치하는지 확인. 일치하면 그 run 재사용 — Step 3으로 점프.

2.2 신규 run 부트스트랩

다음을 **반드시 정확히 이 순서로** Bash 툴로 실행:

# 2.2.1 — timestamp + slug 결정 (한국어 보존)
TS=$(node -e "console.log(new Date().toISOString().replace(/[:.]/g,'-'))")
SLUG=$(node -e "
const s = process.argv[1].toLowerCase().trim()
  .replace(/[^a-z0-9가-힣\s-]+/g,'')
  .replace(/\s+/g,'-')
  .replace(/-+/g,'-')
  .replace(/^-|-$/g,'');
console.log(s.slice(0,40) || 'untitled');
" "<EXTRACTED_TASK>")
RUN_ID="run-${TS}-${SLUG}"
RUN_DIR=".omd/runs/${RUN_ID}"

# 2.2.2 — 표준 서브폴더 생성
mkdir -p "${RUN_DIR}"/{wireframes,components,assets/briefs,assets/fallback,assets/pinterest-refs,eval/screenshots,persona-feedback,handoff,checkpoints}

# 2.2.3 — task.md
cat > "${RUN_DIR}/task.md" <<EOF
# Harness Task

<EXTRACTED_TASK>

---

- run_id: \`${RUN_ID}\`
- started_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
- cwd: \`$(pwd)\`
EOF

# 2.2.4 — run.log
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] run initialized" > "${RUN_DIR}/run.log"

# 2.2.5 — .omd/.gitignore (idempotent)
mkdir -p .omd
[ -f .omd/.gitignore ] || printf "runs/\ncache/\n" > .omd/.gitignore

# 2.2.6 — INDEX.md (idempotent header + append)
INDEX=".omd/runs/INDEX.md"
[ -f "${INDEX}" ] || cat > "${INDEX}" <<EOF
# Harness Runs Index

One line per run. Append-only.

EOF
TASK_ONELINE=$(echo "<EXTRACTED_TASK>" | tr '\n' ' ' | cut -c1-120)
echo "- $(date -u +%Y-%m-%dT%H:%M:%SZ) \`${RUN_ID}\` — ${TASK_ONELINE}" >> "${INDEX}"

# 2.2.7 — 결과 출력 (이 스킬이 파싱)
echo "RUN_DIR=${RUN_DIR}"
echo "RUN_ID=${RUN_ID}"

2.3 Hard verify gate (master spawn 차단 조건)

부트스트랩 다음, master spawn 전에 반드시:

test -d "${RUN_DIR}" && test -f "${RUN_DIR}/task.md" && echo "OK" || echo "FAIL"

`OK`가 출력되지 않으면 master는 절대 spawn하지 않는다. 사용자에게:

하네스 부트스트랩이 실패했어요 (run dir or task.md 누락). 디스크 권한·경로 문제일 수 있어요. 다시 시도하거나 .omd/ 디렉토리를 정리해주세요.

이 gate를 통과해야만 Step 2.5로.

Step 2.5 — CTX-PRIME — 코드베이스 자동 분석 (v1.6.0+)

reference를 고르라고 사용자에게 묻기 전에 **먼저 레포를 본다**. 사용자가 듣고 싶은 첫 문장은 "이 레포 분석했어요 — Next.js 14 + 토스 블루 + 4개 surface" 같은 *진단*이지 "어느 레퍼런스 골라드릴까요?"가 아니다.

2.5.1 — ctx-prime helper 실행

# HELPER resolution (먼저 존재하는 것 사용):
#   1. .codex/data/scripts/ctx-prime.cjs    ← Codex installer copy
#   2. .claude/data/scripts/ctx-prime.cjs   ← Claude Code / Cursor installer copy
#   3. .opencode/data/scripts/ctx-prime.cjs ← OpenCode installer copy
#   4. node_modules/oh-my-design-cli/scripts/ctx-prime.cjs  (로컬 npm 설치)
#   5. $(npm root -g)/oh-my-design-cli/scripts/ctx-prime.cjs (global)
HELPER=""
for CANDIDATE in \
  ".codex/data/scripts/ctx-prime.cjs" \
  ".claude/data/scripts/ctx-prime.cjs" \
  ".opencode/data/scripts/ctx-prime.cjs"; do
  if [ -f "$CANDIDATE" ]; then HELPER="$CANDIDATE"; break; fi
done
if [