jeo（杰奥）

JEO — Integrated Agent Orchestration

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

When to use this skill

• 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/

Rules (always enforced)

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

Authoritative state: .omc/state/jeo-state.json

State Management

All state operations use one script: scripts/jeo-state-update.py

# Initialize (or resume if state exists)
python3 scripts/jeo-state-update.py init "<task>"

# Record checkpoint at each step
python3 scripts/jeo-state-update.py checkpoint <plan|execute|verify|verify_ui|cleanup>

# Record error (auto-increments retry_count; warns at >= 3)
python3 scripts/jeo-state-update.py error "<message>"

# Check resume point
python3 scripts/jeo-state-update.py resume

# Set any field (supports dot notation for nested keys)
python3 scripts/jeo-state-update.py set phase execute
python3 scripts/jeo-state-update.py set agentation.active true

.jeo Project Ledger

JEO keeps a human-readable project ledger in .jeo/ and a machine-readable state file in .omc/state/jeo-state.json.

Use scripts/jeo-project-sync.py to keep the ledger in sync:

python3 scripts/jeo-project-sync.py init "<task>"
python3 scripts/jeo-project-sync.py queue api-contract "Harden API contract validation"
python3 scripts/jeo-project-sync.py start-next
python3 scripts/jeo-project-sync.py stage <planning|development|qa|done>
python3 scripts/jeo-project-sync.py progress "<message>"
python3 scripts/jeo-project-sync.py complete <slug> "<summary>"
python3 scripts/jeo-project-sync.py status

Phase mapping

Detailed ledger rules: references/DOT_JEO_LEDGER.md

Instructions

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

STEP 0: Bootstrap

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

Claude Code only — hook self-check (run inline):

Verify the ExitPlanMode hook is using claude-plan-gate.py, not raw plannotator. If misconfigured, auto-repair:

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

Notify the user:

"JEO activated. Delivery stage: planning. .jeo ledger initialized. Add the annotate keyword if a UI feedback loop is needed."

STEP 1: PLAN / Planning (never skip)

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

1. Invoke plannotator (per platform): Claude Code (hook mode — only supported method): Codex / Gemini / OpenCode (blocking CLI): # 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

- 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

1. 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

1. When the plan is approved, append a note to .jeo/progress.md describing what is ready to build and what QA must prove.

NEVER: enter EXECUTE without approved: true. NEVER: run with & background.

STEP 2: EXECUTE / Development

python3 scripts/jeo-state-update.py checkpoint execute
python3 scripts/jeo-state-update.py set phase execute
python3 scripts/jeo-project-sync.py stage development
python3 scripts/jeo-project-sync.py progress "Development started from the approved plan."

Auto-detect team availability:

TEAM_AVAILABLE=false
if [[ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-}" =~ ^(1|true|yes)$ ]]; then
  TEAM_AVAILABLE=true
fi
python3 scripts/jeo-state-update.py set team_available $TEAM_AVAILABLE

Check next_mode in state (set by claude-plan-gate.py on approval):

While executing, keep the active .jeo/tasks/active/*.md file current using:

# When plan and risks are locked
python3 scripts/jeo-project-sync.py update-checklist planning "Scope captured in plan.md" --done
python3 scripts/jeo-project-sync.py update-checklist planning "Risks and completion criteria written" --done

# As code, docs, and tests are completed
python3 scripts/jeo-project-sync.py update-checklist development "System changes implemented" --done
python3 scripts/jeo-project-sync.py update-checklist development "Unit tests added or updated" --done

NEVER fall back to single-agent execution in Claude Code.

STEP 3: VERIFY / QA

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): 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: 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

STEP 3.1: VERIFY_UI (only when annotate keyword is detected)

Pre-flight check (all platforms):

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

If server is running:

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)

1. After submit → set agentation.submit_gate_status=submitted
2. Process annotations:

- Claude Code (MCP): agentation_watch_annotations (blocking, batchWindowSeconds:10, timeoutSeconds:120) - Others (HTTP): poll GET http://localhost:4747/pending with timeout

1. Per-annotation loop:

- acknowledge → navigate code via elementPath (CSS selector) → apply fix → resolve - Dismissed annotations: skip code changes, increment annotations.dismissed

1. count=0 or timeout → proceed to STEP 4
2. If QA discovers follow-up work, add it immediately: python3 scripts/jeo-project-sync.py queue follow-up "<new work item>"

NEVER: process draft annotations before submit/onSubmit.

STEP 4: CLEANUP

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: 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: python3 scripts/jeo-project-sync.py queue next-step "<follow-up work>"
4. Run worktree cleanup: bash scripts/worktree-cleanup.sh || git worktree prune
5. Set phase=done

Quick Start

# Install JEO
npx skills add https://github.com/akillness/oh-my-skills --skill jeo

# Full install (all tools + components)
bash scripts/install.sh --all

# Check status
bash scripts/check-status.sh

# Per-platform setup
bash scripts/setup-claude.sh      # Claude Code hooks
bash scripts/setup-codex.sh       # Codex CLI config
bash scripts/setup-gemini.sh      # Gemini CLI hooks
bash scripts/setup-opencode.sh    # OpenCode plugin

Platform Configuration

Claude Code

Hook config (~/.claude/settings.json):

{
  "hooks": {
    "PermissionRequest": [{
      "matcher": "ExitPlanMode",
      "hooks": [{"type": "command", "command": "python3 ~/.claude/skills/jeo/scripts/claude-plan-gate.py", "timeout": 1800}]
    }],
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "python3 ~/.claude/skills/jeo/scripts/claude-agentation-submit-hook.py", "timeout": 300}]
    }]
  },
  "mcpServers": {
    "agentation": {"command": "npx", "args": ["-y", "agentation-mcp", "server"]}
  }
}

Codex CLI

Config (~/.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.

Gemini CLI

Instructions in ~/.gemini/GEMINI.md. AfterAgent hook as safety net in ~/.gemini/settings.json. Agent must call plannotator directly in blocking mode to receive feedback in the same turn.

OpenCode

Plugins in opencode.json. Slash commands: /jeo-plan, /jeo-exec, /jeo-annotate, /jeo-cleanup.

State File Reference

Path: {worktree}/.omc/state/jeo-state.json

Examples

Example 1: New feature with .jeo ledger

python3 scripts/jeo-project-sync.py init "Build exportable analytics dashboard"
python3 scripts/jeo-project-sync.py start-next
python3 scripts/jeo-project-sync.py stage planning

Then run the normal JEO flow: plan approval → development → QA → cleanup. When done:

python3 scripts/jeo-project-sync.py complete 000-primary "Dashboard shipped with unit tests, flow checks, and browser verification."

Example 2: Add follow-up work discovered during QA

python3 scripts/jeo-project-sync.py queue qa-follow-up "Fix chart legend overlap on small screens"
python3 scripts/jeo-project-sync.py progress "Queued QA follow-up from annotate review."

Best practices

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.

Troubleshooting

References

• 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