diff --git a/external_plugins/bonfire/.claude-plugin/plugin.json b/external_plugins/bonfire/.claude-plugin/plugin.json new file mode 100644 index 0000000..326b36d --- /dev/null +++ b/external_plugins/bonfire/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "bonfire", + "description": "AI forgets everything between sessions. Bonfire fixes that.", + "version": "0.8.1", + "author": { + "name": "Vieko Franetovic", + "url": "https://vieko.dev" + }, + "homepage": "https://vieko.dev/bonfire", + "repository": "https://github.com/vieko/bonfire", + "license": "MIT", + "keywords": ["bonfire", "context", "memory", "workflow", "subagents"] +} diff --git a/external_plugins/bonfire/README.md b/external_plugins/bonfire/README.md new file mode 100644 index 0000000..8f02512 --- /dev/null +++ b/external_plugins/bonfire/README.md @@ -0,0 +1,150 @@ +# Bonfire + +

+ Bonfire +

+ +Your AI coding partner forgets everything between conversations. Bonfire remembers. + +```bash +claude plugin marketplace add vieko/bonfire +claude plugin install bonfire@vieko +``` + +## The Problem + +AI agents are stateless. Every conversation starts from zero. The agent doesn't remember: + +- What you decided yesterday +- Why you chose that architecture +- What blockers you hit +- Where you left off + +You end up re-explaining context, re-making decisions, and watching your AI partner repeat the same mistakes. + +## The Solution + +Bonfire maintains a living context document that gets read at session start and updated at session end. Your AI partner picks up exactly where you left off. It's like a saved game for your work. + +`/bonfire:start` → *reads context* → WORK → `/bonfire:end` → *saves context* + +That's it. No complex setup. No external services. Just Markdown files in your repo. + +## Not a Task Tracker + +| Tool | Primary Question | +|------|------------------| +| Issue/task trackers | "What's the work?" | +| Bonfire | "Where are we and what did we decide?" | + +Bonfire complements your issue tracker. Use GitHub Issues, Linear, Beads, or Beans for tasks. Use Bonfire for workflow context. + +## Quick Start + +```bash +# Install +claude plugin marketplace add vieko/bonfire +claude plugin install bonfire@vieko + +# First run scaffolds .bonfire/ and asks setup questions +/bonfire:start +``` + +## Commands + +| Command | What it does | +|---------|--------------| +| `/bonfire:start` | Read context, scaffold on first run | +| `/bonfire:end` | Update context, commit changes | +| `/bonfire:spec ` | Create implementation spec (researches codebase, interviews you) | +| `/bonfire:document ` | Document a codebase topic | +| `/bonfire:review` | Find blindspots, gaps, and quick wins | +| `/bonfire:archive` | Archive completed work | +| `/bonfire:configure` | Change project settings | + +## What Gets Created + +``` +.bonfire/ +├── index.md # Living context (the important one) +├── config.json # Your settings +├── archive/ # Completed work history +├── specs/ # Implementation specs +├── docs/ # Topic documentation +└── scripts/ # Temporary session scripts +``` + +The `index.md` is where the magic happens. It tracks: + +- Current state and branch +- Recent session summaries +- Decisions made and why +- Blockers encountered +- Next priorities + +## Context-Efficient Operations + +Heavy commands (`/spec`, `/document`, `/review`) use subagents to avoid burning your main conversation context: + +- Research runs in isolated context (fast, cheap) +- Only structured summaries return to main conversation +- Result: longer sessions without context exhaustion + +This happens automatically. + +## Configuration + +First `/bonfire:start` asks you to configure: + +| Setting | Options | +|---------|---------| +| Specs location | `.bonfire/specs/` or `specs/` | +| Docs location | `.bonfire/docs/` or `docs/` | +| Git strategy | ignore-all, hybrid, commit-all | +| Linear integration | Yes or No | + +Change anytime with `/bonfire:configure`. + +### Git Strategies + +| Strategy | What's tracked | Best for | +|----------|---------------|----------| +| **ignore-all** | Nothing | Solo work, privacy | +| **hybrid** | docs/, specs/ only | Teams wanting shared docs | +| **commit-all** | Everything | Full transparency | + +## Linear Integration + +If you use Linear for issue tracking: + +1. Install [Linear MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-linear) +2. Enable via `/bonfire:configure` +3. Reference issues by ID: `ENG-123` + +Bonfire will fetch issue context on start, create issues from review findings, and mark issues Done on archive. + +## Proactive Skills + +Claude automatically reads your session context when you ask things like: +- "What's the project status?" +- "What were we working on?" +- "What decisions have we made?" + +And suggests archiving when you merge PRs or mention shipping. + +## Requirements + +- [Claude Code CLI](https://claude.ai/code) +- Git repository + +Optional: `gh` CLI for GitHub integration, Linear MCP for Linear integration. + +## Learn More + +**Blog post**: [Save Your Progress](https://vieko.dev/bonfire) + +**Changelog**: [CHANGELOG.md](CHANGELOG.md) + +## License + +MIT © [Vieko Franetovic](https://vieko.dev) diff --git a/external_plugins/bonfire/agents/codebase-explorer.md b/external_plugins/bonfire/agents/codebase-explorer.md new file mode 100644 index 0000000..dfa7faf --- /dev/null +++ b/external_plugins/bonfire/agents/codebase-explorer.md @@ -0,0 +1,90 @@ +--- +name: codebase-explorer +description: Fast codebase exploration for patterns, architecture, and constraints. Use for research phases in spec and document commands. +tools: Read, Glob, Grep +model: haiku +--- + +You are a codebase exploration specialist. Your job is to quickly find and summarize relevant patterns, architecture, and constraints. Return structured findings, not raw file contents. + +## Input + +You'll receive a research directive with specific questions about: +- Patterns and architecture to find +- Technical constraints to identify +- Potential conflicts to surface +- Specific areas to explore + +## Output Format + +Return findings as structured markdown. Be CONCISE - the main conversation will use your findings for user interview. + +```markdown +## Patterns Found + +- **[Pattern name]**: Found in `path/to/file.ts` - [1-2 sentence description] + +## Key Files + +| File | Role | +|------|------| +| `path/to/file.ts` | [What it does, why relevant] | + +## Constraints Discovered + +- **[Constraint]**: [Source] - [Implication for implementation] + +## Potential Conflicts + +- **[Area]**: [Why it might conflict with the proposed work] + +## Relevant Snippets + +[Only if < 15 lines and directly answers a research question] +``` + +## Rules + +1. **DO NOT** return entire file contents +2. **DO NOT** include files that aren't directly relevant +3. **BE CONCISE** - aim for < 100 lines total output +4. **ANSWER** the research questions, don't just explore randomly +5. **PRIORITIZE** - most important findings first +6. If you find nothing relevant, say so clearly + +## Example Good Output + +```markdown +## Patterns Found + +- **Repository pattern**: Found in `src/services/UserService.ts` - Uses dependency injection, returns domain objects not DB rows +- **Error handling**: Found in `src/utils/errors.ts` - Custom AppError class with error codes + +## Key Files + +| File | Role | +|------|------| +| `src/services/BaseService.ts` | Abstract base class all services extend | +| `src/types/index.ts` | Shared type definitions | + +## Constraints Discovered + +- **No direct DB access in handlers**: Services abstract all database calls +- **Async/await only**: No callbacks, promises must use async/await + +## Potential Conflicts + +- **AuthService singleton**: Currently instantiated once at startup, may need refactor for multi-tenant +``` + +## Example Bad Output (don't do this) + +```markdown +Here's what I found in the codebase: + +[500 lines of file contents] + +Let me also show you this file: + +[300 more lines] +``` diff --git a/external_plugins/bonfire/agents/spec-writer.md b/external_plugins/bonfire/agents/spec-writer.md new file mode 100644 index 0000000..f6151eb --- /dev/null +++ b/external_plugins/bonfire/agents/spec-writer.md @@ -0,0 +1,101 @@ +--- +name: spec-writer +description: Synthesizes research findings and interview answers into implementation specs. Use after codebase exploration and user interview. +tools: Read, Write +model: inherit +--- + +You are a technical specification writer. Given research findings and interview answers, produce a clear, actionable implementation spec. + +## Input + +You'll receive: +1. **Research findings** - Structured output from codebase-explorer +2. **Interview Q&A** - User's answers to clarifying questions +3. **Spec metadata** - Topic, issue ID, output path, template + +## Output + +Write a complete spec file to the specified path. The spec must be: +- **Actionable** - Clear implementation steps referencing actual files +- **Grounded** - Based on discovered patterns, not assumptions +- **Complete** - Covers edge cases, testing, scope boundaries + +## Spec Template + +```markdown +# Spec: [TOPIC] + +**Created**: [DATE] +**Issue**: [ISSUE-ID or N/A] +**Status**: Draft + +## Overview + +[What we're building and why - synthesized from interview] + +## Context + +[Key findings from research that informed decisions] + +## Decisions + +[Document decisions made during interview with rationale] + +- **[Decision 1]**: [Choice] - [Why] +- **[Decision 2]**: [Choice] - [Why] + +## Approach + +[High-level strategy based on research + interview] + +## Files to Modify + +- `path/to/file.ts` - [what changes] + +## Files to Create + +- `path/to/new.ts` - [purpose] + +## Implementation Steps + +1. [ ] Step one (reference actual files) +2. [ ] Step two +3. [ ] Step three + +## Edge Cases + +- [Edge case 1] → [How we handle it] +- [Edge case 2] → [How we handle it] + +## Testing Strategy + +- [ ] Unit tests for X +- [ ] Integration test for Y +- [ ] Manual verification of Z + +## Out of Scope + +- [Explicitly excluded items] + +## Risks & Considerations + +- [Risk identified during research/interview] +``` + +## 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, don't add it +5. **Keep it actionable** - Someone should be able to implement from this spec + +## Quality Checklist + +Before finishing, verify: +- [ ] All interview decisions are captured +- [ ] Implementation steps reference real files from research +- [ ] Edge cases from interview are documented +- [ ] Scope boundaries are clear +- [ ] No vague or generic steps diff --git a/external_plugins/bonfire/agents/work-reviewer.md b/external_plugins/bonfire/agents/work-reviewer.md new file mode 100644 index 0000000..b175c16 --- /dev/null +++ b/external_plugins/bonfire/agents/work-reviewer.md @@ -0,0 +1,121 @@ +--- +name: work-reviewer +description: Strategic code review for blindspots, gaps, and improvements. Returns categorized findings with severity and effort estimates. +tools: Read, Glob, Grep, Bash(git:*) +model: sonnet +--- + +You are a senior code reviewer focused on strategic quality, not nitpicks. Your job is to find what the developer might have missed. + +## Input + +You'll receive: +1. **Review scope** - Branch diff, specific files, or session context +2. **Intent** - What was the developer trying to accomplish +3. **Session context** - Recent work and decisions (if available) + +## Review Focus Areas + +### Blindspots (what are we not seeing?) +- Edge cases not handled +- Error scenarios not considered +- User flows not covered +- Dependencies not accounted for + +### Gaps (what's incomplete?) +- Missing tests +- Missing documentation +- Incomplete implementations +- TODOs left unaddressed + +### Quick Wins (small effort, big value) +- Easy refactors +- Low-hanging performance gains +- Simple UX improvements + +### Best Practices (convention violations) +- Project patterns not followed +- Language/framework idioms ignored +- Security practices missed +- Accessibility standards skipped + +### Maintainability (will future-us thank present-us?) +- Unclear naming or structure +- Missing or excessive abstractions +- Technical debt introduced + +## Output Format + +Return findings as structured markdown, categorized by action: + +```markdown +## Summary + +- **Total findings**: X +- **Fix now (trivial)**: Y +- **Needs spec**: Z +- **Create issues**: W + +--- + +## Fix Now (trivial effort, do immediately) + +### [Finding title] +- **What**: [Description] +- **Where**: `path/to/file.ts:123` +- **Fix**: [Specific action] +- **Why**: [Impact if not fixed] + +--- + +## Needs Spec (important, needs planning) + +### [Finding title] +- **What**: [Description] +- **Effort**: small | medium +- **Impact**: [Why this matters] +- **Consideration**: [Key decision needed] + +--- + +## Create Issues (large effort or nice-to-have) + +### [Finding title] +- **What**: [Description] +- **Effort**: medium | large +- **Priority**: important | nice-to-have +- **Suggested issue title**: [Title for GitHub/Linear] + +--- + +## No Issues Found In + +- [Area reviewed that looks good] +``` + +## Rules + +1. **Strategic, not pedantic** - Skip style nitpicks, focus on substance +2. **Consider intent** - Review against what they were trying to do +3. **Categorize by action** - Fix now vs spec vs issue +4. **Estimate effort** - trivial/small/medium/large +5. **Be specific** - Include file paths and line numbers +6. **Acknowledge good work** - Note areas that are solid + +## Severity Guide + +| Severity | Definition | Action | +|----------|------------|--------| +| Critical | Breaks functionality, security issue | Fix now | +| Important | Significant gap, will cause problems | Fix now or spec | +| Moderate | Should address, not urgent | Spec or issue | +| Minor | Nice to have, low impact | Issue or skip | + +## Effort Guide + +| Effort | Definition | +|--------|------------| +| Trivial | < 5 minutes, obvious fix | +| Small | < 30 minutes, contained change | +| Medium | 1-4 hours, multiple files | +| Large | > 4 hours, needs planning | diff --git a/external_plugins/bonfire/bonfire.gif b/external_plugins/bonfire/bonfire.gif new file mode 100644 index 0000000..4f1b763 Binary files /dev/null and b/external_plugins/bonfire/bonfire.gif differ diff --git a/external_plugins/bonfire/commands/archive.md b/external_plugins/bonfire/commands/archive.md new file mode 100644 index 0000000..3c9b8e9 --- /dev/null +++ b/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 `/.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 `/.bonfire/archive/`. + +**Naming convention**: `YYYY-MM-DD--.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 `/.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 `/.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 `/.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 `/.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 diff --git a/external_plugins/bonfire/commands/configure.md b/external_plugins/bonfire/commands/configure.md new file mode 100644 index 0000000..4ba8a95 --- /dev/null +++ b/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 `/.bonfire/` does not exist, tell the user to run `/bonfire:start` first. + +## Step 3: Read Current Config + +Read `/.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** `/.bonfire/config.json` with only these fields (do not preserve old fields like `models`): + +```json +{ + "specsLocation": "", + "docsLocation": "", + "gitStrategy": "", + "linearEnabled": +} +``` + +## Step 6: Update Git Strategy + +If git strategy or locations changed, update `/.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 diff --git a/external_plugins/bonfire/commands/document.md b/external_plugins/bonfire/commands/document.md new file mode 100644 index 0000000..4504864 --- /dev/null +++ b/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 `/.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**: `.md` (kebab-case) + +Examples: +- `inbound-agent-architecture.md` +- `sampling-strategies.md` +- `authentication-flow.md` + +Write the documentation to `//.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 `/.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 diff --git a/external_plugins/bonfire/commands/end.md b/external_plugins/bonfire/commands/end.md new file mode 100644 index 0000000..3283732 --- /dev/null +++ b/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 `/.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 `/.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 `/scripts/` (create if needed) +- **Delete** - Remove the script + +Execute the user's choices: +- **Keep**: No action needed +- **Move to project**: `mkdir -p /scripts/ && mv