# Compaction Handoff

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-uzysjung-uzys-agent-harness-compaction-handoff`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [uzysjung](https://agentstack.voostack.com/s/uzysjung)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [uzysjung](https://github.com/uzysjung)
- **Source:** https://github.com/uzysjung/uzys-agent-harness/tree/main/templates/skills/compaction-handoff
- **Website:** https://uzysjung.github.io/uzys-agent-harness/

## Install

```sh
agentstack add skill-uzysjung-uzys-agent-harness-compaction-handoff
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Compaction Handoff Protocol

A context window is about to be summarized and reinitialized. The model is stateless, so **only
what you write out survives** — the new window starts from a lossy summary, not the live history.
This skill runs the handoff deliberately so the resumed session can pick up without re-deriving
lost state.

> Sibling skill `strategic-compact` decides **WHEN** to compact (phase boundaries, token pressure).
> This skill is the **HOW**: it executes the handoff at that moment. Run `strategic-compact`'s
> decision first if you're unsure whether to compact at all; run this when the answer is "yes".

## When to use

The user works in Korean and triggers this repeatedly. Treat any of these as a fire signal:

- **"컴팩션 준비해줘"** / **"컴팩션하고 이어서 진행할 수 있게 준비해줘"** / **"핸드오프 준비해줘"**
- English equivalents: "prepare for compaction", "get ready to compact and continue", "hand off".
- **Proactively, before the cliff.** Don't wait for auto-compact at 100%. Auto-compaction fires
  near the window limit; a common practice is to trigger the handoff earlier (around ~80% of the
  window) so there's still budget to write a clean anchor — a rushed handoff at the cliff is exactly
  where load-bearing context gets dropped.

Why proactive matters: auto-compact optimizes for *generic* continuity, not for THIS task's
load-bearing facts (an open PR, a chosen-but-unwritten decision). If you skip the handoff because
the task "looks finished," you risk silent information loss — the resumed agent assumes work
shipped that did not.

## The model: three legs of a checkpoint

Treat the handoff as a deliberate checkpoint, not a passive summary. Three legs, each grounded in
an established practice:

1. **Persist durable facts to external memory** *(before compacting, never after)*.
   The window will be wiped; structured note-taking exists precisely because the summary alone
   can't be trusted to carry everything. Route load-bearing *decisions* to ADRs (`docs/decisions/`)
   so the *why* survives every future compaction, not just this one.
2. **Take an atomic, reconstructible snapshot** — git clean (or a `savepoint` commit) plus an
   **open-PR check**. A dirty/half-committed tree is a corrupt checkpoint; an open PR is itself
   critical state that belongs in "what's left." This is the Checkpoint **Atomicity** and **State
   Completeness** principles applied to the working tree.
3. **Emit a fixed-field resume anchor** — current state / verified / what's left / next action —
   framed *working backwards* from the next concrete step so a freshly-compacted agent re-orients
   instantly instead of replaying history forward.

### Preserve-list, not a prose blob

Use an explicit preserve-list rather than a free-form paragraph (Anthropic's stated preserve/discard
split):

| Preserve (high-value) | Discard (low-value) |
|---|---|
| Architectural decisions + their *why* (link ADR) | Redundant tool outputs, raw logs |
| Unresolved bugs / blockers | Intermediate reasoning already acted on |
| Processed-vs-remaining boundary | File contents you can re-read from disk |
| Open PRs / unpushed branches | Tool-call counts and history |
| Verified-vs-merely-claimed evidence | Restated CLAUDE.md / rules (already loaded) |

## Workflow

Run these in order. Each writes durable state *before* the window is touched.

**1. Memory — persist durable facts.**
Update the auto-memory (`MEMORY.md`) and any session-summary entry with the preserve-list items.
For a load-bearing decision (architecture, dependency, data model, breaking change), write or update
an ADR in `docs/decisions/` — this is the one place "the why behind the constraint" survives lossy
compaction. Don't rely on the `/compact` summary to carry a decision; it strips provenance.

**2. Git — atomic snapshot + open-PR check.**
Make the working tree reflect a consistent state. The `gh pr list` step is **not optional** — it is
the git-policy **Session Cleanup** gate, which is mandatory before any `/clear` or `/compact`. Run it
every handoff:
```bash
git status --short                 # is the tree clean?
# IF tree is dirty AND the work is worth keeping:
git add -A && git commit -m "chore: savepoint before compaction handoff"
gh pr list --state open            # list open PRs — each open PR is what's-left state to surface, not necessarily an anomaly
git branch --show-current          # note unpushed branch state
```
This folds the git-policy **Session Cleanup** gate into the handoff. An open PR is not a
loose end to hide — surface it in the anchor's "what's left" with its number, CI status, and
mergeability, and let the user decide (no auto-merge).

**3. Resume anchor — four fixed fields.**
Emit the anchor. Keep "verified" distinct from "done": *done* is a claim, *verified* encodes the
evidence (test PASS output, exit 0, a merged PR). The resumed agent re-trusts only what's verified.
Make **next action** mandatory and singular — it's the entry point the resumed session executes
first, so the anchor is self-serve (Recovery Automation), not a note to re-interpret.

**4. Suggested /compact line.**
Hand the user a one-line custom summary to pass to `/compact` (e.g.
`/compact Resume: finish ADR-022 flag removal; PR #160 merged, branches drift test failing`). This
is a pointer to the durable anchor, not a replacement for it.

## Handoff report format

Present a compact status table, then the anchor:

```
| Check          | Result                                  | Status |
|----------------|-----------------------------------------|--------|
| Memory         | MEMORY.md + ADR-022 updated             | ✓      |
| Git            | tree clean, savepoint a1b2c3d           | ✓      |
| Open PRs       | gh pr list → 0 open                      | ✓      |
| Files          | resume anchor written, plan SSOT synced | ✓      |
```

## Worked example

**Input** (user, at ~78% context):
> 컴팩션하고 이어서 진행할 수 있게 준비해줘

**Output:**

Handoff checks:

| Check    | Result                                          | Status |
|----------|-------------------------------------------------|--------|
| Memory   | MEMORY.md code-quality-cycle entry refreshed    | ✓      |
| Git      | tree clean (no savepoint needed)                | ✓      |
| Open PRs | `gh pr list` → **1 open: #165** CI pass, mergeable | ⚠ surfaced |
| Files    | resume anchor below; persona-feedback SSOT synced | ✓      |

**Resume anchor**
- **Current state:** Persona P0 fixes in progress on branch `fix/persona-p0`. 2 of 4 fixes landed.
- **Verified:** `npm run ci` exit 0 on current HEAD (typecheck + lint + coverage branches 88.4% + build). Docker scenario for `--with ` exit 0.
- **What's left:** Fixes 3 & 4 (wizard copy + COMPATIBILITY honesty). **Open PR #165 is not merged** — publishing is blocked until P0 complete (per persona-feedback-improvements.md). Branch `fix/persona-p0` unpushed for the last 2 commits.
- **Next action:** Implement fix 3 (wizard understanding-category copy), then re-run `npm run ci`.

**Suggested /compact line:**
`/compact Resume fix/persona-p0: do fix 3 (wizard copy) next, then ci; PR #165 open & blocks publish until all 4 P0 done`

Notice what the anchor does deliberately: it leads with the **next action** (working-backwards), keeps
the open PR visible in "what's left" instead of assuming it shipped, and separates the *verified* CI
evidence from the *unverified* remaining fixes.

## Pitfalls this guards against

- **Lossy summary-stripping** — a headline-only handoff looks complete but is unrecoverable because
  the evidence and reasoning chains are gone. Fix: preserve-list + ADR provenance, not a prose blob.
- **Lost-in-the-Middle over-stuffing** — dumping full history into the new window doesn't help;
  buried facts follow a U-shaped accuracy curve. The anchor stays short and structured.
- **Telephone-game decay** — fidelity erodes across successive compactions. Routing load-bearing
  facts to stable memory/ADRs breaks the degradation chain a chain of summaries can't.
- **Non-atomic snapshot** — handing off with a half-committed tree reconstructs an inconsistent
  state. The git leg forces a clean or savepoint-committed tree.
- **Incomplete state save** — omitting the processed-vs-remaining boundary forces duplicate work or
  silent re-execution of irreversible actions. The "what's left" field is mandatory.

## References

- Anthropic — *Effective context engineering for AI agents* (Compaction; Structured Note-Taking /
  Agentic Memory): https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- Hendricks.ai — Checkpoint patterns (State Completeness, Atomicity, Recovery Automation):
  https://hendricks.ai/insights/checkpoint-patterns-long-running-ai-agent-tasks
- XTrace — AI agent context handoff (Decisions / Artifacts / Preferences / Timeline; decision
  provenance): https://xtrace.ai/blog/ai-agent-context-handoff
- Architectural Decision Records (ADR) — append-only single-decision records; route load-bearing
  decisions here so the *why* survives compaction.
- Amazon *Working Backwards* — lead the anchor with the end state and the single next action.

## Related skills

- **strategic-compact** — decides WHEN to compact (phase boundaries, token pressure). Pair with it:
  it answers "compact now?", this skill executes the handoff when the answer is yes.
- **git-policy Session Cleanup** — the open-PR check (leg 2) is the same gate; this skill folds it
  into the pre-compaction moment.

## Source & license

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

- **Author:** [uzysjung](https://github.com/uzysjung)
- **Source:** [uzysjung/uzys-agent-harness](https://github.com/uzysjung/uzys-agent-harness)
- **License:** MIT
- **Homepage:** https://uzysjung.github.io/uzys-agent-harness/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-uzysjung-uzys-agent-harness-compaction-handoff
- Seller: https://agentstack.voostack.com/s/uzysjung
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.