@every-env/compound-plugin 0.8.0 → 0.12.0

package/docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md

@@ -0,0 +1,627 @@
+---
+title: Windsurf Global Scope Support
+type: feat
+status: completed
+date: 2026-02-25
+deepened: 2026-02-25
+prior: docs/plans/2026-02-23-feat-add-windsurf-target-provider-plan.md (removed — superseded)
+---
+
+# Windsurf Global Scope Support
+
+## Post-Implementation Revisions (2026-02-26)
+
+After auditing the implementation against `docs/specs/windsurf.md`, two significant changes were made:
+
+1. **Agents → Skills (not Workflows)**: Claude agents map to Windsurf Skills (`skills/{name}/SKILL.md`), not Workflows. Skills are "complex multi-step tasks with supporting resources" — a better conceptual match for specialized expertise/personas. Workflows are "reusable step-by-step procedures" — a better match for Claude Commands (slash commands).
+
+2. **Workflows are flat files**: Command workflows are written to `global_workflows/{name}.md` (global scope) or `workflows/{name}.md` (workspace scope). No subdirectories — the spec requires flat files.
+
+3. **Content transforms updated**: `@agent-name` references are kept as-is (Windsurf skill invocation syntax). `/command` references produce `/{name}` (not `/commands/{name}`). `Task agent(args)` produces `Use the @agent-name skill: args`.
+
+### Final Component Mapping (per spec)
+
+| Claude Code | Windsurf | Output Path | Invocation |
+|---|---|---|---|
+| Agents (`.md`) | Skills | `skills/{name}/SKILL.md` | `@skill-name` or automatic |
+| Commands (`.md`) | Workflows (flat) | `global_workflows/{name}.md` (global) / `workflows/{name}.md` (workspace) | `/{workflow-name}` |
+| Skills (`SKILL.md`) | Skills (pass-through) | `skills/{name}/SKILL.md` | `@skill-name` |
+| MCP servers | `mcp_config.json` | `mcp_config.json` | N/A |
+| Hooks | Skipped with warning | N/A | N/A |
+| CLAUDE.md | Skipped | N/A | N/A |
+
+### Files Changed in Revision
+
+- `src/types/windsurf.ts` — `agentWorkflows` → `agentSkills: WindsurfGeneratedSkill[]`
+- `src/converters/claude-to-windsurf.ts` — `convertAgentToSkill()`, updated content transforms
+- `src/targets/windsurf.ts` — Skills written as `skills/{name}/SKILL.md`, flat workflows
+- Tests updated to match
+
+---
+
+## Enhancement Summary
+
+**Deepened on:** 2026-02-25
+**Research agents used:** architecture-strategist, kieran-typescript-reviewer, security-sentinel, code-simplicity-reviewer, pattern-recognition-specialist
+**External research:** Windsurf MCP docs, Windsurf tutorial docs
+
+### Key Improvements from Deepening
+1. **HTTP/SSE servers should be INCLUDED** — Windsurf supports all 3 transport types (stdio, Streamable HTTP, SSE). Original plan incorrectly skipped them.
+2. **File permissions: use `0o600`** — `mcp_config.json` contains secrets and must not be world-readable. Add secure write support.
+3. **Extract `resolveTargetOutputRoot` to shared utility** — both commands duplicate this; adding scope makes it worse. Extract first.
+4. **Bug fix: missing `result[name] = entry`** — all 5 review agents caught a copy-paste bug in the `buildMcpConfig` sample code.
+5. **`hasPotentialSecrets` to shared utility** — currently in sync.ts, would be duplicated. Extract to `src/utils/secrets.ts`.
+6. **Windsurf `mcp_config.json` is global-only** — per Windsurf docs, no per-project MCP config support. Workspace scope writes it for forward-compatibility but emit a warning.
+7. **Windsurf supports `${env:VAR}` interpolation** — consider writing env var references instead of literal values for secrets.
+
+### New Considerations Discovered
+- Backup files accumulate with secrets and are never cleaned up — cap at 3 backups
+- Workspace `mcp_config.json` could be committed to git — warn about `.gitignore`
+- `WindsurfMcpServerEntry` type needs `serverUrl` field for HTTP/SSE servers
+- Simplicity reviewer recommends handling scope as windsurf-specific in CLI rather than generic `TargetHandler` fields — but brainstorm explicitly chose "generic with windsurf as first adopter". **Decision: keep generic approach** per user's brainstorm decision, with JSDoc documenting the relationship between `defaultScope` and `supportedScopes`.
+
+---
+
+## Overview
+
+Add a generic `--scope global|workspace` flag to the converter CLI with Windsurf as the first adopter. Global scope writes to `~/.codeium/windsurf/`, making workflows, skills, and MCP servers available across all projects. This also upgrades MCP handling from a human-readable setup doc (`mcp-setup.md`) to a proper machine-readable config (`mcp_config.json`), and removes AGENTS.md generation (the plugin's CLAUDE.md contains development-internal instructions, not user-facing content).
+
+## Problem Statement / Motivation
+
+The current Windsurf converter (v0.10.0) writes everything to project-level `.windsurf/`, requiring re-installation per project. Windsurf supports global paths for skills (`~/.codeium/windsurf/skills/`) and MCP config (`~/.codeium/windsurf/mcp_config.json`). Users should install once and get capabilities everywhere.
+
+Additionally, the v0.10.0 MCP output was a markdown setup guide — not an actual integration. Windsurf reads `mcp_config.json` directly, so we should write to that file.
+
+## Breaking Changes from v0.10.0
+
+This is a **minor version bump** (v0.11.0) with intentional breaking changes to the experimental Windsurf target:
+
+1. **Default output location changed** — `--to windsurf` now defaults to global scope (`~/.codeium/windsurf/`). Use `--scope workspace` for the old behavior.
+2. **AGENTS.md no longer generated** — old files are left in place (not deleted).
+3. **`mcp-setup.md` replaced by `mcp_config.json`** — proper machine-readable integration. Old files left in place.
+4. **Env var secrets included with warning** — previously redacted, now included (required for the config file to work).
+5. **`--output` semantics changed** — `--output` now specifies the direct target directory (not a parent where `.windsurf/` is created).
+
+## Proposed Solution
+
+### Phase 0: Extract Shared Utilities (prerequisite)
+
+**Files:** `src/utils/resolve-output.ts` (new), `src/utils/secrets.ts` (new)
+
+#### 0a. Extract `resolveTargetOutputRoot` to shared utility
+
+Both `install.ts` and `convert.ts` have near-identical `resolveTargetOutputRoot` functions that are already diverging (`hasExplicitOutput` exists in install.ts but not convert.ts). Adding scope would make the duplication worse.
+
+- [x] Create `src/utils/resolve-output.ts` with a unified function:
+
+```typescript
+import os from "os"
+import path from "path"
+import type { TargetScope } from "../targets"
+
+export function resolveTargetOutputRoot(options: {
+  targetName: string
+  outputRoot: string
+  codexHome: string
+  piHome: string
+  hasExplicitOutput: boolean
+  scope?: TargetScope
+}): string {
+  const { targetName, outputRoot, codexHome, piHome, hasExplicitOutput, scope } = options
+  if (targetName === "codex") return codexHome
+  if (targetName === "pi") return piHome
+  if (targetName === "droid") return path.join(os.homedir(), ".factory")
+  if (targetName === "cursor") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".cursor")
+  }
+  if (targetName === "gemini") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".gemini")
+  }
+  if (targetName === "copilot") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".github")
+  }
+  if (targetName === "kiro") {
+    const base = hasExplicitOutput ? outputRoot : process.cwd()
+    return path.join(base, ".kiro")
+  }
+  if (targetName === "windsurf") {
+    if (hasExplicitOutput) return outputRoot
+    if (scope === "global") return path.join(os.homedir(), ".codeium", "windsurf")
+    return path.join(process.cwd(), ".windsurf")
+  }
+  return outputRoot
+}
+```
+
+- [x] Update `install.ts` to import and call `resolveTargetOutputRoot` from shared utility
+- [x] Update `convert.ts` to import and call `resolveTargetOutputRoot` from shared utility
+- [x] Add `hasExplicitOutput` tracking to `convert.ts` (currently missing)
+
+### Research Insights (Phase 0)
+
+**Architecture review:** Both commands will call the same function with the same signature. This eliminates the divergence and ensures scope resolution has a single source of truth. The `--also` loop in both commands also uses this function with `handler.defaultScope`.
+
+**Pattern review:** This follows the same extraction pattern as `resolveTargetHome` in `src/utils/resolve-home.ts`.
+
+#### 0b. Extract `hasPotentialSecrets` to shared utility
+
+Currently in `sync.ts:20-31`. The same regex pattern also appears in `claude-to-windsurf.ts:223` as `redactEnvValue`. Extract to avoid a third copy.
+
+- [x] Create `src/utils/secrets.ts`:
+
+```typescript
+const SENSITIVE_PATTERN = /key|token|secret|password|credential|api_key/i
+
+export function hasPotentialSecrets(
+  servers: Record<string, { env?: Record<string, string> }>,
+): boolean {
+  for (const server of Object.values(servers)) {
+    if (server.env) {
+      for (const key of Object.keys(server.env)) {
+        if (SENSITIVE_PATTERN.test(key)) return true
+      }
+    }
+  }
+  return false
+}
+```
+
+- [x] Update `sync.ts` to import from shared utility
+- [x] Use in new windsurf converter
+
+### Phase 1: Types and TargetHandler
+
+**Files:** `src/types/windsurf.ts`, `src/targets/index.ts`
+
+#### 1a. Update WindsurfBundle type
+
+```typescript
+// src/types/windsurf.ts
+export type WindsurfMcpServerEntry = {
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  serverUrl?: string
+  headers?: Record<string, string>
+}
+
+export type WindsurfMcpConfig = {
+  mcpServers: Record<string, WindsurfMcpServerEntry>
+}
+
+export type WindsurfBundle = {
+  agentWorkflows: WindsurfWorkflow[]
+  commandWorkflows: WindsurfWorkflow[]
+  skillDirs: WindsurfSkillDir[]
+  mcpConfig: WindsurfMcpConfig | null
+}
+```
+
+- [x] Remove `agentsMd: string | null`
+- [x] Replace `mcpSetupDoc: string | null` with `mcpConfig: WindsurfMcpConfig | null`
+- [x] Add `WindsurfMcpServerEntry` (supports both stdio and HTTP/SSE) and `WindsurfMcpConfig` types
+
+### Research Insights (Phase 1a)
+
+**Windsurf docs confirm** three transport types: stdio (`command` + `args`), Streamable HTTP (`serverUrl`), and SSE (`serverUrl` or `url`). The `WindsurfMcpServerEntry` type must support all three — making `command` optional and adding `serverUrl` and `headers` fields.
+
+**TypeScript reviewer:** Consider making `WindsurfMcpServerEntry` a discriminated union if strict typing is desired. However, since this mirrors JSON config structure, a flat type with optional fields is pragmatically simpler.
+
+#### 1b. Add TargetScope to TargetHandler
+
+```typescript
+// src/targets/index.ts
+export type TargetScope = "global" | "workspace"
+
+export type TargetHandler<TBundle = unknown> = {
+  name: string
+  implemented: boolean
+  /**
+   * Default scope when --scope is not provided.
+   * Only meaningful when supportedScopes is defined.
+   * Falls back to "workspace" if absent.
+   */
+  defaultScope?: TargetScope
+  /** Valid scope values. If absent, the --scope flag is rejected for this target. */
+  supportedScopes?: TargetScope[]
+  convert: (plugin: ClaudePlugin, options: ClaudeToOpenCodeOptions) => TBundle | null
+  write: (outputRoot: string, bundle: TBundle) => Promise<void>
+}
+```
+
+- [x] Add `TargetScope` type export
+- [x] Add `defaultScope?` and `supportedScopes?` to `TargetHandler` with JSDoc
+- [x] Set windsurf target: `defaultScope: "global"`, `supportedScopes: ["global", "workspace"]`
+- [x] No changes to other targets (they have no scope fields, flag is ignored)
+
+### Research Insights (Phase 1b)
+
+**Simplicity review:** Argued this is premature generalization (only 1 of 8 targets uses scopes). Recommended handling scope as windsurf-specific with `if (targetName !== "windsurf")` guard instead. **Decision: keep generic approach** per brainstorm decision "Generic with windsurf as first adopter", but add JSDoc documenting the invariant.
+
+**TypeScript review:** Suggested a `ScopeConfig` grouped object to prevent `defaultScope` without `supportedScopes`. The JSDoc approach is simpler and sufficient for now.
+
+**Architecture review:** Adding optional fields to `TargetHandler` follows Open/Closed Principle — existing targets are unaffected. Clean extension.
+
+### Phase 2: Converter Changes
+
+**Files:** `src/converters/claude-to-windsurf.ts`
+
+#### 2a. Remove AGENTS.md generation
+
+- [x] Remove `buildAgentsMd()` function
+- [x] Remove `agentsMd` from return value
+
+#### 2b. Replace MCP setup doc with MCP config
+
+- [x] Remove `buildMcpSetupDoc()` function
+- [x] Remove `redactEnvValue()` helper
+- [x] Add `buildMcpConfig()` that returns `WindsurfMcpConfig | null`
+- [x] Include **all** env vars (including secrets) — no redaction
+- [x] Use shared `hasPotentialSecrets()` from `src/utils/secrets.ts`
+- [x] Include **both** stdio and HTTP/SSE servers (Windsurf supports all transport types)
+
+```typescript
+function buildMcpConfig(
+  servers?: Record<string, ClaudeMcpServer>,
+): WindsurfMcpConfig | null {
+  if (!servers || Object.keys(servers).length === 0) return null
+
+  const result: Record<string, WindsurfMcpServerEntry> = {}
+  for (const [name, server] of Object.entries(servers)) {
+    if (server.command) {
+      // stdio transport
+      const entry: WindsurfMcpServerEntry = { command: server.command }
+      if (server.args?.length) entry.args = server.args
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+      result[name] = entry
+    } else if (server.url) {
+      // HTTP/SSE transport
+      const entry: WindsurfMcpServerEntry = { serverUrl: server.url }
+      if (server.headers && Object.keys(server.headers).length > 0) entry.headers = server.headers
+      if (server.env && Object.keys(server.env).length > 0) entry.env = server.env
+      result[name] = entry
+    } else {
+      console.warn(`Warning: MCP server "${name}" has no command or URL. Skipping.`)
+      continue
+    }
+  }
+
+  if (Object.keys(result).length === 0) return null
+
+  // Warn about secrets (don't redact — they're needed for the config to work)
+  if (hasPotentialSecrets(result)) {
+    console.warn(
+      "Warning: MCP servers contain env vars that may include secrets (API keys, tokens).\n" +
+      "   These will be written to mcp_config.json. Review before sharing the config file.",
+    )
+  }
+
+  return { mcpServers: result }
+}
+```
+
+### Research Insights (Phase 2)
+
+**Windsurf docs (critical correction):** Windsurf supports **stdio, Streamable HTTP, and SSE** transports in `mcp_config.json`. HTTP/SSE servers use `serverUrl` (not `url`). The original plan incorrectly planned to skip HTTP/SSE servers. This is now corrected — all transport types are included.
+
+**All 5 review agents flagged:** The original code sample was missing `result[name] = entry` — the entry was built but never stored. Fixed above.
+
+**Security review:** The warning message should enumerate which specific env var names triggered detection. Enhanced version:
+
+```typescript
+if (hasPotentialSecrets(result)) {
+  const flagged = Object.entries(result)
+    .filter(([, s]) => s.env && Object.keys(s.env).some(k => SENSITIVE_PATTERN.test(k)))
+    .map(([name]) => name)
+  console.warn(
+    `Warning: MCP servers contain env vars that may include secrets: ${flagged.join(", ")}.\n` +
+    "   These will be written to mcp_config.json. Review before sharing the config file.",
+  )
+}
+```
+
+**Windsurf env var interpolation:** Windsurf supports `${env:VARIABLE_NAME}` syntax in `mcp_config.json`. Future enhancement: write env var references instead of literal values for secrets. Out of scope for v0.11.0 (requires more research on which fields support interpolation).
+
+### Phase 3: Writer Changes
+
+**Files:** `src/targets/windsurf.ts`, `src/utils/files.ts`
+
+#### 3a. Simplify writer — remove AGENTS.md and double-nesting guard
+
+The writer always writes directly into `outputRoot`. The CLI resolves the correct output root based on scope.
+
+- [x] Remove AGENTS.md writing block (lines 10-17)
+- [x] Remove `resolveWindsurfPaths()` — no longer needed
+- [x] Write workflows, skills, and MCP config directly into `outputRoot`
+
+### Research Insights (Phase 3a)
+
+**Pattern review (dissent):** Every other writer (kiro, copilot, gemini, droid) has a `resolve*Paths()` function with a double-nesting guard. Removing it makes Windsurf the only target where the CLI fully owns nesting. This creates an inconsistency in the `write()` contract.
+
+**Resolution:** Accept the divergence — Windsurf has genuinely different semantics (global vs workspace). Add a JSDoc comment on `TargetHandler.write()` documenting that some writers may apply additional nesting while the Windsurf writer expects the final resolved path. Long-term, other targets could migrate to this pattern in a separate refactor.
+
+#### 3b. Replace MCP setup doc with JSON config merge
+
+Follow Kiro pattern (`src/targets/kiro.ts:68-92`) with security hardening:
+
+- [x] Read existing `mcp_config.json` if present
+- [x] Backup before overwrite (`backupFile()`)
+- [x] Parse existing JSON (warn and replace if corrupted; add `!Array.isArray()` guard)
+- [x] Merge at `mcpServers` key: plugin entries overwrite same-name entries, user entries preserved
+- [x] Preserve all other top-level keys in existing file
+- [x] Write merged result with **restrictive permissions** (`0o600`)
+- [x] Emit warning when writing to workspace scope (Windsurf `mcp_config.json` is global-only per docs)
+
+```typescript
+// MCP config merge with security hardening
+if (bundle.mcpConfig) {
+  const mcpPath = path.join(outputRoot, "mcp_config.json")
+  const backupPath = await backupFile(mcpPath)
+  if (backupPath) {
+    console.log(`Backed up existing mcp_config.json to ${backupPath}`)
+  }
+
+  let existingConfig: Record<string, unknown> = {}
+  if (await pathExists(mcpPath)) {
+    try {
+      const parsed = await readJson<unknown>(mcpPath)
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        existingConfig = parsed as Record<string, unknown>
+      }
+    } catch {
+      console.warn("Warning: existing mcp_config.json could not be parsed and will be replaced.")
+    }
+  }
+
+  const existingServers =
+    existingConfig.mcpServers &&
+    typeof existingConfig.mcpServers === "object" &&
+    !Array.isArray(existingConfig.mcpServers)
+      ? (existingConfig.mcpServers as Record<string, unknown>)
+      : {}
+  const merged = { ...existingConfig, mcpServers: { ...existingServers, ...bundle.mcpConfig.mcpServers } }
+  await writeJsonSecure(mcpPath, merged)  // 0o600 permissions
+}
+```
+
+### Research Insights (Phase 3b)
+
+**Security review (HIGH):** The current `writeJson()` in `src/utils/files.ts` uses default umask (`0o644`) — world-readable. The sync targets all use `{ mode: 0o600 }` for secret-containing files. The Windsurf writer (and Kiro writer) must do the same.
+
+**Implementation:** Add a `writeJsonSecure()` helper or add a `mode` parameter to `writeJson()`:
+
+```typescript
+// src/utils/files.ts
+export async function writeJsonSecure(filePath: string, data: unknown): Promise<void> {
+  const content = JSON.stringify(data, null, 2)
+  await ensureDir(path.dirname(filePath))
+  await fs.writeFile(filePath, content + "\n", { encoding: "utf8", mode: 0o600 })
+}
+```
+
+**Security review (MEDIUM):** Backup files inherit default permissions. Ensure `backupFile()` also sets `0o600` on the backup copy when the source may contain secrets.
+
+**Security review (MEDIUM):** Workspace `mcp_config.json` could be committed to git. After writing to workspace scope, emit a warning:
+
+```
+Warning: .windsurf/mcp_config.json may contain secrets. Ensure it is in .gitignore.
+```
+
+**TypeScript review:** The `readJson<Record<string, unknown>>` assertion is unsafe — a valid JSON array or string passes parsing but fails the type. Added `!Array.isArray()` guard.
+
+**TypeScript review:** The `bundle.mcpConfig` null check is sufficient — when non-null, `mcpServers` is guaranteed to have entries (the converter returns null for empty servers). Simplified from `bundle.mcpConfig && Object.keys(...)`.
+
+**Windsurf docs (important):** `mcp_config.json` is a **global configuration only** — Windsurf has no per-project MCP config support. Writing it to `.windsurf/` in workspace scope may not be discovered by Windsurf. Emit a warning for workspace scope but still write the file for forward-compatibility.
+
+#### 3c. Updated writer structure
+
+```typescript
+export async function writeWindsurfBundle(outputRoot: string, bundle: WindsurfBundle): Promise<void> {
+  await ensureDir(outputRoot)
+
+  // Write agent workflows
+  if (bundle.agentWorkflows.length > 0) {
+    const agentDir = path.join(outputRoot, "workflows", "agents")
+    await ensureDir(agentDir)
+    for (const workflow of bundle.agentWorkflows) {
+      validatePathSafe(workflow.name, "agent workflow")
+      const content = formatFrontmatter({ description: workflow.description }, `# ${workflow.name}\n\n${workflow.body}`)
+      await writeText(path.join(agentDir, `${workflow.name}.md`), content + "\n")
+    }
+  }
+
+  // Write command workflows
+  if (bundle.commandWorkflows.length > 0) {
+    const cmdDir = path.join(outputRoot, "workflows", "commands")
+    await ensureDir(cmdDir)
+    for (const workflow of bundle.commandWorkflows) {
+      validatePathSafe(workflow.name, "command workflow")
+      const content = formatFrontmatter({ description: workflow.description }, `# ${workflow.name}\n\n${workflow.body}`)
+      await writeText(path.join(cmdDir, `${workflow.name}.md`), content + "\n")
+    }
+  }
+
+  // Copy skill directories
+  if (bundle.skillDirs.length > 0) {
+    const skillsDir = path.join(outputRoot, "skills")
+    await ensureDir(skillsDir)
+    for (const skill of bundle.skillDirs) {
+      validatePathSafe(skill.name, "skill directory")
+      const destDir = path.join(skillsDir, skill.name)
+      const resolvedDest = path.resolve(destDir)
+      if (!resolvedDest.startsWith(path.resolve(skillsDir))) {
+        console.warn(`Warning: Skill name "${skill.name}" escapes skills/. Skipping.`)
+        continue
+      }
+      await copyDir(skill.sourceDir, destDir)
+    }
+  }
+
+  // Merge MCP config (see 3b above)
+  if (bundle.mcpConfig) {
+    // ... merge logic from 3b
+  }
+}
+```
+
+### Phase 4: CLI Wiring
+
+**Files:** `src/commands/install.ts`, `src/commands/convert.ts`
+
+#### 4a. Add `--scope` flag to both commands
+
+```typescript
+scope: {
+  type: "string",
+  description: "Scope level: global | workspace (default varies by target)",
+},
+```
+
+- [x] Add `scope` arg to `install.ts`
+- [x] Add `scope` arg to `convert.ts`
+
+#### 4b. Validate scope with type guard
+
+Use a proper type guard instead of unsafe `as TargetScope` cast:
+
+```typescript
+function isTargetScope(value: string): value is TargetScope {
+  return value === "global" || value === "workspace"
+}
+
+const scopeValue = args.scope ? String(args.scope) : undefined
+if (scopeValue !== undefined) {
+  if (!target.supportedScopes) {
+    throw new Error(`Target "${targetName}" does not support the --scope flag.`)
+  }
+  if (!isTargetScope(scopeValue) || !target.supportedScopes.includes(scopeValue)) {
+    throw new Error(`Target "${targetName}" does not support --scope ${scopeValue}. Supported: ${target.supportedScopes.join(", ")}`)
+  }
+}
+const resolvedScope = scopeValue ?? target.defaultScope ?? "workspace"
+```
+
+- [x] Add `isTargetScope` type guard
+- [x] Add scope validation in both commands (single block, not two separate checks)
+
+### Research Insights (Phase 4b)
+
+**TypeScript review:** The original plan cast `scopeValue as TargetScope` before validation — a type lie. Use a proper type guard function to keep the type system honest.
+
+**Simplicity review:** The two-step validation (check supported, then check exists) can be a single block with the type guard approach above.
+
+#### 4c. Update output root resolution
+
+Both commands now use the shared `resolveTargetOutputRoot` from Phase 0a.
+
+- [x] Call shared function with `scope: resolvedScope` for primary target
+- [x] Default scope: `target.defaultScope ?? "workspace"` (only used when target supports scopes)
+
+#### 4d. Handle `--also` targets
+
+`--scope` applies only to the primary `--to` target. Extra `--also` targets use their own `defaultScope`.
+
+- [x] Pass `handler.defaultScope` for `--also` targets (each uses its own default)
+- [x] Update the `--also` loop in both commands to use target-specific scope resolution
+
+### Research Insights (Phase 4d)
+
+**Architecture review:** There is no way for users to specify scope for an `--also` target (e.g., `--also windsurf:workspace`). Accept as a known v0.11.0 limitation. If users need workspace scope for windsurf, they can run two separate commands. Add a code comment indicating where per-target scope overrides would be added in the future.
+
+### Phase 5: Tests
+
+**Files:** `tests/windsurf-converter.test.ts`, `tests/windsurf-writer.test.ts`
+
+#### 5a. Update converter tests
+
+- [x] Remove all AGENTS.md tests (lines 275-303: empty plugin, CLAUDE.md missing)
+- [x] Remove all `mcpSetupDoc` tests (lines 305-366: stdio, HTTP/SSE, redaction, null)
+- [x] Update `fixturePlugin` default — remove `agentsMd` and `mcpSetupDoc` references
+- [x] Add `mcpConfig` tests:
+  - stdio server produces correct JSON structure with `command`, `args`, `env`
+  - HTTP/SSE server produces correct JSON structure with `serverUrl`, `headers`
+  - mixed servers (stdio + HTTP) both included
+  - env vars included (not redacted) — verify actual values present
+  - `hasPotentialSecrets()` emits console.warn for sensitive keys
+  - `hasPotentialSecrets()` does NOT warn when no sensitive keys
+  - no servers produces null mcpConfig
+  - empty bundle has null mcpConfig
+  - server with no command and no URL is skipped with warning
+
+#### 5b. Update writer tests
+
+- [x] Remove AGENTS.md tests (backup test, creation test, double-nesting AGENTS.md parent test)
+- [x] Remove double-nesting guard test (guard removed)
+- [x] Remove `mcp-setup.md` write test
+- [x] Update `emptyBundle` fixture — remove `agentsMd`, `mcpSetupDoc`, add `mcpConfig: null`
+- [x] Add `mcp_config.json` tests:
+  - writes mcp_config.json to outputRoot
+  - merges with existing mcp_config.json (preserves user servers)
+  - backs up existing mcp_config.json before overwrite
+  - handles corrupted existing mcp_config.json (warn and replace)
+  - handles existing mcp_config.json with array (not object) at root
+  - handles existing mcp_config.json with `mcpServers: null`
+  - preserves non-mcpServers keys in existing file
+  - server name collision: plugin entry wins
+  - file permissions are 0o600 (not world-readable)
+- [x] Update full bundle test — writer writes directly into outputRoot (no `.windsurf/` nesting)
+
+#### 5c. Add scope resolution tests
+
+Test the shared `resolveTargetOutputRoot` function:
+
+- [x] Default scope for windsurf is "global" → resolves to `~/.codeium/windsurf/`
+- [x] Explicit `--scope workspace` → resolves to `cwd/.windsurf/`
+- [x] `--output` overrides scope resolution (both global and workspace)
+- [x] Invalid scope value for windsurf → error
+- [x] `--scope` on non-scope target (e.g., opencode) → error
+- [x] `--also windsurf` uses windsurf's default scope ("global")
+- [x] `isTargetScope` type guard correctly identifies valid/invalid values
+
+### Phase 6: Documentation
+
+**Files:** `README.md`, `CHANGELOG.md`
+
+- [x] Update README.md Windsurf section to mention `--scope` flag and global default
+- [x] Add CHANGELOG entry for v0.11.0 with breaking changes documented
+- [x] Document migration path: `--scope workspace` for old behavior
+- [x] Note that Windsurf `mcp_config.json` is global-only (workspace MCP config may not be discovered)
+
+## Acceptance Criteria
+
+- [x] `install compound-engineering --to windsurf` writes to `~/.codeium/windsurf/` by default
+- [x] `install compound-engineering --to windsurf --scope workspace` writes to `cwd/.windsurf/`
+- [x] `--output /custom/path` overrides scope for both commands
+- [x] `--scope` on non-supporting target produces clear error
+- [x] `mcp_config.json` merges with existing file (backup created, user entries preserved)
+- [x] `mcp_config.json` written with `0o600` permissions (not world-readable)
+- [x] No AGENTS.md generated for either scope
+- [x] Env var secrets included in `mcp_config.json` with `console.warn` listing affected servers
+- [x] Both stdio and HTTP/SSE MCP servers included in `mcp_config.json`
+- [x] All existing tests updated, all new tests pass
+- [x] No regressions in other targets
+- [x] `resolveTargetOutputRoot` extracted to shared utility (no duplication)
+
+## Dependencies & Risks
+
+**Risk: Global workflow path is undocumented.** Windsurf may not discover workflows from `~/.codeium/windsurf/workflows/`. Mitigation: documented as a known assumption in the brainstorm. Users can `--scope workspace` if global workflows aren't discovered.
+
+**Risk: Breaking changes for existing v0.10.0 users.** Mitigation: document migration path clearly. `--scope workspace` restores previous behavior. Target is experimental with a small user base.
+
+**Risk: Workspace `mcp_config.json` not read by Windsurf.** Per Windsurf docs, `mcp_config.json` is global-only configuration. Workspace scope writes the file for forward-compatibility but emits a warning. The primary use case is global scope anyway.
+
+**Risk: Secrets in `mcp_config.json` committed to git.** Mitigation: `0o600` file permissions, console.warn about sensitive env vars, warning about `.gitignore` for workspace scope.
+
+## References & Research
+
+- Spec: `docs/specs/windsurf.md` (authoritative reference for component mapping)
+- Kiro MCP merge pattern: [src/targets/kiro.ts:68-92](../../src/targets/kiro.ts)
+- Sync secrets warning: [src/commands/sync.ts:20-28](../../src/commands/sync.ts)
+- Windsurf MCP docs: https://docs.windsurf.com/windsurf/cascade/mcp
+- Windsurf Skills global path: https://docs.windsurf.com/windsurf/cascade/skills
+- Windsurf MCP tutorial: https://windsurf.com/university/tutorials/configuring-first-mcp-server
+- Adding converter targets (learning): [docs/solutions/adding-converter-target-providers.md](../solutions/adding-converter-target-providers.md)
+- Plugin versioning (learning): [docs/solutions/plugin-versioning-requirements.md](../solutions/plugin-versioning-requirements.md)