Skip to content

/vt-d-wf-work

Execute work plans efficiently while maintaining quality and finishing features

Plugin: vt-product-dev
Usage: /vt-d-wf-work [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

#$ARGUMENTS

Ralph Wiggum Verification Mode

Autonomous Mode: If --autonomous flag is provided in arguments, this command runs with convergence-based verification:

# Check for --autonomous flag
AUTONOMOUS=false
if [[ "$ARGUMENTS" == *"--autonomous"* ]]; then
  AUTONOMOUS=true
  echo "🔄 Autonomous mode enabled - verification loop active"
fi

How it works: - After completing work tasks (Phase 2) and quality checks (Phase 3) - System automatically runs verification commands - If verification fails: Loop back to fix issues - If verification passes: Continue to Phase 4 (Ship It) - Max 5 iterations to prevent infinite loops

Verification commands (auto-detected from project): - Ruby/Rails: bin/rails test, rubocop - JavaScript: npm test, npm run lint - Python: pytest, ruff check - Go: go test ./... - See ralph-wiggum-loop skill for full list

Execution Workflow

Phase 1: Quick Start

  1. Read Plan and Clarify

  2. Read the work document completely

  3. Review any references or links provided in the plan
  4. If anything is unclear or ambiguous, ask clarifying questions now
  5. Get user approval to proceed

  6. Do not skip this - better to ask questions now than build the wrong thing

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

  1. Create Todo List
  2. Use TodoWrite to break plan into actionable tasks
  3. Include dependencies between tasks
  4. Prioritize based on what needs to be done first
  5. Include testing and quality check tasks
  6. 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.

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

  1. Follow Existing Patterns

  2. The plan should reference similar code - read those files first

  3. Match naming conventions exactly
  4. Reuse existing components where possible
  5. Follow project coding standards (see CLAUDE.md)

  6. When in doubt, grep for similar implementations

  7. Test Continuously

  8. Run relevant tests after each significant change

  9. Don't wait until the end to test
  10. Fix failures immediately

  11. Add new tests for new functionality

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

  • Track Progress

  • Keep TodoWrite 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: 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 CLAUDE.md)
# Use linting-agent before pushing to origin
  1. Run Browser Tests (Web Projects — Mandatory)

For projects with a web frontend, browser testing via Playwright is required before PR creation.

Auto-detection — check for ANY of these web project indicators: - playwright.config.{ts,js} (explicit Playwright setup) - package.json containing react, vue, svelte, angular, next, nuxt, remix - app/views/ directory (Rails/Django templates) - vite.config.*, webpack.config.* (frontend build tools)

If web project detected: 

# Dispatch test-runner agent in full-suite mode (includes e2e automatically)
# Or run Playwright directly:
# npx playwright test
# python scripts/with_server.py --server "npm run dev" --port 5173 -- npx playwright test

ALL browser test items must pass. No items may be skipped. If browser tests fail, fix issues before proceeding to Phase 4.

If NOT a web project (pure backend API, CLI tool, library): Skip browser tests.

  1. Consider Reviewer Agents (Optional)

Use for complex, risky, or large changes:

  • code-simplicity-reviewer: Check for unnecessary complexity
  • angular-reviewer: Verify Angular conventions (if angular.json exists)
  • nestjs-reviewer: Verify NestJS conventions (if nest-cli.json exists)
  • performance-oracle: Check for performance issues
  • security-sentinel: Scan for security vulnerabilities

Run reviewers in parallel with Task tool:

Task(code-simplicity-reviewer): "Review changes for simplicity"
Task(angular-reviewer): "Check Angular conventions"  # if angular.json exists
Task(nestjs-reviewer): "Check NestJS conventions"    # if nest-cli.json exists

Present findings to user and address critical issues.

  1. Final Validation
  2. All TodoWrite tasks marked completed
  3. All tests pass
  4. Linting passes
  5. Code follows existing patterns
  6. Figma designs match (if applicable)
  7. No console errors or warnings

Autonomous Verification Loop (if --autonomous flag enabled):

