Resume Pack — Format Specification

Version: 1.0 Status: Stable Filename convention: <session-title>.resumepack.md (recommended; plain .md is also valid)

A Resume Pack is a portable, plain-markdown handoff document that lets one AI tool pick up project context that another AI tool — or a human — left off with.

The format is intentionally minimal: standard CommonMark, no GFM-only syntax, no proprietary extensions. Any markdown renderer can render a Resume Pack. Any LLM that accepts pasted text can ingest one.

This document is the format contract. The canonical reference implementations are:

• Generator prompt: lib/ai/prompts.ts — the prompt that drives the LLM (Gemini, Grok) to produce conforming Packs.
• Reference output: docs/RESUME_PACK_BASELINE_2026_05_27.md — a real Pack scored 4.83 / 5 against the eval rubric.
• Renderer: components/pack-renderer.tsx — styled React renderer.

Where any of these diverge from this document, the document is the source of truth.

File conventions

The .resumepack infix is a hint to file browsers, integration code, and AI tools that the contents follow this spec. The file remains valid .md and renders correctly in any markdown viewer.

Required structure

A Resume Pack is a single markdown document with:

1. Exactly one top-level heading (H1): # Resume Pack: <Project Name>.
2. A sequence of H2 sections, in the order specified below.

The skeleton:

# Resume Pack: <Project Name>

## Project Overview
* **Project:** <name>
* **Project Goal:** <goal>
* **Session:** <session title>
* **Session Goal:** <session goal>

## Pinned Decisions & Constraints      (optional)
* <bullet>

## What Was Done
* <bullet>

## Open Questions / Blockers
* <bullet, or empty-state fallback>

## Next Recommended Actions
1. <numbered, ≥ 1>

## Continue Prompt
<plain text — see "The Continue Prompt contract" below>

Section reference

Required sections

The Project Overview heading may also be written as ## Project — both forms are valid and equivalent.

Optional sections

Section ordering

Sections appear in the order shown in the skeleton. Inserting other sections between them is non-conforming. Generators must not invent sections.

The Continue Prompt contract

The Continue Prompt is the most important contract in this spec. Purpose: a receiving AI should be able to read this section alone and resume work, even if everything above it gets summarised away.

Required structure, in order:

1. Opening line — Continuing work on <Project Name>.
2. Context: block — 2 to 4 bullets covering project state and in-force constraints. Do not re-list everything from What Was Done — reference it briefly if needed.

   **Context:**
   - <bullet>
   - <bullet>
   

3. Goal line — **Current goal:** <one sentence>
4. Ask line — **Please help me with:** <topmost next action, verbatim from Next Recommended Actions>
5. Important: block — three short bullets:

   **Important:**
   - Use only the context above; do not invent facts I haven't given you.
   - Ask clarifying questions only if you genuinely can't proceed.
   - Stay focused on the goal; defer suggestions outside its scope.
   

   Generators may customise the constraints but must not omit the anti-hallucination directive (the first bullet) — it is what makes the Continue Prompt safe to paste into any LLM without prompt-engineering on the receiver.

Each labelled block is preceded by a blank line so the bold label renders as a paragraph start.

Do not wrap the Continue Prompt in a fenced code block. Nested fences (a ``` inside another ```) break in several common markdown renderers (Slack, Discord, some IDE chat panels). The whole section is plain markdown — bold labels and bulleted lists.

Portability rules

Image / attachment convention

Bullets may carry image attachments. Each image is rendered on an indented continuation line under the parent bullet:

- The Resume Pack rendering issue we hit earlier.
  ![Screenshot of duplicate H1 elements](https://hpath.dev/p/abc.png)
  Screenshot transcript: A markdown preview showing two h1 elements stacked.

Rules:

• Indent continuation lines with exactly two spaces — keeps the image inside the parent list item across CommonMark, GFM, and Slack-flavoured renderers.
• Use standard markdown image syntax: ![alt text](url).
• The alt text must describe the image; never empty.
• If a vision model transcribed the image, emit a third indented line: Screenshot transcript: <plain text>. This lets text-only LLMs ingest the content even when they cannot fetch the URL.

Variants

Two variants are supported. Variant choice does not change the section structure — only per-section content density.

Block-level rules

These govern how a generator classifies and places input blocks. They are mandatory for conformance — getting them wrong leads to packs that look correct but mis-represent project state.

• Blocks tagged done go in What Was Done regardless of their input type. A "done" Next Action is reference, not work to redo.
• Pinned blocks must appear somewhere in the pack — they encode the decisions the rest of the work depends on.
• Open debug-block items go in Open Questions / Blockers. Closed ones go in What Was Done.
• Open next-action items go in Next Recommended Actions, exactly as many as exist — no padding. If zero open next-actions exist, derive exactly one verifiable verb-led action from the session goal.
• Quick-note, decision, project-fact, and AI-paste blocks must never be promoted into Next Recommended Actions.

Faithfulness rules

The most important rules in this spec. Everything above is structure; these are about truth.

• Use only the supplied context. Do not invent file paths, decisions, completed work, blockers, constraints, or technical details.
• If a section has no real content, render the documented empty-state fallback — never pad with plausible-sounding fabrication.
• When paraphrasing a block, keep technical identifiers (file paths, env var names, function names, error strings, version numbers) verbatim. These break if mangled.
• Do not expand product names beyond what the block said. If a block says "Vercel", do not silently expand it to "Vercel Functions" or "Vercel Edge".
• Do not introduce new headings, file paths, or process names that aren't in any block.

Versioning

This spec is version 1.0.

• Additive changes (new optional section, new attachment type) bump the minor version: 1.0 → 1.1.
• Breaking changes (renamed sections, reordered sections, changed Continue Prompt contract) bump the major version: 1.0 → 2.0 and ship with a documented migration path.

The current version is the value at the top of this document.

Reference implementations

Both generators conform to this spec. The LLM-driven path produces richer, eval-graded Packs; the deterministic fallback produces a structurally-identical Pack from the same inputs without an LLM call, used for the workspace live preview, the marketing demo, and the Mock provider.

Third-party readers and generators are welcome. There is no certification process, no fee, and no "official" implementation list. If it conforms to this document, it conforms.

License

This specification is released into the public domain under CC0 1.0. Use it, fork it, build on it, ship it in your own product without attribution. The format wins when more tools speak it.

The HandoffPath implementation of the format is licensed separately; see the repository LICENSE.