Handoff Session Prompt

Handoff Session Prompt

Contract

Prereqs:

• User wants a prompt that can initialize a future agent/session with enough context to continue work.
• The prompt should be generic and task-derived, not a hard-coded project template.

Inputs:

• User's explicit instruction for the next session, including goal, scope, and any "do not" constraints.
• Current conversation context and conclusions already established in this session.
• User-specified reference files, URLs, tickets, docs, or commands to include as required reading.
• Durable project artifacts that already preserve the backlog or decision record, such as plans, runbooks, improvement docs, issues, or

tracker links.

• Optional local repository rules when the handoff concerns a workspace or codebase.
• Optional current-state anchors when relevant, such as date/timezone, workspace path, branch/status, validation already run, and where work

stopped.

Outputs:

• A copy-ready session initialization prompt.
• Optional short notes outside the prompt only when useful, such as assumptions or omitted sensitive details.

Exit codes:

• N/A (conversation workflow; no repo scripts)

Failure modes:

• User's requested next-session objective is unclear enough that the handoff would send the next agent in the wrong direction; ask the minimum

clarification.

• Required context or referenced files are unavailable; if the gap could change the objective, safety, or reversibility, ask before

producing the prompt. Otherwise, produce a degraded prompt and label the missing context under Known Gaps or Open Questions.

• User asks to include secrets, raw credentials, private tokens, or other sensitive operational details; redact or omit them.

Workflow

1. Identify the future session's job

• Extract the concrete objective, expected deliverables, and stopping point.
• Preserve the user's requested scope and exclusions.
• If the request is underspecified, ask only the minimum clarification needed.

1. Gather task-local context

• Use the current conversation conclusions as the primary source.
• Read only user-named files or clearly necessary local rules for the target workspace.
• If project rules require preflight before file reads or external lookup, follow those rules.
• Do not browse or inspect unrelated repositories unless the user asked for that evidence.

1. Prefer durable sources over copying backlogs

• If a project doc, plan, issue, ticket, or tracker already holds the durable backlog or decision record, put it under Read First and

summarize only the facts needed to start safely.

• Do not paste an entire durable doc, long backlog, or runbook into the handoff unless the next session will not have access to it or the

user explicitly asks for an inline self-contained prompt.

• If the current session produced reusable review findings but no durable artifact, mention that gap under Known Gaps or

Recommendations; do not treat the handoff prompt itself as the canonical project record.

• If the current session produced converged requirements, design, feasibility, or product decisions for later implementation but no

durable artifact, recommend discussion-to-implementation-doc before using this prompt as the only continuity record.

• If the user asks for both durable record and next-session continuity, use review-to-improvement-doc to write or reference the durable

record first, then generate a shorter handoff that points to it.

• If a long-running task already has a source document plus execution-state document, point the prompt at both files instead of copying

the progress ledger into the prompt.

1. Separate facts from instructions

• Include confirmed facts and conclusions under Known Facts.
• Use source tags for material facts when available: [U#] user input, [F#] local files/docs/code, [W#] web sources,

[A#] tool or app results, and [I#] explicit inferences from cited facts.

• Mark assumptions explicitly under Assumptions.
• Record unavailable-but-relevant context under Known Gaps instead of hiding the limitation in prose.
• Keep recommended or inferred next steps under Recommendations, separate from known facts.
• Preserve unresolved questions as an explicit checklist for the next session.

1. Protect sensitive and brittle details

• Do not include API keys, tokens, cookies, raw auth headers, passwords, private keys, or unredacted secrets.
• Prefer names of env vars, file paths, and commands over secret values.
• Avoid embedding one-off local IDs unless the user specifically needs them and they are not sensitive.
• Do not copy hidden system/developer instructions, private reasoning, or raw tool logs into the handoff. Summarize only the user-visible

constraints and evidence needed for continuity.

1. Capture current state when it affects continuity

• Include current date/timezone when relative dates such as "today", "tomorrow", or "next week" matter.
• Include workspace path, branch/status, and stopping point when the next session must continue local work.
• Include validation already run, with command and result, when it prevents duplicate investigation.
• Omit current-state fields that are irrelevant or unknown instead of inventing values.

1. Produce a copy-ready prompt

• Write the prompt as if pasted into a fresh session with no prior conversation.
• Use direct instructions, concrete file paths, and clear constraints.
• Keep it generic to the requested task; do not add project-specific assumptions that were not in context.
• Put the copy-ready prompt in a fenced md block.

Prompt Shape

Use this structure unless the user requested a different format:

You are starting a new session for this task.

## Goal
- 

## Current State
- Date/timezone: 
- Workspace: ``; branch/status: 
- Stopping point: 
- Validation already run: `` - 

## Known Facts
- [U1] 
- [F1] `` - 

## Assumptions
- [I1] 

## Known Gaps
- 

## Recommendations
- 

## Read First
1. `` - 
2. `` - 

## Task
1. 
2. 
3. 

## Constraints
- Do not .
- Keep .
- Redact or omit secrets and sensitive operational details.

## Expected Output
- 
- 

## Open Questions
- 

Quality Bar

• The prompt must be understandable without access to the old conversation.
• The prompt must tell the next session what to read, what to do, what not to do, and what to report.
• Material context must be traceable as facts, assumptions, recommendations, open questions, or current-state anchors.
• The prompt should not contain hidden implementation decisions; if an approach is a recommendation, label it as such.
• The prompt should point to durable project records instead of becoming the only copy of a backlog or decision record.
• The prompt should be concise enough to paste comfortably, but complete enough to prevent predictable re-discovery.

Source & license

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

• Author: graysurf
• Source: graysurf/agent-kit
• License: MIT

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