Team Workflows & Collaboration

Windsurf becomes exponentially more powerful when a team standardises on shared conventions, shared .windsurfrules, and shared prompt patterns. This module covers how to scale AI-native development across an engineering team -- from shared configurations and code review workflows to pair programming with AI, establishing team conventions, and building a knowledge-sharing culture around AI-assisted development.

The Foundation: Shared Configuration

Shared .windsurfrules in Practice

The .windsurfrules file is the single most important team artefact for AI-native development. When every developer on the team uses the same .windsurfrules, Cascade generates consistent code regardless of who wrote the prompt. Here is how to manage it as a team:

Ownership and Governance

• Assign an owner: Typically the tech lead or a senior engineer. The owner reviews all proposed changes to ensure rules are clear, non-contradictory, and enforceable.
• Change process: Treat .windsurfrules changes like code changes -- they go through PR review. A bad rule (ambiguous, overly broad, or conflicting) degrades every developer's Cascade experience.
• Retrospective updates: At the end of each sprint, review PR comments. If the same issue came up in multiple reviews ("you used print() instead of structlog again"), add it to .windsurfrules so Cascade prevents it going forward.
• Keep it focused: Every rule in .windsurfrules consumes context in every AI interaction. Rules that Cascade already follows naturally ("use proper indentation") waste context. Focus on rules that are specific to your project and that Cascade would not know without being told.

Layered Rules for Multi-Team Organisations

For organisations with multiple teams or projects, you can layer .windsurfrules files:

# Root .windsurfrules -- applies to all code in the monorepo
project-root/
  .windsurfrules          <-- Organisation-wide rules (language, logging, error handling)
  services/
    payment/
      .windsurfrules      <-- Payment team rules (Stripe conventions, PCI compliance)
    search/
      .windsurfrules      <-- Search team rules (Elasticsearch patterns, ranking conventions)
    auth/
      .windsurfrules      <-- Auth team rules (security patterns, token handling)

# Cascade reads the closest .windsurfrules to the file being edited,
# inheriting from parent directories.

AI-Assisted Code Review Workflows

Code review is one of the highest-leverage applications of Windsurf in a team setting. Cascade can catch mechanical issues -- convention violations, missing tests, security anti-patterns -- freeing human reviewers to focus on design, business logic, and architectural concerns.

The Pre-PR Self-Review

Before requesting human review, every developer should run a Cascade review on their own changes. This catches the embarrassing issues before a colleague sees them:

Review the staged changes in this branch for:

1. Correctness -- does the implementation match the stated goal?
2. Security -- SQL injection, auth bypasses, exposed secrets, SSRF
3. Performance -- N+1 queries, missing indexes, unbounded operations
4. Convention violations -- check against .windsurfrules
5. Missing tests -- are all new code paths covered?
6. Breaking changes -- does this change any public API or data schema?

For each issue found, provide:
- File and line number
- Severity: critical / warning / suggestion
- Specific fix recommendation

End with a summary: ready to review / needs work, with reasoning.

The Reviewer's Flow

When reviewing someone else's PR, use Cascade to accelerate your understanding of the changes:

# As a reviewer, use Chat to understand the PR before commenting

I am reviewing a PR that adds order tracking to ShopMate.
The changed files are:
@shopmate/models/order_tracking.py (new)
@shopmate/services/tracking_service.py (new)
@shopmate/api/routes/tracking.py (new)
@tests/test_tracking.py (new)
@shopmate/api/main.py (modified -- new router added)

Questions:
1. Does the new code follow our .windsurfrules conventions?
2. Are there any security concerns (auth checks, input validation)?
3. Are the tests comprehensive? What edge cases are missing?
4. Does this introduce any performance concerns (N+1 queries, large payloads)?
5. Are the error handling patterns consistent with the rest of the codebase?

Pair Programming with AI

Pair programming with Cascade is a different dynamic from traditional pair programming. In a human pair, one person drives (types) and one navigates (thinks). With Cascade, the human always navigates and Cascade always drives. Your job is to:

• Set the direction: "We need a rate limiter. Let us use the token bucket algorithm."
• Provide constraints: "Store state in Redis. Use our existing Redis connection."
• Review the plan: "That plan looks good, but add a bypass for health check endpoints."
• Catch errors: "The test is not checking the Retry-After header value. Add that assertion."
• Make decisions Cascade cannot: "Use a 60-second window, not 30. Our users are human, not bots."

When to Pair with Cascade vs. a Human

Establishing Team Conventions for AI-Native Development

When a team adopts Windsurf, new conventions are needed beyond the code itself. These conventions govern how the team interacts with AI tools:

Convention 1: Prompt Quality Standards

Define what a "good enough" Flow prompt looks like for your team. At minimum, every Flow prompt should include: the goal, the target files, test expectations, and a reference to .windsurfrules. Document this in your team's contributing guide.

Convention 2: AI-Generated Code Review Standard

AI-generated code should be reviewed with the same rigour as human-written code. In practice, reviewers should pay extra attention to: (1) edge cases the AI may have missed, (2) error handling patterns, (3) security implications, and (4) whether the generated code actually solves the stated problem or just looks like it does.

Convention 3: Attribution and Transparency

