opencode-bonfire 0.9.6

package/files/command/bonfire-review.md

@@ -0,0 +1,158 @@
+---
+description: Review work for blindspots, gaps, and improvements
+---
+
+# Review Work
+
+Strategic review using subagent for analysis, preserving main context for action decisions.
+
+## Step 1: Determine Scope
+
+Based on $ARGUMENTS:
+- No args: Review current branch vs base
+- `--session`: Review work captured in current session context
+- Topic/area: Focus review on specific aspect
+
+## Step 2: Gather Context
+
+- Read session context from `<git-root>/.bonfire/index.md`
+- Get branch diff: `git diff main...HEAD` (or appropriate base)
+- Read relevant specs/docs from `.bonfire/`
+- Understand intent: what were we trying to accomplish?
+
+## Step 3: Run Review (Subagent)
+
+**Progress**: Tell the user "Reviewing work for blindspots and gaps..."
+
+Use the task tool to invoke the **work-reviewer** subagent.
+
+Provide the review context:
+
+```
+Review this work for blindspots, gaps, and improvements.
+
+**Scope**: [Branch diff / session work / specific area]
+
+**Intent**: [What we were trying to accomplish - from session context]
+
+**Files changed**:
+[List of modified files from git diff]
+
+**Session context**:
+[Relevant notes from index.md]
+
+Return categorized findings with severity and effort estimates.
+```
+
+**Wait for the subagent to return findings** before proceeding.
+
+The subagent runs in isolated context (sonnet model), preserving main context for action decisions.
+
+### Review Validation
+
+After the subagent returns, validate the response:
+
+**Valid response contains:**
+- `## Summary` with finding counts
+- At least one of: `## Fix Now`, `## Needs Spec`, or `## Create Issues`
+
+**On valid response**: Proceed to Step 4.
+
+**On partial response** (missing categories but has findings):
+1. Warn user: "Review returned partial results. Some categories may be missing."
+2. Present available findings.
+3. Continue to Step 4.
+
+**On invalid/empty response**:
+1. Warn user: "Review subagent returned no findings. I'll review directly."
+2. Fall back to in-context review:
+   - Read changed files from git diff
+   - Analyze for common issues (missing tests, error handling, etc.)
+   - Check for TODOs and incomplete implementations
+3. Present in-context findings using the same format.
+
+**On subagent failure** (timeout, error):
+1. Warn user: "Review subagent failed. Continuing with direct review."
+2. Perform in-context review as above.
+
+### Resumable Review (Large Changes)
+
+For large changesets, review may need multiple passes. The task tool returns a `session_id` you can use to resume.
+
+**When to offer resume:**
+- Review covers many files and user wants deeper analysis of specific area
+- Findings mention "additional items omitted" or suggest areas need more attention
+- User wants to focus review on specific aspect (e.g., "look more at tests")
+
+**To resume review:**
+1. Tell user: "Review covered [X]. Want deeper analysis of [specific area]?"
+2. If yes, re-invoke work-reviewer with the `session_id` parameter:
+   - Pass the session_id from the previous invocation
+   - Provide a focused directive: "Continue review focusing on: [specific area]."
+3. Merge findings from resumed review with previous findings.
+4. Repeat if needed, up to 3 passes maximum.
+
+**Example multi-pass scenario:**
+- Pass 1: General review → finds 5 issues, notes "test coverage not analyzed"
+- Pass 2 (resume): "Continue review focusing on: test coverage" → finds 3 more test gaps
+- Merge: Combined findings give complete picture
+
+## Step 4: Present Findings
+
+Present the subagent's findings grouped by recommended action:
+
+### Fix Now (trivial effort)
+[List items from subagent that can be fixed immediately]
+
+> Ask: "Want me to fix these now?"
+
+### Needs Spec (important, needs planning)
+[List items that need implementation planning]
+
+> Ask: "Want me to create an implementation spec?"
+
+### Create Issues (large effort or nice-to-have)
+[List items for future sessions]
+
+> Ask: "Want me to create GitHub/Linear issues?"
+
+## Step 5: Execute Chosen Action
+
+Based on user choice:
+- **Fix now**: Make the changes directly
+- **Spec**: Run `/bonfire-spec` with findings
+- **Create issues**: See below
+
+### Creating Issues
+
+First, read `<git-root>/.bonfire/config.json` and check `linearEnabled`.
+
+**Offer choices based on config:**
+- Always offer: "Create GitHub issue"
+- If `linearEnabled` is true: Also offer "Create Linear issue"
+
+**GitHub Issue Creation:**
+```bash
+gh issue create --title "Finding title" --body "Finding details"
+```
+
+**Linear Issue Creation (if enabled):**
+1. Use linear-cli to create the issue:
+   ```bash
+   linear issue create --title "Finding title" --description "Finding details"
+   ```
+2. On success: Return issue URL/ID
+3. On failure: Warn user, offer to create GitHub issue instead
+
+Note: Run `linear issue create --help` to see available options (team, priority, labels, etc.).
+
+**For each created issue:**
+- Record the issue ID and URL
+- Note which tracker (GitHub/Linear) was used
+
+## Step 6: Update Session Context
+
+Add review outcomes to `<git-root>/.bonfire/index.md`:
+- Key findings noted
+- Issues created (with links)
+- Work deferred to future sessions

