work

name	work
description	Execute work efficiently while maintaining quality and finishing features. Use when the user says "implement this", "build it", "execute the plan", or provides a task description or plan document to execute.
requires	["commit"]

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.

Execution Workflow

Phase 0: Input Triage

Determine how to proceed based on what was provided.

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 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 (the field is absent or execution: code) → skip to Phase 1 and run the normal code lifecycle.

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	Consider brainstorm or plan first 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)

   • Read the work document completely. Plans may be markdown (.md) or HTML (.html) — both formats are read as text linearly.
   • When auto-detecting the latest plan (blank invocation), glob docs/plans/*.md AND docs/plans/*.html and pick the most recent regardless of extension.
   • 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. This skill does not mutate the plan — whether it shipped is derived from git, not recorded in the doc.

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

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

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

   Strategy	When to use
   Inline	1-2 small tasks, or tasks needing user interaction mid-flight. Default for bare-prompt work
   Serial subagents	3+ tasks with dependencies between them. Each subagent gets a fresh context window focused on one unit
   Parallel subagents	3+ tasks that pass the Parallel Safety Check (below). Dispatch independent units simultaneously, run dependent units after their prerequisites complete

   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 overlap is found: downgrade to serial subagents. Log the reason (e.g., "Units 2 and 4 share config/routes.rb — using serial dispatch").

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

   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 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.
   2. Cross-check for discovered file collisions: compare the actual files modified by all subagents in the batch. A collision only matters when 2+ subagents in the same batch modified the same file. 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.
   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 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
     - If the unit's work is already present and matches the plan's intent, 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)
     - Implement following existing conventions
     - Add, update, or remove tests to match implementation changes
     - Run tests after changes
     - Assess testing coverage: did this task change behavior? If yes, were tests written or updated?
     - Mark task as completed
     - Evaluate for incremental commit
   

   When a unit carries an Execution note, honor it. For test-first units, write the failing test before implementation. 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. When a plan specifies test scenarios or test files, start there, then check for additional test coverage. 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:

   Category	When it applies	How to derive if missing
   Happy path	Always for feature-bearing units	Read the unit's Goal and Approach for core input/output pairs
   Edge cases	When the unit has meaningful boundaries	Identify boundary values, empty/nil inputs, and concurrent access patterns
   Error/failure paths	When the unit has failure modes	Enumerate invalid inputs, permission/auth denials, and downstream failures
   Integration	When the unit crosses layers	Identify the cross-layer chain and write a scenario that exercises it without mocks

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

   Question	What to do
   What fires when this runs?	Trace two levels out from your change — callbacks, middleware, observers, event handlers.
   Do my tests exercise the real chain?	Write at least one integration test that uses real objects through the full callback/middleware chain.
   Can failure leave orphaned state?	Trace the failure path with real objects. If state is created before the risky call, test that failure cleans up or that retry is idempotent.
   What other interfaces expose this?	Grep for the method/behavior in related classes. If parity is needed, add it now.
   Do error strategies align across layers?	List the specific error classes at each layer. Verify your rescue list matches what the lower layer actually raises.

   When to skip: Leaf-node changes with no callbacks, no state persistence, no parallel interfaces.

2. Incremental Commits

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

   Commit when...	Don't commit when...
   Logical unit complete (model, service, component)	Small part of a larger unit
   Tests pass + meaningful progress	Tests failing
   About to switch contexts (backend → frontend)	Purely scaffolding with no behavior
   About to attempt risky/uncertain changes	Would need a "WIP" commit message

   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.

   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.

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)
   • 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.

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.

   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 simplify-code is available, invoke it at phase boundaries (especially before Phase 3 when the diff is >=30 lines). Otherwise, review the changed files yourself for reuse and consolidation opportunities.

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
   • When the plan defines U-IDs for Implementation Units, or the plan or origin document carries stable R-IDs, reference them in blockers, deferred-work notes, task summaries, and final verification. Use the IDs the plan supplies and do not invent ones it does not.

Phase 3-4: Quality Check and Finishing Work

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

Code review tiers: Tier 1 when the harness has built-in review. Tier 2 only when escalation criteria in shipping-workflow.md match — not because Tier 1 is missing.

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

When Tier 2 applies:

1. Review — Invoke the code-review skill. Use mode:agent in orchestrated workflows; pass plan:<path> when you have a plan and base:<ref> when the merge base is already known.
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.

Tier 1 harness-native review may still fix inline; Tier 2 always separates review from apply.

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 when Tier 1 is available or Tier 2 criteria match (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 — Use Tier 1 when available; escalate to Tier 2 only on criteria in shipping-workflow.md; document when both are skipped