Use when the user asks to build, implement, fix, or execute a plan — detects context (existing plan, new feature, bug, quick task, visual input) and routes through brainstorming, planning, debugging, or execution workflows
Installation
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.
Use when the user asks to build, implement, fix, or execute a plan — detects context (existing plan, new feature, bug, quick task, visual input) and routes through brainstorming, planning, debugging, or execution workflows
x-do is a router. It classifies the user's request, detects mode, and dispatches to the right executor. It does not apply code changes itself in Modes A, B, E, or F.
x-do MUST NOT (in Modes A, B, E, F):
Call Edit or Write directly — dispatch to an executor subagent via Agent tool or ralph
Call Bash to run mutating commands on project files — dispatch to a verifier/executor
Mode D exception: Quick tasks (single file, <10 lines, no ambiguity) may use Edit/Write directly. Mode D was designed for this — spawning an executor for s/foo/bar/ adds 30-60s overhead for zero benefit. The forbid applies to complex work, not trivial edits.
Post-execution correction exception: After an executor completes and the user provides a targeted correction (≤ 3 files, clear instructions, no investigation needed), x-do may apply corrections directly using Edit/Write. For corrections spanning 4+ files or requiring investigation, dispatch a new executor.
Always allowed:
Read for loading gotchas, config, referenced files
Skill tool for dispatching to x-research, writing-plans, etc.
Agent tool for launching executor / verifier subagents
Bash for dispatching OMO agents via omo-agent
Self-check (Modes A, B, E, F only):
If you're about to call Edit/Write/mutating Bash and you're NOT in Mode D, STOP.
x-do routes. It does not execute. Dispatch to an executor subagent via Agent tool.
Completion (MANDATORY)
Before claiming done, resolve the verifier slot per ../x-shared/slot-schema.md § "Slot precedence (v1 — 3-layer cascade)":
User in-prompt override? ("use x-review for verification this time", "skip verification") → wins.
Schema default (would be verification-before-completion) — only if 1 and 2 are silent.
Surface the resolution inline before dispatching, e.g. Dispatching verifier slot → resolved to x-verify via skill frontmatter default. Then dispatch the resolved value via the Skill tool (skills) or Agent tool (OMC agents) per ../x-shared/invocation-guide.md § "skill-or-agent-typed slot dispatch".
# Default resolution (no override): Skill tool: x-verify
x-verify runs the completion cascade (see ../x-shared/completion-cascade.md). Honor its verdict:
verdict: done → proceed to the handoff menu
verdict: failed → fire verification-failed reaction (routes to re-review, then re-execute if approved)
verdict: needs-user-review → surface x-verify's menu to the user, wait for input
verdict: aborted → exit the current workflow immediately; do not proceed to the handoff menu. Report the abort reason (user-abort or stagnation-option-D) to the user.
verdict: waiting-for-user → surface x-verify's menu (e.g., stagnation A/B/C/D) and pause. Do NOT loop or re-dispatch until the user answers.
Do not claim done without calling x-verify. This is the single biggest compliance-gap closer.
x-do — Universal Work Command
Smart entry point that detects what to do and routes through the optimal workflow.
Bootstrap
MANDATORY first step — do this BEFORE anything else:
Pin capabilities for the session per ../x-shared/capability-loading.md (look for the [x-skills/capabilities] snapshot injected by SessionStart; otherwise read ~/.config/x-skills/capabilities.json once). Filter routing tables against the pinned set; do NOT re-check per dispatch. If mcp.gitnexus is pinned, also consume the shared session-pinned indexed+fresh probe per ../x-shared/capability-loading.md § "Shared GitNexus Indexed+Fresh Probe" — do NOT run an independent gitnexus list; read the single pinned record. (F3)
Read ../x-omo/SKILL.md to load the OMO agent catalog, invocation commands, and model routing. This ensures you know how to invoke OMO agents (oracle, explore, librarian, multimodal-looker) via Bash — they are NOT OMC agents. For the unavailable-agent list and replacement model-routing (--model codex, --model gpt), see ../x-shared/omo-routing.md § Unavailable Agents.
Invocation
For how to invoke skills, OMO agents, and OMC agents, see ../x-shared/invocation-guide.md.
For x-do-specific routing, see references/omo-routing.md.
Research Gate
Before classifying mode, check: does this task need research first?
Trigger rule: if ANY of the following hold, dispatch Skill: x-skills:x-research first and return on its envelope, then re-enter this skill skipping step-01-gather.md:
Unfamiliar library, framework, API, or external system involved
Requirements vague AND scope crosses 3+ modules
"How does X work in our codebase?" must be answered before fixing/building
User explicitly asks for research / investigation / understanding
x-research owns the signal taxonomy and tool selection — do NOT re-classify here. When it completes, it will offer to hand off to x-do; use its envelope to skip step-01-gather.md (requirements already collected).
Return path: If x-research just completed in the same session and provided findings/context, skip this gate entirely. Continue to the Pre-Flight Checklist, then Detection. This includes cases where x-research's quick-action exception applied a small fix inline.
Pre-Flight Checklist (MANDATORY)
Complete ALL of these checks BEFORE Detection (mode classification) below:
--wt flag detection: Scan the user prompt for --wt (with optional <target_branch> and optional <new_branch>). Also scan for --wt-no-isolate (caller-side flag — translates to passing --no-isolate through to x-worktree, suppressing auto-isolation). If present:
Strip the entire --wt … segment AND any --wt-no-isolate token from the prompt — mode classification must NOT see them.
Dispatch via Skill: x-skills:x-worktree with the parsed args (empty string if a slot was omitted). Append --no-isolate to the inner args when --wt-no-isolate was set.
Parse the returned envelope. Pin WORKTREE_PATH for the rest of this task.
From this point, every mutating Bash / Agent / OMC executor / OMO dispatch MUST run inside WORKTREE_PATH per the cwd-propagation rules in ../x-worktree/SKILL.md § "CWD propagation". Forward WORKTREE_PATH in any handoff envelope (e.g., x-do → x-bugfix).
Parse ISOLATE_APPLIED and act on it (see ../x-worktree/references/auto-isolation.md for the full contract):
ISOLATE_APPLIED=true → Read $WORKTREE_PATH/.worktree-isolate/state.local.json, validate schema == 1 (refuse on mismatch), build the DOCKER CONTEXT block per ../x-worktree/references/caller-integration.md § "DOCKER CONTEXT propagation". Prepend that block to every subsequent executor / Agent / OMC / OMO dispatch for the rest of the task. Reconstruct Launch: line at every dispatch from [ -f $WORKTREE_PATH/.env ] — never cache the rendered block.
ISOLATE_APPLIED=false → Surface ISOLATE_REASON + ISOLATE_HINT to the user via AskUserQuestion (2 options, default abort): (1) abort and let me retry isolate manually / (2) proceed without isolation, I accept docker collisions with my other worktrees. Default = abort.
ISOLATE_APPLIED=skipped → Proceed normally. No DOCKER CONTEXT block.
ISOLATE_APPLIED line absent (because --no-isolate / --wt-no-isolate was set) → Proceed normally. No DOCKER CONTEXT block.
If x-worktree returns ✗ Worktree FAILED, abort and surface the reason — do NOT silently continue in the original cwd.
Resume detection: Check for in-progress state (paths in config.json):
ralph_state — incomplete stories → offer to resume
specs_dir — uncommitted design docs → offer to continue
Draft plan files (spec-wip.md) → offer to continue
docs/backlog/*.md with frontmatter status: in-progress — a backlog doc abandoned mid-implementation (Mode A flipped it, the run never finished) → offer to resume it before starting anything new
Gotchas: Read gotchas.md for known failure patterns before starting
Memory recall — § Memory Reflex recall beat (../x-shared/mcp-toolbox.md): search_notes({ query: "<task keywords>", page_size: 5 }), fired BEFORE mode classification so Mode A and Mode D recall too — not just the Mode B steps/step-01-gather.md path. Prior similar tasks are leads, not verdicts. Gate: mcp.basic_memory pinned in the bootstrap-active set — otherwise skip silently.
Detection (pattern-match, no LLM judgment)
Classify into ONE of 4 modes via observable signals:
Mode
Detect When
Key Signals
A: Existing Plan
Prompt references an existing plan/spec/doc file path
.md file path that exists, "implement the plan", "execute the spec", numbered feedback list on a prior commit
B: New Work
Build / add / create / refactor with no plan referenced
Creative/new work, structural changes, no plan path in prompt
C: Bug Fix
Error, stack trace, or failure described
"fix", "bug", "error", "broken", "crash", "failing", stack trace text
D: Quick Task
Trivial single-file change, ≤ 10 lines, no ambiguity
After mode detection, only three axes drive routing — no scoring, no depth ladder:
Mode (A / B / C / D from Detection above)
Task count (from the plan, after step-02-plan) — 1-2 / 3+
Walk-away signal (from user prompt language) — present when the user says "until done" / "don't stop" / "walk away" / "finish overnight" / similar; otherwise absent (default = stay in session)
That's the entire routing surface. Depth scoring (Light / Standard / Heavy) and gitnexus-grounded impact routing are removed — they added complexity without proportional value. The optional x-mindful envelope consumption (Mode A handoff) remains intact: symbols named in envelope items are already analyzed, do NOT re-invoke impact.
Available Tools
See references/available-tools.md for the full tool table (MCP tools, skills, agents). Key rule: native Edit/Grep are the default for edits/search (use OMO explore for semantic search) — before spawning agents.
Proactive OMO Delegation
See references/delegation-and-scaling.md for signal→agent routing table and delegation rules. Key rule: after 2+ failed attempts, delegate to oracle or --model codex (replaces UNAVAILABLE hephaestus) — don't keep grinding.
Cross-Model Review
Cross-model review (plan or post-implementation) is delegated to x-review. Dispatch Skill: x-skills:x-review <target> and honor the returned verdict envelope. x-review owns reviewer fan-out, synthesis, severity tiering, passes menu, and Fix Mode. Do not redefine reviewer dispatch here.
Mode Guidance
See references/mode-guidance.md for detailed per-mode instructions. Key rules:
A/B: Plan Review — dispatch Skill: x-skills:x-review <plan-path> when plan has 3+ tasks or crosses modules. x-review owns the cross-model fan-out — single call, single envelope.
A: Consume x-mindful envelope when present. Symbols named in envelope items are already analyzed; do NOT re-invoke impact on them.
A/B: Post-Implementation Review mandatory before claiming done — dispatch Skill: x-skills:x-review on the diff.
B: Brainstorming gate — when no plan/spec ref provided, dispatch superpowers:brainstorming FIRST (creates design.md per project convention), then superpowers:writing-plans. Run explore in parallel to detect the convention. See steps/step-01-gather.md.
C: Delegate to /x-bugfix — uses systematic-debugging gate + debugger agent + TDD failing test before fix.
D: Direct execution via native Edit/Write, still verify.
Backlog Doc Lifecycle (Mode A)
Applies when the Mode A plan/spec path is under docs/backlog/ (an x-backlog doc). The
frontmatter edits and file move below are mechanical bookkeeping — an explicit exception to
the router forbid, same class as Mode D.
Worktree suggestion (once, before executing). If no --wt flag was passed AND cwd is
the main checkout ([ "$(cd "$(git rev-parse --git-dir)" && pwd)" = "$(cd "$(git rev-parse --git-common-dir)" && pwd)" ]
— canonicalize both sides via cd+pwd: the plain forms return mixed absolute/relative
paths from a subdirectory and false-negative there, and --path-format=absolute needs
git ≥ 2.31, above x-worktree's documented git ≥ 2.5 floor),
offer once via AskUserQuestion: (1) isolate — new worktree from this doc (recommended) /
(2) continue in current dir. On (1), dispatch Skill: x-skills:x-worktree <doc-path> and
honor the same envelope rules as Pre-Flight --wt steps 3–6 (pin WORKTREE_PATH,
ISOLATE_APPLIED handling). Already inside a linked worktree → skip silently. Also skip
(without asking) when this dispatch came from x-backlog's close menu [D] (/x-do <doc>
here) — the user just chose to stay in the current dir; re-offering a worktree would negate
that choice.
Status flip at start. Set frontmatter status: in-progress + updated: <today> before
dispatching executors, and flip the doc's row Status cell in docs/backlog/README.md to
in-progress in the same edit — the index must mirror frontmatter for the whole
implementation window. No separate commit — both ride with the implementation commits.
Do NOT roll this back on abort. A doc left at in-progress is not a bug — it is the
resume signal: the Pre-Flight resume-detection bullet scans for exactly this state and
offers to pick the work back up. Reverting status to backlog / ready would make an
abandoned run byte-indistinguishable from one never started, and silently defeat that scan.
Only step 3 (archive on completion) clears in-progress.
Archive on completion. After verification passes and commits are recomposed
(steps/step-04-execute.md § Execution step 6.5), archive the doc:
Destination from frontmatter type per ../x-backlog/references/template.md
§ "Archival on done": feat → docs/feature/, fix → docs/bugs/, anything else →
docs/<type>/. Missing type → derive via ../x-worktree/references/doc-naming.md
detection order.
git mv docs/backlog/<slug>.md docs/<dest>/<slug>.md (create the folder if absent;
destination already occupied → stop and ask per ../x-backlog/references/template.md
§ "Archival on done"); set status: done + updated: <today>; delete the doc's row from
docs/backlog/README.md (when that was the last row, add the empty-state line per the
same file's § "Index file").
Commit: docs: archive <slug> — done, moved to <dest>.
Skip all three silently for plans that are not backlog docs — this section adds nothing to
plain writing-plans output or ad-hoc specs.
Complexity Scaling
The 3-axis Routing Signals above replace previous file-count and depth heuristics. references/delegation-and-scaling.md is retained for its agent fallback table and escalation rules — ignore any scaling guidance in it that contradicts the 3-axis model.
Implementation Discipline (MANDATORY)
Every executor / ralph / --model codex / direct-execution route MUST carry the three rules from ../x-shared/instrument-and-verify.md into the implementation:
Log on first pass — structured logs at decision points (entry/exit, branches, state transitions, error catches, external boundaries) ship in the same diff as the implementation. Not a debugging afterthought.
Test-first for unknowns — before calling any unfamiliar lib/API/upstream-path, run a scratch script (REPL, node -e, curl -v, 10-line /tmp/scratch.*) and observe the REAL return shape / error class. Cite the artifact in the implementation rationale.
Never guess — every claim ("this lib returns X", "this endpoint accepts Y") needs a citation: file:line, test output, log line, doc URL, or a re-readable tool call result. Words like "probably", "I think", "should work" are STOP signals — go run an experiment instead.
These rules are forwarded into every executor dispatch via the [STANDING CONSTRAINTS] block in steps/step-04-execute.md § "Forward Intelligence". Do NOT strip them when composing the executor prompt.
Post-Implementation Verification (MANDATORY)
After completing implementation in any TS/JS project, run before claiming done:
Fix all errors before proceeding to review or completion.
Commit Recomposition (executor / ralph routes)
OMC executor and ralph commit per micro-step, producing noisy history. After verification passes, recompose into atomic, domain-grouped commits via the commit skill. See steps/step-04-execute.md § "Commit Recomposition" for the full procedure (capture BASE_SHA before dispatch → soft-reset → Skill commit → verify zero net diff). Skip if branch is already pushed/shared, or if user asked to preserve granular commits.
After This Skill
Use ../x-shared/done-format.md DONE shape. Next-step options typically: [A] commit · [B] x-review. Append · [L] save as skill when OMC plugin is available and the workflow was complex (3+ steps, multi-agent, novel pattern) — skip [L] silently otherwise. Handoff context block suppressed by default per done-format.md; include only when the next skill explicitly requires it. See ../x-shared/workflow-chains.md for chaining sequences.
Dependencies
This skill references shared infrastructure in ../x-shared/:
invocation-guide.md — tool invocation patterns (OMO via Bash, OMC via Agent)
