bumblebee-cli 0.1.1 → 0.3.0

package/package.json

@@ -1,28 +1,42 @@
-{
-  "name": "bumblebee-cli",
-  "version": "0.1.1",
-  "description": "Bumblebee CLI — Dev task management + Claude Code automation",
-  "license": "MIT",
-  "bin": {
-    "bb": "./bin/bb.mjs"
-  },
-  "scripts": {
-    "postinstall": "node ./scripts/postinstall.mjs"
-  },
-  "files": [
-    "bin/",
-    "scripts/",
-    "python/"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "bumblebee",
-    "cli",
-    "task-management",
-    "claude",
-    "ai",
-    "automation"
-  ]
-}
+{
+  "name": "bumblebee-cli",
+  "version": "0.3.0",
+  "description": "Bumblebee - Dev Task Management + Claude Code Automation CLI",
+  "type": "module",
+  "bin": {
+    "bb": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["cli", "project-management", "claude", "ai-agent", "automation"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "@iarna/toml": "^2.2.5",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "execa": "^9.5.2",
+    "log-update": "^6.1.0",
+    "ofetch": "^1.4.1",
+    "p-limit": "^6.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/skills/bb-agent/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: bb-agent
+description: |
+  Resolve work items or investigate problems using Bumblebee MCP tools + bb CLI.
+  Modes: (1) Action — verb + item IDs for specific phases (suggest, implement, split, run, test).
+  (2) Resolve — item IDs only → full lifecycle. (3) Investigate — free text → root cause analysis.
+  Auto-detects mode from arguments.
+  Invoke with: /bb-agent suggest BB-42 or /bb-agent BB-42 or /bb-agent login page returns 500
+version: 4.0.0
+user_invocable: true
+arguments: "[action] work-item-IDs or free-text problem description"
+---
+
+# Bumblebee Agent
+
+Combined skill for resolving work items and investigating problems.
+
+**Data operations** use MCP tools (`bumblebee_work_items`, `bumblebee_comments`, `bumblebee_projects`).
+**Agent orchestration** uses the `bb agent` CLI commands (suggest, execute, test, run, merge).
+
+## Usage
+
+```
+/bb-agent suggest BB-42                      ← action mode: analyze + propose solution
+/bb-agent implement BB-42                    ← action mode: implement + test + resolve
+/bb-agent split BB-42                        ← action mode: create sub-items from proposal
+/bb-agent run BB-42                          ← action mode: full auto-split autonomous run
+/bb-agent test BB-42                         ← action mode: run tests in worktree
+/bb-agent reimplement BB-42                  ← action mode: retry failed implementation
+/bb-agent continue BB-42                     ← action mode: resume incomplete work
+/bb-agent integrate BB-42                    ← action mode: merge children + docker test
+/bb-agent BB-42                              ← resolve mode: smart triage → best action
+/bb-agent BB-42 BB-43                        ← resolve multiple items
+/bb-agent login page returns 500             ← investigate mode (free text)
+/bb-agent create: build auth system          ← create mode: create items from description
+```
+
+## Mode Detection
+
+Parse arguments left-to-right:
+
+1. **Action mode**: First token matches an action keyword → run that specific phase on the remaining item IDs
+2. **Create mode**: Arguments start with `create:` → create items from the description text
+3. **Resolve mode**: ALL tokens match work item ID regex → smart triage (see below)
+4. **Investigate mode**: Any token is free text → investigation workflow
+
+**Action keywords**: `suggest`, `implement`, `split`, `run`, `test`, `reimplement`, `continue`, `integrate`
+**Item ID regex**: `^([A-Z]+-\d+|\d+|[0-9a-f-]{36})$`
+
+## Action Mode
+
+Each action maps to a specific phase. Always **fetch the item first** before any action.
+
+### `suggest` — Analyze + Propose Solution
+
+Analyze the work item and post a proposal comment with implementation plan + split analysis.
+
+1. Fetch item + comments via MCP
+2. Read knowledge base (CLAUDE.md, docs/knowledge.md)
+3. Run `bb agent suggest <id_or_number>` from CLI
+4. The suggest phase posts a `type: "proposal"` comment with:
+   - Analysis of the problem
+   - Implementation plan
+   - SPLIT_RESULT block (if item spans multiple packages)
+5. Report the proposal summary to the user
+
+### `implement` — Implement + Test + Resolve
+
+Execute the full implementation lifecycle (same as Resolve mode):
+
+Follow `references/workflow.md` steps 1–14:
+Fetch → Triage → Knowledge → Branch → Status → Plan/Execute → Implement → Test → Self-review → Code simplify → Commit → Test gate → Comment → Resolve
+
+### `split` — Create Sub-Items from Proposal
+
+Parse the latest proposal comment and create child work items.
+
+1. Fetch item + comments
+2. Run `bb agent split <id_or_number>` from CLI
+3. This parses the SPLIT_RESULT block from the latest proposal comment
+4. Creates child items with `parent_id` set to the parent
+5. Report created children to the user
+
+### `run` — Full Autonomous Flow
+
+Run the complete agent pipeline including auto-split if needed.
+
+1. Run `bb agent run <id_or_number> --auto-split --target release/dev`
+2. Pipeline: suggest → (split → batch-run children → integrate) or (execute → test → merge)
+3. See `references/parallel-workflow.md` for details
+
+### `test` — Run Tests in Worktree
+
+Run tests for an item that's already been implemented in a worktree.
+
+1. Run `bb agent test <id_or_number>` from CLI
+2. Posts test report comment on the item
+
+### `reimplement` — Retry Failed Implementation
+
+Re-implement a failed item using feedback from previous attempt.
+
+1. Fetch item + comments (reads previous plan + execution report + test failures)
+2. Run `bb agent reimplement <id_or_number>` from CLI
+3. Uses previous feedback to avoid repeating the same mistakes
+
+### `continue` — Resume Incomplete Work
+
+Continue work on an item that was started but not finished.
+
+1. Run `bb agent continue <id_or_number>` from CLI
+2. Reads previous comments to understand where work left off
+
+### `integrate` — Merge Children + Docker Test
+
+Merge all child branches and run integration tests.
+
+1. Run `bb agent integrate <id_or_number> --target release/dev` from CLI
+2. See `references/parallel-workflow.md` for the full integrate flow
+
+## Resolve Mode (Smart Triage)
+
+When only item IDs are provided without an action keyword, **smart triage** determines the best action based on item status:
+
+| Item Status | Auto Action | Rationale |
+|---|---|---|
+| `open`, `confirmed`, `approved` | **suggest** | Item needs analysis first |
+| `in_progress` | **continue** | Work already started, resume it |
+| `failed` | **reimplement** | Previous attempt failed, retry with feedback |
+| `in_review`, `resolved` | **skip** | Already done, report status |
+| `needs_info` | **skip** | Missing info, ask user to clarify |
+| `backlog`, `todo` | **suggest** | Needs analysis before work |
+
+For multiple items: triage each independently, report plan, then execute sequentially or in parallel.
+
+## Investigate Mode
+
+Follow the investigation process in `references/investigate-workflow.md`:
+
+1. **Understand** — parse problem description (what, where, when)
+2. **Check duplicates** — `bumblebee_work_items(action="list", project_slug="...", data='{"status":"open"}')`, search for related items
+3. **Reproduce** — attempt to reproduce the issue
+4. **Trace root cause** — follow error through architecture layers
+5. **Assess impact** — determine priority based on severity
+6. **Create items** — `bumblebee_work_items(action="create", project_slug="...", data='{"title":"...","type":"bug","priority":"high"}')`
+7. **Add details** — post investigation comment with root cause, steps, suggested fix
+8. **Create sub-tasks** — break complex fixes into child items
+9. **Summarize** — present findings and created items to user
+
+## Create Mode
+
+Arguments start with `create:` followed by a description:
+- `/bb-agent create: build notification system` → creates items
+- Type auto-detected: large scope → epic + children, small → task
+- Uses `bumblebee_create_items` or `bumblebee_work_items(create)` MCP tools
+
+## MCP Tools & CLI Reference
+
+See `references/bb-commands.md` for the full reference.
+
+## Key Rules
+
+1. **Always fetch data first** — never assume data from the prompt
+2. **Triage before working** — if lacking detail, ask for clarification and stop
+3. **Check for duplicates** — search existing items before creating new ones
+4. **One item per root cause** — don't create multiple items for symptoms
+5. **Stay on your branch** — never switch branches mid-work
+6. **Run tests** after implementation
+7. **Self-review** all changes before finishing
+8. **Post comments** summarizing changes or findings
+9. **Follow existing patterns** — read CLAUDE.md and match conventions
+
+## References
+
+- `references/workflow.md` — resolve lifecycle (step-by-step)
+- `references/investigate-workflow.md` — investigation process
+- `references/bb-commands.md` — MCP tools + CLI command quick reference
+- `references/prompts.md` — prompt templates for each phase
+- `references/status-transitions.md` — valid status flows per type
+- `references/parallel-workflow.md` — parallel split/integrate workflow

package/templates/skills/bb-agent/references/bb-commands.md

@@ -0,0 +1,124 @@
+# Bumblebee Quick Reference
+
+Data operations use **MCP tools**. Agent orchestration uses **`bb agent` CLI commands**.
+
+## MCP Tools — Data Operations
+
+### Projects
+
+```
+# List all projects
+bumblebee_projects(action="list")
+
+# Get project details
+bumblebee_projects(action="get", project_slug="my-project")
+
+# Create project
+bumblebee_projects(action="create", data='{"name":"My Project","slug":"my-project","key":"MP"}')
+```
+
+### Work Items
+
+```
+# List items (with optional filters)
+bumblebee_work_items(action="list", project_slug="my-project")
+bumblebee_work_items(action="list", project_slug="my-project", data='{"status":"open"}')
+bumblebee_work_items(action="list", project_slug="my-project", data='{"type":"bug"}')
+bumblebee_work_items(action="list", project_slug="my-project", data='{"type":"task","status":"open"}')
+bumblebee_work_items(action="list", project_slug="my-project", data='{"assignee":"thanhlc"}')
+
+# Get item details
+bumblebee_work_items(action="get", item_id="42")
+
+# Create item
+bumblebee_work_items(action="create", project_slug="my-project", data='{"title":"Fix 500 error on tree endpoint","type":"bug","priority":"high"}')
+bumblebee_work_items(action="create", project_slug="my-project", data='{"title":"Add pagination to items list","type":"task","priority":"medium"}')
+bumblebee_work_items(action="create", project_slug="my-project", data='{"title":"Fix schema validation","type":"task","parent_id":10}')
+
+# Update item
+bumblebee_work_items(action="update", item_id="42", data='{"status":"in_progress"}')
+bumblebee_work_items(action="update", item_id="42", data='{"priority":"critical"}')
+bumblebee_work_items(action="update", item_id="42", data='{"assignee":"thanhlc"}')
+bumblebee_work_items(action="update", item_id="42", data='{"status":"in_review"}')
+```
+
+### Comments
+
+```
+# List comments
+bumblebee_comments(action="list", work_item_id="42")
+
+# Create comment
+bumblebee_comments(action="create", work_item_id="42", data='{"body":"Investigation findings: ...","type":"discussion"}')
+bumblebee_comments(action="create", work_item_id="42", data='{"body":"## Proposed Fix\\n...","type":"proposal"}')
+bumblebee_comments(action="create", work_item_id="42", data='{"body":"## Changes Made\\n...","type":"agent_output"}')
+bumblebee_comments(action="create", work_item_id="42", data='{"body":"<test report>","type":"test_report"}')
+```
+
+### Sprints
+
+```
+# List sprints
+bumblebee_sprints(action="list", project_slug="my-project")
+
+# Get sprint
+bumblebee_sprints(action="get", sprint_id="1")
+
+# Create sprint
+bumblebee_sprints(action="create", project_slug="my-project", data='{"name":"Sprint 1","goal":"MVP features"}')
+```
+
+## CLI Commands — Agent Orchestration
+
+These commands manage the agent lifecycle (worktrees, Claude CLI spawning, merge). Keep using `bb agent` for these:
+
+```bash
+# Suggest a plan (analysis only, no code changes)
+bb agent suggest BB-42
+
+# Full run: verify → execute → test → retry → merge
+bb agent run BB-42 --auto-merge --target release/dev
+
+# Skip verification, go straight to execute
+bb agent run BB-42 --skip-verify -y
+
+# Test in worktree
+bb agent test BB-42
+
+# Re-implement after failure
+bb agent reimplement BB-42
+
+# Continue incomplete work
+bb agent continue BB-42
+
+# Merge completed work
+bb agent merge --target release/dev
+
+# Clean up worktree
+bb agent cleanup 42
+
+# List active worktrees
+bb agent worktrees
+```
+
+## CLI Commands — Board View
+
+```bash
+bb board                    # all types
+bb board --type story       # stories only
+bb board --type bug         # bugs only
+```
+
+## Valid Values
+
+### Types
+epic, story, task, bug, feature, chore, spike
+
+### Statuses
+open, confirmed, approved, in_progress, in_review, resolved, closed, failed, needs_info, backlog, todo, done, cancelled, wont_fix
+
+### Priorities
+critical, high, medium, low, none
+
+### Comment Types
+discussion, proposal, agent_output, test_report, execution_report

package/templates/skills/bb-agent/references/investigate-workflow.md

@@ -0,0 +1,150 @@
+# Investigation Workflow
+
+Step-by-step process for investigating a problem and creating work items.
+
+## Step 1: Understand the Problem
+
+Parse the user's description to identify:
+- **What**: The observed behavior (error, wrong data, performance issue)
+- **Where**: Which service/component (API, Web, CLI, Agent)
+- **When**: Under what conditions (specific input, timing, user action)
+
+## Step 2: Check Existing Items
+
+Search for duplicates or related items using MCP tools:
+
+```
+bumblebee_work_items(action="list", project_slug="<slug>", data='{"status":"open"}')
+bumblebee_work_items(action="list", project_slug="<slug>", data='{"type":"bug"}')
+bumblebee_work_items(action="list", project_slug="<slug>", data='{"type":"task"}')
+```
+
+Search by keywords in titles. If the problem already has an open item, update it instead of creating a new one.
+
+## Step 3: Reproduce the Problem
+
+Attempt to reproduce using the appropriate method:
+
+| Service | How to Reproduce |
+|---------|-----------------|
+| **API** | `curl` or `httpx` to the endpoint directly |
+| **Web** | Browser DevTools: Console errors, Network tab, snapshot |
+| **CLI** | Run the `bb` command with verbose output |
+| **Agent** | Check worktree state, agent comments, logs |
+| **Database** | Query the relevant tables directly |
+
+Capture:
+- Exact error messages and stack traces
+- HTTP status codes and response bodies
+- Console errors and network failures
+
+## Step 4: Trace the Root Cause
+
+Follow the error upstream through the architecture layers:
+
+```
+Web UI → API Client (fetch) → FastAPI Route → Service → SQLAlchemy → PostgreSQL
+CLI    → httpx → FastAPI Route → Service → SQLAlchemy → PostgreSQL
+```
+
+Use these tools to trace:
+- **Read source code** — find the handler, service function, model
+- **Check schemas** — Pydantic validation, type mismatches
+- **Check migrations** — `alembic current` vs schema drift
+- **Check config** — `.env`, CORS origins, database URL
+
+## Step 5: Assess Impact and Priority
+
+| Priority | Criteria |
+|----------|----------|
+| **critical** | Data loss, security vulnerability, blocks all users |
+| **high** | Core feature broken, no workaround, affects many users |
+| **medium** | Feature degraded, workaround exists, moderate impact |
+| **low** | Cosmetic, edge case, minor inconvenience |
+
+## Step 6: Create Work Items
+
+For each distinct root cause found, create a work item:
+
+```
+bumblebee_work_items(action="create", project_slug="<slug>", data='{"title":"<actionable title>","type":"bug","priority":"high"}')
+```
+
+### Title Format
+
+Use action-oriented titles that describe the fix, not just the symptom:
+
+| Bad Title | Good Title |
+|-----------|-----------|
+| "Login broken" | "Fix 500 error on Google OAuth login when client_id not configured" |
+| "Items not showing" | "Fix WorkItemTreeResponse missing depth/children_count defaults" |
+| "Slow page" | "Add pagination to work items list endpoint (currently loads all)" |
+
+### Description Template
+
+After creating the item, add a detailed description via comment:
+
+```
+bumblebee_comments(action="create", work_item_id="<id>", data='{"body":"## Problem\n<what is happening>\n\n## Root Cause\n<why it is happening — reference specific file:line>\n\n## Reproduction Steps\n1. <step 1>\n2. <step 2>\n3. <expected vs actual>\n\n## Suggested Fix\n<what needs to change>\n\n## Acceptance Criteria\n- [ ] <criterion 1>\n- [ ] <criterion 2>\n- [ ] <no regressions in related features>\n\n## Affected Files\n- `path/to/file.py:line`\n- `path/to/other.ts:line`","type":"discussion"}')
+```
+
+## Step 7: Create Sub-Tasks (If Complex)
+
+If the fix requires multiple steps or touches multiple packages:
+
+```
+# Create parent item
+bumblebee_work_items(action="create", project_slug="<slug>", data='{"title":"Fix authentication flow across API and Web","type":"story","priority":"high"}')
+
+# Create sub-tasks under the parent (use the parent's id from the response)
+bumblebee_work_items(action="create", project_slug="<slug>", data='{"title":"Fix JWT token validation in API middleware","type":"task","parent_id":<parent_id>}')
+bumblebee_work_items(action="create", project_slug="<slug>", data='{"title":"Update auth context in Web to handle token refresh","type":"task","parent_id":<parent_id>}')
+bumblebee_work_items(action="create", project_slug="<slug>", data='{"title":"Add integration test for full auth flow","type":"task","parent_id":<parent_id>}')
+```
+
+## Step 8: Summarize Findings
+
+Present the investigation results to the user:
+
+```
+## Investigation Summary
+
+**Problem**: <one-line summary>
+**Root Cause**: <what's actually wrong>
+**Impact**: <who/what is affected>
+
+### Items Created
+- BB-<N> <title> (priority: <p>, type: <t>)
+- BB-<N> <title> (priority: <p>, type: <t>)
+
+### Recommended Next Steps
+1. <most urgent fix>
+2. <secondary fix>
+3. <preventive measure>
+```
+
+## Common Investigation Patterns
+
+### API Returns 500
+1. Check uvicorn/FastAPI logs for the traceback
+2. Test the endpoint with `curl` directly
+3. Check if the Pydantic schema matches the SQLAlchemy model
+4. Check if migrations are up to date
+
+### Web Page Not Loading Data
+1. Open browser DevTools → Network tab
+2. Check for CORS errors in Console
+3. Check if the API endpoint returns data via `curl`
+4. Check React Query error state in components
+
+### CLI Command Fails
+1. Run with verbose/debug output
+2. Check `~/.bumblebee/config.toml` for correct API URL and token
+3. Test the API endpoint directly
+4. Check Python package version matches API expectations
+
+### Items Missing or Wrong Data
+1. Query the database directly to see raw data
+2. Check soft-delete filter (`deleted_at IS NULL`)
+3. Check if project ownership matches (`project.owner_id == user.id`)
+4. Check serialization schema for missing/wrong fields

package/templates/skills/bb-agent/references/parallel-workflow.md

@@ -0,0 +1,105 @@
+# Parallel Development Workflow
+
+Guide for splitting work items across packages and running agents in parallel.
+
+## When to Use
+
+Use parallel mode when a work item:
+- Affects 2+ packages (api/, web/, cli/)
+- Has clearly separable scopes of work
+- Benefits from independent implementation and testing
+
+Do NOT split items that:
+- Have tight cross-package dependencies requiring coordinated changes
+- Are small enough to implement in a single pass
+- Only affect one package
+
+## Split Analysis Format
+
+The suggest phase outputs a SPLIT_RESULT block:
+
+```
+### SPLIT_RESULT
+NEEDS_SPLIT: true
+ITEMS:
+- SCOPE: api
+  TITLE: API - add auth endpoints
+  DESCRIPTION: Create POST /api/auth/login and /api/auth/register
+  ACCEPTANCE_CRITERIA: Endpoints return JWT tokens, tests pass
+- SCOPE: web
+  TITLE: Web - login page
+  DESCRIPTION: Create login form with email/password
+  ACCEPTANCE_CRITERIA: Form submits to API, redirects on success
+```
+
+## Commands
+
+### Manual Flow (step-by-step)
+
+```bash
+# 1. Analyze and propose split
+bb agent suggest BB-42
+
+# 2. Create sub-items from proposal
+bb agent split BB-42
+
+# 3. Run sub-items in parallel (each gets own worktree)
+bb agent batch-run BB-43 BB-44 BB-45
+
+# 4. Integration test + merge all
+bb agent integrate BB-42 --target release/dev --cleanup
+```
+
+### Autonomous Flow (single command)
+
+```bash
+bb agent run BB-42 --auto-split --target release/dev
+```
+
+This runs: suggest → split → batch-run children → integrate.
+Use `--no-auto-split` to disable and use the single-item flow.
+
+## Batch-Run Behavior
+
+`bb agent batch-run` runs items in parallel:
+
+1. Each item gets its own git worktree under `~/.bumblebee/worktrees/{slug}/`
+2. Each worktree has its own branch: `{prefix}/{key}_{slug}`
+3. Claude Code runs in `--permission-mode bypassPermissions`
+4. Max parallelism controlled by `--parallel N` (default: 2)
+5. After execution: Docker tests per item
+6. Passing items can auto-merge with `--auto-merge`
+
+## Integrate Flow
+
+`bb agent integrate` merges all child branches:
+
+1. Validates all children are resolved/in_review
+2. Creates temp branch: `integrate/{parent-key}`
+3. Merges each child branch sequentially
+4. Runs Docker tests on the integration branch
+5. On pass: fast-forward target, mark parent resolved, cleanup
+6. On fail: abort, post failure report, cleanup integration branch
+
+### Conflict Handling
+
+If a child branch has merge conflicts during integration:
+- The integration aborts immediately
+- A failure comment is posted on the parent item
+- Manual conflict resolution is needed before re-running
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Child execution fails | Continues other children, reports failure |
+| Docker test fails | Triggers reimplement retry (up to 3x) |
+| Merge conflict | Aborts integration, posts conflict details |
+| All retries exhausted | Parent marked `failed`, manual fix needed |
+
+## MCP Tools
+
+For programmatic access (Claude Code agents):
+
+- `bumblebee_split_item(parent_item_id, sub_items, project_slug)` — create children from JSON
+- `bumblebee_create_items(project_slug, items)` — batch create with auto-type detection