/work

name: workflows:work
description: Execute work plans efficiently while maintaining quality and finishing features
argument-hint: "[plan file, specification, or todo file path]"

Work Plan Execution Command

Execute a work plan efficiently while maintaining quality and finishing features.

Introduction

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

1. **Read Plan and Clarify**

• Read the work document completely
• Review any references or links provided in the plan
• 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):

• Ask: "Continue working on `[current_branch]`, or create a new branch?"
• If continuing, 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**

• Use TodoWrite to break plan into actionable tasks
• Include dependencies between tasks
• Prioritize based on what needs to be done first
• Include testing and quality check tasks
• Keep tasks specific and completable

Phase 2: Execute

1. **Task Execution Loop**

For each task in priority order:

   while (tasks remain):
     - Mark task as in_progress in TodoWrite
     - Read any referenced files from the plan
     - Look for similar patterns in codebase
     - Implement following existing conventions
     - Write tests for new functionality
     - Run tests after changes
     - Mark task as completed in TodoWrite
     - Mark off the corresponding checkbox in the plan file ([ ] → [x])
     - Evaluate for incremental commit (see below)

**IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.

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."

**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 CLAUDE.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 functionality

5. **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 TodoWrite updated as you complete tasks
• Note any blockers or unexpected discoveries
• Create new ta