@pavp/storywright 1.11.1 → 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/commands/story-generate.md

@@ -15,7 +15,12 @@ Follow the skill's full procedure:
 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 pre-split test. If count ≥2, show candidate children + ask via `AskUserQuestion` with options: "Yes, split" / "Continue without split" / "No, keep as-is". Never auto-split silently. For other verdicts (NOT A STORY / NEEDS REFINEMENT / RUN A SPIKE) — STOP and hand off accordingly.
-7. Render dual outputs via `jira-wiki-formatter`. Use the `Write` tool to write `story.standard.md` and `story.jira-wiki.md` to `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` (current local time, title in kebab-case max 5 words). Also emit both as fenced code blocks in chat. Then write `.storywright-context.json` to the same folder with all resolved answers from this session: `{"language":"...","persona":"...","naming_pattern":null,"output_folder":"...","resolved_questions":[],"sibling_refs":[]}`. Never ask — always write all three files.
+7. Render three outputs via `jira-wiki-formatter` to `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` (current local time, title kebab-case max 5 words). Use the `Write` tool for all files — never ask:
+   - `story.standard.md` — PM-facing CommonMark: observable behavior only, no file paths/imports/component names/CLI commands
+   - `story.jira-wiki.md` — PM-facing Jira wiki markup: same content as standard
+   - `story.dev.md` — dev-facing CommonMark: full technical detail (file paths, imports, Technical Considerations, technical edge cases, DoD with `npm run` commands)
+   - `.storywright-context.json` — resolved session answers: `{"language":"...","persona":"...","naming_pattern":null,"output_folder":"...","resolved_questions":[],"sibling_refs":[]}`
+   Emit `story.standard.md` and `story.jira-wiki.md` as fenced code blocks in chat. Do NOT emit `story.dev.md` in chat.
 8. Non-blocking assumptions remain? Mark inline with `⚠️ Assumed:`. Do NOT emit clarifications.md.
 
 Output in the input language (preserve es/en).

package/commands/story-refine.md

@@ -16,5 +16,10 @@ Follow the skill's procedure:
 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 pre-split test. If count ≥2, show candidate children + ask via `AskUserQuestion` with options: "Yes, split" / "Continue without split" / "No, keep as-is". Never auto-split silently.
-7. Render dual outputs via `jira-wiki-formatter`. Use the `Write` tool to write `story.standard.md` and `story.jira-wiki.md` to `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` (current local time, title in kebab-case max 5 words). Also emit both as fenced code blocks in chat. Then write `.storywright-context.json` to the same folder with all resolved answers from this session: `{"language":"...","persona":"...","naming_pattern":null,"output_folder":"...","resolved_questions":[],"sibling_refs":[]}`. Never ask — always write all three files.
+7. Render three outputs via `jira-wiki-formatter` to `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` (current local time, title kebab-case max 5 words). Use the `Write` tool for all files — never ask:
+   - `story.standard.md` — PM-facing CommonMark: observable behavior only, no file paths/imports/component names/CLI commands
+   - `story.jira-wiki.md` — PM-facing Jira wiki markup: same content as standard
+   - `story.dev.md` — dev-facing CommonMark: full technical detail (file paths, imports, Technical Considerations, technical edge cases, DoD with `npm run` commands)
+   - `.storywright-context.json` — resolved session answers: `{"language":"...","persona":"...","naming_pattern":null,"output_folder":"...","resolved_questions":[],"sibling_refs":[]}`
+   Emit `story.standard.md` and `story.jira-wiki.md` as fenced code blocks in chat. Do NOT emit `story.dev.md` in chat.
 8. Non-blocking assumptions remain? Mark inline with `⚠️ Assumed:`. Do NOT emit clarifications.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/storywright",
-  "version": "1.11.1",
+  "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/jira-wiki-formatter/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: jira-wiki-formatter
-description: Render a story into both Jira wiki markup and standard CommonMark Markdown. Outputs two artifacts so the same story is copy-pasteable into Jira and into any MD-aware tool.
+description: Render a story into three files: story.standard.md and story.jira-wiki.md (PM-facing, no technical detail) plus story.dev.md (dev-facing, full technical detail).
 trigger: "internal use by story-* skills"
-intent: Component skill that takes a structured story (all sections drafted) and produces two output files following the templates in story-generate/templates.
-version: 1.0.0
+intent: Component skill that takes a structured story and produces three output files following the templates in story-generate/templates.
+version: 2.0.0
 inputs:
   - structured-story
 outputs:
-  - story.jira-wiki.md
   - story.standard.md
+  - story.jira-wiki.md
+  - story.dev.md
 ---
 
 ## Purpose
@@ -25,7 +26,21 @@ Final step in `story-generate` and `story-refine`. Always last.
 
 ## Application (step-by-step)
 
-1. Render `story.jira-wiki.md` using Jira's wiki markup:
+## Audience separation — THREE files
+
+| File | Audience | Technical detail |
+|---|---|---|
+| `story.standard.md` | PM, stakeholders | ❌ None — no file paths, no imports, no component names, no `npm run X` in DoD |
+| `story.jira-wiki.md` | PM → Jira paste | ❌ None — same content as standard, Jira markup |
+| `story.dev.md` | Developer | ✅ Full — file paths, imports, Technical Considerations, technical edge cases, full DoD with commands |
+
+**What is "technical":** file paths, import statements, component/hook names, API method names, CLI commands (`npm run test`), null/undefined checks, browser API constraints (HTTPS, permissions), specific library flags.
+
+**ACs in PM files must describe observable behavior only.** "A copy icon appears next to the email field and clicking it copies the value" — not "ContentCopyOutlinedIcon is rendered next to the email Typography block and calls navigator.clipboard.writeText()".
+
+---
+
+1. Render `story.jira-wiki.md` (PM-facing) using Jira's wiki markup:
    - Headings: `h1. `, `h2. `, `h3. `
    - Bold: `*text*`
    - Italic: `_text_`
