Delivery Timeline

Delivery Timeline

Generates a delivery timeline from a completed milestones.yaml. Asks for delivery parameters (production deploy date, QA rounds, days per QA session), updates milestones with day estimates, and produces timeline.yaml with two sections: a relative-day timeline and a real-date workback schedule anchored to the production deploy date.

Prerequisites

• Completed {base_directory}/implementation/milestones.yaml (output from /implementation-planner)

Usage

/delivery-timeline [base-directory]

If no directory is provided, auto-detect by looking for implementation/milestones.yaml in the current directory.

If not found, prompt the user: "Where are your planning artifacts located?"

Wait for the user to provide a path before proceeding. Store as base_directory.

Process

Step 1: Determine Base Directory and Load Milestones

If no directory parameter was provided, check if implementation/milestones.yaml exists in the current directory.

• If found, use current directory as base_directory
• If not found, prompt: "Where are your planning artifacts located?" and wait for user response

Once base_directory is determined:

Read {base_directory}/implementation/milestones.yaml and extract each milestone's id, name, dependencies, and estimated_duration.

Also read meta.ordering_strategy if present. Store as ordering_strategy. If absent, default to foundation-first.

The ordering_strategy value drives structural differences in Steps 6 and 7:

• multi-pr: PR/review/merge cycles are inserted after each milestone in the development timeline; the fixed pre-QA PR block in Step 7 is omitted.
• All other strategies (single-feature-branch, value-first, risk-first, vertical-slice, foundation-first): standard single-PR post-development flow (no change to current behavior).

Step 2: Gather Delivery Parameters

Ask the user the following three questions. You may present them together in a single message:

1. Production deploy date — "What is your desired production deploy date? (YYYY-MM-DD)" 2. QA rounds — "How many rounds of QA are required?" 3. QA days per round — "How many days should be allotted for each QA session?"

If the provided production deploy date falls on a Saturday or Sunday, warn the user:

"Note: [date] falls on a weekend. Would you like to use [previous Friday] or [next Monday] instead?"

Wait for the user to confirm or correct before proceeding. Store the confirmed values as:

• production_deploy_date (ISO 8601 date string)
• qa_rounds (integer ≥ 1)
• qa_days_per_round (integer ≥ 1)

Step 3: Convert Durations to Days

Convert each milestone's estimated_duration string to a whole number of business days using this table:

For durations expressed in days already (e.g., 5 days), use the number as-is.

Step 4: Update milestones.yaml

Add estimated_days to every milestone entry in {base_directory}/implementation/milestones.yaml. Do not modify any other fields.

Example — before:

- id: m0
  name: Foundation & Project Setup
  estimated_duration: 1 week

After:

- id: m0
  name: Foundation & Project Setup
  estimated_duration: 1 week
  estimated_days: 5

Step 5: Determine Project Size

Calculate total_development_days by summing estimated_days across all milestones.

Large project if either condition is true:

• total_development_days > 30
• Number of milestones > 5

Large projects receive two rounds of QA feedback by default, but this is overridden by the user-provided `qa_rounds` value from Step 2. is_large_project is still recorded in the summary for informational purposes.

Step 6: Build the Development Timeline

Starting at Day 0, assign a completion_day to each milestone in dependency order. Each milestone's start_day is the business day after its last dependency completes (or 0 if no dependencies). Its completion_day is start_day + estimated_days.

Day calculation formula:

• No dependencies: start_day = 0
• Has dependencies: start_day = max(dependency.completion_day) + 1 (next business day after dependencies complete)
• completion_day = start_day + estimated_days

For sequential milestone chains (each depends on the previous):

m0: start_day=0, completion_day=0+estimated_days(m0)=5
m1: start_day=5+1=6, completion_day=6+estimated_days(m1)=16
m2: start_day=16+1=17, completion_day=17+estimated_days(m2)=27
...

For parallel milestones (sharing same dependency), they all start the day after that dependency completes. They share the same start_day but their completion_day is calculated independently based on their individual estimated_days.

Standard strategies (all except multi-pr)

last_milestone_day = the highest completion_day among all milestones.

multi-pr strategy

After each milestone, insert four PR cycle phases before the next milestone may start. Use the milestone id as a prefix (e.g. for m0: m0-pr-creation, m0-pr-review, m0-review-feedback, m0-merge).

