opencode-bonfire 1.3.0 → 1.5.0

package/files/command/bonfire-configure.md

@@ -10,9 +10,47 @@ Always runs interactively - asks all configuration questions regardless of argum
 
 Run `git rev-parse --show-toplevel` to locate the repository root.
 
-## Step 2: Check for Bonfire Directory
+## Step 2: Ensure Bonfire Directory Exists
 
-If `<git-root>/.bonfire/` does not exist, tell the user to run `/bonfire-start` first.
+If `<git-root>/.bonfire/` does not exist, create it.
+
+If `<git-root>/.bonfire/index.md` does not exist, create a minimal version:
+
+```markdown
+# Session Context: [PROJECT_NAME]
+
+**Date**: [CURRENT_DATE]
+**Status**: Active
+**Branch**: [CURRENT_BRANCH]
+
+---
+
+## Current State
+
+[Created via /bonfire-configure - run /bonfire-start for full setup]
+
+---
+
+## Recent Sessions
+
+_No sessions recorded yet._
+
+---
+
+## Next Session Priorities
+
+1. [Define your priorities]
+
+---
+
+## Notes
+
+[Add notes here]
+```
+
+Detect project name from: package.json name → git remote → directory name.
+
+This ensures configure can be run as the first entry point without leaving the project in an incomplete state.
 
 ## Step 3: Read Current Config
 

package/files/command/bonfire-document.md

@@ -4,175 +4,102 @@ description: Create documentation about a topic in the codebase
 
 # Document Topic
 
-Create reference documentation using subagent for research, preserving main context.
+Create reference documentation for **$ARGUMENTS**.
 
-## 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.
-
-**Docs location**: Read `docsLocation` from config. Default to `.bonfire/docs/` if not set.
-
-## Step 3: Understand the Topic
-
-The topic to document is: $ARGUMENTS
-
-If no topic provided, ask the user what they want documented.
-
-## Step 4: Explore the Codebase (Subagent)
-
-**Progress**: Tell the user "Exploring codebase for [TOPIC]..."
-
-Use the task tool to invoke the **codebase-explorer** subagent for research.
-
-Provide a research directive:
-
-```
-Research the codebase to document: [TOPIC]
-
-Find:
-1. **Architecture**: How this system/feature is structured, key components
-2. **Key Files**: Important files and their roles
-3. **Flow**: How data/control flows through the system
-4. **Patterns**: Design patterns and conventions used
-5. **Gotchas**: Important details, edge cases, things to watch out for
-
-Return structured findings with file paths and brief descriptions.
-```
-
-**Wait for the subagent to return findings** before proceeding.
-
-The subagent runs in isolated context (haiku model, fast), preserving main context for writing.
+---
 
-### Exploration Validation
+## Outcome
 
-After the subagent returns, validate the response:
+Complete reference documentation that helps developers understand a system, feature, or pattern in the codebase. The doc should enable someone unfamiliar with the code to:
+- Understand what it does and why it exists
+- Find the relevant files quickly
+- Understand how it works at a conceptual level
+- Avoid common pitfalls
 
-**Valid response contains at least one of:**
-- `## Architecture` or `## Patterns Found` with content
-- `## Key Files` with entries
-- `## Flow` or `## Gotchas` with items
+---
 
-**On valid response**: Proceed to Step 5.
+## Acceptance Criteria
 
-**On invalid/empty response**:
-1. Warn user: "Codebase exploration returned limited results. I'll research directly."
-2. Fall back to in-context research:
-   - `glob("**/*[topic-related]*")` to find relevant files
-   - `grep("topic-keywords")` to find implementations
-   - Read identified files
-3. Continue to Step 5 with in-context findings.
+The doc file must contain these sections:
 
