omu

name	omu
description	OMU - Integrated AI agent orchestration skill for Unity3D game development. Manages game lifecycle (기획→개발→QA→수익성) via .omu folder, plan with ralph+plannotator, execute with team/bmad, verify with unity-mcp, and auto-cleanup. Supports Claude, Codex, Gemini CLI, and OpenCode.
compatibility	Requires git, node>=18, bash. Optional: bun, docker.
allowed-tools	Read Write Bash Grep Glob Task
metadata	{"tags":"omu, orchestration, ralph, plannotator, team, bmad, omc, omx, ohmg, agent-browser, multi-agent, workflow, worktree-cleanup, browser-verification, game-lifecycle, planning-docs","platforms":"Claude, Codex, Gemini, OpenCode","keyword":"omu","version":"2.1.0","source":"akillness/oh-my-unity3d"}

OMU - Integrated Agent Orchestration

Keyword: omu | Platforms: Claude Code, Codex CLI, Gemini CLI, OpenCode

Workflow: Plan (ralph + plannotator) -> Execute (team or bmad) -> Verify (unity-mcp / agent-browser) -> Cleanup (worktree-cleanup)

Game Lifecycle: 기획 (Plan) → 개발 (Execute) → QA (Verify) → 수익성 (Monetize)

OMU is the release-oriented orchestration skill package shipped in this repository. It standardizes one path through planning, implementation, Unity3D verification, and worktree cleanup across the supported AI coding tools.

The .omu/ folder is the persistent game project management hub — long-term plans, short-term sprints, progress tracking, and history archiving are all managed here across OMU workflow runs.

agentation, annotate, and agentui are intentionally removed in v2.0.0. UI review is handled with agent-browser snapshots and normal edit loops only.

Quick Start

bash scripts/install.sh --all
bash scripts/check-status.sh

Then activate OMU with a task statement such as omu "ship the inventory prototype" and follow the gated PLAN -> EXECUTE -> VERIFY -> CLEANUP flow.

When to use this skill

• When the user wants a Unity3D-oriented orchestration flow spanning planning, execution, verification, and cleanup
• When the task should combine ralph, plannotator, team or bmad, browser verification, and optional Unity MCP verification
• When the user invokes omu or asks for a release-oriented, cross-platform game-development workflow

Instructions

Execution contract

Run the phases in order. Do not skip PLAN. Do not enter EXECUTE without an approved plan.

Unity3D 모드 (unity-mcp 감지)

Before starting PLAN, check unity-mcp availability:

curl -sf http://localhost:8080/health >/dev/null 2>&1 && echo "unity-mcp: available" || echo "unity-mcp: not available"

If available (exit 0): activate Unity3D verification loop in VERIFY phase. If unavailable: use standard agent-browser verification.

STEP 0: Bootstrap

Create the working state directories:

mkdir -p .omc/state .omc/plans .omc/logs

---

STEP 0.1: .omu Game Plan Bootstrap

Before planning, check and initialize the .omu/ game management folder.

0.1a — Create .omu/ if it doesn't exist

if [ ! -d ".omu" ]; then
  mkdir -p .omu/history
  echo "(.omu folder created — populate long-term-plan.md and short-term-plan.md)"
fi

If .omu/long-term-plan.md does not exist, create it from the template at .unity-skills/omu/templates/.omu/long-term-plan.md (or use the built-in template below).

0.1b — Read existing plans

Read all .omu/ documents in parallel and build context:

File	Purpose	Action
.omu/long-term-plan.md	기획 컨셉, 규칙, 게임성	Read → extract current concept and constraints
.omu/short-term-plan.md	시스템, 밸런스, 배치, 연출	Read → identify sprint scope and backlog
.omu/progress.md	진행내용 체크리스트	Read → find unchecked items and blockers

0.1c — Detect current game development stage

Based on .omu/progress.md content, detect and log the active stage:

기획 (Planning)  → GDD not complete, concept not finalized
개발 (Development) → Core loop implemented, systems in progress
QA (Quality Assurance) → Implementation complete, testing in progress
수익성 (Monetization) → QA passed, analytics/IAP integration in progress

Update .omc/state/omu-state.json:

{
  "game_stage": "기획 | 개발 | QA | 수익성",
  "omu_docs_loaded": true
}

User-facing message:

OMU activated. Game Stage: [stage]. Phase: PLAN. Plan docs loaded from .omu/ — [N] pending items found.

If .omc/state/omu-state.json does not exist, create it with:

{
  "mode": "omu",
  "phase": "plan",
  "task": "<detected task>",
  "plan_approved": false,
  "plan_gate_status": "pending",
  "team_available": null,
  "retry_count": 0,
  "last_error": null,
  "checkpoint": null,
  "created_at": "<ISO 8601>",
  "updated_at": "<ISO 8601>"
}

User-facing activation message:

OMU activated. Phase: PLAN.

STEP 0.1: Recovery Rules

