Omd Harness

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 [ -z "$HELPER" ]; then
  OMD_DIR=$(npm root)/oh-my-design-cli
  [ -d "$OMD_DIR" ] || OMD_DIR=$(npm root -g)/oh-my-design-cli
  HELPER="$OMD_DIR/scripts/ctx-prime.cjs"
fi
[ -f "$HELPER" ] || { echo "CTX_PRIME_MISSING"; exit 0; }

node "$HELPER" "$(pwd)" "${RUN_DIR}"

성공 시 ${RUN_DIR}/ctx-prime.json 생성. ~12-50ms (typical repo). ctx-prime.cjs는 활성 host의 .codex/data/scripts/, .claude/data/scripts/, 또는 .opencode/data/scripts/에 installer가 복사하므로 패키지 dir 없이도 동작한다 (companion context.cjs도 같은 폴더에 함께 복사됨).

CTX_PRIME_MISSING (모든 local/global 경로 miss) → Step 3로 직진 (legacy path).

2.5.1b — Council-prime decision ledger (v1.9.733+)

고정된 audience + 4문항을 바로 묻지 않는다. 먼저 design-council-prime.cjs를 ctx-prime.cjs와 같은 resolution order로 찾아 실행한다:

COUNCIL_HELPER="$(dirname "$HELPER")/design-council-prime.cjs"
[ -f "$COUNCIL_HELPER" ] && node "$COUNCIL_HELPER" "$(pwd)" "${RUN_DIR}"

council/decision-ledger.json이 생성되면 이것이 intake의 단일 source of truth다. 아래 2.5.2–2.5.3 고정 picker는 실행하지 않는다.

1. auto이면서 proposed_value가 있는 항목만 prefilled_slots[slot]에 적재.
2. interview 항목만 한 번의 최대 4-question batch로 질문. ledger의 options와 reason을 사용하고 근거 없는 추천 표시는 만들지 않는다.
3. defer는 묻거나 채우지 않고 deferred_slots에 id/slot/reason을 보존.
4. blocked가 하나라도 있으면 진행하지 않고 필요한 evidence/authority만 알림. dispatch-plan.json의 dispatch_suppressed_by_blocked: true는 이미 결정론적으로 blocker가 확인됐다는 뜻이다. blocker가 풀리기 전에는 자문 agent를 호출하지 않는다.
5. auto 값과 사용자 답을 slot에 매핑해 handoff에 decision_ledger_ref: "council/decision-ledger.json"와 함께 기록.

이 분류를 host가 prose로 다시 구현하지 않는다. council helper와 같은 폴더의 design-council-handoff.cjs를 사용해 checkpoint를 materialize한다:

HANDOFF_HELPER="$(dirname "$COUNCIL_HELPER")/design-council-handoff.cjs"
[ -f "$HANDOFF_HELPER" ] && node "$HANDOFF_HELPER" "$(pwd)" "${RUN_DIR}" prepare

• status: blocked → 질문을 만들지 않고 blocking_items만 사용자에게 알린 뒤 중단.
• status: ask_user → questions_file의 product-authority 질문만 한 batch로 제시.
• state: PROPOSE_PLAN → 질문 없이 Step 3으로 진행.

checkpoint materialize 직후 같은 helper dir의 context planner를 실행한다:

CONTEXT_HELPER="$(dirname "$COUNCIL_HELPER")/design-harness-context-plan.cjs"
[ -f "$CONTEXT_HELPER" ] && node "$CONTEXT_HELPER" "$(pwd)" "${RUN_DIR}" relay

${RUN_DIR}/handoff/context-plan.json을 읽고 그대로 따른다. relay_blocked와 relay_questions는 master를 spawn하지 않고 launcher가 기존 artifact를 exact relay한다. resume_master/run_master만 master를 호출하며, sidecars에 적힌 파일만 active channel skill tree에서 추가로 읽는다. planner가 없는 legacy install에서만 master의 내장 conditional pointer를 사용한다. sidecar를 관성적으로 전부 로드하지 않는다.

질문 답은 ${RUN_DIR}/checkpoints/council-intake.answers.json에 저장한다. 답변 객체에는 handoff의 checkpoint_id, ledger_sha256, questions_sha256를 그대로 복사하고 answers 아래 decision id별 응답을 넣는다. 이 receipt가 없거나 현재 ledger/questions hash와 다르면 재질문 없이 fail-close한다. 이후 다음처럼 병합한다. helper는 모든 required interview가 답변됐을 때만 PROPOSE_PLAN을 쓴다.

