add(plugin): bonfire — session-context workflow tooling

Adapted from PR #108 by @vieko (Vercel).
Original: https://github.com/anthropics/claude-plugins-official/pull/108

external_plugins/bonfire/commands/archive.md

@@ -0,0 +1,126 @@
+---
+description: Archive completed session work
+allowed-tools: Bash(git:*), Read, Write, Glob, mcp__linear__*
+model: haiku
+---
+
+# Archive Session
+
+## Step 1: Find Git Root
+
+Run `git rev-parse --show-toplevel` to locate the repository root.
+
+## Step 2: Review Completed Work
+
+Read `<git-root>/.bonfire/index.md` and identify completed work:
+- Sessions with merged PRs
+- Completed features/tasks
+- Work that's no longer active
+
+## Step 3: Create Archive Entry
+
+Move completed session content to `<git-root>/.bonfire/archive/`.
+
+**Naming convention**: `YYYY-MM-DD-<issue-id>-<topic>.md`
+
+Examples:
+- `2025-12-22-GTMENG-387-inbound-improvements.md` (with issue ID)
+- `2025-12-22-fix-login-redirect.md` (without issue ID)
+
+Use this template:
+```markdown
+# [TOPIC]
+
+**Date**: [DATE]
+**Issue**: [ISSUE-ID or N/A]
+**PR**: [PR link if available]
+**Status**: Completed
+
+---
+
+## Summary
+
+[Brief description of what was accomplished]
+
+## Accomplished
+
+- [List of completed items]
+
+## Decisions Made
+
+- [Key decisions and rationale]
+
+## Impact
+
+- [Before/after metrics if applicable]
+- Files changed: [count]
+
+## Related
+
+- [Links to related docs, specs, or code]
+```
+
+## Step 4: Clean Up Index
+
+Update `<git-root>/.bonfire/index.md`:
+- Remove archived session entries from Recent Sessions
+- Keep Current State focused on active work
+- Update Next Session Priorities
+- Add link to archive file in Archived Sessions section:
+  ```markdown
+  ## Archived Sessions
+
+  - [YYYY-MM-DD - Topic](archive/YYYY-MM-DD-issue-topic.md)
+  ```
+
+## Step 5: Clean Up Specs (if applicable)
+
+Read `specsLocation` from `<git-root>/.bonfire/config.json` (default `.bonfire/specs/`).
+
+Check if any specs in the configured location are now complete:
+- If the spec was fully implemented, delete the spec file (archive has the record)
+- If the spec has reusable reference material, move that content to `docs/` first
+
+## Step 6: Update Linear Issue (if applicable)
+
+Read `<git-root>/.bonfire/config.json` and check `linearEnabled`.
+
+**If `linearEnabled` is true**:
+
+1. Check if archived work references a Linear issue (look in session context for `[A-Z]+-[0-9]+` pattern)
+2. If Linear issue found, ask user: "Mark Linear issue [ISSUE-ID] as Done?"
+3. If user confirms:
+   - Use Linear MCP `linear_update_issue` tool with:
+     - `id`: The issue ID (e.g., `ENG-123`)
+     - `status`: Set to "Done" or completed state
+   - Optionally use `linear_add_comment` to add link to archive/PR
+4. On failure: Warn user - "Couldn't update Linear issue. You may need to update it manually."
+
+Note: Tool names may vary by Linear MCP implementation.
+
+**If `linearEnabled` is false or not set**: Skip this step.
+
+## Step 7: Commit Archive (if tracked)
+
+Read `gitStrategy` from `<git-root>/.bonfire/config.json`.
+
+**If gitStrategy is "ignore-all"**: Skip committing - archive is local only.
+
+**If gitStrategy is "hybrid" or "commit-all"**:
+1. **NEVER use `git add -f`** - respect gitignore
+2. Stage unignored files:
+   ```bash
+   git add .bonfire/
+   ```
+3. Check if anything was staged before committing:
+   ```bash
+   git diff --cached --quiet .bonfire/ || git commit -m "docs: archive completed session work"
+   ```
+
+## Step 8: Confirm
+
+Report:
+- What was archived
+- Any specs cleaned up
+- Current state of index.md
+- Ready for next session

external_plugins/bonfire/commands/configure.md

