@pavp/storywright 1.12.0 → 1.12.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "storywright",
-  "version": "0.1.0",
+  "version": "1.12.0",
   "description": "PM skills for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
   "author": "pavp",
   "license": "MIT",
@@ -11,6 +11,7 @@
     "skills/story-refine",
     "skills/story-split",
     "skills/story-from-figma",
+    "skills/_components/storywright-base",
     "skills/_components/clarification-questions",
     "skills/_components/acceptance-criteria",
     "skills/_components/invest-checklist",

package/README.md

@@ -26,7 +26,8 @@ Alternatives:
 - **Git clone + symlink** for contributors:
   ```bash
   git clone git@github.com:pavp/storywright.git
-  ln -s "$(pwd)/storywright/skills" ~/.claude/skills/storywright
+  cd storywright
+  ln -s "$(pwd)/skills" ~/.claude/skills/storywright
   ```
 - **ZIP upload to claude.ai**:
   ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/storywright",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "PM Skills pack for Claude Code — turn ambiguous inputs (prompts, screenshots, Figma links) into Jira-ready user stories.",
   "keywords": [
     "claude",

package/scripts/install-skills.mjs

@@ -17,6 +17,10 @@ async function installSkills() {
   }
   await mkdir(skillsTarget, { recursive: true });
   await cp(SKILLS_DIR, skillsTarget, { recursive: true });
+  // Verify the copy landed — cp can silently no-op on permission quirks.
+  if (!(await pathExists(join(skillsTarget, "_components")))) {
+    throw new Error(`copy verification failed: ${skillsTarget}/_components missing after install`);
+  }
   console.log(`✓ Installed skills to ${skillsTarget}`);
 }
 
@@ -49,7 +53,9 @@ async function ensureGlobalGitignore() {
     globalIgnorePath = join(homedir(), ".gitignore_global");
     execSync(`git config --global core.excludesFile "${globalIgnorePath}"`);
   }
-  if (globalIgnorePath.startsWith("~")) {
+  if (globalIgnorePath === "~") {
+    globalIgnorePath = homedir();
+  } else if (globalIgnorePath.startsWith("~/")) {
     globalIgnorePath = join(homedir(), globalIgnorePath.slice(2));
   }
 

package/scripts/validate-skills.mjs

@@ -57,14 +57,31 @@ async function main() {
     }
   }
 
