pbl-skills

Product Backlog management for pi — commands, tools, and skills to manage your product backlog inside your repo.

pbl-skills turns your repo into a lightweight product management workspace. It structures your backlog as plain markdown folders, gives you interactive TUI widgets for visualization and reordering, and bundles a suite of AI-assisted skills for creating, refining, splitting, and completing backlog items.

Read The Product Backlog Should Live in Your Repo for the theory behind this approach.

Why?

| Problem | How pbl-skills solves it | |---|---| | Backlog lives in Jira/Notion, far from the code | Backlog lives in product-backlog/ — same repo, same branch | | Prioritization gets stale | Interactive reorder via /pbl-view --order (or press o in the view) makes it effortless | | Stories aren't ready to code | Structured 3 C's pipeline: Card → Conversation → Confirmation | | No visibility into backlog health | Anti-pattern scanner detects bottlenecks, stale items, over-refinement | | Too much manual bash | Tools like create_backlog_item replace mkdir + write calls |

Installation

pi install -l npm:pbl-skills

What you get

4 Commands (TUI widgets)

| Command | What it does | |---|---| | /pbl-view | Segmented progress bar + color-coded item list. Supports --order for interactive reorder, --widget for static widget. | | /pbl-metrics | Backlog health check + velocity sparkline — scans for 5 anti-patterns and shows a health widget + status bar indicator | | /pbl-done | Interactive "mark as done" selector (with keyboard search/filter) | | /pbl-timeline | Chronological event history (created, refined, confirmed, done, split) |

3 Tools (LLM-callable)

| Tool | What it does | |---|---| | create_backlog_item | Creates a new PBI folder with Card.md and history entry — no bash needed | | split_backlog_item | Splits an item using Hamburger Method results — updates original + creates new | | show_backlog_widget | Toggles the visualization widget programmatically |

7 Skills (AI-assisted workflows)

| Skill | What it does | |---|---| | pbl-kickoff | Bootstrap a full product idea into backlog items (structured interview) | | pbl-add | Add a new item with a short 3-question interview (creates CONNEXTRA Card) | | pbl-refine | Refine a raw item through a structured 3 C's interview | | pbl-split | Split a large item into two independent items (Hamburger Method) | | pbl-implement | Bridge from a refined item to coding — generates test skeleton + identifies design files | | pbl-diagnose | Deep analysis of backlog health — identifies anti-patterns, explains root causes, and offers to act on flagged items | | pbl-done | Mark an item as done with Definition of Done gate |

Scripts

| Script | What it does | |---|---| | scripts/pbl-index.js | Regenerates product-backlog/.index.md (item counts, status summaries, recent history) |

How it works

The 3 C's pipeline

Every backlog item progresses through three states, tracked by which files exist:

raw        refined       ready
  ● ──────→ ◉ ────────→ ◆
Card.md    +Conversation.md   +Confirmation.md

• raw — just a Card.md with a CONNEXTRA story (As a… I want… So that…)
• refined — Card.md + Conversation.md (structured refinement decisions)
• ready — all three files present, ready for /pbl-implement to bridge into code

Folder structure

product-backlog/
├── CLAUDE.md              ← auto-generated guide for AI agents
├── .index.md              ← auto-generated index (fast path for diagnosis)
├── .history/              ← one file per event: YYYY-MM-DD_{slug}_{event}
├── .removed-items/        ← soft-deleted items (can be restored)
├── done/                  ← completed items
├── 0010-user-login/
│   ├── Card.md            ← CONNEXTRA user story
│   ├── Conversation.md    ← refinement decisions
│   └── Confirmation.md    ← prose acceptance criteria
├── 0020-profile-page/
│   └── Card.md
└── 0030-payment-flow/
    ├── Card.md
    └── Conversation.md

Anti-pattern detection

/pbl-metrics checks for 5 common issues:

1. Refinement bottleneck — >3 items discussed but never confirmed
2. Ready but not started — >5 items fully refined, waiting
3. Stale refined — item refined 5+ done events ago (may be outdated)
4. Stale unrefined — item created 8+ events ago, never refined
5. DoD may be stale — docs/adr/ has files newer than the Definition of Done

Additionally, /pbl-metrics shows a delivery velocity sparkline (last 10 weeks).

The status bar shows a live indicator: 🟢 healthy, 🟡 warnings, 🔴 errors.

Quickstart

# 1. Install the package
pi install -l npm:pbl-skills

# 2. Start pi (or Claude Code) in your repo
pi

# 3. Kickoff a new product (or add items one by one)
/pbl-kickoff

# 4. View your backlog
/pbl-view

# 5. Refine the top unrefined item
/pbl-refine

# 6. Check health + velocity
/pbl-metrics

# 7. Start coding
/pbl-implement

Requirements

• pi (@earendil-works/pi-coding-agent) — peer dependency
• typebox — for tool parameter validation (peer dependency)
• Node.js ≥ 18

License

MIT