Keyword:

jeo

·

annotate

·

UI-review

·

agentui (deprecated)

| Platforms: Claude Code · Codex CLI · Gemini CLI · OpenCode

Planning (plannotator) → Development (team/bmad) → QA (agent-browser + agentation) → Cleanup (worktree) with a persistent

.jeo

project ledger

• Run an end-to-end multi-agent workflow with an explicit planning gate
• Add a browser-backed UI feedback loop with

  annotate

  or

  ui-review

• Coordinate plan approval, execution, verification, and cleanup in one skill
• Keep long-term rules, short-term system/test plans, active work items, and history in

  .jeo/

1. Do not reopen the PLAN gate when the current plan hash already has a terminal result
2. Only a revised plan resets

   plan_gate_status

   to

   pending

3. Do not process agentation annotations before explicit submit/onSubmit opens the submit gate
4. NEVER enter EXECUTE without

   plan_approved: true

5. NEVER run plannotator or agentation with

   &

   (background)
6. NEVER reopen an unchanged plan after

   approved

   ,

   manual_approved

   ,

   feedback_required

   , or

   infrastructure_blocked

.omc/state/jeo-state.json

Execute steps in order. Each step only proceeds after the previous one completes.

mkdir -p .omc/state .omc/plans .omc/logs
python3 scripts/jeo-state-update.py init "<detected task>"
python3 scripts/jeo-project-sync.py init "<detected task>"
python3 scripts/jeo-project-sync.py start-next

ExitPlanMode

claude-plan-gate.py

plannotator

import json, os, subprocess, sys

p = os.path.expanduser("~/.claude/settings.json")
if os.path.exists(p):
    s = json.load(open(p))
    for entry in s.get("hooks", {}).get("PermissionRequest", []):
        if entry.get("matcher") == "ExitPlanMode":
            for h in entry.get("hooks", []):
                cmd = h.get("command", "")
                if (cmd.strip() == "plannotator" or cmd.startswith("plannotator ")) and "claude-plan-gate" not in cmd:
                    print("[JEO][WARN] Hook uses raw plannotator — state tracking disabled. Auto-repairing...", file=sys.stderr)
                    for candidate in [
                        os.path.join(os.getcwd(), ".agent-skills/jeo/scripts/setup-claude.sh"),
                        os.path.expanduser("~/.claude/skills/jeo/scripts/setup-claude.sh"),
                        os.path.expanduser("~/.agent-skills/jeo/scripts/setup-claude.sh"),
                    ]:
                        if os.path.exists(candidate):
                            subprocess.run(["bash", candidate], check=False)
                            print("[JEO] Hook repaired. Restart Claude Code to apply.", file=sys.stderr)
                            break

"JEO activated. Delivery stage: planning.

.jeo

ledger initialized. Add the

annotate

keyword if a UI feedback loop is needed."

python3 scripts/jeo-state-update.py checkpoint plan
python3 scripts/jeo-project-sync.py stage planning
python3 scripts/jeo-project-sync.py progress "Entered planning gate."

1. Review

   .jeo/long-term.md

   ,

   .jeo/short-term.md

   ,

   .jeo/planned.md

   ,

   .jeo/progress.md

   , and

   .jeo/history.md

   before changing scope.
2. Write

   plan.md

   (include goal, steps, risks, completion criteria, and the current planning/development/QA expectations from

   .jeo/short-term.md

   ).
3. Update

   .jeo/short-term.md

   with:
   • the system slice for this run
   • the unit-test plan
   • the flow/browser verification plan
4. Invoke plannotator (per platform):
   Claude Code (hook mode — only supported method):
   • Call

     EnterPlanMode

     → write plan content → call

     ExitPlanMode

   • The

     ExitPlanMode

     PermissionRequest hook fires plannotator automatically
   • Wait for the hook result before proceeding
   • NEVER call plannotator via MCP tool or CLI directly in Claude Code
   Codex / Gemini / OpenCode (blocking CLI):
   bash

   # Skip if same plan hash already has terminal gate status
   # (check plan_gate_status and last_reviewed_plan_hash in jeo-state.json)
   
   # Resolve JEO scripts directory
   _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
     [ -f "${_candidate}/plannotator-plan-loop.sh" ] && _JEO_SCRIPTS="$_candidate" && break
   done
   
   # Auto-install plannotator if missing
   bash "${_JEO_SCRIPTS}/ensure-plannotator.sh" || exit 1
   
   # Run blocking plan gate (no &)
   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)")
   bash "${_JEO_SCRIPTS}/plannotator-plan-loop.sh" plan.md "${FEEDBACK_DIR}/plannotator_feedback.txt" 3

5. Check result:

   • approved

     (exit 0) → set

     phase=execute

     ,

     plan_approved=true

     → STEP 2
   • Feedback (exit 10) → read feedback, revise

     plan.md

     , repeat step 2
   • Infrastructure blocked (exit 32) → Conversation Approval Mode: output plan.md to user, ask "approve" or provide feedback. WAIT for user response
   • Session exited 3 times (exit 30/31) → ask user whether to abort
