Add a story

Add a story to the board.

A story is one unit of work, stored as a ticket record. Title, description, acceptance criteria, a phase to live in, optional blockers. You can create them two ways: through the Mac app, or by asking Claude Code directly. Both write the same JSON file under .story/tickets.

Written guide available · Video coming soon

Follow along

  1. 1.

    Option A - use the Mac app

    Open Storybloq, pick the storybook project, and press the + button next to Tickets. Fill in a title, a short description, acceptance criteria as a checklist, and drop it into a phase. Save. The new story appears on the board instantly.

  2. 2.

    Option B - ask Claude Code

    Inside Claude Code, just describe what you want: "add a story to phase 1 for setting up the Next.js project with our design system." Claude uses the storybloq_ticket_create tool to write the file, wire up the phase link, and give it the next free T- number. The dashboard updates the same way.

  3. 3.

    Link blockers and parents if needed

    If this story is blocked by another, set blockedBy. If it's part of a larger umbrella, set parentTicket. Both are plain fields on the story JSON; the app and Claude both understand them.

  4. 4.

    Commit it

    Stories are ticket records under .story/tickets/. Existing records may use T-001.json; newer records use canonical t-*.json filenames and carry a displayId such as T-001. Run git status --porcelain .story/ and stage the changed files it reports, then commit. Do not infer a filename from the display ID.