Complete Workflow Tutorial: From Idea to Production

Who is this for? Someone who has never used Claude Code or Claude Craft. We start from zero, build a real feature end to end, and explain every term the first time it appears.
What we build: TaskFlow — a small team task-tracking SaaS with a REST API (Python / FastAPI) and a React web client. It is simple enough to follow in one sitting, real enough to exercise the whole workflow.
Claude Craft v8.19.2 · Estimated reading + doing time: 60–90 minutes.

0. Before you start

What you will do

You will take TaskFlow from a one-sentence idea to a reviewed, tested first sprint — using Claude Craft's BMAD workflow. The path always flows in one direction, and every arrow is protected by a quality gate (a blocking check):

 IDEA
   │  /workflow:init        ← pick the track
   ▼
 BACKLOG ──/gate:validate-backlog──┐  (PRD ≥ 80%, INVEST 6/6)
   │  /workflow:plan                │
   ▼                                │
 TECH DESIGN ──/gate:validate-techspec──┐  (Tech Spec ≥ 90%)
   │  /workflow:design                   │
   ▼                                      │
 SPRINT PLAN ──/gate:validate-sprint──┐  (Sprint Ready 100%)
   │  /workflow:start                  │
   │  /project:decompose-tasks         │
   ▼                                    │
 IMPLEMENTATION (TDD) ──/gate:validate-story──┐  (Story DoD 100%)
   │  /sprint:dev                              │
   ▼                                            │
 REVIEW + RETRO ──/workflow:review, /workflow:retro
   │
   ▼
 NEXT SPRINT ↺

Golden rule of the method: you do not move to the next step until its gate passes. This is what stops you from building on shaky foundations.

1. The basics in 5 minutes

Read this once. You will come back to it.

Claude Code — the CLI where you talk to Claude in your terminal (or IDE). You type messages and slash-commands; Claude reads/writes files, runs commands, and answers.
Slash-command — a packaged instruction starting with /. Example: /workflow:init. Claude Craft ships 125 of them across 15 namespaces.
Agent — a specialized Claude persona you summon with @. Example: @tdd-coach, @symfony-reviewer. Each has focused expertise.
Claude Craft — the framework you installed: rules, commands, agents, skills, and the BMAD project-management layer.
BMAD — Claude Craft's lightweight SCRUM-style method (Backlog → sprint → review). It writes its state to files, not to the conversation — which is why clearing the chat later is safe.

Mini-glossary

Term	Plain meaning
Epic	A large chunk of value, split into stories.
User Story (US)	A small, user-visible increment ("As a user, I can…").
Backlog	The ordered list of epics and stories.
Sprint	A short batch of stories you commit to finishing.
Task	A story split into ≤ 30-min steps a dev (or agent) executes.
Gate	A blocking quality check between phases.
DoD	Definition of Done — the checklist a story must pass.
INVEST	The 6 qualities of a good story (Independent, Negotiable, Valuable, Estimable, Small, Testable).
TDD	Test-Driven Development: write a failing test → make it pass → refactor.

1.5 Understanding execution modes (read this — it trips up everyone)

There are two different things called "mode". Do not confuse them.

(a) The three interaction modes (toggle with Shift+Tab in Claude Code):

Mode	Indicator	What it does
Plan	📋	Claude proposes a plan and edits nothing until you approve.
Normal	⚡	Claude acts, but asks permission before risky actions. Default for this tutorial.
Auto-accept	🤖	Claude executes without asking. Powerful, but only once you trust the flow.

(b) The "plan mode" some commands turn on by themselves. Several Claude Craft commands (/workflow:design, /workflow:plan…) deliberately enter a planning step and wait for your "go" before writing files — independent of which Shift-Tab mode you are in.

Simple rule for beginners: stay in Normal (⚡), let commands trigger their own planning step, and approve the plans. Use auto-accept and --auto flags only once the flow feels familiar.

Throughout this tutorial, every command shows the mode it expects:

Mode: Normal (⚡) — interactive
Mode: Plan required — Claude will plan first
Mode: Read-only — safe in any mode

