workflow-rules

Development Workflow Rules: Catch Issues Early

🚨 BEFORE ANY CODE CHANGES

1. Run Quality Checks

# ALWAYS run these before starting work
npm run lint:check      # Check current issues
npm run typecheck      # Verify TypeScript
npm run build          # Ensure builds
npm test              # Run tests

# Check our performance metrics
time node dist/cli.js --version  # Should be <50ms
du -sh dist/                     # Should be <5MB

2. Check File Sizes (Current Issues Found)

# Files over 250 lines need splitting:
# ⚠️  src/ui/utils/markdownUtilities.ts has 414 lines
# ⚠️  src/ui/hooks/useClaudeStream.ts has 390 lines  
# ⚠️  src/ui/hooks/useClaude4Stream.ts has 467 lines
# ⚠️  src/tools/screenshot.ts has 417 lines
# ⚠️  src/tools/code-analyzer.ts has 291 lines

find src -name "*.ts" -exec wc -l {} + | awk '$1 > 250 {print "⚠️  " $2 " has " $1 " lines"}'

3. Check Console Pollution (Current Issue: 278 statements!)

# We have 278 console statements outside CLI/tests - need cleanup!
grep -r "console\." src/ | grep -v ".test." | grep -v "cli.ts" | wc -l

# Find specific violations:
grep -rn "console\." src/ | grep -v ".test." | grep -v "cli.ts" | head -20

🔧 DEVELOPMENT PATTERNS

File Creation Rules

// ✅ CORRECT - New file template
/**
 * [Module Name] - [Brief Description]
 * 
 * [Detailed description of purpose and functionality]
 */

import { /* required imports */ } from './path.js';  // Always .js extension
import type { /* type imports */ } from './types.js';

// Implementation (max 250 lines)

export { /* exports */ };

Function Creation Rules

// ✅ CORRECT - Function template (max 30 lines)
/**
 * [Function description]
 * 
 * @param parameter - Description
 * @returns Description
 * @throws {UserError} When [condition]
 */
async function descriptiveFunctionName(
  parameter: SpecificType
): Promise<SpecificReturnType> {
  // Validation
  if (!isValid(parameter)) {
    throw createUserError('Clear error message', {
      category: ErrorCategory.VALIDATION,
      resolution: 'How to fix this'
    });
  }
  
  // Implementation (max 25 lines after validation)
  try {
    const result = await operation(parameter);
    return result;
  } catch (error) {
    throw createUserError('Operation failed', {
      category: ErrorCategory.SYSTEM,
      details: { error }
    });
  }
}