@@ -33,7 +48,8 @@ Final step in `story-generate` and `story-refine`. Always last.
    - Lists: `* item`, `# item` (numbered)
    - Tables: `||header||header||` then `|cell|cell|`
    - Panels for callouts: `{panel:title=⚠️ Assumed}…{panel}`
-2. Render `story.standard.md` using CommonMark:
+   - Strip all technical detail (see audience table above)
+2. Render `story.standard.md` (PM-facing) using CommonMark:
    - Headings: `##`, `###`
    - Bold: `**text**`
    - Italic: `*text*`
@@ -41,29 +57,28 @@ Final step in `story-generate` and `story-refine`. Always last.
    - Lists: `- item`, `1. item`
    - Tables: standard pipe tables
    - Callouts: `> ⚠️ **Assumed:** …`
-3. Section model = **core + optional**.
+   - Strip all technical detail (see audience table above)
+3. Render `story.dev.md` (dev-facing) using CommonMark:
+   - Same structure as `story.standard.md` PLUS:
+   - Technical Considerations section (file paths, imports, API calls)
+   - Edge Cases section (null checks, error states, browser constraints)
+   - DoD includes CLI commands and file-level criteria
+   - Refinement log includes technical changes
+4. Section model for PM files = **core + optional (non-technical)**.
 
    **Core (always emit, in this order):**
    1. Title
-   2. Summary
-   3. User Story (As a / I want to / so that)
-   4. Acceptance Criteria
-   5. Definition of Done
-
-   **Optional (emit only if non-empty, in this order, after a separator):**
-   6. Contexto
-   7. Business Goal
-   8. Scope
-   9. Out of Scope
-   10. Business Rules
-   11. Technical Considerations
-   12. Dependencies
-   13. Risks
-   14. Analytics
-   15. Edge Cases
-
-4. **Drop any section with no real content.** An empty heading is noise. A story with only the 5 core sections is a valid output.
-5. Emit both as fenced code blocks in the chat so the user can copy them. File persistence is handled by the calling skill via the `Write` tool.
+   2. User Story (As a / I want to / so that)
+   3. Acceptance Criteria (observable behavior only)
+   4. Definition of Done (acceptance criteria only, no commands)
+
+   **Optional PM sections (emit only if non-empty):**
+   5. Business Goal
+   6. Scope / Out of Scope
+   7. Business Rules
+
+5. **Drop any section with no real content.** An empty heading is noise.
+6. Emit `story.standard.md` and `story.jira-wiki.md` as fenced code blocks in chat (PM-facing). Do NOT emit `story.dev.md` in chat — write to disk only. File persistence is handled by the calling skill via the `Write` tool.
 
 ## Examples
 

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.
@@ -228,10 +238,13 @@ NOTHING else. No NFR block. No Edge Cases enumeration. No Dependencies prose. No
 
 10. **Render** via `[[jira-wiki-formatter]]`.
     - Derive the output folder: `docs/storywright/YYYY-MM-DD-HHmm-<title-slug>/` where `YYYY-MM-DD-HHmm` is the current local date+time and `<title-slug>` is the story title in kebab-case (max 5 words, drop articles/prepositions).
-    - Use the `Write` tool to persist `story.standard.md` and `story.jira-wiki.md` to that folder (create it if it does not exist).
-    - Also emit both as fenced code blocks in chat.
+    - Use the `Write` tool to persist three files to that folder (create it if it does not exist):
+      - `story.standard.md` — PM-facing CommonMark, no technical detail
+      - `story.jira-wiki.md` — PM-facing Jira wiki markup, no technical detail
+      - `story.dev.md` — dev-facing CommonMark, full technical detail (file paths, imports, technical edge cases, full DoD with commands)
+    - Emit `story.standard.md` and `story.jira-wiki.md` as fenced code blocks in chat. Do NOT emit `story.dev.md` in chat.
     - Write `.storywright-context.json` to the same folder.
-    - No other files. Never ask whether to save — always write.
+    - Never ask whether to save — always write all four files.
 
 11. **Log** ≤3 bullets (≤5 if SPLIT) appended at story end. Log type label is host-specific (Generation / Refinement / Split).
 

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

@@ -11,11 +11,17 @@ inputs:
 outputs:
   - story.standard.md
   - story.jira-wiki.md
+  - story.dev.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
 ---

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

@@ -0,0 +1,27 @@
+# {{Title}} — Dev Notes
+
+> This file is the developer supplement to `story.standard.md`.
+> It contains all technical detail stripped from the PM-facing outputs.
+
+## Technical Considerations
+
+- {{file path or component name}} — {{what changes}}
+- {{import to add/remove}}
+- {{API call / SDK / feature flag / data model note}}
+
+## Edge Cases & Error States
+
+- **{{axis}}:** {{technical behavior — null checks, error states, race conditions, HTTPS requirements}}
+
+## Definition of Done
+
+- [ ] {{business criterion}}
+- [ ] {{test command: npm run test / npm run lint}}
+- [ ] {{file-level criterion: file X updated, import Y removed}}
+
+---
+
+<!-- Refinement Log — full version including technical changes -->
+
+*Refinement log*
+- {{change}} — {{reason}}

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

@@ -11,11 +11,17 @@ inputs:
 outputs:
   - story.standard.md
   - story.jira-wiki.md
+  - story.dev.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
 ---

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`.