Modality

Appearance

Roadmap Block ​

The roadmap block configures project-level settings for roadmapping and task planning. This block defines team capacity, timeline parameters, and project planning constraints.

Purpose ​

The roadmap block helps you:

  • Set project timeline and start date
  • Define team capacity and resources
  • Configure working hours
  • Establish planning parameters

Syntax ​

mml
roadmap {
  start_date = "YYYY-MM-DD"
  team_size = N
  hours_per_day = N
}

Attributes ​

Required Attributes ​

None - all attributes are optional with sensible defaults.

Optional Attributes ​

start_date ​

The project start date for roadmap planning.

  • Type: String (date)
  • Required: No
  • Format: "YYYY-MM-DD"
  • Default: Current date
mml
roadmap {
  start_date = "2025-01-01"
}

team_size ​

Number of team members available for the project.

  • Type: Number
  • Required: No
  • Default: 1
mml
roadmap {
  team_size = 5
}

hours_per_day ​

Available working hours per team member per day.

  • Type: Number
  • Required: No
  • Default: 8
  • Common values: 4-8 hours
mml
roadmap {
  hours_per_day = 6
}

Examples ​

Basic Roadmap ​

mml
roadmap {
  start_date = "2025-01-01"
  team_size = 3
  hours_per_day = 6
}

Small Team ​

mml
roadmap {
  start_date = "2025-02-01"
  team_size = 2
  hours_per_day = 8
}

Part-Time Team ​

mml
roadmap {
  start_date = "2025-01-15"
  team_size = 4
  hours_per_day = 4  # Half days
}

Integration with Tasks ​

The roadmap configuration works with task blocks to calculate:

  • Start and end dates for each task
  • Resource allocation
  • Timeline dependencies
  • Project completion estimates

Example with tasks:

mml
roadmap {
  start_date = "2025-01-01"
  team_size = 3
  hours_per_day = 6
}

task "Build Customer Table" {
  builds "Sales.Customer"
  assignee = "alice"
  status = "pending"
}

task "Build Order Table" {
  builds "Sales.Order"
  depends_on "Build Customer Table"
  assignee = "bob"
  status = "pending"
}

task "Customer Dashboard" {
  builds "Sales_Analytics.Customer_Overview"
  depends_on "Build Customer Table"
  depends_on "Build Order Table"
  assignee = "charlie"
  status = "pending"
}

Capacity Calculation ​

The roadmap block enables automatic capacity calculations:

Total Daily Capacity:

daily_capacity = team_size × hours_per_day

Example:

mml
roadmap {
  team_size = 3      # 3 people
  hours_per_day = 6  # 6 hours each
}
# Total = 3 × 6 = 18 hours per day

Weekly Capacity:

weekly_capacity = daily_capacity × 5  # 5 working days

Use Cases ​

1. Sprint Planning ​

mml
roadmap {
  start_date = "2025-01-06"  # Monday
  team_size = 5
  hours_per_day = 6  # 6 productive hours
}

task "Sprint 1 - Core Entities" {
  builds "Platform.User"
  builds "Platform.Account"
  manual_hours = 120  # 2 weeks
}

task "Sprint 2 - Data Products" {
  builds "SaaS_Metrics"
  depends_on "Sprint 1 - Core Entities"
  manual_hours = 120
}

2. Phased Rollout ​

mml
roadmap {
  start_date = "2025-02-01"
  team_size = 8
  hours_per_day = 7
}

task "Phase 1 - Foundation" {
  builds "Customer.Customer"
  builds "Sales.Order"
  manual_hours = 200
}

task "Phase 2 - Analytics" {
  builds "Customer_Analytics"
  depends_on "Phase 1 - Foundation"
  manual_hours = 150
}

task "Phase 3 - Advanced Features" {
  builds "Product_Recommendations"
  depends_on "Phase 2 - Analytics"
  manual_hours = 180
}

3. Resource Constrained ​

mml
roadmap {
  start_date = "2025-01-15"
  team_size = 2  # Small team
  hours_per_day = 4  # Part-time
}

task "MVP - Essential Entities" {
  builds "Platform.User"
  builds "Platform.Subscription"
  manual_hours = 80
  notes = "Focus on core functionality only"
}

Best Practices ​

  1. Be realistic with hours per day

    mml
    # Unrealistic - assumes 100% coding time
roadmap {
  hours_per_day = 8
}

# Realistic - accounts for meetings, interruptions
roadmap {
  hours_per_day = 6
}

  2. Account for team availability

    mml
    # If you have 5 people but 2 are part-time
roadmap {
  team_size = 3  # Full-time equivalents
  hours_per_day = 6
}

  3. Start dates should be Mondays

    mml
    # Good - starts on a Monday
roadmap {
  start_date = "2025-01-06"
}

# Avoid - mid-week starts complicate planning
roadmap {
  start_date = "2025-01-08"  # Wednesday
}

  4. Update as team changes

    mml
    # Before - solo developer
roadmap {
  start_date = "2025-01-01"
  team_size = 1
  hours_per_day = 8
}

# After - team grows
roadmap {
  start_date = "2025-02-01"
  team_size = 3
  hours_per_day = 6
}

  5. Document assumptions

    mml
    roadmap {
  start_date = "2025-01-01"
  team_size = 5
  hours_per_day = 6
  # Assumes:
  # - 2 senior, 3 mid-level engineers
  # - 6 productive hours (2 hours for meetings, etc.)
  # - No major holidays in timeline
}

Complete Example ​

mml
# Roadmap configuration
roadmap {
  start_date = "2025-01-06"
  team_size = 4
  hours_per_day = 6
}

# Domains
domain "Sales" {
  entity "Customer" { ... }
  entity "Order" { ... }
}

# Entity estimates
entity_estimate "Sales.Customer" {
  estimated_hours = 80
  complexity = "medium"
}

entity_estimate "Sales.Order" {
  estimated_hours = 60
  complexity = "low"
}

# Tasks
task "Customer Entity" {
  builds "Sales.Customer"
  assignee = "alice"
  status = "in-progress"
  # Duration: ~2.7 weeks (80 hours ÷ (4 people × 6 hours/day))
}

task "Order Entity" {
  builds "Sales.Order"
  depends_on "Customer Entity"
  assignee = "bob"
  status = "pending"
  # Duration: ~2 weeks (60 hours ÷ (4 people × 6 hours/day))
}

task "Sales Dashboard" {
  builds "Sales_Analytics.Revenue_Dashboard"
  depends_on "Customer Entity"
  depends_on "Order Entity"
  assignee = "charlie"
  status = "pending"
  manual_hours = 40
}

Viewing the Roadmap ​

In the Modality app, the roadmap view shows:

  • Timeline with task bars
  • Dependencies between tasks
  • Resource allocation
  • Team assignments
  • Progress tracking

Limitations ​

  • Assumes uniform team productivity
  • Does not account for holidays/vacations
  • Simple linear task scheduling
  • No parallel task optimization

For more accurate planning, consider:

  • Adding buffer time to estimates
  • Using conservative hours per day
  • Regular progress updates
  • Adjusting team size as needed

Released under the MIT License.

Copyright © 2025 Modality