@pavp/storywright 1.2.0 → 1.4.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,20 @@
+---
+description: Audit an existing user story and fill gaps in place (supports text + optional image / Figma companion)
+argument-hint: <paste existing story> [+ attach image or paste Figma URL for cross-source check]
+---
+
+Invoke the `story-refine` skill from the storywright pack to audit and improve this story:
+
+$ARGUMENTS
+
+Follow the skill's procedure:
+
+0. Detect companion sources (image, figma-link). If present, run conflict detection between the story text and the design BEFORE filling sections. Surface conflicts as BLOCKING clarifications; never silently rewrite the story to match the design.
+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,25 @@
+---
+description: Split an oversize story into an epic + child stories using INVEST + Humanizing Work patterns
+argument-hint: <paste oversize story> [+ optional image / Figma URL for flow inventory]
+---
+
+Invoke the `story-split` skill from the storywright pack to split this story:
+
+$ARGUMENTS
+
+Follow the skill's procedure:
+
+0. Detect companion sources (image, figma-link). If present, use them to inventory candidate sub-flows (prototype links, frame structure). If Figma shows N flows but text mentions K (K < N), surface as BLOCKING clarification before drafting the split plan. Text is canonical for scope of the epic; design is canonical for flow structure.
+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.2.0",
+  "version": "1.4.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/story-refine/SKILL.md

@@ -6,6 +6,8 @@ intent: Refinement skill for stories that already exist but are incomplete or we
 version: 1.0.0
 inputs:
   - text
+  - image
+  - figma-link
 outputs:
   - story.jira-wiki.md
   - story.standard.md
@@ -37,9 +39,19 @@ For oversized stories that fail `Independent / Estimable / Small`, hand off to `
 ## Inputs & interpretation
 
 - **text** — existing story. Detect which sections are present, which are missing, which are weak.
+- **image (optional)** — companion screenshot/mockup the story references. Use to validate UI claims and surface missing edge cases / states.
+- **figma-link (optional)** — companion design. Use to enrich Technical Considerations, Edge Cases (states shown but not in story), and to detect scope mismatches.
+
+### Mixed inputs
+
+When the user pastes a story plus an image / Figma link, apply the source-priority matrix from `[[story-generate]]` "Mixed inputs" section:
+- Story text remains canonical for `User Story / Scope / Business Goal`.
+- Image/Figma is canonical for `Components / States / Edge Cases / UX flow`.
+- Surface conflicts as BLOCKING clarifications (e.g., story says "single provider" but Figma shows multiple). Never silently rewrite the story to match the design without asking.
 
 ## Application (step-by-step)
 
+0. **Detect companion sources** (image, figma-link). If present, run conflict detection against the story text BEFORE filling sections. Add detected conflicts to the gap-check output.
 1. **Parse the existing story.** Map content into the 15-section taxonomy. Note: present / missing / weak.
 2. **Gap-check the weak sections** via `[[clarification-questions]]`. If gaps are inferrable, mark `⚠️ Assumed` and proceed. Only ask BLOCKING questions.
 3. **Detect language** of the existing story; preserve it in the output.

package/skills/story-split/SKILL.md

@@ -6,6 +6,8 @@ intent: Splitting skill that uses the INVEST failure reasons (from invest-checkl
 version: 1.0.0
 inputs:
   - text
+  - image
+  - figma-link
 outputs:
   - split-plan.md
   - epic.md
@@ -28,6 +30,16 @@ When a story is an epic in disguise, splitting badly is worse than not splitting
 ## Inputs & interpretation
 
 - **text** — the oversize story (or a one-line goal that's clearly epic-scoped).
+- **image (optional)** — companion mockup. Use to validate scope and reveal hidden sub-flows the text doesn't mention.
+- **figma-link (optional)** — companion design. Often makes splitting easier: prototype links and frame structure reveal natural flow boundaries that map to children.
+
+### Mixed inputs
+
+When the user provides text + image / Figma alongside the story:
+- **Text is canonical for User Story / Scope / Business Goal** of the epic.
+- **Figma / image is canonical for flow structure** — use prototype links to enumerate candidate sub-flows. Each flow is a candidate child story.
+- **Conflict handling:** if Figma shows N flows but text only mentions K (K < N), surface this in the gap-check via `[[clarification-questions]]` BEFORE drafting the split plan. Ask: "Figma includes flows for X, Y, Z — include in this epic, or scope out?" Never silently expand or shrink scope.
+- See `[[story-generate]]` "Mixed inputs" for the full source-priority matrix.
 
 ## Application (step-by-step)