node "$HANDOFF_HELPER" "$(pwd)" "${RUN_DIR}" apply \
  "${RUN_DIR}/checkpoints/council-intake.answers.json"

interview가 0개면 질문 없이 Step 3으로 간다. 이 단계는 deterministic intake 분류이며 multi-agent council이 실행됐다고 표현하지 않는다. helper 누락·실패 때만 아래 legacy path를 사용한다.

기존/current surface의 개선 작업에서 ctx-prime이 confidence 0.75 이상의 audience evidence와 단일 surface를 함께 보유하면 audience와 scope는 값을 새로 확정하지 않고 defer한다. 사용자가 action 변경을 요청하지 않았다면 primary CTA도 같은 surface evidence에 묶어 defer한다. 이 decision들은 council에도 보내지 않는다. 이는 기존 제품 방향과 행동 계약을 보존하는 것이며 unknown을 채우거나 새 사실을 auto하는 규칙이 아니다. root index.html도 하나의 실제 surface로 센다.

2.5.1c — Bounded advisory council (v1.9.735+)

council/dispatch-plan.json을 읽는다. dispatch_required: false면 agent를 호출하지 않고 2.5.1b의 ledger를 그대로 사용한다. true면 아래 계약으로 선택된 lane만, 한 번, 최대 2개 병렬 실행한다.

1. selected_lanes의 role과 decision_ids를 그대로 사용한다. 전체 역할을 관성적으로 호출하거나 선택되지 않은 쟁점을 추가하지 않는다.
2. 각 agent는 제품 파일을 수정하지 않는 read-only 자문이다. 유일한 write ownership은 council/lanes/<lane_id>.json이다.
3. 출력은 { "lane_id": "...", "claims": [...] }이고, 각 claim은 decision_id, decision_mode, authority_mode, recommendation, reason, evidence를 포함한다.
   • decision_mode: preserve-existing | choose-new | unknown
   • authority_mode: preserve-existing | user-answerable | external-unverifiable | unknown
   • 기존 audience/scope/CTA 계약을 그대로 지키는 일은 preserve-existing/defer다. 새 제품 결정을 한 것이 아니다.
   • 제품 소유자가 답할 수 있는 price/packaging/CTA/audience/scope/security/data 결정은 choose-new/user-answerable/interview다.
   • 사용자 선호로 대체할 수 없는 공식 brand source나 측정 fact 부재만 external-unverifiable/blocked다. evidence는 실제 존재하는 repo/run-relative 경로여야 한다. 인용할 근거가 없으면 claim을 만들지 않는다.
4. agent/role을 사용할 수 없거나 실행이 실패하면 재시도하거나 다른 모델의 의견을 꾸며내지 않는다. 해당 lane에 { "lane_id": "...", "status": "unavailable", "claims": [] }를 쓰고 원래 disposition을 보존한다.
5. 모든 lane 종료 뒤 council-prime과 같은 폴더의 reconciler를 한 번 실행한다:

RECONCILE_HELPER="$(dirname "$COUNCIL_HELPER")/design-council-reconcile.cjs"
[ -f "$RECONCILE_HELPER" ] && node "$RECONCILE_HELPER" "$(pwd)" "${RUN_DIR}"

이후 council/reconciled-ledger.json을 intake authority로 사용한다. council은 interview ↔ defer/blocked 범위의 자문만 할 수 있고, 이미 확정된 auto 값은 snapshot hash로 동결된다. 어떤 자문도 auto로 승격할 수 없다. blocked가 남으면 정확히 필요한 evidence/authority만 알리고 중단한다. 각 항목은 effective_disposition을 우선 사용하며 없으면 원래 disposition을 쓴다. interview만 한 번의 최대 4-question batch로 묻는다. blocked는 interview와 같은 것으로 세지 않는다. blocked는 필요한 외부 근거를 알리고 멈추며, user-answerable 결정은 blocked로 바꾸지 않고 interview에 남긴다. 실제 council/debate.json이 생성되지 않았으면 council이 실행됐다고 표현하지 않는다.

2.5.2 — Legacy: ctx-prime.json Read + 사용자 picker 게이트

Read 툴로 ${RUN_DIR}/ctx-prime.json 로드. 다음 필드만 사용자에게 한 줄로 brief:

• stack.framework, stack.kind, brand_signal.dominant_color_hex
• surface_inventory.length (몇 개 surface 발견)
• brand_signal.language (ko / en / ja)

AskUserQuestion 1개를 다음 shape로:

