ce-work

name	ce-work
description	Execute a plan or concrete work prompt end-to-end. Use when implementing from docs/plans, a spec path, or a clear build request; use ce-debug for open-ended bugs.
argument-hint	[Plan doc path or description of work. Blank to auto use latest plan doc]

Work Execution Command

Execute work efficiently while maintaining quality and finishing features.

Introduction

This command takes a work document (plan or specification) or a bare prompt describing the work, and executes it systematically. The focus is on shipping complete features by understanding requirements quickly, following existing patterns, and maintaining quality throughout.

Running inside Fusion (autonomous workflow step)

When the environment variable FUSION_WORKFLOW_STEP is set, you are running as a Fusion workflow step, not an interactive session:

• No synchronous user. Do not call AskUserQuestion (no listener). If you must ask a genuinely blocking question, emit a single await-input block and stop — Fusion pauses the task and surfaces it on the task card, then re-runs this step with the reply as the latest steering comment:

  ===FUSION_AWAIT_INPUT===
  <your single clear question>
  ===END_FUSION_AWAIT_INPUT===
  

  If FUSION_HEADLESS is also set, do not ask — proceed on reasonable assumptions and note them.

• Sub-agent dispatch uses fn_spawn_agent, not Task. To run a ce-* persona, read its def from ${FUSION_CE_AGENTS_DIR}/<persona>.md, strip the frontmatter, and pass the body as fn_spawn_agent's systemPromptOverride (with an appropriate role) and the unit scope as task. If FUSION_CE_AGENTS_DIR is unset or the def is missing, run the unit inline (single-agent) rather than failing. Parallel/worktree dispatch still applies — each fn_spawn_agent child already runs in its own worktree.

Input Document

<input_document> #$ARGUMENTS </input_document>

Execution Workflow

Phase 0: Input Triage

First, parse a leading mode token. If <input_document> begins with mode:return-to-caller (or the legacy aliases mode:caller-owned-tail / caller:lfg), strip that token before anything else: the remainder of the string is the plan path, and this run executes in Return-to-Caller Mode (see § Return-to-Caller Mode) — implement and locally verify only, then return the structured envelope instead of running the standalone shipping tail. Classify the stripped plan path with the rules below. A mode token with no following path is an error: report it rather than treating mode:return-to-caller as a bare prompt.

Determine how to proceed based on what was provided in <input_document> (after any mode token is stripped).

Plan document (input is a file path to an existing plan or specification): read the plan's metadata first — YAML frontmatter for a markdown plan, or the visible header text for an HTML plan (both formats carry the same fields).

• If it carries artifact_contract: ce-unified-plan/v1, classify artifact_readiness before reading the body.
  • artifact_readiness: requirements-only -> stop and tell the user this Product Contract needs ce-plan enrichment before implementation. Offer the exact ce-plan <plan-path> handoff.
  • artifact_readiness: implementation-ready plus execution: code -> continue to Phase 1 using the unified-plan reader strategy below.
  • Any other readiness value or any non-code/unclassified execution mode -> do not auto-execute as code. Route execution: knowledge-work to the non-code carve-out; otherwise ask the user to return to ce-plan to produce an implementation-ready code plan.
  • Progress-like values (active, in_progress, completed, done) are invalid readiness values. Stop and ask for plan repair rather than guessing.
• If it carries execution: knowledge-work, this is a non-code plan — read references/non-code-execution.md and follow that carve-out instead of the rest of this workflow.
• Otherwise (legacy plan, field absent, or execution: code) -> continue to Phase 1 and run the normal code lifecycle.

