opencode-bonfire 1.2.1 → 1.3.0

package/files/command/bonfire-end.md

@@ -8,14 +8,35 @@ description: End session - update context and commit changes
 
 Run `git rev-parse --show-toplevel` to locate the repository root.
 
-## Step 2: Review Session Work
+## Step 2: Check for Handoff
+
+Check if `<git-root>/.bonfire/handoff/handed-off` exists.
+
+**If it exists**: This session was handed off to a new session. Warn the user:
+
+> "This session was previously handed off. The new session may have already updated `index.md`.
+> Running `/bonfire-end` here could cause conflicts or overwrite the new session's changes."
+
+Ask the user:
+1. "Proceed anyway" - Continue with /bonfire-end (user takes responsibility)
+2. "Skip index.md update" - Only commit changes, don't update context
+3. "Cancel" - Abort /bonfire-end
+
+If user chooses to proceed or skip, delete the marker file after completion:
+```bash
+rm <git-root>/.bonfire/handoff/handed-off
+```
+
+**If marker doesn't exist**: Continue normally.
+
+## Step 3: Review Session Work
 
 Review what was accomplished this session by examining:
 - Recent git commits
 - Files changed
 - Conversation context
 
-## Step 3: Update Session Context
+## Step 4: Update Session Context
 
 Update `<git-root>/.bonfire/index.md`:
 
@@ -29,7 +50,7 @@ Update `<git-root>/.bonfire/index.md`:
 
 3. Update "Current State" to reflect new status
 
-## Step 4: Update Codemap
+## Step 5: Update Codemap
 
 Update the "Codemap" section in `index.md` with files referenced this session:
 
@@ -68,7 +89,7 @@ Example:
 - `.bonfire/specs/codemap-feature.md` - Feature specification
 ```
 
-## Step 5: Commit Changes (if tracked)
+## Step 6: Commit Changes (if tracked)
 
 Read `<git-root>/.bonfire/config.json` to check `gitStrategy`.
 
@@ -91,7 +112,7 @@ Read `<git-root>/.bonfire/config.json` to check `gitStrategy`.
 
 If the commit fails due to hooks, help resolve the issue (but never bypass hooks with `--no-verify`).
 
-## Step 6: Confirm
+## Step 7: Confirm
 
 Summarize:
 - What was documented

package/files/command/bonfire-handoff.md

@@ -0,0 +1,168 @@
+---
+description: Hand off session to new Claude instance when approaching context limits
+---
+
+# Session Handoff
+
+Hand off the current session to a fresh Claude instance, preserving work state.
+
+## Step 1: Verify Environment
+
+Check if running inside tmux:
+
+```bash
+[ -n "$TMUX" ] && echo "tmux: yes" || echo "tmux: no"
+```
+
+**If not in tmux**: Still generate handoff context, then provide manual instructions:
+
+1. Continue with Steps 2-8 (skip Step 9)
+2. Tell the user:
+
+> "Automatic session spawning requires tmux. I've saved the handoff context.
+>
+> **To continue manually:**
+> 1. Open a new terminal in this directory
+> 2. Run: `opencode --append-system-prompt "$(cat .bonfire/handoff/context.md)"`
+> 3. In the new session, run `/bonfire-start` to load full history
+>
+> The handoff context is saved at `.bonfire/handoff/context.md`"
+
+## Step 2: Find Git Root
+
+```bash
+git rev-parse --show-toplevel
+```
+
+## Step 3: Verify Bonfire Exists
+
+Check if `<git-root>/.bonfire/index.md` exists.
+
+**If not**: Abort with message:
+> "No .bonfire/ directory found. Run `/bonfire-start` first to initialize session tracking."
+
+## Step 4: Check for Uncommitted Changes
+
+```bash
+git status --porcelain
+```
+
+**If uncommitted changes exist**: Warn the user:
+> "Note: You have uncommitted changes. The new session will see them. Consider committing or stashing before handoff."
+
+Ask if they want to proceed anyway.
+
+## Step 5: Update index.md
+
+Read `<git-root>/.bonfire/index.md` and update the current session entry:
+
+1. **Add HANDOFF marker** to session title:
+   ```markdown
+   ### Session N - DATE (HANDOFF)
+   ```
+
+2. **Add "In Progress at Handoff"** section:
+   ```markdown
+   **In Progress at Handoff**:
+   - [What was actively being worked on]
+   - [Current state of that work]
+   ```
+
+3. **Add handoff metadata**:
+   ```markdown
+   **Handoff Reason**: Approaching context limit
+   **Continued In**: Next session
+   ```
+
+4. **Update "Next Session Priorities"** with the immediate work that needs to continue.
+
+5. **Update Codemap** "This Session's Key Files" with files relevant to current work.
+
+## Step 6: Generate Handoff Context
+
+Create `<git-root>/.bonfire/handoff/` directory if it doesn't exist.
+
+Write `<git-root>/.bonfire/handoff/context.md` with minimal context (~1K tokens max):
+
+```markdown
+# Session Handoff Context
+
+**Date**: [CURRENT_DATE]
+**Branch**: [current git branch]
+**Repository**: [repo name from package.json or directory name]
+
+## Current Task
+
+[1-2 sentences describing what was actively being worked on when handoff triggered]
+
+## Immediate Next Steps
+
+1. [First priority - most urgent continuation]
+2. [Second priority]
+3. [Third priority if applicable]
+
+## Key Context
+
+- [Critical decision or constraint affecting the work]
+- [Important file or component being modified]
+- [Any blockers or considerations for new session]
+
+## Uncommitted Changes
+
+[List modified files from git status, or "None" if clean]
+
+---
+
+**Instructions for new session**: Run `/bonfire-start` to load full session context from `.bonfire/index.md`.
+```
+
+**Size guidance**: Keep this file under 1000 tokens (~150 words, ~750 characters). Focus on what's needed to continue immediately, not history. If the content exceeds this, trim the "Key Context" section to essential items only.
+
+## Step 7: Mark Session as Handed Off
+
+Create a marker file to prevent context corruption:
+
+```bash
+echo "$(date -Iseconds)" > <git-root>/.bonfire/handoff/handed-off
+```
+
+This marker tells other commands (like `/bonfire-end`) that this session has been handed off and should not update `index.md` again.
+
+## Step 8: Add handoff/ to .gitignore
+
+Read `<git-root>/.bonfire/.gitignore` and add `handoff/` if not present:
+
+```
+handoff/
+```
+
+Handoff context is transient and should not be committed.
+
+## Step 9: Spawn New Session
+
+Run the tmux command to spawn a new pane (horizontal split):
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+CONTEXT="$(cat "$REPO_ROOT/.bonfire/handoff/context.md")"
+tmux split-window -h -c "$REPO_ROOT" \
+  "opencode --append-system-prompt '$CONTEXT' 'Continuing from session handoff. Please run /bonfire-start to load the full session context.'"
+```
+
+**Verify spawn succeeded**: Check that the new pane exists. If tmux fails (e.g., terminal too small), warn the user and provide manual instructions from Step 1.
+
+This creates a new pane to the right of the current pane, keeping both sessions visible during handoff.
+
+## Step 10: Confirm Handoff
+
+Tell the user:
+
+> **Handoff complete.**
+>
+> - Session state saved to `.bonfire/index.md`
+> - Handoff context written to `.bonfire/handoff/context.md`
+> - New session spawned in adjacent pane
+>
+> The new session will run `/bonfire-start` to load your full session history.
+>
+> You can close this pane when ready, or keep both visible during transition.

