[V2] Enhance task generation with dependency analysis and effort estimation

[frankbria]

🎯 Overview

Enhance the existing task generation system to include advanced dependency analysis, effort estimation, and critical path identification. This addresses Phase 2 requirements for intelligent task management and scheduling.

📊 Current State Analysis

Existing Implementation: Basic `codeframe tasks generate` with LLM support
Current Features:

• LLM-based task generation from PRD content
• Simple dependency field structure
• Basic priority assignment (order-based)
• Fallback to simple extraction when LLM fails

Identified Gaps:

• Limited dependency graph analysis
• No effort estimation or complexity analysis
• Missing critical path identification and scheduling
• No task template system for common patterns
• Automatic task prioritization not implemented

📋 Implementation Requirements

Phase 1: Advanced Dependency Analysis

• Enhance existing `_generate_tasks_with_llm()` with dependency inference
• Add circular dependency detection and resolution suggestions
• Implement dependency graph visualization capabilities
• Add conflict detection and automatic resolution recommendations
• Support for cross-task dependency validation

Phase 2: Effort Estimation & Complexity Analysis

• Add AI-based effort estimation for each generated task
• Implement complexity analysis and difficulty scoring
• Add time estimation based on historical data and patterns
• Support for resource requirement identification
• Add uncertainty handling for ambiguous task specifications

Phase 3: Critical Path & Scheduling

• Implement critical path identification algorithm
• Add automatic task scheduling based on dependencies
• Support for parallel execution opportunity identification
• Add resource allocation optimization for team scenarios
• Implement timeline prediction and milestone tracking

Phase 4: Task Template System

• Create template framework for common implementation patterns
• Add templates for: setup, implementation, testing, deployment
• Support for custom template creation and sharing
• Add template application based on task type and project characteristics
• Implement template inheritance and composition capabilities

Phase 5: Enhanced Task Management

• Add `codeframe tasks analyze --conflicts` command
• Implement `codeframe tasks visualize-deps` for graph display
• Add `codeframe tasks suggest-order` for optimization recommendations
• Enhance `codeframe tasks list` with dependency-aware filtering
• Add batch task management and dependency updates

🔗 Dependencies

• Builds on existing `codeframe/core/tasks.py` and LLM integration
• Must integrate with existing state machine and batch execution
• Should work with current PRD and workspace systems
• Benefits from enhanced dependency graph analysis

✅ Acceptance Criteria

• Task generation includes dependency analysis with graph visualization
• Effort estimation is accurate within ±25% of actual implementation time
• Critical path identification enables optimal scheduling
• Task templates reduce repetitive task setup by 50%+
• Dependency conflicts are detected and resolved automatically
• CLI commands provide rich task management capabilities
• Comprehensive test coverage for all task generation scenarios
• Performance benchmarks show improved prediction accuracy

🎯 Success Metrics

• Reduced manual task planning and dependency management overhead
• Improved timeline prediction accuracy for development projects
• Higher task completion rates through better estimation and scheduling
• Reduced project delays from hidden dependencies
• Improved developer productivity through task templates

📚 References

• Enhanced MVP specification: `docs/GOLDEN_PATH.md`
• Current task system: `codeframe/core/tasks.py`
• Gap analysis: `docs/GAP_ANALYSIS_SUMMARY.md`
• Implementation roadmap: `docs/IMPLEMENTATION_ROADMAP.md`
• CLI wireframe: `docs/CLI_WIREFRAME.md`

This is high priority as it enables more predictable and efficient project execution while building on the solid foundation that already exists.

[traycerai]

Plan

Observations

The codebase has a solid foundation for task generation with LLM-powered decomposition (file:codeframe/planning/task_decomposer.py), hierarchical issue/task modeling, and DAG-based dependency resolution (file:codeframe/agents/dependency_resolver.py). The current system generates tasks from PRD content via file:codeframe/agents/lead_agent.py and stores them with basic dependency information. However, it lacks advanced features like effort estimation, critical path analysis, and intelligent scheduling that would enable predictable project execution.

Approach

The implementation will enhance the existing task generation pipeline by integrating AI-powered analysis at each stage: (1) extend TaskDecomposer to include effort estimation during LLM-based decomposition, (2) enhance DependencyResolver with critical path algorithms and scheduling capabilities, (3) create a template system for common task patterns, and (4) add new CLI commands for dependency visualization and conflict analysis. This approach builds incrementally on proven components while maintaining backward compatibility with existing task workflows.

Implementation Plan

Phase 1: Enhanced Task Decomposition with Effort Estimation

1.1 Extend TaskDecomposer for Effort Estimation

Modify file:codeframe/planning/task_decomposer.py:

• Enhance build_decomposition_prompt() method to request effort estimation
  • Add section requesting complexity (1-5 scale) for each task
  • Request time estimation (hours) based on task scope
  • Ask for resource requirements (skills, tools, dependencies)
  • Request uncertainty assessment (low/medium/high) for ambiguous tasks
• Enhance parse_claude_response() method to extract effort data
  • Parse complexity scores from Claude response
  • Extract estimated hours for each task
  • Parse resource requirements as JSON
  • Extract uncertainty levels
• Store estimates in new Task fields (see 1.2)
• Add fallback to default estimates if parsing fails
• Log estimation confidence for tracking accuracy over time

1.2 Update Task Model

Modify file:codeframe/core/models.py:

• Add new fields to Task dataclass:
  • estimated_hours: Optional[float] - Time estimate in hours
  • complexity_score: Optional[int] - Complexity rating (1-5)
  • uncertainty_level: Optional[str] - "low", "medium", "high"
  • resource_requirements: Optional[str] - JSON string of required skills/tools
• Update to_dict() method to include new fields

1.3 Database Schema Migration

Update database schema in file:codeframe/persistence/database.py:

• Add columns to tasks table: estimated_hours, complexity_score, uncertainty_level, resource_requirements
• Create migration script to add columns with default values
• Update file:codeframe/persistence/repositories/task_repository.py to handle new fields in _row_to_task() and create_task_with_issue()

Phase 2: Advanced Dependency Analysis

2.1 Enhance DependencyResolver with Critical Path Analysis

Extend file:codeframe/agents/dependency_resolver.py:

• Add calculate_critical_path(task_durations: Dict[int, float]) method using longest path algorithm
  • Accept task duration estimates (hours) as input
  • Compute earliest start/finish times for each task using forward pass
  • Compute latest start/finish times using backward pass
  • Identify tasks with zero slack (critical path)
  • Return CriticalPathResult with critical task IDs, total duration, and task timings
• Add identify_parallel_opportunities() method
  • Find tasks that can execute concurrently (no dependency conflicts)
  • Group tasks by dependency level for parallel execution waves
  • Return dict mapping execution wave (0, 1, 2...) to task IDs
  • Include wave duration estimates
• Add calculate_task_slack(task_durations: Dict[int, float]) method
  • Compute float/slack time for each task using critical path data
  • Return dict mapping task ID to slack hours
  • Tasks with zero slack are on critical path

2.2 Add Conflict Detection and Resolution

Extend file:codeframe/agents/dependency_resolver.py:

• Add detect_dependency_conflicts(task_durations: Dict[int, float]) method
  • Identify bottleneck tasks (many dependents, high impact on critical path)
  • Detect long dependency chains that risk delays (chain length > 5 tasks)
  • Find tasks with high complexity and many dependents (risk multipliers)
  • Return list of DependencyConflict objects with severity (critical/high/medium) and recommendations
  • Include impact analysis (how many tasks blocked, estimated delay)
• Add suggest_dependency_resolution(conflicts: List[DependencyConflict]) method
  • Propose task splitting for bottlenecks to increase parallelization
  • Suggest dependency reordering to reduce critical path length
  • Recommend prioritizing high-impact tasks
  • Return list of ResolutionSuggestion objects with expected improvements

2.3 Create Dependency Visualization Support

Create new file file:codeframe/planning/dependency_visualizer.py:

• Implement generate_dependency_graph(tasks, critical_path_ids, task_status) function
  • Accept list of tasks, critical path task IDs, and task status map
  • Generate Mermaid flowchart syntax for task DAG
  • Highlight critical path tasks in red/bold
  • Color-code tasks by status: pending (gray), in_progress (blue), completed (green), blocked (orange)
  • Include task complexity scores as node labels
  • Return Mermaid markdown string suitable for display/export
• Implement generate_gantt_chart(tasks, task_durations, critical_path_ids) function
  • Create Gantt chart representation with estimated durations
  • Show task dependencies and critical path highlighting
  • Include milestone markers for critical path completion
  • Return Mermaid Gantt syntax
• Implement export_graph_formats(graph_data) function
  • Support export to Mermaid, DOT (Graphviz), and JSON formats
  • Enable integration with external visualization tools

Phase 3: Intelligent Task Scheduling

3.1 Create Task Scheduler Component

Create new file file:codeframe/planning/task_scheduler.py:

• Implement TaskScheduler class with methods:
  • schedule_tasks(tasks, task_durations, agents_available) - Assign start times based on dependencies and resources
    • Use critical path method (CPM) for scheduling
    • Consider agent availability and skill matching from resource requirements
    • Return ScheduleResult with task assignments, start/end times, and timeline
  • optimize_schedule(schedule, constraints) - Use heuristics to minimize project duration
    • Identify parallelization opportunities
    • Suggest task reordering within slack windows
    • Return optimized schedule with estimated duration reduction
  • predict_completion_date(current_progress, schedule) - Estimate project end date based on current progress
    • Account for completed tasks and in-progress work
    • Apply historical velocity factors
    • Return predicted completion date with confidence interval
  • identify_bottlenecks(schedule, task_durations) - Find tasks/agents causing delays
    • Identify tasks on critical path with high duration
    • Find agents with overallocation
    • Return list of bottleneck items with impact analysis

3.2 Integrate Scheduler with LeadAgent

Modify file:codeframe/agents/lead_agent.py:

• Add schedule_project_tasks() method that calls TaskScheduler
• Update start_multi_agent_execution() to use scheduled task assignments
• Add scheduling metadata to task assignment broadcasts
• Store schedule in database for progress tracking

Phase 4: Task Template System

4.1 Create Template Framework

Create new file file:codeframe/planning/task_templates.py:

• Define TaskTemplate dataclass with fields:
  • name: str - Template identifier (e.g., "rest_api_endpoint")
  • category: str - "setup", "implementation", "testing", "deployment", "refactor"
  • keywords: List[str] - Keywords for automatic detection (e.g., ["API", "endpoint", "REST"])
  • task_pattern: List[Dict] - List of task definitions with placeholders
    • Each task has: title, description, complexity_score, estimated_hours
  • dependencies: List[Tuple[int, int]] - Dependency relationships between task indices
  • estimated_hours: Dict[int, float] - Time estimates per task
  • version: str - Template version for migration tracking
• Implement TemplateLibrary class:
  • load_templates() - Load built-in and custom templates from file:codeframe/planning/templates/
  • get_template(name) - Retrieve template by name
  • find_applicable_templates(issue_description) - Find templates matching issue keywords
  • apply_template(template, context) - Generate tasks from template with variable substitution
  • save_custom_template(template) - Persist user-defined templates to database
  • get_template_stats() - Return usage statistics for each template

4.2 Create Built-in Templates

Create template definitions in file:codeframe/planning/templates/:

• setup_template.json - Project initialization tasks
  • Initialize git repository, setup environment, install dependencies, configure tools
  • 4-5 sequential tasks, ~8-12 hours total
• rest_api_endpoint_template.json - REST API implementation pattern
  • Design schema, implement endpoint, add validation, write tests, document API
  • 5-6 tasks with some parallelization, ~12-16 hours total
• crud_template.json - CRUD operations for a model
  • Create model, implement create/read/update/delete operations, add tests
  • 4-5 sequential tasks, ~10-14 hours total
• testing_template.json - Test suite setup and implementation
  • Setup test framework, write unit tests, add integration tests, configure CI
  • 4-5 tasks with parallelization opportunities, ~8-12 hours total
• deployment_template.json - CI/CD and deployment tasks
  • Setup CI pipeline, configure deployment, add monitoring, document process
  • 4-5 sequential tasks, ~10-15 hours total
• refactor_template.json - Code refactoring pattern
  • Analyze code, plan refactoring, implement changes, test thoroughly, document
  • 5-6 tasks, ~12-18 hours total
• Each template includes task titles, descriptions, complexity scores, dependencies, and estimates

4.3 Integrate Templates with Task Generation

Modify file:codeframe/planning/task_decomposer.py:

• Add detect_template_applicability(issue: Issue) method
  • Analyze issue title and description for template keywords
  • Score each template based on keyword matches (0.0-1.0)
  • Return list of applicable templates sorted by confidence
  • Threshold: only return templates with confidence > 0.6
• Add apply_template_if_applicable(issue: Issue, templates: List[TaskTemplate]) method
  • Check if highest-confidence template exceeds confidence threshold (0.75)
  • Apply template with variable substitution (issue title, description, priority)
  • Preserve issue number and parent relationships
  • Return generated tasks or None if no suitable template
• Update decompose_issue() to try template matching first
  • Call detect_template_applicability() and apply_template_if_applicable()
  • Fall back to LLM decomposition if no suitable template (confidence < 0.75)
  • Log template usage for analytics
• Add _substitute_template_variables() helper method
  • Replace placeholders like {issue_title}, {issue_description} in task templates

Phase 5: Enhanced CLI Commands

5.1 Add Dependency Analysis Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add analyze command:

  @tasks_app.command("analyze")
  def analyze_dependencies(
      project_id: int,
      show_conflicts: bool = typer.Option(False, "--conflicts"),
      show_critical_path: bool = typer.Option(False, "--critical-path"),
      show_bottlenecks: bool = typer.Option(False, "--bottlenecks"),
      show_all: bool = typer.Option(False, "--all")
  )

  • Call new API endpoint GET /api/projects/{id}/tasks/analysis
  • Display dependency conflicts with severity and recommendations
  • Display critical path tasks with total duration
  • Display bottleneck tasks with impact analysis
  • Use rich tables with color coding: critical (red), high (orange), medium (yellow)
  • Show summary statistics (total tasks, critical path length, conflicts count)

5.2 Add Visualization Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add visualize-deps command:

  @tasks_app.command("visualize-deps")
  def visualize_dependencies(
      project_id: int,
      format: str = typer.Option("mermaid", "--format", "-f"),
      save_to: Optional[str] = typer.Option(None, "--output", "-o"),
      show_critical_path: bool = typer.Option(True, "--critical-path/--no-critical-path")
  )

  • Call API endpoint GET /api/projects/{id}/tasks/dependency-graph
  • Display Mermaid diagram in terminal or save to file
  • Support formats: mermaid (default), dot (Graphviz), json
  • Highlight critical path tasks in red when show_critical_path=True
  • Color-code tasks by status (pending/in_progress/completed/blocked)
  • If saving to file, auto-detect format from extension (.mmd, .dot, .json)

5.3 Add Scheduling Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add suggest-order command:

  @tasks_app.command("suggest-order")
  def suggest_execution_order(
      project_id: int,
      optimize_for: str = typer.Option("duration", "--optimize", "-o"),
      show_timeline: bool = typer.Option(True, "--timeline/--no-timeline"),
      show_parallel: bool = typer.Option(True, "--parallel/--no-parallel")
  )

  • Call API endpoint GET /api/projects/{id}/tasks/suggested-order
  • Display optimal task execution order with task numbers and titles
  • Show estimated completion timeline with milestones
  • Highlight parallel execution opportunities (execution waves)
  • Display estimated total duration and critical path length
  • Show resource requirements for each task
  • Support optimization strategies: "duration" (minimize time), "resources" (balance load)

