From 8b41c9707fa5eacb26e6f9496d48b5aae03f0fe2 Mon Sep 17 00:00:00 2001 From: Aaron Bockelie Date: Mon, 29 Jun 2026 01:28:32 -0500 Subject: [PATCH] feat(wrap): add /wrap skill + meta/wrap way for deliberate session close MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `compaction-checkpoint` way already handles the automatic, near-limit checkpoint. This adds the on-demand counterpart: a way the user pulls when they decide the session is at a seam. - skills/wrap/SKILL.md — the procedure: read the context gauge first (early-vs-late shapes how heavy the handoff is), loose-ends check (ship is iterative, wrap is terminal — wrap doesn't ship, it confirms nothing stranded), an honest TaskList pass (close done, retire stale, write real remaining with resume-detail), a dense continuation prompt that survives even /clear, and a gauge-dependent handoff to a directed /compact. A skill can't trigger /compact itself, so it hands over a ready-to-run line. - hooks/ways/meta/wrap/wrap.md — keyword + semantic router that catches "wrap up / hand this off / done for the day" and points Claude at the skill with the why (the three failure modes of a freehand wrap). - Cross-refs: compaction-checkpoint and todos now point back at wrap, closing the loop between the automatic and on-demand siblings. Claude-Session: https://claude.ai/code/session_01TFyiQNDZ8RTMHX4Tnmp1wY --- .../compaction-checkpoint.md | 1 + hooks/ways/meta/todos/todos.md | 5 + hooks/ways/meta/wrap/wrap.md | 48 +++++ skills/wrap/SKILL.md | 170 ++++++++++++++++++ 4 files changed, 224 insertions(+) create mode 100644 hooks/ways/meta/wrap/wrap.md create mode 100644 skills/wrap/SKILL.md diff --git a/hooks/ways/meta/compaction-checkpoint/compaction-checkpoint.md b/hooks/ways/meta/compaction-checkpoint/compaction-checkpoint.md index 9e9a6fdf..9b94a381 100644 --- a/hooks/ways/meta/compaction-checkpoint/compaction-checkpoint.md +++ b/hooks/ways/meta/compaction-checkpoint/compaction-checkpoint.md @@ -68,6 +68,7 @@ When a goal is active: ## See Also +- wrap(meta) — the on-demand version: same wrap-up when *you* pick the seam, routing to the `/wrap` skill. This way is the automatic sibling that fires near the limit. - tracking(meta) — tracking files survive compaction - todos(meta) — task state should be captured before compaction - goals(meta) — an active /goal anchors continuation across the checkpoint diff --git a/hooks/ways/meta/todos/todos.md b/hooks/ways/meta/todos/todos.md index 28b0352f..d3f0259e 100644 --- a/hooks/ways/meta/todos/todos.md +++ b/hooks/ways/meta/todos/todos.md @@ -32,3 +32,8 @@ For each task, capture: Mark the in-flight task as `in_progress`. This creates the tasks-active marker and stops this checkpoint from repeating. This repeats every prompt until you create a task list or the session ends. + +## See Also + +- wrap(meta) — wrapping a session deliberately runs this same TaskList-honesty pass, then writes a continuation prompt and hands off to a directed compaction. The `/wrap` skill is where the on-demand version lives. +- compaction-checkpoint(meta) — the broader near-limit checkpoint this task discipline feeds. diff --git a/hooks/ways/meta/wrap/wrap.md b/hooks/ways/meta/wrap/wrap.md new file mode 100644 index 00000000..e9b86bca --- /dev/null +++ b/hooks/ways/meta/wrap/wrap.md @@ -0,0 +1,48 @@ +--- +description: Recognize an end-of-session signal and route to the /wrap skill — square the TaskList honestly, write a continuation prompt, and hand off to a gauge-aware directed compaction. +vocabulary: wrap session end checkpoint handoff continuation compact close out done for the day pause stopping point sign off end of session wind down +pattern: wrap.?(up|this up|it up|things up)|wrapping up|let'?s wrap|end of (the )?session|wrap.{0,10}(session|for the day|for today)|checkpoint.{0,15}compact|/wrap +scope: agent +refire: 0.15 +--- + +# Wrapping Up + +The user is signaling the session is ending — they want to close out, not keep building. +This is exactly what the **`wrap` skill** is for. Pull it up (`Skill: wrap`) rather than +improvising a summary; the skill enforces the parts that are easy to skip when you eyeball it. + +## Why the skill, not a freehand summary + +Three things go wrong when an end-of-session wrap is done by feel: + +- **The TaskList lies.** Finished work sits marked pending; abandoned ideas linger as + tasks; real remaining work has no entry. Post-reset-you inherits that list with zero + memory of this conversation. The skill makes squaring it honestly the load-bearing step — + close done, retire stale, write what's real with enough detail to resume cold. +- **The handoff is too thin to resume from.** The skill produces a dense, copy-paste + continuation prompt that survives even a hard reset (`/clear` + paste), not just compaction. +- **Compaction is mis-timed.** Wrapping at 30% is not wrapping at 90%. The skill reads the + context gauge *first* (`ways context`) and lets early-vs-late shape how heavy the handoff + needs to be — and whether `/compact` is even worth it (early, it reclaims little and ends + the live thread). + +## The compaction caveat + +Neither a way nor a skill can trigger `/compact` — Claude Code forbids invoking `/` commands +programmatically. So `/wrap` *prepares* everything and hands the user a ready-to-run +`/compact ` line. Don't claim the session was compacted; you set it up, the user pulls +the trigger. + +## Relation to the automatic sibling + +The `compaction-checkpoint` way fires **on its own** as context nears the limit. This way +fires when the **user says so** — an early, deliberate close. Same destination, different +trigger: one is the smoke alarm, the other is choosing to leave. + +## See Also + +- wrap (skill) — the procedure this routes to. +- compaction-checkpoint(meta) — the automatic, threshold-triggered sibling. +- todos(meta) — the TaskList-at-compaction discipline the skill enforces on demand. +- ship(softwaredev) — shipping is iterative (many per session); wrapping is terminal (once). diff --git a/skills/wrap/SKILL.md b/skills/wrap/SKILL.md new file mode 100644 index 00000000..d9e13f16 --- /dev/null +++ b/skills/wrap/SKILL.md @@ -0,0 +1,170 @@ +--- +name: wrap +description: Wrap up a session at a natural seam — land in-flight work, square the TaskList honestly, write a copy-paste continuation prompt, then hand off to a directed /compact. Use when the user says "wrap up", "wrap this up", "let's wrap", "end of session", "checkpoint and compact", "hand off", or invokes /wrap. +allowed-tools: Bash, Read, Grep, Glob, TaskList, TaskCreate, TaskUpdate, TaskGet, AskUserQuestion, Agent +--- + +# Wrap + +Close out a session at its end. This is the on-demand sibling of the +`meta/compaction-checkpoint` way — the way fires automatically near the context limit; +`/wrap` runs the same muscle whenever you decide the session is done. + +**Wrap is not ship.** Shipping is *iterative* — many ships happen across a session as +each piece of work lands. Wrap is *terminal* — it runs once, at the end. By the time you +wrap, the session's work should already be shipped. So `/wrap` does **not** ship; it +confirms nothing got stranded, then produces the artifacts that outlive the session. + +The deliverable is two things that survive a reset: a **TaskList that honestly mirrors +reality**, and a **copy-paste continuation prompt**. The skill ends by handing you a +ready-to-run `/compact` line — it cannot run it for you (see Step 4). + +## Arguments + +- `/wrap` — full flow: land work (offer), square the TaskList, write the handoff, hand off to `/compact`. +- `/wrap stay` — wrapping mid-work on purpose: **skip** the land/merge step. Don't ship anything; just capture state accurately and produce the handoff. Use when the seam is "I'm pausing", not "I'm done". + +## Step 0 — Read the context gauge first + +Before anything else, check where the session sits. Same source as `context-status`: + +```bash +ways context --json # used / total tokens, pct filled; total auto-detected from model +``` + +The fill level calibrates the entire wrap, and is worth saying out loud — the user may be +wrapping early *on purpose*, and that's valid. Locate it against the ways trigger curves +(the `todos` way fires ~75%, `compaction-checkpoint` ~85%): + +- **Early** (well below the curves — e.g. 300k/1M, 30%): lots of headroom. Say so plainly + ("we'd be wrapping early — 300k of 1M used"), but **don't talk the user out of it** — + end-of-day, task-switching, or banking a clean state are all good reasons. When early, + `/compact` reclaims little and costs you the live thread, so in Step 4 *offer the lighter + paths*: checkpoint-and-continue (no compact), or `/clear`+paste later. The handoff can be + leaner — less accumulated context means less to reconstruct. +- **Late** (near or past the curves): compaction is imminent or already mandatory. This is + the urgent case — be thorough and quick. A lot is about to be summarized away, so the + continuation prompt and TaskList carry more weight; get them down before auto-compact + fires on its own. + +Let this scale Steps 2–3: **how much detail the handoff needs is proportional to how much +context is about to be lost.** A near-full window deserves a dense, complete prompt; an +early wrap can be crisp. Knowing the *total* window (1M vs 200k) is what makes that call. + +## Step 1 — Loose-ends check (not a ship step) + +Wrap assumes the session's work already shipped. This step only confirms that and catches +anything stranded — it is **not** the place to run a full delivery. Assess in parallel: + +```bash +git status --short # uncommitted changes? +git branch --show-current +git log --oneline main..HEAD # unmerged commits? +``` + +- **Clean / already merged** → the expected state. Move on. +- **Something stranded** (uncommitted changes, or commits never PR'd) → this is a guard, not wrap's job. Surface it and let the user decide: invoke `ship` to land it, or leave it parked. +- **Parked on purpose** (`/wrap stay`, or user chooses to leave it) → do **not** merge. Record *exactly* what's uncommitted, on which branch, and why it's parked — verbatim into Step 3 so post-reset-you can resume the partial work cold. + +The rule: wrap never silently drops stranded work, and never ships it behind your back. +Either the user ships it (via `ship`), or it's described in the handoff. + +## Step 2 — TaskList honesty pass (load-bearing) + +This is the point of the skill, not a footnote. Post-compaction-you (or a fresh session) +inherits the TaskList with **zero memory of this conversation** — so the list must be +*true*, not optimistic. Use `TaskList` to read current state, then reconcile it: + +**Close the books** (`TaskUpdate`): +- Mark genuinely-finished tasks `completed`. +- Retire stale, obsolete, abandoned, or aspirational tasks — don't carry cruft forward. A task that no longer reflects the plan is noise that will mislead the next session. + +**Write what's real** (`TaskCreate`): +- One task per piece of *actual* remaining work. +- Each `description` must be resumable cold: file paths, decisions already made (so they aren't re-litigated), what was tried, and the next concrete step. The `subject` is imperative; `activeForm` is present-continuous. +- Mark the genuine next task `in_progress`. + +**The bar is honesty.** Before moving on, sanity-check: does any "pending" task describe +work that's actually done? Does any real remaining thread have no task? A dishonest list +is worse than none — it hands the next session a confident lie. + +## Step 3 — Write the continuation prompt + +Produce a single copy-pastable block. Compaction keeps the session alive; this prompt is +the harder guarantee — it survives even a `/clear` or a brand-new window. Tailor sections +to the work, but cover: + +``` +Continue work on () — . +. + +LANDED — . + +STATE — IN FLIGHT — . + +INVARIANTS / GOTCHAS — + +DO NEXT — . + +CONVENTIONS — . + +KEY FILES / BRANCHES — . +``` + +If a `/goal` is active, **restate the goal condition** at the top — it's the anchor the +post-compaction turns steer by, and it survives compaction. + +Keep it dense and concrete. The gold standard is a prompt a stranger could resume from. + +## Step 4 — Hand off (compaction is gauge-dependent) + +First, let Step 0 decide whether compaction even applies: + +- **Early wrap** → `/compact` is *optional*; it reclaims little and ends the live thread. + Lead with the lighter paths: checkpoint-and-continue (keep working in the same session — + the TaskList and handoff are already saved), or `/clear`+paste later for a clean switch. + Mention `/compact` as available, not as the default. +- **Late wrap** → compaction is the point. Make the directed `/compact` the headline action. + +A skill **cannot** trigger `/compact` — Claude Code forbids hooks/skills from invoking +`/` commands. So when compaction is the move, end by handing the user a one-keystroke +directed compaction, and explain why directed beats generic: + +> The synthesis above is now the freshest content in context. Run `/compact` with these +> focus instructions and it'll preserve the synthesis as the anchor instead of the system +> keeping whatever it guesses: + +Then output the exact line, with focus instructions tailored to what should survive: + +``` +/compact keep the continuation prompt and TaskList state; 's next step is ; drop the exploratory back-and-forth +``` + +Offer the alternative explicitly: for a hard reset (switching tasks entirely), `/clear` +then paste the Step 3 prompt into a fresh session — the old one stays in `/resume`. + +Make the `/compact ...` line the **last thing** in your response so it's immediately +copyable. Do not claim the session is compacted — you've prepared it; the user pulls the trigger. + +## Key Principles + +- **The TaskList must be honest** — done is done, stale is gone, real work is captured with resume-detail. That's the load-bearing deliverable. +- **Prepare, don't pretend** — the skill can't self-compact; it hands off a ready `/compact`. Never report compaction as done. +- **Directed > generic** — a synthesis-anchored `/compact` keeps what matters; an unanchored one keeps what the system guesses. +- **On-demand, not automatic** — that's the whole reason this exists alongside the `compaction-checkpoint` way. You choose the seam. +- **Two survival layers** — TaskList + continuation prompt survive even a hard reset; `/compact` is the lighter same-session path on top. + +## Not for + +- Authoring the code being wrapped — `/wrap` closes out work, it doesn't write it. +- Replacing the `compaction-checkpoint` way — that fires passively near the limit; this is the on-demand version. They share DNA on purpose. +- Actually performing compaction — it can't. It prepares everything and hands you `/compact`. + +## See Also + +- `ship` — Step 1 delegates here to land work. +- `compaction-checkpoint` (meta way) — the automatic sibling that fires near the context limit. +- `todos` (meta way) — the TaskList-at-compaction discipline this enforces on demand. +- `context-status` — check how much room is left before you decide to wrap.