Enhancement: Add Pearls adapter for git-native issue tracking

[tbrandenburg]

Overview

Add a Pearls adapter to enable work CLI to manage issues in repositories using Pearls - a git-native, local-first issue tracker designed for agentic development.

Why Pearls?

Pearls aligns perfectly with work CLI's philosophy:

• Local-first: Issues stored in .pearls/issues.jsonl alongside code
• Stateless: No daemon, single binary (prl), fast Rust implementation
• Agent-ready: Strict schema, structured JSON data, finite-state transitions
• Git-native: Built-in merge driver and hooks for real workflows
• Lightweight: No cloud dependencies, works offline

Integration Benefits

1. Natural fit: Both tools prioritize stateless execution, local-first design, and AI agent support
2. Complementary: Pearls handles git-native storage, work CLI provides unified interface across backends
3. Agent workflows: Enables mixed teams to use work CLI with repositories already using Pearls
4. Zero dependencies: Pearls is a single binary, minimal installation friction

Proposed Implementation

Adapter Structure

src/adapters/pearls/
├── index.ts          # PearlsAdapter implementing WorkAdapter interface
├── cli-wrapper.ts    # Spawn prl commands, parse JSON output
├── mapper.ts         # Map Pearls data model to work CLI WorkItem
└── types.ts          # Pearls-specific types

Data Model Mapping

work CLI	Pearls	Notes
id	id	prl-xxxxxx format
title	title	Direct mapping
description	description	Direct mapping
state	status	Open→new, InProgress→active, Closed→closed
assignee	metadata.assignee	Via prl meta commands
priority	priority	P0-P4 → map to work CLI priority levels
labels	labels	Direct array mapping
created_at	created_at	Unix timestamp
updated_at	updated_at	Unix timestamp

Relation Mapping

work CLI	Pearls Dependency Type
blocks	blocks
parent	parent_child
relates_to	related

Context Configuration

# Add Pearls context pointing to repo root
work context add my-pearls-repo --tool pearls --path /path/to/repo

# work CLI will execute: prl --root /path/to/repo <command>

Core Operations

List items

// Execute: prl list --format json
// Parse JSON array, convert to WorkItem[]

Create item

// Execute: prl create "title" --description "desc" --priority 2 --label tag1,tag2
// Parse output to extract prl-xxxxxx ID

Update item

// Execute: prl update prl-abc123 --title "new" --status in_progress
// For metadata: prl meta set prl-abc123 assignee "user"

Link items

// Execute: prl link prl-abc123 prl-def456 blocks

Prerequisites Check

Before adapter implementation:

• Verify prl binary is available in PATH
• Check .pearls/issues.jsonl exists
• Run prl doctor for integrity validation

Implementation Phases

Phase 1: Core Adapter (MVP)

• CLI wrapper with prl command execution
• Data model mapper (WorkItem ↔ Pearls)
• Basic operations: create, list, get, update
• State transition mapping
• Unit tests with mocked CLI responses

Phase 2: Relations & Metadata

• Link/unlink implementation (prl link/unlink)
• Metadata support via prl meta
• Query engine integration for WHERE clauses
• Cycle detection compatibility

Phase 3: Advanced Features

• Ready queue integration (prl ready)
• Archive handling (prl compact)
• Schema discovery (prl doctor validation)
• Error handling for git conflicts
• Integration tests with real Pearls repo

Phase 4: Documentation & Examples

• Pearls adapter guide in docs/
• Example workflows (ai-scrum-pearls/)
• Migration guide (GitHub → Pearls)
• Performance benchmarks

Testing Strategy

tests/
├── unit/adapters/pearls/
│   ├── cli-wrapper.test.ts      # Mock prl command execution
│   ├── mapper.test.ts           # Data model conversion
│   └── adapter.test.ts          # Core adapter logic
├── integration/adapters/pearls/
│   └── full-workflow.test.ts    # Real prl commands in test repo
└── e2e/
    └── pearls-workflow.test.ts  # Complete user journey

Error Handling

• Missing prl binary → Clear installation instructions
• Invalid repo path → Check for .pearls/ directory
• JSONL corruption → Run prl doctor --fix
• Git conflicts → Defer to Pearls merge driver
• State transition errors → Map to work CLI error types

Documentation Updates

• Add to docs/README.md
• Create docs/pearls-adapter-guide.md
• Update docs/work-adapter-architecture.md
• Add Pearls example to examples/
• Update README.md with Pearls in adapter list

Success Criteria

✅ All core lifecycle operations work (create, update, close)
✅ Relations and dependencies properly mapped
✅ Query engine filters Pearls data correctly
✅ >60% test coverage maintained
✅ Documentation complete with examples
✅ No breaking changes to existing adapters

Future Enhancements

• Real-time sync detection via .pearls/issues.jsonl file watch
• Bulk operations optimization (single prl call for multiple items)
• Import existing Pearls issues on context creation
• Export work CLI data to Pearls format

References

• Pearls repository: https://github.com/mrorigo/pearls
• Pearls USER-GUIDE.md: Core commands and data model
• Pearls WHITEPAPER.md: Architecture and design philosophy
• work CLI adapter architecture: docs/work-adapter-architecture.md

---

Related: Complements existing local-fs (#28) and GitHub (#995) adapters.
Complexity: Medium - CLI wrapper pattern similar to GitHub adapter, but simpler auth.
Priority: P2 - Valuable for git-native workflows and agentic development teams.