convez.ai
SkillProdutividadeIntermediário
MartinForReal

Story Map Skill

MartinForReal/storymap-skill

Mapeia histórias de usuário em planos de entrega priorizados e fatiaveis

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que transforma objetivos, briefings ou backlogs desorganizados em planos de entrega fatiados usando a metodologia de Jeff Patton. Gera mapa de histórias em múltiplos formatos, prioriza tarefas com WSJF/RICE/MoSCoW e valida dependências e cobertura de OKRs.

Instalação

$npx convez-ai MartinForReal/storymap-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
1
Acompanhando
1
Saúde
42%
Último commit
há 3 meses
Versão
v0.0.6
Issues abertas
0
Contribuidores
1

Casos de uso

  • Estruturar backlogs caóticos em entregas incrementais
  • Priorizar histórias usando WSJF, RICE ou MoSCoW
  • Gerar critérios de aceitação e testes E2E para primeira fatia
  • Alinhar histórias com OKRs e detectar lacunas

Veredito

Skill robusto e bem-testado (98.3% no benchmark) que resolve um problema real: transformar demandas nebulosas em roadmaps executáveis. Integração com Claude Code, MCP e frameworks irmãos (Superpowers, gstack, GSD) o torna prático para times que trabalham em ciclos curtos. Recomendado para PMs e tech leads que enfrentam backlogs desorganizados.

README

A tradução para o português deste README ainda está na fila.

storymap-skill

License: MIT Agent Skills standard Spec-valid Benchmark

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 three-format story map (markdown + Mermaid + CSV), 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

  • Four invocation modes — from scratch (verbal idea), from a brief/PRD, from an existing messy backlog, iterative refinement of a prior map
  • 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 — spawns role-play subagents to fill gaps + surface stakeholder conflicts (user-input-authoritative — sim never overrides user)
  • 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
  • Mode D limit-breach detection — capacity / dependencies / OKR coverage / scope; 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/

# Or build the .skill bundle yourself:
git clone https://github.com/martinforreal/storymap-skill.git
cd storymap-skill
python scripts/build_skill_bundle.py   # writes user-story-mapping.skill

Verify

Once installed, the skill triggers on prompts like:

  • "What should we build first for X?"
  • "Help me find the MVP slice"
  • "Organize this backlog"
  • "PI planning"
  • "Scope this project"

File structure

storymap-skill/                                   # repo root = Claude Code plugin
├── .claude-plugin/
│   ├── plugin.json                               # plugin manifest (Claude Code)
│   └── marketplace.json                          # self-marketplace entry
├── skills/
│   └── user-story-mapping/                       # the skill itself (Agent Skills v1)
│       ├── SKILL.md                              # entry point — workflow at a glance + 6 steps
│       ├── assets/
│       │   ├── storymap-template.md              # canonical markdown format the scripts parse
│       │   ├── design-doc-template.md            # design doc with Backbone criteria + source tagging
│       │   ├── backlog-template.csv              # backlog with WSJF/RICE/MoSCoW/depends_on/okr columns
│       │   └── backlog-summary-template.md
│       ├── evals/
│       │   └── evals.json                        # 18 consolidated test scenarios across 9 categories
│       ├── references/                           # 14 reference files loaded on demand
│       │   ├── context-collection.md             # Step 0 adaptive loop, framework artifacts, skill chaining
│       │   ├── customer-interview-synthesis.md   # raw notes → personas/activities/hypotheses
│       │   ├── persistent-knowledge.md           # memory across sessions
│       │   ├── persona-simulation-and-gap-filling.md  # Step 0.4 — role-play subagents, conflict matrix
│       │   ├── discovery-questions.md            # Mode A question bank
│       │   ├── slicing-strategies.md             # Patton / SAFe PI / Now-Next-Later + cross-cutting rule
│       │   ├── prioritization-frameworks.md      # WSJF / RICE / MoSCoW with worked examples
│       │   ├── dependency-tracking.md            # depends_on column, cycle detection
│       │   ├── okr-alignment.md                  # OKR coverage matrix
│       │   ├── acceptance-criteria.md            # Given/When/Then generation + INVEST
│       │   ├── e2e-verification-and-contract.md  # backbone-as-E2E-contract
│       │   ├── iterative-refinement-and-snapshots.md  # Mode D: snapshot + breach detection + diff
│       │   ├── framework-integration.md          # Superpowers / gstack / GSD handoff patterns
│       │   └── work-item-tracking.md             # Jira / ADO / GitHub / Linear / etc. import
│       └── scripts/
│           ├── storymap_to_csv.py                # storymap.md → storymap.csv
│           └── storymap_to_mermaid.py            # storymap.md → storymap.mmd
├── examples/                                     # sample outputs from 3 scenarios
├── tests/                                        # benchmark infrastructure
├── benchmark/                                    # latest published benchmark.json + benchmark.md
├── scripts/
│   └── build_skill_bundle.py                     # builds user-story-mapping.skill from skills/
├── .github/workflows/
│   └── release.yml                               # CI: builds .skill on tag push, attaches to release
├── CHANGELOG.md
├── LICENSE                                       # MIT
└── README.md

Workflow at a glance

StepPurposeBudget
0 Context loopHypothesis-driven mining of cheap-then-conditional sources (works for both from-scratch and existing project)<15%
0.4 Fill gapsList blocking gaps; ask user; if can't ask, spawn persona-sim subagents; gate planning on completeness15-20%
1 BackboneLeft-to-right user activities; criteria user-confirmed + recorded5-10%
2 DecomposeTasks under activities; stories under tasks10-15%
3 SliceWalking-skeleton/PI/Now-Next-Later; first slice covers every backbone activity5%
4 PrioritizeWSJF/RICE/MoSCoW + OKR linkage + dependency feasibility check15-20%
4a ACsGiven/When/Then for slice-1 stories + INVEST check10-15%
4b E2E contractBackbone-as-contract: coverage matrix, E2E-HAPPY happy path, per-activity scenarios5-10%
5 Generate derivedRun bundled scripts for storymap.csv + storymap.mmd<2%
6 Hand offWhat was produced; what's still uncertain; smallest next decision5%

