Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

docs(windsurf): add Changelog Drafter example doc (#485)

AImindcrafter456e1576ea69
diff --git a/examples/README.md b/examples/README.md
index 516255e..e95c46a 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/<pattern>/`.
diff --git a/examples/windsurf/README.md b/examples/windsurf/README.md
index 1e3c896..0fb2161 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 0000000..dbba2c4
--- /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 (`<last-tag>..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 (`<last-tag>..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.