/craft-story-new

name: story-new
description: "Create a new story. It lands in the backlog until assigned to a cycle."

Story New

Create a new story from an idea. Stories can be quick sparks (just the idea), creatively explored, or fully designed — you choose how deep to go.

Flow

Step 1: Capture the Idea

> "What's the story about?" > > [User describes the idea]

**CRITICAL: Questions vs Answers**

Before capturing ANYTHING, distinguish:

• **Question from user:** "What do you recommend?" / "What should this do?" / "Any ideas?" → **ANSWER THE QUESTION FIRST.** Provide recommendations/options. Do NOT capture or lock anything. Wait for user to explicitly confirm.
• **Answer from user:** "Let's do X" / "The spark is Y" / "It should handle Z" → This is input to capture.

**Never lock or save based on a question.** Questions require answers, not actions.

Step 2: Clarify (if needed)

If the idea is vague or could mean multiple things, use **AskUserQuestion** to clarify.

**For UI/layout changes:**

question: "What aspect do you want to change?"
header: "Focus"
options:
  - label: "Rearrange sections"
    description: "Move things around, change order"
  - label: "Responsive behavior"
    description: "How it works on different screen sizes"
  - label: "Add/remove elements"
    description: "New components or removing existing ones"
  - label: "Overall structure"
    description: "Sidebar vs stacked, major layout shift"

**For feature work:**

question: "What's the core of this change?"
header: "Focus"
options:
  - label: "New functionality"
    description: "Something that doesn't exist yet"
  - label: "Improve existing"
    description: "Make current feature better"
  - label: "Fix a problem"
    description: "Something's broken or confusing"
  - label: "Performance/technical"
    description: "Speed, reliability, code quality"

**If user provides custom text:** Use their clarification and proceed to Step 2.5.

**If idea is already clear:** Skip directly to Step 2.5.

Step 2.5: Story Source Detection

Before asking "How deep do you want to go?" (Step 3), check whether this project has planning docs OR converged mockups that the story could be built from.

**Detection logic:**

Use **Bash**:

# Planning concepts/initiatives
find "$CRAFT_PROJECT_ROOT/.craft/planning" -maxdepth 3 -type f -name "*.md" 2>/dev/null \
  | xargs grep -l "^concept:\|^initiative:" 2>/dev/null \
  | head -20
# Non-abandoned mockup records
grep -L "^status: abandoned" "$CRAFT_PROJECT_ROOT"/.craft/mockups/*/record.md 2>/dev/null | head -20

**If both come back empty:** skip this step entirely and continue to Step 3. No AskUserQuestion shown. Users who have never used craft planning or mockups see zero behavior change.

**If either has matches:** present the choice via **AskUserQuestion** - include ONLY the source options whose scan found something, plus Freeform:

question: "Where does this story come from? (I see [N] concepts in .craft/planning/ / [M] mockups in .craft/mockups/.)"
header: "Source"
options:
  - label: "From planning"   (only if concepts matched)
    description: "Build this story from existing planning docs. I'll walk the concept(s) and produce a thorough story with Reference Materials."
  - label: "From mockup"   (only if mockup records matched)
    description: "Build this story from a converged mockup. Spark, Visual Direction, and binding table pre-fill from the record; the mockup's CSS is normative."
  - label: "Freeform"
    description: "Build a fresh story without planning context. Continue with the standard flow."

**If "From planning":**

⛔ **DO NOT invoke story-from-planning via the Skill tool (chain break - no return-to-caller).** Instead, Read and execute the logic inline:

Read "${CLAUDE_PLUGIN_ROOT}/commands/references/story-from-planning.md"
Execute the phases (1, 2, 3a, 3b, 4, 5, 6, 7) described in that file against the planning corpus.

The reference file owns the entire planning-to-story transformation: concept selection, Explore-agent extraction, gap-fill, file write with all canonical sections including `## Reference Materials`, and mandatory forward-linking to active.md + consumed concepts. When it completes Phase 7, the parent flow is DONE.

**Do NOT continue to Step 3 (Choose Your Path) or Step 3b (Content Check)** after the From planning branch completes. The story file is fully written with `alignment: pending` - the existing alignment-check fires when `/craft:story-implement` runs later.

**If "From mockup":**

⛔ **Same chain-break rule - never via the Skill tool.** Read and execute inline:

Read "${CLAUDE_PLUGIN_ROOT}/commands/references/story-from-mockup.md"
Execute its phases against the chosen mockup record.

The reference owns the mockup-to-story transformation: record selection (when several are open), the parked-mockup surface re-check, and the pre-filled story write (Spark, Visual Direction, Element Binding Table with mockup anchors, Reference Materials, frontmatter `mockup:`). When it completes, the parent flow is DONE - do not continue to Step 3.

**If "Freeform":** continue to Step 3 (Choose Your Path) unchanged.

Step 3: Choose Your Path

Use **AskUserQuestion**:

question: "How deep do you want to go?"
header: "Depth"
options:
  - label: "Just a spark"
    description: "Save the idea, flesh it out later"
  - label: "Let's get creative"
    description: "Explore options, riff on the design together"
  - label: "I know what I want"
    description: "Skip to planning chunks, let's build it"

**If "Just a spark"** → Skip to Step 10 (Save & Place) — asks priority, writes minimal file, offers placement

**If "Let's get creative"** → Continue to Step 3b (Content Check), then Step 4 (with creative-spark)

**If "I know what I want"** → Continue to Step 3b (Content Check), then Step 7 (Quick Decisions)

---

Step 3b: Content Check

Before exploring HOW (creative or smart), check if the content directio