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

Tier	Meaning	Example
Epic	Major value theme / user activity	User Registration & Login
Feature	Functional module under an Epic	Phone signup, Email signup, SSO login
Story	Smallest deliverable user story	As a user, I can register with my phone number and a verification code

MoSCoW Priorities

Level	Meaning	Color
Must	Essential — product is unusable without it	🔴 Red
Should	Important — significantly increases value	🟠 Orange
Could	Nice to have — adds polish	🔵 Blue
Wont	Not this time — recorded for future reference	⚪ Gray

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:

Item	Required	Notes
Project name	✅	Displayed in the map title
Epic list	✅	2–8 Epics
Features per Epic	✅	1–6 Features per Epic
Stories per Feature	✅	1–10 Stories per Feature
Priority per Story	✅	must / should / could / wont
Release per Story	✅	Which version it belongs to
Release list	✅	Version names and descriptions
Story Points (optional)	❌	Effort estimate
Story description (optional)	❌	Additional details

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

Field	Type	Required	Description
project	string	✅	Project name
releases	array	✅	Release list (in order)
releases[].name	string	✅	Version name — must match the release field in Stories
releases[].description	string	❌	Version description
epics	array	✅	Epic list
epics[].name	string	✅	Epic name
epics[].features	array	✅	Feature list
epics[].features[].name	string	✅	Feature name
epics[].features[].stories	array	✅	Story list
stories[].name	string	✅	Story name
stories[].priority	string	✅	must / should / could / wont
stories[].release	string	✅	Assigned version name
stories[].points	number	❌	Story Points
stories[].description	string	❌	Additional description

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

Argument	Required	Description
--input	❌	Input JSON file path (reads from stdin if omitted)
--output	✅	Output HTML file path

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