-**On subagent failure** (timeout, error):
-1. Warn user: "Subagent exploration failed. Continuing with direct research."
-2. Perform in-context research as above.
-3. Continue to Step 5.
+| Section | Purpose |
+|---------|---------|
+| `## Overview` | What this is and why it matters |
+| `## Key Files` | Important files with their roles |
+| `## How It Works` | Conceptual explanation of flow/behavior |
+| `## Gotchas` | Edge cases, pitfalls, things to watch out for |
 
-### Resumable Exploration (Large Codebases)
+Additional sections are welcome (Architecture, Examples, Related Topics) but these four are required.
 
-For very large codebases, exploration may need multiple passes. The task tool returns a `session_id` you can use to resume.
+**Quality signals:**
+- File paths are accurate and exist in the codebase
+- Explanations match actual code behavior
+- Gotchas reflect real issues (not hypothetical concerns)
 
-**When to offer resume:**
-- Subagent returns with "X additional items omitted" notes
-- Findings cover only part of the topic (e.g., found architecture but not flows)
-- User asks for deeper exploration of a specific aspect
+---
 
-**To resume exploration:**
-1. Tell user: "Exploration found [X] but there's more to document. Continue exploring [specific aspect]?"
-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 aspect]. Focus on [what to find]."
-3. Merge findings from resumed exploration with previous findings.
-4. Repeat if needed, up to 3 passes maximum.
+## Constraints
 
-**Example multi-pass scenario:**
-- Pass 1: "Document payment system" → finds payment service, stripe integration
-- Pass 2 (resume): "Continue exploring: refund handling" → finds refund logic, webhooks
-- Merge: Combined findings produce more complete documentation
+### Context Isolation
 
-## Step 5: Write Documentation (Subagent)
+Research happens in an isolated subagent context to preserve main context.
 
-**Progress**: Tell the user "Writing documentation..."
+| Phase | Agent | Model | Why |
+|-------|-------|-------|-----|
+| Research | `codebase-explorer` | haiku | Fast exploration without polluting main context |
+| Writing | `doc-writer` | inherit | Synthesis in isolation with full research context |
 
-**Naming convention**: `<topic>.md` (kebab-case)
+### No Interview Required
 
-Examples:
-- `inbound-agent-architecture.md`
-- `sampling-strategies.md`
-- `authentication-flow.md`
+Unlike specs, documentation is based purely on codebase research. The code is the source of truth.
 
-Use the task tool to invoke the **doc-writer** subagent.
+### File Locations
 
-Provide the prompt in this exact format:
+- **Config**: `<git-root>/.bonfire/config.json` contains `docsLocation`
+- **Default**: `.bonfire/docs/` if not configured
+- **Naming**: `<topic>.md` (kebab-case, e.g., `authentication-flow.md`)
 
-```
-## Research Findings
+### Verification
 
-<paste structured findings from Step 4>
+After writing, verify the doc contains all 4 required sections. If incomplete:
+- Warn user what's missing
+- Offer: proceed / retry / abort
 
-## Doc Metadata
+### Session Context
 
-- **Topic**: <topic name>
-- **Output Path**: <git-root>/<docsLocation>/<topic>.md
-- **Date**: <YYYY-MM-DD>
-```
+After writing, add a reference to the doc in `<git-root>/.bonfire/index.md` under Key Resources.
 
-The subagent will write the doc file directly to the Output Path.
+### Completion
 
-### Doc Verification
+After verification, confirm doc creation and offer options:
+- Add more detail to any section
+- Document related topics
+- Proceed with other work
 
-After the doc-writer subagent returns, verify the doc is complete.
+---
 
-**Key sections to check** (lenient - only these 4):
-- `## Overview`
-- `## Key Files`
-- `## How It Works`
-- `## Gotchas`
+## Guidance (Not Rules)
 
-**Verification steps:**
+These patterns tend to work well, but adapt as needed:
 
-1. **Read the doc file** at `<git-root>/<docsLocation>/<topic>.md`
+**Research before writing** - Let the codebase inform the structure.
 
