Examples
Refactoring Workflow

Refactoring Workflow

Systematic code refactoring with safety checks.

Overview

This workflow performs safe refactoring:

  1. Analyzes existing code structure
  2. Identifies improvement opportunities
  3. Implements changes incrementally
  4. Validates with tests at each step

Complete Manifest

{
  "$schema": "https://hydra.opiusai.com/schemas/workflow/v1.0.json",
  "manifest_version": "1.0",
  "name": "Refactoring Workflow",
  "intent": "Safely refactor code to improve quality while maintaining functionality",
  "context": {
    "language": "typescript",
    "framework": "React"
  },
  "steps": [
    {
      "id": "analyze_current",
      "name": "Analyze current code",
      "action": "analyze_code",
      "parameters": {
        "focus": "code structure, dependencies, complexity, code smells"
      }
    },
    {
      "id": "ensure_test_coverage",
      "name": "Ensure test coverage",
      "action": "generate_tests",
      "depends_on": ["analyze_current"],
      "parameters": {
        "focus": "existing functionality, behavior preservation",
        "coverage_target": 80
      }
    },
    {
      "id": "run_baseline_tests",
      "name": "Run baseline tests",
      "action": "execute_command",
      "depends_on": ["ensure_test_coverage"],
      "parameters": {
        "command": "npm test"
      }
    },
    {
      "id": "plan_refactoring",
      "name": "Plan refactoring steps",
      "action": "design_architecture",
      "depends_on": ["run_baseline_tests"],
      "parameters": {
        "focus": "incremental changes, minimal risk, clear improvements"
      }
    },
    {
      "id": "implement_refactoring",
      "name": "Implement refactoring",
      "action": "edit_files",
      "depends_on": ["plan_refactoring"],
      "parameters": {
        "focus": "one change at a time, maintain functionality"
      }
    },
    {
      "id": "run_tests_after",
      "name": "Run tests after refactoring",
      "action": "execute_command",
      "depends_on": ["implement_refactoring"],
      "parameters": {
        "command": "npm test"
      }
    },
    {
      "id": "verify_improvements",
      "name": "Verify improvements",
      "action": "analyze_code",
      "depends_on": ["run_tests_after"],
      "parameters": {
        "focus": "reduced complexity, improved readability, better structure"
      }
    }
  ],
  "outputs": {
    "type": "code",
    "expected_files": ["src/**/*.ts", "src/**/*.tsx"]
  },
  "adapters": {
    "claude": {
      "mode": "sub_agent",
      "config": {
        "spawn_agents_per_step": true,
        "max_parallel_agents": 2
      }
    },
    "cursor": {
      "mode": "direct",
      "config": {
        "use_composer": true,
        "show_diff": true
      }
    }
  }
}

Refactoring Categories

Extract Method/Function

Break large functions into smaller, focused ones:

{
  "id": "extract_methods",
  "action": "edit_files",
  "parameters": {
    "focus": "extract reusable functions, single responsibility"
  }
}

Rename for Clarity

Improve naming throughout the codebase:

{
  "id": "improve_naming",
  "action": "edit_files",
  "parameters": {
    "focus": "descriptive names, consistent conventions, remove abbreviations"
  }
}

Remove Duplication

Consolidate repeated code:

{
  "id": "remove_duplication",
  "action": "edit_files",
  "parameters": {
    "focus": "DRY principle, shared utilities, common patterns"
  }
}

Simplify Conditionals

Make conditional logic clearer:

{
  "id": "simplify_conditionals",
  "action": "edit_files",
  "parameters": {
    "focus": "early returns, guard clauses, polymorphism over switches"
  }
}

Usage

With Claude Code

Run Refactoring workflow on src/services/UserService.ts
Focus: Extract methods and improve naming

With Cursor

@hydra Refactor @src/components/Dashboard.tsx
Goals: Reduce complexity, extract reusable hooks

Safety Checklist

The workflow ensures safety through:

  1. Test coverage first - Ensures behavior is captured
  2. Incremental changes - One refactoring at a time
  3. Test after each change - Catches regressions immediately
  4. No functionality changes - Pure refactoring only

Before/After Example

Before

// Large, complex function
function processOrder(order: Order) {
  // Validate
  if (!order.items || order.items.length === 0) {
    throw new Error('No items');
  }
  if (!order.customer) {
    throw new Error('No customer');
  }
 
  // Calculate totals
  let subtotal = 0;
  for (const item of order.items) {
    subtotal += item.price * item.quantity;
  }
  const tax = subtotal * 0.08;
  const total = subtotal + tax;
 
  // Apply discount
  let finalTotal = total;
  if (order.couponCode) {
    const discount = getCouponDiscount(order.couponCode);
    finalTotal = total * (1 - discount);
  }
 
  // Create invoice
  return {
    orderId: order.id,
    customer: order.customer,
    items: order.items,
    subtotal,
    tax,
    total: finalTotal,
    date: new Date()
  };
}

After

// Extracted, focused functions
function validateOrder(order: Order): void {
  if (!order.items?.length) {
    throw new Error('Order must have items');
  }
  if (!order.customer) {
    throw new Error('Order must have a customer');
  }
}
 
function calculateSubtotal(items: OrderItem[]): number {
  return items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );
}
 
function calculateTax(subtotal: number, rate = 0.08): number {
  return subtotal * rate;
}
 
function applyDiscount(total: number, couponCode?: string): number {
  if (!couponCode) return total;
  const discount = getCouponDiscount(couponCode);
  return total * (1 - discount);
}
 
function createInvoice(order: Order, totals: OrderTotals): Invoice {
  return {
    orderId: order.id,
    customer: order.customer,
    items: order.items,
    ...totals,
    date: new Date()
  };
}
 
function processOrder(order: Order): Invoice {
  validateOrder(order);
 
  const subtotal = calculateSubtotal(order.items);
  const tax = calculateTax(subtotal);
  const total = applyDiscount(subtotal + tax, order.couponCode);
 
  return createInvoice(order, { subtotal, tax, total });
}

Customization

Focus on Performance

{
  "parameters": {
    "focus": "reduce allocations, optimize loops, memoization"
  }
}

Focus on Readability

{
  "parameters": {
    "focus": "clear naming, consistent formatting, documentation"
  }
}

Focus on Testability

{
  "parameters": {
    "focus": "dependency injection, pure functions, mock-friendly"
  }
}

Tips

  1. Start with tests - Never refactor without test coverage
  2. Small commits - Each refactoring should be a separate commit
  3. No behavior changes - Refactoring should preserve functionality
  4. Measure improvement - Compare complexity before and after