Target total token budget: ~200K. Story count cap: ~50 total; slice-1 ≤ 15.

The user-input-authoritative principle

What the actual user told you, in this conversation, always wins. Lower-priority sources fill gaps but never override.

priority of sources (highest → lowest):
  1. The actual user in this conversation
  2. Verbatim from interview notes / call transcripts
  3. Persistent memory from prior sessions (only if user approved)
  4. Context mined from artifacts (README, code, tests, tracker)
  5. Simulated persona responses
  6. General-knowledge inference

Every fact in design.md is source-tagged so reviewers can audit later.

Examples

The examples/ directory contains sample outputs from three scenarios:

  • from-scratch-internal-tool/ — Mode A, verbal-only fintech-refund-portal brief, WSJF, SAFe PI
  • multi-stakeholder-conflict/ — internal developer platform with conflicting stakeholders, user-input-authoritative principle in action
  • snapshot-and-breaks-limits/ — Mode D snapshot of a mid-flight PI, new feature requested, 6 limit breaches detected with trade-off options

Each contains the full 7-file output (design.md, storymap.md, storymap.csv, storymap.mmd, backlog.md, backlog.csv, handoff.md) plus slice-1-acceptance-criteria.md / breach-decisions.md where applicable.

Tests

evals/evals.json contains 18 consolidated test scenarios spanning:

  • Invocation modes A/B/C/D
  • App types: web, mobile (consumer + B2B), desktop, API/SDK, CLI, enterprise multi-tenant
  • Framework integrations: Superpowers, gstack, GSD
  • Capabilities: customer interview synthesis, dependency tracking, OKR alignment, persona simulation + conflict resolution, Mode D limit-breach detection, context loop short-circuit, framework-artifact mining + backbone criteria

Test infrastructure (grade_runs.py, build_benchmark.py, build_viewer.py, setup_iter10.py) lives in tests/. See tests/README.md.

Benchmark

Latest full benchmark (iteration 11, all 18 evals × {with-skill, baseline}):

ConfigurationPass rateMean durationMean tokens
with-skill98.3% (171/174)554s215,947
baseline (no skill)20.1% (35/174)236s162,905
Δ+78.2pp+319s+33%

The skill adds ~33% tokens for a ~4.9× quality improvement. Per-eval breakdown + analyst notes in benchmark/benchmark.md; raw data in benchmark/benchmark.json. Regenerate locally with python tests/run-benchmark.sh or the individual scripts in tests/.

Where the skill earns its keep

  • Structural conformance — all 6 canonical files in the canonical CSV/Mermaid format, every time. Baseline produces ad-hoc structures that don't import into Jira/ADO cleanly.
  • Methodology correctness — WSJF/RICE/MoSCoW with all required columns, slice-1 backbone coverage rule honored, dependency cycles surfaced not silently broken.
  • Capability-specific behaviors — persona conflict matrix with user-input-authoritative principle (eval-15), Mode D limit-breach detection with trade-off options (eval-16), framework-artifact mining without re-asking user (eval-18).

Where baseline closes the gap

  • Eval-16 (Mode D + breach detection): 8/8 vs 6/8 — when the prompt explicitly demands breach surfacing, baseline does well. The skill's value is consistent breach detection across less-structured prompts.
  • Evals 5, 15, 16: baseline 3-6 — when the user explicitly names the methodology in the prompt, baseline has something to grab onto.

When prompts are sparse, baseline collapses to 0-2/N.

Security considerations

Before installing any third-party Agent Skill (this one included):

  1. Audit the instructions. Read SKILL.md and the references/ files. Skills are loaded into your agent's context and influence what it does. Treat the skill like a configuration file with side effects on agent behavior.
  2. Audit the bundled scripts. This skill ships two Python files in scripts/. Read them — they're <200 lines combined and only convert markdown to CSV / Mermaid. They do not access network, write outside the working directory, or read user secrets.
  3. Check compatibility in SKILL.md frontmatter — this skill declares what it expects (Python 3.10+, no other system deps).
  4. Don't put secrets in the skill's working directory. The skill mines context from files in the working directory. Keep .env, credentials, etc. outside.
  5. Tracker MCP access is opt-in. This skill can mine Jira / ADO / GitHub via MCP if the user wires those MCPs up — it never auto-installs them.

The skill never:

  • Makes network calls (no requests, urllib, httpx imports)
  • Modifies code in the working directory (only writes to <output-dir>/ per the user's request)
  • Auto-invokes other skills (per spec — only the user does that)
  • Persists state without explicit user opt-in (.user-story-mapping/state.json is opt-in; see references/persistent-knowledge.md)

If you find a security concern, please open an issue.

License

MIT — see LICENSE.

Contributing

Issues and PRs welcome. When adding capabilities:

  1. Write the reference file first (references/<your-feature>.md)
  2. Update SKILL.md workflow steps to call it out
  3. Add at least one new test case to evals/evals.json
  4. Update assets (backlog-template.csv etc.) if schema changes

Credits

Built iteratively with Claude Code's skill-creator plugin over 10 test iterations. Story mapping methodology per Jeff Patton's User Story Mapping (O'Reilly, 2014). Conforms to the Agent Skills v1 specification.

Changelog

See CHANGELOG.md.

Ver o original no GitHub

Bom para

Relacionados