5.4 Add Task Generation Command

Extend file:codeframe/cli/tasks_commands.py:

• Add generate command:

  @tasks_app.command("generate")
  def generate_tasks(
      project_id: int,
      use_templates: bool = typer.Option(True, "--templates/--no-templates"),
      estimate_effort: bool = typer.Option(True, "--estimate/--no-estimate"),
      show_summary: bool = typer.Option(True, "--summary/--no-summary")
  )

  • Trigger task generation from PRD via POST /api/projects/{id}/tasks/generate
  • Apply templates when applicable (if use_templates=True)
  • Include effort estimation (if estimate_effort=True)
  • Display generated tasks with estimates, complexity scores, and dependencies
  • Show summary: total tasks, estimated duration, template usage, critical path length
  • Display any dependency conflicts or bottlenecks detected

Phase 6: API Endpoints

6.1 Create Task Analysis Router

Create new file file:codeframe/ui/routers/task_analysis.py:

• Implement endpoints:
  • GET /api/projects/{id}/tasks/analysis - Dependency analysis with conflicts and critical path
    • Returns: conflicts (list), critical_path (list of task IDs), bottlenecks (list), summary stats
  • GET /api/projects/{id}/tasks/dependency-graph - Mermaid/DOT graph representation
    • Query params: format (mermaid/dot/json), show_critical_path (bool)
    • Returns: graph data in requested format
  • GET /api/projects/{id}/tasks/suggested-order - Optimal execution order
    • Query params: optimize_for (duration/resources)
    • Returns: execution waves, timeline, estimated duration, parallel opportunities
  • GET /api/projects/{id}/tasks/critical-path - Critical path tasks and duration
    • Returns: critical task IDs, total duration, task timings (start/end)
  • GET /api/projects/{id}/tasks/schedule - Scheduled task timeline
    • Returns: task assignments, start/end times, resource allocation
  • POST /api/projects/{id}/tasks/generate - Trigger task generation with options
    • Request body: use_templates (bool), estimate_effort (bool)
    • Returns: generated tasks with estimates, conflicts, critical path

6.2 Update Existing Task Endpoints

Modify file:codeframe/ui/routers/tasks.py:

• Enhance GET /api/projects/{id}/tasks response to include:
  • estimated_hours, complexity_score, uncertainty_level, resource_requirements
  • is_critical_path boolean flag
  • slack_hours for non-critical tasks (null for critical path tasks)
  • parallel_group integer for tasks that can run concurrently (execution wave)
  • blocking_count - number of tasks blocked by this task
  • blocked_by_count - number of tasks blocking this task
• Add query parameters for filtering:
  • ?critical_path=true - Only critical path tasks
  • ?has_conflicts=true - Tasks with dependency conflicts
  • ?ready=true - Tasks ready to execute (dependencies satisfied)
  • ?parallel_group=N - Tasks in execution wave N
  • ?complexity=3 - Tasks with specific complexity score

Phase 7: Testing and Documentation

7.1 Unit Tests

Create test files:

• file:tests/planning/test_task_decomposer_effort.py - Test effort estimation parsing
  • Test parsing of complexity scores, hours, resource requirements from Claude response
  • Test fallback to defaults when parsing fails
  • Test uncertainty level assignment
• file:tests/agents/test_dependency_resolver_critical_path.py - Test critical path algorithms
  • Test critical path calculation with various task durations
  • Test slack calculation for non-critical tasks
  • Test parallel opportunity identification
  • Test conflict detection (bottlenecks, long chains)
• file:tests/planning/test_task_scheduler.py - Test scheduling logic
  • Test task scheduling with dependencies
  • Test schedule optimization
  • Test completion date prediction
  • Test bottleneck identification
• file:tests/planning/test_task_templates.py - Test template application
  • Test template loading and retrieval
  • Test template applicability detection
  • Test variable substitution in templates
  • Test custom template persistence
• file:tests/planning/test_dependency_visualizer.py - Test visualization generation
  • Test Mermaid diagram generation
  • Test Gantt chart generation
  • Test format exports (DOT, JSON)
• file:tests/cli/test_tasks_commands_enhanced.py - Test new CLI commands
  • Test analyze, visualize-deps, suggest-order, generate commands
  • Test output formatting and options
• file:tests/api/test_task_analysis_endpoints.py - Test analysis API endpoints
  • Test all new endpoints with various project states
  • Test filtering and query parameters

7.2 Integration Tests

Create integration test file file:tests/integration/test_task_generation_e2e.py:

• Test full flow: PRD → Issues → Tasks with effort estimation
  • Verify effort estimates are parsed and stored correctly
  • Validate complexity scores and uncertainty levels
• Verify dependency analysis and critical path calculation
  • Test with various dependency patterns
  • Validate critical path identification
  • Verify slack calculations
• Test template application for common patterns
  • Test REST API endpoint template
  • Test CRUD template
  • Test setup template
  • Verify template variable substitution
• Validate scheduling and conflict detection
  • Test schedule generation with dependencies
  • Verify bottleneck detection
  • Test conflict resolution suggestions
• Test end-to-end CLI workflow
  • Generate tasks from PRD
  • Analyze dependencies
  • Visualize dependency graph
  • Get suggested execution order

7.3 Documentation

Create/update documentation files:

• file:docs/TASK_GENERATION.md - Comprehensive guide to task generation features
  • Explain effort estimation process and accuracy expectations
  • Document complexity scoring system
  • Show examples of generated tasks with estimates
• file:docs/DEPENDENCY_ANALYSIS.md - Dependency analysis and critical path documentation
  • Explain critical path method (CPM) algorithm
  • Document conflict detection and resolution
  • Show examples of dependency graphs and analysis output
• file:docs/TASK_TEMPLATES.md - Template system usage and custom template creation
  • List built-in templates with examples
  • Explain template applicability detection
  • Guide for creating custom templates
  • Document template versioning and migration
• file:docs/TASK_SCHEDULING.md - Task scheduling and timeline prediction
  • Explain scheduling algorithm and constraints
  • Document parallel execution opportunities
  • Show timeline prediction examples
• Update file:docs/CLI_WIREFRAME.md with new commands
  • Add analyze, visualize-deps, suggest-order, generate commands
  • Show example outputs and options
• Update file:README.md with new features section
  • Highlight effort estimation, critical path analysis, templates
  • Link to detailed documentation

Phase 8: UI Integration (Optional Enhancement)

8.1 Dashboard Components

Create React components in file:web-ui/src/components/tasks/:

• TaskDependencyGraph.tsx - Interactive dependency visualization using Mermaid
• CriticalPathView.tsx - Highlight critical path tasks
• TaskScheduleTimeline.tsx - Gantt chart view of scheduled tasks
• TaskEffortEstimates.tsx - Display effort estimates and complexity scores
• DependencyConflicts.tsx - Show conflicts with resolution suggestions

8.2 API Integration

Update file:web-ui/src/lib/api.ts:

• Add API client methods for new endpoints
• Add TypeScript types for analysis responses
• Integrate with existing task management UI

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant API
    participant LeadAgent
    participant TaskDecomposer
    participant DependencyResolver
    participant TaskScheduler
    participant Database

    User->>CLI: codeframe tasks generate 1
    CLI->>API: POST /api/projects/1/tasks/generate
    API->>LeadAgent: generate_issues_from_prd()
    LeadAgent->>TaskDecomposer: decompose_issue(issue)
    TaskDecomposer->>TaskDecomposer: build_prompt_with_effort_estimation()
    TaskDecomposer->>Claude: Send enhanced prompt
    Claude-->>TaskDecomposer: Tasks with effort estimates
    TaskDecomposer->>TaskDecomposer: parse_effort_data()
    TaskDecomposer-->>LeadAgent: Tasks with estimates
    LeadAgent->>DependencyResolver: build_dependency_graph(tasks)
    DependencyResolver->>DependencyResolver: calculate_critical_path()
    DependencyResolver->>DependencyResolver: detect_conflicts()
    DependencyResolver-->>LeadAgent: Analysis results
    LeadAgent->>TaskScheduler: schedule_tasks(tasks, agents)
    TaskScheduler-->>LeadAgent: Scheduled timeline
    LeadAgent->>Database: save_tasks_with_metadata()
    Database-->>LeadAgent: Task IDs
    LeadAgent-->>API: Generation summary
    API-->>CLI: Success response
    CLI-->>User: Display tasks with estimates

Loading

Success Metrics

• Effort Estimation Accuracy: Track actual vs estimated hours for completed tasks, target ±25% accuracy after 10+ tasks
  • Monitor estimation confidence levels over time
  • Identify patterns in estimation errors (over/under estimation)
• Critical Path Identification: Verify critical path tasks are prioritized in agent assignment
  • Measure % of critical path tasks completed on schedule
  • Track impact of critical path awareness on project timeline
• Template Usage: Measure % of tasks generated from templates vs LLM decomposition
  • Target: 40%+ of tasks from templates after 20 issues
  • Track template accuracy vs LLM decomposition
• Dependency Conflict Detection: Count conflicts detected and resolved before execution
  • Track conflicts prevented through early detection
  • Measure impact on project delays
• Scheduling Optimization: Compare actual project duration vs predicted timeline
  • Target: Predictions within ±15% of actual duration
  • Track improvement over time as historical data accumulates
• CLI Adoption: Track usage of new analysis and visualization commands
  • Monitor command frequency and user satisfaction

Dependencies

• Existing file:codeframe/planning/task_decomposer.py for LLM integration
• Existing file:codeframe/agents/dependency_resolver.py for DAG operations
• Existing file:codeframe/agents/lead_agent.py for orchestration
• Anthropic Claude API for enhanced task decomposition prompts
• Database schema updates require migration scripts

Risk Mitigation

• Backward Compatibility: New fields are optional; existing tasks continue to work
  • Database migrations add columns with default values
  • API responses include new fields only when available
  • Existing task workflows unaffected
• LLM Reliability: Fall back to simple decomposition if effort estimation fails
  • Use default estimates when Claude parsing fails
  • Log estimation failures for monitoring
  • Provide manual override capability
• Performance: Cache dependency analysis results; recompute only on task changes
  • Cache critical path calculations
  • Invalidate cache on task creation/update/deletion
  • Monitor cache hit rates
• Template Maintenance: Version templates and provide migration path for updates
  • Track template versions in database
  • Provide migration scripts for template updates
  • Allow rollback to previous template versions
• Estimation Accuracy: Continuously improve estimates with historical data
  • Track estimation vs actual for all tasks
  • Adjust default estimates based on project history
  • Provide feedback loop for estimation refinement

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a solid foundation for task generation with LLM-powered decomposition (`file:codeframe/planning/task_decomposer.py`), hierarchical issue/task modeling, and DAG-based dependency resolution (`file:codeframe/agents/dependency_resolver.py`). The current system generates tasks from PRD content via `file:codeframe/agents/lead_agent.py` and stores them with basic dependency information. However, it lacks advanced features like effort estimation, critical path analysis, and intelligent scheduling that would enable predictable project execution.

## Approach

The implementation will enhance the existing task generation pipeline by integrating AI-powered analysis at each stage: (1) extend `TaskDecomposer` to include effort estimation during LLM-based decomposition, (2) enhance `DependencyResolver` with critical path algorithms and scheduling capabilities, (3) create a template system for common task patterns, and (4) add new CLI commands for dependency visualization and conflict analysis. This approach builds incrementally on proven components while maintaining backward compatibility with existing task workflows.

## Implementation Plan

### Phase 1: Enhanced Task Decomposition with Effort Estimation

**1.1 Extend TaskDecomposer for Effort Estimation**

Modify `file:codeframe/planning/task_decomposer.py`:
- Enhance `build_decomposition_prompt()` method to request effort estimation
  - Add section requesting complexity (1-5 scale) for each task
  - Request time estimation (hours) based on task scope
  - Ask for resource requirements (skills, tools, dependencies)
  - Request uncertainty assessment (low/medium/high) for ambiguous tasks
- Enhance `parse_claude_response()` method to extract effort data
  - Parse complexity scores from Claude response
  - Extract estimated hours for each task
  - Parse resource requirements as JSON
  - Extract uncertainty levels
- Store estimates in new Task fields (see 1.2)
- Add fallback to default estimates if parsing fails
- Log estimation confidence for tracking accuracy over time

**1.2 Update Task Model**

Modify `file:codeframe/core/models.py`:
- Add new fields to `Task` dataclass:
  - `estimated_hours: Optional[float]` - Time estimate in hours
  - `complexity_score: Optional[int]` - Complexity rating (1-5)
  - `uncertainty_level: Optional[str]` - "low", "medium", "high"
  - `resource_requirements: Optional[str]` - JSON string of required skills/tools
- Update `to_dict()` method to include new fields

**1.3 Database Schema Migration**

Update database schema in `file:codeframe/persistence/database.py`:
- Add columns to `tasks` table: `estimated_hours`, `complexity_score`, `uncertainty_level`, `resource_requirements`
- Create migration script to add columns with default values
- Update `file:codeframe/persistence/repositories/task_repository.py` to handle new fields in `_row_to_task()` and `create_task_with_issue()`

### Phase 2: Advanced Dependency Analysis

**2.1 Enhance DependencyResolver with Critical Path Analysis**

Extend `file:codeframe/agents/dependency_resolver.py`:
- Add `calculate_critical_path(task_durations: Dict[int, float])` method using longest path algorithm
  - Accept task duration estimates (hours) as input
  - Compute earliest start/finish times for each task using forward pass
  - Compute latest start/finish times using backward pass
  - Identify tasks with zero slack (critical path)
  - Return `CriticalPathResult` with critical task IDs, total duration, and task timings
- Add `identify_parallel_opportunities()` method
  - Find tasks that can execute concurrently (no dependency conflicts)
  - Group tasks by dependency level for parallel execution waves
  - Return dict mapping execution wave (0, 1, 2...) to task IDs
  - Include wave duration estimates
- Add `calculate_task_slack(task_durations: Dict[int, float])` method
  - Compute float/slack time for each task using critical path data
  - Return dict mapping task ID to slack hours
  - Tasks with zero slack are on critical path

**2.2 Add Conflict Detection and Resolution**

Extend `file:codeframe/agents/dependency_resolver.py`:
- Add `detect_dependency_conflicts(task_durations: Dict[int, float])` method
  - Identify bottleneck tasks (many dependents, high impact on critical path)
  - Detect long dependency chains that risk delays (chain length > 5 tasks)
  - Find tasks with high complexity and many dependents (risk multipliers)
  - Return list of `DependencyConflict` objects with severity (critical/high/medium) and recommendations
  - Include impact analysis (how many tasks blocked, estimated delay)
- Add `suggest_dependency_resolution(conflicts: List[DependencyConflict])` method
  - Propose task splitting for bottlenecks to increase parallelization
  - Suggest dependency reordering to reduce critical path length
  - Recommend prioritizing high-impact tasks
  - Return list of `ResolutionSuggestion` objects with expected improvements

**2.3 Create Dependency Visualization Support**

Create new file `file:codeframe/planning/dependency_visualizer.py`:
- Implement `generate_dependency_graph(tasks, critical_path_ids, task_status)` function
  - Accept list of tasks, critical path task IDs, and task status map
  - Generate Mermaid flowchart syntax for task DAG
  - Highlight critical path tasks in red/bold
  - Color-code tasks by status: pending (gray), in_progress (blue), completed (green), blocked (orange)
  - Include task complexity scores as node labels
  - Return Mermaid markdown string suitable for display/export
