@pavp/storywright 1.18.1 → 1.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +99 -45
- package/bin/storywright.mjs +6 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,13 +4,18 @@
|
|
|
4
4
|
[](https://github.com/pavp/storywright/actions/workflows/ci.yml)
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Turn ambiguous inputs — vague prompts, half-baked stories, screenshots, Figma links, raw backlogs — into **Jira-ready user stories** for Claude Code. Every story comes out INVEST-checked, with Given/When/Then acceptance criteria, a Fibonacci estimate, and a clean split between what the PM reads and what the developer needs.
|
|
8
8
|
|
|
9
|
-
> Inspired by [`deanpeters/Product-Manager-Skills`](https://github.com/deanpeters/Product-Manager-Skills) (CC BY-NC-SA 4.0). Clean-room MIT rewrite — no copied content
|
|
9
|
+
> Inspired by [`deanpeters/Product-Manager-Skills`](https://github.com/deanpeters/Product-Manager-Skills) (CC BY-NC-SA 4.0). Clean-room MIT rewrite — no copied content; only the frontmatter shape, body skeleton, and splitting-pattern selection draw on patterns from that repo. All prose, taxonomy, output model, and rubrics are this repo's own. Methodological credit: Bill Wake (INVEST), Mike Cohn (*User Stories Applied*), Dan North (BDD / Given-When-Then), Richard Lawrence & Peter Green (*Humanizing Work* splitting patterns).
|
|
10
10
|
|
|
11
11
|
## What it is
|
|
12
12
|
|
|
13
|
-
A **skills pack for Claude Code
|
|
13
|
+
A **skills pack for Claude Code** — not a runtime, no LLM inside, no API calls in code. The skills are Markdown files Claude Code reads as instructions; the npm package is a thin installer that copies them into `~/.claude/skills/`. All the behavior lives in the prose.
|
|
14
|
+
|
|
15
|
+
Two design choices shape everything:
|
|
16
|
+
|
|
17
|
+
- **Two-file output (the PM↔dev split).** Every story is rendered as `story.standard.md` (PM-facing — user story, acceptance criteria, Definition of Done; zero technical detail) and `story.dev.md` (dev-facing — edge cases, analytics, risks, dependencies, the estimate, command-level DoD). The PM never wades through implementation detail; the developer never loses it.
|
|
18
|
+
- **Project-less by design.** storywright writes a *forward contract* for work that often doesn't exist yet. It does **not** read your codebase — technical specifics in the dev file are domain-knowledge inferences (marked `⚠️ Assumed:`), never scraped from whatever repo happens to be open. That keeps output deterministic and portable.
|
|
14
19
|
|
|
15
20
|
## Install
|
|
16
21
|
|
|
@@ -19,94 +24,143 @@ npm install -g @pavp/storywright
|
|
|
19
24
|
storywright install
|
|
20
25
|
```
|
|
21
26
|
|
|
22
|
-
Restart Claude Code so the skills are picked up.
|
|
27
|
+
Restart Claude Code so the skills and slash commands are picked up.
|
|
23
28
|
|
|
24
|
-
|
|
29
|
+
<details>
|
|
30
|
+
<summary>Other install paths</summary>
|
|
25
31
|
|
|
26
|
-
- **Git clone + symlink**
|
|
32
|
+
- **Git clone + symlink** (contributors):
|
|
27
33
|
```bash
|
|
28
|
-
git clone git@github.com:pavp/storywright.git
|
|
29
|
-
cd storywright
|
|
34
|
+
git clone git@github.com:pavp/storywright.git && cd storywright
|
|
30
35
|
ln -s "$(pwd)/skills" ~/.claude/skills/storywright
|
|
31
36
|
```
|
|
32
37
|
- **ZIP upload to claude.ai**:
|
|
33
38
|
```bash
|
|
34
|
-
storywright zip story-generate
|
|
35
|
-
# → dist/story-generate.zip — upload via Claude.ai UI
|
|
39
|
+
storywright zip story-generate # → dist/story-generate.zip, upload via the claude.ai UI
|
|
36
40
|
```
|
|
41
|
+
</details>
|
|
37
42
|
|
|
38
43
|
## Use
|
|
39
44
|
|
|
40
|
-
|
|
45
|
+
Each skill has a slash command (installed as `/storywright-<skill>`), or you can describe the task in plain language and Claude Code routes it.
|
|
41
46
|
|
|
42
47
|
```
|
|
43
|
-
generate
|
|
48
|
+
/storywright-story-generate Permitir login con Google
|
|
44
49
|
```
|
|
45
|
-
|
|
46
50
|
```
|
|
47
|
-
refine
|
|
51
|
+
/storywright-story-refine
|
|
48
52
|
<paste a half-baked story>
|
|
49
53
|
```
|
|
50
|
-
|
|
51
54
|
```
|
|
52
|
-
|
|
55
|
+
/storywright-story-split
|
|
56
|
+
<paste a story that visibly mixes flows>
|
|
57
|
+
```
|
|
58
|
+
```
|
|
59
|
+
/storywright-story-from-figma https://www.figma.com/file/…
|
|
53
60
|
```
|
|
61
|
+
```
|
|
62
|
+
/storywright-story-batch
|
|
63
|
+
1. Show a cart summary before payment
|
|
64
|
+
2. Apply a discount code at checkout
|
|
65
|
+
3. Handle the full payment flow…
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
storywright replies in the language of your input — paste Spanish, get Spanish.
|
|
69
|
+
|
|
70
|
+
### Example output
|
|
71
|
+
|
|
72
|
+
A `story.standard.md` (PM-facing) is plain portable Markdown that pastes cleanly into Jira Cloud, Notion, or Linear:
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
# Login con Google
|
|
54
76
|
|
|
77
|
+
**Summary:** Permitir que un visitante nuevo se autentique con su cuenta de Google.
|
|
78
|
+
|
|
79
|
+
## User Story
|
|
80
|
+
- **As a** visitante nuevo sin cuenta
|
|
81
|
+
- **I want to** iniciar sesión con mi cuenta de Google
|
|
82
|
+
- **so that** entro al producto sin crear una contraseña nueva
|
|
83
|
+
|
|
84
|
+
## Acceptance Criteria
|
|
85
|
+
**AC-1: Login exitoso con cuenta válida**
|
|
86
|
+
- **Given** el visitante está en la pantalla de login
|
|
87
|
+
- **When** toca "Continuar con Google" y autoriza una cuenta válida
|
|
88
|
+
- **Then** se crea su sesión y es redirigido al dashboard en <3s
|
|
55
89
|
```
|
|
56
|
-
|
|
57
|
-
|
|
90
|
+
|
|
91
|
+
The companion `story.dev.md` carries everything technical — including a Fibonacci estimate with an auditable breakdown:
|
|
92
|
+
|
|
93
|
+
```markdown
|
|
94
|
+
## Estimate
|
|
95
|
+
**Story Points: 5** (Fibonacci)
|
|
96
|
+
|
|
97
|
+
| Signal | Value | Weight | Contribution |
|
|
98
|
+
|--------|-------|--------|--------------|
|
|
99
|
+
| Acceptance Criteria | 1 | ×1.0 | 1.0 |
|
|
100
|
+
| Edge Cases | 5 | ×0.6 | 3.0 |
|
|
101
|
+
| Dependencies | 3 | ×1.5 | 4.5 |
|
|
102
|
+
| ...
|
|
58
103
|
```
|
|
59
104
|
|
|
60
|
-
|
|
105
|
+
See the full committed examples under [`examples/outputs/`](./examples/outputs/).
|
|
61
106
|
|
|
62
107
|
## Skills
|
|
63
108
|
|
|
64
|
-
|
|
109
|
+
Five top-level skills, each invokable as `/storywright-<name>`:
|
|
110
|
+
|
|
65
111
|
| Skill | When to use |
|
|
66
112
|
|---|---|
|
|
67
|
-
| `story-generate` |
|
|
68
|
-
| `story-refine` |
|
|
69
|
-
| `story-split` |
|
|
70
|
-
| `story-from-figma` | Figma file or frame URL → one
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
113
|
+
| `story-generate` | An ambiguous prompt, screenshot, or fresh story request → one full story |
|
|
114
|
+
| `story-refine` | An existing story that's incomplete or weakly specified → audit + fill gaps in place |
|
|
115
|
+
| `story-split` | A story that fails INVEST on Independent / Estimable / Small → epic + child stories |
|
|
116
|
+
| `story-from-figma` | A Figma file or frame URL → one story per user-goal flow |
|
|
117
|
+
| `story-batch` | A multi-item backlog → one story per item in a single pass, plus a backlog summary |
|
|
118
|
+
|
|
119
|
+
They never split silently — a split always waits for your approval. And no story is ever auto-grounded against your open repo.
|
|
120
|
+
|
|
121
|
+
### Components
|
|
122
|
+
|
|
123
|
+
All five top-level skills compose the same eleven components:
|
|
124
|
+
|
|
125
|
+
- `storywright-base` — the shared rulebook: canonical story shape, the PM↔dev split, language detection, the mechanical pre-split test, INVEST handling, and the project-less rule. Everything else inherits from it.
|
|
126
|
+
- `clarification-questions` — the minimum critical questions to ask before drafting
|
|
127
|
+
- `acceptance-criteria` — Given/When/Then acceptance criteria
|
|
128
|
+
- `invest-checklist` — INVEST self-check, mapping the verdict to the next action
|
|
129
|
+
- `definition-of-done` — DoD baseline (acceptance-only in PM files, full command-level in the dev file)
|
|
77
130
|
- `business-rules` — policy invariants
|
|
78
|
-
- `edge-cases` —
|
|
79
|
-
- `analytics-events` — funnel events
|
|
80
|
-
- `risks-and-dependencies` — risks
|
|
81
|
-
- `
|
|
131
|
+
- `edge-cases` — eight technical failure axes → dev file only
|
|
132
|
+
- `analytics-events` — funnel events + payload taxonomy with a PII boundary → dev file only
|
|
133
|
+
- `risks-and-dependencies` — risks and blocking dependencies with owner + status → dev file only
|
|
134
|
+
- `estimation` — relative Fibonacci story points from countable signals (ACs, edge cases, deps, risks) → dev file only
|
|
135
|
+
- `story-formatter` — renders the two-file output
|
|
82
136
|
|
|
83
|
-
## Multimodal
|
|
137
|
+
## Multimodal input
|
|
84
138
|
|
|
85
139
|
| Input | Runtime | Notes |
|
|
86
140
|
|---|---|---|
|
|
87
141
|
| Text | Native | Always available |
|
|
88
|
-
| Images (PNG/JPG) | Claude vision | Drop file into chat |
|
|
89
|
-
| Figma
|
|
142
|
+
| Images (PNG / JPG) | Claude vision | Drop the file into chat |
|
|
143
|
+
| Figma | MCP Figma server | See `skills/story-from-figma/mcp-figma-notes.md` |
|
|
144
|
+
|
|
145
|
+
When you pass several at once (text + image + Figma), storywright follows a source-priority matrix and surfaces genuine conflicts as blocking clarifications — it never silently picks a winner.
|
|
90
146
|
|
|
91
147
|
## CLI
|
|
92
148
|
|
|
93
149
|
```bash
|
|
94
|
-
storywright install # copy skills
|
|
150
|
+
storywright install # copy skills + slash commands into ~/.claude/
|
|
95
151
|
storywright list # show available + installed skills
|
|
96
|
-
storywright validate # lint skill files (frontmatter +
|
|
97
|
-
storywright zip <skill-name> # build a ZIP for
|
|
98
|
-
storywright uninstall # remove from ~/.claude/
|
|
152
|
+
storywright validate # lint skill files (frontmatter + composition)
|
|
153
|
+
storywright zip <skill-name> # build a ZIP for claude.ai upload
|
|
154
|
+
storywright uninstall # remove from ~/.claude/
|
|
99
155
|
```
|
|
100
156
|
|
|
101
157
|
## Multi-provider stance
|
|
102
158
|
|
|
103
|
-
Skills are written in **format-neutral Markdown** with optional `<claude-specific>`
|
|
159
|
+
Skills are written in **format-neutral Markdown** with optional `<claude-specific>` blocks. Non-Claude LLMs ignore those blocks; Claude reads them. No adapters are shipped — that's a downstream concern.
|
|
104
160
|
|
|
105
161
|
## Releases
|
|
106
162
|
|
|
107
|
-
`semantic-release` + Conventional Commits + GitHub Actions + npm Trusted Publishing (OIDC).
|
|
108
|
-
|
|
109
|
-
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
163
|
+
`semantic-release` + Conventional Commits + GitHub Actions + npm Trusted Publishing (OIDC). Merge to `main` → version bump → publish, on a single `latest` channel. See [CONTRIBUTING.md](./CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md) (the guide for coding agents working in this repo).
|
|
110
164
|
|
|
111
165
|
## License
|
|
112
166
|
|
package/bin/storywright.mjs
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
import { fileURLToPath } from "node:url";
|
|
3
3
|
import { dirname, resolve } from "node:path";
|
|
4
4
|
import { spawn } from "node:child_process";
|
|
5
|
+
import pkg from "../package.json" with { type: "json" };
|
|
5
6
|
|
|
6
7
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
7
8
|
const scriptsDir = resolve(__dirname, "..", "scripts");
|
|
@@ -25,11 +26,16 @@ Usage:
|
|
|
25
26
|
storywright list Show available + installed skills
|
|
26
27
|
storywright zip <skill-name> Build a ZIP for Claude.ai upload
|
|
27
28
|
storywright validate Lint skill files (frontmatter + structure)
|
|
29
|
+
storywright --version Print the installed version
|
|
28
30
|
|
|
29
31
|
Repo: https://github.com/pavp/storywright`);
|
|
30
32
|
process.exit(exit);
|
|
31
33
|
}
|
|
32
34
|
|
|
35
|
+
if (cmd === "--version" || cmd === "-v") {
|
|
36
|
+
console.log(pkg.version);
|
|
37
|
+
process.exit(0);
|
|
38
|
+
}
|
|
33
39
|
if (!cmd || cmd === "--help" || cmd === "-h") usage(0);
|
|
34
40
|
if (!COMMANDS[cmd]) {
|
|
35
41
|
console.error(`Unknown command: ${cmd}\n`);
|
package/package.json
CHANGED