Start Session

Git root: !git rev-parse --show-toplevel Current branch: !git branch --show-current

Step 1: 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/ (Default) – Keep with session context
      • specs/ – Project root level

   2. “Where should docs be saved?” (Header: “Docs”)

      • .bonfire/docs/ (Default) – Keep with session context
      • docs/ – Project root level

   3. “How should .bonfire/ be handled in git?” (Header: “Git”)

      • ignore-all (Default) – Keep sessions private/local
      • hybrid – Commit docs/specs, keep notes private
      • commit-all – Share everything with team

   4. “Enable Linear integration?” (Header: “Linear”)

      • No (Default) – Skip Linear integration
      • Yes – Fetch/create Linear issues (requires linear-cli)

   Then ask a second round (1 question):

   5. “Set up bonfire hooks?” (Header: “Hooks”)
      • Yes (Recommended) – Context preservation + archive suggestions
      • No – Skip hook setup

3. Create the directory structure based on user choices:

   Always create in .bonfire/:

   .bonfire/
   ├── index.md
   ├── config.json
   ├── archive/
   └── .gitignore
   

   If specsLocation is .bonfire/specs/: create .bonfire/specs/ If specsLocation is specs/: create <git-root>/specs/

   If docsLocation is .bonfire/docs/: create .bonfire/docs/ If docsLocation is docs/: create <git-root>/docs/

4. Detect project name from: package.json name → git remote → directory name

5. Create config.json with user’s answers:

   {
     "specsLocation": "<user-answer>",
     "docsLocation": "<user-answer>",
     "gitStrategy": "<user-answer>",
     "linearEnabled": <true-or-false>
   }
   

6. Create index.md with template:

   # 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)
   
   ---
   
   ## Codemap
   
   **Entry Points** (user-curated):
   - [Add main entry points here]
   
   **Core Components** (user-curated):
   - [Add key directories/modules here]
   
   **This Session's Key Files** (auto-updated):
   - [Files will be added by /bonfire-end]
   
   ---
   
   ## 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/
   

8. If user answered “Yes” to hooks, set up bonfire hooks:

   Create <git-root>/.claude/ directory if it doesn’t exist.

   Create or merge into <git-root>/.claude/settings.json:

   {
     "hooks": {
       "PreCompact": [
         {
           "matcher": "*",
           "hooks": [
             {
               "type": "command",
               "command": "echo '## Session Context (preserved before compaction)' && head -100 \"$(git rev-parse --show-toplevel)/.bonfire/index.md\" 2>/dev/null || echo 'No session context found'"
             }
           ]
         }
       ],
       "PostToolUse": [
         {
           "matcher": "Bash",
           "hooks": [
             {
               "type": "command",
               "command": "if echo \"$TOOL_INPUT\" | grep -qE 'gh pr (merge|close)'; then echo 'PR merged/closed! Run /bonfire-archive to archive this session.'; fi"
             }
           ]
         }
       ]
     }
   }
   

   If settings.json already exists, merge hooks carefully (preserve existing hooks).

If .bonfire/ EXISTS, proceed to Step 2.

Step 2: Check/Update CLAUDE.md

Check if <git-root>/CLAUDE.md exists.

If CLAUDE.md does NOT exist, create it:

# [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:

## Session Context

Read `.bonfire/index.md` for current project state, recent work, and priorities.

Step 3: Tasks Integration

Set up the project task list for cross-session persistence:

1. Determine project name: Use package.json name, git remote, or directory name
2. Task list ID: bonfire-<project-name> (e.g., bonfire-my-app)
3. Check for existing tasks:
   • If tasks exist in this list, display: “Continuing work from previous session. Active tasks: [summary]”
   • If no tasks, proceed normally
4. Set environment context: The task list will persist work items across sessions

Note: Tasks are complementary to index.md:

• Tasks = active checklist (what to do)
• index.md = narrative context (why, decisions, history)

Step 4: Read Session Context

Read <git-root>/.bonfire/index.md and report when ready.

Summarize:

• Current state
• Recent work
• Next priorities

Step 4.5: Size Warning

After reading index.md, estimate its size (rough token estimate: character count / 4).

If estimated tokens > 20,000, display a prominent warning:

=== SESSION CONTEXT TOO LARGE ===

Your .bonfire/index.md is ~[N]K tokens, which may cause read errors.

Run /bonfire-archive to clean up old sessions.

Then use AskUserQuestion to confirm how to proceed:

1. “I’ll archive now” – User will run /bonfire-archive
2. “Continue anyway” – Proceed with potentially truncated context

If estimated tokens <= 20,000: Continue to Step 5 without warning.

Step 5: Fetch External Context (Optional)

Only fetch if user provides a new URL or issue ID:

Detecting Issue Type

• GitHub: Starts with #, contains github.com, or doesn’t match Linear pattern
• Linear: Matches [A-Z]+-[0-9]+ pattern (e.g., ENG-123, ABC-456) or contains linear.app

GitHub Issues/PRs

Use gh CLI:

• gh pr view [URL] --json title,body,state,labels
• gh issue view [URL] --json title,body,state,labels

Linear Issues

First, read <git-root>/.bonfire/config.json and check linearEnabled.

If linearEnabled is false or not set: Skip Linear, treat as ad-hoc task.

If linearEnabled is true:

1. Use linear-cli to fetch the issue:

   linear issue view ENG-123
   

2. Extract: title, description, state, priority, labels, assignee
3. On success: Summarize the issue context
4. On failure: Warn user – “Couldn’t fetch Linear issue. Is linear-cli installed and authenticated? Continue without issue context?”

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

Then ask: “What do you want to work on this session?”