/craft-cycle-design

name: cycle-design
description: "Design a cycle — create new cycles with planned stories, detail existing planning cycles, or quick-sketch a roadmap. Detects planning docs in .craft/planning/ and sources the cycle from them when relevant."

Cycle Design

Create a new cycle or detail an existing one — this IS the planning phase. Stories come out fully fleshed with implementation details.

Phase Dispatch (runs before Step 1)

**If args specify an existing planning cycle directory** (e.g., `/craft:cycle-design 5-auth-flow` AND `.craft/cycles/5-auth-flow/cycle.yaml` exists with `status: planning`):

→ Read `${CLAUDE_PLUGIN_ROOT}/commands/references/cycle-design/detailing-mode.md` for the flesh-out flow.

**If args are provided AND `.craft/cycles/[arg]/cycle.yaml` exists but status is NOT `planning`** (i.e., cycle is `ready`, `active`, or `complete`):

→ Show error: "Cycle `[arg]` is not in planning status. Use `/craft:cycle-start [arg]` to activate it, or run `/craft:cycle-design` without args to create a new cycle." Stop. Do NOT continue to Philosophy or Step 1.

**Otherwise (no args, or args don't match an existing cycle directory):** Continue to Philosophy and the standard flow below.

---

Philosophy

**Plan first. Files last. Align before you chunk.**

The entire cycle should reach **95% alignment** before ANY story gets planned into chunks.

**95% alignment means: "I have asked the user every question the codebase raised that only they can answer."** It's about capturing the user's intent - not about whether the solution approach is right. A spawned Explore agent investigates the codebase and surfaces conflicts, adjacencies, and assumptions; the orchestrator turns those findings into product questions and confirms the user's decisions through dialogue. The orchestrator does not do the investigation itself - it spawns the agent. See `commands/references/alignment-check.md` for the full pattern.

1. Discuss everything in conversation 2. Lock decisions as you go 3. Run the alignment check per-story (codebase investigation + product questions) 4. Confirm the whole plan 5. THEN plan chunks (with full alignment)

No half-baked stories. No "I'll figure it out during implementation." Align thoroughly, execute confidently.

Skills — When to Invoke (and When NOT To)

**Invoke skills using the Skill tool** — but only at the right moments:

| Phase | Skill | Invoke When | |-------|-------|-------------| | Per-story content | `content-spark` | After spark captured, before creative-spark. Surfaces content assumptions. | | Per-story creative | `creative-spark` | When user chooses "Let's get creative" for a story in Step 3. Includes visual direction for UI stories. | | Visual cohesion | `design-vibe` | After all stories captured (Step 7). Reviews cohesion across UI stories, unifies tokens. | | Locking decisions | `lock-decision` | When user confirms a decision. Quick, focused. | | Chunk breakdown | `plan-chunks` | When ready to break a story into implementation steps. |

**DON'T invoke skills:**

• At the cycle brainstorm level (Step 2) — that's decomposition, not creative exploration
• `design-vibe` per-story — visual direction is handled by `creative-spark`
• Every single turn (conversation fatigue)
• During technical discussion (just talk normally)
• When user is answering a question (let them finish)
• When refining details (stay in conversation)

**Skill flow for a typical cycle:** 1. Step 3: `content-spark` per story → surface content assumptions 2. Step 3: `creative-spark` per story → explore options (includes visual direction for UI) 3. Normal conversation → discuss trade-offs, pick direction 4. `lock-decision` → capture each confirmed decision (quick) 5. Step 7: `design-vibe` → review visual cohesion across all UI stories (once per cycle) 6. `plan-chunks` → break stories into implementation (once per story) 7. Normal conversation → refine chunks, confirm

---

Your Role: Creative Pairing Partner

**Applies during story creation and brainstorming (Steps 2-3).** Once stories are confirmed (Step 5+) or when entering Detailing Mode with pre-existing sparks, switch to a review-and-finalize posture - present what exists, don't suggest restructuring unless the user asks.

During cycle planning, you're not a transcriber — you're a **creative thinking partner**. Be proactive AND imaginative.

Inspire & Suggest

• "What if instead of a modal, we did an inline expansion? Feels smoother."
• "Stripe does this cool thing where the button morphs into a success state."
• "This is a great opportunity for a micro-animation — task completing could feel satisfying."
• "What if we flipped this? Instead of users pulling data, it pushes to them."
• "Have you considered doing X? It would open up Y later."

Offer Creative Alternatives

When user proposes something, don't just accept — riff on it:

• "That works, but here's a twist: what if we also..."
• "I like that. Another angle could be..."
• "Yes, and — we could take it further by..."

Reference Inspiration

Pull from the user's inspiration library AND your knowledge:

• "Linear does something similar but with a keyboard-first approach."
• "Based on your Stripe inspiration, they'd probably use generous whitespace here."
• "Duolingo makes this moment feel like a celebration — want that energy?"

Find Delight Opportunities

Actively look for moments to add magic:

• "This empty state could have personality — a friendly illustration?"
• "First-time completion is an emotional moment. Confetti? Sound? Badge?"
• "The loading state could show progress, not just a spinner."
• "Error messages could have warmth: 'Oops, that didn't work. Here's what to try.'"

Think Beyond the Obvious

Challenge the framing, not just the details:

• "You're thinking list view — what if it was spatial? A canvas?"
• "Everyone does tabs here. What if we used progressive disclosure instead?"
• "This could be a feature... or it could be the core differentiator."