Skip to content

Update Windsurf file path from commands to workflows #610

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 3 commits into from
Jan 30, 2026
Merged

Update Windsurf file path from commands to workflows #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
04dc6de
fix windsurf workrules
yangjuncode Jan 28, 2026
d59a0b3
fix a missing update
yangjuncode Jan 28, 2026
4772d71
Merge main into fix-windsurf-workrules
TabishB Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/supported-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ For each tool you select, OpenSpec installs:
| Qwen Code | `.qwen/skills/` | `.qwen/commands/` |
| RooCode | `.roo/skills/` | `.roo/commands/` |
| Trae | `.trae/skills/` | `.trae/skills/` (via `/openspec-*`) |
| Windsurf | `.windsurf/skills/` | `.windsurf/commands/opsx/` |
| Windsurf | `.windsurf/skills/` | `.windsurf/workflows/` |

## Non-Interactive Setup

Expand Down
2 changes: 1 addition & 1 deletion openspec/changes/multi-provider-skill-generation/specs/command-generation/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ The system SHALL define a `ToolCommandAdapter` interface for per-tool formatting

- **WHEN** formatting a command for Windsurf
- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `category`, `tags` fields
- **AND** file path SHALL follow pattern `.windsurf/commands/opsx/<id>.md`
- **AND** file path SHALL follow pattern `.windsurf/workflows/opsx-<id>.md`

### Requirement: Command generator function

