diff --git a/README.md b/README.md
index 83f1e72..8452dfb 100644
--- a/README.md
+++ b/README.md
@@ -9,8 +9,63 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
 
 ---
 
+## Development Workflow (Step by Step)
+
+How a project goes from idea to working code with this boilerplate:
+
+```
+Idea → /setup-project → /define-design → refine design → /generate-app → /add-feature (repeat)
+```
+
+### Step 1 — Write down your idea
+Put your brainstorming notes, requirements, and constraints into
+`docs/ideas/initial-requirements.md` (free-form; replace the sample content with your own).
+
+### Step 2 — Create the specification: `/setup-project`
+Automatically creates the six persistent documents that define **what to build**:
+PRD, functional design, architecture, repository structure, development guidelines, and glossary
+(all under `docs/`). Review them and request edits in normal conversation if needed.
+
+### Step 3 — Define the UI/UX design: `/define-design`
+Creates the design specification under `docs/design/`: design brief, design tokens,
+**`ui-blueprint.json` (the source of truth for UI generation)**, platform mapping, and SVG
+wireframes (visual references only). You'll be asked once about platform, style, screens,
+navigation, branding, and accessibility.
+
+### Step 4 — Review and refine the design **before writing any code**
+This is the key design-decision gate: iterate on the design while it is still cheap to change.
+
+- `/update-design <change>` — targeted refinements (e.g. `add a profile screen`)
+- Re-run `/define-design` — change the overall direction
+- Repeat until you approve the design (especially `ui-blueprint.json`)
+
+### Step 5 — Generate the initial app: `/generate-app web | flutter | winui3`
+Scaffolds the app shell from the approved design: theme (from tokens), routes, screens, and
+reusable components. No feature logic yet.
+
+### Step 6 — Implement features: `/add-feature <feature>`
+A fully autonomous loop, one feature at a time. Each run:
+
+1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
+2. Reads the design spec first — and updates it first if the feature changes the UI
+3. Implements every task in `tasklist.md`, checking items off as it goes
+4. Validates quality with the `implementation-validator` subagent
+5. Runs `npm test`, `npm run lint`, `npm run typecheck` until green
+6. Records a retrospective and reconciles all six `docs/` documents with the feature
+
+### Step 7 — Repeat and maintain
+- More features → `/add-feature <feature>` (again and again)
+- UI changes → `/update-design <change>` first, then `/add-feature`
+- Document quality checks → `/review-docs <path>`
+
+**A feature is "done" when**: all tasks in its tasklist are `[x]`, validation passes,
+test/lint/typecheck succeed, and the persistent documents are back in sync with the code.
+
+---
+
 ## Table of Contents
 
+- [Development Workflow (Step by Step)](#development-workflow-step-by-step)
 - [What Is Spec-Driven Development?](#what-is-spec-driven-development)
 - [Conversion Summary (Claude Code → opencode)](#conversion-summary-claude-code--opencode)
 - [Prerequisites](#prerequisites)