bumblebee-cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,144 @@
+# Prompt Templates Reference
+
+Structure of prompts used in each phase of the agent workflow.
+
+## Common Header
+
+All prompts start with:
+```
+You are {action} {item_type} {key}: {title}
+
+Type: {type}  |  Priority: {priority}  [|  Status: {status}]
+```
+
+Followed by optional sections (included only when data exists):
+- `## Description` — work item description
+- `## Acceptance Criteria` — acceptance criteria
+- `## Implementation Plan` / `## Existing Plan` — plan field
+- `## Previous Comments / Progress` — formatted comment history
+- `## Project Knowledge Base` — contents of CLAUDE.md, docs/knowledge.md, .claude/lessons-learned.md
+
+## Phase 1: Suggest (Analysis)
+
+**Purpose**: Analyze the work item and produce a plan. No code changes.
+
+**Key instruction**:
+```
+Analyse this work item **and** the project source code. Return a Markdown plan:
+
+1. **Root Cause / Analysis** -- what needs to change and why
+2. **Files to Modify** -- list every file with a short description
+3. **Implementation Steps** -- numbered, concrete steps
+4. **Testing Strategy** -- how to verify the changes
+5. **Risks & Considerations** -- edge cases, breaking changes
+
+IMPORTANT: Do NOT modify any files. Only analyse and produce the plan.
+```
+
+**CLI command**: `bb agent suggest <id>`
+**Claude flags**: `-p <prompt> --output-format text`
+**Comment type**: `proposal`
+
+## Phase 2: Execute (Implementation)
+
+**Purpose**: Implement the changes in a git worktree.
+
+**Key instruction**:
+```
+Implement the changes described in the plan / comments above.
+
+1. Follow the project's existing coding conventions and patterns
+2. Work through changes one file at a time
+3. Run existing tests after your changes and fix any failures
+4. Add new tests where appropriate
+5. Commit your work with a clear, descriptive commit message
+6. If you hit a blocker, document it clearly
+```
+
+**CLI command**: `bb agent execute <id>`
+**Claude flags**: `--output-format stream-json --verbose --permission-mode bypassPermissions --mcp-config -`
+**Comment type**: `agent_output`
+
+## Phase 3: Test (Verification)
+
+**Purpose**: Run tests and report results. No code changes.
+
+**Key instruction**:
+```
+Run ALL relevant tests and verify the implementation:
+
+1. Identify test commands from CLAUDE.md or project config
+2. Run all relevant test suites
+3. Check acceptance criteria from the work item
+4. Review the git diff for obvious issues
+
+Return a structured test report:
+
+## Test Report
+### Results
+- **Status**: PASS or FAIL
+- **Tests run**: <count>
+- **Passed**: <count>
+- **Failed**: <count>
+
+### Failing Tests (if any)
+### Acceptance Criteria Check
+### Root Cause Analysis (if failures)
+
+IMPORTANT: Do NOT fix any code. Only run tests and report results.
+```
+
+**CLI command**: `bb agent test <id>`
+**Claude flags**: `-p <prompt> --output-format text`
+**Comment type**: `test_report`
+
+## Phase 4: Reimplement (Fix from Failure)
+
+**Purpose**: Re-implement based on test failure feedback. Runs in worktree with full permissions.
+
+**Key instruction**:
+```
+**IMPORTANT: A previous implementation attempt had test failures.**
+Read the comments below — they contain the original plan,
+execution report, and test failure details.
+
+1. Read the test report and failure reasons from previous comments
+2. Identify what went wrong in the previous implementation
+3. Fix the issues — focus on root causes from the test report
+4. Ensure all tests pass after your changes
+5. Run the full test suite to verify no regressions
+6. Commit your fixes with a clear message referencing the re-implementation
+```
+
+**CLI command**: `bb agent reimplement <id>`
+**Claude flags**: `--output-format stream-json --verbose --permission-mode bypassPermissions --mcp-config -`
+**Comment type**: `agent_output`
+
+## Comment Context Format
+
+All phases receive previous comments formatted as:
+
+```markdown
+## Previous Comments / Progress
+
+### {author} [{type}] -- {created_at}
+{body}
+
+### {author} [{type}] -- {created_at}
+{body}
+```
+
+This ensures the agent has full context of prior analysis, implementation attempts, and test results.
+
+## Full Loop Flow
+
+```
+bb agent run <id> --auto-merge --target release/dev
+
+  Phase 1: suggest → post proposal comment → status: confirmed
+  Phase 2: execute → spawn Claude in worktree → post execution report
+  Phase 3: test   → run tests → post test report
+    ├─ PASS → merge to target → status: resolved → cleanup worktree
+    └─ FAIL → status: failed → retry if --max-retries > 0
+                └─ reimplement → test again → ...
+```

