jeo

jeo

JEO — Integrated Agent Orchestration Keyword: jeo · annotate · UI-review · agentui (deprecated) | Platforms: Claude Code · Codex CLI · Gemini CLI · OpenCode A unified skill providing fully automated orchestration flow: Plan (ralph+plannotator) → Execute (team/bmad) → UI Feedback (agentation/annotate) → Cleanup (worktree cleanup) Control Layers JEO uses one cross-platform abstraction for orchestration: settings: platform/runtime configuration such as Claude hooks, Codex config.toml, Gemini settings.json, MCP registration, and prompt parameters rules: policy constraints that must hold on every platform hooks: event callbacks that enforce those rules on each platform The key JEO rules are: do not reopen the PLAN gate when the current plan hash already has a terminal result only a revised plan resets plan_gate_status to pending do not process agentation annotations before explicit submit/onSubmit opens the submit gate The authoritative state is .omc/state/jeo-state.json. Hooks may help advance the workflow, but they must obey the state file. 0. Agent Execution Protocol (follow immediately upon jeo keyword detection) The following are commands, not descriptions. Execute them in order. Each step only proceeds after the previous one completes. STEP 0: State File Bootstrap (required — always first) mkdir -p .omc/state .omc/plans .omc/logs If .omc/state/jeo-state.json does not exist, create it: { "phase": "plan", "task": "", "plan_approved": false, "plan_gate_status": "pending", "plan_current_hash": null, "last_reviewed_plan_hash": null, "last_reviewed_plan_at": null, "plan_review_method": null, "team_available": null, "retry_count": 0, "last_error": null, "checkpoint": null, "created_at": "<ISO 8601>", "updated_at": "<ISO 8601>", "agentation": { "active": false, "session_id": null, "keyword_used": null, "submit_gate_status": "idle", "submit_signal": null, "submit_received_at": null, "submitted_annotation_count": 0, "started_at": null, "timeout_seconds": 120, "annotations": { "total": 0, "acknowledged": 0, "resolved": 0, "dismissed": 0, "pending": 0 }, "completed_at": null, "exit_reason": null } } Notify the user: "JEO activated. Phase: PLAN. Add the annotate keyword if a UI feedback loop is needed." STEP 0.1: Error Recovery Protocol (applies to all STEPs) Checkpoint recording — immediately after entering each STEP: # Execute immediately at the start of each STEP (agent updates jeo-state.json directly) python3 -c " import json, datetime, os, subprocess, 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/jeo-state.json') if os.path.exists(f): import fcntl with open(f, 'r+') as fh: fcntl.flock(fh, fcntl.LOCK_EX) try: d = json.load(fh) d['checkpoint']='<current_phase>' # 'plan'|'execute'|'verify'|'cleanup' d['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 last_error recording — on pre-flight failure or exception: 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/jeo-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']='' d['retry_count']=d.get('retry_count',0)+1 d['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 Checkpoint-based resume on restart: # If jeo-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/jeo-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/jeo-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/jeo-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/jeo-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)$ ]]; then echo "✅ Current plan hash already approved. Skipping re-review." exit 0 fi # BUG FIX (v1.3.1): feedback_required + same hash must NOT exit 0 (approved). # The plan has outstanding feedback and must be revised before re-opening plannotator. # Exiting 0 here would cause JEO to proceed to EXECUTE with an unapproved plan. if [[ "$HASH_MATCH" == "match" && "$PLAN_GATE_STATUS" == "feedback_required" ]]; then echo "❌ Feedback pending for this plan hash — revise plan.md content (new hash required) before re-opening plannotator." echo " Check .omc/state/jeo-state.json → plannotator_feedback for the recorded feedback." exit 1 fi if [[ "$HASH_MATCH" == "match" && "$PLAN_GATE_STATUS" == "infrastructure_blocked" ]]; then echo "⚠️ Infrastructure blocked for current plan hash. Use manual TTY gate or set plan_gate_status='manual_approved' in jeo-state.json." exit 32 fi # plannotator is mandatory for the PLAN step (Codex/Gemini/OpenCode). # If missing, JEO auto-installs it before opening the PLAN gate. # Resolve the JEO scripts directory (works from any CWD) _JEO_SCRIPTS="" for _candidate in \ "${JEO_SKILL_DIR:-}/scripts" \ "$HOME/.agent-skills/jeo/scripts" \ "$HOME/.codex/skills/jeo/scripts" \ "$(pwd)/.agent-skills/jeo/scripts" \ "scripts" \ ; do if [ -f "${_candidate}/plannotator-plan-loop.sh" ]; then _JEO_SCRIPTS="$_candidate" break fi done if [ -z "$_JEO_SCRIPTS" ]; then echo "❌ JEO scripts not found. Re-run: bash setup-codex.sh (or setup-gemini.sh)" exit 1 fi if ! bash "${_JEO_SCRIPTS}/ensure-plannotator.sh"; then echo "❌ plannotator auto-install failed: cannot proceed with PLAN step." echo " Retry: bash ${_JEO_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/jeo-{h}'; os.makedirs(d,exist_ok=True); print(d)" 2>/dev/null || echo '/tmp') FEEDBACK_FILE="${FEEDBACK_DIR}/plannotator_feedback.txt" bash "${_JEO_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 JEO 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 &): # _JEO_SCRIPTS must be resolved first via the dynamic path discovery block in the pre-flight above bash "${_JEO_SCRIPTS}/plannotator-plan-loop.sh" plan.md /tmp/plannotator_feedback.txt 3 If plannotator is missing, JEO must auto-run bash "${_JEO_SCRIPTS}/ensure-plannotator.sh" first and continue only after the CLI is available. Check result: approved: true (Claude Code: hook returns approved) → update jeo-state.json phase 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 without approved: true. NEVER: run with & background. NEVER: reopen the same unchanged plan after approved or manual_approved — it is already approved. NEVER: treat feedback_required as approved — it means the plan was REJECTED and must be revised. When feedback_required + same hash → exit 1 (not 0), revise plan content to get a new hash, then re-open plannotator. 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/jeo-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/jeo-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 jeo-state.json phase to "execute" Team available (Claude Code + omc): /omc:team 3:executor "" Claude Code but no team: echo "❌ JEO 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. No omc (BMAD fallback — Codex / Gemini / OpenCode only): /workflow-init # Initialize BMAD /workflow-status # Check current step STEP 3: VERIFY Update jeo-state.json phase 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): # Auto-start server, auto-install package, auto-inject component (see §3.3.1 for full script) bash scripts/ensure-agentation.sh --project-dir "${PROJECT_DIR:-$PWD}" --endpoint "http://localhost:4747" || true # If agentation-mcp server is still not healthy after pre-flight → graceful skip to STEP 4 if ! curl -sf --connect-timeout 2 http://localhost:4747/health >/dev/null 2>&1; then 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/jeo-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 jeo-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 a

...