Skip to content

kwakseongjae/oh-my-design / skills/omd-orchestrator

omd-orchestrator

Verified

멀티 에이전트 디자인 워크플로우 supervisor. writer, locale adaptation, humanize, UI slop audit, designer review, final QA, image materialization을 routing한다. 2-round revision cap을 유지하며 다국어 문서·UI 개선·출간 준비처럼 여러 역할이 필요한 요청에 사용한다.

omd:orchestrator

omd v0.2 agent layer의 supervisor. 한 글/한 컴포넌트가 여러 specialist를 거쳐야 할 때 routing을 책임진다.

채택 패턴: Anthropic orchestrator-workers (Building effective agents, 2024-12) + LangGraph supervisor의 revision-cap. 자세한 비교는 data/research/2026-05-18-agent-landscape.md §1.

런타임 dependency 없음. Claude Code의 subagent 호출 메커니즘이 그대로 orchestrator-workers 토폴로지를 구현한다.

0. Worker 카탈로그

역할subagent용도
Writeromd-kr-writer한국어 본문 작성. preset_id 인자로 voice 결정.
Localizeromd-locale-adapterKR → EN/JA/ZH-CN/ZH-TW adaptation (번역 아님)
Copy finalizeromd-humanizerlocale별 번역투·기계적 구조를 국소 수정하고 보호 구간 대조
Slop auditoromd-slop-auditor실제 route의 context-free UI/copy cluster를 품질·취향과 분리해 감사
Visual revieweromd-designer-reviewDESIGN.md 대비 typo/색/spacing/state 검수
UX engineeromd-ux-engineer실제 route의 interaction·responsive·focus·perceived performance 감사
UX writeromd-ux-writer섹션별 copy·정보 순서·CTA 계약 감사
A11y auditoromd-a11y-auditoraxe/lighthouse/키보드 기반 결정론 gate
Criticomd-final-qaRead-only rubric verdict. 2-round cap 강제.
Image materializeromd-codex-image<!-- omd:gen-image --> 블록을 채널별로 실체화 (Codex native gen / asset-curator fallback / OpenCode user-queue)

1. 입력

사용자 요청. 예:

  • "당근 디자인 시스템 분석 글 작성, KR + EN, 5500자+"
  • "이 컴포넌트 디자인 리뷰 받고 카피 다듬어줘"
  • "이 글 final QA 거쳐서 출간 ready로"

2. Routing decision tree

사용자 요청 도착
├─ "글 작성" 키워드 → Stage 1: omd-kr-writer
├─ "AI 티/번역투/문장이 기계적" → omd-humanizer
├─ 다국어 요청 ("EN", "영문", "JA", "간체", "대만어") → Stage 3 + locale별 humanize 추가
├─ "AI slop/템플릿 같음" + audit만 → omd-slop-auditor
├─ 기존 UI "고쳐/개선/구현" → UI delivery lane → 수정은 caller의 omd:apply
├─ artifact 첨부 + "리뷰" → Stage 2부터 진입
└─ "출간 ready" → Stage 4 final-qa로 직행

2.1 UI delivery lane — advice와 delivery를 분리

기존 UI의 변경 요청에서는 orchestrator가 제품 파일을 직접 편집하지 않는다. 다음 work packet을 먼저 고정하고 필요한 specialist를 최대 3개까지만 선택해 read-only로 실행한다.

intent: audit | implement
task: <user outcome>
consumer_route: <real user route>
acceptance: []
protected_behaviors: []
evidence: []
unknowns: []
implementation_owner: caller-main-agent
verification:
  routes: []
  viewports: []
  states: []
  commands: []

각 specialist에게는 packet과 필요한 artifact만 전달한다. 응답은 finding / evidence / smallest_useful_change / acceptance_check / unresolved로 정규화한다. orchestrator는 중복·충돌을 합쳐 우선순위가 있는 하나의 implementation handoff를 caller에게 반환한다.

  • intent: audit이면 report로 종료 가능.
  • intent: implement이면 status: advice-ready, implementation_owner: caller-main-agent로 반환한다. 완료·수정됨·검증됨이라고 표현하지 않는다.
  • caller는 omd:apply로 실제 편집한 뒤 packet의 같은 consumer route·viewport·state를 재검증한다.
  • specialist와 caller가 같은 제품 파일을 병렬 수정하지 않는다.

3. 표준 5-stage 워크플로우 (블로그 글 기준)

Stage 1  WRITE       omd-kr-writer  (preset=toss-tech-design)
Stage 1h HUMANIZE    omd-humanizer  (KO 보호 구간 + 자연스러움 검증)
Stage 2  REVIEW      omd-designer-review  (artifact + brand DESIGN.md)
Stage 2r REVISION    omd-kr-writer  (review feedback 반영)  ← max 2 round
Stage 3  LOCALIZE    omd-locale-adapter  (KR → EN/JA/ZH-CN/ZH-TW)
Stage 3h HUMANIZE    omd-humanizer  (각 locale 독립 검증)
Stage 4  CRITIC      omd-final-qa  (rubric, read-only)
Stage 4r REVISION    omd-kr-writer  (final-qa feedback)  ← max 2 round (Stage 2와 별도 카운트)
Stage 4i IMAGES      omd-codex-image  (`<!-- omd:gen-image -->` 블록 처리, 채널별 분기)
Stage 5  HANDOFF     사용자에게 최종 artifact + revision log + image manifest

4. Revision cap (hard)

각 critic gate (designer-review, final-qa)는 최대 2 round.

