Wrap

/wrap

Read ~/.claude/skills/vibeflow/CORE.md (or CORE.md at the vibeflow pack root, wherever it's installed) first (skip if already in context).

Mode stance: Archivist. Save this session's context, learnings, and progress so a cold session with no memory of this chat starts smarter — nothing it needs should live only here.

The test for every action: would a fresh session need this to proceed well? Precision over volume — each fact lands once, in its one home. Close the loop so that project context compounds instead of evaporating. Wrap often runs with context nearly gone, so the order below is deliberate: cheapest, highest-value work first, and everything front-loaded into batches.

1 — Ground (one silent batch)

In one parallel pass: git status + git diff (uncommitted) + git log since the last wrap commit (find it via the docs(wrap): prefix); every in-flight sprint file; the target docs you may edit (DECISIONS + ARCHITECTURE — skim whole, you'll edit only diff-touched areas — and ROADMAP top); .claude/.last-session.md and .claude/.session-snapshot.md if present (the snapshot means a prior session ended unwrapped — its work is part of this reconciliation). Reading targets now prevents mid-apply read-thrash later. No git repo? Skip diff reconciliation and the checkpoint commit — ground in the conversation, still write every .claude/ update, and suggest turning on git next session.

Base "what shipped" on the diff and log — the conversation supplies the why and the attribution, not the what. Stamp dates from the environment, never from memory (long sessions carry a stale sense of today).

2 — Attribute

Map changed paths → sprint scopes explicitly when more than one sprint is in flight, and say the mapping in one line ("profile components → profile-vault; bridge → hotfix task D — updating both"). A path both sprints could claim: attribute by which sprint's step it advances. Every touched sprint file gets its status updated — never consolidate two sprints' work into one file. Changes this session didn't discuss get flagged as a line in the proposal, not a standalone question ("payments/ also changed — leaving it out as another chat's work unless you say otherwise").

Update each touched sprint: check off what the diff proves shipped; "Last session" one-liner; "Next up" with the context to resume cleanly — including where iteration stalled mid-conversation ("user was mid-feedback on the Me page; reflection treatment undecided"), which is often the most valuable line in the file. Route open TO-DOs yourself (promote to a step / defer to ROADMAP Later / resolve into DECISIONS / drop) — only genuinely open forks go to the user.

Freebuild session with real work and no sprint: summarize what shipped from the diff and fold outcomes into the docs below; offer a retroactive archive entry only if the user wants a trace.

3 — Harvest and route

Walk the session once — the diff for what changed, the conversation for what we learned — and route each piece:

Most of these rows are empty in any given session — that's the normal outcome, not a miss. It's fine to find nothing for an area and leave its file untouched; write only where the session genuinely produced something a future session would act on.

Routing rules (from CORE.md, applied here): transient states → sprint TO-DOs only; merge-don't-append in DECISIONS (supersede in place, ≤6 lines/entry); lessons positive or negative; edit docs in place — never bolt on dated "what we did" sections; a quiet session legitimately updates only sprint progress. The global playbook is merge-first too: before appending a lesson there, check for an entry sharing its mechanism and amend that one instead; strip the story to kernel + reuse-when, and skip it entirely unless it would change how a session on a different project acts — that file loads everywhere, so every line taxes every session. Auto-memory handles incidental session habits on its own — wrap owns the git-tracked project state; don't duplicate into both.

Re-verify existing claims (the step that prevents doc rot): for each area the diff touched, check the Map, the ROADMAP top, and matching DECISIONS/gotcha lines — do they still hold? A model bump, a retired table, a cleared blocker: rewrite the stale sentence now, while the change is in context. While in ROADMAP, delete shipped items (top line + details block) and fix any dead pointers you notice.

Preferences: if the user corrected how you worked this session (verbosity, check-ins, framing, scope appetite), update the Working preferences block in the global profile — edit in place, max ~10 bullets.

Automation ticker (the recurring-work rule from CORE): if the session did a manual task that smells recurring — a deploy dance, a data pull, a status check, a formatting pass — add or update its line in .claude/automations.md: - <task, one line> — seen: YYYY-MM-DD (append today's date if the line exists; create the file on first use). A line with 2+ dates goes in the wrap proposal as a fork: automate it (skill / script / scheduled routine) or delete the line. Keep the file under a screenful — no ceremony, it's a ticker, not a backlog.

Rules come from causes, not incidents: before codifying a rule or lesson from a single incident, re-derive it from first principles — name the mechanism that actually caused the pain, and check the fix against how the user normally works. Prefer removing the cause over banning the command that exposed it; a rule that wouldn't survive the user asking "why?" isn't ready to write.

Distill when a doc outgrows a comfortable read (a sprawling DECISIONS area, a gotcha list past a screen, the global playbook's lessons past a screenful): merge same-fact duplicates into the richest single version, compress verbose entries to their load-bearing why, and fold long superseded chains into one line. Distilling means condensing, not cutting — knowledge only compounds if it survives. Delete an entry only when it's clearly superseded or shipped; when unsure whether something still matters, keep it or ask — never reason it away on a hunch. Propose the distill as its own item in the proposal (the wrap commit makes every distill fully recoverable).

Promote hard-won rules down the stack A gotcha with a greppable trigger and a high violation cost is a hook candidate (the migration-wipe guard is the model) — suggest the promotion; the user decides. And once a rule IS a deterministic guard, trim its prose copies (CLAUDE.md, gotchas, old entries) to one line pointing at the hook: mechanized rules don't need re-reading every session, and lingering prose keeps old incidents alive in every conversation.

Then ask the session one question: what did it teach — learnings, lessons, preferences, frictions? (Surprises, corrections, contradictions with docs, deployed-but-unverified risks all count.) Route what passes the would-a-future-session-act-differently test to its home — gotcha, DECISIONS, sprint TO-DO, global profile. Let one-off friction go unrecorded: this is a harvest, not an incident log.

4 — Propose once, apply once

Present a compact proposal in one message: any genuinely open "needs your call" forks (AskUserQuestion, with recommendations — say "none" if none) together with one line per file describing what you'll write. Not full drafts — one scannable list the user can veto items from. Flag in the line when a change rewrites a pre-existing claim rather than adding ("ARCHITECTURE: +1 gotcha, rewrites stale model-ID line"). Answering the forks — or a bare go-ahead — is the single confirmation; apply immediately, honoring any vetoes. A session with nothing worth saving: say so in one line and stop — no proposal, no commit.

On that confirmation: apply all writes in parallel, including a session note at the top of .claude/.last-session.md — this chat's only, in a guide's voice, ≤5 lines: a header ## YYYY-MM-DD HH:MM · <sprint name or freebuild topic> (stamp from the environment), then Worked on (what shipped, one line), Still open (unverified, undeployed, where iteration stalled), Next. Not a log of everything — what a fresh chat needs to feel oriented. Prepend, never rewrite: re-read the file right before writing, leave other chats' notes exactly as they are (parallel chats each leave their own), and drop notes older than 7 days. The hook shows the last 36 hours of notes; sprint files hold each thread's detail. It's the only trace a no-sprint Freebuild session leaves. Delete .claude/.session-snapshot.md (now reconciled). Archive any fully-checked sprint (sprints/archive/<sprint-NNN>-<slug>.md, next sequential NNN), then make the checkpoint commit (docs(wrap): <summary>). Your own session's code changes get committed by path alongside it — or explicitly deferred with a reason ("leaving X uncommitted until the visual pass"). Never left silently floating in a shared tree for another chat to sweep into an unrelated commit. Offer a push with it — a checkpoint that only lives on this laptop isn't a backup — but push only on their yes.

Then one final summary: the commit hash, one line per file changed, and the carry-forward for next session. No second recap.

On a project's first wrap (no prior docs(wrap): commit): offer the background routine once — Ship Captain + Ship Spotter, ../roadmap/references/background-routine.md, set up via /schedule. This is their first time learning about this, so congratulate them on running through their first vibeflow flow of start, build, wrap, explain to them in a few sentences how this compounds knowledge and memory over time, and then offer the Ship Captain + Ship Spotter with brief explanations of them as agentic scheduled tasks they can run.

5 — If a sprint was archived

If the sprint ran on its own branch and its verification is done, offer the merge back to main first (squash is a fine default) — an archived sprint shouldn't leave a stranded branch. If it ran in its own worktree, offer git worktree remove <path> after the merge too (Claude-managed worktrees clean themselves up); anything with a deploy step ships from main after this merge, not from the worktree.

Offer once: plan the next sprint now (read ../start/SKILL.md, run its planning), or defer — "next session, /start picks up from here."