2. Verify your install

Mode: Read-only. Open Claude Code in your project folder and confirm Claude Craft is present.

bash

# In your terminal, inside the project
claude

Then, inside Claude Code:

/workflow:status

If you see a workflow status report (even "no workflow yet"), Claude Craft is installed. If the command is unknown, (re)install:

bash

npx @the-bearded-bear/claude-craft install . --tech=python --lang=en

About the Project Management layer. The /gate:*, /sprint:*, and /project:* commands used below come from the Project Management commands option, included by default during install (the installer asks "Include Project Management commands? (Y/n)" → Yes). If those commands are missing, re-run the installer and accept that option.

2.x Saving tokens: context and `/clear`

The context window is Claude's working memory — and your most precious resource. Two habits keep it healthy:

/clear between unrelated steps. Because BMAD writes its state to files, nothing is lost: after /clear, run /workflow:status and Claude re-reads where you are.
RTK + hooks for token optimization. Run /common:setup-rtk once to configure the Rust Token Killer proxy and the optimization hooks (60–90% savings on dev-command output).

You will see "Good time to /clear" markers between the lettered steps below.

Step A — Build the backlog

A.1 Initialize the workflow

Mode: Plan required.

/workflow:init

Claude analyzes your project and recommends a track:

Track	Setup	Phases	Best for
Quick Flow	< 5 min	Implement only	Bug fixes, hotfixes
Standard	< 15 min	Plan → Design → Implement	New features (← TaskFlow uses this)
Enterprise	< 30 min	Analyze → Plan → Design → Implement	Platforms

Pick Standard for TaskFlow.

A.2 Generate the PRD and backlog

Mode: Plan required.

/workflow:plan

Claude interviews you about TaskFlow, then drafts a PRD (Product Requirements Document), personas, and an initial backlog of epics and stories under project-management/. Answer concretely, e.g.:

"TaskFlow lets a small team create projects, add tasks, assign them, and mark them done. MVP = REST API + web list/board view. No mobile yet."

What to expect: files such as project-management/prd.md and project-management/backlog/ with epics like EPIC-001 Projects, EPIC-002 Tasks, and stories like US-001 Create a project.

A.3 Validate the backlog

Mode: Read-only.

/gate:validate-backlog

This gate checks the backlog against INVEST (6/6) and PRD coverage (≥ 80%). If it fails, it tells you exactly which stories are too big, untestable, or unestimable. Fix them (re-run /workflow:plan or edit the stories) until the gate is green.

Good time to /clear. Then /workflow:status to resume.

Step B — Design, then create the sprint

B.1 Design the technical solution

Mode: Plan required.

/workflow:design

Claude (acting as architect) produces a Tech Spec: architecture choices, data model, API contract, and the libraries to use — grounded in your stack's Claude Craft references (Clean Architecture, FastAPI patterns, etc.).

B.2 Validate the tech spec

Mode: Read-only.

/gate:validate-techspec

Gate threshold: Tech Spec ≥ 90%. It flags missing error handling, undefined contracts, or untestable designs.

B.3 Plan the first sprint

Mode: Plan required.

/workflow:start

Claude proposes a sprint goal and selects the top backlog stories that fit. For TaskFlow, a sensible first sprint is a walking skeleton: project + task creation through the API, surfaced in the web list.

B.4 Decompose stories into tasks

Mode: Plan required.

/project:decompose-tasks

Each story is split into ≤ 30-minute, independently testable tasks (write the model, write the endpoint, write the test, wire the UI…). This is what makes TDD and /sprint:dev flow smoothly.

B.5 Validate the sprint

Mode: Read-only.

/gate:validate-sprint

Gate threshold: Sprint Ready 100% — every story estimated, every task defined, dependencies ordered. Green means you can start coding.

Good time to /clear.

Step C — Implement the sprint with TDD

C.1 The recommended path for beginners

Mode: Normal (⚡).

/sprint:dev