The PR cycle adds 4 business days of overhead after each milestone. The next milestone's start_day = completion_day of its predecessor's merge phase + 1 (starts the day after merge completes).

For sequential milestones under multi-pr:

m0: start_day=0, completion_day=0+estimated_days(m0)=5
m0-pr-creation: start_day=5, completion_day=5          # 0 days, opens same day
m0-pr-review: start_day=5, completion_day=5+2=7
m0-review-feedback: start_day=7, completion_day=7+2=9
m0-merge: start_day=9, completion_day=9                # 0 days, merges same day

m1: start_day=9+1=10, completion_day=10+estimated_days(m1)=20
# ... repeat for each milestone

For parallel milestones under multi-pr, each branch gets its own PR cycle. A milestone depending on multiple parallel predecessors starts the day after the latest merge completion_day among them (max(merge.completion_day) + 1).

last_milestone_day = the highest completion_day of the final [milestone-id]-merge phase across all milestones.

Step 7: Append Post-Development Timeline

Add delivery phase items starting from last_milestone_day. Each item has a start_day (day the work begins) and completion_day (day the work is done). Items with estimated_days: 0 complete on the same day they start.

Use qa_rounds and qa_days_per_round from Step 2 to drive the QA section.

Fixed Pre-QA Phases

Standard strategies (all except `multi-pr`): Include the full PR/merge/deployment block below. This represents the single end-of-project PR.

`multi-pr` strategy: Omit post-pr-creation, post-pr-review, post-review-feedback, and post-merge — those cycles already occurred per-milestone in Step 6. Start directly with post-deployment.

QA Phases (repeated for each round 1..qa_rounds)

For each round R from 1 to qa_rounds, generate the following phases using qa_days_per_round as the QA Deadline duration. Use round-specific ids (e.g. post-qa-r1-deadline, post-qa-r2-deadline). When qa_rounds == 1, ids may omit the round suffix (e.g. post-qa-deadline).

Fixed Post-QA Phase (all projects)

Step 8: Build Workback Schedule

Map every timeline item (milestones + delivery phases) to a real calendar date by working backwards from production_deploy_date.

Anchor point: production_deploy_date = the real date for completion_day of post-signoff (the final day of the timeline, total_delivery_days).

Business day arithmetic: When counting backwards, skip Saturdays and Sundays. One business day back from a Monday is the previous Friday.

For each timeline item:

• completion_date = production_deploy_date minus (total_delivery_days − item.completion_day) business days
• start_date = production_deploy_date minus (total_delivery_days − item.start_day) business days

`project_start_date` = production_deploy_date minus total_delivery_days business days (Day 0).

Include all items from timeline in the same order. Also append a final entry for production-deploy with date: production_deploy_date.

Step 9: Generate timeline.yaml

Write {base_directory}/delivery/timeline.yaml.

Create directory if it doesn't exist:

mkdir -p {base_directory}/delivery

Output Format

Updated milestones.yaml

The estimated_days field is added to each milestone entry. All other content is preserved exactly.

timeline.yaml Schema

The output document includes: version, project, generated, milestones_file, summary (total days, project size, QA rounds, delivery model), timeline (milestones + delivery phases with start_day/completion_day/estimated_days), and workback (production deploy date, project start date, real calendar schedule).

See [references/output-spec.md](references/output-spec.md) for the complete document specification with all fields, phase types, and workback calculation rules.

See [references/example.yaml](references/example.yaml) for a full example.

Example Output

See [references/example.yaml](references/example.yaml) for a complete sample timeline.

Gap Analysis

After generating timeline.yaml, perform a gap analysis and report findings inline.

Checks

Coverage

• [ ] Every milestone in milestones.yaml appears in timeline.yaml
• [ ] All milestone dependencies are respected (no milestone completes before its dependencies)
• [ ] estimated_days was added to every milestone in milestones.yaml

Duration Reasonableness

• [ ] No single milestone has estimated_days: 0 (flag for review)
• [ ] No milestone exceeds 30 days without a note explaining the scope
• [ ] Duration conversions match the table in Step 2

Project Size Classification

• [ ] is_large_project correctly reflects total_development_days > 30 OR milestone_count > 5
• [ ] QA rounds in timeline.yaml match user-provided qa_rounds
• [ ] QA Deadline phases each use qa_days_per_round days

Delivery Model

