docs: modernize Windsurf integration with Rules engine

[juanitourquiza]

Problem

The existing docs/windsurf-setup.md was outdated. It described:

• Manual copy-paste of skills into .windsurfrules (deprecated)
• Pasting content into Global Rules via UI (no automation)
• No mention of activation modes, AGENTS.md, or the modern Rules engine
  Windsurf has evolved significantly. It now supports:
• Global Rules (global_rules.md) — applies to all workspaces
• Workspace Rules (.windsurf/rules/*.md) — with activation modes (always_on, model_decision, glob, manual)
• AGENTS.md — native support in any workspace directory
• Native Skills — multi-step procedures with reference files

Solution

This PR modernizes the Windsurf integration to match the current platform capabilities:

Changes

1. Rewrites docs/windsurf-setup.md completely:
   • Documents the modern Rules engine context system
   • Adds Global Installation section with global_rules.md for intent mapping across all projects
   • Adds Workspace-Local Installation section with .windsurf/rules/*.md and activation modes
   • Documents AGENTS.md integration
   • Includes verification steps and limitations
   • Replaces the deprecated .windsurfrules approach
2. Adds scripts/install-windsurf.sh — automated installer that:
   • Detects OS (macOS, Linux, Windows)
   • Copies skills to ~/.agents/skills/
   • Creates global_rules.md with full intent mapping and lifecycle rules
   • Optionally installs workspace rules (agent-skills.md, test-driven-development.md, spec-driven-development.md, debugging-and-error-recovery.md, code-review-and-quality.md)
   • Optionally creates AGENTS.md template
3. Updates README.md — Windsurf quick-start summary now mentions both global (install-windsurf.sh) and workspace-local options

Verification

Tested locally on macOS:

• Ran bash scripts/install-windsurf.sh
• Confirmed ~/.codeium/windsurf/memories/global_rules.md created
• Confirmed ~/.agents/skills/ populated with 21 skills
• Confirmed workspace rules created in .windsurf/rules/

Why This Matters

This brings the Windsurf integration to parity with the OpenCode and Claude Code integrations:

• Automatic skill selection via intent mapping (no manual /command needed)
• Global availability (no per-project setup required)
• Context-efficient (model_decision only loads skills when relevant)
• Agent-driven workflow (the model decides which skill to apply)

---

Files changed: 3 files (+568 lines, -26 lines)

[federicobartoli]

Substantive PR and the old doc was genuinely outdated. A few concerns worth addressing before merge:

1. Content duplication / drift risk. The global_rules.md content (~70 lines of intent mapping) is duplicated in three places: the heredoc in install-windsurf.sh, the manual-setup walkthrough in the docs, and the underlying skills themselves. CLAUDE.md explicitly calls this out: "Never: Duplicate content between skills — reference other skills instead." As evidence the duplication has already drifted: the hard-coded mapping covers 17 skills but the repo has 21 (idea-refine and using-agent-skills missing). Could the script generate the rules by iterating skills/*/SKILL.md frontmatter instead?

2. cp -R skills/* ~/.agents/skills/ is silently destructive. If a user has anything under ~/.agents/skills/ (the path claims a generic namespace), it gets overwritten with no prompt or backup. Suggest a confirmation prompt and/or a Windsurf-scoped path like ~/.codeium/agent-skills/.

3. Global "always check skills, even 1% chance" is too aggressive at global scope. These rules apply to every Windsurf session for every project. For trivial edits, forcing a full skill check is friction. Worth softening to "if a substantive task matches" or moving the anti-rationalization block to workspace rules where it's opt-in.