@pavp/storywright 1.1.0 → 1.3.0

package/.claude-plugin/plugin.json

@@ -21,5 +21,11 @@
     "skills/_components/risks-and-dependencies",
     "skills/_components/jira-wiki-formatter"
   ],
+  "commands": [
+    "commands/story-generate.md",
+    "commands/story-refine.md",
+    "commands/story-split.md",
+    "commands/story-from-figma.md"
+  ],
   "tags": ["product-management", "user-stories", "jira", "agile", "invest"]
 }

package/commands/story-from-figma.md

@@ -0,0 +1,19 @@
+---
+description: Generate user stories from a Figma file or frame URL (uses MCP Figma when available)
+argument-hint: <Figma URL> [+ optional text prompt or screenshots]
+---
+
+Invoke the `story-from-figma` skill from the storywright pack to analyze:
+
+$ARGUMENTS
+
+Follow the skill's procedure:
+
+1. Phase 0 — verify MCP Figma server is available. If not, ask the user to either install one, paste PNG exports, or describe the flows.
+2. Phase 0.5 — detect companion text / screenshots. Use text as canonical for `User Story / Scope / Business Goal`; Figma as canonical for `Components / States / Flows`. Surface conflicts as BLOCKING clarifications. Never silently pick a winner.
+3. Phase 1 — inventory pages and frames; group by prototype links into flows.
+4. Phase 2 — per flow: identify goal, entry point, states, components. Score per-inference confidence (HIGH/MEDIUM/LOW). Mark MEDIUM/LOW with `> ⚠️ Assumed:` blockquotes.
+5. Phase 3 — for any flow that fails INVEST (Small), hand off to `/story-split` before generating.
+6. Phase 4 — invoke `story-generate` per flow. Emit dual outputs + `flow-summary.md` mapping stories → frames for traceability.
+
+Output in the input language (text language wins if mixed inputs).

package/commands/story-generate.md

@@ -0,0 +1,21 @@
+---
+description: Transform an ambiguous prompt, screenshot, or Figma link into a Jira-ready user story
+argument-hint: <prompt | paste story | attach image | figma URL>
+---
+
+Invoke the `story-generate` skill from the storywright pack to handle the following input:
+
+$ARGUMENTS
+
+Follow the skill's full procedure:
+
+1. Detect input types present (text / image / figma-link / mixed).
+2. If multi-source, apply the source-priority matrix and surface conflicts as BLOCKING clarifications BEFORE drafting.
+3. Run gap check via `clarification-questions` component. Ask at most 3 critical questions if anything is blocking.
+4. Fill the CORE sections (Title, Summary, User Story, Acceptance Criteria, Definition of Done).
+5. Fill optional sections only if they have real content (drop empty ones).
+6. Run INVEST self-check. If NOT A STORY / NEEDS REFINEMENT / RUN A SPIKE / SPLIT RECOMMENDED — STOP and hand off accordingly.
+7. Render dual outputs: `story.jira-wiki.md` (Jira wiki markup) and `story.standard.md` (CommonMark).
+8. If clarifications remain, emit `clarifications.md` and mark the story DRAFT.
+
+Output in the input language (preserve es/en).

package/commands/story-refine.md

@@ -0,0 +1,19 @@
+---
+description: Audit an existing user story and fill gaps in place
+argument-hint: <paste existing story>
+---
+
+Invoke the `story-refine` skill from the storywright pack to audit and improve this story:
+
+$ARGUMENTS
+
+Follow the skill's procedure:
+
+1. Parse the existing story into the section taxonomy. Mark each section: present / missing / weak.
+2. Gap-check weak sections via `clarification-questions`. Ask only BLOCKING questions.
+3. Detect language and preserve it in output.
+4. Fill missing/weak sections via component skills. Preserve original wording where good.
+5. Append a "Refinement log" at the end listing what changed.
+6. Run INVEST. If verdict is `SPLIT RECOMMENDED`, stop and recommend `/story-split` instead.
+7. Render dual outputs via `jira-wiki-formatter`.
+8. Emit `clarifications.md` if assumptions remain unresolved.

package/commands/story-split.md