package/files/command/bonfire-start.md

@@ -199,6 +199,28 @@ Read `.bonfire/index.md` for current project state, recent work, and priorities.
 Read `.bonfire/index.md` for current project state, recent work, and priorities.
 ```
 
+## Step 3.5: Check for Handoff Continuation
+
+Check if `<git-root>/.bonfire/handoff/context.md` exists.
+
+**If it exists**: This session is continuing from a handoff. Acknowledge it:
+
+> "Detected handoff context from previous session. Loading continuation state..."
+
+Read the handoff context file and note:
+- What task was in progress
+- Immediate next steps
+- Key context
+
+Then clean up the handoff files:
+```bash
+rm -rf <git-root>/.bonfire/handoff/
+```
+
+The handoff context provides quick orientation, but the full history is in `index.md` (read in Step 4).
+
+**If handoff context doesn't exist**: Continue normally.
+
 ## Step 4: Read Session Context
 
 Read `<git-root>/.bonfire/index.md` and report when ready.

package/files/opencode.json

@@ -7,6 +7,9 @@
     },
     {
       "directory": "skill/archive-bonfire-awareness"
+    },
+    {
+      "directory": "skill/handoff-awareness"
     }
   ]
 }

package/files/skill/handoff-awareness/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: Handoff Awareness
+model: anthropic/claude-haiku-4-20250514
+mode: task
+hidden: true
+tools:
+  - bash
+  - read
+  - glob
+permission:
+  task:
+    "*": deny
+---
+
+# Handoff Awareness
+
+This skill detects when a session handoff may be beneficial and suggests the appropriate action.
+
+## When to Trigger
+
+Activate when user mentions:
+- Context concerns: "running out of context", "context limit", "context window"
+- Length concerns: "conversation is getting long", "too much context", "large conversation"
+- Fresh start: "should we start fresh?", "new session?", "hand off?", "start over?"
+- Degraded quality: "you're losing context", "you forgot", "we already discussed this"
+- Explicit ask: "can you hand off?", "transfer to new session"
+
+## Instructions
+
+1. **Check for .bonfire/ directory**:
+   ```bash
+   git rev-parse --show-toplevel
+   ```
+   Then check if `.bonfire/index.md` exists.
+
+2. **If .bonfire/ exists**, suggest handoff:
+
+   > "I can hand off this session to a fresh Claude instance while preserving your work.
+   >
+   > Run `/bonfire-handoff` to:
+   > 1. Save current progress to `.bonfire/index.md`
+   > 2. Generate minimal handoff context
+   > 3. Spawn a new Claude session in an adjacent tmux pane
+   >
+   > The new session will have access to your full session history via `/bonfire-start`."
+
+3. **If .bonfire/ doesn't exist**, suggest initialization:
+
+   > "To enable session handoff, first run `/bonfire-start` to initialize session tracking.
+   > This creates a `.bonfire/` directory that preserves context across sessions."
+
+4. **If not in tmux**, mention the limitation:
+
+   > "Note: Automatic session spawning requires tmux. If you're not in tmux, you can still
+   > run `/bonfire-handoff` to generate the handoff context, then manually start a new
+   > session and paste the context."
+
+## Important
+
+- This skill **suggests** handoff, it does NOT trigger it automatically
+- User must explicitly run `/bonfire-handoff` to perform the handoff
+- Don't suggest handoff for short conversations or early in a session
+- If user is mid-task, suggest completing the current atomic unit first
+- Handoff is specifically for context limit concerns, not for switching topics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-bonfire",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "OpenCode forgets everything between sessions. Bonfire remembers.",
   "type": "module",
   "bin": {