Ce:Work

Work Execution Command

Execute work efficiently while maintaining quality and finishing features.

Introduction

This command takes a work document (plan, specification, or todo file) 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

Determine how to proceed based on what was provided in <input_document>.

Plan document (input is a file path to an existing plan, specification, or todo file) → skip to Phase 1.

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

---

Phase 1: Quick Start

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

• Read the work document completely
• Treat the plan as a decision artifact, not an execution script
• If the plan includes sections such as Implementation Units, Work Breakdown, 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
• Get user approval to proceed
• Do not skip this - better to ask questions now than build the wrong thing

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: git-worktree
   # The skill will create a new branch from the default branch in an isolated worktree

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 Todo List _(skip if Phase 0 already built one, or if Phase 0 routed as Trivial)_

• Use your available task tracking tool (e.g., TodoWrite, task lists) to break the plan into actionable tasks
• Derive tasks from the plan's implementation units, dependencies, files, test targets, and verification criteria
• 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 Strategy

After creating the task list, decide how to execute based on the plan's size and dependency structure:

Parallel Safety Check — required before choosing parallel dispatch:

1. Build a file-to-unit mapping from every candidate unit's Files: section (Create, Modify, and Test paths) 2. Check for intersection — any file path appearing in 2+ units means overlap 3. If any overlap is found, downgrade to serial subagents. Log the reason (e.g., "Units 2 and 4 share config/routes.rb — using serial dispatch"). Serial subagents still provide context-window isolation without shared-directory risks

Even with no file overlap, parallel subagents sharing a working directory face git index contention (concurrent staging/committing corrupts the index) and test interference (concurrent test runs pick up each other's in-progress changes). The parallel subagent constraints below mitigate these.

Subagent dispatch uses your available subagent or task spawning mechanism. For each unit, give the subagent:

• The full plan file path (for overall context)
• The specific unit's Goal, Files, Approach, Execution note, Patterns, Test scenarios, and Verification
• Any resolved deferred questions relevant to that unit
• 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

Parallel subagent constraints — when dispatching units in parallel (not serial or inline):

• Instruct each subagent: "Do not stage files (git add), create commits, or run the project test suite. The orchestrator handles testing, staging, and committing after all parallel units complete."
• These constraints prevent git index contention and test interference between concurrent subagents

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 subagent completes (serial mode): 1. Review the subagent's diff — verify changes match the unit's scope and Files: list 2. Run the relevant test suite to confirm the tree is healthy 3. If tests fail, diagnose and fix before proceeding — do not dispatch dependent units on a broken tree 4. Update the plan checkboxes and task list 5. Dispatch the next unit

After all parallel subagents in a batch complete: 1. Wait for every subagent in the current parallel batch to finish before acting on any of their results 2. Cross-check for discovered file collisions: compare the actual files modified by all subagents in the batch (not just their declared Files: lists). Subagents may create or modify files not anticipated during planning — this is expected, since plans describe what not how. A collision only matters when 2+ subagents in the same batch modified the same file. In a shared working directory, only the last writer's version survives — the other unit's changes to that file are lost. If a collision is detected: commit all non-colliding files from all units first, then re-run the affected units serially for the shared file so each builds on the other's committed work 3. For each completed unit, in dependency order: review the diff, run the relevant test suite, stage only that unit's files, and commit with a conventional message derived from the unit's Goal 4. If tests fail after committing a unit's changes, diagnose and fix before committing the next unit 5. Update the plan checkboxes and task list 6. Dispatch the next batch of independent units, or the next dependent unit

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
     - 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:

System-Wide Test Check — Before marking a task done, pause and ask:

When to skip: Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."

When this matters most: Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.

2. Incremental Commits

After completing each task, evaluate whether to create an incremental commit:

Heuristic: "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."

If the plan has Implementation Units, use them as a starting guide for commit boundaries — but adapt based on what you find during implementation. A unit might need multiple commits if it's larger than expected, or small related units might land together. Use each unit's Goal to inform the commit message.

Commit workflow:

   # 1. Verify tests pass (use project's test command)
   # Examples: bin/rails test, npm test, pytest, go test, etc.

   # 2. Stage only files related to this logical unit (not `git add .`)
   git add <files related to this logical unit>

   # 3. Commit with conventional message
   git commit -m "feat(scope): description of this unit"

Handling merge conflicts: If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.

Note: Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.

Parallel subagent mode: When units run as parallel subagents, the subagents do not commit — the orchestrator handles staging and committing after the entire parallel batch completes (see Parallel subagent constraints in Phase 1 Step 4). The commit guidance in this section applies to inline and serial execution, and to the orchestrator's commit decisions after parallel batch completion.

3. Follow Existing Patterns

• The plan should reference similar code - read those files first
• Match naming conventions exactly
• Reuse existing components where possible
• Follow project coding standards (see AGENTS.md; use CLAUDE.md only if the repo still keeps a compatibility shim)
• When in doubt, grep for similar implementations

4. Test Continuously

• Run relevant tests after each significant change
• Don't wait until the end to test
• Fix failures immediately
• Add new tests for new behavior, update tests for changed behavior, remove tests for deleted behavior
• Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together. If your change touches callbacks, middleware, or error handling — you need both.

5. Simplify as You Go

After completing a cluster of related implementation units (or every 2-3 units), review recently changed files for simplification opportunities — consolidate duplicated patterns, extract shared helpers, and improve code reuse and efficiency. This is especially valuable when using subagents, since each agent works with isolated context and can't see patterns emerging across units.

Don't simplify after every single unit — early patterns may look duplicated but diverge intentionally in later units. Wait for a natural phase boundary or when you notice accumulated complexity.

If a /simplify skill or equivalent is available, use it. Otherwise, review the changed files yourself for reuse and consolidation opportunities.

6. Figma Design Sync (if applicable)

For UI work with Figma designs:

• Implement components following design specs
• Use figma-design-sync agent iteratively to compare
• Fix visual differences identified
• Repeat until implementation matches design

6. Track Progress

• Keep the task list updated as you complete tasks
• Note any blockers or unexpected discoveries
• Create new tasks if scope expands
• Keep user informed of major milestones

Phase 3-4: Quality Check and Ship It

When all Phase 2 tasks are complete and execution transitions to quality check, read references/shipping-workflow.md for the full shipping workflow: quality checks, code review, final validation, PR creation, and notification.

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

• Follow existing patterns
• Write tests for new code
• Run linting before pushing
• Review every change — inline for simple additive work, full review for everything else

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 - Every change gets reviewed; only the depth varies

Shipping Workflow

This file contains the shipping workflow (Phase 3-4). Load it only when all Phase 2 tasks are complete and execution transitions to quality check.

Phase 3: Quality Check

1. Run Core Quality Checks

Always run before submitting:

   # Run full test suite (use project's test command)
   # Examples: bin/rails test, npm test, pytest, go test, etc.

   # Run linting (per AGENTS.md)
   # Use linting-agent before pushing to origin

2. Code Review (REQUIRED)

Every change gets reviewed before shipping. The depth scales with the change's risk profile, but review itself is never skipped.

Tier 2: Full review (default) -- REQUIRED unless Tier 1 criteria are explicitly met. Invoke the ce:review skill with mode:autofix to run specialized reviewer agents, auto-apply safe fixes, and surface residual work as todos. When the plan file path is known, pass it as plan:<path>. This is the mandatory default -- proceed to Tier 1 only after confirming every criterion below.

Tier 1: Inline self-review -- A lighter alternative permitted only when all four criteria are true. Before choosing Tier 1, explicitly state which criteria apply and why. If any criterion is uncertain, use Tier 2.

• Purely additive (new files only, no existing behavior modified)
• Single concern (one skill, one component -- not cross-cutting)
• Pattern-following (implementation mirrors an existing example with no novel logic)
• Plan-faithful (no scope growth, no deferred questions resolved with surprising answers)

3. Final Validation

• All tasks marked completed
• Testing addressed -- tests pass and new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)
• Linting passes
• Code follows existing patterns
• Figma designs match (if applicable)
• No console errors or warnings
• If the plan has a Requirements Trace, verify each requirement is satisfied by the completed work
• If any Deferred to Implementation questions were noted, confirm they were resolved during execution