• [ ] ordering_strategy was read from milestones.yaml (or defaulted to foundation-first)
• [ ] delivery_model in timeline.yaml summary matches the resolved strategy
• [ ] For multi-pr: each milestone has a corresponding [milestone-id]-pr-creation / pr-review / review-feedback / merge block in the timeline; post-pr-creation through post-merge are absent from post-development phases
• [ ] For all other strategies: post-pr-creation through post-merge are present in post-development phases; no per-milestone PR blocks exist

Timeline Integrity

• [ ] completion_day values are strictly increasing for sequential milestones
• [ ] Parallel milestones have correct independent completion_day values
• [ ] Post-development phases follow immediately after last_milestone_day
• [ ] total_delivery_days = completion_day of post-signoff

Workback Integrity

• [ ] project_start_date = production_deploy_date minus total_delivery_days business days
• [ ] production-deploy entry date matches production_deploy_date
• [ ] All completion_date values are on weekdays (Mon–Fri)
• [ ] workback.schedule contains all entries from timeline in the same order
• [ ] post-signoff completion_date = production_deploy_date

Gap Analysis Report

After generating files, output a brief inline report:

## Timeline Gap Analysis

**Project:** [name]
**Delivery Model:** [ordering_strategy]
**Total Development Days:** [n] ([n] weeks)
**Total Delivery Days:** [n] (including post-dev phases)
**Project Size:** [Small / Large] ([reason if large])
**QA Rounds:** [n] × [qa_days_per_round] days each
**Production Deploy:** [YYYY-MM-DD]
**Project Start:** [YYYY-MM-DD]

**Checks:**
✓ All [n] milestones included
✓ Dependency order respected
✓ Duration conversions applied
[✓ / ✗] estimated_days added to milestones.yaml
[✓ / ✗] QA rounds match user-specified value ([n] rounds)
[✓ / ✗] All workback dates land on weekdays
[✓ / ✗] post-signoff completion_date = production_deploy_date

**Issues:** [none / list issues]

**Recommendations:** [none / list recommendations]

If issues are found, ask:

"I found the following timeline issues:

>

- [Issue 1]

- [Issue 2]

>

Would you like to:

>

1. Fix these issues now

2. Proceed with the timeline as-is

3. Manually adjust the estimates before generating"

Timeline YAML Specification

Document Type: timeline.yaml Version: 1.0.0 Generated By: delivery-timeline skill Purpose: Complete delivery schedule with relative-day timeline and calendar workback, generated from milestones.yaml. Includes development milestones, post-development phases, QA cycles, and final signoff mapped to real calendar dates working backwards from production deploy date.

---

Document Structure

Root Level

version: string                    # Semantic version (required, format: "X.Y.Z")
project: string                    # Project name (required)
generated: string                  # ISO 8601 timestamp (required)
milestones_file: string            # Path to source milestones.yaml (required)

Validation Rules:

• version: Must be semantic version format (e.g., "1.0.0")
• project: 3-100 characters, matches source milestones.yaml
• generated: ISO 8601 format (e.g., "2026-04-16T10:30:00Z")
• milestones_file: Relative path to milestones.yaml (typically "../milestones.yaml" or "milestones.yaml")

Summary Section

summary:
  total_development_days: integer      # Sum of all milestone estimated_days (required)
  total_delivery_days: integer         # Development + post-dev phases (required)
  is_large_project: boolean            # true if >30 dev days OR >5 milestones (required)
  milestone_count: integer             # Number of milestones (required)
  qa_rounds: integer                   # User-specified QA rounds (required, ≥1)
  qa_days_per_round: integer           # Days per QA session (required, ≥1)
  production_deploy_date: string       # Target deploy date (required, YYYY-MM-DD)
  delivery_model: string               # Ordering strategy from milestones.yaml (required)

Validation Rules:

• total_development_days: Positive integer, sum of milestone estimated_days
• total_delivery_days: Positive integer, > total_development_days (development + post-development phases)
• is_large_project: true if total_development_days > 30 OR milestone_count > 5
• milestone_count: Positive integer, matches milestones array length
• qa_rounds: Integer 1-10 (warn if >5)
• qa_days_per_round: Integer 1-20 (warn if >10)
• production_deploy_date: ISO 8601 date (YYYY-MM-DD), weekday (Mon-Fri)
• delivery_model: One of: multi-pr, single-feature-branch, value-first, risk-first, vertical-slice, foundation-first

