diff --git a/cursor-team-kit/README.md b/cursor-team-kit/README.md index f25739dc..c5a21536 100644 --- a/cursor-team-kit/README.md +++ b/cursor-team-kit/README.md @@ -46,6 +46,8 @@ Internal-style workflows for CI, code review, shipping, and test reliability. Th |:-----|:------------| | `typescript-exhaustive-switch` | Require exhaustive switch handling for unions/enums | | `no-inline-imports` | Keep imports at module top-level for readability and consistency | +| `worktree-cleanup` | Remove sibling git worktrees when their branch merges so parallel-work directories do not accumulate | +| `one-shot-script-cleanup` | Delete `_tmp-*` helper scripts and temp payload files when the task that created them ships | ## License diff --git a/cursor-team-kit/rules/one-shot-script-cleanup.mdc b/cursor-team-kit/rules/one-shot-script-cleanup.mdc new file mode 100644 index 00000000..615295bb --- /dev/null +++ b/cursor-team-kit/rules/one-shot-script-cleanup.mdc @@ -0,0 +1,72 @@ +--- +description: Delete one-shot helper scripts and temp payload files when the task that created them ships +alwaysApply: true +--- + +# One-shot script cleanup + +Agent sessions often generate throwaway helper scripts and temp payload +files to drive a single task -- claim a work item, extract one field +from an API response, feed a CLI a file it insists on reading from +disk. Left behind, they bury every future `git status` under an +untracked `_tmp-*` haystack. The same session that creates a one-shot +artifact is responsible for deleting it. + +## What counts + +- Temp helper scripts written to run once: `_tmp-*.ps1`, `_tmp-*.sh`, + `_tmp-*.py`, `_tmp-*.js`, etc. +- Temp JSON / text payloads fed to a single API or CLI call: + `_tmp--wi.json`, `_tmp--desc.txt`, + `_tmp--ac.txt`. +- Extract or parse scripts written to pull one value out of an API + response and then never used again. +- PR-body markdown drafts written to disk only because a CLI wants a + file (`_tmp-*-pr-body.md`, `PR_BODY.md` used only as `--body-file`). + +## What does not count + +Never auto-delete these -- they need review, not silent removal: + +- Real project source, migrations, or tests. +- Scripts under a documented, git-tracked `scripts/` folder that has a + README explaining what stays. +- Anything already tracked by git. If a real file has drifted, discuss + it, do not silently `rm`. + +## Naming and layout + +Prefix single-use artifacts with `_tmp-` (or match the repo's existing +scratch prefix if it already has one). When a task will produce more +than a couple of files, prefer a per-task subfolder such as +`scripts/_scratch//` and delete the whole subfolder at the end +of the task. + +## Delete when done + +When the task the artifact was written for ships -- PR merged, work +item closed, question answered -- the same session removes the +artifact. Do not leave `_tmp-*` files behind for the next session to +puzzle over. + +## Session-end sweep + +Before ending a session, check for untracked `_tmp-*` files the current +session created and delete them. Do not touch `_tmp-*` files another +running session might still be using: if you did not create it and you +are not sure, leave it alone and mention it in your final summary. + +## Never + +- Delete anything that looks like a secret: `.env*`, `.pat*`, `*.key`, + `*.pem`, VAPID / JWT / token blobs. If a secret leaked to disk, tell + the user; do not silently `rm`. +- Run `git clean -fd` (or equivalent broad sweeps) in a shared + workspace without explicit user approval. +- Delete files under `.git/`, `node_modules/`, `venv/`, `.next/`, or + other tool-managed directories. + +## Reporting + +List any `_tmp-*` cruft you leave behind, with a reason, in your final +summary. Silent orphans defeat the whole point. diff --git a/cursor-team-kit/rules/worktree-cleanup.mdc b/cursor-team-kit/rules/worktree-cleanup.mdc new file mode 100644 index 00000000..9a394052 --- /dev/null +++ b/cursor-team-kit/rules/worktree-cleanup.mdc @@ -0,0 +1,68 @@ +--- +description: Clean up git worktrees when their branch merges so parallel-work siblings do not accumulate +alwaysApply: true +--- + +# Worktree cleanup + +Applies to any repo where an agent uses `git worktree` to run parallel +branch work in sibling directories. The same session that adds a +worktree is responsible for removing it. Pairs with (does not repeat) +one-writer-per-branch and subagent-isolation guidance covered by rules +like `parallel-agent-write-discipline`. + +## Create + +Use short-lived sibling worktrees off the integration branch, and name +them so it is obvious what work they hold: + +```bash +git -C worktree add ../-wt- \ + -b feature/ origin/ +``` + +Reach for a worktree when: another session owns the current branch, the +tree is dirty with edits you did not author, or a subagent needs write +access without touching the shared checkout. + +## Commit before removing + +Never `git worktree remove` a dirty tree. Either land the work (its PR +merges, or push the WIP branch) or get explicit user OK to discard. +If a session ends mid-flight, commit WIP with a clear message on the +feature branch first -- uncommitted work in a removed worktree is gone. + +## Remove when done + +After the worktree's PR merges (or the branch is abandoned), the same +session that created it must, from the main checkout: + +1. `git worktree remove ` +2. `git worktree prune` +3. `git branch -d feature/<...>` once fully merged. Do not use `-D` + without a merge-into-integration proof and a note explaining it. + +Never delete long-lived branches: `main`, `master`, `staging`, +`develop`, or any equivalent release line. + +## Report leftovers + +An agent's final response must list any worktree it created and either +state that it has been removed or explain why it stayed (for example, +`unmerged WIP at on branch `). Silent orphans defeat the +whole point. + +## Optional housekeeping pass + +At session end, an agent may `git worktree list` and remove siblings +whose branches are already merged to the integration branch upstream, +but only when the worktree is clean, `git status` shows no changes it +did not author, and no other running agent owns it. When in doubt, +leave it. + +## Never touch + +- Another running agent's worktree. +- The main repo checkout the shared session is working out of. +- Unrelated sibling project folders that happen to live next to the + repo's worktree siblings.