• Update checkpoint whenever a phase starts.
• Update last_error and increment retry_count before failing pre-flight.
• Resume from .omc/state/omu-state.json if a prior run already exists:
  • phase=plan → re-run plannotator gate if plan_approved=false
  • phase=execute → skip PLAN, resume from last implementation checkpoint
  • phase=verify → skip PLAN+EXECUTE, re-run verification commands
  • phase=cleanup → run cleanup script, then mark done
• If retry_count >= 3, stop and ask the user whether to continue.

---

1. PLAN

PLAN is mandatory in every OMU run.

Required output

Write plan.md with:

• goal
• implementation steps
• risks
• completion criteria

Required plan gate

Run the blocking plannotator loop:

bash scripts/plannotator-plan-loop.sh plan.md /tmp/plannotator_feedback.txt 3

Rules:

• Never use &.
• If plannotator is missing, auto-run bash scripts/ensure-plannotator.sh first.

Exit code handling:

• exit 0 → approved=true → proceed to EXECUTE
• exit 10 → approved=false (feedback) → update plan.md and re-run the loop
• exit 32 → plannotator unavailable (non-interactive env, port conflict, or install failure) → HALT: do NOT proceed to EXECUTE. Output: "⚠️ PLAN GATE: plannotator가 필요합니다. bash scripts/ensure-plannotator.sh 실행 후 재시도하세요." TUI 폴백은 비활성화되어 있습니다. plannotator 없이 plan을 승인할 수 없습니다.

When approved, update the state file:

{
  "phase": "execute",
  "plan_approved": true,
  "plan_gate_status": "approved"
}

---

2. EXECUTE

OMU supports two execution paths.

Claude Code

Use team execution:

/omc:team 3:executor "<task>"

OMU expects CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Codex, Gemini CLI, OpenCode

Use BMAD as the fallback orchestration path:

/workflow-init
/workflow-status

Execution rule:

• keep the implementation aligned to the approved plan
• update phase to execute
• return to PLAN only if the plan is invalidated by new information

When execution is complete, update the state file:

{
  "phase": "verify",
  "checkpoint": "execute-complete"
}

.omu Progress Update (EXECUTE 단계 완료 시)

After each completed task during EXECUTE, update .omu/progress.md:

1. Mark completed items with - [x]
2. Add newly discovered tasks under the appropriate section
3. Update short-term-plan.md if sprint scope changes

# Example: mark a system as complete
# .omu/progress.md: "- [ ] 코어 루프 구현" → "- [x] 코어 루프 구현"

New short-term tasks discovered during execution should be appended to .omu/short-term-plan.md under Backlog.

---

3. VERIFY

Use browser verification when the task includes UI or browser behavior.

Primary command:

agent-browser snapshot http://localhost:3000

Useful follow-ups:

agent-browser screenshot http://localhost:3000 -o verify.png
playwriter --help

Verification rule:

• confirm the changed behavior, not only page load
• capture evidence before cleanup when the task is browser-facing
• keep the state file in phase = "verify" until verification is complete

When verification passes, update the state file:

{
  "phase": "cleanup",
  "checkpoint": "verify-complete"
}

STEP 3: VERIFY — Unity3D 검증 루프

Unity3D 모드가 활성화된 경우 브라우저 검증 대신 아래 루프를 실행합니다.

① unity-mcp: run_tests → pass/fail 집계 ② unity-mcp: read_console → Error/Exception 패턴 탐지 ③ unity-mcp: editor_state → 씬 로드 상태 확인 ④ unity-mcp: find_gameobjects → 필수 오브젝트 확인

검증 결과:

• 모두 통과 → CLEANUP
• 실패 → Fix 루프 (code-refactoring 또는 unity-mcp: validate_script → 재검증, 최대 3회)
• 3회 초과 → 사용자 확인 요청

omu-state.json 업데이트:

{ "unity_verify": { "tests_passed": true, "console_errors": 0, "retry_count": 0 } }

---

4. CLEANUP

After verification, guard against uncommitted changes:

# Guard: warn if uncommitted changes exist
if ! git diff --quiet || ! git diff --cached --quiet; then
  echo "[OMU][CLEANUP] ⚠️ Uncommitted changes detected. Commit or stash before cleanup."
  git status --short
  exit 1
fi

Then run cleanup:

bash scripts/worktree-cleanup.sh || git worktree prune

Then set:

{
  "phase": "done",
  "checkpoint": "cleanup"
}

Cleanup rule:

• warn before cleanup if there are uncommitted changes
• clean extra worktrees only
• never delete unrelated user work

.omu Archive (CLEANUP 단계)

Archive completed work from .omu/ to history:

# 1. Generate archive filename
ARCHIVE_DATE=$(date +%Y%m%d)
ARCHIVE_FILE=".omu/history/${ARCHIVE_DATE}-$(echo "$TASK" | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | head -c 40).md"

# 2. Extract completed items from progress.md (lines with [x])
grep -E "^\s*- \[x\]" .omu/progress.md > /tmp/completed_items.txt

# 3. Write archive entry
cat > "$ARCHIVE_FILE" << EOF
# Archive: $TASK
**Date**: $ARCHIVE_DATE
**Stage**: $(jq -r '.game_stage' .omc/state/omu-state.json)
**Sprint**: (from short-term-plan.md)

