Windsurf

Setup for Windsurf

Windsurf Quick Start

Install & Deploy

1. Install

npm install -g aiwg

2. Deploy to your project

cd /path/to/your/project

# Deploy SDLC framework:
aiwg use sdlc --provider windsurf

3. Open in Windsurf

# Windsurf automatically loads rules and agents
code /path/to/your/project  # or use Windsurf launcher

4. Regenerate for intelligent integration

/aiwg-regenerate

`aiwg use` writes a usable project context immediately. Run regeneration for every existing project and after upgrades so the context is re-tailored to the current codebase. A newly scaffolded project can defer it until project content exists. See the Regenerate Guide for details.

5. You're ready. See the Intake Guide for starting projects.

What Gets Created

AGENTS.md                    # Aggregated agent definitions (auto-loaded)
.windsurf/
├── workflows/               # Commands deployed as native workflows
├── skills/                  # Skill directories (native since v1.13.6)
└── rules/                   # Rule files with trigger frontmatter
.aiwg/                       # SDLC artifacts

Key Architecture:

Agents: Aggregated into single `AGENTS.md` at project root (Windsurf auto-discovers at root and subdirectories)
Commands: Deployed as native workflows to `.windsurf/workflows/` (manual invocation via `/workflow-name`)
Skills: Deployed to `.windsurf/skills/` (native platform support — Cascade auto-matches by description)
Rules: Deployed to `.windsurf/rules/` with YAML frontmatter for trigger control (`always_on`, `model_decision`, `glob`, `manual`)

Using Agents

Windsurf reads `AGENTS.md` automatically. Use natural language to invoke agents:

"Generate intake for an e-commerce platform"
"Transition to Elaboration"
"Run security review"
"Where are we in the project?"

@-Mention Patterns

Reference agents directly using @-mentions:

"@requirements-analyst create user stories for checkout"
"@architecture-designer review the SAD"
"@test-engineer generate integration tests"

Workflow Commands

Commands are deployed as Windsurf workflows:

/transition inception elaboration
/security-review
/project-status

Agent Aggregation

Windsurf discovers agent definitions exclusively via `AGENTS.md` files (no `.windsurf/agents/` directory support):

Why Aggregation?

Windsurf's rules engine processes `AGENTS.md` natively — root-level files are always-on
Subdirectory `AGENTS.md` files auto-scope via generated globs (`<directory>/**`)
All agent definitions remain accessible via @-mentions
Regenerate updates aggregation when framework changes

How It Works: 1. Framework defines agents in `agentic/code/frameworks/sdlc-complete/agents/` 2. Deployment aggregates all agents into root `AGENTS.md` 3. Windsurf's rules engine loads `AGENTS.md` automatically — treated as always-on rules 4. Regenerate command updates aggregation if needed

Regenerate Guide

The regenerate command is essential for Windsurf integration:

/aiwg-regenerate

What it does:

Aggregates all agent definitions into `AGENTS.md`
Updates `.windsurf/rules/` with latest orchestration patterns (with `trigger: always_on` frontmatter)
Synchronizes `.windsurf/workflows/` with command definitions
Enables natural language → workflow mapping

When to regenerate:

After initial deployment
After updating AIWG framework (`npm update -g aiwg`)
When adding custom agents or commands
If natural language workflows stop working

Windsurf Commands

# Regenerate aggregated files
/aiwg-regenerate

# Project setup
/aiwg-setup-project

# Workflow commands (examples)
/transition <from-phase> <to-phase>
/security-review
/project-status

Troubleshooting

Natural language not working?

Run regenerate to update mappings:

/aiwg-regenerate

AGENTS.md not loading?

Windsurf reads root `AGENTS.md` automatically. If agents aren't available:

1. Verify `AGENTS.md` exists at project root 2. Check file isn't empty 3. Restart Windsurf 4. Regenerate if needed

Workflows missing?

Check deployment:

# Redeploy framework
aiwg use sdlc --provider windsurf --force

# Verify workflows exist
ls .windsurf/workflows/

Commands not found?

Ensure rules are up to date:

/aiwg-regenerate

Then verify:

ls .windsurf/rules/
ls .windsurf/workflows/

Agents not responding correctly?

1. Check `AGENTS.md` contains expected agents:

   grep "^# Agent:" AGENTS.md

2. Verify aggregation is recent:

   head -n 5 AGENTS.md  # Check timestamp comment

3. Regenerate if stale:

   /aiwg-regenerate

Skills not available?

Skills are deployed to `.windsurf/skills/`:

# Check skills directory
ls .windsurf/skills/

# Redeploy if missing
aiwg use sdlc --provider windsurf --force

Support Levels

Artifact Type	Support	Location
Agents	Aggregated	`AGENTS.md` (root)
Commands	Native	`.windsurf/workflows/`
Skills	Native	`.windsurf/skills/`
Rules	Native	`.windsurf/rules/`

Aggregated: All agent definitions combined into single file (auto-discovered by rules engine) Native: Deployed to platform-specific location with full auto-discovery support

Rules System

Windsurf uses `.windsurf/rules/*.md` files with optional YAML frontmatter for trigger control. AIWG deploys rules with appropriate trigger modes:

Trigger Modes

Mode	Behavior	AIWG Usage
`always_on`	Included in system prompt every message	Orchestration rules, core conventions
`model_decision`	Description shown; full content loaded on demand	Optional guidance
`glob`	Activated when matching files are edited	Language-specific rules
`manual`	Activated via `@rule-name` mention	Reference rules

Example Rule File

---
trigger: always_on
---

Follow AIWG SDLC conventions. Use @-mentions for traceability.

Character Limits

Scope	Limit
Workspace rules (per file)	12,000 chars
Global rules	6,000 chars

Skills

Windsurf natively supports skills since v1.13.6 (January 2026). Each skill is a directory with a `SKILL.md` file:

.windsurf/skills/
  project-awareness/
    SKILL.md

Skills require `name` and `description` in YAML frontmatter. Cascade auto-matches skills by evaluating user requests against descriptions — only `name` and `description` are in context by default (progressive disclosure).

Skills are also discoverable at `.agents/skills/` (cross-agent compatibility path) and `~/.codeium/windsurf/skills/` (global).

Memories

Windsurf has an automatic memory system (since v1.1.0) that persists context across conversations:

Cascade auto-generates memories when it encounters reusable context
Stored locally at `~/.codeium/windsurf/memories/` (per-machine)
Users can explicitly request: "remember that X"
Retrieved automatically when relevant to current conversation

AIWG and Memories: Memories are local and cannot be committed to version control. For team-shareable context, AIWG uses `.windsurf/rules/` (always-on rules) and `AGENTS.md` instead. There is currently no external API for writing to the memories store.

Agent Loop

Agent loops support multi-provider execution. While Windsurf agents are deployed via AIWG, agent task loops run through the CLI:

aiwg ralph "Fix all tests" --completion "npm test passes"

See Al Guide for full documentation including `--provider` options.

Next Steps

Cross-Platform Overview - Compare platform differences
Intake Guide - Start your first project
SDLC Framework - Complete framework reference
Commands Reference - All 40 AIWG commands

MCP Sidecar (Unrestricted AIWG Access)

Windsurf has no dangerous mode flag. The MCP sidecar is the only path to unrestricted AIWG tool access:

aiwg mcp install windsurf

See the Windsurf MCP Sidecar Guide for complete setup including tool whitelisting and context optimization.

Additional Resources

Windsurf Documentation: docs.windsurf.com AIWG Repository: github.com/jmagly/aiwg Support: Discord | Telegram