Menu
Use if supervising Jean agents through MCP and Computer Use for monitoring, recovery, or closure.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use skill if you are exhaustively testing or release-gating martool CLI commands in a source checkout or deployed Coolify container over SSH, without local Docker or provider spend.
Use if driving agent-browser for Chrome/CDP automation, @ref snapshots, tabs, or verification.
Use if testing or debugging an iOS app via agent-device CLI — simulator flows, evidence, bug triage.
Use if auditing or designing a CLI for agent/LLM use — JSON output, exit codes, non-interactive.
Use if auditing or designing an MCP server for agent-readiness — framework, security, context.
Use if verifying claimed-done work or auditing session/plan/branch completion with evidence.
| name | orchestrate-projects-by-jean |
| description | Use if supervising Jean agents through MCP and Computer Use for monitoring, recovery, or closure. |
Act as the portfolio manager for coding agents already running in Jean. Keep every project tied to its product purpose, unblock it in place, and drive it to verified code, CI, deploy, and repository closure.
Codex desktop on macOS, an already-running Jean app with [mcp_servers.jean] configured, Python 3.9 or newer, and either mcp2cli in PATH or mcp2cli available in the existing offline uvx cache. The observer fails closed when these trust requirements are not met; it never starts Jean or installs dependencies during supervision.
Never quit, relaunch, kill, or restart Jean to recover an agent or UI failure. Preserve the running app, open projects, sessions, and worktrees. Recover the affected session in place by inspecting it, cancelling only its current turn when necessary, switching its available backend/model in place, and sending an exact-state continuation prompt.
Do not rationalize a restart as the fastest fix. A transient stream failure, token limit, quota error, frozen command, stale accessibility tree, or missing response is a session problem until proven otherwise—not an app-process problem.
Read these before the corresponding phase; do not guess their contents.
| Phase | Read | Why |
|---|---|---|
| Before the first Jean UI action | references/computer-use-runbook.md | Exact Codex Computer Use protocol, navigation, fresh-state and no-restart rules |
| Any Jean MCP inventory, status read, or background watcher | references/jean-ops-cli.md | Read-only Python command surface, mcp2cli transport, result files, exit codes, and UI handoff |
| Before resolving projects or steering sessions | references/jean-state-and-steering.md | UI/MCP/shell truth hierarchy, project-root discovery, session ownership, YOLO mode, prompt-start proof |
| Portfolio inventory and ongoing supervision | references/project-control-loop.md | Purpose ledger, startup prioritization, project workers, monitoring and wakeups |
| Any wait, CI watcher, heartbeat, or recurring schedule | references/monitoring-and-automations.md | Bounded polling, wait-handle routing, heartbeat vs standalone automation, lifecycle cleanup |
| A session stalls, errors, loops, or lies | references/derailment-recovery.md | Failure classification and bounded in-place recovery prompts |
| A session says complete or work must be merged | references/completion-gates.md | Exact-SHA, CI, runtime, deploy, worktree, and dirty-overlay proof |
Read only the references required by the current phase, then return to this control loop. Do not preload all references or copy their detailed checklists into prompts.
Resolve the installed script once so commands work from any project directory:
JEAN_OPS="${CODEX_HOME:-$HOME/.codex}/skills/orchestrate-projects-by-jean/scripts/jean_ops.py"
/usr/bin/python3 "$JEAN_OPS" doctor --probe
/usr/bin/python3 "$JEAN_OPS" projects
Resolve project → worktree → session with the returned IDs; high-level child-list commands verify their parent IDs before accepting an empty result. Use status, compact messages, and changes for bounded evidence. messages --limit N returns at most N message records and omits tool payloads unless --include-tool-details is explicit. Inspect schema TOOL or capabilities before supplying unfamiliar arguments. For a long-running session, start watch-session through the shell execution tool without &; pin it with --expect-run-id or --after-run-id, and continue its returned shell session_id with the matching stdin/poll tool. The script acquires a durable session lease and checkpoints each event, but an observed terminal run is only a routing signal—run completion gates before approval.
Use Computer Use only where the visible app is authoritative: confirm Jean is already running, identify the selected session, set or verify backend/model/YOLO, handle approvals, submit a UI-owned prompt, and prove that prompt appeared and started. When UI and MCP disagree, stop mutations and reconcile identity.
Example contract:
Input: Babysit every active Jean project until terminal; do not restart Jean.
Output: marketing-mcp — verified complete at <SHA>; exact-SHA CI success; runtime probe passed; merged worktree retired.
aura-monorepo — recovering in existing session; prompt visibly started; watcher owns run <ID> until <deadline>.
Run Frame → Inventory → Steer → Observe → Verify → Close. Re-enter at Inventory whenever the UI or repo state changes materially.
Translate the user's outcome into one sentence. Record the supervision horizon before acting:
The user's explicit horizon wins. “Babysit” does not silently convert “one sweep” or “check now” into an endless loop. Use references/monitoring-and-automations.md for the execution method.
If the user gives no horizon, default to a bounded sweep. Do not create a heartbeat, schedule, worker, session, or worktree merely to make supervision persistent.
Typical terminal conditions are:
If project instructions, a plan, or a named decision file exists, read it before steering that project.
Run the read-only ops script to discover live project/worktree/session IDs and statuses, then use Computer Use to reconcile the selected Jean header/history and UI-only controls. Do not infer state from old chat memory. Resolve exact identity with references/jean-state-and-steering.md; never invent a repo root or a directory for a bare filename. Build or refresh a compact ledger:
| Project | Main purpose | Horizon/owner | Session/worktree | State | Last evidence | Blocker | Next action | Final SHA / proof |
|---|
Use the canonical state model in references/project-control-loop.md: active, waiting, stuck, recovering, failed, claims-complete, verification-failed, verified-ready, awaiting-authorization, verified-complete, inconsistent, orphaned/superseded, or terminal-blocked. Record exact branch/worktree names and already-achieved milestones so a recovery prompt cannot redo work.
Before the first mutation, reconcile the selected Jean header/history, Jean project/session/worktree identity, and repo branch/HEAD. If they conflict, stop mutations and resolve identity; do not average conflicting sources or pick the most convenient one.
Work in this order unless a project-specific dependency changes it:
Do not demand enterprise-scale design, exhaustive abstraction, or broad rewrites from a small product. Require rigor only where failure is expensive: auth, payments, data integrity, security, destructive operations, deployment, and repository history.
Before sending a prompt, read the session's current history—not only its possibly stale tab title—expanded tool result when relevant, repo instructions, and current git state. Apply the source hierarchy and prompt-start proof in references/jean-state-and-steering.md. A steering prompt must include:
Do not send generic prompts such as “continue,” “finish everything,” or “try again” when recovery context is available.
When the user authorizes YOLO mode, set it only on the intended existing session and verify the visible selection. YOLO removes routine agent approval pauses; it does not waive completion gates, Computer Use confirmations, or authorization boundaries.
After each action, fetch fresh Jean state. Progress means a new meaningful tool result, commit, test result, CI transition, deployment transition, or clarified blocker—not a higher tool-call count alone.
Use scripts/jean_ops.py watch-session for one session's read-only state transitions and references/monitoring-and-automations.md for its shell handle, CI/provider waits, and later wakeups. Honor the framed horizon: stop after a bounded sweep, keep an active turn alive only while that mode applies, or use a verified heartbeat/schedule for later wakeups. Never turn a bounded request into terminal-state monitoring and never invent loop, monitor, cron, or scheduling parameters.
When a session claims completion, run references/completion-gates.md. Route failed claims back to the same session with the missing evidence or work stated precisely. Approve only after the proof matches the claim.
Close a project only after intended commits are integrated, exact-SHA gates are terminal, unrelated overlays are preserved, and merged worktrees/branches are safely retired according to repo rules and authorization.
Use the canonical topology and mission template in references/project-control-loop.md. At most one persistent worker observes/verifies each independent project when delegation is allowed; the manager owns Jean UI, steering, cross-project priority, and final approval. While a Jean run owns a worktree, a worker is observer/verifier-only. Direct implementation requires an idle/stopped Jean turn and explicit exclusive worktree ownership. The script's session lease is the durable cross-task ownership record; conversation ledgers alone are not enough.
Decide autonomously when the choice is reversible, local to the authorized project, and supported by evidence. Examples: selecting an equivalent model/backend already authorized for the same provider, cost, privacy, and data-residency boundary after a quota error; cancelling one frozen agent turn after recording and reconciling any non-idempotent operation; adding a timeout to a read-only probe; choosing the next critical-path project; asking an agent to restore its own preserved stash; or requesting missing exact-SHA proof.
Ask only when the decision changes product intent, creates spend, loses data/history, needs a genuinely unavailable secret, or expands outward impact beyond the user's authorization.
references/computer-use-runbook.md.references/jean-state-and-steering.md.references/derailment-recovery.md.references/monitoring-and-automations.md.references/completion-gates.md.After an exception, refresh the ledger and re-enter at Inventory. Do not resume from stale UI indices, SHAs, ownership, or wait handles.
During supervision, keep user updates short and decision-oriented:
Final handoff lists each project with target outcome, final disposition, exact SHA when applicable, CI/runtime/deploy proof, and worktree/branch cleanup. Never collapse “code exists,” “CI is green,” and “deployed behavior works” into one claim.
For a bounded sweep, distinguish observed active from verified complete; observation is a valid handoff state, not a reason to invent a completion claim. For recurring supervision, include the automation identity and next wakeup only when verified from the live schema.
jean_ops.py to launch or mutate Jean; it is a read-only observer and refuses mutation tools.jean_ops.py leases and reconcile the owner.