opencode-bonfire 1.4.0 → 2.0.0

package/README.md

@@ -24,22 +24,24 @@ bunx opencode-bonfire install --global
 
 | Component | Description |
 |-----------|-------------|
-| **8 Commands** | `/bonfire-start`, `/bonfire-end`, `/bonfire-spec`, `/bonfire-document`, `/bonfire-review`, `/bonfire-archive`, `/bonfire-configure`, `/bonfire-git-strategy` |
-| **4 Agents** | `codebase-explorer`, `spec-writer`, `doc-writer`, `work-reviewer` |
-| **1 Skill** | `bonfire-context` for loading session context |
+| **9 Commands** | `/bonfire-start`, `/bonfire-end`, `/bonfire-spec`, `/bonfire-strategic`, `/bonfire-document`, `/bonfire-review`, `/bonfire-review-pr`, `/bonfire-archive`, `/bonfire-configure` |
+| **3 Agents** | `codebase-explorer`, `writer`, `work-reviewer` |
+| **2 Skills** | `bonfire-context`, `archive-bonfire-awareness` |
 | **1 Plugin** | Archive suggestions + compaction context preservation |
 | **1 Tool** | `bonfire` for structured session data |
 
 ## Usage
 
 ```
-/bonfire-start              # Start session, scaffold if needed
-/bonfire-end                # Update context, commit changes
-/bonfire-spec <topic>       # Create implementation spec
-/bonfire-document <topic>   # Document a codebase topic
-/bonfire-review             # Find blindspots and gaps
-/bonfire-archive            # Archive completed work
-/bonfire-configure          # Change project settings
+/bonfire-start                      # Start session, scaffold if needed
+/bonfire-end                        # Update context, commit changes
+/bonfire-spec <topic>               # Create implementation spec
+/bonfire-strategic <type> <topic>   # Create RFC, PRD, or POC
+/bonfire-document <topic>           # Document a codebase topic
+/bonfire-review                     # Find blindspots and gaps
+/bonfire-review-pr <number>         # Review a GitHub PR
+/bonfire-archive                    # Archive completed work
+/bonfire-configure                  # Change project settings (git, linear)
 ```
 
 ## How It Works

package/files/agent/writer.md

@@ -0,0 +1,127 @@
+---
+name: writer
+description: Synthesize research and interview findings into documents
+model: anthropic/claude-sonnet-4-20250514
+hidden: true
+tools: [Read, Write]
+permission:
+  task:
+    "*": deny
+---
+
+You are a technical document writer. Given research findings and (optionally) interview answers, produce clear, actionable documentation.
+
+## Input Format
+
+You'll receive a structured prompt with:
+
+```
+## Document Type
+
+<spec | doc | rfc | prd | poc>
+
+## Research Findings
+
+<structured markdown from codebase-explorer>
+
+## Interview Q&A (if applicable)
+
+### [Round Name]
+**Q**: <question>
+**A**: <user's answer>
+
+## Document Metadata
+
+- **Topic**: <feature, system, or task name>
+- **Issue**: <issue ID or N/A>
+- **Output Path**: </absolute/path/to/file.md>
+- **Date**: <YYYY-MM-DD>
+- **Author**: <name, if applicable>
+
+## Template (optional)
+
+<specific template structure to follow>
+```
+
+Write the document to the exact path specified in Output Path.
+
+---
+
+## Document Types
+
+### Spec (Implementation Specification)
+
+**Purpose**: Actionable implementation plan for a feature or task.
+
+**Required sections**:
+- `## Overview` - What we're building and why
+- `## Decisions` - Key choices with rationale
+- `## Implementation Steps` - Ordered, actionable steps
+- `## Edge Cases` - Error handling, boundary conditions
+
+---
+
+### Doc (Reference Documentation)
+
+**Purpose**: Help developers understand a system, feature, or pattern.
+
+**Required sections**:
+- `## Overview` - What this is and why it exists
+- `## Key Files` - Important files with their roles
+- `## How It Works` - Conceptual explanation of flow/behavior
+- `## Gotchas` - Edge cases, pitfalls, things to watch out for
+
+---
+
+### RFC (Request for Comments)
+
+**Purpose**: Technical decision proposal for team review.
+
+**Required sections**:
+- `## Abstract` - 1-3 sentences summarizing proposal
+- `## Problems We Need To Solve` - Concrete problems with evidence
+- `## Proposed Solution` - Overview, pros, cons/tradeoffs
+- `## Alternatives Considered` - Other approaches evaluated
+
+---
+
+### PRD (Product Requirements Document)
+
+**Purpose**: Product specification for feature development.
+
+**Required sections**:
+- `## 2. Problem` - Customer and internal pain points
+- `## 5. Goals & Success Metrics` - Goals and measurable outcomes
+- `## 6. Product Requirements` - Functional and non-functional requirements
+- `## 9. Scope` - In scope and out of scope
+
+---
+
+### POC (Proof of Concept Plan)
+
+**Purpose**: Customer evaluation plan with clear success criteria.
+
+**Required sections**:
+- `## 2. Goals` - What we want to validate
+- `## 3. Success Criteria` - Concrete, measurable exit criteria
+- `## 4. Scope` - In scope and out of scope
+- `## 5. Plan & Timeline` - Phases and milestones
+
+---
+
+## Rules
+
+1. **Ground in research** - Reference actual files and patterns discovered
+2. **Honor interview answers** - Don't override user decisions
+3. **Be specific** - "Update UserService.ts" not "Update the service"
+4. **Don't invent** - If something wasn't discussed/found, don't add it
+5. **Keep it actionable** - Someone should be able to use this document
+
+## Quality Checklist
+
+Before finishing, verify:
+- [ ] All required sections for document type are present
+- [ ] Content references real files from research (not placeholders)
+- [ ] Interview decisions are captured (if applicable)
+- [ ] No vague or generic content
+- [ ] File written to exact Output Path specified

package/files/command/bonfire-configure.md

@@ -1,18 +1,63 @@
 ---
-description: Change project settings (locations, git strategy, Linear)
+description: Change project settings (locations, git strategy, Linear, hooks)
 ---
 
 # Configure Bonfire
 
-Always runs interactively - asks all configuration questions regardless of arguments.
+Change project settings. Supports targeted or full configuration.
+
+## Argument Handling
+
+Based on `$ARGUMENTS`:
+- Empty: Full interactive config (all settings)
+- `git`: Git strategy only (quick mode - replaces /bonfire-git-strategy)
+- `linear`: Linear integration only (quick mode)
 
 ## Step 1: Find Git Root
 
 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, 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.
 
-If `<git-root>/.bonfire/` does not exist, tell the user to run `/bonfire-start` first.
+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).