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:

Tell the user: "No bonfire directory found. Let me set that up for you."

Use AskUserQuestion to ask setup questions (4 questions, one round):

"Where should specs be saved?" (Header: "Specs")

• .bonfire/specs/ (Default) - Keep with session context

• specs/ - Project root level

"Where should docs be saved?" (Header: "Docs")

• .bonfire/docs/ (Default) - Keep with session context

• docs/ - Project root level

"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

"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):

• "Set up bonfire hooks?" (Header: "Hooks")

• Yes (Recommended) - Context preservation + archive suggestions

• No - Skip hook setup

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/

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

Create config.json with user's answers:

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

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:

External Links:

• Issue Tracker

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]

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/

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:

• Determine project name: Use package.json name, git remote, or directory name

• Task list ID: bonfire-<project-name> (e.g., bonfire-my-app )

• Check for existing tasks:

• If tasks exist in this list, display: "Continuing work from previous session. Active tasks: [summary]"

• If no tasks, proceed normally

• 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:

• "I'll archive now" - User will run /bonfire-archive

• "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:

• Use linear-cli to fetch the issue: linear issue view ENG-123

• Extract: title, description, state, priority, labels, assignee

• On success: Summarize the issue context

• 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?"