/sprint:dev walks the sprint task by task, coaching you through the Red → Green → Refactor TDD cycle:

Red — write a failing test that pins the expected behavior.
Green — write the minimum code to pass it.
Refactor — clean up, tests stay green.

For each story it also runs a code review and checks the Story DoD (100%) before moving on.

TDD is non-negotiable. A test written before the code is what lets the agent write code you can trust. Bug fixes get a regression test first (it must fail before your fix, pass after).

C.2 Alternatives (optional)

/project:run-sprint — runs the whole sprint more autonomously.
/team:sprint — implements multiple stories in parallel using Agent Teams (advanced).
@tdd-coach — summon the coach mid-task for guidance.

Stick with /sprint:dev for your first run.

C.3 Drive it day to day

/sprint:next-story --claim — grab the next story.
/sprint:transition US-001 in-progress — move a story across the board.
/qa:tdd — fix a bug in strict TDD/BDD mode.

Docker reminder. Run tests and commands through Docker so results don't depend on your local machine, e.g. docker compose exec app pytest.

Step D — Track progress with the Kanban board

D.1 Launch the board

Mode: Read-only.

/project:board

This opens a local Kanban board (no SaaS, no lock-in) reading the BMAD state files. Columns follow the status routing:

backlog → ready-for-dev → in-progress → review → done   (any → blocked)

Companion views: /project:burndown (sprint burndown), /project:dependencies, /project:critical-path, /project:metrics.

D.2 Why a card may refuse to move

The board enforces the same gates. A story won't enter done until its DoD passes — that's the method protecting you, not a bug.

Good time to /clear.

Step E — Close the sprint and loop

E.1 Sprint review

Mode: Normal (⚡).

/workflow:review

Summarizes what shipped against the sprint goal, with a demo checklist.

E.2 Retrospective

/workflow:retro

Captures what went well / what to improve. Persist durable learnings with /memory so they survive future /clears.

E.3 Loop

Run /workflow:start again to plan sprint 2 from the remaining backlog. The cycle repeats: plan → design → implement → review.

Cheat sheet

Commands, in order

bash

# Step A — Backlog
/workflow:init                 # pick the track
/workflow:plan                 # PRD + backlog
/gate:validate-backlog         # INVEST 6/6, PRD ≥ 80%

# Step B — Design + sprint
/workflow:design               # tech spec
/gate:validate-techspec        # Tech Spec ≥ 90%
/workflow:start                # plan the sprint
/project:decompose-tasks       # stories → tasks
/gate:validate-sprint          # Sprint Ready 100%

# Step C — Implement (TDD)
/sprint:dev                    # task-by-task Red/Green/Refactor
/gate:validate-story US-001    # Story DoD 100%

# Step D — Track
/project:board                 # Kanban
/project:burndown              # burndown

# Step E — Close + loop
/workflow:review
/workflow:retro

When to `/clear`

After each lettered step (A→B→C→D→E). State lives in files; /workflow:status re-reads it.

Where files live

What	Where
PRD, personas	`project-management/prd.md`
Backlog (epics/stories)	`project-management/backlog/`
Sprints, tasks	`project-management/sprints/`
BMAD status	`project-management/.bmad/` / `sprint-status.yaml`

Gate thresholds

Gate	Threshold
PRD	≥ 80%
Tech Spec	≥ 90%
INVEST	6/6
Sprint Ready	100%
Story DoD	100%
Spec Alignment	≥ 85%

Common problems

Symptom	Fix
`/gate:` / `/sprint:` unknown	Re-install and accept Project Management commands.
`/bmad:init` not found	It doesn't exist — use `/workflow:init`.
Gate keeps failing	Read its report; it names the exact failing item.
Card won't reach done	Its DoD isn't met yet — that's intended.
Lost after `/clear`	Run `/workflow:status`.
Context > 60%	`/clear`, then `/workflow:status`.

Automating with Ralph (optional)

Once comfortable, automate a story end to end with the continuous loop:

/common:ralph-run "Implement US-001 with full DoD validation"

