ai-branch-cleanup
$
npx mdskill add arcasilesgroup/ai-engineering/ai-branch-cleanup``` /ai-branch-cleanup # full: sync + branch cleanup + spec sweep + runtime rotate + report /ai-branch-cleanup --sync # sync to default branch only /ai-branch-cleanup --branches # branch cleanup only /ai-branch-cleanup --specs # spec lifecycle sweep + _history.md rotation /ai-branch-cleanup --runtime # rotate .ai-engineering/runtime/ per retention policy /ai-branch-cleanup --consolidate-spec <slug> # delete finalised spec, append _history row ```
SKILL.md
.github/skills/ai-branch-cleanupView on GitHub ↗
--- name: ai-branch-cleanup description: "Cleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead." effort: cheap argument-hint: "--branches|--sync|--specs|--runtime|--consolidate-spec <slug>|--all" mode: agent tags: [git, branch, cleanup, hygiene, status, delivery] requires: bins: - git model_tier: haiku mirror_family: copilot-skills generated_by: ai-eng sync canonical_source: .claude/skills/ai-branch-cleanup/SKILL.md edit_policy: generated-do-not-edit --- # Branch Cleanup ## Quick start ``` /ai-branch-cleanup # full: sync + branch cleanup + spec sweep + runtime rotate + report /ai-branch-cleanup --sync # sync to default branch only /ai-branch-cleanup --branches # branch cleanup only /ai-branch-cleanup --specs # spec lifecycle sweep + _history.md rotation /ai-branch-cleanup --runtime # rotate .ai-engineering/runtime/ per retention policy /ai-branch-cleanup --consolidate-spec <slug> # delete finalised spec, append _history row ``` Full repository hygiene: safely migrate to the default branch, delete merged and squash-merged branches, rotate runtime artifacts, and produce a per-branch status report. No destructive operations without confirmation. ## When to Use - Session start, after merging PRs, between tasks, before `/ai-brainstorm`. - NOT for committing -- use `/ai-commit`. ## Process Default (no flags) is equivalent to `--all`: runs sync, branch cleanup, and report. ### Phase 0a: Instinct consolidation (default / `--all`, fail-open) 0. **Consolidate session learnings BEFORE switching branches** -- if `.ai-engineering/observations/observations.yml` exists, run `/ai-session-watch --review` to fold this session's observations (especially the LLM-only `corrections` family) into the corpus. This closes the no-commit/no-PR gap: a session that ends at tidy-up time — without a `/ai-commit` or `/ai-pr` having run `--review` — still consolidates its learnings instead of losing them. Skip silently when the file is absent (fail-open) or when a single-purpose flag (`--branches` / `--sync` / `--specs` / `--runtime` / `--consolidate-spec`) was passed without `--all`. Mirrors the `/ai-pr` Step 2 and `/ai-commit` Step 2 gate. ### Phase 0: Safe Migration (`--sync` or `--all`) 1. **Detect default branch** -- `git symbolic-ref refs/remotes/origin/HEAD` (main or master). 2. **Record current branch** for the report. 3. **Auto-stash if dirty** -- `git stash push -m "cleanup-auto-stash-$(date +%s)"`. 4. **Switch to default** -- `git checkout <default>`. 5. **Pull latest** -- `git pull --ff-only origin <default>`. If ff-only fails: WARN and STOP. 6. **Restore stash** -- `git stash pop`. If conflict: WARN, leave stash, continue cleanup. ### Phase 1: Branch Analysis (`--branches` or `--all`) 7. **Fetch and prune** -- `git fetch --prune origin`. 8. **Enumerate** all local branches (excluding `main`, `master`). 9. **Classify each branch**: | Category | Criteria | Action | |----------|----------|--------| | Merged | In `git branch --merged <default>` | Delete (`git branch -d`) | | Squash-merged | Not in `--merged` but `git diff <default>..<branch>` is empty | Delete (`git branch -D`) | | Gone (safe) | Tracking ref `[gone]` AND no content diff | Delete (`git branch -D`) | | Gone (has dev) | Tracking ref `[gone]` BUT has content diff | KEEP | | Active | Has remote tracking, not merged | KEEP | | Local only | No remote, has commits ahead | KEEP | 10. **Delete eligible** -- merged with `-d`, squash-merged and gone-safe with `-D`. ### Phase 3: Spec sweep (`--specs` or `--all`) Reap stale spec drafts so the lifecycle ledger does not accumulate abandonware. Invoke `python .ai-engineering/scripts/spec_lifecycle.py sweep`: DRAFTs older than 14 days move to ABANDONED; counts are returned as JSON and emitted as a `framework_operation` audit event. **Fail-open**: a missing script or locked sidecar logs and continues — branch cleanup is the load-bearing hot path here. ### Phase 4: Runtime rotation (`--runtime` or `--all`) Rotate `.ai-engineering/runtime/` so transient observability data does not bloat the working tree. Invoke `python .ai-engineering/scripts/runtime_rotate.py`: | Subtree | Retention | Action | |-----------------------------------|--------------------|-------------| | `runtime/tool-outputs/*.txt` | 7 days | unlink | | `runtime/autopilot/sub-*` | 30 days | rmtree | | `runtime/tool-history.ndjson` | 10000 lines / 5 MB | tail-truncate | Hot-path budget <100 ms; stdlib only; idempotent; fail-open on missing dirs; emits a `runtime-rotate` `framework_event` per run. ### Phase 5: Spec consolidation (`--specs` or `--all`) First **reconcile merged-but-unshipped specs**, then **consolidate** — `ai-eng cleanup specs` runs both verbs in order (`reconcile_merged` then `consolidate_shipped`). The composite phase ORDER is unchanged (the D-161-04 fix is gh-aware classification, NOT resequencing). The reconcile pass (`python .ai-engineering/scripts/spec_lifecycle.py reconcile_merged`) is the D-153-03 backstop: for any non-terminal sidecar (DRAFT/APPROVED/IN_PROGRESS), it classifies merge state primarily via `gh` PR state (`gh pr list --head <branch> --state merged`), which SURVIVES the Phase-1 branch prune; the local-ref check (`git branch --merged` + squash-merge emptiness) is the FALLBACK when `gh` is absent. On a merged classification it resolves the PR via `gh` and calls `mark_shipped` — catching specs merged via the GitHub UI that `/ai-pr` never marked, including those whose local branch Phase 1 already deleted. Then `python .ai-engineering/scripts/spec_lifecycle.py consolidate_shipped` appends the canonical 7-col `_history.md` row for any SHIPPED record (including the ones reconcile just marked) and emits the `framework_operation` audit event. **Verification-only step** — actual lifecycle writes live in `spec_lifecycle.py`; this skill calls the entry point. Idempotent: already-SHIPPED records are a no-op. **Fail-open**: missing script or locked sidecar logs and continues. See `.github/skills/_shared/consolidate-spec.md` for the shared handler; the `--consolidate-spec <slug>` flag exposes the explicit post-merge action via `spec_lifecycle.py mark_shipped`. ### Phase 2: Status Report 11. **Build per-branch table**: ```markdown ## Repository Cleanup Report **Default branch**: `main` (up to date) **Previous branch**: `feat/old-feature` **Working tree**: clean | stash restored | stash pending | Branch | Action | Reason | Remote | Ahead/Behind | |--------|--------|--------|--------|--------------| | `feat/done` | DELETED | Merged | -- | -- | | `feat/squashed` | DELETED | Squash-merged | -- | -- | | `feat/active` | KEPT | Unmerged (5 commits) | origin/feat/active | +5/-2 | ``` ## Quick Reference ``` /ai-branch-cleanup # full: sync + branch cleanup + spec sweep + runtime rotate + report /ai-branch-cleanup --sync # sync to default branch only /ai-branch-cleanup --branches # branch cleanup only (no migration) /ai-branch-cleanup --specs # spec lifecycle sweep + _history.md rotation (DRAFT > 14d → ABANDONED; SHIPPED → row appended) /ai-branch-cleanup --runtime # runtime rotation only /ai-branch-cleanup --consolidate-spec <slug> # manual spec consolidation via _shared/consolidate-spec.md /ai-branch-cleanup --all # explicit full cleanup ``` ### Phase 6: Spec consolidation (`--consolidate-spec`) When invoked with `--consolidate-spec <slug>`, read `.github/skills/_shared/consolidate-spec.md` and execute the shared handler: resolve the spec record, append/upsert the `_history.md` row via `spec_lifecycle.py mark_shipped`, clear `.ai-engineering/specs/spec.md` and `plan.md` to placeholders. Fail-open on missing script. ## Common Mistakes - Force-pulling when ff-only fails -- STOP and resolve manually. ## Examples ### Example 1 — full hygiene at session start User: "tidy up before I start a new task" ``` /ai-branch-cleanup ``` Switches to `main`, ff-pulls, prunes merged + squash-merged branches, sweeps stale spec drafts, prints the per-branch report. ### Example 2 — branches only after a long session User: "just clean up old branches, leave the specs alone" ``` /ai-branch-cleanup --branches ``` Skips sync and spec sweep; runs branch classification + delete + report only. ## Integration Called by: `/ai-pr` (auto after merge), `/ai-start` (session bootstrap). Calls: `/ai-session-watch --review` (Phase 0a, fail-open instinct consolidation), `git`, `python .ai-engineering/scripts/spec_lifecycle.py sweep`, `python .ai-engineering/scripts/runtime_rotate.py`. See also: `/ai-brainstorm` (run before new spec), `/ai-simplify` (code-level cleanup). ## References - `.ai-engineering/manifest.yml` -- protected branch rules. - `.github/skills/ai-brainstorm/SKILL.md` -- spec creation composes cleanup. $ARGUMENTS
More from arcasilesgroup/ai-engineering
- ai-adviseProactive governance advisor — checks standards, decisions, and quality trends during development. Always advisory, NEVER blocks. Three modes: `advise` (post-edit), `gate` (pre-dispatch), `drift` (on-demand decision audit). Trigger for 'governance check', 'advise on this change', 'check for drift', 'is this aligned with active decisions', 'shift-left advisory'. Not for blocking gates — use /ai-verify. Not for narrative code review — use /ai-review.
- ai-analyze-permissionsUse when Claude Code keeps asking to approve commands you have already approved, when settings.local.json has grown large, or when you want to consolidate permission grants into wildcard patterns. Trigger for 'too many permission prompts', 'clean up permissions', 'audit my settings', 'consolidate allow rules'. Claude Code only — not available in GitHub Copilot, Antigravity, or Codex.
- ai-animationDesigns motion, transitions, and micro-interactions for UI components: spring animations, gestures, easing, staggers — taste-driven detail compounding. Trigger for 'animate this', 'add transitions', 'micro-interactions for', 'gesture design', 'swipe to dismiss', 'easing for this', 'stagger the'. Not for design systems; use /ai-design instead. Not for visual art; use /ai-visual instead. Not for testing animation code; use /ai-test instead.
- ai-autopilotDelivers large multi-concern specs and backlog runs autonomously: decomposes specs into sub-specs (or normalizes work items into a backlog DAG), deep-plans with parallel agents, builds a dependency DAG, implements in waves, runs a single final quality loop with one bounded quality-remediation pass (verify+guard+review on full changeset), delivers via PR. Trigger for 'implement spec-NNN end to end', 'autopilot this', 'autonomous delivery', 'decompose and ship', 'run the backlog', 'execute these GitHub issues', 'process the sprint backlog'. Invocation is the approval gate. Not for small or single-concern tasks; use /ai-build instead. Not for ambiguous requirements; use /ai-brainstorm first.
- ai-boardOperates the project board (GitHub Projects v2 or Azure DevOps): discovers configuration after install (fields, state mappings, process templates) and syncs work-item state at lifecycle transitions. Trigger for 'set up the board', 'configure our ADO board', 'discover board fields', 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Two subcommands: `discover` (post-install configuration write) and `sync` (lifecycle state transitions). Auto-invoked via `sync` by /ai-brainstorm, /ai-build, and /ai-pr; fail-open. Not for backlog execution; use /ai-autopilot --backlog instead.
- ai-brainstormForces rigorous design interrogation BEFORE any code: explores approaches, surfaces ambiguity, gathers evidence, produces an approved spec that becomes the contract for /ai-plan. Trigger for 'lets add X', 'how should we handle Y', 'whats the best approach', 'I am thinking about', 'what should we build for'. Not for existing approved specs; use /ai-plan instead. Not for execution; use /ai-build instead.
- ai-buildCanonical implementation gateway: reads approved plan.md, resolves stack from manifest, deterministic-routes each task to its adapter, dispatches the build agent in an isolated worktree, runs TDD self-validation per task, then a single final quality loop with one bounded quality-remediation pass on the full changeset before /ai-pr. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'lets do this', 'build the plan', 'resume', 'continue'. Not without an approved plan; run /ai-plan first. Not for multi-concern specs needing decomposition; use /ai-autopilot instead. Not for a single function or subcomponent; use /ai-code.
- ai-codeWrites production code that satisfies stack-context standards on the first pass: interface-first design, backward-compatibility checks, lightweight self-review. Trigger for 'implement this', 'write the code for', 'add X to Y', 'build this function', 'make this work'. Not for tests; use /ai-test instead. Not for debugging; use /ai-debug instead. Not for refactoring; use /ai-simplify instead. Not for executing an approved plan end-to-end; use /ai-build (the gateway).
- ai-commitRuns the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead.
- ai-constitutionInterviews the operator to produce a project-identity CONSTITUTION.md (Mission / Stakeholders / Vocabulary / Prohibitions / Compliance gates / Anti-goals / Boundaries / Escalation / Language / Lifecycle phase). Trigger for 'set up the constitution', 'define project identity', 'who is this project for', 'what does this project never do', 'amend the constitution'. Not for AI-behaviour rules — those live in CANONICAL.md / AGENTS.md. Not for spec governance; use /ai-governance instead.