Choose and implement Windsurf validated architecture blueprints for different scales.
Use when designing new Windsurf integrations, choosing between monolith/service/microservice
architectures, or planning migration paths for Windsurf applications.
Trigger with phrases like "windsurf architecture", "windsurf blueprint",
"how to structure windsurf", "windsurf project layout", "windsurf microservice".
How you structure your Windsurf workspace directly impacts Cascade's effectiveness. Large monorepos, multi-service setups, polyglot codebases, and different team sizes each require different approaches. This skill covers workspace strategies from solo projects to 100+ developer organizations.
Prerequisites
Windsurf installed
Understanding of Cascade's workspace indexing model
Git workflow established
Instructions
Variant 1: Single Project (Solo / Small Team)
Best for: 1-3 developers, single service, <10K files.
1. One Windsurf window per service/package
2. Every service has its own .windsurfrules and .codeiumignore
3. Cascade tasks scoped to current workspace only
4. Cross-service changes: open both workspaces side by side
5. Tag cascade commits: git commit -m "[cascade] description"
6. Use shared workflows from central config repo
Variant 4: Polyglot / Multi-Language
Best for: Projects with multiple languages (TypeScript + Python + Go).
# Each language has different .windsurfrules
services/
├── ts-api/
│ └── .windsurfrules # TypeScript patterns, Fastify, Vitest
├── python-ml/
│ └── .windsurfrules # Python patterns, FastAPI, pytest
└── go-gateway/
└── .windsurfrules # Go patterns, chi router, go test
<!-- .windsurfrules for Python service -->
# Project: ML Pipeline
## Stack
- Language: Python 3.11
- Framework: FastAPI
- ML: scikit-learn, pandas
- Testing: pytest with fixtures
- Type checking: mypy (strict)
## Conventions
- Use pydantic for all data models
- Async endpoints with asyncio
- Type hints on all functions
- No print() — use logging module
Variant 5: Frontend-Heavy (Design System)
Best for: UI-heavy projects with design system, Storybook, component library.
<!-- .windsurfrules for design system -->
# Project: Design System
## Stack
- Framework: React 18 + Next.js 14
- Styling: Tailwind CSS + custom tokens
- Components: Radix UI primitives
- Docs: Storybook 8
- Testing: Vitest + Testing Library
## Component Conventions
- One component per file (ComponentName.tsx)
- Co-located tests: ComponentName.test.tsx
- Co-located stories: ComponentName.stories.tsx
- Props interface exported: ComponentNameProps
- Use forwardRef for all components
- Use CVA (class-variance-authority) for variants
## Design Tokens
- Colors: use design-system/tokens, never raw Tailwind colors
- Spacing: use space-* scale (4px base)
- Typography: use text-* presets
Cascade integration: Use Previews to iterate on UI components:
"Preview the Button component with all variants"
Click elements in Preview → send to Cascade for refinement