4. Prepare Operational Validation Plan (REQUIRED)

• Add a ## Post-Deploy Monitoring & Validation section to the PR description for every change.
• Include concrete:
• Log queries/search terms
• Metrics or dashboards to watch
• Expected healthy signals
• Failure signals and rollback/mitigation trigger
• Validation window and owner
• If there is truly no production/runtime impact, still include the section with: No additional operational monitoring required and a one-line reason.

Phase 4: Ship It

1. Prepare Evidence Context

Do not invoke ce-demo-reel directly in this step. Evidence capture belongs to the PR creation or PR description update flow, where the final PR diff and description context are available.

Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output). The git-commit-push-pr skill will ask whether to capture evidence only when evidence is possible.

2. Update Plan Status

If the input document has YAML frontmatter with a status field, update it to completed:

   status: active  ->  status: completed

3. Commit and Create Pull Request

Load the git-commit-push-pr skill to handle committing, pushing, and PR creation. The skill handles convention detection, branch safety, logical commit splitting, adaptive PR descriptions, and attribution badges.

When providing context for the PR description, include:

• The plan's summary and key decisions
• Testing notes (tests added/modified, manual testing performed)
• Evidence context from step 1, so git-commit-push-pr can decide whether to ask about capturing evidence
• Figma design link (if applicable)
• The Post-Deploy Monitoring & Validation section (see Phase 3 Step 4)

If the user prefers to commit without creating a PR, load the git-commit skill instead.

4. Notify User

• Summarize what was completed
• Link to PR (if one was created)
• Note any follow-up work needed
• Suggest next steps if applicable

Quality Checklist

Before creating PR, verify:

• [ ] All clarifying questions asked and answered
• [ ] All tasks marked completed
• [ ] Testing addressed -- tests pass AND new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)
• [ ] Linting passes (use linting-agent)
• [ ] Code follows existing patterns
• [ ] Figma designs match implementation (if applicable)
• [ ] Evidence decision handled by git-commit-push-pr when the change has observable behavior
• [ ] Commit messages follow conventional format
• [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
• [ ] Code review completed (inline self-review or full ce:review)
• [ ] PR description includes summary, testing notes, and evidence when captured
• [ ] PR description includes Compound Engineered badge with accurate model and harness

Code Review Tiers

Every change gets reviewed. The tier determines depth, not whether review happens.

Tier 2 (full review) -- REQUIRED default. Invoke ce:review mode:autofix with plan:<path> when available. Safe fixes are applied automatically; residual work surfaces as todos. Always use this tier unless all four Tier 1 criteria are explicitly confirmed.

Tier 1 (inline self-review) -- permitted only when all four are true (state each explicitly before choosing):

• Purely additive (new files only, no existing behavior modified)
• Single concern (one skill, one component -- not cross-cutting)
• Pattern-following (mirrors an existing example, no novel logic)
• Plan-faithful (no scope growth, no surprising deferred-question resolutions)