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
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
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)
