opencode-bonfire 1.2.1 → 1.4.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-review-pr.md

@@ -0,0 +1,229 @@
+---
+description: Review a GitHub pull request and post inline comments
+---
+
+# Review Pull Request
+
+Review a GitHub PR in an isolated worktree, then post inline comments on findings.
+
+## Step 1: Parse Arguments
+
+Extract PR number from `$ARGUMENTS`:
+- `333` or `#333` → PR number 333
+- Empty → Show usage and abort
+
+**Usage**: `/bonfire-review-pr <pr-number>`
+
+If no PR number provided:
+> "Usage: `/bonfire-review-pr <pr-number>`
+>
+> Example: `/bonfire-review-pr 333`"
+
+## Step 2: Verify Environment
+
+Check if running inside tmux:
+
+```bash
+[ -n "$TMUX" ] && echo "tmux: yes" || echo "tmux: no"
+```
+
+**If not in tmux**: Provide manual instructions and abort:
+
+> "PR review with inline comments requires tmux for worktree isolation.
+>
+> **Manual alternative:**
+> 1. Create worktree: `git worktree add ../pr-<number>-review origin/<branch>`
+> 2. Open new terminal in that directory
+> 3. Run: `opencode 'Review this PR and help me post comments'`
+> 4. Clean up when done: `git worktree remove ../pr-<number>-review`"
+
+## Step 3: Fetch PR Metadata
+
+Get PR details:
+
+```bash
+gh pr view <number> --json number,title,headRefName,baseRefName,headRefOid,url,body,files
+```
+
+**If PR not found**: Abort with "PR #<number> not found in this repository."
+
+Extract and store:
+- `headRefName` - PR branch name
+- `baseRefName` - Target branch (usually main)
+- `headRefOid` - Commit SHA for inline comments
+- `title` - PR title
+- `url` - PR URL
+- `files` - Changed files list
+
+## Step 4: Find Git Root and Compute Paths
+
+```bash
+git rev-parse --show-toplevel
+```
+
+Compute worktree path: `<git-root>/../<repo-name>-pr-<number>-review`
+
+Example: `/Users/vieko/dev/gtm` → `/Users/vieko/dev/gtm-pr-333-review`
+
+## Step 5: Create Worktree
+
+Create isolated worktree for PR branch:
+
+```bash
+git fetch origin <headRefName>
+git worktree add <worktree-path> origin/<headRefName>
+```
+
+**On failure** (branch conflict, dirty state, etc.):
+
+1. Check error message
+2. If worktree already exists: Ask user "Worktree already exists. Remove and recreate?"
+   - Yes: `git worktree remove <worktree-path> --force` then retry
+   - No: Abort
+3. If other error: Report error and abort with suggestion to check `git worktree list`
+
+## Step 6: Get PR Diff Summary
+
+Get the diff for context:
+
+```bash
+cd <worktree-path> && git diff origin/<baseRefName>...HEAD --stat
+```
+
+Get changed files:
+
+```bash
+cd <worktree-path> && git diff origin/<baseRefName>...HEAD --name-only
+```
+
+## Step 7: Generate Review Context
+
+Create context document for spawned session.
+
+Write to `<worktree-path>/.bonfire-pr-review-context.md`:
+
+```markdown
+# PR Review Context
+
+**PR**: #<number> - <title>
+**URL**: <url>
+**Branch**: <headRefName> → <baseRefName>
+**Commit**: <headRefOid>
+
+## Changed Files
+
+<list of changed files>
+
+## PR Description
+
+<body from PR>
+
+---
+
+## Instructions
+
+You are reviewing PR #<number> in an isolated worktree.
+
+### Step 1: Run Review
+
+Use the task tool to invoke the **work-reviewer** subagent:
+
+```
+Review this pull request for blindspots, gaps, and improvements.
+
+**Scope**: PR #<number> - <title>
+
+**Files changed**:
+<list of changed files>
+
+**PR Description**:
+<body>
+
+Return categorized findings with severity, effort, and specific file:line references.
+```
+
+### Step 2: Present Findings
+
+After review completes, present findings grouped by severity.
+
+For each finding, note:
+- File and line number (if applicable)
+- Severity (critical/moderate/minor)
+- Description
+
+### Step 3: Batch Comment Selection
+
+Ask user: "Which findings should I post as PR comments?"
+
+Options:
+1. List findings by number, let user select (e.g., "1, 3, 5")
+2. "All" - post all findings
+3. "None" - skip commenting
+
+### Step 4: Post Inline Comments
+
+For each selected finding with a file:line reference, post an inline comment:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/<number>/comments \
+  -f body="**Review Finding**
+
+<finding description>
+
+*Severity: <severity> | Effort: <effort>*" \
+  -f commit_id="<headRefOid>" \
+  -f path="<file-path>" \
+  -f line=<line-number>
+```
+
+For findings without line numbers, post as general PR comment:
+
+```bash
+gh pr comment <number> --body "**Review Finding**
+
+<finding description>
+
+*Severity: <severity> | Effort: <effort>*"
+```
+
+**Note**: GitHub only allows inline comments on files that are part of the PR diff. If a finding references a file not in the diff (e.g., missing config in turbo.json when turbo.json wasn't changed), post it as a general PR comment instead.
+
+### Step 5: Offer Cleanup
+
+After commenting, ask: "Review complete. Remove worktree?"
+
+If yes:
+```bash
+cd <original-git-root>
+git worktree remove <worktree-path>
+```
+
+Report: "Worktree cleaned up. PR review complete."
+```
+
+## Step 8: Spawn Review Session
+
+Spawn a new OpenCode session in the worktree:
+
+```bash
+WORKTREE_PATH="<computed-worktree-path>"
+CONTEXT="$(cat "$WORKTREE_PATH/.bonfire-pr-review-context.md")"
+tmux split-window -h -c "$WORKTREE_PATH" \
+  "opencode --append-system-prompt '$CONTEXT' 'Ready to review PR #<number>. Starting work-reviewer subagent...'"
+```
+
+**Verify spawn succeeded**: If tmux fails (terminal too small), warn user and provide manual instructions.
+
+## Step 9: Confirm
+
+Tell the user:
+
+> **PR review session spawned.**
+>
+> - Worktree created at `<worktree-path>`
+> - Review session opened in adjacent pane
+> - The new session will run work-reviewer and help you post comments
+>
+> When done, the review session will offer to clean up the worktree.
+>
+> You can continue working here - your current branch is unchanged.

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.4.0",
   "description": "OpenCode forgets everything between sessions. Bonfire remembers.",
   "type": "module",
   "bin": {