## Completed Items
$(cat /tmp/completed_items.txt)

## Notes
(Add retrospective notes here)
EOF

# 4. Remove completed items from progress.md
sed -i '' '/^\s*- \[x\]/d' .omu/progress.md

# 5. Remove completed items from short-term-plan.md
sed -i '' '/^\s*- \[x\]/d' .omu/short-term-plan.md

.omu/ post-cleanup state:

• progress.md — only unchecked (- [ ]) items remain
• short-term-plan.md — backlog updated, completed sprint items removed
• history/YYYYMMDD-<task>.md — permanent record of what was done

---

Examples

Unity3D 워크플로우 예제

Workflow 1: 게임 기획 → 씬 프로토타이핑

omu "씬 프로토타이핑: <게임명>"
  [PLAN]     bmad-gds-brainstorm-game → bmad-gds-gdd
  [EXECUTE]  unity-mcp: manage_scene → manage_gameobject → manage_probuilder
  [VERIFY]   unity-mcp: run_tests → read_console → editor_state → Fix 루프 (max 3)
  [CLEANUP]

Workflow 2: 스프린트 스토리 → C# 구현

omu "스토리 구현: <스토리명>"
  [PLAN]     bmad-gds-sprint-planning → bmad-gds-create-story
  [EXECUTE]  bmad-gds-dev-story → unity-mcp: create_script → validate_script → script_apply_edits
  [VERIFY]   unity-mcp: run_tests → read_console → Fix 루프 → bmad-gds-code-review
  [CLEANUP]

Workflow 3: 에셋 파이프라인 자동화

omu "에셋 파이프라인: <에셋 종류>"
  [PLAN]     file-organization
  [EXECUTE]  unity-mcp: manage_asset → manage_texture → manage_material → manage_prefabs → batch_execute
  [VERIFY]   unity-mcp: read_console → run_tests → performance-optimization → Fix 루프
  [CLEANUP]

Workflow 4: Unity UI/비주얼 개발

design-system (Unity3D Design Guide 탐색)
  → ui-component-patterns → unity-mcp: manage_ui → manage_animation → manage_vfx
  → [VERIFY] unity-mcp: run_tests → read_console

Workflow 5: 성능 최적화 & 디버깅

omu "성능 최적화: <증상>"
  [PLAN]     log-analysis (unity-mcp: read_console) → find_gameobjects → codebase-search
  [EXECUTE]  performance-optimization → unity-mcp: manage_components → batch_execute
  [VERIFY]   unity-mcp: run_tests → read_console → bmad-gds-performance-test → Fix 루프
  [CLEANUP]

---

6. Quick Start

Install dependencies and helpers

bash scripts/install.sh --all

Check current environment

bash scripts/check-status.sh

Configure each platform

bash scripts/setup-claude.sh
bash scripts/setup-codex.sh
bash scripts/setup-gemini.sh
bash scripts/setup-opencode.sh

---

7. Installed Components

Tool	Purpose
omc	Claude Code team orchestration
omx	OpenCode orchestration
ohmg	Gemini multi-agent support
bmad	Fallback workflow orchestration
ralph	specification-first planning loop
plannotator	blocking plan review gate
agent-browser	browser verification
playwriter	optional browser automation helper

---

8. Platform Notes

Claude Code

• setup-claude.sh enables team mode and plannotator review hooks.
• OMU does not fall back to single-agent execution in Claude Code.

Codex CLI

• setup-codex.sh writes developer_instructions, /prompts:omu, and a PLAN_READY notify hook.

Gemini CLI

• setup-gemini.sh installs a plannotator-oriented AfterAgent helper and appends OMU guidance to GEMINI.md.

OpenCode

• setup-opencode.sh registers plugins and slash commands for plan, execute, verify, and cleanup.

---

9. State File

Path:

.omc/state/omu-state.json

Example:

{
  "mode": "omu",
  "phase": "verify",
  "task": "Ship the OMU release package",
  "plan_approved": true,
  "plan_gate_status": "approved",
  "team_available": false,
  "retry_count": 0,
  "last_error": null,
  "checkpoint": "verify",
  "created_at": "2026-03-09T00:00:00Z",
  "updated_at": "2026-03-09T00:00:00Z"
}

---

10. Troubleshooting

Problem	Action
plannotator unavailable	Run bash scripts/ensure-plannotator.sh or bash scripts/install.sh --with-plannotator
Claude team execution unavailable	Run bash scripts/setup-claude.sh, restart Claude Code, confirm CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Codex prompt not found	Re-run bash scripts/setup-codex.sh
Gemini hook missing	Re-run bash scripts/setup-gemini.sh
Browser verification unavailable	Install agent-browser with bash scripts/install.sh --with-browser
Worktrees remain after completion	Run bash scripts/worktree-cleanup.sh and then git worktree prune

---

11. Release Notes

v2.0.0

• removed agentation integration from the skill contract
• removed annotate and agentui workflow branches
• simplified verification around agent-browser
• aligned setup scripts and docs to the reduced release surface