if [ "$AUTONOMOUS" = true ]; then
  LOOP_COUNT=0
  MAX_ITERATIONS=5

  while [ $LOOP_COUNT -lt $MAX_ITERATIONS ]; do
    echo "🔍 Running verification (iteration $((LOOP_COUNT+1))/$MAX_ITERATIONS)..."

    # Load verification commands from ralph-wiggum-loop skill
    Read: assets/verification-commands.md

    # Detect and run appropriate verification commands
    # Examples:
    # - bin/rails test (Rails)
    # - npm test (Node)
    # - pytest (Python)

    VERIFICATION_PASSED=false

    # Run verification command
    if VERIFICATION_OUTPUT=$(run_verification_command 2>&1); then
      if [[ $? -eq 0 ]] && [[ ! "$VERIFICATION_OUTPUT" =~ (failures|errors|failed) ]]; then
        VERIFICATION_PASSED=true
      fi
    fi

    if [ "$VERIFICATION_PASSED" = true ]; then
      echo "✅ Verification passed after $((LOOP_COUNT+1)) iteration(s)"

      # Log metrics
      Read: metrics/verification-loops.json
      TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
      ENTRY=$(cat <<EOFENTRY
{
  "timestamp": "$TIMESTAMP",
  "command": "$(get_verification_command)",
  "loop_count": $((LOOP_COUNT+1)),
  "final_status": "passed",
  "false_claims_prevented": $LOOP_COUNT
}
EOFENTRY
)
      jq '.loops += ['"$ENTRY"']' metrics/verification-loops.json > metrics/verification-loops.json.tmp
      mv metrics/verification-loops.json.tmp metrics/verification-loops.json

      break
    else
      echo "❌ Verification failed: $VERIFICATION_OUTPUT"
      echo "🔄 Looping to fix issues... (iteration $((LOOP_COUNT+1)))"

      # Present failure details to agent for fixing
      echo "
      Verification failures detected:
      $VERIFICATION_OUTPUT

      Please fix the issues and tests will run again automatically.
      "

      LOOP_COUNT=$((LOOP_COUNT+1))

      # Go back to Phase 2: Execute to fix issues
      # (In actual implementation, this would re-run task execution with context about failures)
    fi
  done

  if [ $LOOP_COUNT -eq $MAX_ITERATIONS ]; then
    echo "⚠️  Max iterations ($MAX_ITERATIONS) reached without passing verification."
    echo "
    Verification Loop Summary:
    - Iterations: $MAX_ITERATIONS
    - Final status: FAILED
    - Last failure: $VERIFICATION_OUTPUT

    Manual intervention needed. Options:
    1. Review failures and continue fixing manually
    2. Disable --autonomous and complete without verification loop
    3. Adjust verification criteria
    "

    # Ask user how to proceed
    echo "How would you like to proceed?"
    # Wait for user input before continuing
  fi
fi

Phase 4: Ship It

  1. Create Commit
git add .
git status  # Review what's being committed
git diff --staged  # Check the changes

# Commit with conventional format
git commit -m "$(cat <<'EOF'
feat(scope): description of what and why

Brief explanation if needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
  1. Capture and Upload Screenshots for UI Changes (REQUIRED for any UI work)

For any design changes, new views, or UI modifications, you MUST capture and upload screenshots:

Step 1: Start dev server (if not running) 

bin/dev  # Run in background

Step 2: Capture screenshots with agent-browser CLI 

agent-browser open http://localhost:3000/[route]
agent-browser snapshot -i
agent-browser screenshot output.png
See the agent-browser skill for detailed usage.

Step 3: Upload using imgup skill 

skill: imgup
# Then upload each screenshot:
imgup -h pixhost screenshot.png  # pixhost works without API key
# Alternative hosts: catbox, imagebin, beeimg

What to capture: - New screens: Screenshot of the new UI - Modified screens: Before AND after screenshots - Design implementation: Screenshot showing Figma design match

IMPORTANT: Always include uploaded image URLs in PR description. This provides visual context for reviewers and documents the change.

  1. Create Pull Request
git push -u origin feature-branch-name

gh pr create --title "Feature: [Description]" --body "$(cat <<'EOF'
## Summary
- What was built
- Why it was needed
- Key decisions made

## Testing
- Tests added/modified
- Manual testing performed

## Before / After Screenshots
| Before | After |
|--------|-------|
| ![before](URL) | ![after](URL) |

## Figma Design
[Link if applicable]

---

[![Compound Engineered](https://img.shields.io/badge/Compound-Engineered-6366f1)](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
  1. Notify User
  2. Summarize what was completed
  3. Link to PR
  4. Note any follow-up work needed
  5. Suggest next steps if applicable

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
  • Use reviewer agents for complex/risky changes only

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

Quality Checklist

Before creating PR, verify:

  • [ ] All clarifying questions asked and answered
  • [ ] All TodoWrite tasks marked completed
  • [ ] Tests pass (run project's test command)
  • [ ] Browser/e2e tests pass (web projects — Playwright, no skipped items)
  • [ ] No browser console errors during e2e tests (web projects)
  • [ ] Linting passes (use linting-agent)
  • [ ] Code follows existing patterns
  • [ ] Figma designs match implementation (if applicable)
  • [ ] Before/after screenshots captured and uploaded (for UI changes)
  • [ ] Commit messages follow conventional format
  • [ ] PR description includes summary, testing notes, and screenshots
  • [ ] PR description includes Compound Engineered badge

When to Use Reviewer Agents

Don't use by default. Use reviewer agents only when:

  • Large refactor affecting many files (10+)
  • Security-sensitive changes (authentication, permissions, data access)
  • Performance-critical code paths
  • Complex algorithms or business logic
  • User explicitly requests thorough review

For most features: tests + linting + following patterns is sufficient.

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 TodoWrite - Track progress or lose track of what's done
  • 80% done syndrome - Finish the feature, don't move on early
  • Over-reviewing simple changes - Save reviewer agents for complex work