Blank invocation latest-plan discovery: when <input_document> is blank, glob docs/plans/*.md and docs/plans/*.html, inspect metadata for the newest candidates, and only auto-select a plan that is artifact_readiness: implementation-ready plus execution: code or a legacy code plan. Stop instead of silently executing when the newest matching artifact is requirements-only, execution: knowledge-work, an approach-plan, or an unclassified universal/answer-seeking output. Ask for an explicit path or a ce-plan enrichment step. Superseded sibling: if a requirements-only candidate has a same-basename file in the other format (<basename>.md / <basename>.html) that is implementation-ready, a format conversion left the requirements-only copy stale — select the implementation-ready sibling and execute it rather than stopping.

Bare prompt (input is a description of work, not a file path):

1. Scan the work area

   • Identify files likely to change based on the prompt
   • Find existing test files for those areas (search for test/spec files that import, reference, or share names with the implementation files)
   • Note local patterns and conventions in the affected areas

2. Assess complexity and route

   Complexity	Signals	Action
   Trivial	1-2 files, no behavioral change (typo, config, rename)	Proceed to Phase 1 step 2 (environment setup), then implement directly — no task list, no execution loop. Apply Test Discovery if the change touches behavior-bearing code
   Small / Medium	Clear scope, under ~10 files	Build a task list from discovery. Proceed to Phase 1 step 2
   Large	Cross-cutting, architectural decisions, 10+ files, touches auth/payments/migrations	Inform the user this would benefit from /ce-brainstorm or /ce-plan to surface edge cases and scope boundaries. Honor their choice. If proceeding, build a task list and continue to Phase 1 step 2

---

Phase 1: Quick Start

1. Read Plan and Clarify (skip if arriving from Phase 0 with a bare prompt)

   • For unified plans, size your read. A short plan (lightweight or requirements-only, a screen or two) can be read in full. For a long implementation-ready plan, do not read the whole document first — it is expensive and unnecessary. Build a section map, then read only what the active unit needs: metadata, then Goal Capsule, Verification Contract, Definition of Done, the Implementation Units heading list, and only the active U-ID section plus referenced R/F/AE/KTD excerpts. Read appendices or unrelated U-IDs only when the active unit cites them. To build the map: in markdown scan headings (rg -n '^#{1,3} ' <plan> — top-level sections plus ### U<N>. units); in HTML scan the <h1>–<h3> heading elements and their anchor ids. Match on the stable section names / unit IDs (Goal Capsule, Verification Contract, ### U<N>., …), ignoring HTML wrapper tags — not on a format-specific pattern.
   • For legacy plans, read the work document completely. Both formats (.md, .html) carry the same section names and IDs; HTML just wraps them in semantic elements (<section>, <article>, etc.).
   • Treat the plan as a decision artifact, not an execution script
   • If the plan includes sections such as Implementation Units, Work Breakdown, Requirements (or legacy Requirements Trace), Files, Test Scenarios, or Verification, use those as the primary source material for execution
   • Check for Execution note on each implementation unit — these carry the plan's execution posture signal for that unit (for example, test-first or characterization-first). Note them when creating tasks.
   • Check for a Deferred to Implementation or Implementation-Time Unknowns section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-task
   • Check for a Scope Boundaries section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent work
   • Review any references or links provided in the plan
   • If the user explicitly asks for TDD, test-first, or characterization-first execution in this session, honor that request even if the plan has no Execution note
   • If anything is unclear or ambiguous, ask clarifying questions now
   • If clarifying questions were needed above, get user approval on the resolved answers. If no clarifications were needed, proceed without a separate approval step — plan scope is the plan's authority, not something to renegotiate
   • Do not skip this - better to ask questions now than build the wrong thing
   • Do not edit the plan body during execution. The plan is a decision artifact; progress lives in git commits and the task tracker, not the plan. ce-work does not mutate the plan — whether it shipped is derived from git, not recorded in the doc. Legacy plans may contain - [ ] / - [x] marks on unit headings or a status: field — ignore them as state; per-unit completion is determined during execution by reading the current file state.

2. Setup Environment

   First, check the current branch:

   current_branch=$(git branch --show-current)
   default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
   
   # Fallback if remote HEAD isn't set
   if [ -z "$default_branch" ]; then
     default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
   fi
   

   If already on a feature branch (not the default branch):

   First, check whether the branch name is meaningful — a name like feat/crowd-sniff or fix/email-validation tells future readers what the work is about. Auto-generated worktree names (e.g., worktree-jolly-beaming-raven) or other opaque names do not.

   If the branch name is meaningless or auto-generated, suggest renaming it before continuing:

   git branch -m <meaningful-name>
   

   Derive the new name from the plan title or work description (e.g., feat/crowd-sniff). Present the rename as a recommended option alongside continuing as-is.

   Then ask: "Continue working on [current_branch], or create a new branch?"

   • If continuing (with or without rename), proceed to step 3
   • If creating new, follow Option A or B below

   If on the default branch, choose how to proceed:

   Option A: Create a new branch

   git pull origin [default_branch]
   git checkout -b feature-branch-name
   

   Use a meaningful name based on the work (e.g., feat/user-authentication, fix/email-validation).

   Option B: Use a worktree (recommended for parallel development)

   skill: ce-worktree
   # Ensures isolation: detects an existing worktree, prefers the harness's
   # native worktree tool, else creates one from the default branch
   

   Option C: Continue on the default branch

   • Requires explicit user confirmation
   • Only proceed after user explicitly says "yes, commit to [default_branch]"
   • Never commit directly to the default branch without explicit permission

   Recommendation: Use worktree if:

   • You want to work on multiple features simultaneously
   • You want to keep the default branch clean while experimenting
   • You plan to switch between branches frequently

3. Create Task List (skip if Phase 0 already built one, or if Phase 0 routed as Trivial)

   • Use the platform's task tracking tool (TaskCreate/TaskUpdate/TaskList in Claude Code, update_plan in Codex, or the equivalent on other harnesses) to break the plan into actionable tasks
   • Derive tasks from the plan's implementation units, dependencies, files, test targets, and verification criteria
   • When the plan defines U-IDs for Implementation Units, preserve the unit's U-ID as a prefix in the task subject (e.g., "U3: Add parser coverage"). This keeps blocker references, deferred-work notes, and final summaries anchored to the same identifier the plan uses, so progress and traceability remain unambiguous across plan edits
   • Carry each unit's Execution note into the task when present
   • For each unit, read the Patterns to follow field before implementing — these point to specific files or conventions to mirror
   • Use each unit's Verification field as the primary "done" signal for that task
   • Do not expect the plan to contain implementation code, micro-step TDD instructions, or exact shell commands
   • Include dependencies between tasks
   • Prioritize based on what needs to be done first
   • Include testing and quality check tasks
   • Keep tasks specific and completable

4. Choose Execution Engine, then Strategy

   For an implementation-ready unified code plan, first pick the engine that runs implementation: inline/subagent (default and only callable engine on Claude Code), goal-mode, or dynamic-workflow. Goal-mode and dynamic-workflow are usable only when the host exposes a callable primitive for them — Codex exposes create_goal (a skill can start a goal directly), while Claude Code exposes no goal tools, so on Claude Code they are prompt-emission only (never invoked from inside this skill). Prefer dynamic-workflow over goal-mode for large fan-out plans (many independent U-IDs, codebase-wide sweeps, migrations, adversarial cross-checking). Read references/execution-engines.md for the host-capability probe, the plan-shape selection table, the copyable goal-mode/ultracode: prompts, and the resume-tail rules. An engine choice never changes tail ownership — after implementation, resume standalone quality gates in normal use, or return the return-to-caller envelope when invoked by lfg. Legacy and bare-prompt work skip this and use the inline/subagent engine directly.

   For the inline/subagent engine, prefer subagents for any structured multi-unit plan — each worker gets a fresh context window for one unit. Parallelize independent units whenever it is safe; fall back to serial only when parallel isn't safe or the harness can't isolate concurrent writes. Let the plan's Dependencies and Files drive batching: run an independent dependency layer together, then the next.

   Strategy	When to use
   Inline	Trivial work (1-2 files, no real decomposition), work needing user interaction mid-flight, or bare prompts that lack structured units
   Serial subagents	The default for structured multi-unit plans whose units are dependent, few, or whose parallel-safety is uncertain. Fresh context per unit, executed in dependency order
   Parallel subagents	Independent units (per the Parallel Safety Check) when you want the speed and the harness can isolate concurrent work. Run a dependency layer at once, then the next

   Parallel Safety Check — before dispatching a batch in parallel:

   1. Map files to units from each candidate unit's Files: section (Create/Modify/Test paths).
   2. File overlap is necessary but not sufficient. Also serialize units that contend on things absent from Files:: shared types/APIs/interfaces, DB migrations, generated artifacts or clients, lockfiles, snapshots, shared config/schema — or an environment singleton (one dev server/port, a shared database, browser sessions, package installs, MCP rate limits). Reason about these; don't just diff paths.
   3. No contention: dispatch the batch in parallel.
   4. Contention with harness-native isolation: parallel is recoverable (isolated workers don't lose each other's writes) but not automatically safe — overlapping edits still need a real merge. Serialize contending units by default; run them parallel-isolated only when the expected merge is trivial. Log the predicted overlap.
   5. Contention without isolation (shared workspace): serialize — in a shared directory only the last writer survives.
   6. Cap concurrency at a bounded batch (~3-5 workers) even when more units are independent; over-parallelizing costs more in contention, merge, and integration than it saves.
   7. Abort criteria: if a batch produces broad unplanned edits, out-of-scope test failures, or repeated conflicts, stop parallelizing and finish the rest serially.

   Isolation is the harness's job, never ce-work's — never run git worktree add yourself. Probe what your subagent mechanism provides and pick the parallel path:

   • Harness-native isolated workers — each worker edits an isolated workspace the harness manages: Claude Code Agent tool (isolation: "worktree" + run_in_background: true; worktree under a gitignored .claude/worktrees/), Codex spawn_agent (a coding worker edits its forked workspace), Cursor best-of-n-runner. Parallelize freely here, including overlapping-file units (subject to the Safety Check's merge-cost judgment). This works even when you are already inside a worktree — harness worktrees are peers of one repo, not nested, branched from your current HEAD.
   • Shared workspace only — subagents run in your working directory (Cursor Task default, or any harness without isolation). Parallelize disjoint-file units only, under the shared-workspace constraints below; contending units run serial.
   • No subagent mechanism: run inline.

   Dispatch uses your harness's subagent/worker mechanism. Give each worker:

   • The plan path plus a bounded unit packet — Goal Capsule, Definition of Done, the unit's section, the Verification Contract entries relevant to it, and any referenced R/F/AE/KTD excerpts. Do not send "read the whole plan" as the worker prompt. (For a legacy non-unified plan, the plan path for reference is acceptable.)
   • The unit's Goal, Files, Approach, Execution note, Patterns, Test scenarios, Verification, and any resolved deferred questions for it.
   • Instruction to check whether the unit's test scenarios cover all applicable categories (happy paths, edge cases, error paths, integration) and supplement gaps before writing tests.
   • Instruction to report, in its final message, the file paths it changed — the handoff is a text summary on most harnesses with no guaranteed diff, so reported paths are the orchestrator's starting hint (it still verifies the actual tree).
   • Do not commit. Workers implement and may run their own unit's focused tests in isolation as a self-check, but the orchestrator owns staging, committing, and the authoritative test runs. (Capability note: a harness that reaps the isolated workspace on worker completion — none of our current targets do — would instead require the worker to commit to its branch; confirm before assuming it.)

   Shared-workspace constraints — when subagents share your working directory (no isolation): they must not git add, commit, or run the full test suite concurrently (index corruption + test interference); the orchestrator does all of that after the batch. A worker may run a single focused unit test only if it touches no shared state.

   Permission mode: Omit the mode parameter when dispatching subagents so the user's configured permission settings apply. Do not pass mode: "auto" — it overrides user-level settings like bypassPermissions.

   After each serial unit: review the diff against the unit's scope and Files:, run the relevant tests, fix before dispatching the next (never on a broken tree), update the task list (never edit the plan body — progress lives in commits), and commit. Then dispatch the next unit.

   After a parallel batch — the orchestrator integrates; never trust the handoff summary alone:

   1. Wait for every worker in the batch to finish.
   2. Inspect the actual tree, not reported paths. Determine what each worker really changed (git status/diff in its workspace or the shared dir). Reported paths are a hint; declared Files: are often incomplete — workers create/modify files the plan didn't anticipate.
   3. Detect real collisions — 2+ workers that actually modified the same file. In a shared workspace only the last writer survived: commit the non-colliding work first, then re-run the colliding units serially so each builds on the other's committed result. With harness-native isolation the collision surfaces as a merge conflict at integration instead (see the per-harness note).
   4. Review, test, and commit each unit in dependency order — the orchestrator owns commits. Stage only that unit's files, commit with a message derived from its Goal, run the relevant tests, and fix before the next.
   5. Update the task list (progress lives in the commits).
   6. Release the workers — close/clean up each worker handle so it stops holding a concurrency slot or leaving orphans (e.g., Codex close_agent; for a Claude per-worker worktree: git worktree unlock <path> → git worktree remove <path> → git branch -d <branch>). These isolated worktrees are peers invisible to any outer orchestrator (e.g., Orca), so cleanup is entirely ce-work's.
   7. Dispatch the next dependency layer.

   Per-harness integration (examples — the universal flow above is the contract):

   • Claude Agent isolation:"worktree": each worker is on its own branch. Integrate by merging each branch into the orchestrator's branch in dependency order; on conflict, git merge --abort and re-run that unit serially against the merged tree (hand-resolving silently discards one unit's intent).
   • Codex spawn_agent worker: integrate the worker's "uploaded changes," then close_agent.
   • Cursor Task (shared workspace): edits are already in your tree — review and commit per step 4; best-of-n-runner: integrate its worktree.

Phase 2: Execute

1. Task Execution Loop

   For each task in priority order: