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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
docs(windsurf): add Changelog Drafter example doc (#485)
AImindcrafter456e1576ea69
diff --git a/examples/README.md b/examples/README.mdindex 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.mdindex 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.mdnew file mode 100644index 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.