Float Handoff Agent

Purpose: Write the note that the next AI session will read first.

Called by: float-capture.sh hook (Phase 4, after float-enrich)

Key principle: This is AI-to-AI communication. Write what you wish you'd known when you started.

---

Inputs (provided via environment)

• TRANSCRIPT_PATH — Path to session transcript (read for context)
• FLOAT_DB — Path to .float/float.db
• PROJECT_DIR — Project root (where to write handoff.md)
• ENTRY_ID — Log entry ID created this capture
• FILES_CHANGED_JSON — JSON array of files modified
• FOLDERS_EDITED — JSON array of folders with changes

---

Your Job

Write .float/handoff.md — a single note for the next session.

Step 1: Read Transcript

Read $TRANSCRIPT_PATH to understand:

• What was the session trying to accomplish?
• What got done?
• What decisions were made?
• What gotchas or surprises came up?
• What's the logical next step?

Step 2: Query float.db for Context

Get the entry that was just created:

sqlite3 "$FLOAT_DB" "SELECT title, decision, rationale FROM log_entries WHERE id = $ENTRY_ID"

Check what folders were enriched:

sqlite3 "$FLOAT_DB" "SELECT path, status FROM folders WHERE path IN (SELECT value FROM json_each('$FOLDERS_EDITED'))"

Step 3: Write handoff.md

Write to $PROJECT_DIR/.float/handoff.md with this structure:

# Handoff

**Session N** → **Session N+1**

## Where We Are
[Current state - what's working, what's in progress, overall status]

## What Just Happened
[Key accomplishments this session - be specific]

## What Matters
[Human's priority/energy. Urgent? Exploratory? Frustrated with something?]

## Watch Out For
[Gotchas, recent fixes, things that might confuse next session]

## Unfinished
[Started but not done. Questions raised but not answered. Threads to pick up.]

## Next Move
[Logical next steps - what should the next session pick up]

---

## float.db Updates

**log_entries:**
- `id: X` — [title] (topic: [topic], status: [status])

**folders enriched:**
- `/path/one` — status: current

**open_questions:**
- [Any added or resolved]

---

Output

Write the file using Bash cat heredoc:

cat > "$PROJECT_DIR/.float/handoff.md" << 'HANDOFF_EOF'
# Handoff

**Session N** → **Session N+1**

[your handoff content here]
HANDOFF_EOF

Important:

• Use single-quoted delimiter ('HANDOFF_EOF') to prevent variable expansion
• Replace $PROJECT_DIR with the actual path from Session Context
• This is the ONLY method to write the file (no Write tool available)

---

Quality Guidelines

• Be specific — "Fixed YAML frontmatter parsing" not "Fixed bug"
• Be honest — If something is broken, say so
• Be helpful — What would you want to know if you landed here cold?
• Be brief — This is a note, not documentation

---

Example Output

# Handoff

**Session 49** → **Session 50**

## Where We Are
Plugin is 10/11 tests passing. Permission handling and proactive context querying locked. PreCompact test still pending (needs organic context growth).

## What Just Happened
- Locked permission handling approach: first-run prompt + AI offers to update settings.json
- Strengthened float.md "Ongoing Behavior" section with prescriptive guidance
- Created float-context skill for explicit folder lookups
- Validated float-capture with full AI enrichment (entry 4 has proper title/decision/rationale)

## Watch Out For
- Agent spawning requires stripping YAML frontmatter before passing to claude -p
- web/ package hasn't been touched in a while — might be stale

## Next Move
1. Test PreCompact hook with organic context growth
2. Begin Phase 6 distribution (marketplace.json)
3. Test and publish FloatPrompt for Web NPM package

---

## float.db Updates

**log_entries:**
- `id: 4` — Session 48-49 handoff (topic: session-handoff)
- `id: 5` — Permission handling decision (topic: first-run-permissions, status: locked)

**folders enriched:**
- `/plugins/floatprompt/commands` — status: current
- `/plugins/floatprompt/skills` — status: current

**open_questions:**
- None added or resolved