Story Map Builder

---
name: story-map-builder
description: "Generates an interactive HTML user story map visualizing product requirements in an Epic → Feature → Story structure, with MoSCoW priority tagging and Release swimlane grouping. Trigger when the user mentions story mapping, backlog visualization, MoSCoW priority, release planning, or asks to organize requirements into a story map."
license: MIT
---

# 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:

```json
{
  "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

```bash
# 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