Expand Down
4 changes: 2 additions & 2 deletions src/core/command-generation/adapters/windsurf.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,14 @@ function formatTagsArray(tags: string[]): string {

/**
* Windsurf adapter for command generation.
* File path: .windsurf/commands/opsx/<id>.md
* File path: .windsurf/workflows/opsx-<id>.md
* Frontmatter: name, description, category, tags
*/
export const windsurfAdapter: ToolCommandAdapter = {
toolId: 'windsurf',

getFilePath(commandId: string): string {
return path.join('.windsurf', 'commands', 'opsx', `${commandId}.md`);
return path.join('.windsurf', 'workflows', `opsx-${commandId}.md`);
},
Comment on lines 34 to 44
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

git ls-files src/core/command-generation/adapters/ | head -20

Repository: Fission-AI/OpenSpec

Length of output: 1021

🏁 Script executed:

cat -n src/core/command-generation/adapters/windsurf.ts

Repository: Fission-AI/OpenSpec

Length of output: 2177

🏁 Script executed:

cat -n src/core/command-generation/adapters/cursor.ts

Repository: Fission-AI/OpenSpec

Length of output: 1857

🏁 Script executed:

cat -n src/core/command-generation/adapters/cline.ts

Repository: Fission-AI/OpenSpec

Length of output: 1006

🏁 Script executed:

rg -A 30 "formatFile.*commandId" src/core/command-generation/adapters/windsurf.ts

Repository: Fission-AI/OpenSpec

Length of output: 45

🏁 Script executed:

sed -n '45,100p' src/core/command-generation/adapters/windsurf.ts

Repository: Fission-AI/OpenSpec

Length of output: 337

🏁 Script executed:

rg "591" . -t ts -t md | head -20

Repository: Fission-AI/OpenSpec

Length of output: 45

🏁 Script executed:

rg -i "windsurf" . -t ts -t md -t json | grep -v node_modules | head -30

Repository: Fission-AI/OpenSpec

Length of output: 2996

🏁 Script executed:

fd "windsurf" -t f . | head -20

Repository: Fission-AI/OpenSpec

Length of output: 113

🏁 Script executed:

find . -name "*windsurf*" -type f 2>/dev/null | head -20

Repository: Fission-AI/OpenSpec

Length of output: 113

🏁 Script executed:

ls -la src/core/command-generation/adapters/*.test.ts src/core/command-generation/adapters/__tests__/ 2>/dev/null | head -20

Repository: Fission-AI/OpenSpec

Length of output: 45

🏁 Script executed:

find . -path ./node_modules -prune -o -name "*.test.ts" -type f -print 2>/dev/null | grep -i adapter

Repository: Fission-AI/OpenSpec

Length of output: 110

🏁 Script executed:

wc -l src/core/command-generation/adapters/windsurf.ts

Repository: Fission-AI/OpenSpec

Length of output: 114

🏁 Script executed:

cat src/core/command-generation/adapters/windsurf.ts

Repository: Fission-AI/OpenSpec

Length of output: 1778

🌐 Web query:

Windsurf IDE workflow file format YAML frontmatter specification

💡 Result:

Windsurf Workflow files are Markdown (.md) files stored under .windsurf/workflows/ (and can also be discovered in subdirectories / up to the git root). They are invoked in Cascade via a slash command /[workflow-name], and the docs describe their contents as a title, a description, and an ordered series of steps/instructions. The official Windsurf docs do not publish a YAML-frontmatter schema/spec for workflow files (i.e., no documented required/optional frontmatter keys for workflows). [1]

What is explicitly documented in Windsurf is YAML frontmatter for Skills (.windsurf/skills/<skill-name>/SKILL.md), where the frontmatter uses --- delimiters and includes (at least) name and description. [2]

Sources:
[1] Windsurf Docs – Workflows (storage/discovery/character limit; “title, description, and steps”; slash invocation)
[2] Windsurf Docs – Cascade Skills (SKILL.md YAML frontmatter example/required fields)

🏁 Script executed:

rg -i "workflow" src/core/command-generation/adapters/windsurf.ts -B 2 -A 2

Repository: Fission-AI/OpenSpec

Length of output: 336

🌐 Web query:

Windsurf IDE .windsurf/workflows directory structure file format

💡 Result:

.windsurf/workflows directory structure (discovery)

Windsurf/Cascade loads workflow files from any folder named:

  • ./.windsurf/workflows/ (at your workspace root)
  • ./**/.windsurf/workflows/ (in any subdirectory)
  • For git repos, it also searches parent directories up to the git root for .windsurf/workflows/ folders (so workflows can be shared from higher-level folders). New workflows you create are saved to the current workspace’s .windsurf/workflows/ (not necessarily the git root). [1]

(Enterprise) System-level workflows can also be deployed via OS directories like /Library/Application Support/Windsurf/workflows/*.md, /etc/windsurf/workflows/*.md, or C:\ProgramData\Windsurf\workflows\*.md, and they take precedence over workspace/global/built-in workflows. [1]

File format

  • One workflow = one Markdown file (.md) placed in a discovered .windsurf/workflows/ directory. [1]
  • A workflow Markdown file should include a title, a description, and a sequence of steps/instructions for Cascade to follow. [1]
  • File size limit: 12,000 characters per workflow file. [1]

Minimal template (practical)

# /my-workflow-name
One-line description of what this does.

1. Step one instruction for Cascade.
2. Step two instruction.
3. (Optional) Include code blocks/CLI commands as needed.

Invocation: type /my-workflow-name in Cascade. [1]

Sources:
[1] Windsurf Docs — “Workflows” (storage locations, discovery rules, and that workflows are .md with title/description/steps; size limit; enterprise paths/precedence). (docs.windsurf.com)

Citations:

🏁 Script executed:

rg -i "opsx-" . --type ts --type md | head -20

Repository: Fission-AI/OpenSpec

Length of output: 2274

Path structure is correct, but frontmatter format is unsupported for Windsurf workflows.

The path change to .windsurf/workflows/opsx-<id>.md aligns with Windsurf's directory structure, but the implementation has a critical issue: the adapter generates YAML frontmatter (name, description, category, tags), which is not documented in Windsurf's official workflow specification. According to Windsurf documentation, workflow files should contain a markdown title, description, and ordered steps—not YAML frontmatter. YAML frontmatter is only documented for Windsurf Skills (.windsurf/skills/), not workflows.

The current format may not work with actual Windsurf workflows. Consider either: (1) removing the YAML frontmatter and using markdown headers similar to the Cline adapter, or (2) clarifying that this format is intended for Skills, not workflows, and adjust the file path accordingly.

🤖 Prompt for AI Agents 
In `@src/core/command-generation/adapters/windsurf.ts` around lines 34 - 44, The
windsurfAdapter currently writes YAML frontmatter for workflows which Windsurf
does not support; update the adapter (wind​surfAdapter and its getFilePath
usage) to either (A) output workflows as markdown with a title, description
paragraph and ordered steps (mirroring the Cline adapter format) and keep the
path '.windsurf/workflows/opsx-<id>.md', or (B) if YAML frontmatter is intended
for Skills, change getFilePath to place files under
'.windsurf/skills/opsx-<id>.md' and keep the frontmatter; implement one of these
two fixes consistently across the adapter so generated files match Windsurf's
documented format.


formatFile(content: CommandContent): string {
Expand Down
4 changes: 2 additions & 2 deletions test/core/command-generation/adapters.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ describe('command-generation/adapters', () => {

it('should generate correct file path', () => {
const filePath = windsurfAdapter.getFilePath('explore');
expect(filePath).toBe(path.join('.windsurf', 'commands', 'opsx', 'explore.md'));
expect(filePath).toBe(path.join('.windsurf', 'workflows', 'opsx-explore.md'));
});

it('should format file similar to Claude format', () => {
Expand Down Expand Up @@ -495,7 +495,7 @@ describe('command-generation/adapters', () => {

it('Windsurf adapter uses path.join for paths', () => {
const filePath = windsurfAdapter.getFilePath('test');
expect(filePath.split(path.sep)).toEqual(['.windsurf', 'commands', 'opsx', 'test.md']);
expect(filePath.split(path.sep)).toEqual(['.windsurf', 'workflows', 'opsx-test.md']);
});

it('All adapters use path.join for paths', () => {
Expand Down
4 changes: 2 additions & 2 deletions test/core/init.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ describe('InitCommand', () => {
await fs.mkdir(testDir, { recursive: true });

// Mock console.log to suppress output during tests
vi.spyOn(console, 'log').mockImplementation(() => {});
vi.spyOn(console, 'log').mockImplementation(() => { });
});

afterEach(async () => {
Expand Down Expand Up @@ -375,7 +375,7 @@ describe('InitCommand', () => {
const initCommand = new InitCommand({ tools: 'windsurf', force: true });
await initCommand.execute(testDir);

const cmdFile = path.join(testDir, '.windsurf', 'commands', 'opsx', 'explore.md');
const cmdFile = path.join(testDir, '.windsurf', 'workflows', 'opsx-explore.md');
expect(await fileExists(cmdFile)).toBe(true);
});

Expand Down
5 changes: 2 additions & 3 deletions test/core/update.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,9 +301,8 @@ Old instructions content
const windsurfCmd = path.join(
testDir,
'.windsurf',
'commands',
'opsx',
'explore.md'
'workflows',
'opsx-explore.md'
);
const exists = await FileSystemUtils.fileExists(windsurfCmd);
expect(exists).toBe(true);
Expand Down
Loading