Ralph keeps Claude working until the Definition of Done validators pass. See RALPH-GUIDE.md.

Appendix — A real-world multi-stack scenario

TaskFlow is single-stack on purpose. Real products are messier — and the same workflow scales to them. As a richer example, consider a Wrandly-style app (anonymized version shipped as a test fixture under tests/fixtures/wrandly-anon/):

Two clients: a web PWA (Symfony + React) and a Flutter mobile app, plus a custom REST API.
A design handoff already exists before development starts (a "Claude Design" package): source documents, 5 locked architecture decisions, and a phased plan (Epics 0 → 7).

How it maps to this tutorial:

Design artifact	Feeds into
Source documents	`/workflow:plan` (input for the PRD + backlog)
Locked architecture decisions	`/workflow:design` (formalized in the Tech Spec)
Phases 0 → 7	The epics → sprints split

Two adjustments for multi-stack:

Start with the foundation epic (Epic 0): monorepo, shared design tokens, the OpenAPI contract, and a map style before any UI component — a true walking skeleton.
Run web and mobile sprints in parallel with /team:sprint (Agent Teams), each respecting its own stack's gates.

Everything else — gates, TDD, the Kanban board, /clear discipline — is identical. The method does not change with scale; only the number of parallel tracks does.

Next steps

Feature Development — go deeper on the TDD loop and agents.
Backlog Management — master epics, stories, and the 15+ project commands.
BMAD Practical Guide — the full command reference for the method.
Autonomous Sprint — let an agent pipeline run the whole sprint.
Learning Paths — Beginner → Intermediate → Advanced progression.

Complete Workflow Tutorial: From Idea to Production ​

0. Before you start ​

What you will do ​

1. The basics in 5 minutes ​

Mini-glossary ​

1.5 Understanding execution modes (read this — it trips up everyone) ​

2. Verify your install ​

2.x Saving tokens: context and /clear ​

Step A — Build the backlog ​

A.1 Initialize the workflow ​

A.2 Generate the PRD and backlog ​

A.3 Validate the backlog ​

Step B — Design, then create the sprint ​

B.1 Design the technical solution ​

B.2 Validate the tech spec ​

B.3 Plan the first sprint ​

B.4 Decompose stories into tasks ​

B.5 Validate the sprint ​

Step C — Implement the sprint with TDD ​

C.1 The recommended path for beginners ​

C.2 Alternatives (optional) ​

C.3 Drive it day to day ​

Step D — Track progress with the Kanban board ​

D.1 Launch the board ​

D.2 Why a card may refuse to move ​

Step E — Close the sprint and loop ​

E.1 Sprint review ​

E.2 Retrospective ​

E.3 Loop ​

Cheat sheet ​

Commands, in order ​

When to /clear ​

Where files live ​

Gate thresholds ​

Common problems ​

Automating with Ralph (optional) ​

Appendix — A real-world multi-stack scenario ​

Next steps ​

Complete Workflow Tutorial: From Idea to Production

0. Before you start

What you will do

1. The basics in 5 minutes

Mini-glossary

1.5 Understanding execution modes (read this — it trips up everyone)

2. Verify your install

2.x Saving tokens: context and `/clear`

Step A — Build the backlog

A.1 Initialize the workflow

A.2 Generate the PRD and backlog

A.3 Validate the backlog

Step B — Design, then create the sprint

B.1 Design the technical solution

B.2 Validate the tech spec

B.3 Plan the first sprint

B.4 Decompose stories into tasks

B.5 Validate the sprint

Step C — Implement the sprint with TDD

C.1 The recommended path for beginners

C.2 Alternatives (optional)

C.3 Drive it day to day

Step D — Track progress with the Kanban board

D.1 Launch the board

D.2 Why a card may refuse to move

Step E — Close the sprint and loop

E.1 Sprint review

E.2 Retrospective

E.3 Loop

Cheat sheet

Commands, in order

When to `/clear`

Where files live

Gate thresholds

Common problems

Automating with Ralph (optional)

Appendix — A real-world multi-stack scenario

Next steps