- Implement `generate_gantt_chart(tasks, task_durations, critical_path_ids)` function
  - Create Gantt chart representation with estimated durations
  - Show task dependencies and critical path highlighting
  - Include milestone markers for critical path completion
  - Return Mermaid Gantt syntax
- Implement `export_graph_formats(graph_data)` function
  - Support export to Mermaid, DOT (Graphviz), and JSON formats
  - Enable integration with external visualization tools

### Phase 3: Intelligent Task Scheduling

**3.1 Create Task Scheduler Component**

Create new file `file:codeframe/planning/task_scheduler.py`:
- Implement `TaskScheduler` class with methods:
  - `schedule_tasks(tasks, task_durations, agents_available)` - Assign start times based on dependencies and resources
    - Use critical path method (CPM) for scheduling
    - Consider agent availability and skill matching from resource requirements
    - Return `ScheduleResult` with task assignments, start/end times, and timeline
  - `optimize_schedule(schedule, constraints)` - Use heuristics to minimize project duration
    - Identify parallelization opportunities
    - Suggest task reordering within slack windows
    - Return optimized schedule with estimated duration reduction
  - `predict_completion_date(current_progress, schedule)` - Estimate project end date based on current progress
    - Account for completed tasks and in-progress work
    - Apply historical velocity factors
    - Return predicted completion date with confidence interval
  - `identify_bottlenecks(schedule, task_durations)` - Find tasks/agents causing delays
    - Identify tasks on critical path with high duration
    - Find agents with overallocation
    - Return list of bottleneck items with impact analysis

**3.2 Integrate Scheduler with LeadAgent**

Modify `file:codeframe/agents/lead_agent.py`:
- Add `schedule_project_tasks()` method that calls `TaskScheduler`
- Update `start_multi_agent_execution()` to use scheduled task assignments
- Add scheduling metadata to task assignment broadcasts
- Store schedule in database for progress tracking

### Phase 4: Task Template System

**4.1 Create Template Framework**

Create new file `file:codeframe/planning/task_templates.py`:
- Define `TaskTemplate` dataclass with fields:
  - `name: str` - Template identifier (e.g., "rest_api_endpoint")
  - `category: str` - "setup", "implementation", "testing", "deployment", "refactor"
  - `keywords: List[str]` - Keywords for automatic detection (e.g., ["API", "endpoint", "REST"])
  - `task_pattern: List[Dict]` - List of task definitions with placeholders
    - Each task has: title, description, complexity_score, estimated_hours
  - `dependencies: List[Tuple[int, int]]` - Dependency relationships between task indices
  - `estimated_hours: Dict[int, float]` - Time estimates per task
  - `version: str` - Template version for migration tracking
- Implement `TemplateLibrary` class:
  - `load_templates()` - Load built-in and custom templates from `file:codeframe/planning/templates/`
  - `get_template(name)` - Retrieve template by name
  - `find_applicable_templates(issue_description)` - Find templates matching issue keywords
  - `apply_template(template, context)` - Generate tasks from template with variable substitution
  - `save_custom_template(template)` - Persist user-defined templates to database
  - `get_template_stats()` - Return usage statistics for each template

**4.2 Create Built-in Templates**

Create template definitions in `file:codeframe/planning/templates/`:
- `setup_template.json` - Project initialization tasks
  - Initialize git repository, setup environment, install dependencies, configure tools
  - 4-5 sequential tasks, ~8-12 hours total
- `rest_api_endpoint_template.json` - REST API implementation pattern
  - Design schema, implement endpoint, add validation, write tests, document API
  - 5-6 tasks with some parallelization, ~12-16 hours total
- `crud_template.json` - CRUD operations for a model
  - Create model, implement create/read/update/delete operations, add tests
  - 4-5 sequential tasks, ~10-14 hours total
- `testing_template.json` - Test suite setup and implementation
  - Setup test framework, write unit tests, add integration tests, configure CI
  - 4-5 tasks with parallelization opportunities, ~8-12 hours total
- `deployment_template.json` - CI/CD and deployment tasks
  - Setup CI pipeline, configure deployment, add monitoring, document process
  - 4-5 sequential tasks, ~10-15 hours total
- `refactor_template.json` - Code refactoring pattern
  - Analyze code, plan refactoring, implement changes, test thoroughly, document
  - 5-6 tasks, ~12-18 hours total
- Each template includes task titles, descriptions, complexity scores, dependencies, and estimates

**4.3 Integrate Templates with Task Generation**

Modify `file:codeframe/planning/task_decomposer.py`:
- Add `detect_template_applicability(issue: Issue)` method
  - Analyze issue title and description for template keywords
  - Score each template based on keyword matches (0.0-1.0)
  - Return list of applicable templates sorted by confidence
  - Threshold: only return templates with confidence > 0.6
- Add `apply_template_if_applicable(issue: Issue, templates: List[TaskTemplate])` method
  - Check if highest-confidence template exceeds confidence threshold (0.75)
  - Apply template with variable substitution (issue title, description, priority)
  - Preserve issue number and parent relationships
  - Return generated tasks or None if no suitable template
- Update `decompose_issue()` to try template matching first
  - Call `detect_template_applicability()` and `apply_template_if_applicable()`
  - Fall back to LLM decomposition if no suitable template (confidence < 0.75)
  - Log template usage for analytics
- Add `_substitute_template_variables()` helper method
  - Replace placeholders like {issue_title}, {issue_description} in task templates

### Phase 5: Enhanced CLI Commands

**5.1 Add Dependency Analysis Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `analyze` command:
  ```python
  @tasks_app.command("analyze")
  def analyze_dependencies(
      project_id: int,
      show_conflicts: bool = typer.Option(False, "--conflicts"),
      show_critical_path: bool = typer.Option(False, "--critical-path"),
      show_bottlenecks: bool = typer.Option(False, "--bottlenecks"),
      show_all: bool = typer.Option(False, "--all")
  )
  ```
  - Call new API endpoint `GET /api/projects/{id}/tasks/analysis`
  - Display dependency conflicts with severity and recommendations
  - Display critical path tasks with total duration
  - Display bottleneck tasks with impact analysis
  - Use rich tables with color coding: critical (red), high (orange), medium (yellow)
  - Show summary statistics (total tasks, critical path length, conflicts count)

**5.2 Add Visualization Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `visualize-deps` command:
  ```python
  @tasks_app.command("visualize-deps")
  def visualize_dependencies(
      project_id: int,
      format: str = typer.Option("mermaid", "--format", "-f"),
      save_to: Optional[str] = typer.Option(None, "--output", "-o"),
      show_critical_path: bool = typer.Option(True, "--critical-path/--no-critical-path")
  )
  ```
  - Call API endpoint `GET /api/projects/{id}/tasks/dependency-graph`
  - Display Mermaid diagram in terminal or save to file
  - Support formats: mermaid (default), dot (Graphviz), json
  - Highlight critical path tasks in red when `show_critical_path=True`
  - Color-code tasks by status (pending/in_progress/completed/blocked)
  - If saving to file, auto-detect format from extension (.mmd, .dot, .json)

**5.3 Add Scheduling Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `suggest-order` command:
  ```python
  @tasks_app.command("suggest-order")
  def suggest_execution_order(
      project_id: int,
      optimize_for: str = typer.Option("duration", "--optimize", "-o"),
      show_timeline: bool = typer.Option(True, "--timeline/--no-timeline"),
      show_parallel: bool = typer.Option(True, "--parallel/--no-parallel")
  )
  ```
  - Call API endpoint `GET /api/projects/{id}/tasks/suggested-order`
  - Display optimal task execution order with task numbers and titles
  - Show estimated completion timeline with milestones
  - Highlight parallel execution opportunities (execution waves)
  - Display estimated total duration and critical path length
  - Show resource requirements for each task
  - Support optimization strategies: "duration" (minimize time), "resources" (balance load)

**5.4 Add Task Generation Command**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `generate` command:
  ```python
  @tasks_app.command("generate")
  def generate_tasks(
      project_id: int,
      use_templates: bool = typer.Option(True, "--templates/--no-templates"),
      estimate_effort: bool = typer.Option(True, "--estimate/--no-estimate"),
      show_summary: bool = typer.Option(True, "--summary/--no-summary")
  )
  ```
  - Trigger task generation from PRD via `POST /api/projects/{id}/tasks/generate`
  - Apply templates when applicable (if `use_templates=True`)
  - Include effort estimation (if `estimate_effort=True`)
  - Display generated tasks with estimates, complexity scores, and dependencies
  - Show summary: total tasks, estimated duration, template usage, critical path length
  - Display any dependency conflicts or bottlenecks detected

### Phase 6: API Endpoints

**6.1 Create Task Analysis Router**

Create new file `file:codeframe/ui/routers/task_analysis.py`:
- Implement endpoints:
  - `GET /api/projects/{id}/tasks/analysis` - Dependency analysis with conflicts and critical path
    - Returns: conflicts (list), critical_path (list of task IDs), bottlenecks (list), summary stats
  - `GET /api/projects/{id}/tasks/dependency-graph` - Mermaid/DOT graph representation
    - Query params: `format` (mermaid/dot/json), `show_critical_path` (bool)
    - Returns: graph data in requested format
  - `GET /api/projects/{id}/tasks/suggested-order` - Optimal execution order
    - Query params: `optimize_for` (duration/resources)
    - Returns: execution waves, timeline, estimated duration, parallel opportunities
  - `GET /api/projects/{id}/tasks/critical-path` - Critical path tasks and duration
    - Returns: critical task IDs, total duration, task timings (start/end)
  - `GET /api/projects/{id}/tasks/schedule` - Scheduled task timeline
    - Returns: task assignments, start/end times, resource allocation
  - `POST /api/projects/{id}/tasks/generate` - Trigger task generation with options
    - Request body: `use_templates` (bool), `estimate_effort` (bool)
    - Returns: generated tasks with estimates, conflicts, critical path

**6.2 Update Existing Task Endpoints**

Modify `file:codeframe/ui/routers/tasks.py`:
- Enhance `GET /api/projects/{id}/tasks` response to include:
  - `estimated_hours`, `complexity_score`, `uncertainty_level`, `resource_requirements`
  - `is_critical_path` boolean flag
  - `slack_hours` for non-critical tasks (null for critical path tasks)
  - `parallel_group` integer for tasks that can run concurrently (execution wave)
  - `blocking_count` - number of tasks blocked by this task
  - `blocked_by_count` - number of tasks blocking this task
- Add query parameters for filtering:
  - `?critical_path=true` - Only critical path tasks
  - `?has_conflicts=true` - Tasks with dependency conflicts
  - `?ready=true` - Tasks ready to execute (dependencies satisfied)
  - `?parallel_group=N` - Tasks in execution wave N
  - `?complexity=3` - Tasks with specific complexity score

### Phase 7: Testing and Documentation

**7.1 Unit Tests**

Create test files:
- `file:tests/planning/test_task_decomposer_effort.py` - Test effort estimation parsing
  - Test parsing of complexity scores, hours, resource requirements from Claude response
  - Test fallback to defaults when parsing fails
  - Test uncertainty level assignment
- `file:tests/agents/test_dependency_resolver_critical_path.py` - Test critical path algorithms
  - Test critical path calculation with various task durations
  - Test slack calculation for non-critical tasks
  - Test parallel opportunity identification
  - Test conflict detection (bottlenecks, long chains)
- `file:tests/planning/test_task_scheduler.py` - Test scheduling logic
  - Test task scheduling with dependencies
  - Test schedule optimization
  - Test completion date prediction
  - Test bottleneck identification
- `file:tests/planning/test_task_templates.py` - Test template application
  - Test template loading and retrieval
  - Test template applicability detection
  - Test variable substitution in templates
  - Test custom template persistence
- `file:tests/planning/test_dependency_visualizer.py` - Test visualization generation
  - Test Mermaid diagram generation
  - Test Gantt chart generation
  - Test format exports (DOT, JSON)
- `file:tests/cli/test_tasks_commands_enhanced.py` - Test new CLI commands
  - Test analyze, visualize-deps, suggest-order, generate commands
  - Test output formatting and options
- `file:tests/api/test_task_analysis_endpoints.py` - Test analysis API endpoints
  - Test all new endpoints with various project states
  - Test filtering and query parameters

**7.2 Integration Tests**

Create integration test file `file:tests/integration/test_task_generation_e2e.py`:
- Test full flow: PRD → Issues → Tasks with effort estimation
  - Verify effort estimates are parsed and stored correctly
  - Validate complexity scores and uncertainty levels
- Verify dependency analysis and critical path calculation
  - Test with various dependency patterns
  - Validate critical path identification
  - Verify slack calculations
- Test template application for common patterns
  - Test REST API endpoint template
  - Test CRUD template
  - Test setup template
  - Verify template variable substitution
- Validate scheduling and conflict detection
  - Test schedule generation with dependencies
  - Verify bottleneck detection
  - Test conflict resolution suggestions
- Test end-to-end CLI workflow
  - Generate tasks from PRD
  - Analyze dependencies
  - Visualize dependency graph
  - Get suggested execution order

**7.3 Documentation**

Create/update documentation files:
- `file:docs/TASK_GENERATION.md` - Comprehensive guide to task generation features
  - Explain effort estimation process and accuracy expectations
  - Document complexity scoring system
  - Show examples of generated tasks with estimates
- `file:docs/DEPENDENCY_ANALYSIS.md` - Dependency analysis and critical path documentation
  - Explain critical path method (CPM) algorithm
  - Document conflict detection and resolution
  - Show examples of dependency graphs and analysis output
- `file:docs/TASK_TEMPLATES.md` - Template system usage and custom template creation
  - List built-in templates with examples
  - Explain template applicability detection
  - Guide for creating custom templates
  - Document template versioning and migration
- `file:docs/TASK_SCHEDULING.md` - Task scheduling and timeline prediction
  - Explain scheduling algorithm and constraints
  - Document parallel execution opportunities
  - Show timeline prediction examples
- Update `file:docs/CLI_WIREFRAME.md` with new commands
  - Add `analyze`, `visualize-deps`, `suggest-order`, `generate` commands
  - Show example outputs and options
- Update `file:README.md` with new features section
  - Highlight effort estimation, critical path analysis, templates
  - Link to detailed documentation

### Phase 8: UI Integration (Optional Enhancement)

**8.1 Dashboard Components**

Create React components in `file:web-ui/src/components/tasks/`:
- `TaskDependencyGraph.tsx` - Interactive dependency visualization using Mermaid
- `CriticalPathView.tsx` - Highlight critical path tasks
- `TaskScheduleTimeline.tsx` - Gantt chart view of scheduled tasks
- `TaskEffortEstimates.tsx` - Display effort estimates and complexity scores
- `DependencyConflicts.tsx` - Show conflicts with resolution suggestions

**8.2 API Integration**

Update `file:web-ui/src/lib/api.ts`:
- Add API client methods for new endpoints
- Add TypeScript types for analysis responses
- Integrate with existing task management UI

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant API
    participant LeadAgent
    participant TaskDecomposer
    participant DependencyResolver
    participant TaskScheduler
    participant Database

    User->>CLI: codeframe tasks generate 1
    CLI->>API: POST /api/projects/1/tasks/generate
    API->>LeadAgent: generate_issues_from_prd()
    LeadAgent->>TaskDecomposer: decompose_issue(issue)
    TaskDecomposer->>TaskDecomposer: build_prompt_with_effort_estimation()
    TaskDecomposer->>Claude: Send enhanced prompt
    Claude-->>TaskDecomposer: Tasks with effort estimates
    TaskDecomposer->>TaskDecomposer: parse_effort_data()
    TaskDecomposer-->>LeadAgent: Tasks with estimates
    LeadAgent->>DependencyResolver: build_dependency_graph(tasks)
    DependencyResolver->>DependencyResolver: calculate_critical_path()
    DependencyResolver->>DependencyResolver: detect_conflicts()
    DependencyResolver-->>LeadAgent: Analysis results
    LeadAgent->>TaskScheduler: schedule_tasks(tasks, agents)
    TaskScheduler-->>LeadAgent: Scheduled timeline
    LeadAgent->>Database: save_tasks_with_metadata()
    Database-->>LeadAgent: Task IDs
    LeadAgent-->>API: Generation summary
    API-->>CLI: Success response
    CLI-->>User: Display tasks with estimates
