[Refactoring] Split StableWorkflowHandler - Reduce File Size & Improve Modularity

[gloomcheng]

Problem

stable-workflow-handler.ts has grown to 1294 lines, making it difficult to maintain and navigate. The file contains multiple responsibilities that should be separated.

Current State

File Size: 1294 lines
Responsibilities:

• Workflow phase handlers (spec, clarify, plan, review, tasks, implement, status)
• Memory operations (learn, context, correct)
• Checkpoint operations (save, resume, list, clear)
• Task decomposition & implementation validation
• Release & onboarding flows
• Utility methods

Proposed Solution

Refactor into multiple focused modules following single responsibility principle:

Option A: Domain-based Split

handlers/
  workflow/
    - workflow-phase-handler.ts (spec, clarify, plan, review, tasks, implement)
    - workflow-status-handler.ts (status, list)
  memory/
    - memory-handler.ts (learn, context, correct)
  checkpoint/
    - checkpoint-handler.ts (save, resume, list, clear)
  tooling/
    - release-handler.ts
    - onboard-handler.ts
    - constitution-handler.ts
  utils/
    - handler-utils.ts (common patterns)

Option B: Feature-based Split

handlers/
  - workflow-lifecycle-handler.ts (spec → implement flow)
  - workflow-support-handler.ts (memory, checkpoints, validation)
  - project-management-handler.ts (release, onboard, constitution)

Benefits

1. Maintainability: Smaller, focused files easier to understand
2. Testability: Each module can be tested independently
3. Reusability: Extracted utilities can be shared
4. Collaboration: Multiple developers can work in parallel
5. Performance: Potential for lazy-loading handlers

Success Criteria

• No file exceeds 500 lines
• All tests pass
• Build succeeds
• No functionality regression
• Code is more maintainable (subjective review)

Related

This addresses the architectural concern raised during Issue #8 implementation.

[gloomcheng]

✅ Refactoring complete!

Results:

• Reduced stable-workflow-handler.ts from 1294 lines → 312 lines (76% reduction)
• Created 13 domain-based handler files (150-300 lines each)
• Build and tests passing
• Maintained backward compatibility

Architecture:

All handlers follow Single Responsibility Principle and are easier to maintain.