Update Windsurf file path from commands to workflows #610
Conversation
📝 WalkthroughWalkthroughUpdate changes Windsurf file path and filename pattern: generated files move from Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
Greptile OverviewGreptile SummaryFixed Windsurf workflow file paths from the incorrect nested structure This change:
Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant User
participant CLI as OpenSpec CLI
participant Adapter as Windsurf Adapter
participant FS as File System
User->>CLI: openspec init --tools windsurf
CLI->>Adapter: getFilePath("explore")
Adapter-->>CLI: ".windsurf/workflows/opsx-explore.md"
CLI->>Adapter: formatFile(commandContent)
Adapter-->>CLI: Formatted content with YAML frontmatter
CLI->>FS: Write file to .windsurf/workflows/opsx-explore.md
FS-->>CLI: Success
CLI-->>User: Windsurf workflows configured
Note over Adapter,FS: Changed from .windsurf/commands/opsx/<id>.md<br/>to .windsurf/workflows/opsx-<id>.md
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@src/core/command-generation/adapters/windsurf.ts`:
- Around line 34-44: The windsurfAdapter currently writes YAML frontmatter for
workflows which Windsurf does not support; update the adapter (windsurfAdapter
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.
| /** | ||
| * 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`); | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
git ls-files src/core/command-generation/adapters/ | head -20Repository: Fission-AI/OpenSpec
Length of output: 1021
🏁 Script executed:
cat -n src/core/command-generation/adapters/windsurf.tsRepository: Fission-AI/OpenSpec
Length of output: 2177
🏁 Script executed:
cat -n src/core/command-generation/adapters/cursor.tsRepository: Fission-AI/OpenSpec
Length of output: 1857
🏁 Script executed:
cat -n src/core/command-generation/adapters/cline.tsRepository: Fission-AI/OpenSpec
Length of output: 1006
🏁 Script executed:
rg -A 30 "formatFile.*commandId" src/core/command-generation/adapters/windsurf.tsRepository: Fission-AI/OpenSpec
Length of output: 45
🏁 Script executed:
sed -n '45,100p' src/core/command-generation/adapters/windsurf.tsRepository: Fission-AI/OpenSpec
Length of output: 337
🏁 Script executed:
rg "591" . -t ts -t md | head -20Repository: Fission-AI/OpenSpec
Length of output: 45
🏁 Script executed:
rg -i "windsurf" . -t ts -t md -t json | grep -v node_modules | head -30Repository: Fission-AI/OpenSpec
Length of output: 2996
🏁 Script executed:
fd "windsurf" -t f . | head -20Repository: Fission-AI/OpenSpec
Length of output: 113
🏁 Script executed:
find . -name "*windsurf*" -type f 2>/dev/null | head -20Repository: 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 -20Repository: 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 adapterRepository: Fission-AI/OpenSpec
Length of output: 110
🏁 Script executed:
wc -l src/core/command-generation/adapters/windsurf.tsRepository: Fission-AI/OpenSpec
Length of output: 114
🏁 Script executed:
cat src/core/command-generation/adapters/windsurf.tsRepository: 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 2Repository: 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 -20Repository: 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 (windsurfAdapter 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.
yangjuncode
changed the title
1 participant
Update Windsurf file path from commands to workflows, close #591
Summary by CodeRabbit
Changes
Documentation
Tests
✏️ Tip: You can customize this high-level summary in your review settings.