Windsurf Workflow Demo

A from‑scratch reference project that demonstrates how to use Windsurf's AI-native workflow capabilities to scaffold, plan, and iteratively build applications.

Project Goals

1. Implement a phased, repeatable AI-native software delivery workflow for green‑field projects
2. Keep it lightweight & right-sized - start small, grow as needed
3. Codify everything as code & markdown for reproducibility
4. Serve as a living template that teams can adapt for any stack

🚀 Quick Start

# Clone the repo
$ git clone https://github.com/liatrio/windsurf-lessons-workflows.git && cd windsurf-lessons-workflows

# Open in Windsurf (or VS Code if you have the Windsurf extension)
$ windsurf .

1. Install Windsurf if you haven't already (https://windsurf.ai).
2. Confirm your global rules (see global_rules.md and .windsurf/rules/).
3. Run the first workflow:

   /project-01-define-product <your-product-idea>
   

4. Follow the prompts—the rest of the repo (PRD, user stories, architecture docs, feature branches, tests) will be generated step‑by‑step.

Tip 🧠: Everything lives in Git history. If the agent drifts, just git reset --hard to your last good commit and retry.

---

Repository Structure

.windsurf/
  workflows/          # Sequential and general purpose workflows (see below)
  rules/              # Coding & style conventions
docs/
  templates/          # PRD and ADR templates
global_rules.md       # Development principles & AI behavior (Set in Windsurf)
WORKFLOWS.md          # Detailed workflow example documentation

Flow Diagram

  flowchart LR
      Start([High-Level Idea]) --> Step1[Product Requirements]
      Step1 --> Step2[Research]
      Step2 --> Step3[Stories & Acceptance Criteria]
      Step3 --> Step4[Design Architecture]
      Step4 --> Step5[Review & Validate]
      Step5 --> Step6[Generate Windsurf Rules]
      Step6 --> Step7[Initialize Project]
      Step7 --> Step8[Decompose Features]
      Step8 --> Step9[Develop Feature<br/>TDD: Tests → Code → Refactor]
      Step9 --> Step10[Stage Changes<br/>Incremental Commits]
      Step10 --> FeatureComplete[Feature Complete]
      FeatureComplete --> PR[Local Code Review<br />Create Pull Request]
      PR --> Check{More Features<br/>to Develop?}
      Check -->|Yes| Step9

      %% Dark mode optimized styling
      classDef planPhase fill:#1e3a5f,stroke:#4fc3f7,stroke-width:2px,color:#e1f5fe
      classDef buildPhase fill:#1b4332,stroke:#66bb6a,stroke-width:2px,color:#e8f5e9
      classDef startEnd fill:#4a148c,stroke:#ce93d8,stroke-width:3px,color:#f3e5f5
      classDef decision fill:#5d4e37,stroke:#ffc947,stroke-width:2px,color:#fff3e0
      classDef milestone fill:#01579b,stroke:#4fc3f7,stroke-width:2px,color:#e1f5fe
      classDef reviewPhase fill:#4a1c1c,stroke:#ef5350,stroke-width:2px,color:#ffebee

      class Step1,Step2,Step3,Step4,Step5,Step6 planPhase
      class Step7,Step8,Step9,Step10 buildPhase
      class Start startEnd
      class Check decision
      class FeatureComplete milestone
      class PR reviewPhase

Loading

Sequential Workflows

#	Command	Purpose	Output	Action
1	/project-01-define-product	Define product vision	PRD	Review & refine before research
2	/project-02-product-research	Product research	Analysis	Incorporate findings into stories
3	/project-03-create-user-stories	Transform PRD to stories	User stories	Validate with stakeholders
4	/project-04-design-architecture	Choose stack & patterns	ADRs	Document decisions & rationale
5	/project-05-review	Review planning docs	Validated plan	Address gaps before coding
6	/project-06-generate-rules	Project-specific rules	Guidelines	Add to Windsurf settings
7	/project-07-project-initialization	Scaffold codebase	Project structure	Verify build & test setup
8	/project-08-plan-features	Plan development	Feature specs	Prioritize & sequence work
9	/project-09-develop-feature	TDD implementation	Tests + Features	Stage changes for review

General Purpose Workflows

#	Command	Purpose	Output	Action
10	/code-review	Code review	Code review	Address feedback & iterate
11	/stage-changes	Propose commits	Commits	Review & commit changes

What's Included

Templates: PRD template, ADR template, Windsurf global rules
Workflows: 10 sequential workflows from idea to implementation
Principles: TDD, modular architecture, security-first, performance optimization
AI Behavior: Requirement understanding, clarifying questions, pattern recognition

Extending the Template

For existing codebases: Replace phases 1-2 with discovery workflow, adapt stories to current state
Custom integrations: Add MCP servers, extend workflows, customize templates
Scaling: Remove unneeded phases, add deployment/monitoring workflows, match team processes

Ready to Start?

1. Fork this repository
2. Run /project-01-define-product with your product idea
3. Follow the workflow sequence
4. Customize as needed
5. Delete this README.md and WORKFLOWS.md when you're ready to start.