feat(windsurf): add Windsurf as converter target with global scope support

Add `--to windsurf` target for the converter CLI with full spec compliance per docs/specs/windsurf.md: - Claude agents → Windsurf skills (skills/{name}/SKILL.md) - Claude commands → Windsurf workflows (workflows/{name}.md, flat) - Pass-through skills copy unchanged - MCP servers → mcp_config.json (merged with existing, 0o600 permissions) - Hooks skipped with warning, CLAUDE.md skipped Global scope support via generic --scope flag (Windsurf as first adopter): - --to windsurf defaults to global (~/.codeium/windsurf/) - --scope workspace for project-level .windsurf/ output - --output overrides scope-derived paths Shared utilities extracted (resolveTargetOutputRoot, hasPotentialSecrets) to eliminate duplication across CLI commands. 68 new tests (converter, writer, scope resolution). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 18:36:34 +08:00
parent 63e76cf67f
commit 6fe51a0602
19 changed files with 3361 additions and 62 deletions
--- a/docs/specs/windsurf.md
+++ b/docs/specs/windsurf.md
@@ -0,0 +1,477 @@
+# Windsurf Editor Global Configuration Guide
+
+> **Purpose**: Technical reference for programmatically creating and managing Windsurf's global Skills, Workflows, and Rules.
+>
+> **Source**: Official Windsurf documentation at [docs.windsurf.com](https://docs.windsurf.com) + local file analysis.
+>
+> **Last Updated**: February 2026
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Base Directory Structure](#base-directory-structure)
+3. [Skills](#skills)
+4. [Workflows](#workflows)
+5. [Rules](#rules)
+6. [Memories](#memories)
+7. [System-Level Configuration (Enterprise)](#system-level-configuration-enterprise)
+8. [Programmatic Creation Reference](#programmatic-creation-reference)
+9. [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+Windsurf provides three main customization mechanisms:
+
+| Feature | Purpose | Invocation |
+|---------|---------|------------|
+| **Skills** | Complex multi-step tasks with supporting resources | Automatic (progressive disclosure) or `@skill-name` |
+| **Workflows** | Reusable step-by-step procedures | Slash command `/workflow-name` |
+| **Rules** | Behavioral guidelines and preferences | Trigger-based (always-on, glob, manual, or model decision) |
+
+All three support both **workspace-level** (project-specific) and **global** (user-wide) scopes.
+
+---
+
+## Base Directory Structure
+
+### Global Configuration Root
+
+| OS | Path |
+|----|------|
+| **Windows** | `C:\Users\{USERNAME}\.codeium\windsurf\` |
+| **macOS** | `~/.codeium/windsurf/` |
+| **Linux** | `~/.codeium/windsurf/` |
+
+### Directory Layout
+
+```
+~/.codeium/windsurf/
+├── skills/                    # Global skills (directories)
+│   └── {skill-name}/
+│       └── SKILL.md
+├── workflows/                 # Global workflows (flat .md files)
+│   └── {workflow-name}.md
+├── rules/                     # Global rules (flat .md files)  
+│   └── {rule-name}.md
+├── memories/
+│   ├── global_rules.md        # Always-on global rules (plain text)
+│   └── *.pb                   # Auto-generated memories (protobuf)
+├── mcp_config.json            # MCP server configuration
+└── user_settings.pb           # User settings (protobuf)
+```
+
+---
+
+## Skills
+
+Skills bundle instructions with supporting resources for complex, multi-step tasks. Cascade uses **progressive disclosure** to automatically invoke skills when relevant.
+
+### Storage Locations
+
+| Scope | Location |
+|-------|----------|
+| **Global** | `~/.codeium/windsurf/skills/{skill-name}/SKILL.md` |
+| **Workspace** | `.windsurf/skills/{skill-name}/SKILL.md` |
+
+### Directory Structure
+
+Each skill is a **directory** (not a single file) containing:
+
+```
+{skill-name}/
+├── SKILL.md              # Required: Main skill definition
+├── references/           # Optional: Reference documentation
+├── assets/               # Optional: Images, diagrams, etc.
+├── scripts/              # Optional: Helper scripts
+└── {any-other-files}     # Optional: Templates, configs, etc.
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: skill-name
+description: Brief description shown to model to help it decide when to invoke the skill
+---
+
+# Skill Title
+
+Instructions for the skill go here in markdown format.
+
+## Section 1
+Step-by-step guidance...
+
+## Section 2
+Reference supporting files using relative paths:
+- See [deployment-checklist.md](./deployment-checklist.md)
+- Run script: [deploy.sh](./scripts/deploy.sh)
+```
+
+### Required YAML Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **Yes** | Unique identifier (lowercase letters, numbers, hyphens only). Must match directory name. |
+| `description` | **Yes** | Explains what the skill does and when to use it. Critical for automatic invocation. |
+
+### Naming Convention
+
+- Use **lowercase-kebab-case**: `deploy-to-staging`, `code-review`, `setup-dev-environment`
+- Name must match the directory name exactly
+
+### Invocation Methods
+
+1. **Automatic**: Cascade automatically invokes when request matches skill description
+2. **Manual**: Type `@skill-name` in Cascade input
+
+### Example: Complete Skill
+
+```
+~/.codeium/windsurf/skills/deploy-to-production/
+├── SKILL.md
+├── deployment-checklist.md
+├── rollback-procedure.md
+└── config-template.yaml
+```
+
+**SKILL.md:**
+```markdown
+---
+name: deploy-to-production
+description: Guides the deployment process to production with safety checks. Use when deploying to prod, releasing, or pushing to production environment.
+---
+
+## Pre-deployment Checklist
+1. Run all tests
+2. Check for uncommitted changes
+3. Verify environment variables
+
+## Deployment Steps
+Follow these steps to deploy safely...
+
+See [deployment-checklist.md](./deployment-checklist.md) for full checklist.
+See [rollback-procedure.md](./rollback-procedure.md) if issues occur.
+```
+
+---
+
+## Workflows
+
+Workflows define step-by-step procedures invoked via slash commands. They guide Cascade through repetitive tasks.
+
+### Storage Locations
+
+| Scope | Location |
+|-------|----------|
+| **Global** | `~/.codeium/windsurf/workflows/{workflow-name}.md` |
+| **Workspace** | `.windsurf/workflows/{workflow-name}.md` |
+
+### File Format
+
+Workflows are **single markdown files** (not directories):
+
+```markdown
+---
+description: Short description of what the workflow does
+---
+
+# Workflow Title
+
+> Arguments: [optional arguments description]
+
+Step-by-step instructions in markdown.
+
+1. First step
+2. Second step
+3. Third step
+```
+
+### Required YAML Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | **Yes** | Short title/description shown in UI |
+
+### Invocation
+
+- Slash command: `/workflow-name`
+- Filename becomes the command (e.g., `deploy.md` → `/deploy`)
+
+### Constraints
+
+- **Character limit**: 12,000 characters per workflow file
+- Workflows can call other workflows: Include instructions like "Call `/other-workflow`"
+
+### Example: Complete Workflow
+
+**File**: `~/.codeium/windsurf/workflows/address-pr-comments.md`
+
+```markdown
+---
+description: Address all PR review comments systematically
+---
+
+# Address PR Comments
+
+> Arguments: [PR number]
+
+1. Check out the PR branch: `gh pr checkout [id]`
+
+2. Get comments on PR:
+   ```bash
+   gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line}'
+   ```
+
+3. For EACH comment:
+   a. Print: "(index). From [user] on [file]:[lines] — [body]"
+   b. Analyze the file and line range
+   c. If unclear, ask for clarification
+   d. Make the change before moving to next comment
+
+4. Summarize what was done and which comments need attention
+```
+
+---
+
+## Rules
+
+Rules provide persistent behavioral guidelines that influence how Cascade responds.
+
+### Storage Locations
+
+| Scope | Location |
+|-------|----------|
+| **Global** | `~/.codeium/windsurf/rules/{rule-name}.md` |
+| **Workspace** | `.windsurf/rules/{rule-name}.md` |
+
+### File Format
+
+Rules are **single markdown files**:
+
+```markdown
+---
+description: When to use this rule
+trigger: activation_mode
+globs: ["*.py", "src/**/*.ts"]
+---
+
+Rule instructions in markdown format.
+
+- Guideline 1
+- Guideline 2
+- Guideline 3
+```
+
+### YAML Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | **Yes** | Describes when to use the rule |
+| `trigger` | Optional | Activation mode (see below) |
+| `globs` | Optional | File patterns for glob trigger |
+
+### Activation Modes (trigger field)
+
+| Mode | Value | Description |
+|------|-------|-------------|
+| **Manual** | `manual` | Activated via `@mention` in Cascade input |
+| **Always On** | `always` | Always applied to every conversation |
+| **Model Decision** | `model_decision` | Model decides based on description |
+| **Glob** | `glob` | Applied when working with files matching pattern |
+
+### Constraints
+
+- **Character limit**: 12,000 characters per rule file
+
+### Example: Complete Rule
+
+**File**: `~/.codeium/windsurf/rules/python-style.md`
+
+```markdown
+---
+description: Python coding standards and style guidelines. Use when writing or reviewing Python code.
+trigger: glob
+globs: ["*.py", "**/*.py"]
+---
+
+# Python Coding Guidelines
+
+- Use type hints for all function parameters and return values
+- Follow PEP 8 style guide
+- Use early returns when possible
+- Always add docstrings to public functions and classes
+- Prefer f-strings over .format() or % formatting
+- Use pathlib instead of os.path for file operations
+```
+
+---
+
+## Memories
+
+### Global Rules (Always-On)
+
+**Location**: `~/.codeium/windsurf/memories/global_rules.md`
+
+This is a special file for rules that **always apply** to all conversations. Unlike rules in the `rules/` directory, this file:
+
+- Does **not** require YAML frontmatter
+- Is plain text/markdown
+- Is always active (no trigger configuration)
+
+**Format:**
+```markdown
+Plain text rules that always apply to all conversations.
+
+- Rule 1
+- Rule 2
+- Rule 3
+```
+
+### Auto-Generated Memories
+
+Cascade automatically creates memories during conversations, stored as `.pb` (protobuf) files in `~/.codeium/windsurf/memories/`. These are managed by Windsurf and should not be manually edited.
+
+---
+
+## System-Level Configuration (Enterprise)
+
+Enterprise organizations can deploy system-level configurations that apply globally and cannot be modified by end users.
+
+### System-Level Paths
+
+| Type | Windows | macOS | Linux/WSL |
+|------|---------|-------|-----------|
+| **Rules** | `C:\ProgramData\Windsurf\rules\*.md` | `/Library/Application Support/Windsurf/rules/*.md` | `/etc/windsurf/rules/*.md` |
+| **Workflows** | `C:\ProgramData\Windsurf\workflows\*.md` | `/Library/Application Support/Windsurf/workflows/*.md` | `/etc/windsurf/workflows/*.md` |
+
+### Precedence Order
+
+When items with the same name exist at multiple levels:
+
+1. **System** (highest priority) - Organization-wide, deployed by IT
+2. **Workspace** - Project-specific in `.windsurf/`
+3. **Global** - User-defined in `~/.codeium/windsurf/`
+4. **Built-in** - Default items provided by Windsurf
+
+---
+
+## Programmatic Creation Reference
+
+### Quick Reference Table
+
+| Type | Path Pattern | Format | Key Fields |
+|------|--------------|--------|------------|
+| **Skill** | `skills/{name}/SKILL.md` | YAML frontmatter + markdown | `name`, `description` |
+| **Workflow** | `workflows/{name}.md` | YAML frontmatter + markdown | `description` |
+| **Rule** | `rules/{name}.md` | YAML frontmatter + markdown | `description`, `trigger`, `globs` |
+| **Global Rules** | `memories/global_rules.md` | Plain text/markdown | None |
+
+### Minimal Templates
+
+#### Skill (SKILL.md)
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+Instructions here.
+```
+
+#### Workflow
+```markdown
+---
+description: What this workflow does
+---
+
+1. Step one
+2. Step two
+```
+
+#### Rule
+```markdown
+---
+description: When this rule applies
+trigger: model_decision
+---
+
+- Guideline one
+- Guideline two
+```
+
+### Validation Checklist
+
+When programmatically creating items:
+
+- [ ] **Skills**: Directory exists with `SKILL.md` inside
+- [ ] **Skills**: `name` field matches directory name exactly
+- [ ] **Skills**: Name uses only lowercase letters, numbers, hyphens
+- [ ] **Workflows/Rules**: File is `.md` extension
+- [ ] **All**: YAML frontmatter uses `---` delimiters
+- [ ] **All**: `description` field is present and meaningful
+- [ ] **All**: File size under 12,000 characters (workflows/rules)
+
+---
+
+## Best Practices
+
+### Writing Effective Descriptions
+
+The `description` field is critical for automatic invocation. Be specific:
+
+**Good:**
+```yaml
+description: Guides deployment to staging environment with pre-flight checks. Use when deploying to staging, testing releases, or preparing for production.
+```
+
+**Bad:**
+```yaml
+description: Deployment stuff
+```
+
+### Formatting Guidelines
+
+- Use bullet points and numbered lists (easier for Cascade to follow)
+- Use markdown headers to organize sections
+- Keep rules concise and specific
+- Avoid generic rules like "write good code" (already built-in)
+
+### XML Tags for Grouping
+
+XML tags can effectively group related rules:
+
+```markdown
+<coding_guidelines>
+- Use early returns when possible
+- Always add documentation for new functions
+- Prefer composition over inheritance
+</coding_guidelines>
+
+<testing_requirements>
+- Write unit tests for all public methods
+- Maintain 80% code coverage
+</testing_requirements>
+```
+
+### Skills vs Rules vs Workflows
+
+| Use Case | Recommended |
+|----------|-------------|
+| Multi-step procedure with supporting files | **Skill** |
+| Repeatable CLI/automation sequence | **Workflow** |
+| Coding style preferences | **Rule** |
+| Project conventions | **Rule** |
+| Deployment procedure | **Skill** or **Workflow** |
+| Code review checklist | **Skill** |
+
+---
+
+## Additional Resources
+
+- **Official Documentation**: [docs.windsurf.com](https://docs.windsurf.com)
+- **Skills Specification**: [agentskills.io](https://agentskills.io/home)
+- **Rule Templates**: [windsurf.com/editor/directory](https://windsurf.com/editor/directory)