storymap-skill
-success)
An Agent Skill that runs user story mapping (Jeff Patton style) to turn a goal, brief, or messy backlog into a sliced, prioritized delivery plan.
Built primarily for Claude Code, but works across any agent that supports the Agent Skills open standard — including Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, OpenCode, Goose, Letta, Roo, Kiro, and ~30 others.
It produces a project design doc, a story map (markdown + CSV, plus a Mermaid graph when no tracker is defined), a prioritized backlog (WSJF / RICE / MoSCoW), and optionally Given/When/Then acceptance criteria + an E2E test contract for slice 1.
Plays well inside Superpowers, gstack, and GSD. Works fine standalone.
What it does
- One re-entrant loop — discover → diff (vs. existing artifacts/tracker/code) → apply saved preferences → interview until approved → backbone → generate/update idempotently → derive + hand off. "From scratch" is just the loop running when the data sources are empty (the diff is against nothing) — no separate mode to detect.
- Tracker-aware — when an issue tracker is defined, reuses its existing taxonomy (epics/components/fix-versions/labels/custom fields) instead of inventing categories, and persists the field-mapping to
.user-story-mapping/state.json
- Adaptive context loop — mines README, code, tests, ADRs, commit log, Jira/ADO/GitHub via MCP, sister-framework state (
.gsd/, .superpowers/), and prior design.md BEFORE asking the user
- Customer-interview synthesis — extracts personas/activities/problems from raw transcripts with verbatim-quote preservation
- Persona simulation + interactions — spawns role-play subagents to fill gaps, surface stakeholder conflicts (user-input-authoritative — sim never overrides user), and map cross-persona handoffs/dependencies
- Six backbone-generation criteria — frame, persona perspective, time horizon, granularity, scope, aggregation (user-confirmed + recorded for reproducibility)
- Three slicing strategies — Patton classic, SAFe PI, Now/Next/Later
- Three prioritization methods — WSJF, RICE, MoSCoW
- Dependency tracking —
depends_on column, cycle detection, slice-1 feasibility check
- OKR alignment — coverage matrix, orphan stories + orphan KRs
- Acceptance criteria — Given/When/Then for slice 1 + INVEST check
- E2E test contract — backbone activities as E2E swimlanes
- Iteration limit-breach detection — re-running the loop on a non-empty baseline detects capacity / dependencies / OKR coverage / scope breaches; surfaces trade-offs rather than silently absorbing
- Output routing — from-scratch projects → seed an issue tracker (Jira/ADO/GitHub Projects/Linear/Trello); existing projects → keep-in-place cascade (sister-framework state →
TODO.md → Memory MCP), with optional Claude Code TodoWrite pairing when the user is about to execute
- Persistent memory — opt-in
.user-story-mapping/state.json or MCP memory server
- Skill chaining — invokes other installed skills (code-explorer, db-analyzer, etc.) for context gathering
Installation
As a Claude Code plugin (recommended)
The repo is a self-contained Claude Code plugin marketplace. From inside Claude Code:
/plugin marketplace add martinforreal/storymap-skill
/plugin install storymap-skill@storymap-skill
That's it — Claude Code picks up the .claude-plugin/marketplace.json and installs the bundled skill (located at skills/user-story-mapping/).
As a raw Agent Skill (for any compatible host)
The packaged .skill artifact is built by CI on tag push and attached to each release — download user-story-mapping.skill from the assets and install it via your host's skill installer:
- Cursor / Codex CLI / Goose / Letta / Roo / Kiro / OpenCode / ~30 others — drop into the host's skills directory, or use the host's CLI installer
- Claude Code (manual install path) — copy
skills/user-story-mapping/ into ~/.claude/skills/
# Manual install from source
git clone https://github.com/martinforreal/storymap-skill.git
cp -r storymap-skill/skills/user-story-mapping ~/.claude/skills/