package/templates/skills/bb-agent/references/status-transitions.md

@@ -0,0 +1,93 @@
+# Status Transitions by Work Item Type
+
+Valid statuses for each work item type, sourced from `api/src/schemas/work_item.py`.
+
+## Epic
+
+```
+open → in_progress → done
+                  ↘ cancelled
+```
+
+Statuses: `open`, `in_progress`, `done`, `cancelled`
+
+## Story
+
+```
+open → confirmed → approved → in_progress → in_review → resolved → closed
+                                   │
+                                   └─ failed → (reimplement) → in_progress
+                                   └─ needs_info → (clarify) → open
+```
+
+Statuses: `open`, `confirmed`, `approved`, `in_progress`, `in_review`, `resolved`, `closed`, `failed`, `needs_info`
+
+## Task
+
+```
+backlog → todo → in_progress → in_review → done
+```
+
+Statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`
+
+## Bug
+
+```
+open → confirmed → in_progress → in_review → resolved → closed
+                                                      ↘ wont_fix
+```
+
+Statuses: `open`, `confirmed`, `in_progress`, `in_review`, `resolved`, `closed`, `wont_fix`
+
+## Feature
+
+```
+open → confirmed → approved → in_progress → in_review → resolved → closed
+```
+
+Statuses: `open`, `confirmed`, `approved`, `in_progress`, `in_review`, `resolved`, `closed`
+
+## Chore
+
+```
+open → in_progress → done
+```
+
+Statuses: `open`, `in_progress`, `done`
+
+## Spike
+
+```
+open → in_progress → done
+```
+
+Statuses: `open`, `in_progress`, `done`
+
+## Agent Flow Status Mapping
+
+| Phase | Action | Status Transition |
+|-------|--------|-------------------|
+| Suggest | Post analysis plan | `open` → `confirmed` |
+| Confirm | User approves | `confirmed` → `approved` (manual) |
+| Execute | Start implementation | `approved`/`confirmed`/`open` → `in_progress` |
+| Test Pass | All tests green | `in_progress` → `in_review` |
+| Test Fail | Tests failing | `in_progress` → `failed` |
+| Reimplement | Fix from failure | `failed` → `in_progress` |
+| Merge | Code merged | `in_review` → `resolved` |
+| Close | User accepts | `resolved` → `closed` (manual) |
+
+## Default Statuses
+
+| Type | Default |
+|------|---------|
+| epic | `open` |
+| story | `open` |
+| task | `backlog` |
+| bug | `open` |
+| feature | `open` |
+| chore | `open` |
+| spike | `open` |
+
+## Priorities
+
+Valid priorities (all types): `critical`, `high`, `medium`, `low`, `none`

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

@@ -0,0 +1,178 @@
+# Work Item Resolution Workflow
+
+Step-by-step process for resolving a Bumblebee work item.
+
+## Step 1: Fetch Work Item Data
+
+For each id_or_number provided, fetch the full item and its comments using MCP tools:
+
+```
+bumblebee_work_items(action="get", item_id="<id>")
+bumblebee_comments(action="list", work_item_id="<id>")
+```
+
+Review all returned data:
+- **Core**: title, type, description, status, priority, assignee
+- **Criteria**: acceptance_criteria
+- **Plan**: plan (pre-approved implementation plan, if set)
+- **Context**: comments (proposals, execution reports, test reports)
+
+For multiple items, fetch all in parallel to minimize round trips.
+
+## Step 2: Triage — Is This Actionable?
+
+Before investing effort, check if the item has enough detail to act on. An item is **too generic** if:
+
+- Description is vague with no concrete scope (e.g. "improve performance", "fix bugs")
+- No acceptance criteria and no plan
+- Cannot determine what files, features, or behaviors are involved
+
+If the item is too generic:
+```
+bumblebee_work_items(action="update", item_id="<id>", data='{"status":"needs_info"}')
+bumblebee_comments(action="create", work_item_id="<id>", data='{"body":"Moved to needs_info — [explain what is missing]","type":"discussion"}')
+```
+Then **stop**.
+
+## Step 3: Read Knowledge Base
+
+Read project context to understand conventions before writing code:
+
+- **CLAUDE.md** — project structure, commands, conventions
+- **docs/knowledge.md** — tech stack details, status enums, patterns
+- **.claude/lessons-learned.md** — previous learnings and gotchas
+
+Use the knowledge to follow existing patterns rather than inventing new ones.
+
+## Step 4: Create Branch / Worktree
+
+The CLI creates a git worktree for isolated work:
+
+- **Worktree path**: `~/.bumblebee/worktrees/{project_slug}/item-{number}`
+- **Branch**: `{type_prefix}/{key}_{slugified_title}`
+
+Branch naming convention:
+| Work Item Type | Prefix |
+|---------------|--------|
+| epic | `epic/` |
+| story | `feat/` |
+| task | `task/` |
+| bug | `fix/` |
+| feature | `feat/` |
+| chore | `chore/` |
+| spike | `spike/` |
+
+Example: `feat/bb-42_user-authentication` in `~/.bumblebee/worktrees/my-project/item-42`
+
+If using the skill interactively (not via CLI), create a branch manually:
+```bash
+git checkout -b {type_prefix}/{key}_{slugified_title}
+```
+
+## Step 5: Update Status
+
+Mark the item as in progress:
+```
+bumblebee_work_items(action="update", item_id="<id>", data='{"status":"in_progress"}')
+```
+
+## Step 6: Plan or Execute
+
+**If the item has a `plan` field:** The plan is pre-approved. Execute it directly — do not re-plan or skip steps.
+
+**If no plan and task is complex** (touches 3+ files, multiple packages, or requires architectural decisions): Analyze first, then save the plan:
+```
+bumblebee_comments(action="create", work_item_id="<id>", data='{"body":"<markdown plan>","type":"proposal"}')
+```
+
+**If no plan and task is simple** (single file fix, straightforward change): Proceed directly to implementation.
+
+## Step 7: Implement
+
+Write the code changes:
+
+- **Stay on the feature branch** — never switch branches mid-work
+- **Follow acceptance criteria** if provided
+- **Match existing patterns** — use conventions from CLAUDE.md and surrounding code
+- **Minimal changes** — only modify what's needed. Don't refactor surrounding code or "improve" things outside scope
+
+## Step 8: Run Tests
+
+Run the appropriate test commands to catch regressions:
+
+- Check CLAUDE.md for package-specific test commands
+- Common commands: `pytest` (API), `vitest` / `npm test` (web), `npm run build` (web)
+- Run from the correct package directory
+- Fix any test failures before proceeding
+
+## Step 9: Self-Review
+
+Review all changes via `git diff HEAD~1`:
+
+- **Bugs**: incorrect logic, off-by-one errors, null risks
+- **Dead code**: unused variables, unreachable branches
+- **Edge cases**: empty arrays, missing null checks
+- **Type issues**: incorrect casts, missing validation
+- **Security**: injection risks, exposed secrets
+
+Fix any issues found and commit separately.
+
+## Step 10: Code Simplify
+
+Launch a code simplifier agent to polish the implementation:
+
+```
+Task → subagent_type: "code-simplifier"
+  prompt: "Simplify the recently modified code. Focus on files changed
+           in the last 2 commits (run `git diff HEAD~2 --name-only`).
+           Look for redundancy, unnecessary complexity, and inconsistencies."
+```
+
+Review and commit any simplifications.
+
+## Step 11: Commit
+
+Stage and commit with a clear message:
+
+- Use conventional commit format: `feat:`, `fix:`, `refactor:`, etc.
+- Reference the work item key in the message (e.g. `feat: add auth flow [BB-42]`)
+- Stage specific files — avoid `git add .`
+
+## Step 12: Test Gate
+
+Run the full test suite one final time:
+
+- If all tests pass → continue to Step 13
+- If tests fail → post a test report comment, set status to `failed`, and stop
+
+```
+bumblebee_comments(action="create", work_item_id="<id>", data='{"body":"<test report markdown>","type":"test_report"}')
+bumblebee_work_items(action="update", item_id="<id>", data='{"status":"failed"}')
+```
+
+## Step 13: Post Comment
+
+Post a summary comment on the work item:
+
+```
+bumblebee_comments(action="create", work_item_id="<id>", data='{"body":"<summary of changes>","type":"agent_output"}')
+```
+
+The comment should cover:
+- What was implemented or fixed
+- Key design decisions
+- Any caveats or follow-up items
+
+## Step 14: Resolve
+
+After tests pass, review is clean, and changes are committed:
+
+```
+bumblebee_work_items(action="update", item_id="<id>", data='{"status":"in_review"}')
+```
+
+Suggest the merge command:
+```
+Merge with: git checkout release/dev && git merge {branch}
+Or: bb agent merge --target release/dev
+```

package/README.md

@@ -1,49 +0,0 @@
-# bumblebee-cli
-
-npm wrapper for the Bumblebee CLI — dev task management + Claude Code automation.
-
-## Install
-
-```bash
-npm install -g bumblebee-cli
-```
-
-**Requires Python 3.12+**. The postinstall script will automatically set up a Python virtual environment if `bb` is not already installed.
-
-## Usage
-
-```bash
-bb --help
-bb login
-bb item list
-bb agent suggest BB-42
-bb agent run BB-42        # Full cycle: verify → execute → test → merge
-bb agent daemon start     # Long-running daemon for web-initiated sessions
-```
-
-## How it works
-
-This is a thin Node.js wrapper around the Python CLI. It resolves `bb` in this order:
-
-1. System `bb` on PATH (if you installed via `pip install bumblebee-cli`)
-2. Local `.venv` created by the npm postinstall script
-3. `python -m bb_cli` as a fallback
-
-## Manual Python install
-
-If the automatic setup doesn't work, install the Python CLI directly:
-
-```bash
-pip install bumblebee-cli
-```
-
-## Project-local config
-
-Initialize a project-local config:
-
-```bash
-cd your-project
-bb init --project my-app
-```
-
-This creates `.bumblebee/config.toml` which overrides `~/.bumblebee/config.toml` settings (except credentials).

package/bin/bb.mjs

@@ -1,132 +0,0 @@
-#!/usr/bin/env node
-
-import { execFileSync, execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = join(__dirname, "..");
-const args = process.argv.slice(2);
-
-/**
- * Thin Node.js wrapper for the Bumblebee Python CLI.
- *
- * Resolution order:
- * 1. `bb` already on PATH (user installed via pip — not our own npm wrapper)
- * 2. Local .venv created by postinstall
- * 3. `python -m bb_cli` (fallback)
- */
-
-function getNpmGlobalPrefix() {
-  try {
-    return execSync("npm prefix -g", { encoding: "utf8", stdio: "pipe" }).trim();
-  } catch {
-    return null;
-  }
-}
-
-function isOurOwnWrapper(bbPath) {
-  // Check if the found bb is inside our npm package or the npm global bin
-  const normalized = resolve(bbPath).toLowerCase();
-  if (normalized.includes("node_modules") && normalized.includes("bumblebee-cli")) {
-    return true;
-  }
-  // On Windows/Linux, npm global installs create shims in the npm prefix dir
-  const npmPrefix = getNpmGlobalPrefix();
-  if (npmPrefix && normalized.startsWith(resolve(npmPrefix).toLowerCase())) {
-    return true;
-  }
-  return false;
-}
-
-// 1. Check if `bb` is already available on PATH (pip install)
-function trySystemBb() {
-  try {
-    const which = process.platform === "win32" ? "where" : "which";
-    const result = execSync(`${which} bb`, { stdio: "pipe", encoding: "utf8" });
-    // On Windows, `where` may return multiple lines; check each
-    const paths = result.trim().split(/\r?\n/);
-    for (const bbPath of paths) {
-      const p = bbPath.trim();
-      if (p && !isOurOwnWrapper(p)) {
-        return p;
-      }
-    }
-  } catch {
-    // not found
-  }
-  return null;
-}
-
-// 2. Check local .venv
-function tryLocalVenv() {
-  const isWin = process.platform === "win32";
-  const venvBb = isWin
-    ? join(pkgRoot, ".venv", "Scripts", "bb.exe")
-    : join(pkgRoot, ".venv", "bin", "bb");
-  if (existsSync(venvBb)) {
-    return venvBb;
-  }
-  return null;
-}
-
-// 3. Fallback to python -m bb_cli
-function tryPythonModule() {
-  const pythonCmds =
-    process.platform === "win32" ? ["python", "python3"] : ["python3", "python"];
-  for (const py of pythonCmds) {
-    try {
-      execSync(`${py} -c "import bb_cli"`, { stdio: "pipe" });
-      return { python: py, module: true };
-    } catch {
-      // try next
-    }
-  }
-  return null;
-}
-
-// --- Main ---
-
-const systemBb = trySystemBb();
-if (systemBb) {
-  try {
-    execFileSync(systemBb, args, { stdio: "inherit" });
-    process.exit(0);
-  } catch (e) {
-    process.exit(e.status ?? 1);
-  }
-}
-
-const venvBb = tryLocalVenv();
-if (venvBb) {
-  try {
-    execFileSync(venvBb, args, { stdio: "inherit" });
-    process.exit(0);
-  } catch (e) {
-    process.exit(e.status ?? 1);
-  }
-}
-
-const pyFallback = tryPythonModule();
-if (pyFallback) {
-  try {
-    execFileSync(pyFallback.python, ["-m", "bb_cli", ...args], {
-      stdio: "inherit",
-    });
-    process.exit(0);
-  } catch (e) {
-    process.exit(e.status ?? 1);
-  }
-}
-
-console.error(
-  "Error: Could not find the Bumblebee Python CLI.\n" +
-    "\n" +
-    "The npm package needs the Python CLI installed. Fix with ONE of:\n" +
-    "  1. pip install bumblebee-cli          (install globally)\n" +
-    "  2. npm rebuild bumblebee-cli          (retry postinstall setup)\n" +
-    "\n" +
-    "Requires Python 3.12+ — https://python.org"
-);
-process.exit(1);

package/python/bb_cli/__main__.py

@@ -1,3 +0,0 @@
-from bb_cli.main import app
-
-app()

package/python/bb_cli/api_client.py

@@ -1,45 +0,0 @@
-import httpx
-
-from .config import get_api_url, get_token
-
-
-def get_client() -> httpx.Client:
-    headers = {}
-    token = get_token()
-    if token:
-        headers["Authorization"] = f"Bearer {token}"
-    return httpx.Client(base_url=get_api_url(), headers=headers, timeout=30)
-
-
-def api_get(path: str, params: dict | None = None) -> dict | list:
-    with get_client() as client:
-        resp = client.get(path, params=params)
-        resp.raise_for_status()
-        return resp.json()
-
-
-def api_post(path: str, json: dict | None = None, params: dict | None = None) -> dict:
-    with get_client() as client:
-        resp = client.post(path, json=json, params=params)
-        resp.raise_for_status()
-        return resp.json()
-
-
-def api_put(path: str, json: dict) -> dict:
-    with get_client() as client:
-        resp = client.put(path, json=json)
-        resp.raise_for_status()
-        return resp.json()
-
-
-def api_patch(path: str, json: dict) -> dict:
-    with get_client() as client:
-        resp = client.patch(path, json=json)
-        resp.raise_for_status()
-        return resp.json()
-
-
-def api_delete(path: str):
-    with get_client() as client:
-        resp = client.delete(path)
-        resp.raise_for_status()