# If omg-state.json already exists, resume from checkpoint
python3 -c "
import json, os, subprocess
try:
root = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], stderr=subprocess.DEVNULL).decode().strip()
except:
root = os.getcwd()
f = os.path.join(root, '.omc/state/omg-state.json')
if os.path.exists(f):
d=json.load(open(f))
cp=d.get('checkpoint')
err=d.get('last_error')
if err: print(f'Previous error: {err}')
if cp: print(f'Resuming from: {cp}')
" 2>/dev/null || true
Rule : Before exit 1 in pre-flight, always update last_error and increment retry_count. If retry_count >= 3, ask the user whether to abort.
STEP 1: PLAN (never skip)
Pre-flight (required before entering):
# Record checkpoint
python3 -c "
import json,datetime,os,subprocess,fcntl,tempfile
try:
root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip()
except:
root=os.getcwd()
f=os.path.join(root,'.omc/state/omg-state.json')
if os.path.exists(f):
with open(f,'r+') as fh:
fcntl.flock(fh,fcntl.LOCK_EX)
try:
d=json.load(fh)
d.update({'checkpoint':'plan','updated_at':datetime.datetime.utcnow().isoformat()+'Z'})
fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate()
finally:
fcntl.flock(fh,fcntl.LOCK_UN)
" 2>/dev/null || true
# NOTE: Claude Code — skip this entire bash block.
# plannotator is a hook-only binary; calling it directly always fails.
# For Claude Code: call EnterPlanMode → write plan → call ExitPlanMode.
# The ExitPlanMode PermissionRequest hook fires plannotator automatically.
# The following script is for Codex / Gemini / OpenCode only.
# GUARD: enforce no-repeat PLAN review by plan hash.
# same hash + terminal gate status => skip reopening the plan gate
# revised plan.md content => reset gate to pending and review again
PLAN_GATE_STATUS=$(python3 -c "
import json, os
try:
s = json.load(open('.omc/state/omg-state.json'))
print(s.get('plan_gate_status', 'pending'))
except Exception:
print('pending')
" 2>/dev/null || echo "pending")
HASH_MATCH=$(python3 -c "
import hashlib, json, os
try:
s = json.load(open('.omc/state/omg-state.json'))
if not os.path.exists('plan.md'):
print('no-match')
else:
current_hash = hashlib.sha256(open('plan.md', 'rb').read()).hexdigest()
print('match' if current_hash == (s.get('last_reviewed_plan_hash') or '') else 'no-match')
except Exception:
print('no-match')
" 2>/dev/null || echo "no-match")
if [[ "$HASH_MATCH" == "match" && "$PLAN_GATE_STATUS" =~ ^(approved|manual_approved|feedback_required|infrastructure_blocked)$ ]]; then
echo "✅ Current plan hash already has gate result: $PLAN_GATE_STATUS. Do not reopen plannotator."
exit 0
fi
# plannotator is mandatory for the PLAN step (Codex/Gemini/OpenCode).
# If missing, OMG auto-installs it before opening the PLAN gate.
# Resolve the OMG scripts directory (works from any CWD)
_OMG_SCRIPTS=""
for _candidate in \
"${OMG_SKILL_DIR:-}/scripts" \
"$HOME/.agent-skills/omg/scripts" \
"$HOME/.codex/skills/omg/scripts" \
"$(pwd)/.agent-skills/omg/scripts" \
"scripts" \
; do
if [ -f "${_candidate}/plannotator-plan-loop.sh" ]; then
_OMG_SCRIPTS="$_candidate"
break
fi
done
if [ -z "$_OMG_SCRIPTS" ]; then
echo "❌ OMG scripts not found. Re-run: bash setup-codex.sh (or setup-gemini.sh)"
exit 1
fi
if ! bash "${_OMG_SCRIPTS}/ensure-plannotator.sh"; then
echo "❌ plannotator auto-install failed: cannot proceed with PLAN step."
echo " Retry: bash ${_OMG_SCRIPTS}/../scripts/install.sh --with-plannotator"
exit 1
fi
# Required PLAN gate (Codex / Gemini / OpenCode):
# - Must wait until approve/feedback is received
# - Auto-restart on session exit (up to 3 times)
# - After 3 exits, ask user whether to end PLAN
FEEDBACK_DIR=$(python3 -c "import hashlib,os; h=hashlib.md5(os.getcwd().encode()).hexdigest()[:8]; d=f'/tmp/omg-{h}'; os.makedirs(d,exist_ok=True); print(d)" 2>/dev/null || echo '/tmp')
FEEDBACK_FILE="${FEEDBACK_DIR}/plannotator_feedback.txt"
bash "${_OMG_SCRIPTS}/plannotator-plan-loop.sh" plan.md "$FEEDBACK_FILE" 3
PLAN_RC=$?
if [ "$PLAN_RC" -eq 0 ]; then
echo "✅ Plan approved"
elif [ "$PLAN_RC" -eq 10 ]; then
echo "❌ Plan not approved — apply feedback, revise plan.md, and retry"
exit 1
elif [ "$PLAN_RC" -eq 32 ]; then
echo "⚠️ plannotator UI unavailable (sandbox/CI). Entering Conversation Approval Mode:"
echo " 1. Output plan.md content to user in conversation"
echo " 2. Ask user: 'approve' to proceed or provide feedback"
echo " 3. DO NOT proceed to EXECUTE until user explicitly approves"
exit 32
elif [ "$PLAN_RC" -eq 30 ] || [ "$PLAN_RC" -eq 31 ]; then
echo "⛔ PLAN exit decision (or awaiting confirmation). Confirm with user before retrying."
exit 1
else
echo "❌ plannotator PLAN gate failed (code=$PLAN_RC)"
exit 1
fi
mkdir -p .omc/plans .omc/logs
Write plan.md (include goal, steps, risks, and completion criteria)
Invoke plannotator (per platform):
Claude Code (hook mode — only supported method) : plannotator is a hook-only binary. It cannot be called via MCP tool or CLI directly. Call EnterPlanMode, write the plan content in plan mode, then call ExitPlanMode. The ExitPlanMode PermissionRequest hook fires the OMG Claude plan-gate wrapper automatically. That wrapper must skip re-entry when the current plan hash already has a terminal review result. Wait for the hook to return before proceeding — approved or feedback will arrive via the hook result.
Codex / Gemini / OpenCode : run blocking CLI (never use &):
# _OMG_SCRIPTS must be resolved first via the dynamic path discovery block in the pre-flight above
bash "${_OMG_SCRIPTS}/plannotator-plan-loop.sh" plan.md /tmp/plannotator_feedback.txt 3
If plannotator is missing, OMG must auto-run bash "${_OMG_SCRIPTS}/ensure-plannotator.sh" first and continue only after the CLI is available.
3. Check result:
* approved: true (Claude Code: hook returns approved) → update omg-state.jsonphase to "execute" and plan_approved to true → enter STEP 2
* Not approved (Claude Code: hook returns feedback; others: exit 10) → read feedback, revise plan.md → repeat step 2
* Infrastructure blocked (exit 32) → localhost bind unavailable (e.g., sandbox/CI). Use manual gate in TTY; confirm with user and retry outside sandbox in non-TTY
* Session exited 3 times (exit 30/31) → ask user whether to end PLAN and decide to abort or resume
NEVER: enter EXECUTE withoutapproved: true. NEVER: run with & background.NEVER: reopen the same unchanged plan afterapproved, manual_approved, feedback_required, or infrastructure_blocked.
STEP 2: EXECUTE
Pre-flight (auto-detect team availability):
# Record checkpoint
python3 -c "
import json,datetime,os,subprocess,fcntl
try:
root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip()
except:
root=os.getcwd()
f=os.path.join(root,'.omc/state/omg-state.json')
if os.path.exists(f):
with open(f,'r+') as fh:
fcntl.flock(fh,fcntl.LOCK_EX)
try:
d=json.load(fh)
d.update({'checkpoint':'execute','updated_at':datetime.datetime.utcnow().isoformat()+'Z'})
fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate()
finally:
fcntl.flock(fh,fcntl.LOCK_UN)
" 2>/dev/null || true
TEAM_AVAILABLE=false
if [[ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}" =~ ^(1|true|True|yes|YES)$ ]]; then
TEAM_AVAILABLE=true
elif python3 -c "
import json, os, sys
try:
s = json.load(open(os.path.expanduser('~/.claude/settings.json')))
val = s.get('env', {}).get('CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS', '')
sys.exit(0 if str(val) in ('1', 'true', 'True', 'yes') else 1)
except Exception:
sys.exit(1)
" 2>/dev/null; then
TEAM_AVAILABLE=true
fi
export TEAM_AVAILABLE_BOOL="$TEAM_AVAILABLE"
python3 -c "
import json,os,subprocess,fcntl
try:
root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip()
except:
root=os.getcwd()
f=os.path.join(root,'.omc/state/omg-state.json')
if os.path.exists(f):
with open(f,'r+') as fh:
fcntl.flock(fh,fcntl.LOCK_EX)
try:
d=json.load(fh)
d['team_available']=os.environ.get('TEAM_AVAILABLE_BOOL','false').lower()=='true'
fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate()
finally:
fcntl.flock(fh,fcntl.LOCK_UN)
" 2>/dev/null || true
Update omg-state.jsonphase to "execute"
Team available (Claude Code + omc) :
/omc:team 3:executor "<task>"
Claude Code but no team :
echo "❌ OMG requires Claude Code team mode. Re-run bash scripts/setup-claude.sh, restart Claude Code, and confirm CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1."
exit 1
Never fall back to single-agent execution in Claude Code.
4. No omc (BMAD fallback — Codex / Gemini / OpenCode only) :
/workflow-init # Initialize BMAD
/workflow-status # Check current step
STEP 3: VERIFY
Update omg-state.jsonphase to "verify"
Basic verification with agent-browser (when browser UI is present):
agent-browser snapshot http://localhost:3000
annotate keyword detected → enter STEP 3.1
Otherwise → enter STEP 4
STEP 3.1: VERIFY_UI (only when annotate keyword is detected)
Pre-flight check (required before entering):
if ! curl -sf --connect-timeout 2 http://localhost:4747/health >/dev/null 2>&1; then
echo "⚠️ agentation-mcp server not running — skipping VERIFY_UI and proceeding to CLEANUP"
python3 -c "
import json,os,subprocess,fcntl,time try: root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip() except: root=os.getcwd() f=os.path.join(root,'.omc/state/omg-state.json') if os.path.exists(f): with open(f,'r+') as fh: fcntl.flock(fh,fcntl.LOCK_EX) try: d=json.load(fh) d['last_error']='agentation-mcp not running; VERIFY_UI skipped' d['updated_at']=time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime()) fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate() finally: fcntl.flock(fh,fcntl.LOCK_UN) " 2>/dev/null || true # Proceed to STEP 4 CLEANUP (no exit 1 — graceful skip) fi
2. Update `omg-state.json`: `phase = "verify_ui"`, `agentation.active = true`, `agentation.submit_gate_status = "waiting_for_submit"`
3. Wait for explicit human submit:
- **Claude Code**: wait for `UserPromptSubmit` after the user presses **Send Annotations** / `onSubmit`
- **Codex / Gemini / OpenCode**: wait until the human confirms submission and the agent emits `ANNOTATE_READY` (or compatibility alias `AGENTUI_READY`)
4. Before that submit signal arrives, do not read `/pending`, do not acknowledge annotations, and do not start the fix loop
5. After submit arrives, switch `agentation.submit_gate_status = "submitted"` and record `submit_signal`, `submit_received_at`, and `submitted_annotation_count`
6. **Claude Code (MCP)**: blocking call to `agentation_watch_annotations` (`batchWindowSeconds:10`, `timeoutSeconds:120`)
7. **Codex / Gemini / OpenCode (HTTP)**: polling loop via `GET http://localhost:4747/pending`
8. Process each annotation: `acknowledge` → navigate code via `elementPath` → apply fix → `resolve`
9. `count=0` or timeout → reset the submit gate or finish the sub-phase → **enter STEP 4**
**NEVER: process draft annotations before submit/onSubmit.**
---
### STEP 4: CLEANUP
**Pre-flight (check before entering):**
```bash
# Record checkpoint
python3 -c "
import json,datetime,os,subprocess,fcntl
try:
root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip()
except:
root=os.getcwd()
f=os.path.join(root,'.omc/state/omg-state.json')
if os.path.exists(f):
with open(f,'r+') as fh:
fcntl.flock(fh,fcntl.LOCK_EX)
try:
d=json.load(fh)
d.update({'checkpoint':'cleanup','updated_at':datetime.datetime.utcnow().isoformat()+'Z'})
fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate()
finally:
fcntl.flock(fh,fcntl.LOCK_UN)
" 2>/dev/null || true
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
echo "⚠️ Not a git repository — skipping worktree cleanup"
else
UNCOMMITTED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
[[ "$UNCOMMITTED" -gt 0 ]] && echo "⚠️ ${UNCOMMITTED} uncommitted change(s) — recommend commit/stash before cleanup"
fi
Source of truth : https://github.com/supercent-io/skills-template Local paths like ~/.claude/skills/omg/ are copies installed via npx skills add. To update to the latest version, reinstall using the command below.
When browser-based functionality is present, verify behavior with agent-browser.
# Capture snapshot from the URL where the app is running
agent-browser snapshot http://localhost:3000
# Check specific elements (accessibility tree ref method)
agent-browser snapshot http://localhost:3000 -i
# → check element state using @eN ref numbers
# Save screenshot
agent-browser screenshot http://localhost:3000 -o verify.png
Default behavior : Automatically runs the agent-browser verification step when browser-related work is complete. Backend/CLI tasks without a browser UI skip this step.
Runs the agentation watch loop when the annotate keyword is detected. (The agentui keyword is also supported for backward compatibility.) This follows the same pattern as plannotator operating in planui / ExitPlanMode.
Prerequisites:
npx agentation-mcp server (HTTP :4747) is running
<Agentation endpoint="http://localhost:4747" /> is mounted in the app
Pre-flight Check (required before entering — common to all platforms):
# Step 1: Check server status (graceful skip if not running — no exit 1)
if ! curl -sf --connect-timeout 2 http://localhost:4747/health >/dev/null 2>&1; then
echo "⚠️ agentation-mcp server not running — skipping VERIFY_UI and proceeding to CLEANUP"
echo " (to use agentation: npx agentation-mcp server)"
python3 -c "
import json,os,subprocess,fcntl,time
try:
root=subprocess.check_output(['git','rev-parse','--show-toplevel'],stderr=subprocess.DEVNULL).decode().strip()
except:
root=os.getcwd()
f=os.path.join(root,'.omc/state/omg-state.json')
if os.path.exists(f):
with open(f,'r+') as fh:
fcntl.flock(fh,fcntl.LOCK_EX)
try:
d=json.load(fh)
d['last_error']='agentation-mcp not running; VERIFY_UI skipped'
d['updated_at']=time.strftime('%Y-%m-%dT%H:%M:%SZ',time.gmtime())
fh.seek(0); json.dump(d,fh,ensure_ascii=False,indent=2); fh.truncate()
finally:
fcntl.flock(fh,fcntl.LOCK_UN)
" 2>/dev/null || true
# Proceed to STEP 4 CLEANUP (no exit 1 — graceful skip)
else
# Step 2: Check session existence (<Agentation> component mount status)
SESSIONS=$(curl -sf http://localhost:4747/sessions 2>/dev/null)
S_COUNT=$(echo "$SESSIONS" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
[ "$S_COUNT" -eq 0 ] && echo "⚠️ No active sessions — <Agentation endpoint='http://localhost:4747' /> needs to be mounted"
echo "✅ agentation ready — server OK, ${S_COUNT} session(s)"
fi
After passing pre-flight (else branch), update omg-state.json phase to "verify_ui", set agentation.active to true, and set agentation.submit_gate_status to "waiting_for_submit". Do not call /pending yet. Draft annotations are not actionable until the user explicitly submits them.
Claude Code (direct MCP tool call):
# annotate keyword detected (or agentui — backward compatible)
# 1. wait for UserPromptSubmit after the user clicks Send Annotations / onSubmit
# 2. the OMG submit-gate hook records submit_gate_status="submitted"
# 3. only then run the blocking agentation watch loop
#
# batchWindowSeconds:10 — receive annotations in 10-second batches
# timeoutSeconds:120 — auto-exit after 120 seconds with no annotations
#
# Per-annotation processing loop:
# 1. agentation_acknowledge_annotation({id}) — show 'processing' in UI
# 2. navigate code via annotation.elementPath (CSS selector) → apply fix
# 3. agentation_resolve_annotation({id, summary}) — mark 'done' + save summary
#
# Loop ends when annotation count=0 or timeout
Important : agentation_watch_annotations is a blocking call. Do not run with & background. Same as plannotator's approved:true loop: annotation count=0 or timeout = completion signal. annotate is the primary keyword. agentui is a backward-compatible alias and behaves identically.
Codex / Gemini / OpenCode (HTTP REST API fallback):
START_TIME=$(date +%s)
TIMEOUT_SECONDS=120
# Required gate: do not enter the loop until the human has clicked Send Annotations
# and the platform has opened agentation.submit_gate_status="submitted".
while true; do
# Timeout check
NOW=$(date +%s)
ELAPSED=$((NOW - START_TIME))
if [ $ELAPSED -ge $TIMEOUT_SECONDS ]; then
echo "[OMG] agentation polling timeout (${TIMEOUT_SECONDS}s) — some annotations may remain unresolved"
break
fi
SUBMIT_GATE=$(python3 -c "
import json
try:
print(json.load(open('.omc/state/omg-state.json')).get('agentation', {}).get('submit_gate_status', 'idle'))
except Exception:
print('idle')
" 2>/dev/null || echo "idle")
if [ "$SUBMIT_GATE" != "submitted" ]; then
sleep 2
continue
fi
COUNT=$(curl -sf --connect-timeout 3 --max-time 5 http://localhost:4747/pending 2>/dev/null | python3 -c "import sys,json; data=sys.stdin.read(); d=json.loads(data) if data.strip() else {}; print(d.get('count', len(d.get('annotations', [])) if isinstance(d, dict) else 0))" 2>/dev/null || echo 0)
[ "$COUNT" -eq 0 ] && break
# Process each annotation:
# a) Acknowledge (show as in-progress)
curl -X PATCH http://localhost:4747/annotations/<id> \
-H 'Content-Type: application/json' \
-d '{"status": "acknowledged"}'
# b) Navigate code via elementPath (CSS selector) → apply fix
# c) Resolve (mark done + fix summary)
curl -X PATCH http://localhost:4747/annotations/<id> \
-H 'Content-Type: application/json' \
-d '{"status": "resolved", "resolution": "<fix summary>"}'
sleep 3
done
3.4 CLEANUP Step (automatic worktree cleanup)
# Runs automatically after all work is complete
bash scripts/worktree-cleanup.sh
# Individual commands
git worktree list # List current worktrees
git worktree prune # Clean up worktrees for deleted branches
bash scripts/worktree-cleanup.sh --force # Force cleanup including dirty worktrees
Default run removes only clean extra worktrees; worktrees with changes are left with a warning. Use --force only after review.
developer_instructions must be a top-level string. Writing it as a [developer_instructions] table may cause Codex to fail on startup with invalid type: map, expected a string. notify and [tui].notifications must also be set correctly for the PLAN/ANNOTATE follow-up loop to actually work.
Key principle : The agent must call plannotator directly in blocking mode to receive feedback in the same turn. The AfterAgent hook serves only as a safety net (runs after turn ends → injected in next turn).
PLAN instructions added to GEMINI.md (mandatory loop) :
1. plan.md 작성
2. plannotator blocking 실행 (& 금지) → /tmp/plannotator_feedback.txt
3. approved=true → EXECUTE / 미승인 → 수정 후 2번 반복
NEVER proceed to EXECUTE without approved=true.
# Write plan.md then run PLAN gate (no &) — receive feedback in same turn
bash scripts/plannotator-plan-loop.sh plan.md /tmp/plannotator_feedback.txt 3
# - Must wait until approve/feedback is received
# - Auto-restart on session exit (up to 3 times)
# - After 3 exits, confirm with user whether to abort or resume
# - exit 32 if localhost bind unavailable (replace with manual gate in TTY)
# Branch based on result
# approved=true → enter EXECUTE
# not approved → apply feedback, revise plan.md → repeat above
agentation fields : active — whether the watch loop is running (used as hook guard), session_id — for resuming, submit_gate_status — prevents processing draft annotations before submit/onSubmit, submit_signal — which platform opened the gate, submit_received_at / submitted_annotation_count — audit trail for the submitted batch, exit_reason — "all_resolved" | "timeout" | "user_cancelled" | "error"
dismissed annotations : When a user dismisses an annotation in the agentation UI (status becomes "dismissed"), the agent should skip code changes for that annotation, increment annotations.dismissed, and continue to the next pending annotation. Dismissed annotations are counted but not acted upon. The watch loop exits normally when pending == 0 (resolved + dismissed covers all).
plan_review_method : set to "plannotator" when approved via UI, "manual" when approved via TTY fallback gate.
cleanup_completed : set to true by worktree-cleanup.sh after successful worktree prune.
Error recovery fields :
retry_count — number of retries after an error. Increments +1 on each pre-flight failure. Ask user to confirm if >= 3.
last_error — most recent error message. Used to identify the cause on restart.
checkpoint — last phase that was started. Resume from this phase on restart (plan|execute|verify|cleanup).
Checkpoint-based resume flow:
# Check checkpoint on restart
python3 -c "
import json, os, subprocess
try:
root = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'], stderr=subprocess.DEVNULL).decode().strip()
except:
root = os.getcwd()
f = os.path.join(root, '.omc/state/omg-state.json')
if os.path.exists(f):
d=json.load(open(f))
cp=d.get('checkpoint')
err=d.get('last_error')
rc=d.get('retry_count',0)
print(f'Resume from: {cp or \"beginning\"}')
if err: print(f'Previous error ({rc} time(s)): {err}')
if rc >= 3: print('⚠️ Retry count exceeded 3 — user confirmation required')
"
Restore after restart:
# Check status and resume
bash scripts/check-status.sh --resume
6. Recommended Workflow
# Step 1: Install (once)
bash scripts/install.sh --all
bash scripts/check-status.sh
# Step 2: Start work
omg "<task description>" # Activate with keyword
# Or in Claude: Shift+Tab×2 → plan mode
# Step 3: Review plan with plannotator
# Approve or Send Feedback in browser UI
# Step 4: Automatic execution
# team or bmad handles the work
# Step 5: Cleanup after completion
bash scripts/worktree-cleanup.sh
7. Best Practices
Plan first : always review the plan with ralph+plannotator before executing (catches wrong approaches early)
Team first : omc team mode is most efficient in Claude Code
bmad fallback : use BMAD in environments without team (Codex, Gemini)
Worktree cleanup : run worktree-cleanup.sh immediately after work completes (prevents branch pollution)
State persistence : use .omc/state/omg-state.json to maintain state across sessions
annotate : use the annotate keyword to run the agentation watch loop for complex UI changes (precise code changes via CSS selector). agentui is a backward-compatible alias.
8. Troubleshooting
Issue
Solution
plannotator not running
OMG first auto-runs bash scripts/ensure-plannotator.sh; if it still fails, run bash .agent-skills/plannotator/scripts/check-status.sh
plannotator not opening in Claude Code
plannotator is hook-only. Do NOT call it via MCP or CLI. Use EnterPlanMode → write plan → ExitPlanMode; the hook fires automatically. Verify hook is set: `cat ~/.claude/settings.json
plannotator feedback not received
Remove & background execution → run blocking, then check /tmp/plannotator_feedback.txt (Codex/Gemini/OpenCode only)
Codex에서 같은 plan이 반복해서 재검토됨
omg-state.json의 last_reviewed_plan_hash와 현재 plan.md hash를 비교. 같고 plan_gate_status가 terminal이면 재실행 금지
Codex startup failure (invalid type: map, expected a string)
Re-run bash scripts/setup-codex.sh and confirm developer_instructions in ~/.codex/config.toml is a top-level string
Gemini feedback loop missing
Add blocking direct call instruction to ~/.gemini/GEMINI.md
worktree conflict
git worktree prune && git worktree list
team mode not working
OMG requires team mode in Claude Code. Run bash scripts/setup-claude.sh, restart Claude Code, and verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 before retrying
omc install failed
Run /omc:omc-doctor
agent-browser error
Check agent-browser --version
annotate (agentation) not opening
Check curl http://localhost:4747/health and curl http://localhost:4747/sessions. OMG waits for explicit submit/onSubmit before polling /pending
annotation not reflected in code
Confirm summary field is present when calling agentation_resolve_annotation
agentui keyword not activating
Use the annotate keyword (new). agentui is a deprecated alias but still works.