```

## Success Metrics

- **Effort Estimation Accuracy**: Track actual vs estimated hours for completed tasks, target ±25% accuracy after 10+ tasks
  - Monitor estimation confidence levels over time
  - Identify patterns in estimation errors (over/under estimation)
- **Critical Path Identification**: Verify critical path tasks are prioritized in agent assignment
  - Measure % of critical path tasks completed on schedule
  - Track impact of critical path awareness on project timeline
- **Template Usage**: Measure % of tasks generated from templates vs LLM decomposition
  - Target: 40%+ of tasks from templates after 20 issues
  - Track template accuracy vs LLM decomposition
- **Dependency Conflict Detection**: Count conflicts detected and resolved before execution
  - Track conflicts prevented through early detection
  - Measure impact on project delays
- **Scheduling Optimization**: Compare actual project duration vs predicted timeline
  - Target: Predictions within ±15% of actual duration
  - Track improvement over time as historical data accumulates
- **CLI Adoption**: Track usage of new analysis and visualization commands
  - Monitor command frequency and user satisfaction

## Dependencies

- Existing `file:codeframe/planning/task_decomposer.py` for LLM integration
- Existing `file:codeframe/agents/dependency_resolver.py` for DAG operations
- Existing `file:codeframe/agents/lead_agent.py` for orchestration
- Anthropic Claude API for enhanced task decomposition prompts
- Database schema updates require migration scripts

## Risk Mitigation

- **Backward Compatibility**: New fields are optional; existing tasks continue to work
  - Database migrations add columns with default values
  - API responses include new fields only when available
  - Existing task workflows unaffected
- **LLM Reliability**: Fall back to simple decomposition if effort estimation fails
  - Use default estimates when Claude parsing fails
  - Log estimation failures for monitoring
  - Provide manual override capability
- **Performance**: Cache dependency analysis results; recompute only on task changes
  - Cache critical path calculations
  - Invalidate cache on task creation/update/deletion
  - Monitor cache hit rates
- **Template Maintenance**: Version templates and provide migration path for updates
  - Track template versions in database
  - Provide migration scripts for template updates
  - Allow rollback to previous template versions
- **Estimation Accuracy**: Continuously improve estimates with historical data
  - Track estimation vs actual for all tasks
  - Adjust default estimates based on project history
  - Provide feedback loop for estimation refinement

---

Execution Information

Branch: main
Commit: 81fdeee

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#74 - Refactor task identifier and dependency system [merged]
#205 - feat(planning): Add planning phase automation and task approval [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#016-6) [merged]
#234 - fix(ui): make TaskStats phase-aware to fix late-joining user bug [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The codebase has a solid foundation for task generation with LLM-powered decomposition (file:codeframe/planning/task_decomposer.py), hierarchical issue/task modeling, and DAG-based dependency resolution (file:codeframe/agents/dependency_resolver.py). The current system generates tasks from PRD content via file:codeframe/agents/lead_agent.py and stores them with basic dependency information. However, it lacks advanced features like effort estimation, critical path analysis, and intelligent scheduling that would enable predictable project execution.

Approach

The implementation will enhance the existing task generation pipeline by integrating AI-powered analysis at each stage: (1) extend TaskDecomposer to include effort estimation during LLM-based decomposition, (2) enhance DependencyResolver with critical path algorithms and scheduling capabilities, (3) create a template system for common task patterns, and (4) add new CLI commands for dependency visualization and conflict analysis. This approach builds incrementally on proven components while maintaining backward compatibility with existing task workflows.

Implementation Plan

Phase 1: Enhanced Task Decomposition with Effort Estimation

1.1 Extend TaskDecomposer for Effort Estimation

Modify file:codeframe/planning/task_decomposer.py:

• Add effort estimation to the LLM prompt in build_decomposition_prompt() method
• Request Claude to estimate complexity (1-5 scale) and time (hours) for each task
• Parse effort data from Claude response in parse_claude_response() method
• Store estimates in Task.estimated_tokens field (repurpose) or add new fields to schema
• Add uncertainty scoring (low/medium/high) based on task ambiguity

1.2 Update Task Model

Modify file:codeframe/core/models.py:

• Add new fields to Task dataclass:
  • estimated_hours: Optional[float] - Time estimate in hours
  • complexity_score: Optional[int] - Complexity rating (1-5)
  • uncertainty_level: Optional[str] - "low", "medium", "high"
  • resource_requirements: Optional[str] - JSON string of required skills/tools
• Update to_dict() method to include new fields

1.3 Database Schema Migration

Update database schema in file:codeframe/persistence/database.py:

• Add columns to tasks table: estimated_hours, complexity_score, uncertainty_level, resource_requirements
• Create migration script to add columns with default values
• Update file:codeframe/persistence/repositories/task_repository.py to handle new fields in _row_to_task() and create_task_with_issue()

Phase 2: Advanced Dependency Analysis

2.1 Enhance DependencyResolver with Critical Path Analysis

Extend file:codeframe/agents/dependency_resolver.py:

• Add calculate_critical_path() method using longest path algorithm
  • Compute earliest start/finish times for each task
  • Compute latest start/finish times (backward pass)
  • Identify tasks with zero slack (critical path)
  • Return list of critical task IDs and total project duration
• Add identify_parallel_opportunities() method
  • Find tasks that can execute concurrently (no dependency conflicts)
  • Group tasks by dependency level for parallel execution
  • Return dict mapping execution wave to task IDs
• Add calculate_task_slack() method
  • Compute float/slack time for each task
  • Return dict mapping task ID to slack hours

2.2 Add Conflict Detection and Resolution

Extend file:codeframe/agents/dependency_resolver.py:

• Add detect_dependency_conflicts() method
  • Check for resource conflicts (same agent assigned to parallel tasks)
  • Identify bottleneck tasks (many dependents)
  • Detect long dependency chains that risk delays
  • Return list of DependencyConflict objects with severity and recommendations
• Add suggest_dependency_resolution() method
  • Propose dependency reordering to reduce critical path
  • Suggest task splitting for bottlenecks
  • Recommend resource allocation changes

2.3 Create Dependency Visualization Support

Create new file file:codeframe/planning/dependency_visualizer.py:

• Implement generate_dependency_graph() function
  • Accept list of tasks and dependencies
  • Generate Mermaid diagram syntax for task DAG
  • Highlight critical path in red
  • Color-code tasks by status (pending/in_progress/completed)
  • Return Mermaid markdown string
• Implement generate_gantt_chart() function
  • Create Gantt chart representation with estimated durations
  • Show task dependencies and critical path
  • Return Mermaid Gantt syntax

Phase 3: Intelligent Task Scheduling

3.1 Create Task Scheduler Component

Create new file file:codeframe/planning/task_scheduler.py:

• Implement TaskScheduler class with methods:
  • schedule_tasks(tasks, agents_available) - Assign start times based on dependencies and resources
  • optimize_schedule() - Use heuristics to minimize project duration
  • predict_completion_date() - Estimate project end date based on current progress
  • identify_bottlenecks() - Find tasks/agents causing delays
• Use critical path method (CPM) for scheduling
• Consider agent availability and skill matching
• Return ScheduleResult with task assignments and timeline

3.2 Integrate Scheduler with LeadAgent

Modify file:codeframe/agents/lead_agent.py:

• Add schedule_project_tasks() method that calls TaskScheduler
• Update start_multi_agent_execution() to use scheduled task assignments
• Add scheduling metadata to task assignment broadcasts
• Store schedule in database for progress tracking

Phase 4: Task Template System

4.1 Create Template Framework

Create new file file:codeframe/planning/task_templates.py:

• Define TaskTemplate dataclass with fields:
  • name: str - Template identifier
  • category: str - "setup", "implementation", "testing", "deployment"
  • task_pattern: List[Dict] - List of task definitions with placeholders
  • dependencies: List[Tuple[int, int]] - Dependency relationships
  • estimated_hours: Dict[int, float] - Time estimates per task
• Implement TemplateLibrary class:
  • load_templates() - Load built-in and custom templates
  • get_template(name) - Retrieve template by name
  • apply_template(template, context) - Generate tasks from template with variable substitution
  • save_custom_template() - Persist user-defined templates

4.2 Create Built-in Templates

Create template definitions in file:codeframe/planning/templates/:

• setup_template.json - Project initialization tasks (git, env, dependencies)
• api_endpoint_template.json - REST API implementation pattern
• crud_template.json - CRUD operations for a model
• testing_template.json - Test suite setup and implementation
• deployment_template.json - CI/CD and deployment tasks
• Each template includes task titles, descriptions, dependencies, and estimates

4.3 Integrate Templates with Task Generation

Modify file:codeframe/planning/task_decomposer.py:

• Add detect_template_applicability() method
  • Analyze issue description for template keywords
  • Return list of applicable templates
• Add apply_template_if_applicable() method
  • Check if issue matches a template pattern
  • Apply template instead of LLM decomposition if confidence is high
  • Fall back to LLM for custom/complex issues
• Update decompose_issue() to try template matching first

Phase 5: Enhanced CLI Commands

5.1 Add Dependency Analysis Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add analyze command:

  @tasks_app.command("analyze")
  def analyze_dependencies(
      project_id: int,
      show_conflicts: bool = typer.Option(False, "--conflicts"),
      show_critical_path: bool = typer.Option(False, "--critical-path"),
      show_bottlenecks: bool = typer.Option(False, "--bottlenecks")
  )

  • Call new API endpoint GET /api/projects/{id}/tasks/analysis
  • Display dependency conflicts, critical path, and bottlenecks
  • Use rich tables and color coding for visualization

5.2 Add Visualization Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add visualize-deps command:

  @tasks_app.command("visualize-deps")
  def visualize_dependencies(
      project_id: int,
      output: str = typer.Option("mermaid", "--format", "-f"),
      save_to: Optional[str] = typer.Option(None, "--output", "-o")
  )

  • Call API endpoint GET /api/projects/{id}/tasks/dependency-graph
  • Display Mermaid diagram or save to file
  • Support formats: mermaid, dot (Graphviz), json

5.3 Add Scheduling Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add suggest-order command:

  @tasks_app.command("suggest-order")
  def suggest_execution_order(
      project_id: int,
      optimize_for: str = typer.Option("duration", "--optimize")
  )

  • Call API endpoint GET /api/projects/{id}/tasks/suggested-order
  • Display optimal task execution order
  • Show estimated completion timeline
  • Highlight parallel execution opportunities

5.4 Add Task Generation Command

Extend file:codeframe/cli/tasks_commands.py:

• Add generate command:

  @tasks_app.command("generate")
  def generate_tasks(
      project_id: int,
      use_templates: bool = typer.Option(True, "--templates/--no-templates"),
      estimate_effort: bool = typer.Option(True, "--estimate/--no-estimate")
  )

  • Trigger task generation from PRD
  • Apply templates and effort estimation
  • Display generated tasks with estimates

Phase 6: API Endpoints

6.1 Create Task Analysis Router

Create new file file:codeframe/ui/routers/task_analysis.py:

• Implement endpoints:
  • GET /api/projects/{id}/tasks/analysis - Dependency analysis with conflicts and critical path
  • GET /api/projects/{id}/tasks/dependency-graph - Mermaid/DOT graph representation
  • GET /api/projects/{id}/tasks/suggested-order - Optimal execution order
  • GET /api/projects/{id}/tasks/critical-path - Critical path tasks and duration
  • GET /api/projects/{id}/tasks/schedule - Scheduled task timeline
  • POST /api/projects/{id}/tasks/generate - Trigger task generation with options

6.2 Update Existing Task Endpoints

Modify file:codeframe/ui/routers/tasks.py:

• Enhance GET /api/projects/{id}/tasks response to include:
  • estimated_hours, complexity_score, uncertainty_level
  • is_critical_path boolean flag
  • slack_hours for non-critical tasks
  • parallel_group for tasks that can run concurrently
• Add query parameters for filtering:
  • ?critical_path=true - Only critical path tasks
  • ?has_conflicts=true - Tasks with dependency conflicts
  • ?ready=true - Tasks ready to execute (dependencies satisfied)

Phase 7: Testing and Documentation

7.1 Unit Tests

Create test files:

• file:tests/planning/test_task_decomposer_effort.py - Test effort estimation parsing
• file:tests/agents/test_dependency_resolver_critical_path.py - Test critical path algorithms
• file:tests/planning/test_task_scheduler.py - Test scheduling logic
• file:tests/planning/test_task_templates.py - Test template application
• file:tests/cli/test_tasks_commands_enhanced.py - Test new CLI commands
• file:tests/api/test_task_analysis_endpoints.py - Test analysis API endpoints

7.2 Integration Tests

Create integration test file file:tests/integration/test_task_generation_e2e.py:

• Test full flow: PRD → Issues → Tasks with effort estimation
• Verify dependency analysis and critical path calculation
• Test template application for common patterns
• Validate scheduling and conflict detection

7.3 Documentation

Create/update documentation files:

• file:docs/TASK_GENERATION.md - Comprehensive guide to task generation features
• file:docs/DEPENDENCY_ANALYSIS.md - Dependency analysis and critical path documentation
• file:docs/TASK_TEMPLATES.md - Template system usage and custom template creation
• Update file:docs/CLI_WIREFRAME.md with new commands
• Update file:README.md with new features section

Phase 8: UI Integration (Optional Enhancement)

8.1 Dashboard Components

Create React components in file:web-ui/src/components/tasks/:

• TaskDependencyGraph.tsx - Interactive dependency visualization using Mermaid
• CriticalPathView.tsx - Highlight critical path tasks
• TaskScheduleTimeline.tsx - Gantt chart view of scheduled tasks
• TaskEffortEstimates.tsx - Display effort estimates and complexity scores
• DependencyConflicts.tsx - Show conflicts with resolution suggestions

8.2 API Integration

Update file:web-ui/src/lib/api.ts:

• Add API client methods for new endpoints
• Add TypeScript types for analysis responses
• Integrate with existing task management UI

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant API
    participant LeadAgent
    participant TaskDecomposer
    participant DependencyResolver
    participant TaskScheduler
    participant Database

    User->>CLI: codeframe tasks generate 1
    CLI->>API: POST /api/projects/1/tasks/generate
    API->>LeadAgent: generate_issues_from_prd()
    LeadAgent->>TaskDecomposer: decompose_issue(issue)
    TaskDecomposer->>TaskDecomposer: build_prompt_with_effort_estimation()
    TaskDecomposer->>Claude: Send enhanced prompt
    Claude-->>TaskDecomposer: Tasks with effort estimates
    TaskDecomposer->>TaskDecomposer: parse_effort_data()
    TaskDecomposer-->>LeadAgent: Tasks with estimates
    LeadAgent->>DependencyResolver: build_dependency_graph(tasks)
    DependencyResolver->>DependencyResolver: calculate_critical_path()
    DependencyResolver->>DependencyResolver: detect_conflicts()
    DependencyResolver-->>LeadAgent: Analysis results
    LeadAgent->>TaskScheduler: schedule_tasks(tasks, agents)
    TaskScheduler-->>LeadAgent: Scheduled timeline
    LeadAgent->>Database: save_tasks_with_metadata()
    Database-->>LeadAgent: Task IDs
    LeadAgent-->>API: Generation summary
    API-->>CLI: Success response
    CLI-->>User: Display tasks with estimates

Loading

Success Metrics

• Effort Estimation Accuracy: Track actual vs estimated hours for completed tasks, target ±25% accuracy after 10+ tasks
• Critical Path Identification: Verify critical path tasks are prioritized in agent assignment
• Template Usage: Measure % of tasks generated from templates vs LLM decomposition
• Dependency Conflict Detection: Count conflicts detected and resolved before execution
• Scheduling Optimization: Compare actual project duration vs predicted timeline
• CLI Adoption: Track usage of new analysis and visualization commands

Dependencies

• Existing file:codeframe/planning/task_decomposer.py for LLM integration
• Existing file:codeframe/agents/dependency_resolver.py for DAG operations
• Existing file:codeframe/agents/lead_agent.py for orchestration
• Anthropic Claude API for enhanced task decomposition prompts
• Database schema updates require migration scripts

Risk Mitigation

• Backward Compatibility: New fields are optional; existing tasks continue to work
• LLM Reliability: Fall back to simple decomposition if effort estimation fails
• Performance: Cache dependency analysis results; recompute only on task changes
• Template Maintenance: Version templates and provide migration path for updates

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a solid foundation for task generation with LLM-powered decomposition (`file:codeframe/planning/task_decomposer.py`), hierarchical issue/task modeling, and DAG-based dependency resolution (`file:codeframe/agents/dependency_resolver.py`). The current system generates tasks from PRD content via `file:codeframe/agents/lead_agent.py` and stores them with basic dependency information. However, it lacks advanced features like effort estimation, critical path analysis, and intelligent scheduling that would enable predictable project execution.

## Approach

The implementation will enhance the existing task generation pipeline by integrating AI-powered analysis at each stage: (1) extend `TaskDecomposer` to include effort estimation during LLM-based decomposition, (2) enhance `DependencyResolver` with critical path algorithms and scheduling capabilities, (3) create a template system for common task patterns, and (4) add new CLI commands for dependency visualization and conflict analysis. This approach builds incrementally on proven components while maintaining backward compatibility with existing task workflows.

## Implementation Plan

### Phase 1: Enhanced Task Decomposition with Effort Estimation

**1.1 Extend TaskDecomposer for Effort Estimation**

Modify `file:codeframe/planning/task_decomposer.py`:
- Add effort estimation to the LLM prompt in `build_decomposition_prompt()` method
- Request Claude to estimate complexity (1-5 scale) and time (hours) for each task
- Parse effort data from Claude response in `parse_claude_response()` method
- Store estimates in `Task.estimated_tokens` field (repurpose) or add new fields to schema
- Add uncertainty scoring (low/medium/high) based on task ambiguity

**1.2 Update Task Model**

Modify `file:codeframe/core/models.py`:
- Add new fields to `Task` dataclass:
  - `estimated_hours: Optional[float]` - Time estimate in hours
  - `complexity_score: Optional[int]` - Complexity rating (1-5)
  - `uncertainty_level: Optional[str]` - "low", "medium", "high"
  - `resource_requirements: Optional[str]` - JSON string of required skills/tools
- Update `to_dict()` method to include new fields

**1.3 Database Schema Migration**

Update database schema in `file:codeframe/persistence/database.py`:
- Add columns to `tasks` table: `estimated_hours`, `complexity_score`, `uncertainty_level`, `resource_requirements`
- Create migration script to add columns with default values
- Update `file:codeframe/persistence/repositories/task_repository.py` to handle new fields in `_row_to_task()` and `create_task_with_issue()`

### Phase 2: Advanced Dependency Analysis

**2.1 Enhance DependencyResolver with Critical Path Analysis**

Extend `file:codeframe/agents/dependency_resolver.py`:
- Add `calculate_critical_path()` method using longest path algorithm
  - Compute earliest start/finish times for each task
  - Compute latest start/finish times (backward pass)
  - Identify tasks with zero slack (critical path)
  - Return list of critical task IDs and total project duration
- Add `identify_parallel_opportunities()` method
  - Find tasks that can execute concurrently (no dependency conflicts)
  - Group tasks by dependency level for parallel execution
  - Return dict mapping execution wave to task IDs
- Add `calculate_task_slack()` method
  - Compute float/slack time for each task
  - Return dict mapping task ID to slack hours

**2.2 Add Conflict Detection and Resolution**

Extend `file:codeframe/agents/dependency_resolver.py`:
- Add `detect_dependency_conflicts()` method
  - Check for resource conflicts (same agent assigned to parallel tasks)
  - Identify bottleneck tasks (many dependents)
  - Detect long dependency chains that risk delays
  - Return list of `DependencyConflict` objects with severity and recommendations
- Add `suggest_dependency_resolution()` method
  - Propose dependency reordering to reduce critical path
  - Suggest task splitting for bottlenecks
  - Recommend resource allocation changes

**2.3 Create Dependency Visualization Support**

Create new file `file:codeframe/planning/dependency_visualizer.py`:
- Implement `generate_dependency_graph()` function
  - Accept list of tasks and dependencies
  - Generate Mermaid diagram syntax for task DAG
  - Highlight critical path in red
  - Color-code tasks by status (pending/in_progress/completed)
  - Return Mermaid markdown string
- Implement `generate_gantt_chart()` function
  - Create Gantt chart representation with estimated durations
  - Show task dependencies and critical path
  - Return Mermaid Gantt syntax

### Phase 3: Intelligent Task Scheduling

**3.1 Create Task Scheduler Component**

Create new file `file:codeframe/planning/task_scheduler.py`:
- Implement `TaskScheduler` class with methods:
  - `schedule_tasks(tasks, agents_available)` - Assign start times based on dependencies and resources
  - `optimize_schedule()` - Use heuristics to minimize project duration
  - `predict_completion_date()` - Estimate project end date based on current progress
  - `identify_bottlenecks()` - Find tasks/agents causing delays
- Use critical path method (CPM) for scheduling
- Consider agent availability and skill matching
- Return `ScheduleResult` with task assignments and timeline

**3.2 Integrate Scheduler with LeadAgent**

Modify `file:codeframe/agents/lead_agent.py`:
- Add `schedule_project_tasks()` method that calls `TaskScheduler`
- Update `start_multi_agent_execution()` to use scheduled task assignments
- Add scheduling metadata to task assignment broadcasts
- Store schedule in database for progress tracking

### Phase 4: Task Template System

**4.1 Create Template Framework**

Create new file `file:codeframe/planning/task_templates.py`:
- Define `TaskTemplate` dataclass with fields:
  - `name: str` - Template identifier
  - `category: str` - "setup", "implementation", "testing", "deployment"
  - `task_pattern: List[Dict]` - List of task definitions with placeholders
  - `dependencies: List[Tuple[int, int]]` - Dependency relationships
  - `estimated_hours: Dict[int, float]` - Time estimates per task
- Implement `TemplateLibrary` class:
  - `load_templates()` - Load built-in and custom templates
  - `get_template(name)` - Retrieve template by name
  - `apply_template(template, context)` - Generate tasks from template with variable substitution
  - `save_custom_template()` - Persist user-defined templates

**4.2 Create Built-in Templates**

Create template definitions in `file:codeframe/planning/templates/`:
- `setup_template.json` - Project initialization tasks (git, env, dependencies)
- `api_endpoint_template.json` - REST API implementation pattern
- `crud_template.json` - CRUD operations for a model
- `testing_template.json` - Test suite setup and implementation
- `deployment_template.json` - CI/CD and deployment tasks
- Each template includes task titles, descriptions, dependencies, and estimates

**4.3 Integrate Templates with Task Generation**

Modify `file:codeframe/planning/task_decomposer.py`:
- Add `detect_template_applicability()` method
  - Analyze issue description for template keywords
  - Return list of applicable templates
- Add `apply_template_if_applicable()` method
  - Check if issue matches a template pattern
  - Apply template instead of LLM decomposition if confidence is high
  - Fall back to LLM for custom/complex issues
- Update `decompose_issue()` to try template matching first

### Phase 5: Enhanced CLI Commands

**5.1 Add Dependency Analysis Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `analyze` command:
  ```python
  @tasks_app.command("analyze")
  def analyze_dependencies(
      project_id: int,
      show_conflicts: bool = typer.Option(False, "--conflicts"),
      show_critical_path: bool = typer.Option(False, "--critical-path"),
      show_bottlenecks: bool = typer.Option(False, "--bottlenecks")
  )
  ```
  - Call new API endpoint `GET /api/projects/{id}/tasks/analysis`
  - Display dependency conflicts, critical path, and bottlenecks
  - Use rich tables and color coding for visualization

**5.2 Add Visualization Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `visualize-deps` command:
  ```python
  @tasks_app.command("visualize-deps")
  def visualize_dependencies(
      project_id: int,
      output: str = typer.Option("mermaid", "--format", "-f"),
      save_to: Optional[str] = typer.Option(None, "--output", "-o")
  )
  ```
  - Call API endpoint `GET /api/projects/{id}/tasks/dependency-graph`
  - Display Mermaid diagram or save to file
  - Support formats: mermaid, dot (Graphviz), json

**5.3 Add Scheduling Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `suggest-order` command:
  ```python
  @tasks_app.command("suggest-order")
  def suggest_execution_order(
      project_id: int,
      optimize_for: str = typer.Option("duration", "--optimize")
  )
  ```
  - Call API endpoint `GET /api/projects/{id}/tasks/suggested-order`
  - Display optimal task execution order
  - Show estimated completion timeline
  - Highlight parallel execution opportunities

**5.4 Add Task Generation Command**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `generate` command:
  ```python
  @tasks_app.command("generate")
  def generate_tasks(
      project_id: int,
      use_templates: bool = typer.Option(True, "--templates/--no-templates"),
      estimate_effort: bool = typer.Option(True, "--estimate/--no-estimate")
  )
  ```
  - Trigger task generation from PRD
  - Apply templates and effort estimation
  - Display generated tasks with estimates

### Phase 6: API Endpoints

**6.1 Create Task Analysis Router**

Create new file `file:codeframe/ui/routers/task_analysis.py`:
- Implement endpoints:
  - `GET /api/projects/{id}/tasks/analysis` - Dependency analysis with conflicts and critical path
  - `GET /api/projects/{id}/tasks/dependency-graph` - Mermaid/DOT graph representation
  - `GET /api/projects/{id}/tasks/suggested-order` - Optimal execution order
  - `GET /api/projects/{id}/tasks/critical-path` - Critical path tasks and duration
  - `GET /api/projects/{id}/tasks/schedule` - Scheduled task timeline
  - `POST /api/projects/{id}/tasks/generate` - Trigger task generation with options

**6.2 Update Existing Task Endpoints**

Modify `file:codeframe/ui/routers/tasks.py`:
- Enhance `GET /api/projects/{id}/tasks` response to include:
  - `estimated_hours`, `complexity_score`, `uncertainty_level`
  - `is_critical_path` boolean flag
  - `slack_hours` for non-critical tasks
  - `parallel_group` for tasks that can run concurrently
- Add query parameters for filtering:
  - `?critical_path=true` - Only critical path tasks
  - `?has_conflicts=true` - Tasks with dependency conflicts
  - `?ready=true` - Tasks ready to execute (dependencies satisfied)

### Phase 7: Testing and Documentation

**7.1 Unit Tests**

Create test files:
- `file:tests/planning/test_task_decomposer_effort.py` - Test effort estimation parsing
- `file:tests/agents/test_dependency_resolver_critical_path.py` - Test critical path algorithms
- `file:tests/planning/test_task_scheduler.py` - Test scheduling logic
- `file:tests/planning/test_task_templates.py` - Test template application
- `file:tests/cli/test_tasks_commands_enhanced.py` - Test new CLI commands
- `file:tests/api/test_task_analysis_endpoints.py` - Test analysis API endpoints

**7.2 Integration Tests**

Create integration test file `file:tests/integration/test_task_generation_e2e.py`:
- Test full flow: PRD → Issues → Tasks with effort estimation
- Verify dependency analysis and critical path calculation
- Test template application for common patterns
- Validate scheduling and conflict detection

**7.3 Documentation**

Create/update documentation files:
- `file:docs/TASK_GENERATION.md` - Comprehensive guide to task generation features
- `file:docs/DEPENDENCY_ANALYSIS.md` - Dependency analysis and critical path documentation
- `file:docs/TASK_TEMPLATES.md` - Template system usage and custom template creation
- Update `file:docs/CLI_WIREFRAME.md` with new commands
- Update `file:README.md` with new features section

### Phase 8: UI Integration (Optional Enhancement)

**8.1 Dashboard Components**

Create React components in `file:web-ui/src/components/tasks/`:
- `TaskDependencyGraph.tsx` - Interactive dependency visualization using Mermaid
- `CriticalPathView.tsx` - Highlight critical path tasks
- `TaskScheduleTimeline.tsx` - Gantt chart view of scheduled tasks
- `TaskEffortEstimates.tsx` - Display effort estimates and complexity scores
- `DependencyConflicts.tsx` - Show conflicts with resolution suggestions

**8.2 API Integration**

Update `file:web-ui/src/lib/api.ts`:
- Add API client methods for new endpoints
- Add TypeScript types for analysis responses
- Integrate with existing task management UI

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant API
    participant LeadAgent
    participant TaskDecomposer
    participant DependencyResolver
    participant TaskScheduler
    participant Database

    User->>CLI: codeframe tasks generate 1
    CLI->>API: POST /api/projects/1/tasks/generate
    API->>LeadAgent: generate_issues_from_prd()
    LeadAgent->>TaskDecomposer: decompose_issue(issue)
    TaskDecomposer->>TaskDecomposer: build_prompt_with_effort_estimation()
    TaskDecomposer->>Claude: Send enhanced prompt
    Claude-->>TaskDecomposer: Tasks with effort estimates
    TaskDecomposer->>TaskDecomposer: parse_effort_data()
    TaskDecomposer-->>LeadAgent: Tasks with estimates
    LeadAgent->>DependencyResolver: build_dependency_graph(tasks)
    DependencyResolver->>DependencyResolver: calculate_critical_path()
    DependencyResolver->>DependencyResolver: detect_conflicts()
    DependencyResolver-->>LeadAgent: Analysis results
    LeadAgent->>TaskScheduler: schedule_tasks(tasks, agents)
    TaskScheduler-->>LeadAgent: Scheduled timeline
    LeadAgent->>Database: save_tasks_with_metadata()
    Database-->>LeadAgent: Task IDs
    LeadAgent-->>API: Generation summary
    API-->>CLI: Success response
    CLI-->>User: Display tasks with estimates
```

