How to set up Windsurf for SpecDD

How-To Set up your agent Beginner 1021004HOWTO-1021004

HOWTO-1021004Set up your agentBeginner

This guide shows you how to set up Windsurf for SpecDD using the universal Agent Skills package.

Agent Skills give Cascade SpecDD workflow knowledge. The project bootstrap files and .sdd specs remain the source of truth for intent, constraints, local authority, and verification.

Source and install details: github.com/specdd/agentskills

Prerequisites

Before you start, make sure you have:

Windsurf installed
the SpecDD CLI installed
a project where SpecDD is initialized or can be initialized

Steps

1. Initialize SpecDD

From the project root:

specdd init

This creates:

AGENTS.md
CLAUDE.md
.specdd/
  bootstrap.md
  bootstrap.project.md
  bootstrap.local.md

Add a root .sdd file named after the selected content root directory if one does not exist yet.

2. Deploy universal Agent Skills

From the project root, install SpecDD Agent Skills into the current project’s Agent Skills directory:

specdd agentskills deploy

This installs skills into:

.agents/skills

3. Deploy into another project directory

Install into a different project path:

specdd agentskills deploy path/to/project

Use this when you are preparing a repository before opening it in Windsurf.

4. Use user-level or manual install

For a user-level install, use:

specdd agentskills deploy --user

That installs into:

~/.agents/skills

For manual installation, clone the universal Agent Skills package and copy the specdd-* skill directories into the target skills directory Windsurf reads.

5. Open the project root in Windsurf

Open the folder that contains:

AGENTS.md
.specdd/
<root-name>.sdd

Opening a nested folder can make / paths and inherited specs resolve from the wrong place.

6. Verify Cascade can use SpecDD

Use a small orientation request:

Orient in this SpecDD project.

Then ask about a real spec:

Explain the Itinerary spec.

Cascade should describe relevant specs, constraints, allowed files, and verification before changing code.

7. Use a small setup check

After orientation works, test one small planned change:

Plan the Itinerary validation change.

Implement the open validation task.

Common mistakes

Deploying Agent Skills to a directory Windsurf does not read.
Skipping specdd init before testing SpecDD behavior.
Opening only a nested source folder.
Manually copying the package wrapper instead of the specdd-* skill directories.
Skipping the orientation check after deployment.

How to verify the result

Windsurf is ready for SpecDD when:

.agents/skills or ~/.agents/skills contains the SpecDD skills
the project has .specdd/bootstrap.md
orientation and explanation requests mention relevant .sdd specs
planning responses identify allowed files, constraints, and checks
implementation stays inside the paths allowed by the local spec

← Set up your agent guides