From 456e1576ea69ff19ea642e7c9c2593d433760f22 Mon Sep 17 00:00:00 2001 From: AImindcrafter Date: Mon, 10 Aug 2026 13:50:46 +0500 Subject: [PATCH] docs(windsurf): add Changelog Drafter example doc (#485) --- examples/README.md | 2 +- examples/windsurf/README.md | 1 + examples/windsurf/changelog-drafter.md | 82 ++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 examples/windsurf/changelog-drafter.md diff --git a/examples/README.md b/examples/README.md index 516255ed..e95c46ad 100644 --- a/examples/README.md +++ b/examples/README.md @@ -28,7 +28,7 @@ Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilit | CI Sweeper | [grok/ci-sweeper.md](./grok/ci-sweeper.md) | [claude-code/ci-sweeper.md](./claude-code/ci-sweeper.md) | [codex/ci-sweeper.md](./codex/ci-sweeper.md) | [openclaw/ci-sweeper.md](./openclaw/ci-sweeper.md) | [cursor/ci-sweeper.md](./cursor/ci-sweeper.md) | [windsurf/ci-sweeper.md](./windsurf/ci-sweeper.md) | [opencode/ci-sweeper.md](./opencode/ci-sweeper.md) | — | [github-actions/ci-sweeper.yml](./github-actions/ci-sweeper.yml) | | Post-Merge Cleanup | [grok/post-merge-cleanup.md](./grok/post-merge-cleanup.md) | [claude-code/post-merge-cleanup.md](./claude-code/post-merge-cleanup.md) | [codex/post-merge-cleanup.md](./codex/post-merge-cleanup.md) | [openclaw/post-merge-cleanup.md](./openclaw/post-merge-cleanup.md) | [cursor/post-merge-cleanup.md](./cursor/post-merge-cleanup.md) | [windsurf/post-merge-cleanup.md](./windsurf/post-merge-cleanup.md) | [opencode/post-merge-cleanup.md](./opencode/post-merge-cleanup.md) | — | [github-actions/post-merge-cleanup.yml](./github-actions/post-merge-cleanup.yml) | | Dependency Sweeper | [grok/dependency-sweeper.md](./grok/dependency-sweeper.md) | [claude-code/dependency-sweeper.md](./claude-code/dependency-sweeper.md) | [codex/dependency-sweeper.md](./codex/dependency-sweeper.md) | [openclaw/dependency-sweeper.md](./openclaw/dependency-sweeper.md) | [cursor/dependency-sweeper.md](./cursor/dependency-sweeper.md) | [windsurf/dependency-sweeper.md](./windsurf/dependency-sweeper.md) | [opencode/dependency-sweeper.md](./opencode/dependency-sweeper.md) | — | [github-actions/dependency-sweeper.yml](./github-actions/dependency-sweeper.yml) | -| Changelog Drafter | [grok/changelog-drafter.md](./grok/changelog-drafter.md) | [claude-code/changelog-drafter.md](./claude-code/changelog-drafter.md) | [codex/changelog-drafter.md](./codex/changelog-drafter.md) | [openclaw/changelog-drafter.md](./openclaw/changelog-drafter.md) | [cursor/changelog-drafter.md](./cursor/changelog-drafter.md) | — | [opencode/changelog-drafter.md](./opencode/changelog-drafter.md) | — | [github-actions/changelog-drafter.yml](./github-actions/changelog-drafter.yml) | +| Changelog Drafter | [grok/changelog-drafter.md](./grok/changelog-drafter.md) | [claude-code/changelog-drafter.md](./claude-code/changelog-drafter.md) | [codex/changelog-drafter.md](./codex/changelog-drafter.md) | [openclaw/changelog-drafter.md](./openclaw/changelog-drafter.md) | [cursor/changelog-drafter.md](./cursor/changelog-drafter.md) | [windsurf/changelog-drafter.md](./windsurf/changelog-drafter.md) | [opencode/changelog-drafter.md](./opencode/changelog-drafter.md) | — | [github-actions/changelog-drafter.yml](./github-actions/changelog-drafter.yml) | | Issue Triage | [grok/issue-triage.md](./grok/issue-triage.md) | [claude-code/issue-triage.md](./claude-code/issue-triage.md) | [codex/issue-triage.md](./codex/issue-triage.md) | [openclaw/issue-triage.md](./openclaw/issue-triage.md) | [cursor/issue-triage.md](./cursor/issue-triage.md) | [windsurf/issue-triage.md](./windsurf/issue-triage.md) | [opencode/issue-triage.md](./opencode/issue-triage.md) | — | [github-actions/issue-triage.yml](./github-actions/issue-triage.yml) | L2 patterns ship multi-tool skills inside one starter folder — see `starters//`. diff --git a/examples/windsurf/README.md b/examples/windsurf/README.md index 1e3c896e..0fb2161e 100644 --- a/examples/windsurf/README.md +++ b/examples/windsurf/README.md @@ -10,6 +10,7 @@ Copy-pasteable loop patterns for Windsurf, using Cascade Workflows as the manual | Issue Triage | 2h–1d (manual `/issue-triage`; external reminder optional) | Low | [issue-triage.md](issue-triage.md) | | Dependency Sweeper | 6h–1d (manual `/dependency-sweeper`; external reminder optional) | Medium | [dependency-sweeper.md](dependency-sweeper.md) | | Post-Merge Cleanup | 1d–6h (manual `/post-merge-cleanup`; external reminder optional) | Low | [post-merge-cleanup.md](post-merge-cleanup.md) | +| Changelog Drafter | 1d or tag (manual `/changelog-drafter`; external reminder optional) | Low | [changelog-drafter.md](changelog-drafter.md) | No `loop-init --tool windsurf` yet — copy `SKILL.md` + `STATE.md` from any starter (e.g. `starters/minimal-loop`), then follow the example to wire a Cascade Workflow. diff --git a/examples/windsurf/changelog-drafter.md b/examples/windsurf/changelog-drafter.md new file mode 100644 index 00000000..dbba2c4c --- /dev/null +++ b/examples/windsurf/changelog-drafter.md @@ -0,0 +1,82 @@ +# Changelog Drafter — Windsurf (Cascade Workflows) + +This is a practical, copy-pasteable example of a Changelog Drafter loop using Windsurf's Cascade. + +Windsurf has no native `/loop` scheduler or built-in cron. Map the loop to a **Cascade Workflow** (`.windsurf/workflows/changelog-drafter.md`) and invoke it manually with `/changelog-drafter`; if you need an unattended cadence, pair it with an external reminder or trigger (such as GitHub Actions cron, `launchd`, `cron`, or systemd) that prompts a human to run the workflow on schedule (e.g. daily or weekly before releases). + +## Workflow (week one — draft only) + +Create `.windsurf/workflows/changelog-drafter.md`: + +```markdown +# Changelog Drafter + +**Description:** Scan recent merges to main since the last release tag, categorize changes, and draft release notes. Draft only, no auto-publish or tag creation. + +1. Read `changelog-drafter-state.md`, `.windsurf/rules/changelog-scan/SKILL.md`, and `.windsurf/rules/draft-release-notes/SKILL.md`. +2. Inspect merges landed on `main` since the last release tag or last completed scan window. +3. Categorize changes (Features, Fixes, Documentation, Maintenance) citing PR numbers and commit SHAs. Exclude bot-only updates unless security-relevant. +4. Write draft release notes to `RELEASE_NOTES_DRAFT.md`. +5. Update `changelog-drafter-state.md` with the scan window (`..HEAD`), source count, and status `pending human review`. +6. Week one is draft-only (L1): + - do not publish GitHub Releases or Git tags; + - do not modify `CHANGELOG.md` directly; + - do not create or merge pull requests; + - do not post release announcements or notifications. +7. Escalate breaking changes, security items, or ambiguous commit attributions for human wording and review. +``` + +Invoke in Cascade chat with `/changelog-drafter`. + +For an unattended cadence, keep Windsurf as the reviewer/triage surface and use an external scheduler only to remind a human or trigger execution. Review `RELEASE_NOTES_DRAFT.md` and `changelog-drafter-state.md` after every run. See [Safety and human gates](../../docs/safety.md) for permission boundaries and least-privilege guidelines. + +## Human publish gate + +Before anything leaves draft state, a human must: + +1. Verify every drafted item against its merged PR or commit SHA; +2. Confirm the scan window (`..HEAD`) has no gaps or duplicated entries; +3. Review breaking change callouts, security wording, and contributor attribution; +4. Edit and approve `RELEASE_NOTES_DRAFT.md` (or copy into `CHANGELOG.md` / GitHub Release notes); +5. Separately execute or authorize tag creation, release publishing, or announcement posts. + +The workflow never publishes directly, even when the generated draft requires zero edits. + +## Requirements + +- `changelog-drafter-state.md` in the repo root (copied from [`starters/changelog-drafter/changelog-drafter-state.md.example`](../../starters/changelog-drafter/changelog-drafter-state.md.example)) +- The `changelog-scan` skill copied into `.windsurf/rules/changelog-scan/SKILL.md` (from `starters/changelog-drafter/.grok/skills/changelog-scan/SKILL.md` or similar) +- The `draft-release-notes` skill copied into `.windsurf/rules/draft-release-notes/SKILL.md` (from `starters/changelog-drafter/.grok/skills/draft-release-notes/SKILL.md` or similar) +- A `.windsurf/workflows/changelog-drafter.md` workflow like the one above +- Manual `/changelog-drafter` invocation for week one; external scheduler or cron reminder optional after that + +## Example `changelog-drafter-state.md` + +```markdown +# Changelog Drafter State +Last run: 2026-07-23 06:00 UTC +Last release tag: v2.14.0 +Scan window: v2.14.0..abc1234 + +## Pending draft +- File: RELEASE_NOTES_DRAFT.md +- Sources: 8 merged PRs, 1 direct commit +- Breaking changes: 1 (human wording required) +- Security items: 0 +- Status: pending human review + +## Publish gate +- Source verification: pending +- Attribution review: pending +- Tag / GitHub Release / Discussions: denied to agent workflow +``` + +## Notes + +- **Cadence:** Run on a 1d or tag-based cadence (e.g., daily scan or weekly pre-release prompt) to keep draft release notes synchronized with default branch activity. +- **State Schema:** `changelog-drafter-state.md` tracks the exact scan range (`vX.Y.Z..HEAD`), item counts, breaking change flags, and review status across runs. +- **Skills:** Combine `changelog-scan` (commit/PR classification) and `draft-release-notes` (markdown drafting) inside `.windsurf/rules/` for persistent context across Cascade sessions. +- **Human Gate:** Maintain an explicit boundary where tagging, GitHub Release publishing, and CHANGELOG updates remain 100% human-approved. +- See [patterns/changelog-drafter.md](../../patterns/changelog-drafter.md) and [starters/changelog-drafter/](../../starters/changelog-drafter/) for the full pattern spec. + +See the [primitives matrix](../../docs/primitives-matrix.md) for how Windsurf maps to the same six-part loop shape.