-2. **If file missing or empty**:
-   - Warn user: "Doc file wasn't written. Writing directly..."
-   - Write the doc yourself using the write tool
-   - Run verification again on the written file
+**Show your work** - Tell user what you're doing: "Exploring codebase...", "Writing documentation..."
 
-3. **If file exists, check for key sections**:
-   - Scan content for the 4 section headers above
-   - Track which sections are present/missing
+**Fallback gracefully** - If subagent fails, do the work in main context. Warn user but don't stop.
 
-4. **If all 4 sections present**:
-   - Tell user: "Doc written and verified (4/4 key sections present)."
-   - Proceed to Step 6.
+**Large codebases** - Explorer may need multiple passes. Offer to continue if findings seem incomplete for the topic.
 
-5. **If 1-3 sections missing** (partial write):
-   - Warn user: "Doc appears incomplete. Missing sections: [list missing]"
-   - Show which sections ARE present
-   - Ask: "Proceed with partial doc, retry write, or abort?"
-   - **Proceed**: Continue to Step 6
-   - **Retry**: Re-invoke doc-writer subagent with same input, then verify again
-   - **Abort**: Stop and inform user the incomplete doc file remains at path
+**Follow the code** - Document what the code actually does, not what comments claim or what you assume.
 
-6. **If all sections missing but has content**:
-   - Treat as invalid format, trigger fallback write
-   - Write the doc yourself, then verify the written file
+---
 
-**On subagent failure** (timeout, error):
-- Warn user: "Doc writer failed. Writing doc directly..."
-- Write the doc yourself using the write tool
-- Run verification on the written file
+## Anti-Patterns
 
-## Step 5: Link to Session Context
+**Don't document assumptions** - If you can't find it in the code, don't write about it.
 
-Add a reference to the doc in `<git-root>/.bonfire/index.md` under Key Resources or Notes.
+**Don't over-abstract** - Concrete file paths and function names are more useful than vague descriptions.
 
-## Step 6: Confirm
+**Don't skip verification** - Subagents can produce partial output. Always check.
 
-Summarize what was documented and ask if the user wants:
-- More detail on any section
-- Related topics documented
-- To proceed with other work
+**Don't write tutorials** - This is reference documentation (how it works), not a guide (how to use it).

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-spec.md

@@ -4,269 +4,111 @@ 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.
+Create an implementation spec for **$ARGUMENTS**.
 
-## 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?"
+## Outcome
 
-**Do not skip Round 3.** These questions take 30 seconds and prevent spec gaps.
+A complete implementation spec written to the configured specs location that captures:
+- What to build and why
+- Key decisions with rationale
+- Concrete implementation steps
+- Edge cases and error handling
+- Testing approach and scope boundaries
 
-## Step 6: Write the Spec (Subagent)
+---
 
-**Progress**: Tell the user "Writing implementation spec..."
+## Acceptance Criteria
 
-Use the task tool to invoke the **spec-writer** subagent.
+The spec file must contain these sections:
 
-Provide the prompt in this exact format:
+| Section | Purpose |
+|---------|---------|
+| `## Overview` | What this feature does and why it matters |
+| `## Decisions` | Key technical choices with rationale |
+| `## Implementation Steps` | Ordered, actionable steps to build it |
+| `## Edge Cases` | Error handling, boundary conditions, failure modes |
 
-```
-## Research Findings
+Additional sections are welcome but these four are required.
 
-<paste structured findings from Step 4>
+**Quality signals:**
+- Decisions reference actual codebase patterns (not generic advice)
+- Implementation steps are specific to this codebase (file paths, function names)
+- Edge cases reflect real constraints discovered in research
 
-## Interview Q&A
+---
 
-### Core Decisions
-**Q**: <question from Round 1>
-**A**: <user's answer>
+## Constraints
 
-### Edge Cases & Tradeoffs
-**Q**: <question from Round 2>
-**A**: <user's answer>
+### Context Isolation
 
-### Scope & Boundaries
-**Q**: <question from Round 3>
-**A**: <user's answer>
+Research and writing happen in isolated subagent contexts to preserve main context for user interaction.
 
-## Spec Metadata
+| Phase | Agent | Model | Why |
+|-------|-------|-------|-----|
+| Research | `codebase-explorer` | haiku | Fast, cheap exploration without polluting main context |
+| Writing | `spec-writer` | inherit | Synthesis in isolation; has full research + interview context |
 
-- **Topic**: <topic name>
-- **Issue**: <issue ID or N/A>
-- **Output Path**: <git-root>/<specsLocation>/<filename>.md
-- **Date**: <YYYY-MM-DD>
-```
+### User Interview Required
 
