john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: update spec and plan to reflect global_workflows/ directory

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Ryan Burnham
2026-02-26 20:35:09 +08:00
parent e081e32a30
commit 1107e3dd31
5 changed files with 9 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@@ -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.

2
README.md
View File

@@ -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.

4
docs/plans/2026-02-25-feat-windsurf-global-scope-support-plan.md
View File

@@ -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 |

8
docs/specs/windsurf.md
View File

@@ -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 |

2
plugins/compound-engineering/CHANGELOG.md
View File

@@ -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`.