@@ -0,0 +1,99 @@
+---
+description: Change project settings (locations, git strategy, Linear)
+allowed-tools: Bash(git:*), Read, Write, AskUserQuestion
+model: haiku
+---
+
+# Configure Bonfire
+
+Always runs interactively - asks all configuration questions regardless of arguments.
+
+## Step 1: Find Git Root
+
+Run `git rev-parse --show-toplevel` to locate the repository root.
+
+## Step 2: Check for Bonfire Directory
+
+If `<git-root>/.bonfire/` does not exist, tell the user to run `/bonfire:start` first.
+
+## Step 3: Read Current Config
+
+Read `<git-root>/.bonfire/config.json` if it exists to see current settings.
+
+## Step 4: Ask All Configuration Questions
+
+Use AskUserQuestion to ask configuration questions (4 questions, one round):
+
+1. "Where should specs be saved?" (Header: "Specs")
+   - .bonfire/specs/ (Recommended) - Keep with session context
+   - specs/ - Project root level
+
+2. "Where should docs be saved?" (Header: "Docs")
+   - .bonfire/docs/ (Recommended) - Keep with session context
+   - docs/ - Project root level
+
+3. "How should `.bonfire/` be handled in git?" (Header: "Git")
+   - ignore-all (Recommended) - Keep sessions private/local
+   - hybrid - Commit docs/specs, keep notes private
+   - commit-all - Share everything with team
+
+4. "Enable Linear MCP integration?" (Header: "Linear")
+   - No (Recommended) - Skip Linear integration
+   - Yes - Fetch/create Linear issues (requires Linear MCP)
+
+## Step 5: Update Config
+
+**Completely overwrite** `<git-root>/.bonfire/config.json` with only these fields (do not preserve old fields like `models`):
+
+```json
+{
+  "specsLocation": "<user-answer>",
+  "docsLocation": "<user-answer>",
+  "gitStrategy": "<user-answer>",
+  "linearEnabled": <true-or-false>
+}
+```
+
+## Step 6: Update Git Strategy
+
+If git strategy or locations changed, update `<git-root>/.bonfire/.gitignore`:
+
+**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/
+scripts/
+```
+
+If switching FROM commit/hybrid TO ignore:
+- Warn user that existing tracked files will remain tracked
+- Offer to run: `git rm -r --cached .bonfire/`
+
+## Step 7: Confirm
+
+Report:
+- Settings updated
+- Any manual steps needed (git cleanup)
+- New configuration summary

external_plugins/bonfire/commands/document.md

@@ -0,0 +1,114 @@
+---
+description: Create documentation about a topic in the codebase
+allowed-tools: Read, Write, Bash(git:*), Task
+---
+
+# Document Topic
+
+Create reference documentation using subagent for research, preserving main 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.
+
+**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)
+
+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.
+
+## Step 5: Create Documentation
+
+**Naming convention**: `<topic>.md` (kebab-case)
+
+Examples:
+- `inbound-agent-architecture.md`
+- `sampling-strategies.md`
+- `authentication-flow.md`
+
+Write the documentation to `<git-root>/<docsLocation>/<topic>.md`
+
+Structure the documentation using the research findings:
+
+```markdown
+# [TOPIC]
+
+## Overview
+
+[What this is and why it exists - synthesized from research]
+
+## Architecture
+
+[How it's structured - from research findings]
+
+```mermaid
+flowchart TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `path/to/file.ts` | [From research findings] |
+| `path/to/other.ts` | [From research findings] |
+
+## How It Works
+
+[Step-by-step flow and behavior - from research]
+
+## Usage Examples
+
+[Code examples, CLI commands, etc.]
+
+## Gotchas
+
+- [From research findings]
+- [Common mistakes or edge cases]
+
+## Related
+
+- [Link to related doc](other-doc.md)
+- [Code reference]: `path/to/file.ts`
+```
+
+## Step 6: Link to Session Context
+
+Add a reference to the doc in `<git-root>/.bonfire/index.md` under Key Resources or Notes.
+
+## Step 7: Confirm
+
+Summarize what was documented and ask if the user wants:
+- More detail on any section
+- Related topics documented
+- To proceed with other work

external_plugins/bonfire/commands/end.md

@@ -0,0 +1,84 @@
+---
+description: End session - update context and commit changes
+allowed-tools: Bash(git:*), Bash(rm:*), Bash(mv:*), Bash(mkdir:*), Read, Write, Glob, AskUserQuestion
+model: haiku
+---
+
+# End Session
+
+## Step 1: Find Git Root
+
+Run `git rev-parse --show-toplevel` to locate the repository root.
+
+## Step 2: Review Session Work
+
+Review what was accomplished this session by examining:
+- Recent git commits
+- Files changed
+- Conversation context
+
+## Step 3: Update Session Context
+
+Update `<git-root>/.bonfire/index.md`:
+
+1. Update the session entry with:
+   - **Accomplished**: List what was completed
+   - **Decisions**: Key decisions made and rationale
+   - **Files Modified**: Important files changed (if relevant)
+   - **Blockers**: Any issues encountered
+
+2. Update "Next Session Priorities" based on remaining work
+
+3. Update "Current State" to reflect new status
+
+## Step 4: Manage Session Scripts
+
+Check if `<git-root>/.bonfire/scripts/` exists and contains any files.
+
+**If scripts exist**, use AskUserQuestion to ask what to do with each script:
+
+"What should happen to these session scripts?" (Header: "Scripts", multiSelect: false)
+
+For each script found, present options:
+- **Keep** - Leave in `.bonfire/scripts/` for next session
+- **Move to project** - Move to `<git-root>/scripts/` (create if needed)
+- **Delete** - Remove the script
+
+Execute the user's choices:
+- **Keep**: No action needed
+- **Move to project**: `mkdir -p <git-root>/scripts/ && mv <script> <git-root>/scripts/`
+- **Delete**: `rm <script>`
+
+**If no scripts exist**, skip this step.
+
+## Step 5: Commit Changes (if tracked)
+
+Read `<git-root>/.bonfire/config.json` to check `gitStrategy`.
+
+**If gitStrategy is "ignore-all"**: Skip committing - nothing is tracked. Tell the user session context was updated locally.
+
+**If gitStrategy is "hybrid" or "commit-all"**:
+
+1. **Check what can be staged**: Run `git status .bonfire/` to see what files are not ignored
+2. **NEVER use `git add -f`** - if a file is gitignored, respect that
+3. **Stage only unignored files**:
+   ```bash
+   git add .bonfire/
+   ```
+4. **Check if anything was staged**: Run `git diff --cached --quiet .bonfire/`
+   - If nothing staged (exit code 0), tell user "Session context updated locally (files are gitignored)"
+   - If changes staged, commit:
+     ```bash
+     git commit -m "docs: update session context"
+     ```
+
+If the commit fails due to hooks, help resolve the issue (but never bypass hooks with `--no-verify`).
+
+## Step 6: Confirm
+
+Summarize:
+- What was documented
+- Next priorities
+- Any follow-up needed
+
+Let the user know they can run `/bonfire:archive` when this work is merged and complete.

external_plugins/bonfire/commands/git-strategy.md

@@ -0,0 +1,94 @@
+---
+description: Change how .bonfire/ is handled in git
+allowed-tools: Bash(git:*), Read, Write, AskUserQuestion
+model: haiku
+---
+
+# Change Git Strategy
+
+## Step 1: Find Git Root
+
+Run `git rev-parse --show-toplevel` to locate the repository root.
+
+## Step 2: Read Current Config
+
+Read `<git-root>/.bonfire/config.json` to check current `specsLocation` and `docsLocation` settings.
+
+## Step 3: Explain Options
+
+Present the git strategy options:
+
+1. **Ignore all** - Keep sessions completely local
+   - Everything in .bonfire/ is gitignored
+   - Most private, nothing shared
+   - Good for: solo work, sensitive projects
+
+2. **Hybrid** - Commit docs/specs, keep notes private
+   - docs/ and specs/ are committed
+   - index.md and archive/ stay local
+   - Good for: teams that want shared docs but private notes
+
+3. **Commit all** - Share everything with team
+   - All session content is committed
+   - Only data/ and scratch/ ignored
+   - Good for: full transparency, team continuity
+
+## Step 4: Get User Choice
+
+Use AskUserQuestion to ask which strategy:
+
+"Which git strategy for `.bonfire/`?" (Header: "Git")
+- ignore-all (Recommended) - Keep sessions private/local
+- hybrid - Commit docs/specs, keep notes private
+- commit-all - Share everything with team
+
+## Step 5: Update .gitignore
+
+Write the appropriate `.gitignore` to `<git-root>/.bonfire/.gitignore`:
+
+**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/
+scripts/
+```
+
+## Step 6: Handle Git Tracking
+
+If switching FROM commit/hybrid TO ignore:
+- Warn user that existing tracked files will remain tracked
+- Offer to run: `git rm -r --cached .bonfire/` (removes from git but keeps files)
+- They'll need to commit this change
+
+If switching TO commit/hybrid:
+- Files will be picked up on next commit
+- No special action needed
+
+## Step 7: Confirm
+
+Report:
+- New strategy applied
+- Any manual steps needed
+- How to verify the change

external_plugins/bonfire/commands/review.md

@@ -0,0 +1,119 @@
+---
+description: Review work for blindspots, gaps, and improvements
+allowed-tools: Bash(git:*), Bash(gh:*), Read, Write, Task, mcp__linear__*
+---
+
+# 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)
+
+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.
+
+## Step 4: Session Scripts Review
+
+Check if `<git-root>/.bonfire/scripts/` contains any files.
+
+If scripts exist, include in findings:
+- List scripts that may need attention
+- Note if any appear to be temporary/one-off vs reusable
+- Suggest moving useful scripts to project `scripts/` directory
+
+This is informational - actual script management happens during `/bonfire:end`.
+
+## Step 5: 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 6: 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 MCP `linear_create_issue` tool with:
+   - `title`: Finding summary
+   - `description`: Finding details with context
+   - `teamId`: Infer from session context if available, otherwise use default
+2. On success: Return issue URL/ID
+3. On failure: Warn user, offer to create GitHub issue instead
+
+Note: Tool names may vary by Linear MCP implementation.
+
+**For each created issue:**
+- Record the issue ID and URL
+- Note which tracker (GitHub/Linear) was used
+
+## Step 7: Update Session Context
+
+Add review outcomes to `<git-root>/.bonfire/index.md`:
+- Key findings noted
+- Issues created (with links)
+- Work deferred to future sessions

external_plugins/bonfire/commands/spec.md

@@ -0,0 +1,149 @@
+---
+description: Create an implementation spec for a feature or task
+allowed-tools: Read, Write, Bash(git:*), AskUserQuestion, 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)
+
+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 & Architecture**: How similar features are implemented, existing abstractions to reuse, naming conventions
+2. **Technical 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.
+
+## Step 5: Interview Phase (Main Context)
+
+Using the research findings, interview the user with **informed questions** via AskUserQuestion.
+
+### Round 1: 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
+
+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: Scope & Boundaries (if needed)
+
+If scope is still unclear:
+- What's explicitly out of scope?
+- MVP vs full implementation?
+- Dependencies on other work?
+
+### Continue Until Complete
+
+Keep asking rounds of questions until you have clarity on:
+- [ ] Core approach and architecture
+- [ ] Key technical decisions
+- [ ] Error handling strategy
+- [ ] Edge cases covered
+- [ ] Testing approach
+- [ ] Scope boundaries
+
+Tell the user "I have enough to write the spec" when ready.
+
+## Step 6: Write the Spec (Subagent)
+
+Use the Task tool to invoke the **spec-writer** subagent.
+
+Provide:
+1. **Research findings** from Step 4
+2. **Interview Q&A** from Step 5
+3. **Metadata**: topic, issue ID, output path (`<git-root>/<specsLocation>/<filename>.md`)
+
+The subagent will write the spec file directly.
+
+**Naming convention**: `<issue-id>-<topic>.md` or `<topic>.md`
+
+## 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

external_plugins/bonfire/commands/start.md

@@ -0,0 +1,246 @@
+---
+description: Start a new session - reads context and scaffolds .bonfire/ if needed
+allowed-tools: Bash(git:*), Bash(gh:*), Bash(mkdir:*), Read, Write, Glob, AskUserQuestion, mcp__linear__*
+model: haiku
+---
+
+# 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 AskUserQuestion to ask setup questions (4 questions, one round):
+
+   1. "Where should specs be saved?" (Header: "Specs")
+      - .bonfire/specs/ (Recommended) - Keep with session context
+      - specs/ - Project root level
+
+   2. "Where should docs be saved?" (Header: "Docs")
+      - .bonfire/docs/ (Recommended) - Keep with session context
+      - docs/ - Project root level
+
+   3. "How should `.bonfire/` be handled in git?" (Header: "Git")
+      - ignore-all (Recommended) - Keep sessions private/local
+      - hybrid - Commit docs/specs, keep notes private
+      - commit-all - Share everything with team
+
+   4. "Enable Linear MCP integration?" (Header: "Linear")
+      - No (Recommended) - Skip Linear integration
+      - Yes - Fetch/create Linear issues (requires Linear MCP)
+
+3. Create the directory structure based on user choices:
+
+   **Always create in .bonfire/**:
+   ```
+   .bonfire/
+   ├── index.md
+   ├── config.json
+   ├── archive/
+   ├── scripts/
+   └── .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/
+   scripts/
+   ```
+
+**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 MCP `linear_search_issues` tool to find the issue by ID (e.g., `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. Linear MCP may not be configured. Continue without issue context?"
+
+Note: Tool names may vary by Linear MCP implementation. Common tools: `linear_search_issues`, `linear_create_issue`, `linear_update_issue`.
+
+### 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.