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 Post-Merge Cleanup example doc (#484)

AImindcraftera3021a26044a
diff --git a/examples/README.md b/examples/README.md
index 8577999..516255e 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -26,7 +26,7 @@ Start with [primitives-matrix.md](../docs/primitives-matrix.md) to map capabilit
| Daily Triage | [grok/daily-triage.md](./grok/daily-triage.md) | [claude-code/daily-triage.md](./claude-code/daily-triage.md) | [codex/daily-triage.md](./codex/daily-triage.md) | [openclaw/daily-triage.md](./openclaw/daily-triage.md) | [cursor/daily-triage.md](./cursor/daily-triage.md) | [windsurf/daily-triage.md](./windsurf/daily-triage.md) | [opencode/daily-triage.md](./opencode/daily-triage.md) | [hermes/daily-triage.md](./hermes/daily-triage.md) | [github-actions/daily-triage.yml](./github-actions/daily-triage.yml) |
| PR Babysitter | [grok/pr-babysitter.md](./grok/pr-babysitter.md) | [claude-code/pr-babysitter.md](./claude-code/pr-babysitter.md) | [codex/pr-babysitter.md](./codex/pr-babysitter.md) | [openclaw/pr-babysitter.md](./openclaw/pr-babysitter.md) | [cursor/pr-babysitter.md](./cursor/pr-babysitter.md) | [windsurf/pr-babysitter.md](./windsurf/pr-babysitter.md) | [opencode/pr-babysitter.md](./opencode/pr-babysitter.md) | [hermes/pr-babysitter.md](./hermes/pr-babysitter.md) | [github-actions/pr-babysitter.yml](./github-actions/pr-babysitter.yml) |
| 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) | — | [opencode/post-merge-cleanup.md](./opencode/post-merge-cleanup.md) | — | [github-actions/post-merge-cleanup.yml](./github-actions/post-merge-cleanup.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) |
| 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) |
diff --git a/examples/windsurf/README.md b/examples/windsurf/README.md
index dd42ec5..1e3c896 100644
--- a/examples/windsurf/README.md
+++ b/examples/windsurf/README.md
@@ -9,6 +9,7 @@ Copy-pasteable loop patterns for Windsurf, using Cascade Workflows as the manual
| CI Sweeper | 5m–15m (manual `/ci-sweeper`; external reminder optional) | Medium | [ci-sweeper.md](ci-sweeper.md) |
| 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) |
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/post-merge-cleanup.md b/examples/windsurf/post-merge-cleanup.md
new file mode 100644
index 0000000..3da9cf0
--- /dev/null
+++ b/examples/windsurf/post-merge-cleanup.md
@@ -0,0 +1,82 @@
+# Post-Merge Cleanup — Windsurf (Cascade Workflows)
+
+This is a practical, copy-pasteable example of a post-merge cleanup loop using Windsurf's Cascade.
+
+Windsurf has no native `/loop` scheduler or built-in cron. Map the loop to a **Cascade Workflow** (`.windsurf/workflows/post-merge-cleanup.md`) and invoke it manually with `/post-merge-cleanup`; 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 off-peak.
+
+## Workflow (week one — report only)
+
+Create `.windsurf/workflows/post-merge-cleanup.md`:
+
+```markdown
+# Post-Merge Cleanup
+
+**Description:** Scan recent merges to main, identify follow-up technical debt, and update state. Report only, no auto-fix or branch deletion.
+
+1. Read `post-merge-state.md` and `.windsurf/rules/post-merge-scan/SKILL.md`.
+2. Inspect merges landed on `main` over the last 48 hours.
+3. Identify follow-up tasks such as outdated documentation, leftover TODOs, missing tests, or deprecated comments.
+4. Record findings in `post-merge-state.md` under pending cleanup items, including source PR/commit and risk level.
+5. Week one is report-only:
+ - do not modify source code or configuration files;
+ - do not create commits, branches, or pull requests;
+ - do not automatically delete merged branches without human review.
+6. Escalate architectural refactors, breaking changes, or denylist path modifications for human decision.
+```
+
+Invoke in Cascade chat with `/post-merge-cleanup`.
+
+For an unattended cadence, keep Windsurf as the reviewer/triage surface and use an external scheduler only to remind a human or trigger execution off-peak. Review the state file after every run. See [Safety and human gates](../../docs/safety.md) for permission boundaries and least-privilege guidelines.
+
+## Progression
+
+- **Week one — report only (L1).** Append findings to `post-merge-state.md`. Review report-only outputs manually before enabling fix logic. No auto-deletion of branches or automated code edits without human approval.
+- **Add minimal fixes (L2).** Enable automated fixes only for low-risk, single-file documentation or comment updates inside an isolated worktree (`loop-worktree`).
+- **Add verifier split.** Use a separate verifier step (`.windsurf/rules/loop-verifier/SKILL.md`) to validate diffs and tests before presenting fixes for human approval.
+- **Add issue integration.** File tickets for larger architectural cleanup items via GitHub/Linear MCP connectors instead of attempting multi-file code changes.
+
+## Requirements
+
+- `post-merge-state.md` in the repo root (copied from [`starters/post-merge-cleanup/post-merge-state.md.example`](../../starters/post-merge-cleanup/post-merge-state.md.example))
+- The `post-merge-scan` skill copied into `.windsurf/rules/post-merge-scan/SKILL.md` (from `starters/post-merge-cleanup/.grok/skills/post-merge-scan/SKILL.md` or similar)
+- Optional `verifier` skill in `.windsurf/rules/loop-verifier/SKILL.md` (copied from `templates/SKILL.md.verifier`) for L2 fix verification
+- A `.windsurf/workflows/post-merge-cleanup.md` workflow like the one above
+- Manual `/post-merge-cleanup` invocation for week one; external scheduler or off-peak cron reminder optional after that
+
+## Example post-merge-state.md
+
+```markdown
+# Post-Merge Cleanup State — Project X
+
+Last run: 2026-07-06 23:00 UTC
+Status: report-only (week 1)
+
+## Pending Cleanup (from recent merges)
+- [ ] PR #456 merged — update API docs for new user fields
+ Source: commit def4567, line 82 in docs/api.md
+ Risk: low | Effort: small
+- [ ] PR #452 merged — clean up deprecated config warning message
+ Source: commit abc1234, line 12 in config/settings.ts
+ Risk: low | Effort: small
+
+## Completed (last 14d)
+- (none)
+
+## Deferred (human decision)
+- PR #448 merged — database schema refactor deferred; ticket ENG-1005 created
+
+## Denylist paths
+- auth/
+- payments/
+- infra/
+```
+
+## Notes
+
+- **Cadence:** Run off-peak (e.g. 1d–6h cadence, evening/overnight) to avoid colliding with active developer feature branches.
+- **Skill:** Use `.windsurf/rules/post-merge-scan/SKILL.md` for deterministic scanning logic across sessions.
+- **State:** Always read `post-merge-state.md` first to preserve pending tech debt items and avoid duplicate reporting across runs.
+- **Human Gates:** Never delete merged feature branches or push multi-file changes without explicit human sign-off.
+- See [patterns/post-merge-cleanup.md](../../patterns/post-merge-cleanup.md) and [starters/post-merge-cleanup/](../../starters/post-merge-cleanup/) for the full pattern spec.
+
+See the [primitives matrix](../../docs/primitives-matrix.md) for how Windsurf maps to the same six-part loop shape.