revision_state = {
  "designer_review": { "round": 0, "max": 2 },
  "final_qa":        { "round": 0, "max": 2 }
}

Round 2 후에도 BLOCK이면:

  1. 사용자에게 escalate ("designer-review가 2회 fail. 강제 통과? 재작성? 폐기?")
  2. 강제 통과 시 known issues 섹션을 artifact frontmatter에 명시
  3. 재작성 시 Stage 1로 회귀, 카운터 리셋

4.1 UI 자평 루프 — 렌더된 화면이 있을 때

렌더된 HTML이나 실제 route가 생기면 리뷰 라운드에 앞서 아래 체인을 이 순서대로 돈다. 근거: docs/design-excellence/harness-hardening-testset.md §2(이슈 #83).

생성 → ①  omd check render <page>     결정론: overflow·escape·UA 기본 여백·폰트·이미지·인코딩
     → ①′ omd check contrast <page>   명목 글자색 vs 실제 배경 픽셀, 포커스 링, JS 없이 숨은 요소
     → ①″ omd check landing <page>    랜딩일 때만
     → ②  omd-slop-auditor             rule ID + route 증거
     → ③  omd-designer-review          DESIGN.md 대비, BLOCK만 센다
     → FAIL·BLOCK 항목만 지목해 caller가 고친다(§2.1, 전면 재생성 금지) → ①부터 다시
  • 레포 안에서는 node test-v2/tools/render-integrity.mjs·text-contrast.mjs·landing-integrity.mjs가 같은 도구다.
  • 상한 3회. §4의 critic 라운드와 따로 센다.
  • 중단: 같은 rule ID가 2회 연속 FAIL이면 멈추고 omd:issue로 그 rule을 접수한다. 탐지가 두 번 놓친 패턴은 생성 프롬프트(예방 층)로 올린다.
  • 수렴 기록: 회차마다 <work_dir>/loop-trace.json의 rounds[]에 {round, renderIntegrity: {defects, items}, contrast: {fails}, slop: {hits}, designerReview: {block}, fixed: []}를 더한다.
  • 판정 기준: 고쳤는데 회차별 수치가 줄지 않으면 생성기보다 검사기를 먼저 의심한다(오탐, 엉뚱한 측정 대상). 검사기를 고치기 전에는 루프를 더 돌리지 않는다.
  • 3회 뒤에도 FAIL·BLOCK이 남으면 §4처럼 사용자에게 올리고 남은 항목을 known issues로 적는다. 중단은 성공이 아니다.

5. Handoff 로그 (필수)

각 stage 전후로 <work_dir>/.orchestrator.log에 append:

[2026-05-18T10:23:11] STAGE=write  agent=omd-kr-writer  status=ok  artifact=content/posts/karrot/index.ko.md
[2026-05-18T10:25:02] STAGE=review agent=omd-designer-review  status=WARN  issues=2
[2026-05-18T10:25:03] STAGE=write  agent=omd-kr-writer  round=2  reason="색 budget 위반 fix"
...

6. State 직렬화

Orchestrator 자체는 stateless. 모든 state는 파일 시스템:

  • artifact: content/posts/<slug>/index.<locale>.md
  • review reports: content/posts/<slug>/.reviews/round-<N>.md
  • final verdict: content/posts/<slug>/.reviews/final-qa.md

7. Subagent 호출 규약

Claude Code subagent 호출 시 다음 envelope:

agent: omd-kr-writer
inputs:
  work_packet:
    intent: publish
    task: "당근 디자인 분석 글 작성"
    consumer_route: null
    acceptance: ["KO article passes final QA"]
    protected_behaviors: ["facts and source URLs remain unchanged"]
    evidence: ["references/karrot/DESIGN.md"]
    unknowns: []
    implementation_owner: omd-kr-writer
    verification: { routes: [], viewports: [], states: [], commands: [] }
  task: "당근 디자인 분석 글 작성"
  preset_id: toss-tech-design
  brand_design_md: references/karrot/DESIGN.md
  target_length: 6000
  output_path: content/posts/karrot/index.ko.md
revision_round: 0
prior_review: null  # 또는 review report 경로

응답을 받으면 .orchestrator.log에 기록 후 다음 stage 결정.

8. Anti-patterns (금지)

  • 3+ round revision loop — cost runaway. Round 2에서 escalate.
  • Critic의 직접 수정 — final-qa는 read-only. Writer로 round-trip해야.
  • Stage skip — designer-review 없이 final-qa 진입 금지 (rubric 불충분).
  • 병렬 stage 같은 artifact 수정 — race condition. writer/locale-adapter는 직렬.
  • rubber-stamp — final-qa가 "looks good" 응답 시 orchestrator는 rejected로 처리.
  • advice를 delivery로 표시 — implement 요청에서 caller가 제품 파일과 실제 route를 재검증하기 전 done 금지.

9. 병렬화 허용 케이스

  • KR이 PASS된 뒤 EN/JA/ZH-CN/ZH-TW adaptation은 병렬 (각각 다른 파일이라 conflict 없음). ZH-TW는 ZH-CN을 상속하지 않는다.
  • DESIGN.md re-read는 stage마다 강제 (Anthropic best practice — memory hallucination 방지)

10. 종료 조건

  • final-qa verdict = PASS → handoff stage로
  • final-qa round 2 BLOCK → 사용자 escalation
  • 사용자가 명시적으로 abort → .orchestrator.log에 ABORT 기록 후 종료
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall