# Issue Tracker Abstraction Plan
## Current Beads Integration Points
- Worker prompts include Beads-only instructions, commands, and wording in `src/claude_team_mcp/worker_prompt.py`.
- Worktree detection assumes `.beads` in `src/claude_team_mcp/utils/worktree_detection.py` and sets `BEADS_DIR` when spawning workers.
- `spawn_workers` docstrings and behavior reference Beads in `src/claude_team_mcp/tools/spawn_workers.py`.
- The worker message hint and help text are Beads-specific in `src/claude_team_mcp/utils/constants.py` and `src/claude_team_mcp/tools/bd_help.py`.
- `message_workers` always appends a Beads hint in `src/claude_team_mcp/tools/message_workers.py`.
- Tests assert Beads command strings in `tests/test_worker_prompt.py`.
- Docs and command guides hard-code Beads instructions: `CLAUDE.md`, `README.md`, `commands/*.md`.
## Issue Tracker Operations Currently Used
These appear in prompts, help text, docs, or tests:
- List: `bd list`
- Ready: `bd ready`
- Show: `bd show <issue-id>`
- Update status: `bd update <issue-id> --status in_progress`
- Comment: `bd comment <issue-id> "..."`
- Close: `bd close <issue-id>`
- Create: `bd create --title ... --type ... --priority ... --description ...`
- Search: `bd search <query>`
- Blocked: `bd blocked`
- Dependencies: `bd dep add`, `bd dep tree`
- Worktrees: `bd --no-db ...` (required today)
## Proposed Abstraction Interface
Create a small issue tracker abstraction layer that provides:
- A backend registry with two implementations: Beads (bd) and Pebbles (pb).
- A capability surface used by prompts/help/docs (not yet direct CLI calls).
- A detection method that chooses the backend based on repo state or config.
### Suggested Module Layout
- `src/claude_team_mcp/issue_tracker.py` (or `src/claude_team_mcp/issue_tracker/__init__.py`)
- `IssueTrackerBackend` protocol or dataclass:
- `name` ("beads" | "pebbles")
- `cli` ("bd" | "pb")
- `marker_dir` (".beads" | ".pebbles")
- `env_var` (e.g., `BEADS_DIR`, TBD for Pebbles)
- `requires_no_db_flag` (bool)
- `commands` (templates for operations below)
- `supports` (capabilities: search, blocked, dep_types)
- `detect_issue_tracker(project_path: str) -> IssueTrackerBackend`:
- Auto-detect via marker dirs in repo root or main repo (worktree-aware).
- Optional override via env `MANIPLE_ISSUE_TRACKER=beads|pebbles`.
- If both `.beads` and `.pebbles` exist, log and pick deterministic behavior (prefer override).
- `get_worktree_issue_tracker_dir(project_path: str) -> dict | None`:
- Returns `{env_var: path}` for the tracker in the main repo.
### Command Templates to Centralize
The interface should surface command strings used in prompts and help:
- `list`, `ready`, `show`, `update_status`, `comment`, `close`, `create`,
`dep_add`, `dep_rm`, `dep_tree`, `search`, `blocked`.
Commands should be parameterized in one place and reused by:
- `worker_prompt.py`
- `utils/constants.py` (help text)
- `tools/bd_help.py` (rename or alias to `issue_tracker_help`)
- docs and command templates
If a command is unsupported (e.g., Pebbles `search`), return `None` and omit
it from help text or provide the closest alternative.
## Detection Strategy (.beads vs .pebbles)
- Use the current `git rev-parse --git-common-dir` approach to locate the main repo.
- Look for `.pebbles` or `.beads` in the main repo root.
- If both exist:
- Prefer `MANIPLE_ISSUE_TRACKER` env var.
- Otherwise log a warning and choose a default (recommend `.pebbles`).
- If neither exists:
- Return `None` and avoid appending tracker instructions.
## Feature Gaps Between Beads and Pebbles
Based on `pb --help` output:
- Pebbles lacks `search`, `blocked`, and `dep cycles` commands.
- Pebbles dependency types appear limited to `blocks` and `parent-child`.
Beads adds `related` and `discovered-from`.
- Pebbles does not expose a `--no-db` flag; Beads uses `--no-db` for worktrees.
- Pebbles includes `log`, `rename`, `rename-prefix`, `prefix set`, and `import beads`.
- Pebbles `create`/`update` use short flags (`-title`, `-description`, etc.).
Open questions to confirm:
- Pebbles project discovery and env var name (if any) for locating `.pebbles`.
- Pebbles status values (should align with Beads `open`/`in_progress`/`closed`).
## Implementation Plan (No Code Changes Yet)
1. Add issue tracker abstraction module and backend registry.
- Define command templates, capabilities, and detection logic.
- Estimated effort: 1-2 hours.
2. Update worktree detection to return tracker-specific env var.
- Replace `get_worktree_beads_dir` with generalized function.
- Estimated effort: 1 hour.
3. Replace Beads-specific prompt/help strings with backend data.
- Update `worker_prompt.py`, `constants.py`, `bd_help.py`, and
`message_workers.py` to use the abstraction.
- Estimated effort: 2-3 hours.
4. Update docs/tests to be tracker-neutral.
- Adjust `tests/test_worker_prompt.py`, `CLAUDE.md`, `README.md`, and
`commands/*.md`.
- Estimated effort: 1-2 hours.
## Concerns / Blockers
- Need confirmation on Pebbles env var or CLI flags for pointing to a project
directory in worktrees (Beads currently relies on `BEADS_DIR`).
- Some Beads guidance (search/blocked/related deps) has no Pebbles equivalent;
documentation and prompts must omit or adapt those sections.
- If both `.beads` and `.pebbles` exist in a repo, detection order must be
explicitly defined to avoid silent misrouting.
