empty

* Clarify release automation proposal

* chore(release): phase 1 – wire up changesets action (dry-run publish) and GitHub release drafting

* ci(release): phase 1 – add NODE_AUTH_TOKEN alias and registry/auth config for npm (dry-run)

.changeset/add-windsurf-workflows.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": minor
+---
+
+Add Windsurf support.

.github/workflows/release-prepare.yml

@@ -8,8 +8,13 @@ permissions:
   contents: write
   pull-requests: write
 
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   prepare:
+    if: github.repository == 'Fission-AI/OpenSpec'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -24,14 +29,20 @@ jobs:
         with:
           node-version: '20'
           cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@fission-ai'
+          always-auth: true
 
       - run: pnpm install --frozen-lockfile
 
-      # Opens/updates the Version Packages PR; no publishing here
+      # Opens/updates the Version Packages PR; publishes when the Version PR merges
       - name: Create/Update Version PR
         uses: changesets/action@v1
         with:
           title: 'chore(release): version packages'
+          createGithubReleases: true
+          publish: pnpm run release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release-publish.yml

@@ -1,72 +0,0 @@
-name: Publish to npm
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch: {}
-
-permissions:
-  contents: read
-  id-token: write
-
-concurrency:
-  group: publish-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    env:
-      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-          scope: '@fission-ai'
-          always-auth: true
-
-      - run: pnpm install --frozen-lockfile
-      
-      - name: Build project
-        run: pnpm run build
-
-      - name: Ensure running from a tag
-        run: |
-          if [[ "$GITHUB_REF" != refs/tags/* ]]; then
-            echo "This workflow must run from a tag (got: $GITHUB_REF)";
-            exit 1;
-          fi
-
-      - name: Verify release tag matches package.json
-        run: |
-          TAG="${GITHUB_REF_NAME#v}"
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          if [ "$TAG" != "$PKG_VERSION" ]; then
-            echo "Tag v$TAG does not match package.json $PKG_VERSION"; exit 1
-          fi
-
-      - name: Debug npm auth and context
-        run: |
-          test -n "$NODE_AUTH_TOKEN" || (echo "NODE_AUTH_TOKEN is missing" && exit 1)
-          echo "NODE_AUTH_TOKEN present"
-          npm --version
-          pnpm --version
-          node --version
-          npm config get registry
-          npm whoami
-          npm ping
-
-      - run: pnpm test
-
-      - name: Publish
-        run: pnpm publish --access public --provenance --no-git-checks

README.md

@@ -85,6 +85,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
+| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
 
 Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
 

openspec/changes/update-release-automation/proposal.md

@@ -0,0 +1,49 @@
+## Why
+Today’s process requires maintainers to merge the Changesets PR, cut a tag, and draft the GitHub release by hand. npm publish then runs from our existing workflow after the GitHub release is published. The human-in-the-loop steps (versioning, tagging, release notes) slow us down and risk drift between npm, tags, and changelog.
+
+## What Changes
+- Use the single `changesets/action` on pushes to `main` to either open/update the version PR or, when the release PR is merged, run our publish command automatically using repository secrets.
+- Add a `release` script that builds and runs `changeset publish` so the action handles version bumps, changelog commits, npm publish, and GitHub releases end-to-end.
+- Enable `createGithubReleases: true` so GitHub releases are created from the changeset data right after publishing.
+- Document the automated flow, required secrets, guardrails, and recovery steps (rollback, hotfixes).
+
+## Two-Phase Rollout (Two PRs)
+1) Phase 1 — Dry run (no publish)
+   - Update the existing `release-prepare.yml` to wire up `changesets/action` with `createGithubReleases: true` and a no-op `publish` command (e.g., `echo 'dry run'`).
+   - Keep `.github/workflows/release-publish.yml` intact. This avoids any publish path changes while we verify that the version PR behavior and permissions are correct.
+   - Add a repository guard (`if: github.repository == 'Fission-AI/OpenSpec'`) and a concurrency group for safety.
+
+2) Phase 2 — Enable publish and consolidate
+   - Add `"release": "pnpm run build && pnpm exec changeset publish"` to `package.json`.
+   - Change `release-prepare.yml` to use `with: publish: pnpm run release` and `env: NPM_TOKEN: \\${{ secrets.NPM_TOKEN }}` plus the default `GITHUB_TOKEN`.
+   - Remove `.github/workflows/release-publish.yml` to avoid double-publish. Publishing now happens when the version PR is merged.
+
+## Guardrails
+- Concurrency: `concurrency: { group: release-\\${{ github.ref }}, cancel-in-progress: false }` on the workflow to serialize releases.
+- Repository/branch guard: run publish logic only on upstream `main` (`if: github.repository == 'Fission-AI/OpenSpec' && github.ref == 'refs/heads/main'`).
+- Permissions: ensure `contents: write` and `pull-requests: write` for opening/updating the version PR; `packages: read` optional.
+
+## Rollback and Hotfixes
+- Rollback: revert the release PR merge (which reverts version bumps/changelog); if a tag or GitHub release was created, delete the tag and release; deprecate the npm version if necessary (`npm deprecate @fission-ai/openspec@x.y.z 'reason'`).
+- Hotfix (urgent, no pending changesets): create a changeset for the fix and merge the release PR; in emergencies, run a manual bump/publish but reconcile with Changesets by adding a follow-up changeset to align versions.
+
+## Required Secrets
+- `NPM_TOKEN` with publish rights for the `@fission-ai` scope.
+- Default `GITHUB_TOKEN` (provided by GitHub) for opening/updating the version PR and creating GitHub releases.
+
+## How the Maintainer Flow Changes
+| Step | Current process | Future process |
+| --- | --- | --- |
+| Prepare release | Merge changeset PR, then manually draft release notes and tags | Merge release PR; action updates versions and handles changelog automatically |
+| Publish npm package | Happens automatically after GitHub release | Happens automatically via `changeset publish` invoked by the action |
+| GitHub release | Draft manually and sync with changelog | Action creates GitHub releases from changeset data |
+| Docs/process | Follow manual tagging/release steps | Docs describe automated flow + recovery and hotfix paths |
+
+## Impact
+- Automation: reuse `.github/workflows/release-prepare.yml` (phase 1: dry-run, phase 2: publish) and remove `.github/workflows/release-publish.yml` in phase 2.
+- Package metadata: add `release` script to `package.json`.
+- Docs: update README or `/docs` to show the automated flow, secrets, guardrails, and recovery steps.
+
+## Acceptance Criteria
+- Phase 1: merges to `main` open/update a version PR; on merge, the action’s `publish` step is a no-op; no npm publish occurs; logs confirm intended behavior; GitHub releases creation is wired but inert due to no publish.
+- Phase 2: merges to `main` run `pnpm run release` from the action; npm package publishes successfully; GitHub release is created automatically; `.github/workflows/release-publish.yml` is removed; no duplicate publishes occur.

openspec/changes/update-release-automation/tasks.md

@@ -0,0 +1,12 @@
+## 1. Release workflow automation
+- [ ] 1.1 Add a `.github/workflows/release.yml` that runs on pushes to `main`, sets up pnpm + Node 20, installs dependencies, and invokes `changesets/action@v1` with `publish: pnpm run release`.
+- [ ] 1.2 Configure the action with `createGithubReleases: true` and document required secrets (`NPM_TOKEN`, default `GITHUB_TOKEN`) plus recommended concurrency safeguards.
+- [ ] 1.3 Validate the workflow using `act` or a dry-run push to confirm the action opens release PRs when changesets exist and publishes when the release PR merge lands.
+
+## 2. Package release script
+- [ ] 2.1 Add a `release` script to `package.json` that builds the project and runs `changeset publish` using pnpm.
+- [ ] 2.2 Ensure the script respects the existing `prepare`/`prepublishOnly` hooks to avoid duplicate builds and update documentation or scripts if adjustments are needed.
+
+## 3. Documentation and recovery steps
+- [ ] 3.1 Update maintainer docs (e.g., README or `/docs`) with the end-to-end automated release flow, explicitly removing the manual tag/release steps that are no longer required and explaining how changesets drive the release PR.
+- [ ] 3.2 Document fallback steps for failed publishes (rerun workflow, manual publish) and the hotfix path when a release must be cut without pending changesets.

package.json

@@ -46,6 +46,7 @@
     "test:coverage": "vitest --coverage",
     "prepare": "pnpm run build",
     "prepublishOnly": "pnpm run build",
+    "release": "pnpm run build && pnpm exec changeset publish",
     "changeset": "changeset"
   },
   "engines": {

src/core/config.ts

@@ -21,5 +21,6 @@ export const AI_TOOLS: AIToolOption[] = [
   { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor' },
   { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode' },
   { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code' },
+  { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf' },
   { name: 'AGENTS.md (works with Codex, Amp, VS Code, GitHub Copilot, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
 ];

src/core/configurators/slash/registry.ts

@@ -1,6 +1,7 @@
 import { SlashCommandConfigurator } from './base.js';
 import { ClaudeSlashCommandConfigurator } from './claude.js';
 import { CursorSlashCommandConfigurator } from './cursor.js';
+import { WindsurfSlashCommandConfigurator } from './windsurf.js';
 import { KiloCodeSlashCommandConfigurator } from './kilocode.js';
 import { OpenCodeSlashCommandConfigurator } from './opencode.js';
 
@@ -10,11 +11,13 @@ export class SlashCommandRegistry {
   static {
     const claude = new ClaudeSlashCommandConfigurator();
     const cursor = new CursorSlashCommandConfigurator();
+    const windsurf = new WindsurfSlashCommandConfigurator();
     const kilocode = new KiloCodeSlashCommandConfigurator();
     const opencode = new OpenCodeSlashCommandConfigurator();
 
     this.configurators.set(claude.toolId, claude);
     this.configurators.set(cursor.toolId, cursor);
+    this.configurators.set(windsurf.toolId, windsurf);
     this.configurators.set(kilocode.toolId, kilocode);
     this.configurators.set(opencode.toolId, opencode);
   }

src/core/configurators/slash/windsurf.ts

@@ -0,0 +1,27 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+
+const FILE_PATHS: Record<SlashCommandId, string> = {
+  proposal: '.windsurf/workflows/openspec-proposal.md',
+  apply: '.windsurf/workflows/openspec-apply.md',
+  archive: '.windsurf/workflows/openspec-archive.md'
+};
+
+export class WindsurfSlashCommandConfigurator extends SlashCommandConfigurator {
+  readonly toolId = 'windsurf';
+  readonly isAvailable = true;
+
+  protected getRelativePath(id: SlashCommandId): string {
+    return FILE_PATHS[id];
+  }
+
+  protected getFrontmatter(id: SlashCommandId): string | undefined {
+    const descriptions: Record<SlashCommandId, string> = {
+      proposal: 'Scaffold a new OpenSpec change and validate strictly.',
+      apply: 'Implement an approved OpenSpec change and keep tasks in sync.',
+      archive: 'Archive a deployed OpenSpec change and update specs.'
+    };
+    const description = descriptions[id];
+    return `---\ndescription: ${description}\nauto_execution_mode: 3\n---`;
+  }
+}

test/core/init.test.ts

@@ -129,6 +129,50 @@ describe('InitCommand', () => {
       expect(updatedContent).toContain('Custom instructions here');
     });
 
+    it('should create Windsurf workflows when Windsurf is selected', async () => {
+      queueSelections('windsurf', DONE);
+
+      await initCommand.execute(testDir);
+
+      const wsProposal = path.join(
+        testDir,
+        '.windsurf/workflows/openspec-proposal.md'
+      );
+      const wsApply = path.join(
+        testDir,
+        '.windsurf/workflows/openspec-apply.md'
+      );
+      const wsArchive = path.join(
+        testDir,
+        '.windsurf/workflows/openspec-archive.md'
+      );
+
+      expect(await fileExists(wsProposal)).toBe(true);
+      expect(await fileExists(wsApply)).toBe(true);
+      expect(await fileExists(wsArchive)).toBe(true);
+
+      const proposalContent = await fs.readFile(wsProposal, 'utf-8');
+      expect(proposalContent).toContain('---');
+      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+      expect(proposalContent).toContain('auto_execution_mode: 3');
+      expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
+      expect(proposalContent).toContain('**Guardrails**');
+
+      const applyContent = await fs.readFile(wsApply, 'utf-8');
+      expect(applyContent).toContain('---');
+      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('auto_execution_mode: 3');
+      expect(applyContent).toContain('<!-- OPENSPEC:START -->');
+      expect(applyContent).toContain('Work through tasks sequentially');
+
+      const archiveContent = await fs.readFile(wsArchive, 'utf-8');
+      expect(archiveContent).toContain('---');
+      expect(archiveContent).toContain('description: Archive a deployed OpenSpec change and update specs.');
+      expect(archiveContent).toContain('auto_execution_mode: 3');
+      expect(archiveContent).toContain('<!-- OPENSPEC:START -->');
+      expect(archiveContent).toContain('Run `openspec archive <id> --yes`');
+    });
+
     it('should always create AGENTS.md in project root', async () => {
       queueSelections(DONE);
 
@@ -399,6 +443,18 @@ describe('InitCommand', () => {
       const preselected = secondRunArgs.initialSelected ?? [];
       expect(preselected).toContain('kilocode');
     });
+
+    it('should mark Windsurf as already configured during extend mode', async () => {
+      queueSelections('windsurf', DONE, 'windsurf', DONE);
+      await initCommand.execute(testDir);
+      await initCommand.execute(testDir);
+
+      const secondRunArgs = mockPrompt.mock.calls[1][0];
+      const wsChoice = secondRunArgs.choices.find(
+        (choice: any) => choice.value === 'windsurf'
+      );
+      expect(wsChoice.configured).toBe(true);
+    });
   });
 
   describe('error handling', () => {

test/core/update.test.ts

@@ -220,6 +220,81 @@ Old body
     consoleSpy.mockRestore();
   });
 
+  it('should refresh existing Windsurf workflows', async () => {
+    const wsPath = path.join(
+      testDir,
+      '.windsurf/workflows/openspec-apply.md'
+    );
+    await fs.mkdir(path.dirname(wsPath), { recursive: true });
+    const initialContent = `## OpenSpec: Apply (Windsurf)
+Intro
+<!-- OPENSPEC:START -->
+Old body
+<!-- OPENSPEC:END -->`;
+    await fs.writeFile(wsPath, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+
+    await updateCommand.execute(testDir);
+
+    const updated = await fs.readFile(wsPath, 'utf-8');
+    expect(updated).toContain('Work through tasks sequentially');
+    expect(updated).not.toContain('Old body');
+    expect(updated).toContain('## OpenSpec: Apply (Windsurf)');
+
+    const [logMessage] = consoleSpy.mock.calls[0];
+    expect(logMessage).toContain(
+      'Updated slash commands: .windsurf/workflows/openspec-apply.md'
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('should preserve Windsurf content outside markers during update', async () => {
+    const wsPath = path.join(
+      testDir,
+      '.windsurf/workflows/openspec-proposal.md'
+    );
+    await fs.mkdir(path.dirname(wsPath), { recursive: true });
+    const initialContent = `## Custom Intro Title\nSome intro text\n<!-- OPENSPEC:START -->\nOld body\n<!-- OPENSPEC:END -->\n\nFooter stays`;
+    await fs.writeFile(wsPath, initialContent);
+
+    await updateCommand.execute(testDir);
+
+    const updated = await fs.readFile(wsPath, 'utf-8');
+    expect(updated).toContain('## Custom Intro Title');
+    expect(updated).toContain('Footer stays');
+    expect(updated).not.toContain('Old body');
+    expect(updated).toContain('Validate with `openspec validate <id> --strict`');
+  });
+
+  it('should not create missing Windsurf workflows on update', async () => {
+    const wsApply = path.join(
+      testDir,
+      '.windsurf/workflows/openspec-apply.md'
+    );
+    // Only create apply; leave proposal and archive missing
+    await fs.mkdir(path.dirname(wsApply), { recursive: true });
+    await fs.writeFile(
+      wsApply,
+      '<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->'
+    );
+
+    await updateCommand.execute(testDir);
+
+    const wsProposal = path.join(
+      testDir,
+      '.windsurf/workflows/openspec-proposal.md'
+    );
+    const wsArchive = path.join(
+      testDir,
+      '.windsurf/workflows/openspec-archive.md'
+    );
+
+    // Confirm they weren't created by update
+    await expect(FileSystemUtils.fileExists(wsProposal)).resolves.toBe(false);
+    await expect(FileSystemUtils.fileExists(wsArchive)).resolves.toBe(false);
+  });
+
   it('should handle no AI tool files present', async () => {
     // Execute update command with no AI tool files
     const consoleSpy = vi.spyOn(console, 'log');