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.

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

Phase 2: Execute

1. Task Execution Loop

   For each task in priority order:

   while (tasks remain):
     - Mark task as in-progress
     - Read any referenced files from the plan or discovered during Phase 0
     - **If the unit's work is already present and matches the plan's intent** (files exist with the expected capability, or the unit's `Verification` criteria are already satisfied by the current code), the work has likely shipped on a prior branch or session. Verify it matches, mark the task complete, and move on. Do not silently reimplement.
     - Look for similar patterns in codebase
     - Find existing test files for implementation files being changed (Test Discovery — see below)
     - Implement following existing conventions
     - Add, update, or remove tests to match implementation changes (see Test Discovery below)
     - Run System-Wide Test Check (see below)
     - Run tests after changes
     - Assess testing coverage: did this task change behavior? If yes, were tests written or updated? If no tests were added, is the justification deliberate (e.g., pure config, no behavioral change)?
     - Mark task as completed
     - Evaluate for incremental commit (see below)
   

   When a unit carries an Execution note, honor it. For test-first units, write the failing test before implementation for that unit. For characterization-first units, capture existing behavior before changing it. For units without an Execution note, proceed pragmatically.

   Guardrails for execution posture:

   • Do not write the test and implementation in the same step when working test-first
   • Do not skip verifying that a new test fails before implementing the fix or feature
   • Do not over-implement beyond the current behavior slice when working test-first
   • Skip test-first discipline for trivial renames, pure configuration, and pure styling work

   Test Discovery — Before implementing changes to a file, find its existing test files (search for test/spec files that import, reference, or share naming patterns with the implementation file). When a plan specifies test scenarios or test files, start there, then check for additional test coverage the plan may not have enumerated. Changes to implementation files should be accompanied by corresponding test updates — new tests for new behavior, modified tests for changed behavior, removed or updated tests for deleted behavior.

   Test Scenario Completeness — Before writing tests for a feature-bearing unit, check whether the plan's Test scenarios cover all categories that apply to this unit. If a category is missing or scenarios are vague (e.g., "validates correctly" without naming inputs and expected outcomes), supplement from the unit's own context before writing tests:

Phase 3-4: Quality Check and Finishing Work

When all Phase 2 tasks are complete and execution transitions to quality check, you must read references/shipping-workflow.md for the full shipping workflow. Do not skip this.

Code review: one portable path. Review with ce-code-review, which self-sizes (lite roster for small low-risk code-only diffs, full roster otherwise). No harness-native review detection and no escalation tiers — the size/sensitive-surface judgment lives inside ce-code-review. Skip dedicated review only for a purely mechanical diff (formatting, dep-bumps, lint-only, generated). Full rules (autonomous Residual Gate, infra fallback) in shipping-workflow.md.

Review is two steps — review, then fix. ce-code-review is review-only. It returns findings (markdown or mode:agent JSON); it never edits the checkout, commits, or applies fixes.

1. Review — Invoke the ce-code-review skill (invocation command in references/review-findings-followup.md § Fallback). Use mode:agent in orchestrated workflows; pass plan:<path> when you have a plan, base:<ref> when the merge base is known, and depth:full when a deep/thorough review was explicitly requested.
2. Apply fixes — Load references/review-findings-followup.md. Filter eligibility on JSON only, batch applicable findings by file, dispatch fix subagents (parallel when file sets are disjoint). The orchestrator merges diffs, runs tests, and commits — it does not pre-investigate findings.
3. Residual Work Gate — Only after followup; unresolved actionable findings go through the gate in shipping-workflow.md (autonomous sessions auto-accept + record residuals; interactive sessions ask).

Return-to-Caller Mode

mode:return-to-caller <plan-path> (legacy alias: mode:caller-owned-tail) is reserved for orchestrators such as lfg that own simplification, code review, PR creation, and CI watching after implementation. In this mode ce-work performs implementation and local verification only, then returns a structured summary instead of running the standalone shipping tail.

Return:

• status: complete, blocked, or failed
• plan_path
• changed_files
• u_ids_attempted
• u_ids_completed
• verification_results
• blockers
• behavior_change: whether behavior-bearing code changed
• standalone_shipping_skipped: true

Engine selection (references/execution-engines.md) still applies in this mode, but only for implementation. In return-to-caller mode do not emit a copyable goal/workflow prompt — a manual paste step strands the caller; run inline/subagents or return a blocker instead. Any goal/workflow engine used here must not open a PR, run the owner workflow tail, or bypass the caller-owned gates.

Key Principles

Start Fast, Execute Faster

• Get clarification once at the start, then execute
• Don't wait for perfect understanding - ask questions and move
• The goal is to finish the feature, not create perfect process

The Plan is Your Guide

• Work documents should reference similar code and patterns
• Load those references and follow them
• Don't reinvent - match what exists

Test As You Go

• Run tests after each change, not at the end
• Fix failures immediately
• Continuous testing prevents big surprises

Quality is Built In

• Review every non-mechanical diff with ce-code-review (it self-sizes; see shipping-workflow.md)

Ship Complete Features

• Mark all tasks completed before moving on
• Don't leave features 80% done
• A finished feature that ships beats a perfect feature that doesn't

Common Pitfalls to Avoid

• Analysis paralysis - Don't overthink, read the plan and execute
• Skipping clarifying questions - Ask now, not after building wrong thing
• Ignoring plan references - The plan has links for a reason
• Testing at the end - Test continuously or suffer later
• Forgetting to track progress - Update task status as you go or lose track of what's done
• 80% done syndrome - Finish the feature, don't move on early
• Skipping review without reason — review every non-mechanical diff with ce-code-review; skip only for a purely mechanical diff or when it is genuinely unavailable, and document the skip reason
• Re-scoping the plan into human-time phases - The plan's Implementation Units define the scope of execution. Do not estimate human-hours per unit, propose multi-day breakdowns, or ask the user to pick a subset of units for "this session". Agents execute at agent speed, and context-window pressure is addressed by subagent dispatch (Phase 1 Step 4), not by phased sessions. If a plan-file input is genuinely too large for a single execution, say so plainly and suggest the user return to /ce-plan to reduce scope — don't invent session phases as a workaround. For bare-prompt input, Phase 0's Large routing already handles oversized work