Decide as a team whether to mark AI-assisted code. Some teams add comments like "// Generated with Cascade, reviewed by [developer]" for significant AI-generated blocks. Others treat all code the same regardless of origin. The key is consistency -- pick a policy and stick to it.

Convention 4: When NOT to Use AI

Define boundaries. Common team agreements include:

• Do not use AI for security-critical code without additional human review
• Do not paste proprietary customer data into AI prompts
• Do not use AI as a substitute for understanding the code you ship
• If Cascade-generated code fails review twice, rewrite it manually to ensure understanding

Flow Template Library

A shared Flow template library is one of the highest-value team assets. Templates standardise the quality of AI interactions and save each developer from reinventing prompts for common tasks.

How to Maintain the Library

• Store templates in the repository: A docs/windsurf-templates/ directory, committed to version control, ensures everyone has access and templates are versioned.
• Categorise by task type: new-feature.md, migration.md, test-generation.md, bug-fix.md, documentation.md
• Include the prompt and expected output: Each template should show the prompt and an example of what good output looks like, so developers can judge whether Cascade's result matches expectations.
• Tag with difficulty: Some templates are suitable for junior developers; others require senior judgment to review the output.

ShopMate -- Team Flow Templates

## ShopMate Shared Flow Templates (save in docs/windsurf-templates.md)

## New Claude Feature Template
Add a new ShopMate Claude feature: [FEATURE NAME]

Endpoint: [METHOD] /[path]
Input: [JSON fields]
Output: [JSON fields]
Model: [haiku/sonnet] -- [reason: cheap utility / quality needed]

Requirements:
- Call via logged_create(brand_id=brand_id, feature="[feature_name]")
- Customer-facing replies must use safe_reply()
- System prompt in shopmate/prompts/[name].py as module-level constant
- Tests mock Claude with respx -- no real API calls in tests

Tests:
- Happy path: correct output structure
- Claude API error: graceful fallback
- Brand voice applied correctly (if multi-brand)

## New Brand Onboarding Template
Add a new brand to ShopMate: [BRAND NAME]

1. Add entry to shopmate/config/brands.yaml following threadco structure
2. Create sample product descriptions to test the brand voice
3. Add brand_id to the audit log test fixtures
4. Run: pytest tests/ to verify all existing tests still pass
5. Write 5 sample product descriptions and share with the brand for approval

Knowledge Sharing in AI-Native Teams

AI-native development creates new knowledge-sharing opportunities and challenges:

Sharing Effective Prompts

When a developer writes a Flow prompt that produces exceptional results, share it. Create a team channel (Slack, Teams, etc.) specifically for sharing effective prompts. Include: the prompt, what it produced, and why it worked well. Over time, this builds a team knowledge base of prompt patterns.

Sharing Failures

Equally valuable: share prompts that produced bad results and explain why. "I asked Cascade to migrate all tests at once and it introduced subtle bugs because the context window was overloaded. Breaking it into batches of 3 files worked much better." These failure stories prevent teammates from repeating the same mistakes.

Cascade-Assisted Documentation

Use Cascade to keep documentation current. When a significant change lands, run a Flow: "Update the README to reflect the changes in this PR. Include the new endpoint, updated configuration options, and any migration steps." This is faster than writing docs manually and produces documentation that matches the actual code because Cascade reads the code while writing the docs.

Onboarding New Team Members with Cascade

A structured onboarding process using Cascade dramatically reduces ramp-up time:

1. Day 1: New developer opens the project in Windsurf. Uses Chat: "Give me a 5-minute overview of this project's architecture, key modules, and data flow."
2. Day 1: Chat: "Walk me through the request lifecycle from API endpoint to database and back." This builds the mental model.
3. Day 2: Chat: "What are the testing patterns in this project? Show me examples of a good test file." Cascade shows actual examples from the codebase.
4. Day 2: First Flow: use a team template to add a small, well-scoped feature. The template guides the new developer's prompt, and Cascade generates code that follows the team's conventions.
5. Day 3: Submit the first PR. Run the pre-PR review Flow before requesting human review. The human review focuses on mentorship rather than catching mechanical issues.

ShopMate -- PR Review Flow

# Run this before requesting review on any ShopMate PR

Review the staged changes in this ShopMate PR for:

1. Are all new Claude calls going through logged_create()?
2. Are customer-facing replies going through safe_reply()?
3. Are there any hardcoded brand names or API keys?
4. Do new tests mock the Anthropic API (not making real calls)?
5. Is the brand_id always passed through to logged_create()?
6. Any prompt templates that use forbidden words for a brand?

For each issue: file, line, severity (blocker/warning/suggestion), and fix.
End with: ready to merge / needs fixes.

Scaling AI-Native Development

As your team grows, AI-native development practices need to scale with it. Here are the key scaling challenges and solutions:

Measuring Team AI Productivity

To justify and improve AI adoption, track these metrics:

• Time to first commit (new hires): How many days from join date to first merged PR? AI-native teams target 3 days.
• PR review turnaround: AI pre-review should reduce the number of review rounds. Track average rounds before and after adoption.
• Convention compliance: What percentage of PRs have convention violations flagged in review? This should decrease as .windsurfrules matures.
• Test coverage: AI-assisted test generation typically increases coverage. Track coverage percentage over time.
• Developer satisfaction: Survey developers quarterly on their experience with AI tools. Satisfaction predicts retention and adoption.

Hands-On Exercises