From 1107e3dd3113417c4fc31f32d32cbeb6dcefe4b0 Mon Sep 17 00:00:00 2001 From: Ryan Burnham Date: Thu, 26 Feb 2026 20:35:09 +0800 Subject: [PATCH] docs: update spec and plan to reflect global_workflows/ directory Updated docs/specs/windsurf.md and the plan to accurately document that global scope workflows go in global_workflows/ while workspace scope workflows go in workflows/. Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 2 +- README.md | 2 +- .../2026-02-25-feat-windsurf-global-scope-support-plan.md | 4 ++-- docs/specs/windsurf.md | 8 ++++---- plugins/compound-engineering/CHANGELOG.md | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5572769..fc2468b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **Windsurf target** — `--to windsurf` converts plugins to Windsurf format. Claude agents become Windsurf skills (`skills/{name}/SKILL.md`), commands become flat workflows (`workflows/{name}.md`), and pass-through skills copy unchanged. MCP servers write to `mcp_config.json` (machine-readable, merged with existing config). +- **Windsurf target** — `--to windsurf` converts plugins to Windsurf format. Claude agents become Windsurf skills (`skills/{name}/SKILL.md`), commands become flat workflows (`global_workflows/{name}.md` for global scope, `workflows/{name}.md` for workspace), and pass-through skills copy unchanged. MCP servers write to `mcp_config.json` (machine-readable, merged with existing config). - **Global scope support** — New `--scope global|workspace` flag (generic, Windsurf as first adopter). `--to windsurf` defaults to global scope (`~/.codeium/windsurf/`), making installed skills, workflows, and MCP servers available across all projects. Use `--scope workspace` for project-level `.windsurf/` output. - **`mcp_config.json` integration** — Windsurf converter writes proper machine-readable MCP config supporting stdio, Streamable HTTP, and SSE transports. Merges with existing config (user entries preserved, plugin entries take precedence). Written with `0o600` permissions. - **Shared utilities** — Extracted `resolveTargetOutputRoot` to `src/utils/resolve-output.ts` and `hasPotentialSecrets` to `src/utils/secrets.ts` to eliminate duplication. diff --git a/README.md b/README.md index 0038ad7..57df279 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ Pi output is written to `~/.pi/agent/` by default with prompts, skills, extensio Gemini output is written to `.gemini/` with skills (from agents), commands (`.toml`), and `settings.json` (MCP servers). Namespaced commands create directory structure (`workflows:plan` → `commands/workflows/plan.toml`). Skills use the identical SKILL.md standard and pass through unchanged. Copilot output is written to `.github/` with agents (`.agent.md`), skills (`SKILL.md`), and `copilot-mcp-config.json`. Agents get Copilot frontmatter (`description`, `tools: ["*"]`, `infer: true`), commands are converted to agent skills, and MCP server env vars are prefixed with `COPILOT_MCP_`. Kiro output is written to `.kiro/` with custom agents (`.json` configs + prompt `.md` files), skills (from commands), pass-through skills, steering files (from CLAUDE.md), and `mcp.json`. Agents get `includeMcpJson: true` for MCP server access. Only stdio MCP servers are supported (HTTP servers are skipped with a warning). -Windsurf output defaults to global scope (`~/.codeium/windsurf/`). Claude agents become Windsurf skills (`skills/{name}/SKILL.md`), commands become flat workflows (`workflows/{name}.md`), and pass-through skills copy unchanged. MCP servers write to `mcp_config.json` (machine-readable, merged with existing config). Use `--scope workspace` for project-level output (`.windsurf/`). Env vars including secrets are included in `mcp_config.json` with a console warning for sensitive keys. The `--scope` flag is generic — Windsurf is the first target to support it. +Windsurf output defaults to global scope (`~/.codeium/windsurf/`). Claude agents become Windsurf skills (`skills/{name}/SKILL.md`), commands become flat workflows (`global_workflows/{name}.md` for global scope, `workflows/{name}.md` for workspace), and pass-through skills copy unchanged. MCP servers write to `mcp_config.json` (machine-readable, merged with existing config). Use `--scope workspace` for project-level output (`.windsurf/`). Env vars including secrets are included in `mcp_config.json` with a console warning for sensitive keys. The `--scope` flag is generic — Windsurf is the first target to support it. All provider targets are experimental and may change as the formats evolve. diff --git a/docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md b/docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md index 162ecb2..d90eb6a 100644 --- a/docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md +++ b/docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md @@ -15,7 +15,7 @@ After auditing the implementation against `docs/specs/windsurf.md`, two signific 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 `workflows/{name}.md` (no subdirectories). The spec requires flat files, not `workflows/agents/` or `workflows/commands/` subdirectories. +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`. @@ -24,7 +24,7 @@ After auditing the implementation against `docs/specs/windsurf.md`, two signific | Claude Code | Windsurf | Output Path | Invocation | |---|---|---|---| | Agents (`.md`) | Skills | `skills/{name}/SKILL.md` | `@skill-name` or automatic | -| Commands (`.md`) | Workflows (flat) | `workflows/{name}.md` | `/{workflow-name}` | +| 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 | diff --git a/docs/specs/windsurf.md b/docs/specs/windsurf.md index 129d4d5..a895b52 100644 --- a/docs/specs/windsurf.md +++ b/docs/specs/windsurf.md @@ -53,7 +53,7 @@ All three support both **workspace-level** (project-specific) and **global** (us ├── skills/ # Global skills (directories) │ └── {skill-name}/ │ └── SKILL.md -├── workflows/ # Global workflows (flat .md files) +├── global_workflows/ # Global workflows (flat .md files) │ └── {workflow-name}.md ├── rules/ # Global rules (flat .md files) │ └── {rule-name}.md @@ -167,7 +167,7 @@ Workflows define step-by-step procedures invoked via slash commands. They guide | Scope | Location | |-------|----------| -| **Global** | `~/.codeium/windsurf/workflows/{workflow-name}.md` | +| **Global** | `~/.codeium/windsurf/global_workflows/{workflow-name}.md` | | **Workspace** | `.windsurf/workflows/{workflow-name}.md` | ### File Format @@ -208,7 +208,7 @@ Step-by-step instructions in markdown. ### Example: Complete Workflow -**File**: `~/.codeium/windsurf/workflows/address-pr-comments.md` +**File**: `~/.codeium/windsurf/global_workflows/address-pr-comments.md` ```markdown --- @@ -366,7 +366,7 @@ When items with the same name exist at multiple levels: | Type | Path Pattern | Format | Key Fields | |------|--------------|--------|------------| | **Skill** | `skills/{name}/SKILL.md` | YAML frontmatter + markdown | `name`, `description` | -| **Workflow** | `workflows/{name}.md` | YAML frontmatter + markdown | `description` | +| **Workflow** | `global_workflows/{name}.md` (global) or `workflows/{name}.md` (workspace) | YAML frontmatter + markdown | `description` | | **Rule** | `rules/{name}.md` | YAML frontmatter + markdown | `description`, `trigger`, `globs` | | **Global Rules** | `memories/global_rules.md` | Plain text/markdown | None | diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index dcd83a5..90229ed 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- **Windsurf target provider** — `--to windsurf` converts plugins to Windsurf format per the [Windsurf spec](docs/specs/windsurf.md). Claude agents become Windsurf skills (`skills/{name}/SKILL.md`), commands become flat workflows (`workflows/{name}.md`), pass-through skills copy unchanged, and MCP servers write to `mcp_config.json`. +- **Windsurf target provider** — `--to windsurf` converts plugins to Windsurf format per the [Windsurf spec](docs/specs/windsurf.md). Claude agents become Windsurf skills (`skills/{name}/SKILL.md`), commands become flat workflows (`global_workflows/{name}.md` for global scope, `workflows/{name}.md` for workspace), pass-through skills copy unchanged, and MCP servers write to `mcp_config.json`. - **Global scope support** — New `--scope global|workspace` flag for the converter CLI (generic, Windsurf as first adopter). `--to windsurf` defaults to global scope (`~/.codeium/windsurf/`), making installed skills, workflows, and MCP servers available across all projects. Use `--scope workspace` for project-level `.windsurf/` output. - **`mcp_config.json` integration** — Machine-readable MCP config supporting stdio, Streamable HTTP, and SSE transports. Merges with existing config (user entries preserved, plugin entries take precedence). Written with `0o600` permissions for security. - **Shared utilities** — Extracted `resolveTargetOutputRoot` to `src/utils/resolve-output.ts` and `hasPotentialSecrets` to `src/utils/secrets.ts`.