@@ -0,0 +1,24 @@
+---
+description: Split an oversize story into an epic + child stories using INVEST + Humanizing Work patterns
+argument-hint: <paste oversize story>
+---
+
+Invoke the `story-split` skill from the storywright pack to split this story:
+
+$ARGUMENTS
+
+Follow the skill's procedure:
+
+1. Run `invest-checklist` and apply the pre-split gates:
+   - If Valuable FAILS → NOT A STORY. Don't split. Stop.
+   - If Testable / Negotiable FAILS → fix in place, don't split. Stop.
+   - If Estimable fails on unknowns → recommend a spike. Stop.
+   - If Independent / Estimable / Small fails → continue.
+2. Apply the 9-pattern catalog in order. Name the first pattern that fits + the core complexity (meta-pattern).
+3. Calibrate to Cynefin domain (Obvious/Complicated vs Complex vs Chaotic).
+4. Draft a split plan as a Markdown table with rationale, pattern, and proposed children.
+5. Run the strategic evaluation: does the split reveal low-value work? Are children equal-sized?
+6. STOP and ask the user to approve / adjust / cancel. Never auto-split.
+7. After approval: write `epic.md` + one stub per child + `split-plan.md` decision trail.
+8. Coherence check + recursive re-split for children still >1 sprint.
+9. Save artifacts under `./stories/<epic-slug>/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/storywright",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "PM Skills pack for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
   "keywords": [
     "claude",
@@ -38,6 +38,7 @@
     "bin/",
     "scripts/",
     "skills/",
+    "commands/",
     ".claude-plugin/",
     "README.md",
     "LICENSE"

package/scripts/install-skills.mjs

@@ -1,20 +1,50 @@
 #!/usr/bin/env node
 import { homedir } from "node:os";
-import { cp, mkdir, rm } from "node:fs/promises";
+import { cp, mkdir, readdir, rm, unlink } from "node:fs/promises";
 import { join } from "node:path";
-import { SKILLS_DIR, pathExists } from "./lib/skills.mjs";
+import { REPO_ROOT, SKILLS_DIR, pathExists } from "./lib/skills.mjs";
 
-const target = join(homedir(), ".claude", "skills", "storywright");
+const skillsTarget = join(homedir(), ".claude", "skills", "storywright");
+const commandsDir = join(homedir(), ".claude", "commands");
+const commandsSource = join(REPO_ROOT, "commands");
+const COMMAND_PREFIX = "storywright-";
 
-async function main() {
-  if (await pathExists(target)) {
-    await rm(target, { recursive: true, force: true });
-    console.log(`• Removed existing ${target}`);
+async function installSkills() {
+  if (await pathExists(skillsTarget)) {
+    await rm(skillsTarget, { recursive: true, force: true });
+    console.log(`• Removed existing ${skillsTarget}`);
+  }
+  await mkdir(skillsTarget, { recursive: true });
+  await cp(SKILLS_DIR, skillsTarget, { recursive: true });
+  console.log(`✓ Installed skills to ${skillsTarget}`);
+}
+
+async function installCommands() {
+  if (!(await pathExists(commandsSource))) {
+    console.log("• No commands/ folder in source; skipping slash command install.");
+    return;
+  }
+  await mkdir(commandsDir, { recursive: true });
+
+  // Remove old storywright-* commands so renames don't leave orphans.
+  const existing = await readdir(commandsDir).catch(() => []);
+  for (const f of existing) {
+    if (f.startsWith(COMMAND_PREFIX)) await unlink(join(commandsDir, f));
   }
-  await mkdir(target, { recursive: true });
-  await cp(SKILLS_DIR, target, { recursive: true });
-  console.log(`✓ Installed skills to ${target}`);
-  console.log(`  Restart Claude Code (or reload) for skills to be picked up.`);
+
+  const sources = await readdir(commandsSource);
+  for (const f of sources) {
+    if (!f.endsWith(".md")) continue;
+    await cp(join(commandsSource, f), join(commandsDir, `${COMMAND_PREFIX}${f}`));
+  }
+  console.log(`✓ Installed slash commands to ${commandsDir} (prefix: ${COMMAND_PREFIX})`);
+}
+
+async function main() {
+  await installSkills();
+  await installCommands();
+  console.log(`  Restart Claude Code for changes to be picked up.`);
+  console.log(`  After restart, try: /storywright-story-generate <your prompt>`);
 }
 
 main().catch((err) => {

package/scripts/uninstall-skills.mjs

@@ -1,18 +1,38 @@
 #!/usr/bin/env node
 import { homedir } from "node:os";
-import { rm } from "node:fs/promises";
+import { readdir, rm, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { pathExists } from "./lib/skills.mjs";
 
-const target = join(homedir(), ".claude", "skills", "storywright");
+const skillsTarget = join(homedir(), ".claude", "skills", "storywright");
+const commandsDir = join(homedir(), ".claude", "commands");
+const COMMAND_PREFIX = "storywright-";
 
 async function main() {
-  if (!(await pathExists(target))) {
-    console.log(`• Nothing to uninstall (${target} does not exist)`);
-    return;
+  let removed = 0;
+
+  if (await pathExists(skillsTarget)) {
+    await rm(skillsTarget, { recursive: true, force: true });
+    console.log(`✓ Removed ${skillsTarget}`);
+    removed++;
+  }
+
+  if (await pathExists(commandsDir)) {
+    const files = await readdir(commandsDir);
+    let cmdsRemoved = 0;
+    for (const f of files) {
+      if (f.startsWith(COMMAND_PREFIX)) {
+        await unlink(join(commandsDir, f));
+        cmdsRemoved++;
+      }
+    }
+    if (cmdsRemoved > 0) {
+      console.log(`✓ Removed ${cmdsRemoved} slash commands from ${commandsDir}`);
+      removed++;
+    }
   }
-  await rm(target, { recursive: true, force: true });
-  console.log(`✓ Removed ${target}`);
+
+  if (removed === 0) console.log("• Nothing to uninstall.");
 }
 
 main().catch((err) => {

package/skills/_components/clarification-questions/SKILL.md

@@ -37,6 +37,7 @@ Invoked by `story-generate`, `story-refine`, `story-split`, and `story-from-figm
    - **Data inputs** (auth scope, identifiers, format)
    - **Constraints** (platform, accessibility, locale, SLA)
    - **Out-of-scope assumptions**
