Create Handoff

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Usage

/create-handoff <name>

Create handoff for: $ARGUMENTS

Arguments

$ARGUMENTS - Handoff Context (optional)

Specify handoff details:

• Ticket number: "ENG-1234" - Creates handoff for specific ticket
• General work: "general" - Creates handoff without ticket association
• With description: "ENG-1234 authentication improvements"
• No arguments: Uses current context and prompts for ticket number if applicable

Default Behavior

If no arguments:

• Uses current session context
• Prompts for ticket number or uses "general"
• Generates timestamp-based filename
• Creates comprehensive handoff document with:
  • Task status (completed, in progress, planned)
  • Recent changes with file:line references
  • Learnings and important discoveries
  • Artifacts and documentation
  • Action items for next session
  • Other relevant notes
• Syncs to thoughts directory
• Provides resume command for next session

Create Handoff

You are tasked with writing a handoff document to hand off your work to another agent in a new session. You will create a handoff document that is thorough, but also concise. The goal is to compact and summarize your context without losing any of the key details of what you're working on.

Process

1. Filepath & Metadata

Use the following information to understand how to create your document: - create your file under thoughts/shared/handoffs/ENG-XXXX/YYYY-MM-DD_HH-MM-SS_ENG-ZZZZ_description.md, where: - YYYY-MM-DD is today's date - HH-MM-SS is the hours, minutes and seconds based on the current time, in 24-hour format (i.e. use 13:00 for 1:00 pm) - ENG-XXXX is the ticket number (replace with general if no ticket) - ENG-ZZZZ is the ticket number (omit if no ticket) - description is a brief kebab-case description - Run the scripts/spec_metadata.sh script to generate all relevant metadata - Examples: - With ticket: 2025-01-08_13-55-22_ENG-2166_create-context-compaction.md - Without ticket: 2025-01-08_13-55-22_create-context-compaction.md

2. Handoff writing.

using the above conventions, write your document. use the defined filepath, and the following YAML frontmatter pattern. Use the metadata gathered in step 1, Structure the document with YAML frontmatter followed by content:

Use the following template structure:

---
date: [Current date and time with timezone in ISO format]
researcher: [Researcher name from thoughts status]
git_commit: [Current commit hash]
branch: [Current branch name]
repository: [Repository name]
topic: "[Feature/Task Name] Implementation Strategy"
tags: [implementation, strategy, relevant-component-names]
status: complete
last_updated: [Current date in YYYY-MM-DD format]
last_updated_by: [Researcher name]
type: implementation_strategy
---

# Handoff: ENG-XXXX {very concise description}

## Task(s)
{description of the task(s) that you were working on, along with the status of each (completed, work in progress, planned/discussed). If you are working on an implementation plan, make sure to call out which phase you are on. Make sure to reference the plan document and/or research document(s) you are working from that were provided to you at the beginning of the session, if applicable.}

## Critical References
{List any critical specification documents, architectural decisions, or design docs that must be followed. Include only 2-3 most important file paths. Leave blank if none.}

## Recent changes
{describe recent changes made to the codebase that you made in line:file syntax}

## Learnings
{describe important things that you learned - e.g. patterns, root causes of bugs, or other important pieces of information someone that is picking up your work after you should know. consider listing explicit file paths.}

## Artifacts
{ an exhaustive list of artifacts you produced or updated as filepaths and/or file:line references - e.g. paths to feature documents, implementation plans, etc that should be read in order to resume your work.}

## Action Items & Next Steps
{ a list of action items and next steps for the next agent to accomplish based on your tasks and their statuses}

## Other Notes
{ other notes, references, or useful information - e.g. where relevant sections of the codebase are, where relevant documents are, or other important things you leanrned that you want to pass on but that don't fall into the above categories}

---

3. Approve and Sync

Run humanlayer thoughts sync to save the document.

Once this is completed, you should respond to the user with the template between <template_response></template_response> XML tags. do NOT include the tags in your response.

<template_response> Handoff created and synced! You can resume from this handoff in a new session with the following command:

/resume-handoff path/to/handoff.md

</template_response>

for example (between <example_response></example_response> XML tags - do NOT include these tags in your actual response to the user)

<example_response> Handoff created and synced! You can resume from this handoff in a new session with the following command:

/resume-handoff thoughts/shared/handoffs/ENG-2166/2025-01-08_13-44-55_ENG-2166_create-context-compaction.md

</example_response>

---

##. Additional Notes & Instructions

• more information, not less. This is a guideline that defines the minimum of what a handoff should be. Always feel free to include more information if necessary.
• be thorough and precise. include both top-level objectives, and lower-level details as necessary.
• avoid excessive code snippets. While a brief snippet to describe some key change is important, avoid large code blocks or diffs; do not include one unless it's necessary (e.g. pertains to an error you're debugging). Prefer using /path/to/file.ext:line references that an agent can follow later when it's ready, e.g. packages/dashboard/src/app/dashboard/page.tsx:12-24

Required Tools

Tool	Purpose	Required
Bash	Get git commit hash, branch, run scripts	Yes
Write	Create handoff document	Yes
Read	Read spec_metadata.sh output, context	Optional

Script Dependency:

• scripts/spec_metadata.sh - Generate handoff metadata

Output Validation

Before marking complete, verify handoff contains:

• YAML frontmatter with date, researcher, git_commit, branch
• Task section with status (completed/in progress/planned)
• Critical References (if applicable)
• Recent changes with file:line references
• Learnings section
• Artifacts list (exhaustive file paths)
• Action items for next session
• Resume command provided

---

Action Policy

<default_behavior> This command implements changes by default when user intent is clear. Proceeds with:

• Code generation/modification
• File creation/updates
• Configuration changes
• Git operations (if applicable)

Provides concise progress updates during execution. </default_behavior>

After execution, verify: - Files created/modified as intended - Code compiles/tests pass (if applicable) - Git changes committed (if applicable) - Next recommended step provided

Success Output

When handoff creation completes:

✅ COMMAND COMPLETE: /create-handoff
Handoff: <handoff-path>
Ticket: <ENG-XXXX|general>
Tasks: N documented
Artifacts: N listed
Next Steps: N action items
Resume: /resume-handoff <path>

Completion Checklist

Before marking complete:

• Handoff file created
• Tasks documented
• Recent changes listed
• Learnings captured
• Action items defined
• Synced to thoughts

Failure Indicators

This command has FAILED if:

• ❌ No handoff file created
• ❌ Missing task documentation
• ❌ No resume command provided
• ❌ Sync failed

When NOT to Use

Do NOT use when:

• Session just started (nothing to hand off)
• Simple task completed (no continuation needed)
• No meaningful context to preserve

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Excessive code snippets	Bloated handoff	Use file:line references
Vague tasks	Unclear next steps	Be specific and precise
Skip learnings	Lost knowledge	Document discoveries

Principles

This command embodies:

• #3 Complete Execution - Full handoff workflow
• #6 Clear, Understandable - Structured documentation
• #9 Based on Facts - Specific file references

Full Standard: CODITECT-STANDARD-AUTOMATION.md