/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

**First, check whether the conversation already answers the source.** Ask: "Could a stranger reading the conversation so far tell where this story comes from without asking?"

• A story already worked out in this conversation before story-new ran, or one the user says to build from the discussion, is freeform: no search, no question, continue to Step 3.
• A conversation that names one design (for example "make a story from the story-card mockup"): Read the craft designs reference below, run its Search, then its Pick with that design named. No question.
• A one-line idea given only at Step 1 does not answer the source. When unsure, default toward asking: run the detection below.

Otherwise, before asking "How deep do you want to go?" (Step 3), check whether this project has planning docs OR craft designs waiting to be built (converged or parked mockups, open annotate runs) that the story could be built from.

**Detection logic:**

Read `"${CLAUDE_PLUGIN_ROOT}/commands/references/story-from-craft-designs.md"` with the Read tool (never via the Skill tool) and run its `## Search`. Then use **Bash** for the planning scan:

# 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

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

**If any 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/ / [K] annotations in .craft/annotations/.)"
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: "craft designs"   (only if the craft designs search found any)
    description: "[counts phrase from the search, e.g. 2 mockups, 1 annotate run] waiting to be built"
  - label: "Freeform"
    description: "Build a fresh story without planning context. Continue with the standard flow."

`[M]` and `[K]` are the number of MOCKUP and ANNOTATE lines the craft designs search printed, never directory counts. The counts phrase is built the way the reference's Search describes.

**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 "craft designs":**

⛔ **Same chain-break rule - never via the Skill tool.** Continue in the reference already read for the search, inline with the Read tool:

Read "${CLAUDE_PLUGIN_ROOT}/commands/references/story-from-craft-designs.md"
Continue at ## Pick, then ## Hand-off, against the waiting designs the search found.

The reference owns the pick (one design: "Building from [slug] - that one?"; several: a conversational list) and hands the chosen r