Claude-Code-Workflow/.claude/workflows/complexity-rules.md

Workflow Complexity Rules

Overview

This document defines unified complexity classification rules across all workflow components, ensuring consistent thresholds and scaling behavior throughout the system.

Complexity Classification

Unified Thresholds

Based on task count for consistent classification across all system components

Complexity	Task Count	Max Hierarchy Depth	File Structure Level
Simple	<5 tasks	1 level (impl-N)	Level 0 - Minimal
Medium	5-15 tasks	2 levels (impl-N.M)	Level 1 - Enhanced
Complex	>15 tasks	3 levels (impl-N.M.P)	Level 2 - Complete

Simple Workflows

Characteristics

• Direct implementation tasks with clear, limited scope
• Single-file or small-module changes
• Clear requirements without complex dependencies
• Atomic functionality that can be implemented in one session

System Behavior

• File Structure: Minimal directory structure (Level 0)
• Task Hierarchy: Single level only (impl-1, impl-2, etc.)
• Documentation: Basic IMPL_PLAN.md, no TODO_LIST.md
• Agent Coordination: Direct execution without complex orchestration

Examples

• Bug fixes in existing functionality
• Small feature additions to existing modules
• Documentation updates
• Configuration changes
• Simple utility functions

Medium Workflows

Characteristics

• Feature implementation requiring task breakdown
• Multiple file modifications across related modules
• Some integration requirements with existing systems
• Clear feature boundaries with moderate complexity

System Behavior

• File Structure: Enhanced directory structure (Level 1)
• Task Hierarchy: Two levels (impl-N.M format)
• Documentation: IMPL_PLAN.md + auto-triggered TODO_LIST.md
• Agent Coordination: Context-driven coordination with shared state

Auto-trigger Conditions

TODO_LIST.md and enhanced structure triggered when:

• Task count > 5 OR
• Modules affected > 3 OR
• Estimated effort > 4h OR
• Complex inter-module dependencies exist

Examples

• New feature implementation within existing architecture
• API endpoint creation with frontend integration
• Database schema changes with application updates
• Authentication/authorization enhancements
• Performance optimization across multiple components

Complex Workflows

Characteristics

• System-wide changes requiring detailed decomposition
• Architectural modifications affecting multiple systems
• Cross-team coordination or external dependencies
• High-risk changes requiring extensive testing and review

System Behavior

• File Structure: Complete directory structure (Level 2)
• Task Hierarchy: Three levels maximum (impl-N.M.P format)
• Documentation: Comprehensive planning + progress tracking + summaries
• Agent Coordination: Multi-agent orchestration with deep context analysis

Examples

• New major feature development
• System architecture refactoring
• Third-party service integrations
• Security implementations (OAuth, encryption)
• Database migrations with application changes
• Multi-service deployments

Complexity Assessment Rules

Automatic Classification

System evaluates tasks during creation and applies appropriate complexity level

function classify_complexity(tasks, scope, dependencies):
    task_count = count(tasks)
    
    if task_count < 5 and scope.is_simple() and not dependencies.complex():
        return SIMPLE
    elif task_count <= 15 and scope.is_moderate():
        return MEDIUM
    else:
        return COMPLEX

Upgrade Triggers

Complexity can be upgraded during workflow execution

• Simple → Medium: When subtasks are created or scope expands
• Medium → Complex: When task count exceeds 15 or deep hierarchy needed
• No Downgrades: Complexity level never decreases to prevent data loss

Override Rules

Manual complexity override allowed for edge cases

• User can specify higher complexity at workflow creation
• System warnings issued for mismatched complexity/scope
• Cannot specify lower complexity than system assessment

Component Integration

File Structure Mapping

Complexity directly determines file structure level

Complexity	Directory Structure	Required Files
Simple	Minimal (.task/, .summaries/)	workflow-session.json, IMPL_PLAN.md
Medium	Enhanced (+ TODO_LIST.md)	+ Auto-generated progress tracking
Complex	Complete (+ comprehensive docs)	+ Full documentation suite

Agent Orchestration Mapping

Complexity determines agent coordination patterns

Complexity	Gemini Analysis	Agent Coordination	Review Process
Simple	Focused file-level	Direct context-aware execution	Quick validation
Medium	Comprehensive multi-file	Context-driven coordination	Thorough single-pass
Complex	Deep system-wide	Multi-agent orchestration	Multiple review iterations

Task Hierarchy Mapping

Complexity enforces hierarchy depth limits

• Simple: Single level (impl-N)
• Medium: Two levels (impl-N.M)
• Complex: Three levels maximum (impl-N.M.P)

Decision Tree

Workflow Creation

Start: Analyze user requirements
│
├─ Task count < 5 AND single module AND clear scope?
│  └─ YES → SIMPLE workflow
│
├─ Task count ≤ 15 AND moderate scope AND some integration?
│  └─ YES → MEDIUM workflow  
│
└─ Task count > 15 OR system-wide OR high-risk?
   └─ YES → COMPLEX workflow

Complexity Upgrade Assessment

During Execution: Monitor task growth
│
├─ Simple workflow + subtasks created?
│  └─ Upgrade to MEDIUM
│
├─ Medium workflow + task count > 15?
│  └─ Upgrade to COMPLEX
│
└─ Any workflow + architectural changes?
   └─ Consider upgrade to COMPLEX

Quality Assurance

Validation Rules

• Complexity level must match actual task count
• File structure must align with complexity level
• Agent coordination patterns must match complexity
• Documentation completeness must match complexity requirements

Performance Monitoring

• Track completion times by complexity level
• Monitor accuracy of initial complexity assessments
• Adjust thresholds based on historical data
• Measure overhead costs of each complexity level

Consistency Checks

• All system components use same complexity thresholds
• Cross-references between complexity-dependent files are valid
• Upgrade paths preserve existing work and structure
• No orphaned files after complexity changes

---

System ensures: Unified complexity classification across all workflow components with consistent scaling behavior and automatic optimization for task scope and system performance