Skip to Content
Core FeaturesUnderstanding YAML Structure

Understanding YAML Project Structure

Farline uses YAML to define projects. This article explains the structure and all available fields.

Basic Project Structure

name: My Project
unit: story points
scenarios:
  - name: Baseline
    workstreams:
      - name: Frontend Team
        capacity: 10
        work_items:
          - id: ui-design
            name: UI Design
            size: 20
          - id: components
            name: Build Components
            size: 30
            dependencies: [ui-design]

YAML Structure Diagram

Here’s a visual representation of how Farline’s YAML structure is organized:

YAML Structure Diagram

This diagram shows the hierarchy: Project → Scenarios → Workstreams → Work Items, with Milestones at the scenario level.

Project-Level Fields

name (required)

The name of your project.

name: Website Redesign

unit (required)

The unit of measurement for capacity and work item sizes. Common values:

  • story points
  • engineer-days
  • hours
  • sprints
unit: story points

Scenarios

Each project can have multiple scenarios to model different planning options.

name (required)

The scenario name. Common scenarios:

  • Baseline - Your current plan
  • Optimistic - Best case scenario
  • Pessimistic - Worst case scenario
  • Fast Track - With additional resources
scenarios:
  - name: Baseline
    workstreams: [...]
  - name: Fast Track
    workstreams: [...]

Workstreams

Workstreams represent teams or tracks of work.

name (required)

The workstream name.

- name: Frontend Team

capacity (required)

How many units of work this workstream can complete per week.

capacity: 10  # 10 story points per week

start_delay (optional)

Delay the start of this workstream by a number of weeks.

start_delay: 2  # Start 2 weeks into the project

cost_per_week (optional)

The weekly cost of this workstream in dollars.

cost_per_week: 15000  # $15k per week

Work Items

Work items are the individual pieces of work to be completed.

id (required)

Unique identifier for the work item. Used in dependencies.

- id: backend-api

name (required)

Display name for the work item.

name: Build Backend API

size (required)

How many units of work this item requires (in your project’s unit).

size: 25  # 25 story points

dependencies (optional)

Array of work item IDs that must complete before this item can start.

dependencies: [ui-design, backend-api]

sequence (optional)

Controls the order work items start. Lower numbers start first. Items with the same sequence can run in parallel.

sequence: 1  # Start in the first batch

delay (optional)

Add a fixed delay (in weeks) before this work item starts.

delay: 2  # Wait 2 weeks before starting

Milestones

Milestones represent key dates that depend on work items.

id (required)

Unique identifier for the milestone.

- id: beta-release

name (required)

Display name for the milestone.

name: Beta Release

dependencies (required)

Array of work item IDs that must complete before this milestone is reached.

dependencies: [testing, documentation]

Complete Example

name: Mobile App Launch
unit: story points
 
scenarios:
  - name: Baseline
    workstreams:
      - name: iOS Team
        capacity: 12
        cost_per_week: 18000
        work_items:
          - id: ios-auth
            name: Authentication
            size: 15
            sequence: 1
 
          - id: ios-core
            name: Core Features
            size: 40
            sequence: 2
            dependencies: [ios-auth]
 
          - id: ios-polish
            name: Polish & QA
            size: 20
            sequence: 3
            dependencies: [ios-core]
 
      - name: Backend Team
        capacity: 8
        cost_per_week: 12000
        work_items:
          - id: api-setup
            name: API Infrastructure
            size: 10
            sequence: 1
 
          - id: api-endpoints
            name: API Endpoints
            size: 25
            sequence: 2
            dependencies: [api-setup]
 
          - id: api-testing
            name: API Testing
            size: 15
            sequence: 3
            dependencies: [api-endpoints]
 
    milestones:
      - id: alpha
        name: Alpha Release
        dependencies: [ios-core, api-endpoints]
 
      - id: launch
        name: Public Launch
        dependencies: [ios-polish, api-testing]

Tips for Writing YAML

  1. Indentation matters - YAML uses 2 spaces per level (not tabs)
  2. Use quotes sparingly - Only needed for special characters or numbers as strings
  3. Test incrementally - Build your YAML step by step
  4. Use the AI - The AI chat can generate YAML for you if you describe what you want
  5. Dependencies are powerful - Use them to model realistic project constraints

Common Patterns

Parallel Workstreams

Multiple teams working simultaneously:

workstreams:
  - name: Team A
    capacity: 10
    work_items: [...]
 
  - name: Team B
    capacity: 10
    work_items: [...]

Sequential Phases

Work items that must happen in order:

work_items:
  - id: phase1
    name: Phase 1
    size: 20
    sequence: 1
 
  - id: phase2
    name: Phase 2
    size: 30
    sequence: 2
    dependencies: [phase1]
 
  - id: phase3
    name: Phase 3
    size: 25
    sequence: 3
    dependencies: [phase2]

Cross-Team Dependencies

Frontend depending on backend:

workstreams:
  - name: Backend
    work_items:
      - id: api
        name: Build API
        size: 20
 
  - name: Frontend
    work_items:
      - id: ui
        name: Build UI
        size: 15
        dependencies: [api]  # Waits for backend

Last updated: 2025-12-19

Managing Project SettingsUsing the AI Chat