package/files/command/bonfire-spec.md

@@ -0,0 +1,272 @@
+---
+description: Create an implementation spec for a feature or task
+---
+
+# Create Implementation Spec
+
+A hybrid approach using subagents: research in isolated context, interview in main context, write in isolated context.
+
+## Step 1: Find Git Root
+
+Run `git rev-parse --show-toplevel` to locate the repository root.
+
+## Step 2: Check Config
+
+Read `<git-root>/.bonfire/config.json` if it exists.
+
+**Specs location**: Read `specsLocation` from config. Default to `.bonfire/specs/` if not set.
+
+## Step 3: Gather Initial Context
+
+Get the topic from $ARGUMENTS or ask if unclear.
+
+Check for existing context:
+- Read `<git-root>/.bonfire/index.md` for project state
+- Check for `SPEC.md` or `spec.md` in git root (user's spec template)
+- If issue ID provided, note for filename
+
+## Step 4: Research Phase (Subagent)
+
+**Progress**: Tell the user "Researching codebase for patterns and constraints..."
+
+Use the task tool to invoke the **codebase-explorer** subagent for research.
+
+Provide a research directive with these questions:
+
+```
+Research the codebase for implementing: [TOPIC]
+
+Find:
+1. **Patterns**: How similar features are implemented, existing abstractions to reuse, naming conventions
+2. **Constraints**: Dependencies, API boundaries, performance considerations
+3. **Potential Conflicts**: Files that need changes, intersections with existing code, migration concerns
+
+Return structured findings only - no raw file contents.
+```
+
+**Wait for the subagent to return findings** before proceeding.
+
+The subagent runs in isolated context (haiku model, fast), preserving main context for interview.
+
+### Research Validation
+
+After the subagent returns, validate the response:
+
+**Valid response contains at least one of:**
+- `## Patterns Found` with content
+- `## Key Files` with entries
+- `## Constraints Discovered` with items
+
+**On valid response**: Proceed to Step 5.
+
+**On invalid/empty response**:
+1. Warn user: "Codebase exploration returned limited results. I'll research directly."
+2. Fall back to in-context research using glob, grep, and read:
+   - Search for patterns: `glob("**/*.{ts,js,py,go}")` to find code files
+   - Look for similar implementations: `grep("pattern-keyword")`
+   - Read key files identified
+3. Continue to Step 5 with in-context findings.
+
+**On subagent failure** (timeout, error):
+1. Warn user: "Subagent research failed. Continuing with direct exploration."
+2. Perform in-context research as above.
+3. Continue to Step 5.
+
+### Resumable Exploration (Large Codebases)
+
+For very large codebases, exploration may need multiple passes. The task tool returns a `session_id` you can use to resume.
+
+**When to offer resume:**
+- Subagent returns with "X additional items omitted" notes
+- Findings cover only part of the codebase (e.g., backend but not frontend)
+- User asks for deeper exploration of a specific area
+
+**To resume exploration:**
+1. Tell user: "Exploration found [X] but there's more to explore. Continue exploring [specific area]?"
+2. If yes, re-invoke codebase-explorer with the `session_id` parameter:
+   - Pass the session_id from the previous invocation
+   - Provide a refined directive: "Continue exploring: [specific area]. Focus on [what to find]."
+3. Merge findings from resumed exploration with previous findings.
+4. Repeat if needed, up to 3 passes maximum.
+
+**Example multi-pass scenario:**
+- Pass 1: "Research authentication" → finds auth middleware, auth service
+- Pass 2 (resume): "Continue exploring: authorization rules" → finds permissions, role checks
+- Merge: Combined findings inform better interview questions
+
+## Step 5: Interview Phase (Main Context)
+
+**Progress**: Tell the user "Starting interview (3 rounds: core decisions, edge cases, testing & scope)..."
+
+Using the research findings, interview the user with **informed questions** via the question tool.
+
+### Round 1: Core Decisions
+
+**Progress**: "Round 1/3: Core decisions..."
+
+Ask about fundamental approach based on patterns found:
+
+Example questions (adapt based on actual findings):
+- "I found [Pattern A] in `services/` and [Pattern B] in `handlers/`. Which pattern should this feature follow?"
+- "The existing [Component] handles [X]. Should we extend it or create a new [Y]?"
+- "I see [Library] is used for [purpose]. Should we use it here or try [Alternative]?"
+
+### Round 2: Edge Cases & Tradeoffs
+
+**Progress**: "Round 2/3: Edge cases and tradeoffs..."
+
+Based on Round 1 answers and research, ask about:
+- Error handling approach
+- Edge cases identified in research
+- Performance vs simplicity tradeoffs
+- User experience considerations
+
+Example questions:
+- "What should happen when [edge case from research]?"
+- "I found [potential conflict]. How should we handle it?"
+- "[Approach A] is simpler but [tradeoff]. [Approach B] is more complex but [benefit]. Preference?"
+
+### Round 3: Testing & Scope (Required)
+
+**Progress**: "Round 3/3: Testing and scope (final round)..."
+
+Always ask about testing and scope, even if user seems ready to proceed:
+
+**Testing** (must ask one):
+- "What's the testing approach? Unit tests, integration tests, manual testing, or skip tests for MVP?"
+- "Should this include tests? If so, what should be covered?"
+
+**Scope** (must ask one):
+- "What's explicitly out of scope for this implementation?"
+- "MVP vs full implementation - any features to defer?"
+
+Example combined question:
+- "Two quick questions: (1) Testing approach for this feature? (2) Anything explicitly out of scope?"
+
+**Do not skip Round 3.** These questions take 30 seconds and prevent spec gaps.
+
+## Step 6: Write the Spec (Subagent)
+
+**Progress**: Tell the user "Writing implementation spec..."
+
+Use the task tool to invoke the **spec-writer** subagent.
+
+Provide the prompt in this exact format:
+
+```
+## Research Findings
+
+<paste structured findings from Step 4>
+
+## Interview Q&A
+
+### Core Decisions
+**Q**: <question from Round 1>
+**A**: <user's answer>
+
+### Edge Cases & Tradeoffs
+**Q**: <question from Round 2>
+**A**: <user's answer>
+
+### Scope & Boundaries
+**Q**: <question from Round 3>
+**A**: <user's answer>
+
+## Spec Metadata
+
+- **Topic**: <topic name>
+- **Issue**: <issue ID or N/A>
+- **Output Path**: <git-root>/<specsLocation>/<filename>.md
+- **Date**: <YYYY-MM-DD>
+```
+
+The subagent will write the spec file directly to the Output Path.
+
+**Naming convention**: `<issue-id>-<topic>.md` or `<topic>.md`
+
+### Spec Verification
+
+After the spec-writer subagent returns, verify the spec is complete.
+
+**Key sections to check** (lenient - only these 4):
+- `## Overview`
+- `## Decisions`
+- `## Implementation Steps`
+- `## Edge Cases`
+
+**Verification steps:**
+
+1. **Read the spec file** at `<git-root>/<specsLocation>/<filename>.md`
+
+2. **If file missing or empty**:
+   - Warn user: "Spec file wasn't written. Writing directly..."
+   - Write the spec yourself using the write tool
+   - Run verification again on the written file
+
+3. **If file exists, check for key sections**:
+   - Scan content for the 4 section headers above
+   - Track which sections are present/missing
+
+4. **If all 4 sections present**:
+   - Tell user: "Spec written and verified (4/4 key sections present)."
+   - Proceed to Step 7.
+
+5. **If 1-3 sections missing** (partial write):
+   - Warn user: "Spec appears incomplete. Missing sections: [list missing]"
+   - Show which sections ARE present
+   - Ask: "Proceed with partial spec, retry write, or abort?"
+   - **Proceed**: Continue to Step 7
+   - **Retry**: Re-invoke spec-writer subagent with same input, then verify again
+   - **Abort**: Stop and inform user the incomplete spec file remains at path
+
+6. **If all sections missing but has content**:
+   - Treat as invalid format, trigger fallback write
+   - Write the spec yourself, then verify the written file
+
+**On subagent failure** (timeout, error):
+- Warn user: "Spec writer failed. Writing spec directly..."
+- Write the spec yourself using the write tool
+- Run verification on the written file
+
+## Step 7: Link to Session Context
+
+Add a reference to the spec in `<git-root>/.bonfire/index.md` under Current State.
+
+## Step 8: Confirm
+
+Read the generated spec and present a summary. Ask if user wants to:
+- Proceed with implementation
+- Refine specific sections
+- Add more detail to any area
+- Save for later
+
+## Interview Tips
+
+**Good questions are:**
+- Informed by research (not generic)
+- About tradeoffs (not yes/no)
+- Specific to the codebase
+- Non-obvious (user wouldn't think to mention)
+
+**Bad questions:**
+- "What features do you want?" (too broad)
+- "Should we add error handling?" (obvious)
+- Generic without codebase context
+
+**Examples of good informed questions:**
+- "I found `UserService` uses repository pattern but `OrderService` uses direct DB access. Which approach?"
+- "The `auth` middleware validates JWT but doesn't check permissions. Should this feature add permission checks or assume auth is enough?"
+- "There's a `BaseController` with shared logic. Extend it or keep this feature standalone?"
+
+## Spec Lifecycle
+
+Specs are **temporary artifacts** - they exist to guide implementation:
+
+1. **Draft** → Created, ready for review
+2. **In Progress** → Being implemented
+3. **Completed** → Implementation done
+
+**When a spec is fully implemented**:
+- If it contains reusable reference material, move to `docs/`
+- Delete the spec file - archive has the record
+- Don't let specs accumulate

package/files/command/bonfire-start.md

@@ -0,0 +1,245 @@
+---
+description: Start a new session - reads context and scaffolds .bonfire/ if needed
+---
+
+# Start Session
+
+## Step 1: Find Git Root
+
+Run `git rev-parse --show-toplevel` to locate the repository root. All session files live at `<git-root>/.bonfire/`.
+
+## Step 2: Check for Bonfire Directory
+
+Check if `<git-root>/.bonfire/index.md` exists.
+
+**If .bonfire/ does NOT exist**, scaffold it:
+
+1. Tell the user: "No bonfire directory found. Let me set that up for you."
+
+2. Use the question tool to ask setup questions (4 questions, one round):
+
+   1. "Where should specs be saved?" (Header: "Specs")
+      - .bonfire/specs/ (Default) - Keep with session context
+      - specs/ - Project root level
+
+   2. "Where should docs be saved?" (Header: "Docs")
+      - .bonfire/docs/ (Default) - Keep with session context
+      - docs/ - Project root level
+
+   3. "How should `.bonfire/` be handled in git?" (Header: "Git")
+      - ignore-all (Default) - Keep sessions private/local
+      - hybrid - Commit docs/specs, keep notes private
+      - commit-all - Share everything with team
+
+   4. "Enable Linear integration?" (Header: "Linear")
+      - No (Default) - Skip Linear integration
+      - Yes - Fetch/create Linear issues (requires linear-cli)
+
+3. Create the directory structure based on user choices:
+
+   **Always create in .bonfire/**:
+   ```
+   .bonfire/
+   ├── index.md
+   ├── config.json
+   ├── archive/
+   └── .gitignore
+   ```
+
+   **If specsLocation is `.bonfire/specs/`**: create `.bonfire/specs/`
+   **If specsLocation is `specs/`**: create `<git-root>/specs/`
+
+   **If docsLocation is `.bonfire/docs/`**: create `.bonfire/docs/`
+   **If docsLocation is `docs/`**: create `<git-root>/docs/`
+
+4. Detect project name from: package.json name → git remote → directory name
+
+5. Create `config.json` with user's answers:
+   ```json
+   {
+     "specsLocation": "<user-answer>",
+     "docsLocation": "<user-answer>",
+     "gitStrategy": "<user-answer>",
+     "linearEnabled": <true-or-false>
+   }
+   ```
+
+6. Create `index.md` with template:
+   ```markdown
+   # Session Context: [PROJECT_NAME]
+
+   **Date**: [CURRENT_DATE]
+   **Status**: Active
+   **Branch**: main
+
+   ---
+
+   ## Current State
+
+   [Describe what you're working on]
+
+   ---
+
+   ## Recent Sessions
+
+   ### Session 1 - [CURRENT_DATE]
+
+   **Goal**: [What you want to accomplish]
+
+   **Accomplished**:
+   - [List completed items]
+
+   **Decisions**:
+   - [Key decisions made]
+
+   **Blockers**: None
+
+   ---
+
+   ## Next Session Priorities
+
+   1. [Priority items]
+
+   ---
+
+   ## Key Resources
+
+   **Code References**:
+   - [Component/feature]: `path/to/file.ts`
+
+   **External Links**:
+   - [Issue Tracker](url)
+
+   ---
+
+   ## Archived Sessions
+
+   [Links to archived sessions will appear here]
+
+   ---
+
+   ## Notes
+
+   [Any additional context]
+   ```
+
+7. Create `.gitignore` based on chosen strategy and locations:
+
+   **Ignore all**:
+   ```
+   *
+   !.gitignore
+   ```
+
+   **Hybrid** (only include dirs that are inside .bonfire/):
+   ```
+   *
+   !.gitignore
+   ```
+   If docsLocation is `.bonfire/docs/`, add:
+   ```
+   !docs/
+   !docs/**
+   ```
+   If specsLocation is `.bonfire/specs/`, add:
+   ```
+   !specs/
+   !specs/**
+   ```
+
+   **Commit all**:
+   ```
+   data/
+   scratch/
+   ```
+
+**If .bonfire/ EXISTS**, proceed to Step 3.
+
+## Step 3: Check/Update CLAUDE.md
+
+Check if `<git-root>/CLAUDE.md` exists.
+
+**If CLAUDE.md does NOT exist**, create it:
+```markdown
+# [PROJECT_NAME]
+
+## Quick Context
+
+Read `.bonfire/index.md` for current project state, recent work, and priorities.
+
+## Bonfire Commands
+
+- `/bonfire-start` - Start a session (reads context)
+- `/bonfire-end` - End session (updates context)
+- `/bonfire-spec` - Create implementation spec
+- `/bonfire-document <topic>` - Document a topic
+- `/bonfire-review` - Review work for blindspots and improvements
+- `/bonfire-archive` - Archive completed work
+- `/bonfire-configure` - Change project settings
+```
+
+**If CLAUDE.md EXISTS**, check if it references `.bonfire/index.md`. If not, append:
+```markdown
+
+## Session Context
+
+Read `.bonfire/index.md` for current project state, recent work, and priorities.
+```
+
+## Step 4: Read Session Context
+
+Read `<git-root>/.bonfire/index.md` and report when ready.
+
+Summarize:
+- Current state
+- Recent work
+- Next priorities
+
+Then ask: "What do you want to work on this session?"
+
+## Step 5: Fetch External Context (Optional)
+
+**Only fetch if user provides a new URL or issue ID:**
+
+### Detecting Issue Type
+
+- **GitHub**: Starts with `#`, contains `github.com`, or doesn't match Linear pattern
+- **Linear**: Matches `[A-Z]+-[0-9]+` pattern (e.g., `ENG-123`, `ABC-456`) or contains `linear.app`
+
+### GitHub Issues/PRs
+
+Use `gh` CLI:
+- `gh pr view [URL] --json title,body,state,labels`
+- `gh issue view [URL] --json title,body,state,labels`
+
+### Linear Issues
+
+First, read `<git-root>/.bonfire/config.json` and check `linearEnabled`.
+
+**If `linearEnabled` is false or not set**: Skip Linear, treat as ad-hoc task.
+
+**If `linearEnabled` is true**:
+1. Use linear-cli to fetch the issue:
+   ```bash
+   linear issue view ENG-123
+   ```
+2. Extract: title, description, state, priority, labels, assignee
+3. On success: Summarize the issue context
+4. On failure: Warn user - "Couldn't fetch Linear issue. Is linear-cli installed and authenticated? Continue without issue context?"
+
+Note: Run `linear issue view --help` to see available options.
+
+### Update Session Context
+
+If issue was fetched successfully:
+- Add reference to `index.md` under Current State
+- Include issue ID, title, and link
+- Note the issue tracker type (GitHub/Linear)
+
+### Fallback
+
+If no URL/issue ID provided (continuing work, ad-hoc task):
+- Proceed with existing session context
+- Session notes are the source of truth for ongoing work
+
+Confirm understanding and ask how to proceed.

package/files/opencode.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["CLAUDE.md", ".bonfire/index.md"]
+}

package/files/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "bonfire-opencode",
+  "private": true,
+  "dependencies": {
+    "@opencode-ai/plugin": "*"
+  }
+}