6. When the plan is approved, append a note to

   .jeo/progress.md

   describing what is ready to build and what QA must prove.

approved: true

&

python3 scripts/jeo-state-update.py checkpoint verify
python3 scripts/jeo-state-update.py set phase verify
python3 scripts/jeo-project-sync.py stage qa
python3 scripts/jeo-project-sync.py progress "Entered QA verification."

1. Browser verification with agent-browser (when browser UI is present):
   bash

   agent-browser snapshot http://localhost:3000

2. annotate

   keyword detected → enter STEP 3.1
3. Otherwise → enter STEP 4
4. Record QA evidence in

   .jeo/short-term.md

   using:
   bash

   python3 scripts/jeo-project-sync.py record-evidence "unit tests: X passing, Y added"
   python3 scripts/jeo-project-sync.py record-evidence "flow check: <description>"
   python3 scripts/jeo-project-sync.py record-evidence "browser verification: <outcome>"
   # Then mark QA checklist items complete
   python3 scripts/jeo-project-sync.py update-checklist qa "Flow or integration checks recorded" --done
   python3 scripts/jeo-project-sync.py update-checklist qa "Browser / annotation verification recorded when applicable" --done

if ! curl -sf --connect-timeout 2 http://localhost:4747/health >/dev/null 2>&1; then
  echo "agentation-mcp not running — skipping VERIFY_UI, proceeding to CLEANUP"
  python3 scripts/jeo-state-update.py error "agentation-mcp not running; VERIFY_UI skipped"
  # Proceed to STEP 4 (graceful skip, no exit 1)
fi

1. Set state:

   phase=verify_ui

   ,

   agentation.active=true

   ,

   agentation.submit_gate_status=waiting_for_submit

2. Wait for explicit human submit — do NOT read

   /pending

   before submit
   • Claude Code: wait for

     UserPromptSubmit

     hook
   • Others: wait until

     ANNOTATE_READY

     (or

     AGENTUI_READY

     alias)
3. After submit → set

   agentation.submit_gate_status=submitted

4. Process annotations:
   • Claude Code (MCP):

     agentation_watch_annotations

     (blocking,

     batchWindowSeconds:10

     ,

     timeoutSeconds:120

     )
   • Others (HTTP): poll

     GET http://localhost:4747/pending

     with timeout
5. Per-annotation loop:

   • acknowledge

     → navigate code via

     elementPath

     (CSS selector) → apply fix →

     resolve

   • Dismissed annotations: skip code changes, increment

     annotations.dismissed

6. count=0

   or timeout → proceed to STEP 4
7. If QA discovers follow-up work, add it immediately:
   bash

   python3 scripts/jeo-project-sync.py queue follow-up "<new work item>"

python3 scripts/jeo-state-update.py checkpoint cleanup
python3 scripts/jeo-state-update.py set phase cleanup
python3 scripts/jeo-project-sync.py stage done

1. Check for uncommitted changes (warn if present)
2. Complete the active

   .jeo

   task and write the permanent summary:
   bash

   python3 scripts/jeo-project-sync.py complete <slug> "<what shipped, what QA proved, what follow-up remains>"

3. If more work is needed, queue it before leaving cleanup:
   bash

   python3 scripts/jeo-project-sync.py queue next-step "<follow-up work>"

4. Run worktree cleanup:
   bash

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

5. Set

   phase=done

~/.codex/config.toml

notify = ["python3", "~/.codex/hooks/jeo-notify.py"]
[tui]
notifications = ["agent-turn-complete"]

developer_instructions

must be a top-level string (not a

[table]

), or Codex fails with

invalid type: map, expected a string

.

1. Plan first: always review the plan with ralph+plannotator before executing (catches wrong approaches early)
2. Team first: omc team mode is most efficient in Claude Code
3. bmad fallback: use BMAD in environments without team (Codex, Gemini)
4. Keep

   .jeo

   honest: long-term is durable, short-term is current, history is append-only
5. One active task file: keep only one file under

   .jeo/tasks/active/

   at a time
6. Complete means summarize + delete task file: write history first, then remove the task file
7. Worktree cleanup: run

   worktree-cleanup.sh

   immediately after work completes (prevents branch pollution)
8. State persistence: use

   .omc/state/jeo-state.json

   and

   .jeo/

   together across sessions
9. 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.

• oh-my-claudecode — Claude Code multi-agent
• plannotator — visual plan/diff review
• BMAD Method — structured AI development workflow
• Agent Skills Spec — skill format specification
• agentation — UI annotation → agent code fix (

  annotate

  ;

  agentui

  backward compatible)

• .jeo

  ledger reference — project-local planning, development, and QA ledger