## Success Metrics

- **Effort Estimation Accuracy**: Track actual vs estimated hours for completed tasks, target ±25% accuracy after 10+ tasks
- **Critical Path Identification**: Verify critical path tasks are prioritized in agent assignment
- **Template Usage**: Measure % of tasks generated from templates vs LLM decomposition
- **Dependency Conflict Detection**: Count conflicts detected and resolved before execution
- **Scheduling Optimization**: Compare actual project duration vs predicted timeline
- **CLI Adoption**: Track usage of new analysis and visualization commands

## Dependencies

- Existing `file:codeframe/planning/task_decomposer.py` for LLM integration
- Existing `file:codeframe/agents/dependency_resolver.py` for DAG operations
- Existing `file:codeframe/agents/lead_agent.py` for orchestration
- Anthropic Claude API for enhanced task decomposition prompts
- Database schema updates require migration scripts

## Risk Mitigation

- **Backward Compatibility**: New fields are optional; existing tasks continue to work
- **LLM Reliability**: Fall back to simple decomposition if effort estimation fails
- **Performance**: Cache dependency analysis results; recompute only on task changes
- **Template Maintenance**: Version templates and provide migration path for updates

---

Execution Information

Branch: main
Commit: 81fdeee

New Plan

Observations

The codebase has a solid foundation for task generation with LLM-powered decomposition (file:codeframe/planning/task_decomposer.py), hierarchical issue/task modeling, and DAG-based dependency resolution (file:codeframe/agents/dependency_resolver.py). The current system generates tasks from PRD content via file:codeframe/agents/lead_agent.py and stores them with basic dependency information. However, it lacks advanced features like effort estimation, critical path analysis, and intelligent scheduling that would enable predictable project execution.