-The subagent will write the spec file directly to the Output Path.
+The user must be interviewed before writing. Research informs questions; questions surface decisions the user wouldn't think to mention.
 
-**Naming convention**: `<issue-id>-<topic>.md` or `<topic>.md`
+**Interview must cover:**
+- Core technical decisions (patterns, approaches, tradeoffs)
+- Edge cases and error handling preferences
+- Testing approach
+- Scope boundaries (what's explicitly out)
 
-### Spec Verification
+Use the question tool. Good questions are informed by research, about tradeoffs, and codebase-specific.
 
-After the spec-writer subagent returns, verify the spec is complete.
+### File Locations
 
-**Key sections to check** (lenient - only these 4):
-- `## Overview`
-- `## Decisions`
-- `## Implementation Steps`
-- `## Edge Cases`
+- **Config**: `<git-root>/.bonfire/config.json` contains `specsLocation`
+- **Default**: `.bonfire/specs/` if not configured
+- **Naming**: `<issue-id>-<topic>.md` or `<topic>.md`
 
-**Verification steps:**
+### Verification
 
-1. **Read the spec file** at `<git-root>/<specsLocation>/<filename>.md`
+After writing, verify the spec contains all 4 required sections. If incomplete:
+- Warn user what's missing
+- Offer: proceed / retry / abort
 
-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
+### Session Context
 
-3. **If file exists, check for key sections**:
-   - Scan content for the 4 section headers above
-   - Track which sections are present/missing
+After writing the spec, add a reference to it in `<git-root>/.bonfire/index.md` under Current State. This links the spec to the session that created it.
 
-4. **If all 4 sections present**:
-   - Tell user: "Spec written and verified (4/4 key sections present)."
-   - Proceed to Step 7.
+### Completion
 
-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
+After verification, confirm spec creation and offer options:
+- Proceed with implementation
+- Refine specific sections
+- Save for later
 
-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
+## Guidance (Not Rules)
 
-## Step 7: Link to Session Context
+These patterns tend to work well, but adapt as needed:
 
-Add a reference to the spec in `<git-root>/.bonfire/index.md` under Current State.
+**Research before interviewing** - Findings make questions specific and valuable.
 
-## Step 8: Confirm
+**Three interview rounds** - Core decisions → Edge cases → Testing & scope. But collapse if user is time-constrained.
 
-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
+**Show your work** - Tell user what you're doing: "Researching...", "Starting interview...", "Writing spec..."
 
-## Interview Tips
+**Fallback gracefully** - If subagent fails, do the work in main context. Warn user but don't stop.
 
-**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)
+**Large codebases** - Explorer may need multiple passes. Offer to continue if findings seem incomplete.
 
-**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?"
+## Anti-Patterns
 
-## Spec Lifecycle
+**Don't ask generic questions** - "What features do you want?" wastes an interview slot.
 
-Specs are **temporary artifacts** - they exist to guide implementation:
+**Don't skip the interview** - Research alone misses user intent. Interview alone misses codebase reality.
 
-1. **Draft** → Created, ready for review
-2. **In Progress** → Being implemented
-3. **Completed** → Implementation done
+**Don't write without verification** - Subagents can produce partial output. Always check.
 
-**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
+**Don't over-specify implementation** - Steps should guide, not micromanage. Leave room for implementation judgment.

package/package.json

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