+   - **Multi-source conflicts** (when text + image + Figma are all provided): explicit disagreement between sources MUST be surfaced. Examples: text says "Google only" but Figma shows multiple providers; text mentions 1 flow but Figma shows 3; image shows error state not mentioned in text. Never silently pick a winner.
 2. For each axis, mark one of: ANSWERED · INFERRABLE · BLOCKING.
 3. Drop `ANSWERED`. For `INFERRABLE`, do NOT ask — mark assumption in the story output with `> ⚠️ Assumed:`.
 4. For `BLOCKING`, draft questions. Limit to **3 questions max per round**. Prefer multiple-choice or yes/no.

package/skills/story-from-figma/SKILL.md

@@ -47,6 +47,14 @@ A Figma file usually represents N screens / N flows. This skill maps that visual
    - Ask the user to either (a) install an MCP Figma server, (b) export the relevant frames as PNGs and drop them in chat, or (c) paste a textual description of the flows.
    - Continue under the chosen fallback. The rest of the skill works with screenshots via Claude vision.
 
+### Phase 0.5 — Detect companion inputs
+
+Before extracting from Figma, check whether the user attached:
+- **Accompanying text** (goal, story draft, constraints) — treat as canonical for `User Story / Scope / Business Goal`. Figma is canonical for `Components / States / Flows`.
+- **Reference screenshots** — usually redundant when Figma is available; use only if Figma frames are missing states the screenshots show.
+
+If text + Figma both describe the same flow but disagree (e.g., text says "single page form", Figma shows multi-step wizard), **surface the conflict** in clarifications and ask before drafting. Do NOT silently pick a winner. See `[[story-generate]]` "Mixed inputs" section for source priority.
+
 ### Phase 1 — Inventory
 
 1. List pages in the file (if MCP allows).

package/skills/story-generate/SKILL.md

@@ -49,9 +49,37 @@ Use vision. Extract:
 ### Figma links
 If MCP Figma is available (see `[[story-from-figma]]`), use it to enumerate frames, components, navigation. If not, fall back to asking the user to drop screenshots.
 
+### Mixed inputs (text + image + Figma)
+
+The skill is designed to **fuse multiple sources** in a single invocation. Common pairings:
+
+- **Text + screenshot** — text states the goal, image shows the proposed UI. Use text for `User Story / Goal / Scope`, image for `Components / States / Edge cases / UX flow`.
+- **Text + Figma link** — text gives intent, Figma gives implementation surface. Use text for `User Story / Business goal`, Figma for `Technical considerations / Edge cases / Components / Multi-screen flows`.
+- **Text + image + Figma** — full triangulation. Highest fidelity; also highest chance of conflict.
+
+**Source priority (when sources disagree):**
+
+| Section | Primary | Secondary | Tertiary |
+|---|---|---|---|
+| User Story / Goal | Text | Figma (frame titles, callouts) | Image |
+| Business Rules / Scope | Text | Figma | Image |
+| UI Components / States | Figma | Image | Text |
+| Edge Cases | Figma + Image (states shown) | Text | — |
+| Technical Considerations | Figma (component naming, design system refs) | Text | Image |
+| Acceptance Criteria | Triangulate all three | — | — |
+
+**Conflict handling:**
+
+1. **Detect the conflict explicitly.** Example: text says "Google only" but Figma shows Google + Facebook buttons.
+2. **Do NOT silently pick a winner.** Surface the conflict in `clarifications.md` as a BLOCKING question: *"Text says X but design shows Y — which is canonical?"*
+3. **If the user is in-session, ask immediately** before drafting. If running batch, mark the story `DRAFT` and write both options in scope/out-of-scope with `> ⚠️ Conflict:` annotation.
+4. **Scope coverage check:** if Figma shows N flows but text describes 1, ask whether to (a) generate 1 story bounded to text, (b) generate N stories from Figma, or (c) generate 1 story + flag remaining flows as roadmap.
+
 ## Application (step-by-step)
 
-1. **Detect input type** (text | image | figma-link | mixed). Branch accordingly.
+1. **Detect input types present** — text, image, figma-link, or any combination. Branch accordingly:
+   - **Single source** → process as before.
+   - **Mixed sources** → run the "Mixed inputs" protocol above, including source-priority lookup and explicit conflict detection BEFORE drafting.
 2. **Intake gap check** — invoke `[[clarification-questions]]`. If it returns BLOCKING questions, **ask first** before drafting.
 3. **Detect language** of input (es | en | other). Output in the input language.
 4. **Draft skeleton** of the structured story (all 15 sections from the template).