Flush

Flush

Manually flush the deferred-commit queue from a chain that ran with commit-when=end. Normally /hyperflow:dispatch calls scripts/flush-commits.sh at its Step 4 wrap-up; this skill exists for the case where the chain was interrupted (crash, kill, context loss) before the auto-flush ran.

Subcommands

| Subcommand | Description | |---|---| | (no arg) | Run scripts/flush-commits.sh — fast-forward staging onto user's branch, delete staging, clear queue | | --dry-run | Show what would be flushed without doing it. Lists the queued commits in order. |

What gets flushed

.hyperflow/commits-queue/manifest.json tracks the chain's user_branch, staging_branch (always hyperflow/staging-), and the list of queued commits with SHAs and messages. Flush replays them via git merge --ff-only so:

• All N commits land on the user's branch with original SHAs preserved
• Order is chronological (queue-time order)
• Original commit messages are preserved
• Original file-to-message mapping is preserved (each commit touched exactly the files its sub-task touched)

What happens if fast-forward isn't possible

If the user's branch diverged from staging (e.g. the user committed manually mid-chain on the same branch), git merge --ff-only refuses. The skill surfaces the error with two recovery options:

1. git rebase hyperflow/staging- — replay staging commits on top of user's new commits
2. git cherry-pick ..hyperflow/staging- — selectively pick commits

The staging branch is preserved for the user to act on manually. The queue manifest stays in place so a future /hyperflow:flush retry can attempt again after the user resolves divergence.

Flow

1. Check .hyperflow/commits-queue/manifest.json exists. If not, print No queue to flush. and stop.
2. Run bash $PLUGIN_ROOT/scripts/flush-commits.sh $PROJECT_ROOT [--dry-run].
3. Print the script's output verbatim.

Overview

/hyperflow:flush is the user-facing handle for the deferred-commit flush mechanism. Most users never call it explicitly — /hyperflow:dispatch Step 4 wrap-up runs the same script automatically. This skill exists for recovery: if a chain ran with commit-when=end and crashed before wrap-up, the queue persists on disk and the user can flush it later.

Prerequisites

• .hyperflow/commits-queue/manifest.json exists from a prior chain run with commit-when=end.
• Git repository, on a branch the manifest's user_branch field can be checked out into.
• scripts/flush-commits.sh available in the plugin install.

Error Handling

| Failure | Behavior | |---|---| | No manifest file present | Print No queue to flush. Exit 0. | | Staging branch missing (manual deletion or rename) | Print warning; clear stale manifest. Exit 0. | | Fast-forward not possible (user branch diverged) | Surface git error + recovery suggestions (rebase / cherry-pick). Leave staging branch + manifest intact for manual handling. Exit non-zero. | | User on a branch other than manifest's userbranch | Check out manifest's userbranch automatically; if checkout fails, surface error. |

Examples

Dry-run before flushing

/hyperflow:flush --dry-run

flush-commits (DRY RUN): would fast-forward 7 commits from hyperflow/staging-2026-05-17-1430 onto feat/auth-refactor
abc1234 feat(auth): T7 wire login handler
def5678 feat(auth): T6 add session middleware
…

Recovery after crash

You: /hyperflow:flush

flush-commits: flushed 7 commits onto feat/auth-refactor
abc1234 feat(auth): T7 wire login handler
…

Resources

• [scripts/flush-commits.sh](../../scripts/flush-commits.sh) — the actual flush mechanism.
• [scripts/queue-commit.sh](../../scripts/queue-commit.sh) — the queue-write side called by dispatch during the chain.
• [DOCTRINE.md Layer 8](../hyperflow/DOCTRINE.md#layer-8-git-workflow) — commit-when timing rules.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeremylongshore
• Source: jeremylongshore/claude-code-plugins-plus-skills
• License: MIT
• Homepage: https://tonsofskills.com

Install and usage instructions live in the source repository linked above.