question: "이 레포 분석했어요 — {framework} + {dominant_color_hex} 베이스 + {N}개 surface ({language} 카피). 이번 작업의 1차 타깃 페르소나는?"
header: "Audience"
options: ctx-prime.audience_hypothesis 상위 3개 → label/description 매핑
  - audience_hypothesis[0]: label + "(추천)", description = evidence
  - audience_hypothesis[1]: label, description = evidence
  - audience_hypothesis[2]: label, description = evidence (없으면 생략)

(AskUserQuestion이 자동 "Other" 추가하므로 자유 입력 페르소나도 가능. Codex / OpenCode 등 AskUserQuestion이 없는 채널은 같은 question + option을 prose로 묻고 자유 텍스트 답을 받는다 — #21.)

사용자 답을 ctx-prime.json에 confirmed_audience 필드로 merge (Edit 또는 Write):

{
  // ... 기존 필드 ...
  "confirmed_audience": "외부 트래픽 — SEO/conversion 우선, 톤 일탈 허용"
}

2.5.3 — Legacy: Interview-lite (2-4 picker 묶음)

페르소나 확정 직후 AskUserQuestion 1번 더, 최대 4개 question 묶음. ctx-prime 결과를 활용해 picker option을 동적 구성:

채널 분기 (#21): Claude Code 채널에서는 반드시 AskUserQuestion 툴로 제시 — 복수 답이 자연스러운 question(예: wow moment 여러 개 허용 시)은 multiSelect: true. Codex / OpenCode 등 툴이 없는 채널은 같은 question 묶음을 prose 1회 배치로 묻고 자유 텍스트 답을 받는다. 어느 채널이든 question 수 budget은 동일(아래 최대 4개) — 추가 게이트 금지.

Question 1 — exit_scope:

• "단일 화면만 (한 surface 깊이)"
• "풀 랜딩 (hero + features + CTA + footer)" — 추천 (대부분의 경우)
• "다중 surface (랜딩 + product preview + docs)"

Question 2 — wow moment:

• ctx-prime.wow_moment_candidates 상위 3개 + "Other"

Question 3 — primary CTA:

• "Sign-up / Get started" — 추천 if audience=외부
• "Book demo / Contact sales"
• "GitHub star / View source"
• "View docs / Read more"

Question 4 — visual grounding:

• "Live reference capture (느림, 정확)" — 추천 if exit_scope=풀랜딩
• "Catalog-only (빠름, generic)"

답을 ${RUN_DIR}/handoff/.handoff.json에 prefilled_slots로 적재:

mkdir -p "${RUN_DIR}/handoff"
cat > "${RUN_DIR}/handoff/.handoff.json" <<EOF
{
  "state": "PROPOSE_PLAN",
  "prefilled_slots": {
    "audience": "<confirmed_audience>",
    "exit_scope": "<answer 1>",
    "wow_moment": "<answer 2>",
    "cta_primary": "<answer 3>",
    "visual_grounding": "<answer 4>"
  },
  "ctx_prime_ref": "ctx-prime.json",
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF

이 시점부터 master는 SLOT_GATE를 건너뛰고 PROPOSE_PLAN으로 직행한다 (master INTAKE 분기 참고).

2.5.4 — Backward compatibility

ctx-prime.json 누락 또는 사용자가 picker에서 "Other → 알아서 골라줘" 답하면 Step 3 (reference picker) 그대로 진행. prefilled_slots 없으면 master는 legacy SLOT_GATE 흐름.

Step 3 — DESIGN.md 존재 확인 + reference 의미 매칭

먼저 council/decision-ledger.json의 design-system-disposition을 읽는다.

• reuse → 기존 root DESIGN.md를 사용하고 reference picker를 건너뛴다.
• surface-local-only → root DESIGN.md를 만들지 않고 현재 run의 local surface contract만 사용한다. reference picker를 건너뛴다.
• establish 또는 refresh → 아래 reference 의미 매칭을 보조 evidence로 사용할 수 있다. reference는 제품 사실이나 시스템 전체를 소유하지 않는다.
• interview → checkpoint 답변 전에는 reference를 고르지 않는다.
• blocked → 중단한다.

기존 root DESIGN.md를 사용하는 경우 이 시점에 read-only format inspection을 남긴다: core-v2-bound | core-v2-portable | legacy-13 | legacy-15 | legacy-16 | unmarked | absent. 채택된 profile: portable-core manifest가 exact graph/projection hash를 검증할 때만 core-v2-bound다. migration-candidate는 named source DESIGN.md authority를 유지한다. 이 단계에서 문서를 개명·재정렬·덮어쓰지 않는다. Core v2가 아닌 입력은 Phase 5의 provider-free staged migration으로만 전환하고, dropped=0 수용 게이트를 건너뛰지 않는다.