Roadmap & Timeline Generator

This skill turns a dump of project artifacts (PRDs, architecture diagrams, technical specs, etc.) into a styled, partner-facing Project Roadmap spreadsheet.

The output is a single .xlsx file with four columns — Milestone / Pipeline, Key Deliverables, Status, Deadline — using the bundled navy/teal style system. Partners use it to see what's being built, where each piece stands, and (later) when each piece is due.

Workflow

The work splits into two stages:

1. You analyze the input docs and produce a JSON spec that describes milestones, deliverables, and statuses.
2. A script renders the spec into a styled .xlsx. Styling is locked — never reproduce it by hand.

Stage 1 — Analyze the inputs

When the user provides project artifacts, work through them in this order:

a. Read every input file. PDFs, DOCX, MD, CSV, XLSX, and image files (PNG/JPEG of architecture diagrams) are all in scope. In Claude chat use the pdf-reading, docx, and xlsx skills for those formats; in Claude Code read them directly. Describe images directly in both. Don't skim — partner trackers are public-facing artifacts, so accuracy matters.

b. Identify milestones. Milestones correspond to workflows or pipelines, not individual components. Look at the architecture diagram and architecture doc first — they almost always reveal the pipeline structure (e.g., "Intake Pipeline", "Audio Processing Pipeline", "Matching & Retrieval Pipeline"). Foundation/infrastructure work and final launch/MVP activities typically bracket the pipelines as the first and last milestones.

The number of milestones varies with project size — let the architecture and documentation structure dictate the count. Don't artificially compress or pad it. Number them ("1. Foundation & Infrastructure", "2. Intake Pipeline", …).

c. Map sub-components / deliverables under each milestone. These are the rows under the milestone band — concrete, partner-readable units of work pulled from the PRD and supporting docs. Phrase them as short noun phrases ("Database & storage setup", "Speaker separation & audio event tagging"), not as task verbs ("Build the database").

d. Infer status for each deliverable. Default everything to In-Process. Override only when the input contains explicit cues:

• Shipped / live / deployed / done / completed → Completed
• In QA / under test / in testing / acceptance testing → Testing
• Cancelled / dropped / deprecated / on hold / out of scope → Cancelled

If a deliverable is genuinely ambiguous, default to In-Process rather than guessing.

e. Leave deadlines blank. The skill never populates the Deadline column — partners fill it in themselves. (The script supports a deadline field for future flexibility, but you should not use it.)

f. Ask clarification questions if anything is unclear. Common cases that warrant a question before generating:

• Architecture doc and PRD disagree about pipeline boundaries
• Multiple PRDs cover overlapping scopes — is one canonical?
• The user mentions "the project" but provides docs for multiple projects
• A deliverable is described in detail in one doc and contradicted in another
• It's unclear whether something belongs as a milestone or as a deliverable under another milestone

Ask focused questions — one batch, not a long interrogation. If the inputs are coherent and clear, skip this step and proceed to Stage 2.

Stage 2 — Render the spreadsheet

Build a JSON spec matching this schema:

{
  "project_name": "Lumio",
  "milestones": [
    {
      "name": "1. Foundation & Infrastructure",
      "deliverables": [
        {"name": "Database & storage setup", "status": "In-Process"},
        {"name": "User authentication & access control", "status": "In-Process"}
      ]
    },
    {
      "name": "2. Intake Pipeline",
      "deliverables": [
        {"name": "Audio recording & upload flow", "status": "In-Process"}
      ]
    }
  ]
}

Save it to a temp file, then run the build script:

python <skill-dir>/scripts/build_roadmap.py <spec>.json <output-dir>/<ProjectName>_-_Project_Roadmap.xlsx

Filename convention: {ProjectName}_-_Project_Roadmap.xlsx (e.g., Lumio_-_Project_Roadmap.xlsx). Replace spaces with underscores. The em-dash style ("Lumio — Project Roadmap") goes in the title cell, which the script handles automatically.

See the Environment section for the output directory and how to hand the file over.

Environment

This skill runs in both Claude chat and Claude Code. A few things differ:

Pick based on where you're running: if /mnt/user-data/ exists, you're in Claude chat. A path the user names explicitly always wins over either default. Never overwrite an existing file without saying so first.

Style system (locked — handled by the script)

These are documented for reference only; do not re-implement them by hand. The script enforces them.

• Font: Arial throughout
• Header bar (row 1, merged A:D, and row 3 column headers): navy #1B3A5C fill, white bold text
• Milestone bands (merged A:D): light purple #E8EAF6 fill, navy bold text
• Status colors:
  • Completed — green text #2E7D32 on light grey #F5F5F5
  • In-Process — orange text #F57F17 on white
  • Testing — blue text #1565C0 on light grey
  • Cancelled — grey text #9E9E9E on light grey
• Borders: thin grey on every cell in the table
• Frozen pane: below row 3 (header stays visible while scrolling)
• Column widths: A=42, B=55, C=20.29, D=20

A reference sample is bundled at assets/reference_sample.xlsx (built from the synthetic Lumio project in test_inputs/, and covering all four statuses). When in doubt about layout, open it for inspection — but never copy values from it into a new project's output.

Common mistakes to avoid

• Treating components as milestones. "User authentication" is a deliverable, not a milestone. Milestones are pipelines/workflows like "Foundation & Infrastructure" or "Intake Pipeline."
• Inventing deadlines. Deadline column stays empty. Partners fill it in.
• Marking everything Completed because the PRD describes finished features. PRDs describe what the product will do, not what's shipped. Default is In-Process. Only mark Completed when there's explicit evidence the work is done.
• Hand-rolling styles. Always go through build_roadmap.py. Hand-styling drifts from the reference.
• Skipping the analysis step. Even if the user uploads a single tidy PRD, read it carefully before producing the spec — partner-facing artifacts don't get a second pass.

Reference files

• scripts/build_roadmap.py — the renderer. JSON in, styled .xlsx out.
• assets/reference_sample.xlsx — the visual reference for this style system, generated from test_inputs/test1_lumio_prd.md.