Story Map Builder

User Story Map Builder — Interactive HTML Story Map Generator

Visualizes product requirements as an interactive HTML page using the Epic → Feature → Story three-tier structure, with MoSCoW priority color coding and Release version swimlanes.

Quick Start

The user only needs to provide product requirements — the Agent handles the rest:

1. Guides the user through organizing Epics / Features / Stories
2. Confirms MoSCoW priorities and Release assignments
3. Builds the JSON data and invokes the script to generate HTML
4. Outputs a self-contained HTML file that opens directly in any browser

The user simply says:

"Build me a story map — I have 3 Epics: user registration, product browsing, and checkout"

The Agent will walk the user through the entire story map construction step by step.

1. Core Concepts

Three-Tier Structure

MoSCoW Priorities

Release Swimlanes

Horizontal divider lines group story cards by version:

• Above the Release 1 (MVP) line = must ship in the first version
• Above the Release 2 line = planned for the second version
• And so on

2. Workflow

Step 1: Gather Requirements

Collect the following from the user:

Step 2: Build the JSON Data

Organize the data in the following format:

{
  "project": "E-Commerce Platform MVP",
  "releases": [
    {"name": "Release 1", "description": "MVP core features"},
    {"name": "Release 2", "description": "UX improvements"},
    {"name": "Release 3", "description": "Growth features"}
  ],
  "epics": [
    {
      "name": "User System",
      "features": [
        {
          "name": "Registration & Login",
          "stories": [
            {
              "name": "Phone number signup",
              "priority": "must",
              "release": "Release 1",
              "points": 3,
              "description": "User can register with phone number and verification code"
            },
            {
              "name": "WeChat login",
              "priority": "should",
              "release": "Release 2",
              "points": 5
            }
          ]
        }
      ]
    }
  ]
}

Field Reference

Step 3: Generate the HTML

# Generate from a JSON file
python3 scripts/generate_story_map.py --input data.json --output story_map.html

# Read JSON from stdin
echo '{"project":"demo",...}' | python3 scripts/generate_story_map.py --output story_map.html

Command Arguments

Step 4: Deliver the HTML

The script produces a self-contained HTML file (no external dependencies) with these features:

• 📊 Three-tier card layout: Epic → Feature → Story
• 🎨 MoSCoW priority color coding
• 📏 Release version swimlane grouping
• 📱 Responsive design with horizontal scrolling
• 🖨️ Print-friendly (auto-fits A3 landscape)
• 💡 Hover tooltips showing Story details
• 📈 Stats panel (Story counts and Points totals by priority and release)

3. Conversation Guide

Opening

I'll help you build a user story map. First, let me know:

1. What's the project name?
2. What are the major functional areas (Epics)?
3. How many releases are you planning?

Step-by-Step Walkthrough

Great, let's flesh out the "{Epic name}" Epic:

• What specific features does it include?
• What user stories fall under each feature?

Confirming Priorities

Here are the stories under "{Feature name}" — please confirm each one's priority:

Story	Suggested Priority	Your Call
...	Must

Confirming Release Assignments

Please confirm which Release each Story belongs to:

• Release 1 (MVP): Core essentials
• Release 2: UX improvements
• Release 3: Growth features

4. Notes

1. Data validation: The script automatically checks that each Story's Release reference exists in the releases list
2. Priority validation: priority only accepts must / should / could / wont
3. Empty data handling: If a Feature has no Stories, the column shows an empty placeholder
4. Multilingual support: Project names, Epic names, etc. support mixed CJK and Latin characters
5. Large map advisory: If total Stories exceed 50, consider splitting into multiple sub-maps