+  const referencedComponents = new Set();
   for (const f of files) {
     const skill = await loadSkill(f);
     const composes = Array.isArray(skill.frontmatter.composes) ? skill.frontmatter.composes : [];
     for (const dep of composes) {
       if (!componentPaths.has(dep)) {
         errors.push(`${skill.relPath}: composes references missing component '${dep}'`);
+      } else {
+        referencedComponents.add(dep);
       }
     }
+    // Body [[name]] links also count as a reference, so a component used only via
+    // prose cross-link (not composed) is not flagged as orphaned.
+    for (const m of skill.body.matchAll(/\[\[([a-z0-9-]+)\]\]/g)) {
+      referencedComponents.add(`_components/${m[1]}`);
+    }
+  }
+
+  // Orphan check: every component must be referenced by at least one skill
+  // (via composes or a body [[link]]). Catches dead/stale components that
+  // pass the existence check but are wired to nothing.
+  for (const comp of componentPaths) {
+    if (!referencedComponents.has(comp)) {
+      errors.push(`${comp}: orphaned component — referenced by no skill (composes or [[link]])`);
+    }
   }
 
   if (errors.length) {

package/scripts/zip-skill.mjs

@@ -11,16 +11,34 @@ if (!skillName) {
   process.exit(1);
 }
 
+function hasZip() {
+  const probe = spawnSync("zip", ["-v"], { stdio: "ignore" });
+  return !probe.error;
+}
+
+async function resolveSourceDir() {
+  const topDir = join(SKILLS_DIR, skillName);
+  if (await pathExists(topDir)) return topDir;
+  const compDir = join(SKILLS_DIR, "_components", skillName);
+  if (await pathExists(compDir)) return compDir;
+  return null;
+}
+
 async function main() {
-  const skillDir = join(SKILLS_DIR, skillName);
-  if (!(await pathExists(skillDir))) {
-    const compDir = join(SKILLS_DIR, "_components", skillName);
-    if (!(await pathExists(compDir))) {
-      console.error(`✗ Skill not found: ${skillName}`);
-      process.exit(1);
-    }
+  const sourceDir = await resolveSourceDir();
+  if (!sourceDir) {
+    console.error(`✗ Skill not found: ${skillName}`);
+    process.exit(1);
   }
-  const sourceDir = (await pathExists(skillDir)) ? skillDir : join(SKILLS_DIR, "_components", skillName);
+  if (!(await pathExists(join(sourceDir, "SKILL.md")))) {
+    console.error(`✗ ${skillName} has no SKILL.md — refusing to zip an invalid skill`);
+    process.exit(1);
+  }
+  if (!hasZip()) {
+    console.error("✗ `zip` not found on PATH. Install it (e.g. `brew install zip` / `apt-get install zip`) and retry.");
+    process.exit(127);
+  }
+
   const outDir = join(REPO_ROOT, "dist");
   if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
 

package/skills/_components/analytics-events/SKILL.md

@@ -3,12 +3,12 @@ name: analytics-events
 description: Propose analytics/event tracking for a story. Names events, payloads, and trigger points. Returns only the analytics block, ready for ProductOps to map.
 trigger: "internal use by story-* skills"
 intent: Component skill that drafts a small, opinionated set of analytics events using a consistent naming convention.
-version: 1.0.0
+version: 2.0.0
 inputs:
   - story-context
   - acceptance-criteria
 outputs:
-  - analytics-events-block
+  - analytics-events-block (dev.md only)
 ---
 
 ## Purpose
@@ -17,7 +17,7 @@ Stories without analytics are stories without feedback. Propose the minimum set
 
 ## When to use
 
-After acceptance criteria are drafted; events should align to observable AC outcomes.
+**Dev-file only.** Invoked while rendering `story.dev.md`, after acceptance criteria are drafted; events align to observable AC outcomes. Event names, payloads, and PII boundaries are technical detail — they belong in `story.dev.md`, never the PM-facing files (`[[storywright-base]]` rule 3).
 
 ## Inputs & interpretation
 
@@ -42,7 +42,7 @@ After acceptance criteria are drafted; events should align to observable AC outc
    - `🔧 ops` — feeds error monitoring
    - `💰 revenue` — feeds growth metrics
 5. Note retention/PII boundaries explicitly when sensitive (e.g., emails hashed).
-6. Emit under `### Analytics / Eventos`.
+6. Emit under `### Analytics / Eventos` **inside `story.dev.md`**.
 
 Example block:
 

package/skills/_components/business-rules/SKILL.md

@@ -3,7 +3,7 @@ name: business-rules
 description: Extract and articulate business rules a story must honor. Distinguish rules (always true) from acceptance criteria (testable on this story). Returns only the rules block.
 trigger: "internal use by story-* skills"
 intent: Component skill that surfaces invariants, policies, and constraints that bound a story without being acceptance criteria themselves.
-version: 1.0.0
+version: 2.0.0
 inputs:
   - story-context
   - domain-hints
@@ -17,7 +17,7 @@ Business rules are **policy invariants** the story must respect. They survive ac
 
 ## When to use
 
-After the story body is drafted, before ACs are finalized — so ACs can reference relevant rules.
+After the story body is drafted, before ACs are finalized — so ACs can reference relevant rules. Business Rules are an **optional PM section** (see `[[jira-wiki-formatter]]` — emit in `story.standard.md` / `story.jira-wiki.md` only when non-empty) AND are mirrored in `story.dev.md`. They are policy invariants, not technical detail, so unlike edge-cases they are not dev-only.
 
 ## Inputs & interpretation
 

package/skills/_components/definition-of-done/SKILL.md

@@ -3,7 +3,7 @@ name: definition-of-done
 description: Produce a Definition of Done block for a user story. Covers code, tests, analytics, docs, accessibility, and release gates. Returns only the DoD block.
 trigger: "internal use by story-* skills"
 intent: Component skill that emits a baseline DoD aligned to common product/eng standards. Customizable via project-level overrides documented in the story.
-version: 1.0.0
+version: 2.0.0
 inputs:
   - story-context
   - technical-considerations
@@ -17,7 +17,7 @@ A Definition of Done is the contract for "shippable". It must be **checkable, ob
 
 ## When to use
 
-Invoked by `story-generate` after acceptance criteria and technical considerations are drafted.
+Invoked after acceptance criteria and technical considerations are drafted. DoD is **dual-rendered** (see `[[jira-wiki-formatter]]`): the PM-facing files (`story.standard.md` / `story.jira-wiki.md`) carry the **acceptance-only** DoD (no CLI commands, no file-level criteria); `story.dev.md` carries the **full** DoD including CLI commands (`npm run test`) and file-level lines. Produce both projections from the baseline below: PM projection = drop command/file lines; dev projection = keep everything.
 
 ## Inputs & interpretation
 

package/skills/_components/edge-cases/SKILL.md

@@ -3,11 +3,11 @@ name: edge-cases
 description: Enumerate edge cases for a story. Covers boundary, concurrency, network, data, permission, and UX-state failures. Returns only the edge-cases block.
 trigger: "internal use by story-* skills"
 intent: Component skill that systematically generates edge cases across known failure axes so acceptance criteria can cover them.
-version: 1.0.0
+version: 2.0.0
 inputs:
   - story-context
 outputs:
-  - edge-cases-block
+  - edge-cases-block (dev.md only)
 ---
 
 ## Purpose
@@ -16,7 +16,7 @@ Edge cases are how engineers find latent risk. Generate them **before** acceptan
 
 ## When to use
 
-Invoked by `story-generate` after the story body and business rules are drafted; output feeds `[[acceptance-criteria]]`.
+**Dev-file only.** Invoked while rendering `story.dev.md` (the dev-facing file), never the PM-facing `story.standard.md` / `story.jira-wiki.md`. `[[storywright-base]]` rule 3 forbids an Edge Cases section in the PM story body — this output lands exclusively in `story.dev.md`. It still informs AC failure paths (`[[acceptance-criteria]]`): the AC covers the observable behavior in the PM files; the enumerated technical edge detail lives in dev.md.
 
 ## Inputs & interpretation
 
@@ -37,7 +37,7 @@ Walk these axes and pick the ones that apply:
 
 For each applicable axis, write 1–2 concrete cases. Keep each ≤1 sentence.
 
-Emit under `### Edge Cases`:
+Emit under `### Edge Cases` **inside `story.dev.md`** (never the PM files):
 
 ```
 ### Edge Cases

package/skills/_components/risks-and-dependencies/SKILL.md

@@ -3,13 +3,13 @@ name: risks-and-dependencies
 description: Surface technical, product, and organizational risks plus blocking dependencies for a story. Each item has owner, likelihood, mitigation. Returns only the risks+deps block.
 trigger: "internal use by story-* skills"
 intent: Component skill that turns hidden assumptions into tracked risks and dependencies so PMs and tech leads can act on them.
-version: 1.0.0
+version: 2.0.0
 inputs:
   - story-context
   - business-rules
   - technical-considerations
 outputs:
-  - risks-and-dependencies-block
+  - risks-and-dependencies-block (dev.md only)
 ---
 
 ## Purpose
@@ -18,7 +18,7 @@ Risks and dependencies that aren't written down end up as outages or missed laun
 
 ## When to use
 
-Late in `story-generate`, after business rules and technical considerations are drafted — those inform what's risky.
+**Dev-file only.** Invoked while rendering `story.dev.md`, after business rules and technical considerations are drafted — those inform what's risky. Risks and dependencies reference infra, SDKs, env vars, and ownership — technical/delivery detail that belongs in `story.dev.md`, not the PM-facing files (`[[storywright-base]]` rule 3 bans Dependencies-as-prose in the PM body; PM files link Jira tickets only).
 
 ## Inputs & interpretation
 
@@ -41,7 +41,7 @@ Late in `story-generate`, after business rules and technical considerations are
    - **Operational** (oncall toil, monitoring gap)
 4. For each risk: `<risk> · likelihood (L/M/H) · impact (L/M/H) · mitigation`
 5. If a risk is high-impact AND high-likelihood, flag it `🚨` so it gets attention in review.
-6. Emit under two subheadings: `### Dependencias` and `### Riesgos` (or English).
+6. Emit under two subheadings: `### Dependencias` and `### Riesgos` (or English) **inside `story.dev.md`**.
 
 Example:
 

package/skills/_components/storywright-base/SKILL.md

@@ -3,7 +3,7 @@ name: storywright-base
 description: Shared base behavior for all storywright top-level skills. Hard rules, canonical output, terminal-only Q, context schema, mechanical deps, V audit, language detect.
 trigger: "internal use by story-* skills"
 intent: Component skill that holds the v2.2 baseline. Top-level skills (story-generate, story-refine, story-split, story-from-figma) compose this and add only their source-specific behavior on top.
-version: 2.2.0
+version: 2.3.0
 inputs:
   - none
 outputs:
@@ -31,13 +31,15 @@ If you are reading this through a top-level skill, treat every rule below as non
    - ONE AC Scenario (one Given chain + one `When` + one `Then`).
    If the input naturally needs >1 `When`/`Then`, the skill MUST stop the single-story path and route to `[[story-split]]`.
 
-3. **No mini-PRDs.** PROHIBITED sections in any story output:
+3. **No mini-PRDs in the PM story body.** PROHIBITED in `story.standard.md` / `story.jira-wiki.md`:
    - Non-Functional Requirements blocks (a11y/i18n/perf/tokens) — DoD only.
    - Edge Cases enumerated as their own section — fold into AC failure paths.
    - Dependencies as prose — Jira ticket links only.
    - Per-claim visual specs (pixel measurements, hex inferences) inline — use single banner (rule 5).
    - Logs >3 lines (>5 if SPLIT verdict).
 
+3a. **Technical detail lives in `story.dev.md`.** The content rule 3 bans from the PM body is NOT discarded — it is rendered in the dev-facing file. Edge cases, analytics events, risks/dependencies, technical considerations, and the command-level DoD belong in `story.dev.md`, populated by the enrichment components (Application step 8b). The PM↔dev split is the home for this content; rule 3 governs the PM files, `story.dev.md` carries the technical detail. See `[[jira-wiki-formatter]]` for the audience table.
+
 4. **Output language matches the user's chat language**, not the input's. Auto-detect first via rule 4a; only ask via `AskUserQuestion` if signals split.
 
 5. **Visual inference confidence — single banner only.** Do NOT tag every visual claim. ONE banner at the top of the Design Reference block declares source type; all claims under it inherit:
@@ -218,7 +220,15 @@ NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No
    - Count ≤1 → continue to step 8 (single-story path).
    - Count ≥2 → execute the **host skill's split behavior** (see Source-specific differential in each top-level skill).
 
-8. **Fill the canonical block** (Use Case + AC + Design Ref + INVEST). Preserve original wording where it was already good. NEVER invent NFR/edge-case/deps sections.
+8. **Fill the canonical block** (Use Case + AC + Design Ref + INVEST). Preserve original wording where it was already good. NEVER invent NFR/edge-case/deps sections **in the PM story body** — rule 3 still holds for `story.standard.md` / `story.jira-wiki.md`.
+
+8b. **Gather dev-file enrichment** (feeds `story.dev.md` only — see rule 3a). Invoke the enrichment components to populate the technical sections of the dev file:
+   - `[[edge-cases]]` → `### Edge Cases` (technical failure axes)
+   - `[[risks-and-dependencies]]` → `### Dependencias` + `### Riesgos`
+   - `[[analytics-events]]` → `### Analytics / Eventos`
+   - `[[definition-of-done]]` → full DoD with CLI commands (PM files get the acceptance-only projection)
+   - `[[business-rules]]` → policy invariants (also an *optional* PM section per `[[jira-wiki-formatter]]` when non-empty)
+   None of these may appear in the PM story body except the optional Business Rules section. Skip any component whose output is empty (drop empty sections — rule 3 / jira-wiki-formatter).
 
 9. **Run INVEST** via `[[invest-checklist]]`.
    - `READY` → render.

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

@@ -9,12 +9,18 @@ inputs:
 outputs:
   - story-1.standard.md
   - story-1.jira-wiki.md
+  - story-1.dev.md
   - flow-summary.md
   - .storywright-context.json
 composes:
   - _components/storywright-base
   - _components/clarification-questions
+  - _components/business-rules
   - _components/acceptance-criteria
+  - _components/edge-cases
+  - _components/analytics-events
+  - _components/risks-and-dependencies
+  - _components/definition-of-done
   - _components/invest-checklist
   - _components/jira-wiki-formatter
 ---
@@ -85,15 +91,15 @@ Use the base canonical output shape. Design Reference banner per source-specific
 
 ### Phase 5 — Output
 
-Per drafted flow:
-- `story-<N>.standard.md` + `story-<N>.jira-wiki.md`.
+Per drafted flow, render the full trio via `[[jira-wiki-formatter]]` (same 3-file contract as `story-generate` / `story-refine`):
+- `story-<N>.standard.md` + `story-<N>.jira-wiki.md` (PM-facing) + `story-<N>.dev.md` (dev-facing).
 
 If N>1 OR any flow was routed to split:
 - `flow-summary.md` with the matrix, V audit, build order, and SPLIT-RECOMMENDED markers.
 
 Plus `.storywright-context.json` updated (`extra.figma_url`, `extra.figma_scope`, `extra.mcp_available`).
 
-NO `clarifications.md`. NO Edge Cases sections. NO NFR blocks. NO per-claim visual tags.
+NO `clarifications.md`. NO Edge Cases / NFR sections **in the PM files** (they live in `story-<N>.dev.md` per base rule 3a). NO per-claim visual tags.
 
 ## Examples
 
@@ -124,7 +130,7 @@ Skipping the mechanical matrix in `flow-summary.md` when N>1.
 
 - Treating each frame as a story.
 - Skipping prototype-link analysis — without flow structure, user goals are guesses.
-- Ignoring empty/error/loading states. Fold into AC failure paths, not edge-case sections.
+- Ignoring empty/error/loading states. In the PM files fold them into AC failure paths (no edge-case section); the technical detail goes to `story-<N>.dev.md`.
 - Trusting MEDIUM/LOW inferences silently — mark `⚠️ Assumed`.
 - Skipping per-story V audit when N>1 (figma flows over-split easily).
 - All other pitfalls in `[[storywright-base]]` apply equally.

package/skills/story-generate/SKILL.md

@@ -16,7 +16,12 @@ outputs:
 composes:
   - _components/storywright-base
   - _components/clarification-questions
+  - _components/business-rules
   - _components/acceptance-criteria
+  - _components/edge-cases
+  - _components/analytics-events
+  - _components/risks-and-dependencies
+  - _components/definition-of-done
   - _components/invest-checklist
   - _components/jira-wiki-formatter
 ---

package/skills/story-generate/templates/story.jira-wiki.md

@@ -20,6 +20,10 @@ h3. Definition of Done
 
 ----
 
+{panel:title=PM-facing — no technical detail}
+Technical Considerations, Edge Cases, Analytics, Risks & Dependencies live in story.dev.md (rule 3). Optional sections below — keep only those with content.
+{panel}
+
 h3. Contexto
 {{trigger: feedback / OKR / incident / competitor}}
 
@@ -34,21 +38,3 @@ h3. Out of Scope
 
 h3. Business Rules
 # {{rule 1}}
-
-h3. Technical Considerations
-* {{api / sdk / flag / data model}}
-
-h3. Dependencies
-||What||Owner||Status||Blocks?||
-|{{dep}}|{{owner}}|{{READY/IN-PROGRESS}}|{{Yes/No}}|
-
-h3. Risks
-||Risk||L||I||Mitigation||
-|{{risk}}|{{L/M/H}}|{{L/M/H}}|{{action}}|
-
-h3. Analytics
-||Event||Trigger||Payload||
-|{{event_name}}|{{when}}|{{fields}}|
-
-h3. Edge Cases
-* *{{axis}}:* {{behavior}}

package/skills/story-generate/templates/story.standard.md

@@ -20,7 +20,12 @@
 
 ---
 
-<!-- Optional sections — keep only those with content. Delete the rest. -->
+<!--
+  PM-facing file. NO technical detail (rule 3): no file paths, imports, commands,
+  edge-case sections, NFR blocks, or dependency prose. Technical Considerations,
+  Edge Cases, Analytics, Risks & Dependencies live in story.dev.md.
+  Optional sections below — keep only those with content. Delete the rest.
+-->
 
 ## Contexto
 {{trigger: feedback / OKR / incident / competitor}}
@@ -36,24 +41,3 @@
 
 ## Business Rules
 1. {{rule 1}}
-
-## Technical Considerations
-- {{api / sdk / flag / data model}}
-
-## Dependencies
-| What | Owner | Status | Blocks? |
-|---|---|---|---|
-| {{dep}} | {{owner}} | {{READY/IN-PROGRESS}} | {{Yes/No}} |
-
-## Risks
-| Risk | L | I | Mitigation |
-|---|---|---|---|
-| {{risk}} | {{L/M/H}} | {{L/M/H}} | {{action}} |
-
-## Analytics
-| Event | Trigger | Payload |
-|---|---|---|
-| `{{event_name}}` | {{when}} | {{fields}} |
-
-## Edge Cases
-- **{{axis}}:** {{behavior}}

package/skills/story-refine/SKILL.md

@@ -16,7 +16,12 @@ outputs:
 composes:
   - _components/storywright-base
   - _components/clarification-questions
+  - _components/business-rules
   - _components/acceptance-criteria
+  - _components/edge-cases
+  - _components/analytics-events
+  - _components/risks-and-dependencies
+  - _components/definition-of-done
   - _components/invest-checklist
   - _components/jira-wiki-formatter
 ---

package/skills/story-split/SKILL.md

@@ -10,14 +10,23 @@ inputs:
   - figma-link
 outputs:
   - epic.md
-  - story-1.md
-  - story-2.md
+  - story-1.standard.md
+  - story-1.jira-wiki.md
+  - story-1.dev.md
+  - story-2.standard.md
+  - story-2.jira-wiki.md
+  - story-2.dev.md
   - .storywright-context.json
 composes:
   - _components/storywright-base
   - _components/invest-checklist
   - _components/clarification-questions
+  - _components/business-rules
   - _components/acceptance-criteria
+  - _components/edge-cases
+  - _components/analytics-events
+  - _components/risks-and-dependencies
+  - _components/definition-of-done
   - _components/jira-wiki-formatter
 ---
 
@@ -35,8 +44,8 @@ When a story is an epic in disguise, splitting badly is worse than not splitting
 ## Split behavior differential
 
 This skill IS the split behavior. It always emits multiple files:
-- `epic.md` — title, why-split, INVEST failure reasons, mechanical NxN matrix, build order, V audit per child, list of children.
-- `story-1.md`, `story-2.md`, … — one canonical story per child (per base shape).
+- `epic.md` — title, why-split, INVEST failure reasons, mechanical NxN matrix, build order, V audit per child, list of children. Single file (epic metadata, not a user story).
+- Per child: the full 3-file trio `story-<N>.standard.md` + `story-<N>.jira-wiki.md` + `story-<N>.dev.md`, rendered via `[[jira-wiki-formatter]]` — same contract as every other story-producing skill. Each child is a canonical user story (per base shape).
 - `.storywright-context.json` — persisted answers.
 
 NO `split-plan.md`. The plan lives inside `epic.md`.
@@ -107,7 +116,7 @@ Follow the **base Application** skeleton for the front-end behaviors (context lo
 
 5. **STOP and ask the user to approve via `AskUserQuestion`.**
 
-6. **For each approved child, write the base canonical block.** Each child is its own file (`story-<N>.md`).
+6. **For each approved child, write the base canonical block, then render via `[[jira-wiki-formatter]]` to the 3-file trio** (`story-<N>.standard.md` + `story-<N>.jira-wiki.md` + `story-<N>.dev.md`). The child's enrichment (edge cases, risks, analytics) populates its `story-<N>.dev.md` per base step 8b.
 
 7. **Build dependency matrix mechanically (base rule 10).** Render in `epic.md`.