From windsurf-pack
Guides Windsurf workspace layouts for solo projects, monorepos, multi-services, and large teams up to 100+ developers.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin windsurf-packThis skill is limited to using the following tools:
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.
Implements Windsurf reference architecture with project structure, rules, workflows, and configs to optimize Cascade AI. Use for workspace setup, team standards, and architecture patterns.
Sets up Windsurf IDE workspaces with .windsurfrules for AI rules, editor settings.json, extensions, cross-editor configs, and team standards for projects and monorepos.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Share bugs, ideas, or general feedback.
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.
Best for: 1-3 developers, single service, <10K files.
my-project/
├── .windsurfrules # Full project context
├── .codeiumignore # Exclude build artifacts
├── src/
├── tests/
├── package.json
└── README.md
Configuration:
.windsurfrules contains complete stack and architecture detailsBest for: 3-15 developers, monorepo with 2-10 packages.
monorepo/
├── .windsurfrules # Brief shared conventions
├── .codeiumignore # Aggressive exclusions at root
├── packages/
│ ├── api/
│ │ ├── .windsurfrules # API-specific rules
│ │ └── .codeiumignore
│ ├── web/
│ │ ├── .windsurfrules # Frontend-specific rules
│ │ └── .codeiumignore
│ └── shared/
│ ├── .windsurfrules # Library conventions
│ └── .codeiumignore
└── .windsurf/
└── workflows/ # Shared workflows
Strategy:
# Each developer opens their package directory:
windsurf packages/api/ # Backend dev
windsurf packages/web/ # Frontend dev
windsurf packages/shared/ # Library maintainer
# NOT: windsurf monorepo/ # Too broad!
Best for: 15+ developers, microservices, 50K+ total files.
Developer A: Windsurf → services/auth/ (auth service)
Developer B: Windsurf → services/payments/ (payments)
Developer C: Windsurf → services/notifications/ (notifications)
Developer D: Windsurf → shared/libs/ (shared libraries)
Each developer gets focused Cascade context per workspace window.
Team conventions:
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
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
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
| Factor | Solo | Focused Mono | Multi-Window | Polyglot |
|---|---|---|---|---|
| Team Size | 1-3 | 3-15 | 15+ | Any |
| Codebase | <10K files | 10K-50K | 50K+ | Mixed |
| Cascade Speed | Fast | Fast (per window) | Fast (per window) | Fast (per window) |
| Setup Effort | Minimal | .codeiumignore + rules | Per-service config | Per-language rules |
| Context Quality | Excellent | Good | Good | Good (per lang) |
| Issue | Cause | Solution |
|---|---|---|
| Cascade is slow | Too many files indexed | Open smaller workspace, add .codeiumignore |
| Wrong file context | Monorepo root open | Open specific service directory |
| Conflicting edits | Multiple devs, same files | Feature branches per Cascade session |
| Wrong language patterns | Multi-language workspace | Separate .windsurfrules per language directory |
| Stale suggestions | Index out of date | Command Palette > "Codeium: Reset Indexing" |
node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.map
__pycache__/
.venv/
target/
vendor/
*.log
*.sqlite
set -euo pipefail
FILE_COUNT=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
echo "Indexed files: ~$FILE_COUNT"
[ "$FILE_COUNT" -gt 10000 ] && echo "WARNING: Consider opening a subdirectory"
[ -f .windsurfrules ] && echo "Rules: $(wc -c < .windsurfrules) chars" || echo "Rules: MISSING"
[ -f .codeiumignore ] && echo "Ignore: $(wc -l < .codeiumignore) patterns" || echo "Ignore: MISSING"
For known pitfalls and anti-patterns, see windsurf-known-pitfalls.