Approach

The implementation will enhance the existing task generation pipeline by integrating AI-powered analysis at each stage: (1) extend TaskDecomposer to include effort estimation during LLM-based decomposition, (2) enhance DependencyResolver with critical path algorithms and scheduling capabilities, (3) create a template system for common task patterns, and (4) add new CLI commands for dependency visualization and conflict analysis. This approach builds incrementally on proven components while maintaining backward compatibility with existing task workflows.

Implementation Plan

Phase 1: Enhanced Task Decomposition with Effort Estimation

1.1 Extend TaskDecomposer for Effort Estimation

Modify file:codeframe/planning/task_decomposer.py:

• Enhance build_decomposition_prompt() method to request effort estimation
  • Add section requesting complexity (1-5 scale) for each task
  • Request time estimation (hours) based on task scope
  • Ask for resource requirements (skills, tools, dependencies)
  • Request uncertainty assessment (low/medium/high) for ambiguous tasks
• Enhance parse_claude_response() method to extract effort data
  • Parse complexity scores from Claude response
  • Extract estimated hours for each task
  • Parse resource requirements as JSON
  • Extract uncertainty levels
• Store estimates in new Task fields (see 1.2)
• Add fallback to default estimates if parsing fails
• Log estimation confidence for tracking accuracy over time

1.2 Update Task Model

Modify file:codeframe/core/models.py:

• Add new fields to Task dataclass:
  • estimated_hours: Optional[float] - Time estimate in hours
  • complexity_score: Optional[int] - Complexity rating (1-5)
  • uncertainty_level: Optional[str] - "low", "medium", "high"
  • resource_requirements: Optional[str] - JSON string of required skills/tools
• Update to_dict() method to include new fields

1.3 Database Schema Migration

Update database schema in file:codeframe/persistence/database.py:

• Add columns to tasks table: estimated_hours, complexity_score, uncertainty_level, resource_requirements
• Create migration script to add columns with default values
• Update file:codeframe/persistence/repositories/task_repository.py to handle new fields in _row_to_task() and create_task_with_issue()

Phase 2: Advanced Dependency Analysis

2.1 Enhance DependencyResolver with Critical Path Analysis

Extend file:codeframe/agents/dependency_resolver.py:

• Add calculate_critical_path(task_durations: Dict[int, float]) method using longest path algorithm
  • Accept task duration estimates (hours) as input
  • Compute earliest start/finish times for each task using forward pass
  • Compute latest start/finish times using backward pass
  • Identify tasks with zero slack (critical path)
  • Return CriticalPathResult with critical task IDs, total duration, and task timings
• Add identify_parallel_opportunities() method
  • Find tasks that can execute concurrently (no dependency conflicts)
  • Group tasks by dependency level for parallel execution waves
  • Return dict mapping execution wave (0, 1, 2...) to task IDs
  • Include wave duration estimates
• Add calculate_task_slack(task_durations: Dict[int, float]) method
  • Compute float/slack time for each task using critical path data
  • Return dict mapping task ID to slack hours
  • Tasks with zero slack are on critical path

2.2 Add Conflict Detection and Resolution

Extend file:codeframe/agents/dependency_resolver.py:

• Add detect_dependency_conflicts(task_durations: Dict[int, float]) method
  • Identify bottleneck tasks (many dependents, high impact on critical path)
  • Detect long dependency chains that risk delays (chain length > 5 tasks)
  • Find tasks with high complexity and many dependents (risk multipliers)
  • Return list of DependencyConflict objects with severity (critical/high/medium) and recommendations
  • Include impact analysis (how many tasks blocked, estimated delay)
• Add suggest_dependency_resolution(conflicts: List[DependencyConflict]) method
  • Propose task splitting for bottlenecks to increase parallelization
  • Suggest dependency reordering to reduce critical path length
  • Recommend prioritizing high-impact tasks
  • Return list of ResolutionSuggestion objects with expected improvements

2.3 Create Dependency Visualization Support

Create new file file:codeframe/planning/dependency_visualizer.py:

• Implement generate_dependency_graph(tasks, critical_path_ids, task_status) function
  • Accept list of tasks, critical path task IDs, and task status map
  • Generate Mermaid flowchart syntax for task DAG
  • Highlight critical path tasks in red/bold
  • Color-code tasks by status: pending (gray), in_progress (blue), completed (green), blocked (orange)
  • Include task complexity scores as node labels
  • Return Mermaid markdown string suitable for display/export
• Implement generate_gantt_chart(tasks, task_durations, critical_path_ids) function
  • Create Gantt chart representation with estimated durations
  • Show task dependencies and critical path highlighting
  • Include milestone markers for critical path completion
  • Return Mermaid Gantt syntax
• Implement export_graph_formats(graph_data) function
  • Support export to Mermaid, DOT (Graphviz), and JSON formats
  • Enable integration with external visualization tools

Phase 3: Intelligent Task Scheduling

3.1 Create Task Scheduler Component

Create new file file:codeframe/planning/task_scheduler.py:

• Implement TaskScheduler class with methods:
  • schedule_tasks(tasks, task_durations, agents_available) - Assign start times based on dependencies and resources
    • Use critical path method (CPM) for scheduling
    • Consider agent availability and skill matching from resource requirements
    • Return ScheduleResult with task assignments, start/end times, and timeline
  • optimize_schedule(schedule, constraints) - Use heuristics to minimize project duration
    • Identify parallelization opportunities
    • Suggest task reordering within slack windows
    • Return optimized schedule with estimated duration reduction
  • predict_completion_date(current_progress, schedule) - Estimate project end date based on current progress
    • Account for completed tasks and in-progress work
    • Apply historical velocity factors
    • Return predicted completion date with confidence interval
  • identify_bottlenecks(schedule, task_durations) - Find tasks/agents causing delays
    • Identify tasks on critical path with high duration
    • Find agents with overallocation
    • Return list of bottleneck items with impact analysis

3.2 Integrate Scheduler with LeadAgent

Modify file:codeframe/agents/lead_agent.py:

• Add schedule_project_tasks() method that calls TaskScheduler
• Update start_multi_agent_execution() to use scheduled task assignments
• Add scheduling metadata to task assignment broadcasts
• Store schedule in database for progress tracking

Phase 4: Task Template System

4.1 Create Template Framework

Create new file file:codeframe/planning/task_templates.py:

• Define TaskTemplate dataclass with fields:
  • name: str - Template identifier (e.g., "rest_api_endpoint")
  • category: str - "setup", "implementation", "testing", "deployment", "refactor"
  • keywords: List[str] - Keywords for automatic detection (e.g., ["API", "endpoint", "REST"])
  • task_pattern: List[Dict] - List of task definitions with placeholders
    • Each task has: title, description, complexity_score, estimated_hours
  • dependencies: List[Tuple[int, int]] - Dependency relationships between task indices
  • estimated_hours: Dict[int, float] - Time estimates per task
  • version: str - Template version for migration tracking
• Implement TemplateLibrary class:
  • load_templates() - Load built-in and custom templates from file:codeframe/planning/templates/
  • get_template(name) - Retrieve template by name
  • find_applicable_templates(issue_description) - Find templates matching issue keywords
  • apply_template(template, context) - Generate tasks from template with variable substitution
  • save_custom_template(template) - Persist user-defined templates to database
  • get_template_stats() - Return usage statistics for each template

4.2 Create Built-in Templates

Create template definitions in file:codeframe/planning/templates/:

• setup_template.json - Project initialization tasks
  • Initialize git repository, setup environment, install dependencies, configure tools
  • 4-5 sequential tasks, ~8-12 hours total
• rest_api_endpoint_template.json - REST API implementation pattern
  • Design schema, implement endpoint, add validation, write tests, document API
  • 5-6 tasks with some parallelization, ~12-16 hours total
• crud_template.json - CRUD operations for a model
  • Create model, implement create/read/update/delete operations, add tests
  • 4-5 sequential tasks, ~10-14 hours total
• testing_template.json - Test suite setup and implementation
  • Setup test framework, write unit tests, add integration tests, configure CI
  • 4-5 tasks with parallelization opportunities, ~8-12 hours total
• deployment_template.json - CI/CD and deployment tasks
  • Setup CI pipeline, configure deployment, add monitoring, document process
  • 4-5 sequential tasks, ~10-15 hours total
• refactor_template.json - Code refactoring pattern
  • Analyze code, plan refactoring, implement changes, test thoroughly, document
  • 5-6 tasks, ~12-18 hours total
• Each template includes task titles, descriptions, complexity scores, dependencies, and estimates

4.3 Integrate Templates with Task Generation

Modify file:codeframe/planning/task_decomposer.py:

• Add detect_template_applicability(issue: Issue) method
  • Analyze issue title and description for template keywords
  • Score each template based on keyword matches (0.0-1.0)
  • Return list of applicable templates sorted by confidence
  • Threshold: only return templates with confidence > 0.6
• Add apply_template_if_applicable(issue: Issue, templates: List[TaskTemplate]) method
  • Check if highest-confidence template exceeds confidence threshold (0.75)
  • Apply template with variable substitution (issue title, description, priority)
  • Preserve issue number and parent relationships
  • Return generated tasks or None if no suitable template
• Update decompose_issue() to try template matching first
  • Call detect_template_applicability() and apply_template_if_applicable()
  • Fall back to LLM decomposition if no suitable template (confidence < 0.75)
  • Log template usage for analytics
• Add _substitute_template_variables() helper method
  • Replace placeholders like {issue_title}, {issue_description} in task templates

Phase 5: Enhanced CLI Commands

5.1 Add Dependency Analysis Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add analyze command:

  @tasks_app.command("analyze")
  def analyze_dependencies(
      project_id: int,
      show_conflicts: bool = typer.Option(False, "--conflicts"),
      show_critical_path: bool = typer.Option(False, "--critical-path"),
      show_bottlenecks: bool = typer.Option(False, "--bottlenecks"),
      show_all: bool = typer.Option(False, "--all")
  )

  • Call new API endpoint GET /api/projects/{id}/tasks/analysis
  • Display dependency conflicts with severity and recommendations
  • Display critical path tasks with total duration
  • Display bottleneck tasks with impact analysis
  • Use rich tables with color coding: critical (red), high (orange), medium (yellow)
  • Show summary statistics (total tasks, critical path length, conflicts count)

5.2 Add Visualization Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add visualize-deps command:

  @tasks_app.command("visualize-deps")
  def visualize_dependencies(
      project_id: int,
      format: str = typer.Option("mermaid", "--format", "-f"),
      save_to: Optional[str] = typer.Option(None, "--output", "-o"),
      show_critical_path: bool = typer.Option(True, "--critical-path/--no-critical-path")
  )

  • Call API endpoint GET /api/projects/{id}/tasks/dependency-graph
  • Display Mermaid diagram in terminal or save to file
  • Support formats: mermaid (default), dot (Graphviz), json
  • Highlight critical path tasks in red when show_critical_path=True
  • Color-code tasks by status (pending/in_progress/completed/blocked)
  • If saving to file, auto-detect format from extension (.mmd, .dot, .json)

5.3 Add Scheduling Commands

Extend file:codeframe/cli/tasks_commands.py:

• Add suggest-order command:

  @tasks_app.command("suggest-order")
  def suggest_execution_order(
      project_id: int,
      optimize_for: str = typer.Option("duration", "--optimize", "-o"),
      show_timeline: bool = typer.Option(True, "--timeline/--no-timeline"),
      show_parallel: bool = typer.Option(True, "--parallel/--no-parallel")
  )

  • Call API endpoint GET /api/projects/{id}/tasks/suggested-order
  • Display optimal task execution order with task numbers and titles
  • Show estimated completion timeline with milestones
  • Highlight parallel execution opportunities (execution waves)
  • Display estimated total duration and critical path length
  • Show resource requirements for each task
  • Support optimization strategies: "duration" (minimize time), "resources" (balance load)

5.4 Add Task Generation Command

Extend file:codeframe/cli/tasks_commands.py:

• Add generate command:

  @tasks_app.command("generate")
  def generate_tasks(
      project_id: int,
      use_templates: bool = typer.Option(True, "--templates/--no-templates"),
      estimate_effort: bool = typer.Option(True, "--estimate/--no-estimate"),
      show_summary: bool = typer.Option(True, "--summary/--no-summary")
  )

  • Trigger task generation from PRD via POST /api/projects/{id}/tasks/generate
  • Apply templates when applicable (if use_templates=True)
  • Include effort estimation (if estimate_effort=True)
  • Display generated tasks with estimates, complexity scores, and dependencies
  • Show summary: total tasks, estimated duration, template usage, critical path length
  • Display any dependency conflicts or bottlenecks detected

Phase 6: API Endpoints

6.1 Create Task Analysis Router

Create new file file:codeframe/ui/routers/task_analysis.py:

• Implement endpoints:
  • GET /api/projects/{id}/tasks/analysis - Dependency analysis with conflicts and critical path
    • Returns: conflicts (list), critical_path (list of task IDs), bottlenecks (list), summary stats
  • GET /api/projects/{id}/tasks/dependency-graph - Mermaid/DOT graph representation
    • Query params: format (mermaid/dot/json), show_critical_path (bool)
    • Returns: graph data in requested format
  • GET /api/projects/{id}/tasks/suggested-order - Optimal execution order
    • Query params: optimize_for (duration/resources)
    • Returns: execution waves, timeline, estimated duration, parallel opportunities
  • GET /api/projects/{id}/tasks/critical-path - Critical path tasks and duration
    • Returns: critical task IDs, total duration, task timings (start/end)
  • GET /api/projects/{id}/tasks/schedule - Scheduled task timeline
    • Returns: task assignments, start/end times, resource allocation
  • POST /api/projects/{id}/tasks/generate - Trigger task generation with options
    • Request body: use_templates (bool), estimate_effort (bool)
    • Returns: generated tasks with estimates, conflicts, critical path

6.2 Update Existing Task Endpoints

Modify file:codeframe/ui/routers/tasks.py:

• Enhance GET /api/projects/{id}/tasks response to include:
  • estimated_hours, complexity_score, uncertainty_level, resource_requirements
  • is_critical_path boolean flag
  • slack_hours for non-critical tasks (null for critical path tasks)
  • parallel_group integer for tasks that can run concurrently (execution wave)
  • blocking_count - number of tasks blocked by this task
  • blocked_by_count - number of tasks blocking this task
• Add query parameters for filtering:
  • ?critical_path=true - Only critical path tasks
  • ?has_conflicts=true - Tasks with dependency conflicts
  • ?ready=true - Tasks ready to execute (dependencies satisfied)
  • ?parallel_group=N - Tasks in execution wave N
  • ?complexity=3 - Tasks with specific complexity score

Phase 7: Testing and Documentation

7.1 Unit Tests

Create test files:

• file:tests/planning/test_task_decomposer_effort.py - Test effort estimation parsing
  • Test parsing of complexity scores, hours, resource requirements from Claude response
  • Test fallback to defaults when parsing fails
  • Test uncertainty level assignment
• file:tests/agents/test_dependency_resolver_critical_path.py - Test critical path algorithms
  • Test critical path calculation with various task durations
  • Test slack calculation for non-critical tasks
  • Test parallel opportunity identification
  • Test conflict detection (bottlenecks, long chains)
• file:tests/planning/test_task_scheduler.py - Test scheduling logic
  • Test task scheduling with dependencies
  • Test schedule optimization
  • Test completion date prediction
  • Test bottleneck identification
• file:tests/planning/test_task_templates.py - Test template application
  • Test template loading and retrieval
  • Test template applicability detection
  • Test variable substitution in templates
  • Test custom template persistence
• file:tests/planning/test_dependency_visualizer.py - Test visualization generation
  • Test Mermaid diagram generation
  • Test Gantt chart generation
  • Test format exports (DOT, JSON)
• file:tests/cli/test_tasks_commands_enhanced.py - Test new CLI commands
  • Test analyze, visualize-deps, suggest-order, generate commands
  • Test output formatting and options
• file:tests/api/test_task_analysis_endpoints.py - Test analysis API endpoints
  • Test all new endpoints with various project states
  • Test filtering and query parameters

7.2 Integration Tests

Create integration test file file:tests/integration/test_task_generation_e2e.py:

• Test full flow: PRD → Issues → Tasks with effort estimation
  • Verify effort estimates are parsed and stored correctly
  • Validate complexity scores and uncertainty levels
• Verify dependency analysis and critical path calculation
  • Test with various dependency patterns
  • Validate critical path identification
  • Verify slack calculations
• Test template application for common patterns
  • Test REST API endpoint template
  • Test CRUD template
  • Test setup template
  • Verify template variable substitution
• Validate scheduling and conflict detection
  • Test schedule generation with dependencies
  • Verify bottleneck detection
  • Test conflict resolution suggestions
• Test end-to-end CLI workflow
  • Generate tasks from PRD
  • Analyze dependencies
  • Visualize dependency graph
  • Get suggested execution order

7.3 Documentation

Create/update documentation files:

• file:docs/TASK_GENERATION.md - Comprehensive guide to task generation features
  • Explain effort estimation process and accuracy expectations
  • Document complexity scoring system
  • Show examples of generated tasks with estimates
• file:docs/DEPENDENCY_ANALYSIS.md - Dependency analysis and critical path documentation
  • Explain critical path method (CPM) algorithm
  • Document conflict detection and resolution
  • Show examples of dependency graphs and analysis output
• file:docs/TASK_TEMPLATES.md - Template system usage and custom template creation
  • List built-in templates with examples
  • Explain template applicability detection
  • Guide for creating custom templates
  • Document template versioning and migration
• file:docs/TASK_SCHEDULING.md - Task scheduling and timeline prediction
  • Explain scheduling algorithm and constraints
  • Document parallel execution opportunities
  • Show timeline prediction examples
• Update file:docs/CLI_WIREFRAME.md with new commands
  • Add analyze, visualize-deps, suggest-order, generate commands
  • Show example outputs and options
• Update file:README.md with new features section
  • Highlight effort estimation, critical path analysis, templates
  • Link to detailed documentation

Phase 8: UI Integration (Optional Enhancement)

8.1 Dashboard Components

Create React components in file:web-ui/src/components/tasks/:

• TaskDependencyGraph.tsx - Interactive dependency visualization using Mermaid
• CriticalPathView.tsx - Highlight critical path tasks
• TaskScheduleTimeline.tsx - Gantt chart view of scheduled tasks
• TaskEffortEstimates.tsx - Display effort estimates and complexity scores
• DependencyConflicts.tsx - Show conflicts with resolution suggestions

8.2 API Integration

Update file:web-ui/src/lib/api.ts:

• Add API client methods for new endpoints
• Add TypeScript types for analysis responses
• Integrate with existing task management UI

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant API
    participant LeadAgent
    participant TaskDecomposer
    participant DependencyResolver
    participant TaskScheduler
    participant Database

    User->>CLI: codeframe tasks generate 1
    CLI->>API: POST /api/projects/1/tasks/generate
    API->>LeadAgent: generate_issues_from_prd()
    LeadAgent->>TaskDecomposer: decompose_issue(issue)
    TaskDecomposer->>TaskDecomposer: build_prompt_with_effort_estimation()
    TaskDecomposer->>Claude: Send enhanced prompt
    Claude-->>TaskDecomposer: Tasks with effort estimates
    TaskDecomposer->>TaskDecomposer: parse_effort_data()
    TaskDecomposer-->>LeadAgent: Tasks with estimates
    LeadAgent->>DependencyResolver: build_dependency_graph(tasks)
    DependencyResolver->>DependencyResolver: calculate_critical_path()
    DependencyResolver->>DependencyResolver: detect_conflicts()
    DependencyResolver-->>LeadAgent: Analysis results
    LeadAgent->>TaskScheduler: schedule_tasks(tasks, agents)
    TaskScheduler-->>LeadAgent: Scheduled timeline
    LeadAgent->>Database: save_tasks_with_metadata()
    Database-->>LeadAgent: Task IDs
    LeadAgent-->>API: Generation summary
    API-->>CLI: Success response
    CLI-->>User: Display tasks with estimates

Loading

Success Metrics

• Effort Estimation Accuracy: Track actual vs estimated hours for completed tasks, target ±25% accuracy after 10+ tasks
  • Monitor estimation confidence levels over time
  • Identify patterns in estimation errors (over/under estimation)
• Critical Path Identification: Verify critical path tasks are prioritized in agent assignment
  • Measure % of critical path tasks completed on schedule
  • Track impact of critical path awareness on project timeline
• Template Usage: Measure % of tasks generated from templates vs LLM decomposition
  • Target: 40%+ of tasks from templates after 20 issues
  • Track template accuracy vs LLM decomposition
• Dependency Conflict Detection: Count conflicts detected and resolved before execution
  • Track conflicts prevented through early detection
  • Measure impact on project delays
• Scheduling Optimization: Compare actual project duration vs predicted timeline
  • Target: Predictions within ±15% of actual duration
  • Track improvement over time as historical data accumulates
• CLI Adoption: Track usage of new analysis and visualization commands
  • Monitor command frequency and user satisfaction

Dependencies

• Existing file:codeframe/planning/task_decomposer.py for LLM integration
• Existing file:codeframe/agents/dependency_resolver.py for DAG operations
• Existing file:codeframe/agents/lead_agent.py for orchestration
• Anthropic Claude API for enhanced task decomposition prompts
• Database schema updates require migration scripts

Risk Mitigation

• Backward Compatibility: New fields are optional; existing tasks continue to work
  • Database migrations add columns with default values
  • API responses include new fields only when available
  • Existing task workflows unaffected
• LLM Reliability: Fall back to simple decomposition if effort estimation fails
  • Use default estimates when Claude parsing fails
  • Log estimation failures for monitoring
  • Provide manual override capability
• Performance: Cache dependency analysis results; recompute only on task changes
  • Cache critical path calculations
  • Invalidate cache on task creation/update/deletion
  • Monitor cache hit rates
• Template Maintenance: Version templates and provide migration path for updates
  • Track template versions in database
  • Provide migration scripts for template updates
  • Allow rollback to previous template versions
• Estimation Accuracy: Continuously improve estimates with historical data
  • Track estimation vs actual for all tasks
  • Adjust default estimates based on project history
  • Provide feedback loop for estimation refinement

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a solid foundation for task generation with LLM-powered decomposition (`file:codeframe/planning/task_decomposer.py`), hierarchical issue/task modeling, and DAG-based dependency resolution (`file:codeframe/agents/dependency_resolver.py`). The current system generates tasks from PRD content via `file:codeframe/agents/lead_agent.py` and stores them with basic dependency information. However, it lacks advanced features like effort estimation, critical path analysis, and intelligent scheduling that would enable predictable project execution.

## Approach

The implementation will enhance the existing task generation pipeline by integrating AI-powered analysis at each stage: (1) extend `TaskDecomposer` to include effort estimation during LLM-based decomposition, (2) enhance `DependencyResolver` with critical path algorithms and scheduling capabilities, (3) create a template system for common task patterns, and (4) add new CLI commands for dependency visualization and conflict analysis. This approach builds incrementally on proven components while maintaining backward compatibility with existing task workflows.

## Implementation Plan

### Phase 1: Enhanced Task Decomposition with Effort Estimation

**1.1 Extend TaskDecomposer for Effort Estimation**

Modify `file:codeframe/planning/task_decomposer.py`:
- Enhance `build_decomposition_prompt()` method to request effort estimation
  - Add section requesting complexity (1-5 scale) for each task
  - Request time estimation (hours) based on task scope
  - Ask for resource requirements (skills, tools, dependencies)
  - Request uncertainty assessment (low/medium/high) for ambiguous tasks
- Enhance `parse_claude_response()` method to extract effort data
  - Parse complexity scores from Claude response
  - Extract estimated hours for each task
  - Parse resource requirements as JSON
  - Extract uncertainty levels
- Store estimates in new Task fields (see 1.2)
- Add fallback to default estimates if parsing fails
- Log estimation confidence for tracking accuracy over time

**1.2 Update Task Model**

Modify `file:codeframe/core/models.py`:
- Add new fields to `Task` dataclass:
  - `estimated_hours: Optional[float]` - Time estimate in hours
  - `complexity_score: Optional[int]` - Complexity rating (1-5)
  - `uncertainty_level: Optional[str]` - "low", "medium", "high"
  - `resource_requirements: Optional[str]` - JSON string of required skills/tools
- Update `to_dict()` method to include new fields

**1.3 Database Schema Migration**

Update database schema in `file:codeframe/persistence/database.py`:
- Add columns to `tasks` table: `estimated_hours`, `complexity_score`, `uncertainty_level`, `resource_requirements`
- Create migration script to add columns with default values
- Update `file:codeframe/persistence/repositories/task_repository.py` to handle new fields in `_row_to_task()` and `create_task_with_issue()`

### Phase 2: Advanced Dependency Analysis

**2.1 Enhance DependencyResolver with Critical Path Analysis**

Extend `file:codeframe/agents/dependency_resolver.py`:
- Add `calculate_critical_path(task_durations: Dict[int, float])` method using longest path algorithm
  - Accept task duration estimates (hours) as input
  - Compute earliest start/finish times for each task using forward pass
  - Compute latest start/finish times using backward pass
  - Identify tasks with zero slack (critical path)
  - Return `CriticalPathResult` with critical task IDs, total duration, and task timings
- Add `identify_parallel_opportunities()` method
  - Find tasks that can execute concurrently (no dependency conflicts)
  - Group tasks by dependency level for parallel execution waves
  - Return dict mapping execution wave (0, 1, 2...) to task IDs
  - Include wave duration estimates
- Add `calculate_task_slack(task_durations: Dict[int, float])` method
  - Compute float/slack time for each task using critical path data
  - Return dict mapping task ID to slack hours
  - Tasks with zero slack are on critical path

**2.2 Add Conflict Detection and Resolution**

Extend `file:codeframe/agents/dependency_resolver.py`:
- Add `detect_dependency_conflicts(task_durations: Dict[int, float])` method
  - Identify bottleneck tasks (many dependents, high impact on critical path)
  - Detect long dependency chains that risk delays (chain length > 5 tasks)
  - Find tasks with high complexity and many dependents (risk multipliers)
  - Return list of `DependencyConflict` objects with severity (critical/high/medium) and recommendations
  - Include impact analysis (how many tasks blocked, estimated delay)
- Add `suggest_dependency_resolution(conflicts: List[DependencyConflict])` method
  - Propose task splitting for bottlenecks to increase parallelization
  - Suggest dependency reordering to reduce critical path length
  - Recommend prioritizing high-impact tasks
  - Return list of `ResolutionSuggestion` objects with expected improvements

**2.3 Create Dependency Visualization Support**

Create new file `file:codeframe/planning/dependency_visualizer.py`:
- Implement `generate_dependency_graph(tasks, critical_path_ids, task_status)` function
  - Accept list of tasks, critical path task IDs, and task status map
  - Generate Mermaid flowchart syntax for task DAG
  - Highlight critical path tasks in red/bold
  - Color-code tasks by status: pending (gray), in_progress (blue), completed (green), blocked (orange)
  - Include task complexity scores as node labels
  - Return Mermaid markdown string suitable for display/export
- Implement `generate_gantt_chart(tasks, task_durations, critical_path_ids)` function
  - Create Gantt chart representation with estimated durations
  - Show task dependencies and critical path highlighting
  - Include milestone markers for critical path completion
  - Return Mermaid Gantt syntax
- Implement `export_graph_formats(graph_data)` function
  - Support export to Mermaid, DOT (Graphviz), and JSON formats
  - Enable integration with external visualization tools

### Phase 3: Intelligent Task Scheduling

**3.1 Create Task Scheduler Component**

Create new file `file:codeframe/planning/task_scheduler.py`:
- Implement `TaskScheduler` class with methods:
  - `schedule_tasks(tasks, task_durations, agents_available)` - Assign start times based on dependencies and resources
    - Use critical path method (CPM) for scheduling
    - Consider agent availability and skill matching from resource requirements
    - Return `ScheduleResult` with task assignments, start/end times, and timeline
  - `optimize_schedule(schedule, constraints)` - Use heuristics to minimize project duration
    - Identify parallelization opportunities
    - Suggest task reordering within slack windows
    - Return optimized schedule with estimated duration reduction
  - `predict_completion_date(current_progress, schedule)` - Estimate project end date based on current progress
    - Account for completed tasks and in-progress work
    - Apply historical velocity factors
    - Return predicted completion date with confidence interval
  - `identify_bottlenecks(schedule, task_durations)` - Find tasks/agents causing delays
    - Identify tasks on critical path with high duration
    - Find agents with overallocation
    - Return list of bottleneck items with impact analysis

**3.2 Integrate Scheduler with LeadAgent**

Modify `file:codeframe/agents/lead_agent.py`:
- Add `schedule_project_tasks()` method that calls `TaskScheduler`
- Update `start_multi_agent_execution()` to use scheduled task assignments
- Add scheduling metadata to task assignment broadcasts
- Store schedule in database for progress tracking

### Phase 4: Task Template System

**4.1 Create Template Framework**

Create new file `file:codeframe/planning/task_templates.py`:
- Define `TaskTemplate` dataclass with fields:
  - `name: str` - Template identifier (e.g., "rest_api_endpoint")
  - `category: str` - "setup", "implementation", "testing", "deployment", "refactor"
  - `keywords: List[str]` - Keywords for automatic detection (e.g., ["API", "endpoint", "REST"])
  - `task_pattern: List[Dict]` - List of task definitions with placeholders
    - Each task has: title, description, complexity_score, estimated_hours
  - `dependencies: List[Tuple[int, int]]` - Dependency relationships between task indices
  - `estimated_hours: Dict[int, float]` - Time estimates per task
  - `version: str` - Template version for migration tracking
- Implement `TemplateLibrary` class:
  - `load_templates()` - Load built-in and custom templates from `file:codeframe/planning/templates/`
  - `get_template(name)` - Retrieve template by name
  - `find_applicable_templates(issue_description)` - Find templates matching issue keywords
  - `apply_template(template, context)` - Generate tasks from template with variable substitution
  - `save_custom_template(template)` - Persist user-defined templates to database
  - `get_template_stats()` - Return usage statistics for each template

**4.2 Create Built-in Templates**

