handoff
- Repo stars 31
- Author repo dotfiles
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @hta218 · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Run these commands in parallel to understand the current state: `git status` — see all tracked/untracked files and staging state `git diff` — see unstaged changes `git log --oneline -10` — recent commits to understand work trajectory `git branch --show-current` — current branch name
List all folders in `.specs/` Match the current branch name, modified files, or recent commit messages to spec folder names Use `AskUserQuestion` to confirm the save location with the user: If a likely match is found, suggest it as the recommended option Always include other spec folders as alternatives
Work Completed — analyze recent git commits, review completed todos, identify patterns in changes made Work In Progress — active todo items, uncommitted changes, files currently being modified Work Remaining — pending todo items, blockers, dependencies, priorities Context — branch strategy, important decisions, known issues, relevant file paths with line numbers
Save the file as `handoff--{YYYY-MM-DD-HH-mm}--{brief-work-summary}.md` in the confirmed location. Use `date +"%Y-%m-%d-%H-%M"` to get the correct local timestamp `{brief-work-summary}` is a short kebab-case description of the work (e.g., `add-cart-api`, `fix-auth-redirect`, `refactor-review-section`) Use this structure:
After saving, display: The full file path where the handoff was saved A brief summary of the current state
Generate a comprehensive handoff document capturing the current state of work for seamless continuation by another agent or developer.
## Workflow
### Step 1: Gather Context
Run these commands in parallel to understand the current state:
- `git status` — see all tracked/untracked files and staging state
- `git diff` — see unstaged changes
- `git log --oneline -10` — recent commits to understand work trajectory
- `git branch --show-current` — current branch name
- `git remote get-url origin` — repository name (if available)
Also check for active todos in the todo system.
### Step 2: Confirm Save Location
1. List all folders in `.specs/`
2. Match the current branch name, modified files, or recent commit messages to spec folder names
3. Use `AskUserQuestion` to confirm the save location with the user:
- If a likely match is found, suggest it as the recommended option
- Always include other spec folders as alternatives
- Always allow the user to specify a custom path
4. Only proceed after the user confirms the location
### Step 3: Analyze Work State
1. **Work Completed** — analyze recent git commits, review completed todos, identify patterns in changes made
2. **Work In Progress** — active todo items, uncommitted changes, files currently being modified
3. **Work Remaining** — pending todo items, blockers, dependencies, priorities
4. **Context** — branch strategy, important decisions, known issues, relevant file paths with line numbers
### Step 4: Write the Handoff Document
Save the file as `handoff--{YYYY-MM-DD-HH-mm}--{brief-work-summary}.md` in the confirmed location.
- Use `date +"%Y-%m-%d-%H-%M"` to get the correct local timestamp
- `{brief-work-summary}` is a short kebab-case description of the work (e.g., `add-cart-api`, `fix-auth-redirect`, `refactor-review-section`)
Use this structure:
```markdown
# Handoff Context - {Date Time}
## Project
- Repository: {repo name if available}
- Branch: {current branch}
- Spec: {spec folder path if found}
- Last Updated: {timestamp}
## Current Status
### What's Been Done
{List completed work, recent commits, changes made}
### What's In Progress
{Current todo items, ongoing work}
### What's Next
{Pending tasks, blockers, priorities}
## Technical Context
### Modified Files
{List files changed with brief description}
### Key Decisions
{Important architectural or implementation decisions}
### Known Issues
{Bugs, blockers, or things to watch out for}
## Dependencies & Prerequisites
{External dependencies, required setup, environment notes}
## Additional Notes
{Any other relevant context for continuation}
```
### Step 5: Report
After saving, display:
- The full file path where the handoff was saved
- A brief summary of the current state
## User Arguments
$ARGUMENTS
## Important Notes
- Be concise but comprehensive — focus on actionable information
- Include specific file paths with line numbers where relevant
- Do NOT commit the handoff file automatically
- If the user provided notes via arguments, include them in the "Additional Notes" section
Listed in source order.
sections -> Workflow → Step 1: Gather Context → Step 2: Confirm Save Location → Step 3: Analyze Work State → Step 4: Write the Handoff Document → Step 5: Report
terms -> Work Completed · Work In Progress · Work Remaining · Context
files/cmd -> git status · git diff · git log --oneline -10 · git branch --show-current · git remote get-url origin · .specs/ · AskUserQuestion · handoff--{YYYY-MM-DD-HH-mm}--{brief-work-summary}.md
body sha256 -> 4f1a55bef1ca
Step 1: Gather Context
Run these commands in parallel to understand the current state:
git status— see all tracked/untracked files and staging stategit diff— see unstaged changesgit log --oneline -10— recent commits to understand work trajectorygit branch --show-current— current branch nameStep 2: Confirm Save Location
List all folders in
.specs/Match the current branch name, modified files, or recent commit messages to spec folder names UseAskUserQuestionto confirm the save location with the user: If a likely match is found, suggest it as the recommended option Always include other spec folders as alternativesStep 3: Analyze Work State
Work Completed — analyze recent git commits, review completed todos, identify patterns in changes made Work In Progress — active todo items, uncommitted changes, files currently being modified Work Remaining — pending todo items, blockers, dependencies, priorities Context — branch strategy, important decisions, known issues, relevant file paths with line numbers
Step 4: Write the Handoff Document
Save the file as
handoff--{YYYY-MM-DD-HH-mm}--{brief-work-summary}.mdin the confirmed location. Usedate +"%Y-%m-%d-%H-%M"to get the correct local timestamp{brief-work-summary}is a short kebab-case description of the work (e.g.,add-cart-api,fix-auth-redirect,refactor-review-section) Use this structure:Step 5: Report
After saving, display: The full file path where the handoff was saved A brief summary of the current state