Large Refactor: Coordinating a Major Refactoring Effort¶

# Example: Find all callback-style code
grep -r "function.*callback" src/ --include="*.js" -l

Modules to migrate:
├── src/api/       (15 files)
├── src/services/  (8 files)
├── src/utils/     (12 files)
└── src/db/        (6 files)

# config.yaml
completion:
  default_action: keep_branch  # Review before merging

branch:
  prefix: "refactor"
  include_id: true  # Keep IDs for tracking

pr:
  auto_rebase: true
  labels:
    - refactor
    - needs-review

resources:
  cost_warning_threshold: 10.00
  show_metrics_in_sidebar: true

claudio start callback-to-async

Convert all callback-based functions in src/api/ to async/await.
For each file:
1. Replace callback parameters with async function
2. Replace callback calls with await
3. Add proper error handling with try/catch
4. Update function signatures in index exports
Maintain backward compatibility by keeping the same function names.

Migrate src/services/ from callbacks to async/await. Follow these rules:
1. Convert callback(err, result) patterns to try/catch
2. Replace series operations with sequential await
3. Replace parallel operations with Promise.all
4. Ensure error messages are preserved

Update src/utils/ to use async/await. Pay attention to:
1. Helper functions that wrap callbacks
2. Utility functions with callback last parameter
3. Promisify any remaining callback APIs
4. Update JSDoc comments for async functions

Convert src/db/ database operations to async/await.
Important: Database connections must remain stable.
1. Convert query callbacks to await
2. Handle transaction rollback in catch blocks
3. Ensure connection pooling still works
4. Add TypeScript types if .ts files

# Create a migration guide for instances
cat > .claudio/migration-guide.md << 'EOF'
# Callback to Async/Await Migration Guide

## Pattern Transformations

### Before (Callback):
```javascript
function getData(id, callback) {
  db.query('SELECT * FROM items WHERE id = ?', [id], (err, rows) => {
    if (err) return callback(err);
    callback(null, rows[0]);
  });
}

async function getData(id) {
  try {
    const rows = await db.query('SELECT * FROM items WHERE id = ?', [id]);
    return rows[0];
  } catch (err) {
    throw new Error(`Failed to get data: ${err.message}`);
  }
}

Reference it in tasks:

## Step 6: Monitor for Conflicts

With a large refactor, conflicts are likely. Press `c` regularly to check:

## Step 7: Handle Shared Files

For files multiple instances need to modify:

### Option A: Designate One Owner

### Option B: Create a Dedicated Instance

### Option C: Manual Merge
Let instances work independently and merge manually:
```bash
cd .claudio/worktrees/abc123
git diff src/index.ts > /tmp/api-changes.patch

cd ../def456
git apply /tmp/api-changes.patch

Run all tests in tests/api/ and report any failures.
For failures, identify if they're due to the async/await migration.

Check that src/api/ has no remaining callback patterns:
1. No function parameters named 'callback' or 'cb'
2. No err-first callback calls
3. All async functions properly awaited

pr:
  draft: true

# Callback to Async Migration

## Modules

| Module | Instance | PR | Status |
|--------|----------|-----|--------|
| Utils | abc123 | #45 | Merged |
| Database | def456 | #46 | In Review |
| Services | ghi789 | #47 | CI Running |
| API | jkl012 | - | In Progress |

## Blockers
- Database module has flaky test, investigating

## Notes
- Keep backward compat for external API consumers

Good: "Convert src/api/users.ts and src/api/posts.ts to async"
Too big: "Convert all of src/ to async"

Run tests for src/services/ and fix any failures caused by
the async/await migration.

Convert to async/await while maintaining exact same behavior.
Add any missing error handling but don't change business logic.

# Delete the problematic branch
git branch -D refactor/abc123-api

# Remove the instance
claudio remove abc123 --force

# Start fresh with revised instructions
claudio add "Convert src/api/ with special handling for..."

Convert these similar controller files to async:
- src/controllers/user.js
- src/controllers/post.js
- src/controllers/comment.js
All follow the same CRUD pattern, transform consistently.