Create template definitions in `file:codeframe/planning/templates/`:
- `setup_template.json` - Project initialization tasks
  - Initialize git repository, setup environment, install dependencies, configure tools
  - 4-5 sequential tasks, ~8-12 hours total
- `rest_api_endpoint_template.json` - REST API implementation pattern
  - Design schema, implement endpoint, add validation, write tests, document API
  - 5-6 tasks with some parallelization, ~12-16 hours total
- `crud_template.json` - CRUD operations for a model
  - Create model, implement create/read/update/delete operations, add tests
  - 4-5 sequential tasks, ~10-14 hours total
- `testing_template.json` - Test suite setup and implementation
  - Setup test framework, write unit tests, add integration tests, configure CI
  - 4-5 tasks with parallelization opportunities, ~8-12 hours total
- `deployment_template.json` - CI/CD and deployment tasks
  - Setup CI pipeline, configure deployment, add monitoring, document process
  - 4-5 sequential tasks, ~10-15 hours total
- `refactor_template.json` - Code refactoring pattern
  - Analyze code, plan refactoring, implement changes, test thoroughly, document
  - 5-6 tasks, ~12-18 hours total
- Each template includes task titles, descriptions, complexity scores, dependencies, and estimates

**4.3 Integrate Templates with Task Generation**

Modify `file:codeframe/planning/task_decomposer.py`:
- Add `detect_template_applicability(issue: Issue)` method
  - Analyze issue title and description for template keywords
  - Score each template based on keyword matches (0.0-1.0)
  - Return list of applicable templates sorted by confidence
  - Threshold: only return templates with confidence > 0.6
- Add `apply_template_if_applicable(issue: Issue, templates: List[TaskTemplate])` method
  - Check if highest-confidence template exceeds confidence threshold (0.75)
  - Apply template with variable substitution (issue title, description, priority)
  - Preserve issue number and parent relationships
  - Return generated tasks or None if no suitable template
- Update `decompose_issue()` to try template matching first
  - Call `detect_template_applicability()` and `apply_template_if_applicable()`
  - Fall back to LLM decomposition if no suitable template (confidence < 0.75)
  - Log template usage for analytics
- Add `_substitute_template_variables()` helper method
  - Replace placeholders like {issue_title}, {issue_description} in task templates

### Phase 5: Enhanced CLI Commands

**5.1 Add Dependency Analysis Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `analyze` command:
  ```python
  @tasks_app.command("analyze")
  def analyze_dependencies(
      project_id: int,
      show_conflicts: bool = typer.Option(False, "--conflicts"),
      show_critical_path: bool = typer.Option(False, "--critical-path"),
      show_bottlenecks: bool = typer.Option(False, "--bottlenecks"),
      show_all: bool = typer.Option(False, "--all")
  )
  ```
  - Call new API endpoint `GET /api/projects/{id}/tasks/analysis`
  - Display dependency conflicts with severity and recommendations
  - Display critical path tasks with total duration
  - Display bottleneck tasks with impact analysis
  - Use rich tables with color coding: critical (red), high (orange), medium (yellow)
  - Show summary statistics (total tasks, critical path length, conflicts count)

**5.2 Add Visualization Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `visualize-deps` command:
  ```python
  @tasks_app.command("visualize-deps")
  def visualize_dependencies(
      project_id: int,
      format: str = typer.Option("mermaid", "--format", "-f"),
      save_to: Optional[str] = typer.Option(None, "--output", "-o"),
      show_critical_path: bool = typer.Option(True, "--critical-path/--no-critical-path")
  )
  ```
  - Call API endpoint `GET /api/projects/{id}/tasks/dependency-graph`
  - Display Mermaid diagram in terminal or save to file
  - Support formats: mermaid (default), dot (Graphviz), json
  - Highlight critical path tasks in red when `show_critical_path=True`
  - Color-code tasks by status (pending/in_progress/completed/blocked)
  - If saving to file, auto-detect format from extension (.mmd, .dot, .json)

**5.3 Add Scheduling Commands**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `suggest-order` command:
  ```python
  @tasks_app.command("suggest-order")
  def suggest_execution_order(
      project_id: int,
      optimize_for: str = typer.Option("duration", "--optimize", "-o"),
      show_timeline: bool = typer.Option(True, "--timeline/--no-timeline"),
      show_parallel: bool = typer.Option(True, "--parallel/--no-parallel")
  )
  ```
  - Call API endpoint `GET /api/projects/{id}/tasks/suggested-order`
  - Display optimal task execution order with task numbers and titles
  - Show estimated completion timeline with milestones
  - Highlight parallel execution opportunities (execution waves)
  - Display estimated total duration and critical path length
  - Show resource requirements for each task
  - Support optimization strategies: "duration" (minimize time), "resources" (balance load)

**5.4 Add Task Generation Command**

Extend `file:codeframe/cli/tasks_commands.py`:
- Add `generate` command:
  ```python
  @tasks_app.command("generate")
  def generate_tasks(
      project_id: int,
      use_templates: bool = typer.Option(True, "--templates/--no-templates"),
      estimate_effort: bool = typer.Option(True, "--estimate/--no-estimate"),
      show_summary: bool = typer.Option(True, "--summary/--no-summary")
  )
  ```
  - Trigger task generation from PRD via `POST /api/projects/{id}/tasks/generate`
  - Apply templates when applicable (if `use_templates=True`)
  - Include effort estimation (if `estimate_effort=True`)
  - Display generated tasks with estimates, complexity scores, and dependencies
  - Show summary: total tasks, estimated duration, template usage, critical path length
  - Display any dependency conflicts or bottlenecks detected

### Phase 6: API Endpoints

**6.1 Create Task Analysis Router**

Create new file `file:codeframe/ui/routers/task_analysis.py`:
- Implement endpoints:
  - `GET /api/projects/{id}/tasks/analysis` - Dependency analysis with conflicts and critical path
    - Returns: conflicts (list), critical_path (list of task IDs), bottlenecks (list), summary stats
  - `GET /api/projects/{id}/tasks/dependency-graph` - Mermaid/DOT graph representation
    - Query params: `format` (mermaid/dot/json), `show_critical_path` (bool)
    - Returns: graph data in requested format
  - `GET /api/projects/{id}/tasks/suggested-order` - Optimal execution order
    - Query params: `optimize_for` (duration/resources)
    - Returns: execution waves, timeline, estimated duration, parallel opportunities
  - `GET /api/projects/{id}/tasks/critical-path` - Critical path tasks and duration
    - Returns: critical task IDs, total duration, task timings (start/end)
  - `GET /api/projects/{id}/tasks/schedule` - Scheduled task timeline
    - Returns: task assignments, start/end times, resource allocation
  - `POST /api/projects/{id}/tasks/generate` - Trigger task generation with options
    - Request body: `use_templates` (bool), `estimate_effort` (bool)
    - Returns: generated tasks with estimates, conflicts, critical path

**6.2 Update Existing Task Endpoints**

Modify `file:codeframe/ui/routers/tasks.py`:
- Enhance `GET /api/projects/{id}/tasks` response to include:
  - `estimated_hours`, `complexity_score`, `uncertainty_level`, `resource_requirements`
  - `is_critical_path` boolean flag
  - `slack_hours` for non-critical tasks (null for critical path tasks)
  - `parallel_group` integer for tasks that can run concurrently (execution wave)
  - `blocking_count` - number of tasks blocked by this task
  - `blocked_by_count` - number of tasks blocking this task
- Add query parameters for filtering:
  - `?critical_path=true` - Only critical path tasks
  - `?has_conflicts=true` - Tasks with dependency conflicts
  - `?ready=true` - Tasks ready to execute (dependencies satisfied)
  - `?parallel_group=N` - Tasks in execution wave N
  - `?complexity=3` - Tasks with specific complexity score

### Phase 7: Testing and Documentation

**7.1 Unit Tests**

Create test files:
- `file:tests/planning/test_task_decomposer_effort.py` - Test effort estimation parsing
  - Test parsing of complexity scores, hours, resource requirements from Claude response
  - Test fallback to defaults when parsing fails
  - Test uncertainty level assignment
- `file:tests/agents/test_dependency_resolver_critical_path.py` - Test critical path algorithms
  - Test critical path calculation with various task durations
  - Test slack calculation for non-critical tasks
  - Test parallel opportunity identification
  - Test conflict detection (bottlenecks, long chains)
- `file:tests/planning/test_task_scheduler.py` - Test scheduling logic
  - Test task scheduling with dependencies
  - Test schedule optimization
  - Test completion date prediction
  - Test bottleneck identification
- `file:tests/planning/test_task_templates.py` - Test template application
  - Test template loading and retrieval
  - Test template applicability detection
  - Test variable substitution in templates
  - Test custom template persistence
- `file:tests/planning/test_dependency_visualizer.py` - Test visualization generation
  - Test Mermaid diagram generation
  - Test Gantt chart generation
  - Test format exports (DOT, JSON)
- `file:tests/cli/test_tasks_commands_enhanced.py` - Test new CLI commands
  - Test analyze, visualize-deps, suggest-order, generate commands
  - Test output formatting and options
- `file:tests/api/test_task_analysis_endpoints.py` - Test analysis API endpoints
  - Test all new endpoints with various project states
  - Test filtering and query parameters

**7.2 Integration Tests**

Create integration test file `file:tests/integration/test_task_generation_e2e.py`:
- Test full flow: PRD → Issues → Tasks with effort estimation
  - Verify effort estimates are parsed and stored correctly
  - Validate complexity scores and uncertainty levels
- Verify dependency analysis and critical path calculation
  - Test with various dependency patterns
  - Validate critical path identification
  - Verify slack calculations
- Test template application for common patterns
  - Test REST API endpoint template
  - Test CRUD template
  - Test setup template
  - Verify template variable substitution
- Validate scheduling and conflict detection
  - Test schedule generation with dependencies
  - Verify bottleneck detection
  - Test conflict resolution suggestions
- Test end-to-end CLI workflow
  - Generate tasks from PRD
  - Analyze dependencies
  - Visualize dependency graph
  - Get suggested execution order

**7.3 Documentation**

Create/update documentation files:
- `file:docs/TASK_GENERATION.md` - Comprehensive guide to task generation features
  - Explain effort estimation process and accuracy expectations
  - Document complexity scoring system
  - Show examples of generated tasks with estimates
- `file:docs/DEPENDENCY_ANALYSIS.md` - Dependency analysis and critical path documentation
  - Explain critical path method (CPM) algorithm
  - Document conflict detection and resolution
  - Show examples of dependency graphs and analysis output
- `file:docs/TASK_TEMPLATES.md` - Template system usage and custom template creation
  - List built-in templates with examples
  - Explain template applicability detection
  - Guide for creating custom templates
  - Document template versioning and migration
- `file:docs/TASK_SCHEDULING.md` - Task scheduling and timeline prediction
  - Explain scheduling algorithm and constraints
  - Document parallel execution opportunities
  - Show timeline prediction examples
- Update `file:docs/CLI_WIREFRAME.md` with new commands
  - Add `analyze`, `visualize-deps`, `suggest-order`, `generate` commands
  - Show example outputs and options
- Update `file:README.md` with new features section
  - Highlight effort estimation, critical path analysis, templates
  - Link to detailed documentation

### Phase 8: UI Integration (Optional Enhancement)

**8.1 Dashboard Components**

Create React components in `file:web-ui/src/components/tasks/`:
- `TaskDependencyGraph.tsx` - Interactive dependency visualization using Mermaid
- `CriticalPathView.tsx` - Highlight critical path tasks
- `TaskScheduleTimeline.tsx` - Gantt chart view of scheduled tasks
- `TaskEffortEstimates.tsx` - Display effort estimates and complexity scores
- `DependencyConflicts.tsx` - Show conflicts with resolution suggestions

**8.2 API Integration**

Update `file:web-ui/src/lib/api.ts`:
- Add API client methods for new endpoints
- Add TypeScript types for analysis responses
- Integrate with existing task management UI

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant API
    participant LeadAgent
    participant TaskDecomposer
    participant DependencyResolver
    participant TaskScheduler
    participant Database

    User->>CLI: codeframe tasks generate 1
    CLI->>API: POST /api/projects/1/tasks/generate
    API->>LeadAgent: generate_issues_from_prd()
    LeadAgent->>TaskDecomposer: decompose_issue(issue)
    TaskDecomposer->>TaskDecomposer: build_prompt_with_effort_estimation()
    TaskDecomposer->>Claude: Send enhanced prompt
    Claude-->>TaskDecomposer: Tasks with effort estimates
    TaskDecomposer->>TaskDecomposer: parse_effort_data()
    TaskDecomposer-->>LeadAgent: Tasks with estimates
    LeadAgent->>DependencyResolver: build_dependency_graph(tasks)
    DependencyResolver->>DependencyResolver: calculate_critical_path()
    DependencyResolver->>DependencyResolver: detect_conflicts()
    DependencyResolver-->>LeadAgent: Analysis results
    LeadAgent->>TaskScheduler: schedule_tasks(tasks, agents)
    TaskScheduler-->>LeadAgent: Scheduled timeline
    LeadAgent->>Database: save_tasks_with_metadata()
    Database-->>LeadAgent: Task IDs
    LeadAgent-->>API: Generation summary
    API-->>CLI: Success response
    CLI-->>User: Display tasks with estimates
```

## Success Metrics

- **Effort Estimation Accuracy**: Track actual vs estimated hours for completed tasks, target ±25% accuracy after 10+ tasks
  - Monitor estimation confidence levels over time
  - Identify patterns in estimation errors (over/under estimation)
- **Critical Path Identification**: Verify critical path tasks are prioritized in agent assignment
  - Measure % of critical path tasks completed on schedule
  - Track impact of critical path awareness on project timeline
- **Template Usage**: Measure % of tasks generated from templates vs LLM decomposition
  - Target: 40%+ of tasks from templates after 20 issues
  - Track template accuracy vs LLM decomposition
- **Dependency Conflict Detection**: Count conflicts detected and resolved before execution
  - Track conflicts prevented through early detection
  - Measure impact on project delays
- **Scheduling Optimization**: Compare actual project duration vs predicted timeline
  - Target: Predictions within ±15% of actual duration
  - Track improvement over time as historical data accumulates
- **CLI Adoption**: Track usage of new analysis and visualization commands
  - Monitor command frequency and user satisfaction

## Dependencies

- Existing `file:codeframe/planning/task_decomposer.py` for LLM integration
- Existing `file:codeframe/agents/dependency_resolver.py` for DAG operations
- Existing `file:codeframe/agents/lead_agent.py` for orchestration
- Anthropic Claude API for enhanced task decomposition prompts
- Database schema updates require migration scripts

## Risk Mitigation

- **Backward Compatibility**: New fields are optional; existing tasks continue to work
  - Database migrations add columns with default values
  - API responses include new fields only when available
  - Existing task workflows unaffected
- **LLM Reliability**: Fall back to simple decomposition if effort estimation fails
  - Use default estimates when Claude parsing fails
  - Log estimation failures for monitoring
  - Provide manual override capability
- **Performance**: Cache dependency analysis results; recompute only on task changes
  - Cache critical path calculations
  - Invalidate cache on task creation/update/deletion
  - Monitor cache hit rates
- **Template Maintenance**: Version templates and provide migration path for updates
  - Track template versions in database
  - Provide migration scripts for template updates
  - Allow rollback to previous template versions
- **Estimation Accuracy**: Continuously improve estimates with historical data
  - Track estimation vs actual for all tasks
  - Adjust default estimates based on project history
  - Provide feedback loop for estimation refinement

---

Execution Information

Branch: main
Commit: 81fdeee