npm - opencode-bonfire - Versions diffs - 1.4.0 → 2.0.0 - Mend

opencode-bonfire 1.4.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md +12 -10
package/files/agent/writer.md +127 -0
package/files/command/bonfire-configure.md +49 -4
package/files/command/bonfire-document.md +61 -134
package/files/command/bonfire-review-pr.md +45 -91
package/files/command/bonfire-spec.md +68 -226
package/files/command/bonfire-strategic.md +166 -0
package/files/opencode.json +0 -3
package/package.json +1 -1
package/files/agent/doc-writer.md +0 -120
package/files/agent/spec-writer.md +0 -142
package/files/command/bonfire-git-strategy.md +0 -91
package/files/command/bonfire-handoff.md +0 -168
package/files/command/bonfire-poc.md +0 -332
package/files/command/bonfire-prd.md +0 -332
package/files/command/bonfire-rfc.md +0 -267
package/files/skill/handoff-awareness/SKILL.md +0 -64

package/files/command/bonfire-review-pr.md CHANGED Viewed

@@ -19,25 +19,7 @@ If no PR number provided:
 >
 > 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
+## Step 2: Fetch PR Metadata
 Get PR details:
@@ -55,7 +37,7 @@ Extract and store:
 - `url` - PR URL
 - `files` - Changed files list
-## Step 4: Find Git Root and Compute Paths
+## Step 3: Compute Worktree Path
 ```bash
 git rev-parse --show-toplevel
@@ -65,7 +47,7 @@ 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
+## Step 4: Create Worktree
 Create isolated worktree for PR branch:
@@ -82,85 +64,78 @@ git worktree add <worktree-path> origin/<headRefName>
    - No: Abort
 3. If other error: Report error and abort with suggestion to check `git worktree list`
-## Step 6: Get PR Diff Summary
+## Step 5: Get PR Diff
 Get the diff for context:
 ```bash
-cd <worktree-path> && git diff origin/<baseRefName>...HEAD --stat
+git -C <worktree-path> diff origin/<baseRefName>...HEAD --stat
 ```
 Get changed files:
 ```bash
-cd <worktree-path> && git diff origin/<baseRefName>...HEAD --name-only
+git -C <worktree-path> 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
+## Step 6: Run Review (Subagent)
-You are reviewing PR #<number> in an isolated worktree.
+**Progress**: Tell the user "Reviewing PR for blindspots and gaps..."
-### Step 1: Run Review
+Use the Task tool to invoke the **work-reviewer** agent.
-Use the task tool to invoke the **work-reviewer** subagent:
+Provide the review context:
 ```
 Review this pull request for blindspots, gaps, and improvements.
 **Scope**: PR #<number> - <title>
+**PR Description**:
+<body from PR>
 **Files changed**:
 <list of changed files>
-**PR Description**:
-<body>
+**Worktree path**: <worktree-path>
+Read the changed files from the worktree to understand the actual changes.
 Return categorized findings with severity, effort, and specific file:line references.
 ```
-### Step 2: Present Findings
+**Wait for the subagent to return findings** before proceeding.
+### Review Validation
+After the subagent returns, validate the response:
-After review completes, present findings grouped by severity.
+**Valid response contains:**
+- Findings with file:line references where applicable
+- Severity categorization
-For each finding, note:
+**On subagent failure**: Fall back to in-context review using the diff.
+## Step 7: Present Findings
+Present the findings grouped by severity:
+For each finding, show:
 - File and line number (if applicable)
 - Severity (critical/moderate/minor)
 - Description
-### Step 3: Batch Comment Selection
+## Step 8: 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
+Use the question tool with options:
+1. "All" - post all findings
+2. "Select" - user will specify which ones (e.g., "1, 3, 5")
 3. "None" - skip commenting
-### Step 4: Post Inline Comments
+If "Select" chosen, ask which finding numbers to post.
+## Step 9: Post Comments
 For each selected finding with a file:line reference, post an inline comment:
@@ -186,44 +161,23 @@ gh pr comment <number> --body "**Review Finding**
 *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.
+**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, post it as a general PR comment instead.
-### Step 5: Offer Cleanup
+## Step 10: Cleanup Worktree
 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
+## Step 11: Confirm
-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.
+Summarize:
+- PR reviewed: #<number> - <title>
+- Findings: <count> total, <posted> posted as comments
+- PR URL for reference
+- Worktree status (cleaned up or retained)

package/files/command/bonfire-spec.md CHANGED Viewed

@@ -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.