Timeline Array

The timeline contains all development milestones followed by post-development delivery phases, ordered by completion_day.

Milestone Entry

timeline:
  - id: string                     # Milestone ID from milestones.yaml (required, format: m\d+)
    name: string                   # Milestone name (required)
    type: milestone                # Entry type (required, literal: "milestone")
    start_day: integer             # Day work begins (required, ≥0)
    completion_day: integer        # Day work completes (required, >start_day)
    estimated_days: integer        # Duration in business days (required, >0)
    dependencies: array<string>    # Milestone IDs this depends on (required)

Validation Rules:

• id: Must match pattern m\d+ (e.g., m0, m1, m42)
• name: 10-100 characters
• type: Must be literal string "milestone"
• start_day: Non-negative integer; equals max(dependency.completion_day) + 1 or 0 if no dependencies
• completion_day: Must equal start_day + estimated_days
• estimated_days: Positive integer
• dependencies: Array of milestone IDs or empty array

Delivery Phase Entry (Standard Strategies)

For all strategies except multi-pr, post-development phases include:

  - id: string                     # Phase ID (required, pattern: post-*)
    name: string                   # Phase name (required)
    type: delivery                 # Entry type (required, literal: "delivery")
    start_day: integer             # Day phase begins (required)
    completion_day: integer        # Day phase completes (required)
    estimated_days: integer        # Duration in business days (required, ≥0)
    notes: string                  # Context or explanation (optional)

Standard Post-Development Phases (in order):

QA Feedback Duration Rules:

• qa_rounds == 1: feedback-impl = 2 days, feedback = 1 day
• qa_rounds > 1 AND round == 1: feedback-impl = 3 days, feedback = 2 days (extended for first round)
• qa_rounds > 1 AND round > 1: feedback-impl = 2 days, feedback = 1 day (standard for later rounds)

Note: When qa_rounds == 1, the round suffix SHOULD be omitted (use post-qa-deadline not post-qa-r1-deadline).

Delivery Phase Entry (Multi-PR Strategy)

For multi-pr strategy, each milestone has its own PR cycle inserted immediately after completion:

  - id: string                     # Pattern: [milestone-id]-pr-creation (e.g., m0-pr-creation)
    name: string                   # Pattern: [Milestone Name] PR Creation
    type: delivery                 # Entry type (required)
    start_day: integer             # Milestone completion_day
    completion_day: integer        # Same as start_day (0 days)
    estimated_days: 0              # Always 0

Per-Milestone PR Phases (multi-pr only):

Multi-PR Post-Development Phases:

• Omits: post-pr-creation, post-pr-review, post-review-feedback, post-merge
• Starts with: post-deployment
• Continues with: QA rounds and signoff as normal

Workback Section

Maps timeline items to real calendar dates by counting backwards from production_deploy_date.

workback:
  production_deploy_date: string   # Target deploy date (required, YYYY-MM-DD)
  project_start_date: string       # Day 0 in calendar terms (required, YYYY-MM-DD)
  schedule:
    - id: string                   # Same as timeline entry (required)
      name: string                 # Same as timeline entry (required)
      type: string                 # milestone | delivery | deploy (required)
      start_date: string           # Calendar start date (required, YYYY-MM-DD)
      completion_date: string      # Calendar completion date (required, YYYY-MM-DD)

Validation Rules:

• production_deploy_date: Must match summary.production_deploy_date
• project_start_date: Calculated as production_deploy_date minus total_delivery_days business days
• All dates must be weekdays (Monday-Friday)
• schedule must contain all timeline entries in same order
• Final entry is always production-deploy with type: deploy

Date Calculation:

• Start from anchor: production_deploy_date = completion_date of post-signoff (day N where N = total_delivery_days)
• Count backwards using business days (skip Sat/Sun). Deploy date is the final day of the timeline.
• completion_date = production_deploy_date minus (total_delivery_days - item.completion_day) business days
• start_date = production_deploy_date minus (total_delivery_days - item.start_day) business days
• Example: If total_delivery_days=80 and production_deploy_date=2026-06-05, then day 80 completes on 2026-06-05. Counting backwards 80 business days gives project_start_date (day 0).

Final Production Deploy Entry:

The production deploy entry uses date field (not start_date/completion_date) since it's a point-in-time event:

    - id: production-deploy
      name: Production Deploy
      type: deploy
      date: string                 # production_deploy_date (YYYY-MM-DD)

---

Duration Conversion Table

The delivery-timeline skill converts human-readable durations from milestones.yaml to business days:

Notes:

• Business days only (Mon-Fri)
• Weekends are skipped in all calculations
• Durations already in days are used as-is

---

Delivery Model Differences

Standard strategies (single-feature-branch, value-first, risk-first, vertical-slice, foundation-first) complete all milestones before opening a single PR. Multi-PR strategy inserts a 4-day PR cycle after each milestone. See Delivery Phase Entry sections above for detailed schemas.

---

Project Size Classification

Projects with total_development_days > 30 OR milestone_count > 5 are flagged as is_large_project: true.

Impact:

• Informational only (does not control QA rounds)
• User-specified qa_rounds always takes precedence

---

---

Integration with Other Documents

Input: milestones.yaml and user parameters (production_deploy_date, qa_rounds, qa_days_per_round)

Output: timeline.yaml and updated milestones.yaml (with estimated_days added)

Related: milestone-m*.tasks.yaml (task details), qa-test-plan.yaml (test plan)

Workflow:

milestones.yaml → [user params] → delivery-timeline skill → timeline.yaml + updated milestones.yaml

---

Generation Process

The delivery-timeline skill reads milestones.yaml, gathers user parameters (deploy date, QA rounds, days per round), converts durations to business days, builds a dependency-ordered timeline with delivery phases, and generates workback dates by counting backwards from the production deploy date. See /skills/delivery-timeline/SKILL.md for detailed implementation steps.

---

Validation Checklist

When reviewing a generated timeline.yaml, verify:

Coverage:

• [ ] Every milestone in milestones.yaml appears in timeline.yaml
• [ ] All milestone dependencies respected (no milestone completes before dependencies)
• [ ] estimated_days added to every milestone in milestones.yaml

Duration Validation:

• [ ] No milestone has estimated_days: 0
• [ ] No milestone exceeds 30 days without justification
• [ ] Duration conversions match the standard table

Project Classification:

• [ ] is_large_project correctly reflects total_development_days > 30 OR milestone_count > 5
• [ ] QA rounds match user-specified value
• [ ] QA Deadline phases each use qa_days_per_round days

Delivery Model:

• [ ] ordering_strategy read from milestones.yaml (or defaulted to foundation-first)
• [ ] delivery_model in summary matches resolved strategy
• [ ] Multi-pr timeline contains per-milestone PR phases (4 phases per milestone)
• [ ] Multi-pr post-dev phases start with post-deployment (omit post-pr-* phases)
• [ ] Standard strategy timeline contains no per-milestone PR phases
• [ ] Standard strategy post-dev phases include post-pr-creation through post-merge

Timeline Integrity:

• [ ] All milestone IDs are unique
• [ ] For all timeline items: start_day ≤ completion_day
• [ ] For each milestone with dependencies: start_day = max(dependency.completion_day) + 1 (starts day after dependencies complete)
• [ ] For each milestone: completion_day = start_day + estimated_days
• [ ] Parallel milestones (sharing same dependency) share the same start_day but have independent completion_day values
• [ ] Post-development phases follow immediately after last_milestone_day (no gap)
• [ ] total_delivery_days equals post-signoff completion_day

Workback Integrity:

• [ ] project_start_date = production_deploy_date minus total_delivery_days business days
• [ ] project_start_date is a weekday (if calculated date falls on weekend, adjusted to previous Friday)
• [ ] All completion_date values are weekdays (Mon-Fri)
• [ ] workback.schedule contains all timeline entries in same order
• [ ] post-signoff completion_date = production_deploy_date
• [ ] production-deploy entry date = production_deploy_date

---

Schema Version History

• 1.0.0 (2026-04-16): Initial specification
• Complete timeline.yaml schema
• Support for all ordering strategies (including multi-pr)
• Relative-day timeline and calendar workback
• Flexible QA round configuration
• Integration with milestones.yaml

---

Examples

See example.yaml for a complete timeline.yaml demonstrating:

• Large project (55 dev days, 8 milestones)
• 2 QA rounds × 5 days each
• Standard strategy (single feature branch)
• Full workback schedule with calendar dates